@swarmvaultai/engine 0.1.3 → 0.1.4

package/README.md

@@ -22,12 +22,14 @@ import {
   compileVault,
   createMcpServer,
   defaultVaultConfig,
+  defaultVaultSchema,
   importInbox,
   ingestInput,
   initVault,
   installAgent,
   lintVault,
   loadVaultConfig,
+  loadVaultSchema,
   queryVault,
   searchVault,
   startGraphServer,
@@ -41,11 +43,13 @@ The engine also exports the main runtime types for providers, graph artifacts, p
 ## Example
 
 ```ts
-import { compileVault, importInbox, initVault, queryVault, watchVault } from "@swarmvaultai/engine";
+import { compileVault, importInbox, initVault, loadVaultSchema, queryVault, watchVault } from "@swarmvaultai/engine";
 
 const rootDir = process.cwd();
 
 await initVault(rootDir);
+const schema = await loadVaultSchema(rootDir);
+console.log(schema.path);
 await importInbox(rootDir);
 await compileVault(rootDir);
 
@@ -55,6 +59,18 @@ console.log(result.answer);
 const watcher = await watchVault(rootDir, { lint: true });
 ```
 
+## Schema Layer
+
+Each workspace carries a root markdown file named `swarmvault.schema.md`.
+
+The engine treats that file as vault-specific operating guidance for compile and query work. In `v0.1.4`:
+
+- `initVault()` creates the default schema file
+- `loadVaultSchema()` resolves the canonical file and legacy `schema.md` fallback
+- compile and query prompts include the schema content
+- generated pages store `schema_hash`
+- `lintVault()` marks generated pages stale when the schema changes
+
 ## Provider Model
 
 The engine supports:
@@ -88,8 +104,8 @@ This matters because many "OpenAI-compatible" backends only implement part of th
 
 ### Compile + Query
 
-- `compileVault(rootDir)` writes wiki pages, graph data, and search state
-- `queryVault(rootDir, question, save)` answers against the compiled vault
+- `compileVault(rootDir)` writes wiki pages, graph data, and search state using the vault schema as guidance
+- `queryVault(rootDir, question, save)` answers against the compiled vault using the same schema layer
 - `searchVault(rootDir, query, limit)` searches compiled pages directly
 
 ### Automation
@@ -102,12 +118,13 @@ This matters because many "OpenAI-compatible" backends only implement part of th
 - `createMcpServer(rootDir)` creates an MCP server instance
 - `startMcpServer(rootDir)` runs the MCP server over stdio
 
-The MCP surface includes tools for workspace info, page search, page reads, source listing, querying, ingestion, compile, and lint, along with resources for config, graph, manifests, and page content.
+The MCP surface includes tools for workspace info, page search, page reads, source listing, querying, ingestion, compile, and lint, along with resources for config, graph, manifests, schema, and page content.
 
 ## Artifacts
 
 Running the engine produces a local workspace with these main areas:
 
+- `swarmvault.schema.md`: vault-specific compile and query instructions
 - `inbox/`: capture staging area for markdown bundles and imported files
 - `raw/sources/`: immutable source copies
 - `raw/assets/`: copied attachments referenced by ingested markdown bundles

package/dist/index.d.ts

@@ -84,6 +84,7 @@ interface VaultConfig {
 }
 interface ResolvedPaths {
     rootDir: string;
+    schemaPath: string;
     rawDir: string;
     rawSourcesDir: string;
     rawAssetsDir: string;
@@ -137,6 +138,7 @@ interface SourceClaim {
 interface SourceAnalysis {
     sourceId: string;
     sourceHash: string;
+    schemaHash: string;
     title: string;
     summary: string;
     concepts: AnalyzedTerm[];
@@ -173,6 +175,7 @@ interface GraphPage {
     freshness: Freshness;
     confidence: number;
     backlinks: string[];
+    schemaHash: string;
     sourceHashes: Record<string, string>;
 }
 interface GraphArtifact {
@@ -240,7 +243,8 @@ interface WatchController {
 }
 
 declare function defaultVaultConfig(): VaultConfig;
-declare function resolvePaths(rootDir: string, config?: VaultConfig, configPath?: string): ResolvedPaths;
+declare function defaultVaultSchema(): string;
+declare function resolvePaths(rootDir: string, config?: VaultConfig, configPath?: string, schemaPath?: string): ResolvedPaths;
 declare function loadVaultConfig(rootDir: string): Promise<{
     config: VaultConfig;
     paths: ResolvedPaths;
@@ -269,6 +273,7 @@ declare function readPage(rootDir: string, relativePath: string): Promise<{
 declare function getWorkspaceInfo(rootDir: string): Promise<{
     rootDir: string;
     configPath: string;
+    schemaPath: string;
     rawDir: string;
     wikiDir: string;
     stateDir: string;
@@ -286,6 +291,14 @@ declare function bootstrapDemo(rootDir: string, input?: string): Promise<{
 declare function installAgent(rootDir: string, agent: "codex" | "claude" | "cursor"): Promise<string>;
 declare function installConfiguredAgents(rootDir: string): Promise<string[]>;
 
+interface VaultSchema {
+    path: string;
+    content: string;
+    hash: string;
+    isLegacyPath: boolean;
+}
+declare function loadVaultSchema(rootDir: string): Promise<VaultSchema>;
+
 declare function startGraphServer(rootDir: string, port?: number): Promise<{
     port: number;
     close: () => Promise<void>;
@@ -302,4 +315,4 @@ declare function createProvider(id: string, config: ProviderConfig, rootDir: str
 declare function getProviderForTask(rootDir: string, task: keyof Awaited<ReturnType<typeof loadVaultConfig>>["config"]["tasks"]): Promise<ProviderAdapter>;
 declare function assertProviderCapability(provider: ProviderAdapter, capability: ProviderCapability): void;
 
-export { type AnalyzedTerm, type ClaimStatus, type CompileResult, type Freshness, type GenerationAttachment, type GenerationRequest, type GenerationResponse, type GraphArtifact, type GraphEdge, type GraphNode, type GraphPage, type InboxImportResult, type InboxImportSkip, type LintFinding, type PageKind, type Polarity, type ProviderAdapter, type ProviderCapability, type ProviderConfig, type ProviderType, type QueryResult, type ResolvedPaths, type SearchResult, type SourceAnalysis, type SourceAttachment, type SourceClaim, type SourceManifest, type VaultConfig, type WatchController, type WatchOptions, type WatchRunRecord, assertProviderCapability, bootstrapDemo, compileVault, createMcpServer, createProvider, defaultVaultConfig, getProviderForTask, getWorkspaceInfo, importInbox, ingestInput, initVault, initWorkspace, installAgent, installConfiguredAgents, lintVault, listManifests, listPages, loadVaultConfig, providerCapabilitySchema, providerTypeSchema, queryVault, readExtractedText, readPage, resolvePaths, searchVault, startGraphServer, startMcpServer, watchVault };
+export { type AnalyzedTerm, type ClaimStatus, type CompileResult, type Freshness, type GenerationAttachment, type GenerationRequest, type GenerationResponse, type GraphArtifact, type GraphEdge, type GraphNode, type GraphPage, type InboxImportResult, type InboxImportSkip, type LintFinding, type PageKind, type Polarity, type ProviderAdapter, type ProviderCapability, type ProviderConfig, type ProviderType, type QueryResult, type ResolvedPaths, type SearchResult, type SourceAnalysis, type SourceAttachment, type SourceClaim, type SourceManifest, type VaultConfig, type WatchController, type WatchOptions, type WatchRunRecord, assertProviderCapability, bootstrapDemo, compileVault, createMcpServer, createProvider, defaultVaultConfig, defaultVaultSchema, getProviderForTask, getWorkspaceInfo, importInbox, ingestInput, initVault, initWorkspace, installAgent, installConfiguredAgents, lintVault, listManifests, listPages, loadVaultConfig, loadVaultSchema, providerCapabilitySchema, providerTypeSchema, queryVault, readExtractedText, readPage, resolvePaths, searchVault, startGraphServer, startMcpServer, watchVault };

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";
 
@@ -134,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,
@@ -193,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)) {
@@ -204,7 +253,18 @@ 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");
@@ -215,6 +275,7 @@ function resolvePaths(rootDir, config, configPath = path2.join(rootDir, PRIMARY_
   const inboxDir = path2.resolve(rootDir, effective.workspace.inboxDir);
   return {
     rootDir,
+    schemaPath,
     rawDir,
     rawSourcesDir,
     rawAssetsDir,
@@ -235,17 +296,21 @@ function resolvePaths(rootDir, config, configPath = path2.join(rootDir, PRIMARY_
 }
 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),
@@ -261,11 +326,15 @@ async function initWorkspace(rootDir) {
   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";
@@ -273,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);
@@ -281,8 +350,8 @@ 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) {
@@ -372,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;
@@ -398,17 +467,17 @@ async function persistPreparedInput(rootDir, prepared, paths) {
   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 fs3.writeFile(storedPath, prepared.payloadBytes);
+  await fs4.writeFile(storedPath, prepared.payloadBytes);
   let extractedTextPath;
   if (prepared.extractedText) {
     extractedTextPath = path4.join(paths.extractsDir, `${sourceId}.md`);
-    await fs3.writeFile(extractedTextPath, prepared.extractedText, "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 fs3.writeFile(absoluteAttachmentPath, attachment.bytes);
+    await fs4.writeFile(absoluteAttachmentPath, attachment.bytes);
     manifestAttachments.push({
       path: toPosix(path4.relative(rootDir, absoluteAttachmentPath)),
       mimeType: attachment.mimeType,
@@ -439,7 +508,7 @@ async function persistPreparedInput(rootDir, prepared, paths) {
   return { manifest, isNew: true };
 }
 async function prepareFileInput(rootDir, absoluteInput) {
-  const payloadBytes = await fs3.readFile(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"}`;
@@ -509,7 +578,7 @@ async function collectInboxAttachmentRefs(inputDir, files) {
     if (sourceKind !== "markdown") {
       continue;
     }
-    const content = await fs3.readFile(absolutePath, "utf8");
+    const content = await fs4.readFile(absolutePath, "utf8");
     const refs = extractMarkdownReferences(content);
     if (!refs.length) {
       continue;
@@ -550,12 +619,12 @@ function rewriteMarkdownReferences(content, replacements) {
   });
 }
 async function prepareInboxMarkdownInput(absolutePath, attachmentRefs) {
-  const originalBytes = await fs3.readFile(absolutePath);
+  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 fs3.readFile(attachmentRef.absolutePath);
+    const bytes = await fs4.readFile(attachmentRef.absolutePath);
     attachments.push({
       relativePath: sanitizeAssetRelativePath(attachmentRef.relativeRef),
       mimeType: guessMimeType(attachmentRef.absolutePath),
@@ -652,7 +721,7 @@ async function listManifests(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)))
   );
@@ -666,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
@@ -758,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)}`,
@@ -774,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,
@@ -790,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}
@@ -808,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) => ({
@@ -832,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 ?? "");
@@ -844,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: [],
@@ -853,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);
@@ -869,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 -->";
@@ -880,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.",
@@ -895,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;
   }
@@ -906,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");
@@ -932,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;
     }
@@ -961,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 = [
@@ -984,6 +1066,7 @@ function buildSourcePage(manifest, analysis) {
     confidence: 0.8,
     updated_at: analysis.producedAt,
     backlinks,
+    schema_hash: schemaHash,
     source_hashes: {
       [manifest.sourceId]: manifest.contentHash
     }
@@ -1026,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}`;
@@ -1049,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 = [
@@ -1080,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");
@@ -1102,6 +1188,7 @@ function buildIndexPage(pages) {
     "confidence: 1",
     `updated_at: ${(/* @__PURE__ */ new Date()).toISOString()}`,
     "backlinks: []",
+    `schema_hash: ${schemaHash}`,
     "source_hashes: {}",
     "---",
     "",
@@ -1121,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);
@@ -1145,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 {
@@ -1158,6 +1262,7 @@ function buildOutputPage(question, answer, citations) {
       freshness: "fresh",
       confidence: 0.74,
       backlinks: citations.map((sourceId) => `source:${sourceId}`),
+      schemaHash,
       sourceHashes: {}
     },
     content: matter.stringify(
@@ -1182,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) {
@@ -1211,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")
       }))
     );
   }
@@ -1525,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() {
@@ -1563,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);
   }
@@ -1601,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) => ({
@@ -1682,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);
@@ -1714,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,
@@ -1767,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);
@@ -1774,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)}`;
@@ -1793,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:
@@ -1807,10 +1941,10 @@ ${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)}`]);
@@ -1830,15 +1964,15 @@ async function listPages(rootDir) {
 }
 async function readPage(rootDir, relativePath) {
   const { paths } = await loadVaultConfig(rootDir);
-  const absolutePath = path9.resolve(paths.wikiDir, relativePath);
+  const absolutePath = path10.resolve(paths.wikiDir, relativePath);
   if (!absolutePath.startsWith(paths.wikiDir) || !await fileExists(absolutePath)) {
     return null;
   }
-  const raw = await fs7.readFile(absolutePath, "utf8");
+  const raw = await fs9.readFile(absolutePath, "utf8");
   const parsed = matter3(raw);
   return {
     path: relativePath,
-    title: typeof parsed.data.title === "string" ? parsed.data.title : path9.basename(relativePath, path9.extname(relativePath)),
+    title: typeof parsed.data.title === "string" ? parsed.data.title : path10.basename(relativePath, path10.extname(relativePath)),
     frontmatter: parsed.data,
     content: parsed.content
   };
@@ -1850,6 +1984,7 @@ async function getWorkspaceInfo(rootDir) {
   return {
     rootDir,
     configPath: paths.configPath,
+    schemaPath: paths.schemaPath,
     rawDir: paths.rawDir,
     wikiDir: paths.wikiDir,
     stateDir: paths.stateDir,
@@ -1861,6 +1996,7 @@ async function getWorkspaceInfo(rootDir) {
 }
 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 = [];
@@ -1875,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) {
@@ -1882,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)
         });
       }
     }
@@ -1891,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) {
@@ -1927,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);
@@ -1943,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" });
@@ -1956,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);
@@ -1978,12 +2122,12 @@ async function startGraphServer(rootDir, port) {
 }
 
 // src/mcp.ts
-import fs9 from "fs/promises";
-import path11 from "path";
+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.3";
+var SERVER_VERSION = "0.1.4";
 async function createMcpServer(rootDir) {
   const server = new McpServer({
     name: "swarmvault",
@@ -2086,6 +2230,14 @@ async function createMcpServer(rootDir) {
     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}", {
@@ -2115,8 +2267,8 @@ async function createMcpServer(rootDir) {
         return asTextResource(`swarmvault://pages/${encodedPath}`, `Page not found: ${relativePath}`);
       }
       const { paths } = await loadVaultConfig(rootDir);
-      const absolutePath = path11.resolve(paths.wikiDir, relativePath);
-      return asTextResource(`swarmvault://pages/${encodedPath}`, await fs9.readFile(absolutePath, "utf8"));
+      const absolutePath = path12.resolve(paths.wikiDir, relativePath);
+      return asTextResource(`swarmvault://pages/${encodedPath}`, await fs11.readFile(absolutePath, "utf8"));
     }
   );
   return server;
@@ -2164,7 +2316,7 @@ function asTextResource(uri, text) {
 }
 
 // src/watch.ts
-import path12 from "path";
+import path13 from "path";
 import chokidar from "chokidar";
 async function watchVault(rootDir, options = {}) {
   const { paths } = await initWorkspace(rootDir);
@@ -2258,7 +2410,7 @@ async function watchVault(rootDir, options = {}) {
   };
 }
 function toWatchReason(baseDir, targetPath) {
-  return path12.relative(baseDir, targetPath) || ".";
+  return path13.relative(baseDir, targetPath) || ".";
 }
 export {
   assertProviderCapability,
@@ -2267,6 +2419,7 @@ export {
   createMcpServer,
   createProvider,
   defaultVaultConfig,
+  defaultVaultSchema,
   getProviderForTask,
   getWorkspaceInfo,
   importInbox,
@@ -2279,6 +2432,7 @@ export {
   listManifests,
   listPages,
   loadVaultConfig,
+  loadVaultSchema,
   queryVault,
   readExtractedText,
   readPage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/engine",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Core engine for SwarmVault: ingest, compile, query, lint, and provider abstractions.",
   "type": "module",
   "main": "dist/index.js",