@swarmvaultai/engine 0.1.0

package/dist/index.js

@@ -0,0 +1,1689 @@
+// src/config.ts
+import path2 from "path";
+import { fileURLToPath } from "url";
+import { z as z2 } from "zod";
+
+// src/utils.ts
+import crypto from "crypto";
+import fs from "fs/promises";
+import path from "path";
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "item";
+}
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readJsonFile(filePath) {
+  if (!await fileExists(filePath)) {
+    return null;
+  }
+  const content = await fs.readFile(filePath, "utf8");
+  return JSON.parse(content);
+}
+async function writeJsonFile(filePath, value) {
+  await ensureDir(path.dirname(filePath));
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+async function writeFileIfChanged(filePath, content) {
+  await ensureDir(path.dirname(filePath));
+  if (await fileExists(filePath)) {
+    const existing = await fs.readFile(filePath, "utf8");
+    if (existing === content) {
+      return false;
+    }
+  }
+  await fs.writeFile(filePath, content, "utf8");
+  return true;
+}
+function toPosix(value) {
+  return value.split(path.sep).join(path.posix.sep);
+}
+function firstSentences(value, count = 3) {
+  const sentences = value.replace(/\s+/g, " ").split(/(?<=[.!?])\s+/).filter(Boolean);
+  return sentences.slice(0, count).join(" ").trim();
+}
+function uniqueBy(items, key) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const item of items) {
+    const itemKey = key(item);
+    if (seen.has(itemKey)) {
+      continue;
+    }
+    seen.add(itemKey);
+    result.push(item);
+  }
+  return result;
+}
+function extractJson(text) {
+  const fencedMatch = text.match(/```json\s*([\s\S]*?)```/i);
+  if (fencedMatch) {
+    return fencedMatch[1].trim();
+  }
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  if (start !== -1 && end !== -1 && end > start) {
+    return text.slice(start, end + 1);
+  }
+  throw new Error("Could not locate JSON object in provider response.");
+}
+function normalizeWhitespace(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function truncate(value, maxLength) {
+  if (value.length <= maxLength) {
+    return value;
+  }
+  return `${value.slice(0, maxLength - 3)}...`;
+}
+
+// src/types.ts
+import { z } from "zod";
+var providerCapabilitySchema = z.enum([
+  "responses",
+  "chat",
+  "structured",
+  "tools",
+  "vision",
+  "embeddings",
+  "streaming",
+  "local"
+]);
+var providerTypeSchema = z.enum([
+  "heuristic",
+  "openai",
+  "ollama",
+  "anthropic",
+  "gemini",
+  "openai-compatible",
+  "custom"
+]);
+
+// src/config.ts
+var PRIMARY_CONFIG_FILENAME = "swarmvault.config.json";
+var LEGACY_CONFIG_FILENAME = "vault.config.json";
+var moduleDir = path2.dirname(fileURLToPath(import.meta.url));
+var providerConfigSchema = z2.object({
+  type: providerTypeSchema,
+  model: z2.string().min(1),
+  baseUrl: z2.string().url().optional(),
+  apiKeyEnv: z2.string().min(1).optional(),
+  headers: z2.record(z2.string(), z2.string()).optional(),
+  module: z2.string().min(1).optional(),
+  capabilities: z2.array(providerCapabilitySchema).optional(),
+  apiStyle: z2.enum(["responses", "chat"]).optional()
+});
+var vaultConfigSchema = z2.object({
+  workspace: z2.object({
+    rawDir: z2.string().min(1),
+    wikiDir: z2.string().min(1),
+    stateDir: z2.string().min(1),
+    agentDir: z2.string().min(1)
+  }),
+  providers: z2.record(z2.string(), providerConfigSchema),
+  tasks: z2.object({
+    compileProvider: z2.string().min(1),
+    queryProvider: z2.string().min(1),
+    lintProvider: z2.string().min(1),
+    visionProvider: z2.string().min(1)
+  }),
+  viewer: z2.object({
+    port: z2.number().int().positive()
+  }),
+  agents: z2.array(z2.enum(["codex", "claude", "cursor"])).default(["codex", "claude", "cursor"])
+});
+function defaultVaultConfig() {
+  return {
+    workspace: {
+      rawDir: "raw",
+      wikiDir: "wiki",
+      stateDir: "state",
+      agentDir: "agent"
+    },
+    providers: {
+      local: {
+        type: "heuristic",
+        model: "heuristic-v1",
+        capabilities: ["chat", "structured", "vision", "local"]
+      }
+    },
+    tasks: {
+      compileProvider: "local",
+      queryProvider: "local",
+      lintProvider: "local",
+      visionProvider: "local"
+    },
+    viewer: {
+      port: 4123
+    },
+    agents: ["codex", "claude", "cursor"]
+  };
+}
+async function findConfigPath(rootDir) {
+  const primaryPath = path2.join(rootDir, PRIMARY_CONFIG_FILENAME);
+  if (await fileExists(primaryPath)) {
+    return primaryPath;
+  }
+  const legacyPath = path2.join(rootDir, LEGACY_CONFIG_FILENAME);
+  if (await fileExists(legacyPath)) {
+    return legacyPath;
+  }
+  return primaryPath;
+}
+function resolvePaths(rootDir, config, configPath = path2.join(rootDir, PRIMARY_CONFIG_FILENAME)) {
+  const effective = config ?? defaultVaultConfig();
+  const rawDir = path2.resolve(rootDir, effective.workspace.rawDir);
+  const wikiDir = path2.resolve(rootDir, effective.workspace.wikiDir);
+  const stateDir = path2.resolve(rootDir, effective.workspace.stateDir);
+  const agentDir = path2.resolve(rootDir, effective.workspace.agentDir);
+  return {
+    rootDir,
+    rawDir,
+    wikiDir,
+    stateDir,
+    agentDir,
+    manifestsDir: path2.join(stateDir, "manifests"),
+    extractsDir: path2.join(stateDir, "extracts"),
+    analysesDir: path2.join(stateDir, "analyses"),
+    viewerDistDir: path2.resolve(moduleDir, "../../viewer/dist"),
+    graphPath: path2.join(stateDir, "graph.json"),
+    searchDbPath: path2.join(stateDir, "search.sqlite"),
+    compileStatePath: path2.join(stateDir, "compile-state.json"),
+    configPath
+  };
+}
+async function loadVaultConfig(rootDir) {
+  const configPath = await findConfigPath(rootDir);
+  const raw = await readJsonFile(configPath);
+  const parsed = vaultConfigSchema.parse(raw ?? defaultVaultConfig());
+  return {
+    config: parsed,
+    paths: resolvePaths(rootDir, parsed, configPath)
+  };
+}
+async function initWorkspace(rootDir) {
+  const configPath = await findConfigPath(rootDir);
+  const config = await fileExists(configPath) ? (await loadVaultConfig(rootDir)).config : defaultVaultConfig();
+  const paths = resolvePaths(rootDir, config, configPath);
+  await Promise.all([
+    ensureDir(paths.rawDir),
+    ensureDir(paths.wikiDir),
+    ensureDir(paths.stateDir),
+    ensureDir(paths.agentDir),
+    ensureDir(paths.manifestsDir),
+    ensureDir(paths.extractsDir),
+    ensureDir(paths.analysesDir)
+  ]);
+  if (!await fileExists(configPath)) {
+    await writeJsonFile(configPath, config);
+  }
+  return { config, paths };
+}
+
+// src/ingest.ts
+import fs3 from "fs/promises";
+import path4 from "path";
+import { JSDOM } from "jsdom";
+import TurndownService from "turndown";
+import { Readability } from "@mozilla/readability";
+import mime from "mime-types";
+
+// src/logs.ts
+import fs2 from "fs/promises";
+import path3 from "path";
+async function appendLogEntry(rootDir, action, title, lines = []) {
+  const { paths } = await initWorkspace(rootDir);
+  await ensureDir(paths.wikiDir);
+  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}
+`, "utf8");
+}
+
+// src/ingest.ts
+function inferKind(mimeType, filePath) {
+  if (mimeType.includes("markdown")) {
+    return "markdown";
+  }
+  if (mimeType.startsWith("text/")) {
+    return "text";
+  }
+  if (mimeType === "application/pdf" || filePath.toLowerCase().endsWith(".pdf")) {
+    return "pdf";
+  }
+  if (mimeType.startsWith("image/")) {
+    return "image";
+  }
+  if (mimeType.includes("html")) {
+    return "html";
+  }
+  return "binary";
+}
+function titleFromText(fallback, content) {
+  const heading = content.match(/^#\s+(.+)$/m)?.[1]?.trim();
+  return heading || fallback;
+}
+function guessMimeType(target) {
+  return mime.lookup(target) || "application/octet-stream";
+}
+async function convertHtmlToMarkdown(html, url) {
+  const dom = new JSDOM(html, { url });
+  const article = new Readability(dom.window.document).parse();
+  const turndown = new TurndownService({ headingStyle: "atx", codeBlockStyle: "fenced" });
+  const body = article?.content ?? dom.window.document.body.innerHTML;
+  const markdown = turndown.turndown(body);
+  return {
+    markdown,
+    title: article?.title?.trim() || new URL(url).hostname
+  };
+}
+async function readManifestByHash(manifestsDir, contentHash) {
+  const entries = await fs3.readdir(manifestsDir, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) {
+      continue;
+    }
+    const manifest = await readJsonFile(path4.join(manifestsDir, entry.name));
+    if (manifest?.contentHash === contentHash) {
+      return manifest;
+    }
+  }
+  return null;
+}
+async function ingestInput(rootDir, input) {
+  const { paths } = await initWorkspace(rootDir);
+  await ensureDir(path4.join(paths.rawDir, "sources"));
+  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 existing = await readManifestByHash(paths.manifestsDir, contentHash);
+  if (existing) {
+    return existing;
+  }
+  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") {
+    extractedTextPath = path4.join(paths.extractsDir, `${sourceId}.md`);
+    await fs3.writeFile(extractedTextPath, payloadBytes.toString("utf8"), "utf8");
+  }
+  const manifest = {
+    sourceId,
+    title,
+    originType: isUrl ? "url" : "file",
+    sourceKind,
+    originalPath: isUrl ? void 0 : toPosix(path4.resolve(rootDir, input)),
+    url: isUrl ? input : void 0,
+    storedPath: toPosix(path4.relative(rootDir, storedPath)),
+    extractedTextPath: extractedTextPath ? toPosix(path4.relative(rootDir, extractedTextPath)) : void 0,
+    mimeType,
+    contentHash,
+    createdAt: now,
+    updatedAt: now
+  };
+  await writeJsonFile(path4.join(paths.manifestsDir, `${sourceId}.json`), manifest);
+  await appendLogEntry(rootDir, "ingest", title, [`source_id=${sourceId}`, `kind=${sourceKind}`]);
+  return manifest;
+}
+async function listManifests(rootDir) {
+  const { paths } = await loadVaultConfig(rootDir);
+  if (!await fileExists(paths.manifestsDir)) {
+    return [];
+  }
+  const entries = await fs3.readdir(paths.manifestsDir);
+  const manifests = await Promise.all(
+    entries.filter((entry) => entry.endsWith(".json")).map((entry) => readJsonFile(path4.join(paths.manifestsDir, entry)))
+  );
+  return manifests.filter((manifest) => Boolean(manifest));
+}
+async function readExtractedText(rootDir, manifest) {
+  if (!manifest.extractedTextPath) {
+    return void 0;
+  }
+  const absolutePath = path4.resolve(rootDir, manifest.extractedTextPath);
+  if (!await fileExists(absolutePath)) {
+    return void 0;
+  }
+  return fs3.readFile(absolutePath, "utf8");
+}
+
+// src/vault.ts
+import fs7 from "fs/promises";
+import path9 from "path";
+import matter3 from "gray-matter";
+
+// src/analysis.ts
+import path5 from "path";
+import { z as z3 } from "zod";
+var sourceAnalysisSchema = z3.object({
+  title: z3.string().min(1),
+  summary: z3.string().min(1),
+  concepts: z3.array(z3.object({ name: z3.string().min(1), description: z3.string().default("") })).max(12).default([]),
+  entities: z3.array(z3.object({ name: z3.string().min(1), description: z3.string().default("") })).max(12).default([]),
+  claims: z3.array(z3.object({
+    text: z3.string().min(1),
+    confidence: z3.number().min(0).max(1).default(0.6),
+    status: z3.enum(["extracted", "inferred", "conflicted", "stale"]).default("extracted"),
+    polarity: z3.enum(["positive", "negative", "neutral"]).default("neutral"),
+    citation: z3.string().min(1)
+  })).max(8).default([]),
+  questions: z3.array(z3.string()).max(6).default([])
+});
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "about",
+  "after",
+  "also",
+  "been",
+  "being",
+  "between",
+  "both",
+  "could",
+  "does",
+  "each",
+  "from",
+  "have",
+  "into",
+  "just",
+  "more",
+  "much",
+  "only",
+  "other",
+  "over",
+  "same",
+  "some",
+  "such",
+  "than",
+  "that",
+  "their",
+  "there",
+  "these",
+  "they",
+  "this",
+  "very",
+  "what",
+  "when",
+  "where",
+  "which",
+  "while",
+  "with",
+  "would",
+  "your"
+]);
+function extractTopTerms(text, count) {
+  const frequency = /* @__PURE__ */ new Map();
+  for (const token of text.toLowerCase().match(/[a-z][a-z0-9-]{3,}/g) ?? []) {
+    if (STOPWORDS.has(token)) {
+      continue;
+    }
+    frequency.set(token, (frequency.get(token) ?? 0) + 1);
+  }
+  return [...frequency.entries()].sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])).slice(0, count).map(([token]) => token);
+}
+function extractEntities(text, count) {
+  const matches = text.match(/\b[A-Z][A-Za-z0-9-]+(?:\s+[A-Z][A-Za-z0-9-]+){0,2}\b/g) ?? [];
+  return uniqueBy(matches.map((value) => normalizeWhitespace(value)), (value) => value.toLowerCase()).slice(0, count);
+}
+function detectPolarity(text) {
+  if (/\b(no|not|never|cannot|can't|won't|without)\b/i.test(text)) {
+    return "negative";
+  }
+  if (/\b(is|are|will|does|supports|enables|improves|includes)\b/i.test(text)) {
+    return "positive";
+  }
+  return "neutral";
+}
+function deriveTitle(manifest, text) {
+  const heading = text.match(/^#\s+(.+)$/m)?.[1]?.trim();
+  return heading || manifest.title;
+}
+function heuristicAnalysis(manifest, text) {
+  const normalized = normalizeWhitespace(text);
+  const concepts = extractTopTerms(normalized, 6).map((term) => ({
+    id: `concept:${slugify(term)}`,
+    name: term,
+    description: `Frequently referenced concept in ${manifest.title}.`
+  }));
+  const entities = extractEntities(text, 6).map((term) => ({
+    id: `entity:${slugify(term)}`,
+    name: term,
+    description: `Named entity mentioned in ${manifest.title}.`
+  }));
+  const claimSentences = normalized.split(/(?<=[.!?])\s+/).filter(Boolean).slice(0, 4);
+  return {
+    sourceId: manifest.sourceId,
+    sourceHash: manifest.contentHash,
+    title: deriveTitle(manifest, text),
+    summary: firstSentences(normalized, 3) || truncate(normalized, 280) || `Imported ${manifest.sourceKind} source.`,
+    concepts,
+    entities,
+    claims: claimSentences.map((sentence, index) => ({
+      id: `claim:${manifest.sourceId}:${index + 1}`,
+      text: sentence,
+      confidence: 0.55,
+      status: "extracted",
+      polarity: detectPolarity(sentence),
+      citation: manifest.sourceId
+    })),
+    questions: concepts.slice(0, 3).map((term) => `How does ${term.name} relate to ${manifest.title}?`),
+    producedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+async function providerAnalysis(manifest, text, provider) {
+  const parsed = await provider.generateStructured(
+    {
+      system: "You are compiling a durable markdown wiki and graph. Prefer grounded synthesis over creativity.",
+      prompt: `Analyze the following source and return structured JSON.
+
+Source title: ${manifest.title}
+Source kind: ${manifest.sourceKind}
+Source id: ${manifest.sourceId}
+
+Text:
+${truncate(text, 18e3)}`
+    },
+    sourceAnalysisSchema
+  );
+  return {
+    sourceId: manifest.sourceId,
+    sourceHash: manifest.contentHash,
+    title: parsed.title,
+    summary: parsed.summary,
+    concepts: parsed.concepts.map((term) => ({
+      id: `concept:${slugify(term.name)}`,
+      name: term.name,
+      description: term.description
+    })),
+    entities: parsed.entities.map((term) => ({
+      id: `entity:${slugify(term.name)}`,
+      name: term.name,
+      description: term.description
+    })),
+    claims: parsed.claims.map((claim, index) => ({
+      id: `claim:${manifest.sourceId}:${index + 1}`,
+      text: claim.text,
+      confidence: claim.confidence,
+      status: claim.status,
+      polarity: claim.polarity,
+      citation: claim.citation
+    })),
+    questions: parsed.questions,
+    producedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+async function analyzeSource(manifest, extractedText, provider, paths) {
+  const cachePath = path5.join(paths.analysesDir, `${manifest.sourceId}.json`);
+  const cached = await readJsonFile(cachePath);
+  if (cached && cached.sourceHash === manifest.contentHash) {
+    return cached;
+  }
+  const content = normalizeWhitespace(extractedText ?? "");
+  let analysis;
+  if (!content) {
+    analysis = {
+      sourceId: manifest.sourceId,
+      sourceHash: manifest.contentHash,
+      title: manifest.title,
+      summary: `Imported ${manifest.sourceKind} source. Text extraction is not yet available for this source.`,
+      concepts: [],
+      entities: [],
+      claims: [],
+      questions: [],
+      producedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  } else if (provider.type === "heuristic") {
+    analysis = heuristicAnalysis(manifest, content);
+  } else {
+    try {
+      analysis = await providerAnalysis(manifest, content, provider);
+    } catch {
+      analysis = heuristicAnalysis(manifest, content);
+    }
+  }
+  await writeJsonFile(cachePath, analysis);
+  return analysis;
+}
+function analysisSignature(analysis) {
+  return sha256(JSON.stringify(analysis));
+}
+
+// src/agents.ts
+import fs4 from "fs/promises";
+import path6 from "path";
+var managedStart = "<!-- swarmvault:managed:start -->";
+var managedEnd = "<!-- swarmvault:managed:end -->";
+var legacyManagedStart = "<!-- vault:managed:start -->";
+var legacyManagedEnd = "<!-- vault:managed:end -->";
+function buildManagedBlock(agent) {
+  const body = [
+    managedStart,
+    `# SwarmVault Rules (${agent})`,
+    "",
+    "- 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.",
+    "- Preserve frontmatter fields including `page_id`, `source_ids`, `node_ids`, `freshness`, and `source_hashes`.",
+    "- Save high-value answers back into `wiki/outputs/` instead of leaving them only in chat.",
+    "- Prefer `swarmvault ingest`, `swarmvault compile`, `swarmvault query`, and `swarmvault lint` for SwarmVault maintenance tasks.",
+    managedEnd,
+    ""
+  ].join("\n");
+  if (agent === "cursor") {
+    return body;
+  }
+  return body;
+}
+async function upsertManagedBlock(filePath, block) {
+  const existing = await fileExists(filePath) ? await fs4.readFile(filePath, "utf8") : "";
+  if (!existing) {
+    await ensureDir(path6.dirname(filePath));
+    await fs4.writeFile(filePath, `${block}
+`, "utf8");
+    return;
+  }
+  const startIndex = existing.includes(managedStart) ? existing.indexOf(managedStart) : existing.indexOf(legacyManagedStart);
+  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");
+    return;
+  }
+  await fs4.writeFile(filePath, `${existing.trimEnd()}
+
+${block}
+`, "utf8");
+}
+async function installAgent(rootDir, agent) {
+  const { paths } = await initWorkspace(rootDir);
+  const block = buildManagedBlock(agent);
+  switch (agent) {
+    case "codex": {
+      const target = path6.join(rootDir, "AGENTS.md");
+      await upsertManagedBlock(target, block);
+      return target;
+    }
+    case "claude": {
+      const target = path6.join(rootDir, "CLAUDE.md");
+      await upsertManagedBlock(target, block);
+      return target;
+    }
+    case "cursor": {
+      const rulesDir = path6.join(rootDir, ".cursor", "rules");
+      await ensureDir(rulesDir);
+      const target = path6.join(rulesDir, "swarmvault.mdc");
+      await fs4.writeFile(target, `${block}
+`, "utf8");
+      return target;
+    }
+    default:
+      throw new Error(`Unsupported agent ${String(agent)}`);
+  }
+}
+async function installConfiguredAgents(rootDir) {
+  const { config } = await initWorkspace(rootDir);
+  return Promise.all(config.agents.map((agent) => installAgent(rootDir, agent)));
+}
+
+// src/markdown.ts
+import matter from "gray-matter";
+function pagePathFor(kind, slug) {
+  switch (kind) {
+    case "source":
+      return `sources/${slug}.md`;
+    case "concept":
+      return `concepts/${slug}.md`;
+    case "entity":
+      return `entities/${slug}.md`;
+    case "output":
+      return `outputs/${slug}.md`;
+    default:
+      return `${slug}.md`;
+  }
+}
+function buildSourcePage(manifest, analysis) {
+  const relativePath = pagePathFor("source", manifest.sourceId);
+  const pageId = `source:${manifest.sourceId}`;
+  const nodeIds = [
+    `source:${manifest.sourceId}`,
+    ...analysis.concepts.map((item) => item.id),
+    ...analysis.entities.map((item) => item.id)
+  ];
+  const backlinks = [
+    ...analysis.concepts.map((item) => `concept:${slugify(item.name)}`),
+    ...analysis.entities.map((item) => `entity:${slugify(item.name)}`)
+  ];
+  const frontmatter = {
+    page_id: pageId,
+    kind: "source",
+    title: analysis.title,
+    tags: ["source"],
+    source_ids: [manifest.sourceId],
+    node_ids: nodeIds,
+    freshness: "fresh",
+    confidence: 0.8,
+    updated_at: analysis.producedAt,
+    backlinks,
+    source_hashes: {
+      [manifest.sourceId]: manifest.contentHash
+    }
+  };
+  const body = [
+    `# ${analysis.title}`,
+    "",
+    `Source ID: \`${manifest.sourceId}\``,
+    manifest.url ? `Source URL: ${manifest.url}` : `Source Path: \`${manifest.originalPath ?? manifest.storedPath}\``,
+    "",
+    "## Summary",
+    "",
+    analysis.summary,
+    "",
+    "## Concepts",
+    "",
+    ...analysis.concepts.length ? analysis.concepts.map((item) => `- [[${pagePathFor("concept", slugify(item.name)).replace(/\.md$/, "")}|${item.name}]]: ${item.description}`) : ["- None detected."],
+    "",
+    "## Entities",
+    "",
+    ...analysis.entities.length ? analysis.entities.map((item) => `- [[${pagePathFor("entity", slugify(item.name)).replace(/\.md$/, "")}|${item.name}]]: ${item.description}`) : ["- None detected."],
+    "",
+    "## Claims",
+    "",
+    ...analysis.claims.length ? analysis.claims.map((claim) => `- ${claim.text} [source:${claim.citation}]`) : ["- No claims extracted."],
+    "",
+    "## Questions",
+    "",
+    ...analysis.questions.length ? analysis.questions.map((question) => `- ${question}`) : ["- No follow-up questions yet."],
+    ""
+  ].join("\n");
+  return {
+    page: {
+      id: pageId,
+      path: relativePath,
+      title: analysis.title,
+      kind: "source",
+      sourceIds: [manifest.sourceId],
+      nodeIds,
+      freshness: "fresh",
+      confidence: 0.8,
+      backlinks,
+      sourceHashes: { [manifest.sourceId]: manifest.contentHash }
+    },
+    content: matter.stringify(body, frontmatter)
+  };
+}
+function buildAggregatePage(kind, name, descriptions, sourceAnalyses, sourceHashes) {
+  const slug = slugify(name);
+  const relativePath = pagePathFor(kind, slug);
+  const pageId = `${kind}:${slug}`;
+  const sourceIds = sourceAnalyses.map((item) => item.sourceId);
+  const otherPages = sourceAnalyses.map((item) => `source:${item.sourceId}`);
+  const summary = descriptions.find(Boolean) ?? `${kind} aggregated from ${sourceIds.length} source(s).`;
+  const frontmatter = {
+    page_id: pageId,
+    kind,
+    title: name,
+    tags: [kind],
+    source_ids: sourceIds,
+    node_ids: [pageId],
+    freshness: "fresh",
+    confidence: 0.72,
+    updated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    backlinks: otherPages,
+    source_hashes: sourceHashes
+  };
+  const body = [
+    `# ${name}`,
+    "",
+    "## Summary",
+    "",
+    summary,
+    "",
+    "## Seen In",
+    "",
+    ...sourceAnalyses.map((item) => `- [[${pagePathFor("source", item.sourceId).replace(/\.md$/, "")}|${item.title}]]`),
+    "",
+    "## Source Claims",
+    "",
+    ...sourceAnalyses.flatMap(
+      (item) => item.claims.filter((claim) => claim.text.toLowerCase().includes(name.toLowerCase())).map((claim) => `- ${claim.text} [source:${claim.citation}]`)
+    ),
+    ""
+  ].join("\n");
+  return {
+    page: {
+      id: pageId,
+      path: relativePath,
+      title: name,
+      kind,
+      sourceIds,
+      nodeIds: [pageId],
+      freshness: "fresh",
+      confidence: 0.72,
+      backlinks: otherPages,
+      sourceHashes
+    },
+    content: matter.stringify(body, frontmatter)
+  };
+}
+function buildIndexPage(pages) {
+  const sources = pages.filter((page) => page.kind === "source");
+  const concepts = pages.filter((page) => page.kind === "concept");
+  const entities = pages.filter((page) => page.kind === "entity");
+  return [
+    "---",
+    "page_id: index",
+    "kind: index",
+    "title: SwarmVault Index",
+    "tags:",
+    "  - index",
+    "source_ids: []",
+    "node_ids: []",
+    "freshness: fresh",
+    "confidence: 1",
+    `updated_at: ${(/* @__PURE__ */ new Date()).toISOString()}`,
+    "backlinks: []",
+    "source_hashes: {}",
+    "---",
+    "",
+    "# SwarmVault Index",
+    "",
+    "## Sources",
+    "",
+    ...sources.length ? sources.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`) : ["- No sources yet."],
+    "",
+    "## Concepts",
+    "",
+    ...concepts.length ? concepts.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`) : ["- No concepts yet."],
+    "",
+    "## Entities",
+    "",
+    ...entities.length ? entities.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`) : ["- No entities yet."],
+    ""
+  ].join("\n");
+}
+function buildSectionIndex(kind, pages) {
+  const title = kind.charAt(0).toUpperCase() + kind.slice(1);
+  return [
+    `# ${title}`,
+    "",
+    ...pages.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`),
+    ""
+  ].join("\n");
+}
+function buildOutputPage(question, answer, citations) {
+  const slug = slugify(question);
+  const pageId = `output:${slug}`;
+  const pathValue = pagePathFor("output", slug);
+  const frontmatter = {
+    page_id: pageId,
+    kind: "output",
+    title: question,
+    tags: ["output"],
+    source_ids: citations,
+    node_ids: [],
+    freshness: "fresh",
+    confidence: 0.74,
+    updated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    backlinks: citations.map((sourceId) => `source:${sourceId}`),
+    source_hashes: {}
+  };
+  return {
+    page: {
+      id: pageId,
+      path: pathValue,
+      title: question,
+      kind: "output",
+      sourceIds: citations,
+      nodeIds: [],
+      freshness: "fresh",
+      confidence: 0.74,
+      backlinks: citations.map((sourceId) => `source:${sourceId}`),
+      sourceHashes: {}
+    },
+    content: matter.stringify(
+      [
+        `# ${question}`,
+        "",
+        answer,
+        "",
+        "## Citations",
+        "",
+        ...citations.map((citation) => `- [source:${citation}]`),
+        ""
+      ].join("\n"),
+      frontmatter
+    )
+  };
+}
+
+// src/providers/registry.ts
+import path7 from "path";
+import { pathToFileURL } from "url";
+import { z as z5 } from "zod";
+
+// src/providers/base.ts
+import fs5 from "fs/promises";
+import { z as z4 } from "zod";
+var BaseProviderAdapter = class {
+  constructor(id, type, model, capabilities) {
+    this.id = id;
+    this.type = type;
+    this.model = model;
+    this.capabilities = new Set(capabilities);
+  }
+  id;
+  type;
+  model;
+  capabilities;
+  async generateStructured(request, schema) {
+    const schemaDescription = JSON.stringify(z4.toJSONSchema(schema), null, 2);
+    const response = await this.generateText({
+      ...request,
+      prompt: `${request.prompt}
+
+Return JSON only. Follow this JSON Schema exactly:
+${schemaDescription}`
+    });
+    const parsed = JSON.parse(extractJson(response.text));
+    return schema.parse(parsed);
+  }
+  async encodeAttachments(attachments = []) {
+    return Promise.all(
+      attachments.map(async (attachment) => ({
+        mimeType: attachment.mimeType,
+        base64: await fs5.readFile(attachment.filePath, "base64")
+      }))
+    );
+  }
+};
+
+// src/providers/heuristic.ts
+function summarizePrompt(prompt) {
+  const cleaned = normalizeWhitespace(prompt);
+  if (!cleaned) {
+    return "No prompt content provided.";
+  }
+  return firstSentences(cleaned, 2) || cleaned.slice(0, 280);
+}
+var HeuristicProviderAdapter = class extends BaseProviderAdapter {
+  constructor(id, model) {
+    super(id, "heuristic", model, ["chat", "structured", "vision", "local"]);
+  }
+  async generateText(request) {
+    const attachmentHint = request.attachments?.length ? ` Attachments: ${request.attachments.length}.` : "";
+    return {
+      text: `Heuristic provider response.${attachmentHint} ${summarizePrompt(request.prompt)}`.trim()
+    };
+  }
+};
+
+// src/providers/openai-compatible.ts
+function buildAuthHeaders(apiKey) {
+  return apiKey ? { Authorization: `Bearer ${apiKey}` } : {};
+}
+var OpenAiCompatibleProviderAdapter = class extends BaseProviderAdapter {
+  baseUrl;
+  apiKey;
+  headers;
+  apiStyle;
+  constructor(id, type, model, options) {
+    super(id, type, model, options.capabilities);
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.headers = options.headers;
+    this.apiStyle = options.apiStyle ?? "responses";
+  }
+  async generateText(request) {
+    if (this.apiStyle === "chat") {
+      return this.generateViaChatCompletions(request);
+    }
+    return this.generateViaResponses(request);
+  }
+  async generateViaResponses(request) {
+    const encodedAttachments = await this.encodeAttachments(request.attachments);
+    const input = encodedAttachments.length ? [
+      {
+        role: "user",
+        content: [
+          { type: "input_text", text: request.prompt },
+          ...encodedAttachments.map((item) => ({
+            type: "input_image",
+            image_url: `data:${item.mimeType};base64,${item.base64}`
+          }))
+        ]
+      }
+    ] : request.prompt;
+    const response = await fetch(`${this.baseUrl}/responses`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...buildAuthHeaders(this.apiKey),
+        ...this.headers
+      },
+      body: JSON.stringify({
+        model: this.model,
+        input,
+        instructions: request.system,
+        max_output_tokens: request.maxOutputTokens
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Provider ${this.id} failed: ${response.status} ${response.statusText}`);
+    }
+    const payload = await response.json();
+    return {
+      text: payload.output_text ?? "",
+      usage: payload.usage ? { inputTokens: payload.usage.input_tokens, outputTokens: payload.usage.output_tokens } : void 0
+    };
+  }
+  async generateViaChatCompletions(request) {
+    const encodedAttachments = await this.encodeAttachments(request.attachments);
+    const content = encodedAttachments.length ? [
+      { type: "text", text: request.prompt },
+      ...encodedAttachments.map((item) => ({
+        type: "image_url",
+        image_url: {
+          url: `data:${item.mimeType};base64,${item.base64}`
+        }
+      }))
+    ] : request.prompt;
+    const messages = [
+      ...request.system ? [{ role: "system", content: request.system }] : [],
+      { role: "user", content }
+    ];
+    const response = await fetch(`${this.baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...buildAuthHeaders(this.apiKey),
+        ...this.headers
+      },
+      body: JSON.stringify({
+        model: this.model,
+        messages,
+        max_tokens: request.maxOutputTokens
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Provider ${this.id} failed: ${response.status} ${response.statusText}`);
+    }
+    const payload = await response.json();
+    const contentValue = payload.choices?.[0]?.message?.content;
+    const text = Array.isArray(contentValue) ? contentValue.map((item) => item.text ?? "").join("\n") : contentValue ?? "";
+    return {
+      text,
+      usage: payload.usage ? { inputTokens: payload.usage.prompt_tokens, outputTokens: payload.usage.completion_tokens } : void 0
+    };
+  }
+};
+
+// src/providers/anthropic.ts
+var AnthropicProviderAdapter = class extends BaseProviderAdapter {
+  apiKey;
+  headers;
+  baseUrl;
+  constructor(id, model, options) {
+    super(id, "anthropic", model, ["chat", "structured", "tools", "vision", "streaming"]);
+    this.apiKey = options.apiKey;
+    this.headers = options.headers;
+    this.baseUrl = (options.baseUrl ?? "https://api.anthropic.com").replace(/\/+$/, "");
+  }
+  async generateText(request) {
+    const encodedAttachments = await this.encodeAttachments(request.attachments);
+    const content = [
+      { type: "text", text: request.prompt },
+      ...encodedAttachments.map((item) => ({
+        type: "image",
+        source: {
+          type: "base64",
+          media_type: item.mimeType,
+          data: item.base64
+        }
+      }))
+    ];
+    const response = await fetch(`${this.baseUrl}/v1/messages`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "anthropic-version": "2023-06-01",
+        ...this.apiKey ? { "x-api-key": this.apiKey } : {},
+        ...this.headers
+      },
+      body: JSON.stringify({
+        model: this.model,
+        max_tokens: request.maxOutputTokens ?? 1200,
+        system: request.system,
+        messages: [
+          {
+            role: "user",
+            content
+          }
+        ]
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Provider ${this.id} failed: ${response.status} ${response.statusText}`);
+    }
+    const payload = await response.json();
+    return {
+      text: payload.content?.filter((item) => item.type === "text").map((item) => item.text ?? "").join("\n") ?? "",
+      usage: payload.usage ? { inputTokens: payload.usage.input_tokens, outputTokens: payload.usage.output_tokens } : void 0
+    };
+  }
+};
+
+// src/providers/gemini.ts
+var GeminiProviderAdapter = class extends BaseProviderAdapter {
+  apiKey;
+  baseUrl;
+  constructor(id, model, options) {
+    super(id, "gemini", model, ["chat", "structured", "vision", "tools", "streaming"]);
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? "https://generativelanguage.googleapis.com/v1beta").replace(/\/+$/, "");
+  }
+  async generateText(request) {
+    const encodedAttachments = await this.encodeAttachments(request.attachments);
+    const parts = [
+      ...request.system ? [{ text: `System instructions:
+${request.system}` }] : [],
+      { text: request.prompt },
+      ...encodedAttachments.map((item) => ({
+        inline_data: {
+          mime_type: item.mimeType,
+          data: item.base64
+        }
+      }))
+    ];
+    const response = await fetch(`${this.baseUrl}/models/${this.model}:generateContent`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...this.apiKey ? { "x-goog-api-key": this.apiKey } : {}
+      },
+      body: JSON.stringify({
+        contents: [
+          {
+            role: "user",
+            parts
+          }
+        ],
+        generationConfig: {
+          maxOutputTokens: request.maxOutputTokens ?? 1200
+        }
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Provider ${this.id} failed: ${response.status} ${response.statusText}`);
+    }
+    const payload = await response.json();
+    const text = payload.candidates?.[0]?.content?.parts?.map((part) => part.text ?? "").join("\n") ?? "";
+    return {
+      text,
+      usage: payload.usageMetadata ? { inputTokens: payload.usageMetadata.promptTokenCount, outputTokens: payload.usageMetadata.candidatesTokenCount } : void 0
+    };
+  }
+};
+
+// src/providers/registry.ts
+var customModuleSchema = z5.object({
+  createAdapter: z5.function({
+    input: [z5.string(), z5.custom(), z5.string()],
+    output: z5.promise(z5.custom())
+  })
+});
+function resolveCapabilities(config, fallback) {
+  return config.capabilities?.length ? config.capabilities : fallback;
+}
+function envOrUndefined(name) {
+  return name ? process.env[name] : void 0;
+}
+async function createProvider(id, config, rootDir) {
+  switch (config.type) {
+    case "heuristic":
+      return new HeuristicProviderAdapter(id, config.model);
+    case "openai":
+      return new OpenAiCompatibleProviderAdapter(id, "openai", config.model, {
+        baseUrl: config.baseUrl ?? "https://api.openai.com/v1",
+        apiKey: envOrUndefined(config.apiKeyEnv),
+        headers: config.headers,
+        apiStyle: config.apiStyle ?? "responses",
+        capabilities: resolveCapabilities(config, ["responses", "chat", "structured", "tools", "vision", "streaming"])
+      });
+    case "ollama":
+      return new OpenAiCompatibleProviderAdapter(id, "ollama", config.model, {
+        baseUrl: config.baseUrl ?? "http://localhost:11434/v1",
+        apiKey: envOrUndefined(config.apiKeyEnv) ?? "ollama",
+        headers: config.headers,
+        apiStyle: config.apiStyle ?? "responses",
+        capabilities: resolveCapabilities(config, ["responses", "chat", "structured", "tools", "vision", "streaming", "local"])
+      });
+    case "openai-compatible":
+      return new OpenAiCompatibleProviderAdapter(id, "openai-compatible", config.model, {
+        baseUrl: config.baseUrl ?? "http://localhost:8000/v1",
+        apiKey: envOrUndefined(config.apiKeyEnv),
+        headers: config.headers,
+        apiStyle: config.apiStyle ?? "responses",
+        capabilities: resolveCapabilities(config, ["chat", "structured"])
+      });
+    case "anthropic":
+      return new AnthropicProviderAdapter(id, config.model, {
+        apiKey: envOrUndefined(config.apiKeyEnv),
+        headers: config.headers,
+        baseUrl: config.baseUrl
+      });
+    case "gemini":
+      return new GeminiProviderAdapter(id, config.model, {
+        apiKey: envOrUndefined(config.apiKeyEnv),
+        baseUrl: config.baseUrl
+      });
+    case "custom": {
+      if (!config.module) {
+        throw new Error(`Provider ${id} is type "custom" but no module path was configured.`);
+      }
+      const resolvedModule = path7.isAbsolute(config.module) ? config.module : path7.resolve(rootDir, config.module);
+      const loaded = await import(pathToFileURL(resolvedModule).href);
+      const parsed = customModuleSchema.parse(loaded);
+      return parsed.createAdapter(id, config, rootDir);
+    }
+    default:
+      throw new Error(`Unsupported provider type ${String(config.type)}`);
+  }
+}
+async function getProviderForTask(rootDir, task) {
+  const { config } = await loadVaultConfig(rootDir);
+  const providerId = config.tasks[task];
+  const providerConfig = config.providers[providerId];
+  if (!providerConfig) {
+    throw new Error(`No provider configured with id "${providerId}" for task "${task}".`);
+  }
+  return createProvider(providerId, providerConfig, rootDir);
+}
+function assertProviderCapability(provider, capability) {
+  if (!provider.capabilities.has(capability)) {
+    throw new Error(`Provider ${provider.id} does not support required capability "${capability}".`);
+  }
+}
+
+// src/search.ts
+import fs6 from "fs/promises";
+import path8 from "path";
+import matter2 from "gray-matter";
+function getDatabaseSync() {
+  const builtin = process.getBuiltinModule?.("node:sqlite");
+  if (!builtin?.DatabaseSync) {
+    throw new Error("node:sqlite is unavailable in this Node runtime.");
+  }
+  return builtin.DatabaseSync;
+}
+function toFtsQuery(query) {
+  const tokens = query.toLowerCase().match(/[a-z0-9]{2,}/g)?.filter(Boolean) ?? [];
+  return tokens.join(" OR ");
+}
+async function rebuildSearchIndex(dbPath, pages, wikiDir) {
+  await ensureDir(path8.dirname(dbPath));
+  const DatabaseSync = getDatabaseSync();
+  const db = new DatabaseSync(dbPath);
+  db.exec("PRAGMA journal_mode = WAL;");
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS pages (
+      id TEXT PRIMARY KEY,
+      path TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT NOT NULL
+    );
+    CREATE VIRTUAL TABLE IF NOT EXISTS page_search USING fts5(
+      title,
+      body,
+      content='pages',
+      content_rowid='rowid'
+    );
+    DELETE FROM page_search;
+    DELETE FROM pages;
+  `);
+  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 parsed = matter2(content);
+    insertPage.run(page.id, page.path, page.title, parsed.content);
+  }
+  db.exec("INSERT INTO page_search (rowid, title, body) SELECT rowid, title, body FROM pages;");
+  db.close();
+}
+function searchPages(dbPath, query, limit = 5) {
+  const ftsQuery = toFtsQuery(query);
+  if (!ftsQuery) {
+    return [];
+  }
+  const DatabaseSync = getDatabaseSync();
+  const db = new DatabaseSync(dbPath, { readOnly: true });
+  const statement = db.prepare(`
+    SELECT
+      pages.id AS pageId,
+      pages.path AS path,
+      pages.title AS title,
+      snippet(page_search, 1, '[', ']', '...', 16) AS snippet,
+      bm25(page_search) AS rank
+    FROM page_search
+    JOIN pages ON pages.rowid = page_search.rowid
+    WHERE page_search MATCH ?
+    ORDER BY rank
+    LIMIT ?
+  `);
+  const rows = statement.all(ftsQuery, limit);
+  db.close();
+  return rows.map((row) => ({
+    pageId: String(row.pageId ?? ""),
+    path: String(row.path ?? ""),
+    title: String(row.title ?? ""),
+    snippet: String(row.snippet ?? ""),
+    rank: Number(row.rank ?? 0)
+  }));
+}
+
+// src/vault.ts
+function buildGraph(manifests, analyses, pages) {
+  const sourceNodes = manifests.map((manifest) => ({
+    id: `source:${manifest.sourceId}`,
+    type: "source",
+    label: manifest.title,
+    pageId: `source:${manifest.sourceId}`,
+    freshness: "fresh",
+    confidence: 1,
+    sourceIds: [manifest.sourceId]
+  }));
+  const conceptMap = /* @__PURE__ */ new Map();
+  const entityMap = /* @__PURE__ */ new Map();
+  const edges = [];
+  for (const analysis of analyses) {
+    for (const concept of analysis.concepts) {
+      const existing = conceptMap.get(concept.id);
+      conceptMap.set(concept.id, {
+        id: concept.id,
+        type: "concept",
+        label: concept.name,
+        pageId: `concept:${slugify(concept.name)}`,
+        freshness: "fresh",
+        confidence: 0.7,
+        sourceIds: [.../* @__PURE__ */ new Set([...existing?.sourceIds ?? [], analysis.sourceId])]
+      });
+      edges.push({
+        id: `${analysis.sourceId}->${concept.id}`,
+        source: `source:${analysis.sourceId}`,
+        target: concept.id,
+        relation: "mentions",
+        status: "extracted",
+        confidence: 0.72,
+        provenance: [analysis.sourceId]
+      });
+    }
+    for (const entity of analysis.entities) {
+      const existing = entityMap.get(entity.id);
+      entityMap.set(entity.id, {
+        id: entity.id,
+        type: "entity",
+        label: entity.name,
+        pageId: `entity:${slugify(entity.name)}`,
+        freshness: "fresh",
+        confidence: 0.7,
+        sourceIds: [.../* @__PURE__ */ new Set([...existing?.sourceIds ?? [], analysis.sourceId])]
+      });
+      edges.push({
+        id: `${analysis.sourceId}->${entity.id}`,
+        source: `source:${analysis.sourceId}`,
+        target: entity.id,
+        relation: "mentions",
+        status: "extracted",
+        confidence: 0.72,
+        provenance: [analysis.sourceId]
+      });
+    }
+    const conflictClaims = analysis.claims.filter((claim) => claim.polarity === "negative");
+    for (const claim of conflictClaims) {
+      const related = analyses.filter((item) => item.sourceId !== analysis.sourceId).flatMap((item) => item.claims.filter((other) => other.polarity === "positive" && other.text.split(" ").some((word) => claim.text.includes(word))));
+      for (const other of related) {
+        edges.push({
+          id: `${claim.id}->${other.id}`,
+          source: `source:${analysis.sourceId}`,
+          target: `source:${other.citation}`,
+          relation: "conflicted_with",
+          status: "conflicted",
+          confidence: 0.6,
+          provenance: [analysis.sourceId, other.citation]
+        });
+      }
+    }
+  }
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    nodes: [...sourceNodes, ...conceptMap.values(), ...entityMap.values()],
+    edges,
+    sources: manifests,
+    pages
+  };
+}
+async function writePage(rootDir, relativePath, content, changedPages) {
+  const absolutePath = path9.resolve(rootDir, "wiki", relativePath);
+  const changed = await writeFileIfChanged(absolutePath, content);
+  if (changed) {
+    changedPages.push(relativePath);
+  }
+}
+function aggregateItems(analyses, kind) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const analysis of analyses) {
+    for (const item of analysis[kind]) {
+      const key = slugify(item.name);
+      const existing = grouped.get(key) ?? {
+        name: item.name,
+        descriptions: [],
+        sourceAnalyses: [],
+        sourceHashes: {}
+      };
+      existing.descriptions.push(item.description);
+      existing.sourceAnalyses.push(analysis);
+      existing.sourceHashes[analysis.sourceId] = analysis.sourceHash;
+      grouped.set(key, existing);
+    }
+  }
+  return [...grouped.values()];
+}
+async function initVault(rootDir) {
+  await initWorkspace(rootDir);
+  await installConfiguredAgents(rootDir);
+}
+async function compileVault(rootDir) {
+  const { paths } = await initWorkspace(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))
+  );
+  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"))
+  ]);
+  for (const manifest of manifests) {
+    const analysis = analyses.find((item) => item.sourceId === manifest.sourceId);
+    if (!analysis) {
+      continue;
+    }
+    const sourcePage = buildSourcePage(manifest, analysis);
+    pages.push(sourcePage.page);
+    await writePage(rootDir, 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);
+    pages.push(page.page);
+    await writePage(rootDir, 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);
+    pages.push(page.page);
+    await writePage(rootDir, page.page.path, page.content, changedPages);
+  }
+  const graph = buildGraph(manifests, analyses, pages);
+  await writeJsonFile(paths.graphPath, graph);
+  await writeJsonFile(paths.compileStatePath, {
+    generatedAt: graph.generatedAt,
+    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 rebuildSearchIndex(paths.searchDbPath, pages, paths.wikiDir);
+  await appendLogEntry(rootDir, "compile", `Compiled ${manifests.length} source(s)`, [`provider=${provider.id}`, `pages=${pages.length}`]);
+  return {
+    graphPath: paths.graphPath,
+    pageCount: pages.length,
+    changedPages,
+    sourceCount: manifests.length
+  };
+}
+async function queryVault(rootDir, question, save = false) {
+  const { paths } = await loadVaultConfig(rootDir);
+  const provider = await getProviderForTask(rootDir, "queryProvider");
+  if (!await fileExists(paths.searchDbPath)) {
+    await compileVault(rootDir);
+  }
+  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 parsed = matter3(content);
+      return `# ${result.title}
+${truncate(normalizeWhitespace(parsed.content), 1200)}`;
+    })
+  );
+  let answer;
+  if (provider.type === "heuristic") {
+    answer = [
+      `Question: ${question}`,
+      "",
+      "Relevant pages:",
+      ...searchResults.map((result) => `- ${result.title} (${result.path})`),
+      "",
+      excerpts.length ? excerpts.join("\n\n") : "No relevant pages found yet."
+    ].join("\n");
+  } else {
+    const response = await provider.generateText({
+      system: "Answer using the provided SwarmVault excerpts. Cite source ids or page titles when possible.",
+      prompt: `Question: ${question}
+
+Context:
+${excerpts.join("\n\n---\n\n")}`
+    });
+    answer = response.text;
+  }
+  const citations = uniqueBy(
+    searchResults.filter((result) => result.pageId.startsWith("source:")).map((result) => result.pageId.replace(/^source:/, "")),
+    (item) => item
+  );
+  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");
+    savedTo = absolutePath;
+  }
+  await appendLogEntry(rootDir, "query", question, [`citations=${citations.join(",") || "none"}`, `saved=${Boolean(savedTo)}`]);
+  return { answer, savedTo, citations };
+}
+async function lintVault(rootDir) {
+  const { paths } = await loadVaultConfig(rootDir);
+  const manifests = await listManifests(rootDir);
+  const graph = await readJsonFile(paths.graphPath);
+  const findings = [];
+  if (!graph) {
+    return [
+      {
+        severity: "warning",
+        code: "graph_missing",
+        message: "No graph artifact found. Run `swarmvault compile` first."
+      }
+    ];
+  }
+  const manifestMap = new Map(manifests.map((manifest) => [manifest.sourceId, manifest]));
+  for (const page of graph.pages) {
+    for (const [sourceId, knownHash] of Object.entries(page.sourceHashes)) {
+      const manifest = manifestMap.get(sourceId);
+      if (manifest && manifest.contentHash !== knownHash) {
+        findings.push({
+          severity: "warning",
+          code: "stale_page",
+          message: `Page ${page.title} is stale because source ${sourceId} changed.`,
+          pagePath: path9.join(paths.wikiDir, page.path)
+        });
+      }
+    }
+    if (page.kind !== "index" && page.backlinks.length === 0) {
+      findings.push({
+        severity: "info",
+        code: "orphan_page",
+        message: `Page ${page.title} has no backlinks.`,
+        pagePath: path9.join(paths.wikiDir, page.path)
+      });
+    }
+    const absolutePath = path9.join(paths.wikiDir, page.path);
+    if (await fileExists(absolutePath)) {
+      const content = await fs7.readFile(absolutePath, "utf8");
+      if (content.includes("## Claims")) {
+        const uncited = content.split("\n").filter((line) => line.startsWith("- ") && !line.includes("[source:"));
+        if (uncited.length) {
+          findings.push({
+            severity: "warning",
+            code: "uncited_claims",
+            message: `Page ${page.title} contains uncited claim bullets.`,
+            pagePath: absolutePath
+          });
+        }
+      }
+    }
+  }
+  await appendLogEntry(rootDir, "lint", `Linted ${graph.pages.length} page(s)`, [`findings=${findings.length}`]);
+  return findings;
+}
+async function bootstrapDemo(rootDir, input) {
+  await initVault(rootDir);
+  if (!input) {
+    return {};
+  }
+  const manifest = await ingestInput(rootDir, input);
+  const compile = await compileVault(rootDir);
+  return {
+    manifestId: manifest.sourceId,
+    compile
+  };
+}
+
+// src/viewer.ts
+import fs8 from "fs/promises";
+import http from "http";
+import path10 from "path";
+import mime2 from "mime-types";
+async function startGraphServer(rootDir, port) {
+  const { config, paths } = await loadVaultConfig(rootDir);
+  const effectivePort = port ?? config.viewer.port;
+  const server = http.createServer(async (request, response) => {
+    const url = new URL(request.url ?? "/", `http://${request.headers.host ?? `localhost:${effectivePort}`}`);
+    if (url.pathname === "/api/graph") {
+      if (!await fileExists(paths.graphPath)) {
+        response.writeHead(404, { "content-type": "application/json" });
+        response.end(JSON.stringify({ error: "Graph artifact not found. Run `swarmvault compile` first." }));
+        return;
+      }
+      response.writeHead(200, { "content-type": "application/json" });
+      response.end(await fs8.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 filePath = await fileExists(target) ? target : fallback;
+    if (!await fileExists(filePath)) {
+      response.writeHead(503, { "content-type": "text/plain" });
+      response.end("Viewer build not found. Run `pnpm build` first.");
+      return;
+    }
+    response.writeHead(200, { "content-type": mime2.lookup(filePath) || "text/plain" });
+    response.end(await fs8.readFile(filePath));
+  });
+  await new Promise((resolve) => {
+    server.listen(effectivePort, resolve);
+  });
+  return {
+    port: effectivePort,
+    close: async () => {
+      await new Promise((resolve, reject) => {
+        server.close((error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      });
+    }
+  };
+}
+export {
+  assertProviderCapability,
+  bootstrapDemo,
+  compileVault,
+  createProvider,
+  defaultVaultConfig,
+  getProviderForTask,
+  ingestInput,
+  initVault,
+  initWorkspace,
+  installAgent,
+  installConfiguredAgents,
+  lintVault,
+  listManifests,
+  loadVaultConfig,
+  queryVault,
+  readExtractedText,
+  resolvePaths,
+  startGraphServer
+};