@swarmvaultai/engine 0.1.2 → 0.1.4

package/dist/index.js

@@ -1,5 +1,6 @@
 // src/config.ts
 import path2 from "path";
+import fs2 from "fs/promises";
 import { fileURLToPath } from "url";
 import { z as z2 } from "zod";
 
@@ -36,6 +37,11 @@ async function writeJsonFile(filePath, value) {
   await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}
 `, "utf8");
 }
+async function appendJsonLine(filePath, value) {
+  await ensureDir(path.dirname(filePath));
+  await fs.appendFile(filePath, `${JSON.stringify(value)}
+`, "utf8");
+}
 async function writeFileIfChanged(filePath, content) {
   await ensureDir(path.dirname(filePath));
   if (await fileExists(filePath)) {
@@ -88,6 +94,21 @@ function truncate(value, maxLength) {
   }
   return `${value.slice(0, maxLength - 3)}...`;
 }
+async function listFilesRecursive(rootDir) {
+  const entries = await fs.readdir(rootDir, { withFileTypes: true }).catch(() => []);
+  const files = [];
+  for (const entry of entries) {
+    const absolutePath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await listFilesRecursive(absolutePath));
+      continue;
+    }
+    if (entry.isFile()) {
+      files.push(absolutePath);
+    }
+  }
+  return files;
+}
 
 // src/types.ts
 import { z } from "zod";
@@ -114,6 +135,8 @@ var providerTypeSchema = z.enum([
 // src/config.ts
 var PRIMARY_CONFIG_FILENAME = "swarmvault.config.json";
 var LEGACY_CONFIG_FILENAME = "vault.config.json";
+var PRIMARY_SCHEMA_FILENAME = "swarmvault.schema.md";
+var LEGACY_SCHEMA_FILENAME = "schema.md";
 var moduleDir = path2.dirname(fileURLToPath(import.meta.url));
 var providerConfigSchema = z2.object({
   type: providerTypeSchema,
@@ -130,7 +153,8 @@ var vaultConfigSchema = z2.object({
     rawDir: z2.string().min(1),
     wikiDir: z2.string().min(1),
     stateDir: z2.string().min(1),
-    agentDir: z2.string().min(1)
+    agentDir: z2.string().min(1),
+    inboxDir: z2.string().min(1)
   }),
   providers: z2.record(z2.string(), providerConfigSchema),
   tasks: z2.object({
@@ -150,7 +174,8 @@ function defaultVaultConfig() {
       rawDir: "raw",
       wikiDir: "wiki",
       stateDir: "state",
-      agentDir: "agent"
+      agentDir: "agent",
+      inboxDir: "inbox"
     },
     providers: {
       local: {
@@ -171,6 +196,52 @@ function defaultVaultConfig() {
     agents: ["codex", "claude", "cursor"]
   };
 }
+function defaultVaultSchema() {
+  return [
+    "# SwarmVault Schema",
+    "",
+    "Edit this file to teach SwarmVault how this vault should be organized and maintained.",
+    "",
+    "## Vault Purpose",
+    "",
+    "- Describe the domain this vault covers.",
+    "- Note the intended audience and the kinds of questions the vault should answer well.",
+    "",
+    "## Naming Conventions",
+    "",
+    "- Prefer stable, descriptive page titles.",
+    "- Keep concept and entity names specific to the domain.",
+    "",
+    "## Page Structure Rules",
+    "",
+    "- Source pages should stay grounded in the original material.",
+    "- Concept and entity pages should aggregate source-backed claims instead of inventing new ones.",
+    "- Preserve contradictions instead of smoothing them away.",
+    "",
+    "## Categories",
+    "",
+    "- List domain-specific concept categories here.",
+    "- List important entity types here.",
+    "",
+    "## Relationship Types",
+    "",
+    "- Mentions",
+    "- Supports",
+    "- Contradicts",
+    "- Depends on",
+    "",
+    "## Grounding Rules",
+    "",
+    "- Prefer raw sources over summaries.",
+    "- Cite source ids whenever claims are stated.",
+    "- Do not treat the wiki as a source of truth when the raw material disagrees.",
+    "",
+    "## Exclusions",
+    "",
+    "- List topics, claims, or page types the compiler should avoid generating.",
+    ""
+  ].join("\n");
+}
 async function findConfigPath(rootDir) {
   const primaryPath = path2.join(rootDir, PRIMARY_CONFIG_FILENAME);
   if (await fileExists(primaryPath)) {
@@ -182,18 +253,36 @@ async function findConfigPath(rootDir) {
   }
   return primaryPath;
 }
-function resolvePaths(rootDir, config, configPath = path2.join(rootDir, PRIMARY_CONFIG_FILENAME)) {
+async function findSchemaPath(rootDir) {
+  const primaryPath = path2.join(rootDir, PRIMARY_SCHEMA_FILENAME);
+  if (await fileExists(primaryPath)) {
+    return primaryPath;
+  }
+  const legacyPath = path2.join(rootDir, LEGACY_SCHEMA_FILENAME);
+  if (await fileExists(legacyPath)) {
+    return legacyPath;
+  }
+  return primaryPath;
+}
+function resolvePaths(rootDir, config, configPath = path2.join(rootDir, PRIMARY_CONFIG_FILENAME), schemaPath = path2.join(rootDir, PRIMARY_SCHEMA_FILENAME)) {
   const effective = config ?? defaultVaultConfig();
   const rawDir = path2.resolve(rootDir, effective.workspace.rawDir);
+  const rawSourcesDir = path2.join(rawDir, "sources");
+  const rawAssetsDir = path2.join(rawDir, "assets");
   const wikiDir = path2.resolve(rootDir, effective.workspace.wikiDir);
   const stateDir = path2.resolve(rootDir, effective.workspace.stateDir);
   const agentDir = path2.resolve(rootDir, effective.workspace.agentDir);
+  const inboxDir = path2.resolve(rootDir, effective.workspace.inboxDir);
   return {
     rootDir,
+    schemaPath,
     rawDir,
+    rawSourcesDir,
+    rawAssetsDir,
     wikiDir,
     stateDir,
     agentDir,
+    inboxDir,
     manifestsDir: path2.join(stateDir, "manifests"),
     extractsDir: path2.join(stateDir, "extracts"),
     analysesDir: path2.join(stateDir, "analyses"),
@@ -201,39 +290,51 @@ function resolvePaths(rootDir, config, configPath = path2.join(rootDir, PRIMARY_
     graphPath: path2.join(stateDir, "graph.json"),
     searchDbPath: path2.join(stateDir, "search.sqlite"),
     compileStatePath: path2.join(stateDir, "compile-state.json"),
+    jobsLogPath: path2.join(stateDir, "jobs.ndjson"),
     configPath
   };
 }
 async function loadVaultConfig(rootDir) {
   const configPath = await findConfigPath(rootDir);
+  const schemaPath = await findSchemaPath(rootDir);
   const raw = await readJsonFile(configPath);
   const parsed = vaultConfigSchema.parse(raw ?? defaultVaultConfig());
   return {
     config: parsed,
-    paths: resolvePaths(rootDir, parsed, configPath)
+    paths: resolvePaths(rootDir, parsed, configPath, schemaPath)
   };
 }
 async function initWorkspace(rootDir) {
   const configPath = await findConfigPath(rootDir);
+  const schemaPath = await findSchemaPath(rootDir);
   const config = await fileExists(configPath) ? (await loadVaultConfig(rootDir)).config : defaultVaultConfig();
-  const paths = resolvePaths(rootDir, config, configPath);
+  const paths = resolvePaths(rootDir, config, configPath, schemaPath);
+  const primarySchemaPath = path2.join(rootDir, PRIMARY_SCHEMA_FILENAME);
+  const legacySchemaPath = path2.join(rootDir, LEGACY_SCHEMA_FILENAME);
   await Promise.all([
     ensureDir(paths.rawDir),
     ensureDir(paths.wikiDir),
     ensureDir(paths.stateDir),
     ensureDir(paths.agentDir),
+    ensureDir(paths.inboxDir),
     ensureDir(paths.manifestsDir),
     ensureDir(paths.extractsDir),
-    ensureDir(paths.analysesDir)
+    ensureDir(paths.analysesDir),
+    ensureDir(paths.rawSourcesDir),
+    ensureDir(paths.rawAssetsDir)
   ]);
   if (!await fileExists(configPath)) {
     await writeJsonFile(configPath, config);
   }
+  if (!await fileExists(primarySchemaPath) && !await fileExists(legacySchemaPath)) {
+    await ensureDir(path2.dirname(primarySchemaPath));
+    await fs2.writeFile(primarySchemaPath, defaultVaultSchema(), "utf8");
+  }
   return { config, paths };
 }
 
 // src/ingest.ts
-import fs3 from "fs/promises";
+import fs4 from "fs/promises";
 import path4 from "path";
 import { JSDOM } from "jsdom";
 import TurndownService from "turndown";
@@ -241,7 +342,7 @@ import { Readability } from "@mozilla/readability";
 import mime from "mime-types";
 
 // src/logs.ts
-import fs2 from "fs/promises";
+import fs3 from "fs/promises";
 import path3 from "path";
 async function appendLogEntry(rootDir, action, title, lines = []) {
   const { paths } = await initWorkspace(rootDir);
@@ -249,10 +350,14 @@ async function appendLogEntry(rootDir, action, title, lines = []) {
   const logPath = path3.join(paths.wikiDir, "log.md");
   const timestamp = (/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace("T", " ");
   const entry = [`## [${timestamp}] ${action} | ${title}`, ...lines.map((line) => `- ${line}`), ""].join("\n");
-  const existing = await fileExists(logPath) ? await fs2.readFile(logPath, "utf8") : "# Log\n\n";
-  await fs2.writeFile(logPath, `${existing}${entry}
+  const existing = await fileExists(logPath) ? await fs3.readFile(logPath, "utf8") : "# Log\n\n";
+  await fs3.writeFile(logPath, `${existing}${entry}
 `, "utf8");
 }
+async function appendWatchRun(rootDir, run) {
+  const { paths } = await initWorkspace(rootDir);
+  await appendJsonLine(paths.jobsLogPath, run);
+}
 
 // src/ingest.ts
 function inferKind(mimeType, filePath) {
@@ -280,6 +385,50 @@ function titleFromText(fallback, content) {
 function guessMimeType(target) {
   return mime.lookup(target) || "application/octet-stream";
 }
+function buildCompositeHash(payloadBytes, attachments = []) {
+  if (!attachments.length) {
+    return sha256(payloadBytes);
+  }
+  const attachmentSignature = attachments.map((attachment) => `${attachment.relativePath}:${sha256(attachment.bytes)}`).sort().join("|");
+  return sha256(`${sha256(payloadBytes)}|${attachmentSignature}`);
+}
+function sanitizeAssetRelativePath(value) {
+  const normalized = path4.posix.normalize(value.replace(/\\/g, "/"));
+  const segments = normalized.split("/").filter(Boolean).map((segment) => {
+    if (segment === ".") {
+      return "";
+    }
+    if (segment === "..") {
+      return "_up";
+    }
+    return segment;
+  }).filter(Boolean);
+  return segments.join("/") || "asset";
+}
+function normalizeLocalReference(value) {
+  const trimmed = value.trim().replace(/^<|>$/g, "");
+  const [withoutTitle] = trimmed.split(/\s+(?=(?:[^"]*"[^"]*")*[^"]*$)/, 1);
+  const candidate = withoutTitle.split("#")[0]?.split("?")[0]?.trim();
+  if (!candidate) {
+    return null;
+  }
+  const lowered = candidate.toLowerCase();
+  if (lowered.startsWith("http://") || lowered.startsWith("https://") || lowered.startsWith("data:") || lowered.startsWith("mailto:") || lowered.startsWith("#") || path4.isAbsolute(candidate)) {
+    return null;
+  }
+  return candidate.replace(/\\/g, "/");
+}
+function extractMarkdownReferences(content) {
+  const references = [];
+  const linkPattern = /!?\[[^\]]*]\(([^)]+)\)/g;
+  for (const match of content.matchAll(linkPattern)) {
+    const normalized = normalizeLocalReference(match[1] ?? "");
+    if (normalized) {
+      references.push(normalized);
+    }
+  }
+  return references;
+}
 async function convertHtmlToMarkdown(html, url) {
   const dom = new JSDOM(html, { url });
   const article = new Readability(dom.window.document).parse();
@@ -292,7 +441,7 @@ async function convertHtmlToMarkdown(html, url) {
   };
 }
 async function readManifestByHash(manifestsDir, contentHash) {
-  const entries = await fs3.readdir(manifestsDir, { withFileTypes: true }).catch(() => []);
+  const entries = await fs4.readdir(manifestsDir, { withFileTypes: true }).catch(() => []);
   for (const entry of entries) {
     if (!entry.isFile() || !entry.name.endsWith(".json")) {
       continue;
@@ -304,89 +453,275 @@ async function readManifestByHash(manifestsDir, contentHash) {
   }
   return null;
 }
-async function ingestInput(rootDir, input) {
-  const { paths } = await initWorkspace(rootDir);
-  await ensureDir(path4.join(paths.rawDir, "sources"));
+async function persistPreparedInput(rootDir, prepared, paths) {
+  await ensureDir(paths.rawSourcesDir);
+  await ensureDir(paths.rawAssetsDir);
   await ensureDir(paths.manifestsDir);
   await ensureDir(paths.extractsDir);
-  const isUrl = /^https?:\/\//i.test(input);
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  let title = path4.basename(input);
-  let mimeType = "application/octet-stream";
-  let storedExtension = ".bin";
-  let payloadBytes;
-  let extractedTextPath;
-  let sourceKind = "binary";
-  if (isUrl) {
-    const response = await fetch(input);
-    if (!response.ok) {
-      throw new Error(`Failed to fetch ${input}: ${response.status} ${response.statusText}`);
-    }
-    const arrayBuffer = await response.arrayBuffer();
-    payloadBytes = Buffer.from(arrayBuffer);
-    mimeType = response.headers.get("content-type")?.split(";")[0]?.trim() || guessMimeType(input);
-    sourceKind = inferKind(mimeType, input);
-    if (sourceKind === "html" || mimeType.startsWith("text/html")) {
-      const html = payloadBytes.toString("utf8");
-      const converted = await convertHtmlToMarkdown(html, input);
-      title = converted.title;
-      payloadBytes = Buffer.from(converted.markdown, "utf8");
-      mimeType = "text/markdown";
-      sourceKind = "markdown";
-      storedExtension = ".md";
-    } else {
-      title = new URL(input).hostname + new URL(input).pathname;
-      const extension = path4.extname(new URL(input).pathname) || (mime.extension(mimeType) ? `.${mime.extension(mimeType)}` : ".bin");
-      storedExtension = extension;
-    }
-  } else {
-    const absoluteInput = path4.resolve(rootDir, input);
-    payloadBytes = await fs3.readFile(absoluteInput);
-    mimeType = guessMimeType(absoluteInput);
-    sourceKind = inferKind(mimeType, absoluteInput);
-    storedExtension = path4.extname(absoluteInput) || `.${mime.extension(mimeType) || "bin"}`;
-    if (sourceKind === "markdown" || sourceKind === "text") {
-      title = titleFromText(path4.basename(absoluteInput, path4.extname(absoluteInput)), payloadBytes.toString("utf8"));
-    } else {
-      title = path4.basename(absoluteInput, path4.extname(absoluteInput));
-    }
-  }
-  const contentHash = sha256(payloadBytes);
+  const attachments = prepared.attachments ?? [];
+  const contentHash = prepared.contentHash ?? buildCompositeHash(prepared.payloadBytes, attachments);
   const existing = await readManifestByHash(paths.manifestsDir, contentHash);
   if (existing) {
-    return existing;
+    return { manifest: existing, isNew: false };
   }
-  const sourceId = `${slugify(title)}-${contentHash.slice(0, 8)}`;
-  const storedPath = path4.join(paths.rawDir, "sources", `${sourceId}${storedExtension}`);
-  await fs3.writeFile(storedPath, payloadBytes);
-  if (sourceKind === "markdown" || sourceKind === "text") {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const sourceId = `${slugify(prepared.title)}-${contentHash.slice(0, 8)}`;
+  const storedPath = path4.join(paths.rawSourcesDir, `${sourceId}${prepared.storedExtension}`);
+  await fs4.writeFile(storedPath, prepared.payloadBytes);
+  let extractedTextPath;
+  if (prepared.extractedText) {
     extractedTextPath = path4.join(paths.extractsDir, `${sourceId}.md`);
-    await fs3.writeFile(extractedTextPath, payloadBytes.toString("utf8"), "utf8");
+    await fs4.writeFile(extractedTextPath, prepared.extractedText, "utf8");
+  }
+  const manifestAttachments = [];
+  for (const attachment of attachments) {
+    const absoluteAttachmentPath = path4.join(paths.rawAssetsDir, sourceId, attachment.relativePath);
+    await ensureDir(path4.dirname(absoluteAttachmentPath));
+    await fs4.writeFile(absoluteAttachmentPath, attachment.bytes);
+    manifestAttachments.push({
+      path: toPosix(path4.relative(rootDir, absoluteAttachmentPath)),
+      mimeType: attachment.mimeType,
+      originalPath: attachment.originalPath
+    });
   }
   const manifest = {
     sourceId,
-    title,
-    originType: isUrl ? "url" : "file",
-    sourceKind,
-    originalPath: isUrl ? void 0 : toPosix(path4.resolve(rootDir, input)),
-    url: isUrl ? input : void 0,
+    title: prepared.title,
+    originType: prepared.originType,
+    sourceKind: prepared.sourceKind,
+    originalPath: prepared.originalPath,
+    url: prepared.url,
     storedPath: toPosix(path4.relative(rootDir, storedPath)),
     extractedTextPath: extractedTextPath ? toPosix(path4.relative(rootDir, extractedTextPath)) : void 0,
-    mimeType,
+    mimeType: prepared.mimeType,
     contentHash,
     createdAt: now,
-    updatedAt: now
+    updatedAt: now,
+    attachments: manifestAttachments.length ? manifestAttachments : void 0
   };
   await writeJsonFile(path4.join(paths.manifestsDir, `${sourceId}.json`), manifest);
-  await appendLogEntry(rootDir, "ingest", title, [`source_id=${sourceId}`, `kind=${sourceKind}`]);
-  return manifest;
+  await appendLogEntry(rootDir, "ingest", prepared.title, [
+    `source_id=${sourceId}`,
+    `kind=${prepared.sourceKind}`,
+    `attachments=${manifestAttachments.length}`
+  ]);
+  return { manifest, isNew: true };
+}
+async function prepareFileInput(rootDir, absoluteInput) {
+  const payloadBytes = await fs4.readFile(absoluteInput);
+  const mimeType = guessMimeType(absoluteInput);
+  const sourceKind = inferKind(mimeType, absoluteInput);
+  const storedExtension = path4.extname(absoluteInput) || `.${mime.extension(mimeType) || "bin"}`;
+  let title;
+  let extractedText;
+  if (sourceKind === "markdown" || sourceKind === "text") {
+    extractedText = payloadBytes.toString("utf8");
+    title = titleFromText(path4.basename(absoluteInput, path4.extname(absoluteInput)), extractedText);
+  } else {
+    title = path4.basename(absoluteInput, path4.extname(absoluteInput));
+  }
+  return {
+    title,
+    originType: "file",
+    sourceKind,
+    originalPath: toPosix(absoluteInput),
+    mimeType,
+    storedExtension,
+    payloadBytes,
+    extractedText
+  };
+}
+async function prepareUrlInput(input) {
+  const response = await fetch(input);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${input}: ${response.status} ${response.statusText}`);
+  }
+  let payloadBytes = Buffer.from(await response.arrayBuffer());
+  let mimeType = response.headers.get("content-type")?.split(";")[0]?.trim() || guessMimeType(input);
+  let sourceKind = inferKind(mimeType, input);
+  let storedExtension = ".bin";
+  let title = new URL(input).hostname + new URL(input).pathname;
+  let extractedText;
+  if (sourceKind === "html" || mimeType.startsWith("text/html")) {
+    const html = payloadBytes.toString("utf8");
+    const converted = await convertHtmlToMarkdown(html, input);
+    title = converted.title;
+    extractedText = converted.markdown;
+    payloadBytes = Buffer.from(converted.markdown, "utf8");
+    mimeType = "text/markdown";
+    sourceKind = "markdown";
+    storedExtension = ".md";
+  } else {
+    const extension = path4.extname(new URL(input).pathname);
+    storedExtension = extension || `.${mime.extension(mimeType) || "bin"}`;
+    if (sourceKind === "markdown" || sourceKind === "text") {
+      extractedText = payloadBytes.toString("utf8");
+      title = titleFromText(title || new URL(input).hostname, extractedText);
+    }
+  }
+  return {
+    title,
+    originType: "url",
+    sourceKind,
+    url: input,
+    mimeType,
+    storedExtension,
+    payloadBytes,
+    extractedText
+  };
+}
+async function collectInboxAttachmentRefs(inputDir, files) {
+  const refsBySource = /* @__PURE__ */ new Map();
+  for (const absolutePath of files) {
+    const mimeType = guessMimeType(absolutePath);
+    const sourceKind = inferKind(mimeType, absolutePath);
+    if (sourceKind !== "markdown") {
+      continue;
+    }
+    const content = await fs4.readFile(absolutePath, "utf8");
+    const refs = extractMarkdownReferences(content);
+    if (!refs.length) {
+      continue;
+    }
+    const sourceRefs = [];
+    for (const ref of refs) {
+      const resolved = path4.resolve(path4.dirname(absolutePath), ref);
+      if (!resolved.startsWith(inputDir) || !await fileExists(resolved)) {
+        continue;
+      }
+      sourceRefs.push({
+        absolutePath: resolved,
+        relativeRef: ref
+      });
+    }
+    if (sourceRefs.length) {
+      refsBySource.set(
+        absolutePath,
+        sourceRefs.filter(
+          (ref, index, items) => index === items.findIndex((candidate) => candidate.absolutePath === ref.absolutePath && candidate.relativeRef === ref.relativeRef)
+        )
+      );
+    }
+  }
+  return refsBySource;
+}
+function rewriteMarkdownReferences(content, replacements) {
+  return content.replace(/(!?\[[^\]]*]\()([^)]+)(\))/g, (fullMatch, prefix, target, suffix) => {
+    const normalized = normalizeLocalReference(target);
+    if (!normalized) {
+      return fullMatch;
+    }
+    const replacement = replacements.get(normalized);
+    if (!replacement) {
+      return fullMatch;
+    }
+    return `${prefix}${replacement}${suffix}`;
+  });
+}
+async function prepareInboxMarkdownInput(absolutePath, attachmentRefs) {
+  const originalBytes = await fs4.readFile(absolutePath);
+  const originalText = originalBytes.toString("utf8");
+  const title = titleFromText(path4.basename(absolutePath, path4.extname(absolutePath)), originalText);
+  const attachments = [];
+  for (const attachmentRef of attachmentRefs) {
+    const bytes = await fs4.readFile(attachmentRef.absolutePath);
+    attachments.push({
+      relativePath: sanitizeAssetRelativePath(attachmentRef.relativeRef),
+      mimeType: guessMimeType(attachmentRef.absolutePath),
+      originalPath: toPosix(attachmentRef.absolutePath),
+      bytes
+    });
+  }
+  const contentHash = buildCompositeHash(originalBytes, attachments);
+  const sourceId = `${slugify(title)}-${contentHash.slice(0, 8)}`;
+  const replacements = new Map(
+    attachmentRefs.map((attachmentRef) => [
+      attachmentRef.relativeRef.replace(/\\/g, "/"),
+      `../assets/${sourceId}/${sanitizeAssetRelativePath(attachmentRef.relativeRef)}`
+    ])
+  );
+  const rewrittenText = rewriteMarkdownReferences(originalText, replacements);
+  return {
+    title,
+    originType: "file",
+    sourceKind: "markdown",
+    originalPath: toPosix(absolutePath),
+    mimeType: "text/markdown",
+    storedExtension: path4.extname(absolutePath) || ".md",
+    payloadBytes: Buffer.from(rewrittenText, "utf8"),
+    extractedText: rewrittenText,
+    attachments,
+    contentHash
+  };
+}
+function isSupportedInboxKind(sourceKind) {
+  return ["markdown", "text", "html", "pdf", "image"].includes(sourceKind);
+}
+async function ingestInput(rootDir, input) {
+  const { paths } = await initWorkspace(rootDir);
+  const prepared = /^https?:\/\//i.test(input) ? await prepareUrlInput(input) : await prepareFileInput(rootDir, path4.resolve(rootDir, input));
+  const result = await persistPreparedInput(rootDir, prepared, paths);
+  return result.manifest;
+}
+async function importInbox(rootDir, inputDir) {
+  const { paths } = await initWorkspace(rootDir);
+  const effectiveInputDir = path4.resolve(rootDir, inputDir ?? paths.inboxDir);
+  if (!await fileExists(effectiveInputDir)) {
+    throw new Error(`Inbox directory not found: ${effectiveInputDir}`);
+  }
+  const files = (await listFilesRecursive(effectiveInputDir)).sort();
+  const refsBySource = await collectInboxAttachmentRefs(effectiveInputDir, files);
+  const claimedAttachments = new Set(
+    [...refsBySource.values()].flatMap((refs) => refs.map((ref) => ref.absolutePath))
+  );
+  const imported = [];
+  const skipped = [];
+  let attachmentCount = 0;
+  for (const absolutePath of files) {
+    const basename = path4.basename(absolutePath);
+    if (basename.startsWith(".")) {
+      skipped.push({ path: toPosix(path4.relative(rootDir, absolutePath)), reason: "hidden_file" });
+      continue;
+    }
+    if (claimedAttachments.has(absolutePath)) {
+      skipped.push({ path: toPosix(path4.relative(rootDir, absolutePath)), reason: "referenced_attachment" });
+      continue;
+    }
+    const mimeType = guessMimeType(absolutePath);
+    const sourceKind = inferKind(mimeType, absolutePath);
+    if (!isSupportedInboxKind(sourceKind)) {
+      skipped.push({ path: toPosix(path4.relative(rootDir, absolutePath)), reason: `unsupported_kind:${sourceKind}` });
+      continue;
+    }
+    const prepared = sourceKind === "markdown" && refsBySource.has(absolutePath) ? await prepareInboxMarkdownInput(absolutePath, refsBySource.get(absolutePath) ?? []) : await prepareFileInput(rootDir, absolutePath);
+    const result = await persistPreparedInput(rootDir, prepared, paths);
+    if (!result.isNew) {
+      skipped.push({ path: toPosix(path4.relative(rootDir, absolutePath)), reason: "duplicate_content" });
+      continue;
+    }
+    attachmentCount += result.manifest.attachments?.length ?? 0;
+    imported.push(result.manifest);
+  }
+  await appendLogEntry(rootDir, "inbox_import", toPosix(path4.relative(rootDir, effectiveInputDir)) || ".", [
+    `scanned=${files.length}`,
+    `imported=${imported.length}`,
+    `attachments=${attachmentCount}`,
+    `skipped=${skipped.length}`
+  ]);
+  return {
+    inputDir: effectiveInputDir,
+    scannedCount: files.length,
+    attachmentCount,
+    imported,
+    skipped
+  };
 }
 async function listManifests(rootDir) {
   const { paths } = await loadVaultConfig(rootDir);
   if (!await fileExists(paths.manifestsDir)) {
     return [];
   }
-  const entries = await fs3.readdir(paths.manifestsDir);
+  const entries = await fs4.readdir(paths.manifestsDir);
   const manifests = await Promise.all(
     entries.filter((entry) => entry.endsWith(".json")).map((entry) => readJsonFile(path4.join(paths.manifestsDir, entry)))
   );
@@ -400,12 +735,12 @@ async function readExtractedText(rootDir, manifest) {
   if (!await fileExists(absolutePath)) {
     return void 0;
   }
-  return fs3.readFile(absolutePath, "utf8");
+  return fs4.readFile(absolutePath, "utf8");
 }
 
 // src/vault.ts
-import fs7 from "fs/promises";
-import path9 from "path";
+import fs9 from "fs/promises";
+import path10 from "path";
 import matter3 from "gray-matter";
 
 // src/analysis.ts
@@ -492,7 +827,7 @@ function deriveTitle(manifest, text) {
   const heading = text.match(/^#\s+(.+)$/m)?.[1]?.trim();
   return heading || manifest.title;
 }
-function heuristicAnalysis(manifest, text) {
+function heuristicAnalysis(manifest, text, schemaHash) {
   const normalized = normalizeWhitespace(text);
   const concepts = extractTopTerms(normalized, 6).map((term) => ({
     id: `concept:${slugify(term)}`,
@@ -508,6 +843,7 @@ function heuristicAnalysis(manifest, text) {
   return {
     sourceId: manifest.sourceId,
     sourceHash: manifest.contentHash,
+    schemaHash,
     title: deriveTitle(manifest, text),
     summary: firstSentences(normalized, 3) || truncate(normalized, 280) || `Imported ${manifest.sourceKind} source.`,
     concepts,
@@ -524,10 +860,19 @@ function heuristicAnalysis(manifest, text) {
     producedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-async function providerAnalysis(manifest, text, provider) {
+async function providerAnalysis(manifest, text, provider, schema) {
   const parsed = await provider.generateStructured(
     {
-      system: "You are compiling a durable markdown wiki and graph. Prefer grounded synthesis over creativity.",
+      system: [
+        "You are compiling a durable markdown wiki and graph. Prefer grounded synthesis over creativity.",
+        "",
+        "Follow the vault schema when choosing titles, categories, relationships, and summaries.",
+        "",
+        `Vault schema path: ${schema.path}`,
+        "",
+        "Vault schema instructions:",
+        truncate(schema.content, 6e3)
+      ].join("\n"),
       prompt: `Analyze the following source and return structured JSON.
 
 Source title: ${manifest.title}
@@ -542,6 +887,7 @@ ${truncate(text, 18e3)}`
   return {
     sourceId: manifest.sourceId,
     sourceHash: manifest.contentHash,
+    schemaHash: schema.hash,
     title: parsed.title,
     summary: parsed.summary,
     concepts: parsed.concepts.map((term) => ({
@@ -566,10 +912,10 @@ ${truncate(text, 18e3)}`
     producedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-async function analyzeSource(manifest, extractedText, provider, paths) {
+async function analyzeSource(manifest, extractedText, provider, paths, schema) {
   const cachePath = path5.join(paths.analysesDir, `${manifest.sourceId}.json`);
   const cached = await readJsonFile(cachePath);
-  if (cached && cached.sourceHash === manifest.contentHash) {
+  if (cached && cached.sourceHash === manifest.contentHash && cached.schemaHash === schema.hash) {
     return cached;
   }
   const content = normalizeWhitespace(extractedText ?? "");
@@ -578,6 +924,7 @@ async function analyzeSource(manifest, extractedText, provider, paths) {
     analysis = {
       sourceId: manifest.sourceId,
       sourceHash: manifest.contentHash,
+      schemaHash: schema.hash,
       title: manifest.title,
       summary: `Imported ${manifest.sourceKind} source. Text extraction is not yet available for this source.`,
       concepts: [],
@@ -587,12 +934,12 @@ async function analyzeSource(manifest, extractedText, provider, paths) {
       producedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
   } else if (provider.type === "heuristic") {
-    analysis = heuristicAnalysis(manifest, content);
+    analysis = heuristicAnalysis(manifest, content, schema.hash);
   } else {
     try {
-      analysis = await providerAnalysis(manifest, content, provider);
+      analysis = await providerAnalysis(manifest, content, provider, schema);
     } catch {
-      analysis = heuristicAnalysis(manifest, content);
+      analysis = heuristicAnalysis(manifest, content, schema.hash);
     }
   }
   await writeJsonFile(cachePath, analysis);
@@ -603,7 +950,7 @@ function analysisSignature(analysis) {
 }
 
 // src/agents.ts
-import fs4 from "fs/promises";
+import fs5 from "fs/promises";
 import path6 from "path";
 var managedStart = "<!-- swarmvault:managed:start -->";
 var managedEnd = "<!-- swarmvault:managed:end -->";
@@ -614,6 +961,7 @@ function buildManagedBlock(agent) {
     managedStart,
     `# SwarmVault Rules (${agent})`,
     "",
+    "- Read `swarmvault.schema.md` before compile or query style work. If only `schema.md` exists, treat it as the legacy schema path.",
     "- Treat `raw/` as immutable source input.",
     "- Treat `wiki/` as generated markdown owned by the agent and compiler workflow.",
     "- Read `wiki/index.md` before broad file searching when answering SwarmVault questions.",
@@ -629,10 +977,10 @@ function buildManagedBlock(agent) {
   return body;
 }
 async function upsertManagedBlock(filePath, block) {
-  const existing = await fileExists(filePath) ? await fs4.readFile(filePath, "utf8") : "";
+  const existing = await fileExists(filePath) ? await fs5.readFile(filePath, "utf8") : "";
   if (!existing) {
     await ensureDir(path6.dirname(filePath));
-    await fs4.writeFile(filePath, `${block}
+    await fs5.writeFile(filePath, `${block}
 `, "utf8");
     return;
   }
@@ -640,10 +988,10 @@ async function upsertManagedBlock(filePath, block) {
   const endIndex = existing.includes(managedEnd) ? existing.indexOf(managedEnd) : existing.indexOf(legacyManagedEnd);
   if (startIndex !== -1 && endIndex !== -1) {
     const next = `${existing.slice(0, startIndex)}${block}${existing.slice(endIndex + managedEnd.length)}`;
-    await fs4.writeFile(filePath, next, "utf8");
+    await fs5.writeFile(filePath, next, "utf8");
     return;
   }
-  await fs4.writeFile(filePath, `${existing.trimEnd()}
+  await fs5.writeFile(filePath, `${existing.trimEnd()}
 
 ${block}
 `, "utf8");
@@ -666,7 +1014,7 @@ async function installAgent(rootDir, agent) {
       const rulesDir = path6.join(rootDir, ".cursor", "rules");
       await ensureDir(rulesDir);
       const target = path6.join(rulesDir, "swarmvault.mdc");
-      await fs4.writeFile(target, `${block}
+      await fs5.writeFile(target, `${block}
 `, "utf8");
       return target;
     }
@@ -695,7 +1043,7 @@ function pagePathFor(kind, slug) {
       return `${slug}.md`;
   }
 }
-function buildSourcePage(manifest, analysis) {
+function buildSourcePage(manifest, analysis, schemaHash) {
   const relativePath = pagePathFor("source", manifest.sourceId);
   const pageId = `source:${manifest.sourceId}`;
   const nodeIds = [
@@ -718,6 +1066,7 @@ function buildSourcePage(manifest, analysis) {
     confidence: 0.8,
     updated_at: analysis.producedAt,
     backlinks,
+    schema_hash: schemaHash,
     source_hashes: {
       [manifest.sourceId]: manifest.contentHash
     }
@@ -760,12 +1109,13 @@ function buildSourcePage(manifest, analysis) {
       freshness: "fresh",
       confidence: 0.8,
       backlinks,
+      schemaHash,
       sourceHashes: { [manifest.sourceId]: manifest.contentHash }
     },
     content: matter.stringify(body, frontmatter)
   };
 }
-function buildAggregatePage(kind, name, descriptions, sourceAnalyses, sourceHashes) {
+function buildAggregatePage(kind, name, descriptions, sourceAnalyses, sourceHashes, schemaHash) {
   const slug = slugify(name);
   const relativePath = pagePathFor(kind, slug);
   const pageId = `${kind}:${slug}`;
@@ -783,6 +1133,7 @@ function buildAggregatePage(kind, name, descriptions, sourceAnalyses, sourceHash
     confidence: 0.72,
     updated_at: (/* @__PURE__ */ new Date()).toISOString(),
     backlinks: otherPages,
+    schema_hash: schemaHash,
     source_hashes: sourceHashes
   };
   const body = [
@@ -814,12 +1165,13 @@ function buildAggregatePage(kind, name, descriptions, sourceAnalyses, sourceHash
       freshness: "fresh",
       confidence: 0.72,
       backlinks: otherPages,
+      schemaHash,
       sourceHashes
     },
     content: matter.stringify(body, frontmatter)
   };
 }
-function buildIndexPage(pages) {
+function buildIndexPage(pages, schemaHash) {
   const sources = pages.filter((page) => page.kind === "source");
   const concepts = pages.filter((page) => page.kind === "concept");
   const entities = pages.filter((page) => page.kind === "entity");
@@ -836,6 +1188,7 @@ function buildIndexPage(pages) {
     "confidence: 1",
     `updated_at: ${(/* @__PURE__ */ new Date()).toISOString()}`,
     "backlinks: []",
+    `schema_hash: ${schemaHash}`,
     "source_hashes: {}",
     "---",
     "",
@@ -855,16 +1208,32 @@ function buildIndexPage(pages) {
     ""
   ].join("\n");
 }
-function buildSectionIndex(kind, pages) {
+function buildSectionIndex(kind, pages, schemaHash) {
   const title = kind.charAt(0).toUpperCase() + kind.slice(1);
-  return [
-    `# ${title}`,
-    "",
-    ...pages.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`),
-    ""
-  ].join("\n");
+  return matter.stringify(
+    [
+      `# ${title}`,
+      "",
+      ...pages.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`),
+      ""
+    ].join("\n"),
+    {
+      page_id: `${kind}:index`,
+      kind: "index",
+      title,
+      tags: ["index", kind],
+      source_ids: [],
+      node_ids: [],
+      freshness: "fresh",
+      confidence: 1,
+      updated_at: (/* @__PURE__ */ new Date()).toISOString(),
+      backlinks: [],
+      schema_hash: schemaHash,
+      source_hashes: {}
+    }
+  );
 }
-function buildOutputPage(question, answer, citations) {
+function buildOutputPage(question, answer, citations, schemaHash) {
   const slug = slugify(question);
   const pageId = `output:${slug}`;
   const pathValue = pagePathFor("output", slug);
@@ -879,6 +1248,7 @@ function buildOutputPage(question, answer, citations) {
     confidence: 0.74,
     updated_at: (/* @__PURE__ */ new Date()).toISOString(),
     backlinks: citations.map((sourceId) => `source:${sourceId}`),
+    schema_hash: schemaHash,
     source_hashes: {}
   };
   return {
@@ -892,6 +1262,7 @@ function buildOutputPage(question, answer, citations) {
       freshness: "fresh",
       confidence: 0.74,
       backlinks: citations.map((sourceId) => `source:${sourceId}`),
+      schemaHash,
       sourceHashes: {}
     },
     content: matter.stringify(
@@ -916,7 +1287,7 @@ import { pathToFileURL } from "url";
 import { z as z5 } from "zod";
 
 // src/providers/base.ts
-import fs5 from "fs/promises";
+import fs6 from "fs/promises";
 import { z as z4 } from "zod";
 var BaseProviderAdapter = class {
   constructor(id, type, model, capabilities) {
@@ -945,7 +1316,7 @@ ${schemaDescription}`
     return Promise.all(
       attachments.map(async (attachment) => ({
         mimeType: attachment.mimeType,
-        base64: await fs5.readFile(attachment.filePath, "base64")
+        base64: await fs6.readFile(attachment.filePath, "base64")
       }))
     );
   }
@@ -1259,7 +1630,7 @@ function assertProviderCapability(provider, capability) {
 }
 
 // src/search.ts
-import fs6 from "fs/promises";
+import fs7 from "fs/promises";
 import path8 from "path";
 import matter2 from "gray-matter";
 function getDatabaseSync() {
@@ -1297,7 +1668,7 @@ async function rebuildSearchIndex(dbPath, pages, wikiDir) {
   const insertPage = db.prepare("INSERT INTO pages (id, path, title, body) VALUES (?, ?, ?, ?)");
   for (const page of pages) {
     const absolutePath = path8.join(wikiDir, page.path);
-    const content = await fs6.readFile(absolutePath, "utf8");
+    const content = await fs7.readFile(absolutePath, "utf8");
     const parsed = matter2(content);
     insertPage.run(page.id, page.path, page.title, parsed.content);
   }
@@ -1335,6 +1706,32 @@ function searchPages(dbPath, query, limit = 5) {
   }));
 }
 
+// src/schema.ts
+import fs8 from "fs/promises";
+import path9 from "path";
+async function loadVaultSchema(rootDir) {
+  const { paths } = await loadVaultConfig(rootDir);
+  const schemaPath = paths.schemaPath;
+  const content = await fileExists(schemaPath) ? await fs8.readFile(schemaPath, "utf8") : defaultVaultSchema();
+  const normalized = content.trim() ? content.trim() : defaultVaultSchema().trim();
+  return {
+    path: schemaPath,
+    content: normalized,
+    hash: sha256(normalized),
+    isLegacyPath: path9.basename(schemaPath) === LEGACY_SCHEMA_FILENAME && path9.basename(schemaPath) !== PRIMARY_SCHEMA_FILENAME
+  };
+}
+function buildSchemaPrompt(schema, instruction) {
+  return [
+    instruction,
+    "",
+    `Vault schema path: ${schema.path}`,
+    "",
+    "Vault schema instructions:",
+    schema.content
+  ].join("\n");
+}
+
 // src/vault.ts
 function buildGraph(manifests, analyses, pages) {
   const sourceNodes = manifests.map((manifest) => ({
@@ -1416,8 +1813,8 @@ function buildGraph(manifests, analyses, pages) {
     pages
   };
 }
-async function writePage(rootDir, relativePath, content, changedPages) {
-  const absolutePath = path9.resolve(rootDir, "wiki", relativePath);
+async function writePage(wikiDir, relativePath, content, changedPages) {
+  const absolutePath = path10.resolve(wikiDir, relativePath);
   const changed = await writeFileIfChanged(absolutePath, content);
   if (changed) {
     changedPages.push(relativePath);
@@ -1448,50 +1845,52 @@ async function initVault(rootDir) {
 }
 async function compileVault(rootDir) {
   const { paths } = await initWorkspace(rootDir);
+  const schema = await loadVaultSchema(rootDir);
   const provider = await getProviderForTask(rootDir, "compileProvider");
   const manifests = await listManifests(rootDir);
   const analyses = await Promise.all(
-    manifests.map(async (manifest) => analyzeSource(manifest, await readExtractedText(rootDir, manifest), provider, paths))
+    manifests.map(async (manifest) => analyzeSource(manifest, await readExtractedText(rootDir, manifest), provider, paths, schema))
   );
   const changedPages = [];
   const pages = [];
   await Promise.all([
-    ensureDir(path9.join(paths.wikiDir, "sources")),
-    ensureDir(path9.join(paths.wikiDir, "concepts")),
-    ensureDir(path9.join(paths.wikiDir, "entities")),
-    ensureDir(path9.join(paths.wikiDir, "outputs"))
+    ensureDir(path10.join(paths.wikiDir, "sources")),
+    ensureDir(path10.join(paths.wikiDir, "concepts")),
+    ensureDir(path10.join(paths.wikiDir, "entities")),
+    ensureDir(path10.join(paths.wikiDir, "outputs"))
   ]);
   for (const manifest of manifests) {
     const analysis = analyses.find((item) => item.sourceId === manifest.sourceId);
     if (!analysis) {
       continue;
     }
-    const sourcePage = buildSourcePage(manifest, analysis);
+    const sourcePage = buildSourcePage(manifest, analysis, schema.hash);
     pages.push(sourcePage.page);
-    await writePage(rootDir, sourcePage.page.path, sourcePage.content, changedPages);
+    await writePage(paths.wikiDir, sourcePage.page.path, sourcePage.content, changedPages);
   }
   for (const aggregate of aggregateItems(analyses, "concepts")) {
-    const page = buildAggregatePage("concept", aggregate.name, aggregate.descriptions, aggregate.sourceAnalyses, aggregate.sourceHashes);
+    const page = buildAggregatePage("concept", aggregate.name, aggregate.descriptions, aggregate.sourceAnalyses, aggregate.sourceHashes, schema.hash);
     pages.push(page.page);
-    await writePage(rootDir, page.page.path, page.content, changedPages);
+    await writePage(paths.wikiDir, page.page.path, page.content, changedPages);
   }
   for (const aggregate of aggregateItems(analyses, "entities")) {
-    const page = buildAggregatePage("entity", aggregate.name, aggregate.descriptions, aggregate.sourceAnalyses, aggregate.sourceHashes);
+    const page = buildAggregatePage("entity", aggregate.name, aggregate.descriptions, aggregate.sourceAnalyses, aggregate.sourceHashes, schema.hash);
     pages.push(page.page);
-    await writePage(rootDir, page.page.path, page.content, changedPages);
+    await writePage(paths.wikiDir, page.page.path, page.content, changedPages);
   }
   const graph = buildGraph(manifests, analyses, pages);
   await writeJsonFile(paths.graphPath, graph);
   await writeJsonFile(paths.compileStatePath, {
     generatedAt: graph.generatedAt,
+    schemaHash: schema.hash,
     analyses: Object.fromEntries(analyses.map((analysis) => [analysis.sourceId, analysisSignature(analysis)]))
   });
-  await writePage(rootDir, "index.md", buildIndexPage(pages), changedPages);
-  await writePage(rootDir, "sources/index.md", buildSectionIndex("sources", pages.filter((page) => page.kind === "source")), changedPages);
-  await writePage(rootDir, "concepts/index.md", buildSectionIndex("concepts", pages.filter((page) => page.kind === "concept")), changedPages);
-  await writePage(rootDir, "entities/index.md", buildSectionIndex("entities", pages.filter((page) => page.kind === "entity")), changedPages);
+  await writePage(paths.wikiDir, "index.md", buildIndexPage(pages, schema.hash), changedPages);
+  await writePage(paths.wikiDir, "sources/index.md", buildSectionIndex("sources", pages.filter((page) => page.kind === "source"), schema.hash), changedPages);
+  await writePage(paths.wikiDir, "concepts/index.md", buildSectionIndex("concepts", pages.filter((page) => page.kind === "concept"), schema.hash), changedPages);
+  await writePage(paths.wikiDir, "entities/index.md", buildSectionIndex("entities", pages.filter((page) => page.kind === "entity"), schema.hash), changedPages);
   await rebuildSearchIndex(paths.searchDbPath, pages, paths.wikiDir);
-  await appendLogEntry(rootDir, "compile", `Compiled ${manifests.length} source(s)`, [`provider=${provider.id}`, `pages=${pages.length}`]);
+  await appendLogEntry(rootDir, "compile", `Compiled ${manifests.length} source(s)`, [`provider=${provider.id}`, `pages=${pages.length}`, `schema=${schema.hash.slice(0, 12)}`]);
   return {
     graphPath: paths.graphPath,
     pageCount: pages.length,
@@ -1501,6 +1900,7 @@ async function compileVault(rootDir) {
 }
 async function queryVault(rootDir, question, save = false) {
   const { paths } = await loadVaultConfig(rootDir);
+  const schema = await loadVaultSchema(rootDir);
   const provider = await getProviderForTask(rootDir, "queryProvider");
   if (!await fileExists(paths.searchDbPath)) {
     await compileVault(rootDir);
@@ -1508,8 +1908,8 @@ async function queryVault(rootDir, question, save = false) {
   const searchResults = searchPages(paths.searchDbPath, question, 5);
   const excerpts = await Promise.all(
     searchResults.map(async (result) => {
-      const absolutePath = path9.join(paths.wikiDir, result.path);
-      const content = await fs7.readFile(absolutePath, "utf8");
+      const absolutePath = path10.join(paths.wikiDir, result.path);
+      const content = await fs9.readFile(absolutePath, "utf8");
       const parsed = matter3(content);
       return `# ${result.title}
 ${truncate(normalizeWhitespace(parsed.content), 1200)}`;
@@ -1527,7 +1927,7 @@ ${truncate(normalizeWhitespace(parsed.content), 1200)}`;
     ].join("\n");
   } else {
     const response = await provider.generateText({
-      system: "Answer using the provided SwarmVault excerpts. Cite source ids or page titles when possible.",
+      system: buildSchemaPrompt(schema, "Answer using the provided SwarmVault excerpts. Cite source ids or page titles when possible."),
       prompt: `Question: ${question}
 
 Context:
@@ -1541,17 +1941,62 @@ ${excerpts.join("\n\n---\n\n")}`
   );
   let savedTo;
   if (save) {
-    const output = buildOutputPage(question, answer, citations);
-    const absolutePath = path9.join(paths.wikiDir, output.page.path);
-    await ensureDir(path9.dirname(absolutePath));
-    await fs7.writeFile(absolutePath, output.content, "utf8");
+    const output = buildOutputPage(question, answer, citations, schema.hash);
+    const absolutePath = path10.join(paths.wikiDir, output.page.path);
+    await ensureDir(path10.dirname(absolutePath));
+    await fs9.writeFile(absolutePath, output.content, "utf8");
     savedTo = absolutePath;
   }
   await appendLogEntry(rootDir, "query", question, [`citations=${citations.join(",") || "none"}`, `saved=${Boolean(savedTo)}`]);
   return { answer, savedTo, citations };
 }
+async function searchVault(rootDir, query, limit = 5) {
+  const { paths } = await loadVaultConfig(rootDir);
+  if (!await fileExists(paths.searchDbPath)) {
+    await compileVault(rootDir);
+  }
+  return searchPages(paths.searchDbPath, query, limit);
+}
+async function listPages(rootDir) {
+  const { paths } = await loadVaultConfig(rootDir);
+  const graph = await readJsonFile(paths.graphPath);
+  return graph?.pages ?? [];
+}
+async function readPage(rootDir, relativePath) {
+  const { paths } = await loadVaultConfig(rootDir);
+  const absolutePath = path10.resolve(paths.wikiDir, relativePath);
+  if (!absolutePath.startsWith(paths.wikiDir) || !await fileExists(absolutePath)) {
+    return null;
+  }
+  const raw = await fs9.readFile(absolutePath, "utf8");
+  const parsed = matter3(raw);
+  return {
+    path: relativePath,
+    title: typeof parsed.data.title === "string" ? parsed.data.title : path10.basename(relativePath, path10.extname(relativePath)),
+    frontmatter: parsed.data,
+    content: parsed.content
+  };
+}
+async function getWorkspaceInfo(rootDir) {
+  const { paths } = await loadVaultConfig(rootDir);
+  const manifests = await listManifests(rootDir);
+  const pages = await listPages(rootDir);
+  return {
+    rootDir,
+    configPath: paths.configPath,
+    schemaPath: paths.schemaPath,
+    rawDir: paths.rawDir,
+    wikiDir: paths.wikiDir,
+    stateDir: paths.stateDir,
+    agentDir: paths.agentDir,
+    inboxDir: paths.inboxDir,
+    sourceCount: manifests.length,
+    pageCount: pages.length
+  };
+}
 async function lintVault(rootDir) {
   const { paths } = await loadVaultConfig(rootDir);
+  const schema = await loadVaultSchema(rootDir);
   const manifests = await listManifests(rootDir);
   const graph = await readJsonFile(paths.graphPath);
   const findings = [];
@@ -1566,6 +2011,14 @@ async function lintVault(rootDir) {
   }
   const manifestMap = new Map(manifests.map((manifest) => [manifest.sourceId, manifest]));
   for (const page of graph.pages) {
+    if (page.schemaHash !== schema.hash) {
+      findings.push({
+        severity: "warning",
+        code: "stale_page",
+        message: `Page ${page.title} is stale because the vault schema changed.`,
+        pagePath: path10.join(paths.wikiDir, page.path)
+      });
+    }
     for (const [sourceId, knownHash] of Object.entries(page.sourceHashes)) {
       const manifest = manifestMap.get(sourceId);
       if (manifest && manifest.contentHash !== knownHash) {
@@ -1573,7 +2026,7 @@ async function lintVault(rootDir) {
           severity: "warning",
           code: "stale_page",
           message: `Page ${page.title} is stale because source ${sourceId} changed.`,
-          pagePath: path9.join(paths.wikiDir, page.path)
+          pagePath: path10.join(paths.wikiDir, page.path)
         });
       }
     }
@@ -1582,12 +2035,12 @@ async function lintVault(rootDir) {
         severity: "info",
         code: "orphan_page",
         message: `Page ${page.title} has no backlinks.`,
-        pagePath: path9.join(paths.wikiDir, page.path)
+        pagePath: path10.join(paths.wikiDir, page.path)
       });
     }
-    const absolutePath = path9.join(paths.wikiDir, page.path);
+    const absolutePath = path10.join(paths.wikiDir, page.path);
     if (await fileExists(absolutePath)) {
-      const content = await fs7.readFile(absolutePath, "utf8");
+      const content = await fs9.readFile(absolutePath, "utf8");
       if (content.includes("## Claims")) {
         const uncited = content.split("\n").filter((line) => line.startsWith("- ") && !line.includes("[source:"));
         if (uncited.length) {
@@ -1618,9 +2071,9 @@ async function bootstrapDemo(rootDir, input) {
 }
 
 // src/viewer.ts
-import fs8 from "fs/promises";
+import fs10 from "fs/promises";
 import http from "http";
-import path10 from "path";
+import path11 from "path";
 import mime2 from "mime-types";
 async function startGraphServer(rootDir, port) {
   const { config, paths } = await loadVaultConfig(rootDir);
@@ -1634,12 +2087,12 @@ async function startGraphServer(rootDir, port) {
         return;
       }
       response.writeHead(200, { "content-type": "application/json" });
-      response.end(await fs8.readFile(paths.graphPath, "utf8"));
+      response.end(await fs10.readFile(paths.graphPath, "utf8"));
       return;
     }
     const relativePath = url.pathname === "/" ? "index.html" : url.pathname.slice(1);
-    const target = path10.join(paths.viewerDistDir, relativePath);
-    const fallback = path10.join(paths.viewerDistDir, "index.html");
+    const target = path11.join(paths.viewerDistDir, relativePath);
+    const fallback = path11.join(paths.viewerDistDir, "index.html");
     const filePath = await fileExists(target) ? target : fallback;
     if (!await fileExists(filePath)) {
       response.writeHead(503, { "content-type": "text/plain" });
@@ -1647,7 +2100,7 @@ async function startGraphServer(rootDir, port) {
       return;
     }
     response.writeHead(200, { "content-type": mime2.lookup(filePath) || "text/plain" });
-    response.end(await fs8.readFile(filePath));
+    response.end(await fs10.readFile(filePath));
   });
   await new Promise((resolve) => {
     server.listen(effectivePort, resolve);
@@ -1667,13 +2120,309 @@ async function startGraphServer(rootDir, port) {
     }
   };
 }
+
+// src/mcp.ts
+import fs11 from "fs/promises";
+import path12 from "path";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z as z6 } from "zod";
+var SERVER_VERSION = "0.1.4";
+async function createMcpServer(rootDir) {
+  const server = new McpServer({
+    name: "swarmvault",
+    version: SERVER_VERSION,
+    websiteUrl: "https://www.swarmvault.ai"
+  });
+  server.registerTool("workspace_info", {
+    description: "Return the current SwarmVault workspace paths and high-level counts."
+  }, async () => {
+    const info = await getWorkspaceInfo(rootDir);
+    return asToolText(info);
+  });
+  server.registerTool("search_pages", {
+    description: "Search compiled wiki pages using the local full-text index.",
+    inputSchema: {
+      query: z6.string().min(1).describe("Search query"),
+      limit: z6.number().int().min(1).max(25).optional().describe("Maximum number of results")
+    }
+  }, async ({ query, limit }) => {
+    const results = await searchVault(rootDir, query, limit ?? 5);
+    return asToolText(results);
+  });
+  server.registerTool("read_page", {
+    description: "Read a generated wiki page by its path relative to wiki/.",
+    inputSchema: {
+      path: z6.string().min(1).describe("Path relative to wiki/, for example sources/example.md")
+    }
+  }, async ({ path: relativePath }) => {
+    const page = await readPage(rootDir, relativePath);
+    if (!page) {
+      return asToolError(`Page not found: ${relativePath}`);
+    }
+    return asToolText(page);
+  });
+  server.registerTool("list_sources", {
+    description: "List source manifests in the current workspace.",
+    inputSchema: {
+      limit: z6.number().int().min(1).max(100).optional().describe("Maximum number of manifests to return")
+    }
+  }, async ({ limit }) => {
+    const manifests = await listManifests(rootDir);
+    return asToolText(limit ? manifests.slice(0, limit) : manifests);
+  });
+  server.registerTool("query_vault", {
+    description: "Ask a question against the compiled vault and optionally save the answer.",
+    inputSchema: {
+      question: z6.string().min(1).describe("Question to ask the vault"),
+      save: z6.boolean().optional().describe("Persist the answer to wiki/outputs")
+    }
+  }, async ({ question, save }) => {
+    const result = await queryVault(rootDir, question, save ?? false);
+    return asToolText(result);
+  });
+  server.registerTool("ingest_input", {
+    description: "Ingest a local file path or URL into the SwarmVault workspace.",
+    inputSchema: {
+      input: z6.string().min(1).describe("Local path or URL to ingest")
+    }
+  }, async ({ input }) => {
+    const manifest = await ingestInput(rootDir, input);
+    return asToolText(manifest);
+  });
+  server.registerTool("compile_vault", {
+    description: "Compile source manifests into wiki pages, graph data, and search index."
+  }, async () => {
+    const result = await compileVault(rootDir);
+    return asToolText(result);
+  });
+  server.registerTool("lint_vault", {
+    description: "Run anti-drift and vault health checks."
+  }, async () => {
+    const findings = await lintVault(rootDir);
+    return asToolText(findings);
+  });
+  server.registerResource("swarmvault-config", "swarmvault://config", {
+    title: "SwarmVault Config",
+    description: "The resolved SwarmVault config file.",
+    mimeType: "application/json"
+  }, async () => {
+    const { config } = await loadVaultConfig(rootDir);
+    return asTextResource("swarmvault://config", JSON.stringify(config, null, 2));
+  });
+  server.registerResource("swarmvault-graph", "swarmvault://graph", {
+    title: "SwarmVault Graph",
+    description: "The compiled graph artifact for the current workspace.",
+    mimeType: "application/json"
+  }, async () => {
+    const { paths } = await loadVaultConfig(rootDir);
+    const graph = await readJsonFile(paths.graphPath);
+    return asTextResource(
+      "swarmvault://graph",
+      JSON.stringify(graph ?? { error: "Graph artifact not found. Run `swarmvault compile` first." }, null, 2)
+    );
+  });
+  server.registerResource("swarmvault-manifests", "swarmvault://manifests", {
+    title: "SwarmVault Manifests",
+    description: "All source manifests in the workspace.",
+    mimeType: "application/json"
+  }, async () => {
+    const manifests = await listManifests(rootDir);
+    return asTextResource("swarmvault://manifests", JSON.stringify(manifests, null, 2));
+  });
+  server.registerResource("swarmvault-schema", "swarmvault://schema", {
+    title: "SwarmVault Schema",
+    description: "The vault schema file that guides compile and query behavior.",
+    mimeType: "text/markdown"
+  }, async () => {
+    const schema = await loadVaultSchema(rootDir);
+    return asTextResource("swarmvault://schema", schema.content);
+  });
+  server.registerResource(
+    "swarmvault-pages",
+    new ResourceTemplate("swarmvault://pages/{path}", {
+      list: async () => {
+        const pages = await listPages(rootDir);
+        return {
+          resources: pages.map((page) => ({
+            uri: `swarmvault://pages/${encodeURIComponent(page.path)}`,
+            name: page.title,
+            title: page.title,
+            description: `Generated ${page.kind} page`,
+            mimeType: "text/markdown"
+          }))
+        };
+      }
+    }),
+    {
+      title: "SwarmVault Pages",
+      description: "Generated wiki pages exposed as MCP resources.",
+      mimeType: "text/markdown"
+    },
+    async (_uri, variables) => {
+      const encodedPath = typeof variables.path === "string" ? variables.path : "";
+      const relativePath = decodeURIComponent(encodedPath);
+      const page = await readPage(rootDir, relativePath);
+      if (!page) {
+        return asTextResource(`swarmvault://pages/${encodedPath}`, `Page not found: ${relativePath}`);
+      }
+      const { paths } = await loadVaultConfig(rootDir);
+      const absolutePath = path12.resolve(paths.wikiDir, relativePath);
+      return asTextResource(`swarmvault://pages/${encodedPath}`, await fs11.readFile(absolutePath, "utf8"));
+    }
+  );
+  return server;
+}
+async function startMcpServer(rootDir, stdin, stdout) {
+  const server = await createMcpServer(rootDir);
+  const transport = new StdioServerTransport(stdin, stdout);
+  await server.connect(transport);
+  return {
+    close: async () => {
+      await server.close();
+    }
+  };
+}
+function asToolText(value) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(value, null, 2)
+      }
+    ]
+  };
+}
+function asToolError(message) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: message
+      }
+    ]
+  };
+}
+function asTextResource(uri, text) {
+  return {
+    contents: [
+      {
+        uri,
+        text
+      }
+    ]
+  };
+}
+
+// src/watch.ts
+import path13 from "path";
+import chokidar from "chokidar";
+async function watchVault(rootDir, options = {}) {
+  const { paths } = await initWorkspace(rootDir);
+  const debounceMs = options.debounceMs ?? 900;
+  let timer;
+  let running = false;
+  let pending = false;
+  let closed = false;
+  const reasons = /* @__PURE__ */ new Set();
+  const watcher = chokidar.watch(paths.inboxDir, {
+    ignoreInitial: true,
+    awaitWriteFinish: {
+      stabilityThreshold: Math.max(250, Math.floor(debounceMs / 2)),
+      pollInterval: 100
+    }
+  });
+  const schedule = (reason) => {
+    if (closed) {
+      return;
+    }
+    reasons.add(reason);
+    pending = true;
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      void runCycle();
+    }, debounceMs);
+  };
+  const runCycle = async () => {
+    if (running || closed || !pending) {
+      return;
+    }
+    pending = false;
+    running = true;
+    const startedAt = /* @__PURE__ */ new Date();
+    const runReasons = [...reasons];
+    reasons.clear();
+    let importedCount = 0;
+    let scannedCount = 0;
+    let attachmentCount = 0;
+    let changedPages = [];
+    let lintFindingCount;
+    let success = true;
+    let error;
+    try {
+      const imported = await importInbox(rootDir, paths.inboxDir);
+      importedCount = imported.imported.length;
+      scannedCount = imported.scannedCount;
+      attachmentCount = imported.attachmentCount;
+      const compile = await compileVault(rootDir);
+      changedPages = compile.changedPages;
+      if (options.lint) {
+        const findings = await lintVault(rootDir);
+        lintFindingCount = findings.length;
+      }
+    } catch (caught) {
+      success = false;
+      error = caught instanceof Error ? caught.message : String(caught);
+    } finally {
+      const finishedAt = /* @__PURE__ */ new Date();
+      await appendWatchRun(rootDir, {
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        inputDir: paths.inboxDir,
+        reasons: runReasons,
+        importedCount,
+        scannedCount,
+        attachmentCount,
+        changedPages,
+        lintFindingCount,
+        success,
+        error
+      });
+      running = false;
+      if (pending && !closed) {
+        schedule("queued");
+      }
+    }
+  };
+  watcher.on("add", (filePath) => schedule(`add:${toWatchReason(paths.inboxDir, filePath)}`)).on("change", (filePath) => schedule(`change:${toWatchReason(paths.inboxDir, filePath)}`)).on("unlink", (filePath) => schedule(`unlink:${toWatchReason(paths.inboxDir, filePath)}`)).on("addDir", (dirPath) => schedule(`addDir:${toWatchReason(paths.inboxDir, dirPath)}`)).on("unlinkDir", (dirPath) => schedule(`unlinkDir:${toWatchReason(paths.inboxDir, dirPath)}`)).on("error", (caught) => schedule(`error:${caught instanceof Error ? caught.message : String(caught)}`));
+  return {
+    close: async () => {
+      closed = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+      await watcher.close();
+    }
+  };
+}
+function toWatchReason(baseDir, targetPath) {
+  return path13.relative(baseDir, targetPath) || ".";
+}
 export {
   assertProviderCapability,
   bootstrapDemo,
   compileVault,
+  createMcpServer,
   createProvider,
   defaultVaultConfig,
+  defaultVaultSchema,
   getProviderForTask,
+  getWorkspaceInfo,
+  importInbox,
   ingestInput,
   initVault,
   initWorkspace,
@@ -1681,9 +2430,15 @@ export {
   installConfiguredAgents,
   lintVault,
   listManifests,
+  listPages,
   loadVaultConfig,
+  loadVaultSchema,
   queryVault,
   readExtractedText,
+  readPage,
   resolvePaths,
-  startGraphServer
+  searchVault,
+  startGraphServer,
+  startMcpServer,
+  watchVault
 };