diffdoc 0.5.0 → 0.6.1

package/README.md

@@ -165,6 +165,8 @@ DIFFDOC_SUMMARIZE_CONCURRENCY
 DIFFDOC_INCLUDE_GLOBS
 DIFFDOC_EXCLUDE_GLOBS
 DIFFDOC_IGNORE_FILE
+DIFFDOC_SUMMARY_PROMPT
+DIFFDOC_SUMMARY_PROMPT_FILE
 LOCAL_LLM_ENDPOINT
 LOCAL_CHAT_MODEL
 LOCAL_EMBED_ENDPOINT
@@ -231,16 +233,26 @@ npx diffdoc summarize --path . --mode all
 npx diffdoc summarize --path . --mode delta
 npx diffdoc summarize --path . --mode delta --json
 npx diffdoc summarize --path . --mode all --summarize-concurrency 4
+npx diffdoc summarize --path . --mode all --refresh
 ```
 
 Summarization runs with bounded concurrency. The default is `2`; use `1` for strict rate limits, `2-4` for most providers, and higher values only when your local model server or API quota can handle the request volume.
 
-Store raw code snapshots in summary assets when you want retrieved results to include source text:
+Use `--summary-prompt` or `--summary-prompt-file` to add domain-specific guidance without replacing DiffDoc's default structured prompt:
+
+```bash
+npx diffdoc summarize --summary-prompt "Emphasize billing behavior, permissions, data retention, and operational risk."
+npx diffdoc summarize --summary-prompt-file ./diffdoc-summary-prompt.md
+```
+
+Raw code snapshots are optional. DiffDoc normally stores file path and content hash metadata so tools can look up source files from the repository when needed. Store raw code snapshots only when you need exported, offline, or point-in-time audit artifacts to include source text:
 
 ```bash
 npx diffdoc summarize --path . --mode all --include-code-snapshot
 ```
 
+Snapshots increase artifact size and duplicate source code, which can include sensitive or proprietary content.
+
 Check manifest and index freshness:
 
 ```bash
@@ -248,6 +260,8 @@ npx diffdoc status
 npx diffdoc status --json
 ```
 
+`status` also recommends the next command to run. It prioritizes refreshing missing or stale summaries before rebuilding the vector index.
+
 Embed summaries into the local Vectra index:
 
 ```bash
@@ -305,13 +319,47 @@ Each summary asset is portable JSON:
 
 ```json
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "content_hash": "md5-string",
-  "summary": "Plain-English explanation text here.",
+  "metadata": {
+    "file_path": "src/example.ts",
+    "file_name": "example.ts",
+    "extension": ".ts",
+    "line_count": 42,
+    "byte_size": 1200,
+    "content_hash": "md5-string",
+    "generated_at": "2026-05-27T00:00:00.000Z",
+    "generator": {
+      "provider": "local",
+      "model": "qwen2.5-coder:7b",
+      "base_url": "http://localhost:11434/v1"
+    },
+    "prompt_version": 1,
+    "summary_format": "structured-functional-v1"
+  },
+  "summary": "## Metadata\n- File path: src/example.ts\n...",
   "raw_code_snapshot": "Optional code text when --include-code-snapshot is enabled"
 }
 ```
 
+The JSON `metadata` contains deterministic source and generation facts. The markdown `summary` begins with `## Metadata`, which is embedded with the rest of the summary so file paths, hashes, inferred language/type, symbols, functions, classes, and dependencies are searchable. Language/type and symbol/dependency details are inferred by the model from the file path, extension, and code content rather than maintained through a static parser.
+
+Structured summaries use these sections in order:
+
+```md
+## Metadata
+## Purpose
+## User-Visible Behavior
+## Business Rules
+## Data Inputs And Outputs
+## Side Effects
+## Error And Edge Cases
+## Dependencies
+## Operational Notes
+```
+
+Summary assets are regenerated when the source hash changes, summary schema changes, prompt version changes, summary format changes, custom prompt hash changes, provider/model changes, or `--refresh` is passed. Regenerate existing schema `1` artifacts with `npx diffdoc summarize --mode all --refresh`. The `embed` command remains tolerant of older summary assets as long as they contain a content hash and summary text; use `status` or `summarize` to identify and refresh stale metadata.
+
 Commit `.diffdoc/manifest.json` and `.diffdoc/summaries/*.json` if you want summaries shared across machines or CI runs. Keep `.diffdoc/vectra/` local unless you have a specific reason to commit the generated vector index.
 
 The manifest and summary assets are the stable handoff point for consumers. The local Vectra index produced by `diffdoc embed` is optional and can be replaced by any embedding model and storage backend that fits your environment.

package/dist/commands/embed.js

@@ -22,36 +22,25 @@ function getSummaryPath(summaryDir, hash) {
     return node_path_1.default.resolve(summaryDir, `${hash}.json`);
 }
 async function readManifest(manifestPath) {
-    const parsed = JSON.parse(await promises_1.default.readFile(manifestPath, "utf8"));
-    if (parsed.schemaVersion !== artifacts_1.MANIFEST_SCHEMA_VERSION) {
-        throw new Error(`Unsupported manifest schema in ${manifestPath}. Expected schemaVersion ${artifacts_1.MANIFEST_SCHEMA_VERSION}.`);
+    const raw = JSON.parse(await promises_1.default.readFile(manifestPath, "utf8"));
+    const result = artifacts_1.RepoManifestSchema.safeParse(raw);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
+        throw new Error(`Invalid manifest in ${manifestPath}:\n${issues}`);
     }
-    return {
-        schemaVersion: artifacts_1.MANIFEST_SCHEMA_VERSION,
-        lastSyncedCommit: typeof parsed.lastSyncedCommit === "string" ? parsed.lastSyncedCommit : "",
-        files: parsed.files && typeof parsed.files === "object" ? parsed.files : {}
-    };
+    return result.data;
 }
 async function readSummaryAsset(summaryPath) {
-    const parsed = JSON.parse(await promises_1.default.readFile(summaryPath, "utf8"));
-    if (parsed.schemaVersion !== artifacts_1.SUMMARY_ASSET_SCHEMA_VERSION) {
-        throw new Error(`Unsupported summary schema in ${summaryPath}. Expected schemaVersion ${artifacts_1.SUMMARY_ASSET_SCHEMA_VERSION}.`);
+    const raw = JSON.parse(await promises_1.default.readFile(summaryPath, "utf8"));
+    const result = artifacts_1.SummaryAssetSchema.safeParse(raw);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
+        throw new Error(`Invalid summary asset in ${summaryPath}:\n${issues}`);
     }
-    if (typeof parsed.content_hash !== "string") {
-        throw new Error(`Invalid summary hash in ${summaryPath}.`);
-    }
-    if (typeof parsed.summary !== "string") {
-        throw new Error(`Invalid summary text in ${summaryPath}.`);
-    }
-    return {
-        schemaVersion: artifacts_1.SUMMARY_ASSET_SCHEMA_VERSION,
-        content_hash: parsed.content_hash,
-        summary: parsed.summary,
-        raw_code_snapshot: typeof parsed.raw_code_snapshot === "string" ? parsed.raw_code_snapshot : undefined
-    };
+    return result.data;
 }
-function buildDocument(filePath, summaryText) {
-    return `File: ${filePath}\nSummary: ${summaryText}`;
+function buildDocument(summaryAsset) {
+    return summaryAsset.summary;
 }
 async function runEmbed(options, config) {
     const manifestPath = (0, paths_1.resolveDiffdocArtifactPath)(options.manifest, config.baseDir);
@@ -96,7 +85,7 @@ async function runEmbed(options, config) {
             hash,
             summaryText: summaryAsset.summary,
             rawCodeSnapshot: summaryAsset.raw_code_snapshot,
-            document: buildDocument(filePath, summaryAsset.summary)
+            document: buildDocument(summaryAsset)
         });
     }
     const activePathSet = new Set(entries.map(([filePath]) => filePath));

package/dist/commands/init.js

@@ -8,7 +8,10 @@ const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
 const promises_2 = require("node:readline/promises");
 const node_process_1 = require("node:process");
+const SCHEMA_BASE_URL = "https://raw.githubusercontent.com/sullyTheDev/diffdoc";
+const PKG_VERSION = require("../../package.json").version;
 const DEFAULT_CONFIG = {
+    $schema: `${SCHEMA_BASE_URL}/v${PKG_VERSION}/schemas/diffdocrc.schema.json`,
     baseDir: "./.diffdoc",
     aiProvider: "local",
     localLlmEndpoint: "http://localhost:11434/v1",

package/dist/commands/status.js

@@ -10,6 +10,7 @@ const vectra_1 = require("vectra");
 const embed_1 = require("./embed");
 const artifacts_1 = require("../types/artifacts");
 const paths_1 = require("../utils/paths");
+const llm_1 = require("../utils/llm");
 function getSummaryDir(manifestPath) {
     return node_path_1.default.resolve(node_path_1.default.dirname(manifestPath), "summaries");
 }
@@ -25,18 +26,12 @@ async function readManifest(manifestPath) {
         }
         throw error;
     }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error(`Invalid manifest JSON in ${manifestPath}. Expected an object.`);
+    const result = artifacts_1.RepoManifestSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
+        throw new Error(`Invalid manifest in ${manifestPath}:\n${issues}`);
     }
-    const manifest = parsed;
-    if (manifest.schemaVersion !== artifacts_1.MANIFEST_SCHEMA_VERSION) {
-        throw new Error(`Unsupported manifest schema in ${manifestPath}. Expected schemaVersion ${artifacts_1.MANIFEST_SCHEMA_VERSION}.`);
-    }
-    return {
-        schemaVersion: artifacts_1.MANIFEST_SCHEMA_VERSION,
-        lastSyncedCommit: typeof manifest.lastSyncedCommit === "string" ? manifest.lastSyncedCommit : "",
-        files: manifest.files && typeof manifest.files === "object" ? manifest.files : {}
-    };
+    return result.data;
 }
 async function getSummaryStats(manifestPath, manifest) {
     const summaryDir = getSummaryDir(manifestPath);
@@ -64,10 +59,36 @@ async function getSummaryStats(manifestPath, manifest) {
             missingFromManifestCount += 1;
         }
     }
+    let staleCount = 0;
+    for (const hash of manifestHashes) {
+        if (!summaryHashes.has(hash)) {
+            continue;
+        }
+        try {
+            const raw = JSON.parse(await promises_1.default.readFile(node_path_1.default.resolve(summaryDir, `${hash}.json`), "utf8"));
+            const result = artifacts_1.SummaryAssetSchema.safeParse(raw);
+            if (!result.success) {
+                staleCount += 1;
+                continue;
+            }
+            const asset = result.data;
+            if (asset.content_hash !== hash ||
+                !asset.metadata ||
+                asset.metadata.content_hash !== hash ||
+                asset.metadata.prompt_version !== llm_1.SUMMARY_PROMPT_VERSION ||
+                asset.metadata.summary_format !== llm_1.SUMMARY_FORMAT) {
+                staleCount += 1;
+            }
+        }
+        catch {
+            staleCount += 1;
+        }
+    }
     return {
         summaryFileCount: summaryHashes.size,
         orphanCount,
-        missingFromManifestCount
+        missingFromManifestCount,
+        staleCount
     };
 }
 async function getIndexFreshness(manifest, config) {
@@ -120,22 +141,58 @@ async function getIndexFreshness(manifest, config) {
     };
 }
 function formatSummaryFreshness(stats) {
-    if (stats.missingFromManifestCount === 0) {
+    if (stats.missingFromManifestCount === 0 && stats.staleCount === 0) {
         return "fresh";
     }
-    return `stale (missing: ${stats.missingFromManifestCount})`;
+    return `stale (missing: ${stats.missingFromManifestCount}, stale: ${stats.staleCount})`;
+}
+function buildSummarizeCommand(manifestOption) {
+    const command = "diffdoc summarize --mode all --refresh";
+    return manifestOption === "manifest.json" ? command : `${command} --out ${manifestOption}`;
+}
+function buildEmbedCommand(manifestOption) {
+    const command = "diffdoc embed";
+    return manifestOption === "manifest.json" ? command : `${command} --manifest ${manifestOption}`;
+}
+function getNextCommand(manifestOption, summaryStats, indexFreshness) {
+    if (summaryStats.missingFromManifestCount > 0 || summaryStats.staleCount > 0) {
+        return {
+            command: buildSummarizeCommand(manifestOption),
+            reason: "summary artifacts are missing or stale"
+        };
+    }
+    if (indexFreshness.status === "missing") {
+        return {
+            command: buildEmbedCommand(manifestOption),
+            reason: "vector index is missing"
+        };
+    }
+    if (indexFreshness.status === "stale") {
+        return {
+            command: buildEmbedCommand(manifestOption),
+            reason: "vector index is stale"
+        };
+    }
+    return {
+        command: null,
+        reason: "summaries and index are fresh"
+    };
 }
-function buildStatusReport(manifest, summaryStats, indexFreshness) {
+function buildStatusReport(manifest, summaryStats, indexFreshness, manifestOption) {
+    const nextCommand = getNextCommand(manifestOption, summaryStats, indexFreshness);
     return {
         manifestSchema: manifest.schemaVersion,
         trackedFileCount: Object.keys(manifest.files).length,
         summaryFileCount: summaryStats.summaryFileCount,
         orphanCount: summaryStats.orphanCount,
         summaryFreshness: {
-            status: summaryStats.missingFromManifestCount === 0 ? "fresh" : "stale",
-            missing: summaryStats.missingFromManifestCount
+            status: summaryStats.missingFromManifestCount === 0 && summaryStats.staleCount === 0 ? "fresh" : "stale",
+            missing: summaryStats.missingFromManifestCount,
+            stale: summaryStats.staleCount
         },
-        indexFreshness
+        indexFreshness,
+        nextCommand: nextCommand.command,
+        nextCommandReason: nextCommand.reason
     };
 }
 function formatIndexFreshness(freshness) {
@@ -152,7 +209,7 @@ async function runStatus(options, config) {
     const manifest = await readManifest(manifestPath);
     const summaryStats = await getSummaryStats(manifestPath, manifest);
     const indexFreshness = await getIndexFreshness(manifest, config);
-    const report = buildStatusReport(manifest, summaryStats, indexFreshness);
+    const report = buildStatusReport(manifest, summaryStats, indexFreshness, options.manifest);
     if (options.json) {
         console.log(JSON.stringify(report, null, 2));
         return;
@@ -161,6 +218,10 @@ async function runStatus(options, config) {
     console.log(`tracked files: ${report.trackedFileCount}`);
     console.log(`summary files: ${report.summaryFileCount}`);
     console.log(`orphans: ${report.orphanCount}`);
+    console.log(`stale summaries: ${report.summaryFreshness.stale}`);
     console.log(`summary freshness: ${formatSummaryFreshness(summaryStats)}`);
     console.log(`index freshness: ${formatIndexFreshness(indexFreshness)}`);
+    console.log("");
+    console.log(`next command: ${report.nextCommand || "none"}`);
+    console.log(`reason: ${report.nextCommandReason}`);
 }

package/dist/commands/summarize.js

@@ -12,6 +12,10 @@ const git_1 = require("../utils/git");
 const hashing_1 = require("../utils/hashing");
 const llm_1 = require("../utils/llm");
 const paths_1 = require("../utils/paths");
+const SCHEMA_BASE_URL = "https://raw.githubusercontent.com/sullyTheDev/diffdoc";
+const PKG_VERSION = require("../../package.json").version;
+const MANIFEST_SCHEMA_URL = `${SCHEMA_BASE_URL}/v${PKG_VERSION}/schemas/manifest.schema.json`;
+const SUMMARY_ASSET_SCHEMA_URL = `${SCHEMA_BASE_URL}/v${PKG_VERSION}/schemas/summary-asset.schema.json`;
 function normalizeRelativePath(filePath) {
     return filePath.split(node_path_1.default.sep).join("/");
 }
@@ -71,15 +75,6 @@ function shouldIncludeFile(filePath, includeGlobs, excludeGlobs, ignoreMatcher)
 function isIgnoredDirectory(dirPath, ignoreMatcher) {
     return ignoreMatcher.ignores(dirPath) || ignoreMatcher.ignores(`${dirPath}/`);
 }
-async function fileExists(filePath) {
-    try {
-        await promises_1.default.access(filePath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 async function atomicWriteUtf8(targetPath, content) {
     await promises_1.default.mkdir(node_path_1.default.dirname(targetPath), { recursive: true });
     const tempPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
@@ -99,22 +94,87 @@ async function writeManifest(manifestPath, manifest) {
 async function writeSummaryAsset(summaryPath, summary) {
     await atomicWriteUtf8(summaryPath, `${JSON.stringify(summary, null, 2)}\n`);
 }
+function getPromptHash(config) {
+    return config.summarize.resolvedSummaryPrompt
+        ? (0, hashing_1.hashTextContent)(config.summarize.resolvedSummaryPrompt)
+        : undefined;
+}
+function buildSummaryMetadata(params) {
+    return {
+        file_path: params.filePath,
+        file_name: node_path_1.default.basename(params.filePath),
+        extension: node_path_1.default.extname(params.filePath),
+        line_count: params.rawCodeSnapshot.length === 0 ? 0 : params.rawCodeSnapshot.split(/\r\n|\r|\n/).length,
+        byte_size: Buffer.byteLength(params.rawCodeSnapshot, "utf8"),
+        content_hash: params.hash,
+        generated_at: params.generatedAt,
+        generator: {
+            provider: params.config.provider,
+            model: params.config.chat.model
+        },
+        prompt_version: llm_1.SUMMARY_PROMPT_VERSION,
+        summary_format: llm_1.SUMMARY_FORMAT,
+        custom_prompt_hash: params.customPromptHash,
+        custom_prompt_source: params.customPromptSource
+    };
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function hasExpectedCustomPromptHash(metadata, customPromptHash) {
+    const actual = typeof metadata.custom_prompt_hash === "string" ? metadata.custom_prompt_hash : undefined;
+    return actual === customPromptHash;
+}
+async function isSummaryAssetFresh(summaryPath, expected) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await promises_1.default.readFile(summaryPath, "utf8"));
+    }
+    catch {
+        return false;
+    }
+    if (!isRecord(parsed)) {
+        return false;
+    }
+    if (parsed.schemaVersion !== artifacts_1.SUMMARY_ASSET_SCHEMA_VERSION || parsed.content_hash !== expected.hash) {
+        return false;
+    }
+    if (expected.includeCodeSnapshot !== (typeof parsed.raw_code_snapshot === "string")) {
+        return false;
+    }
+    if (!isRecord(parsed.metadata)) {
+        return false;
+    }
+    const metadata = parsed.metadata;
+    if (metadata.content_hash !== expected.hash) {
+        return false;
+    }
+    if (metadata.prompt_version !== expected.promptVersion || metadata.summary_format !== expected.summaryFormat) {
+        return false;
+    }
+    if (!hasExpectedCustomPromptHash(metadata, expected.customPromptHash)) {
+        return false;
+    }
+    if (!isRecord(metadata.generator)) {
+        return false;
+    }
+    return metadata.generator.provider === expected.provider && metadata.generator.model === expected.model;
+}
 async function readManifest(manifestPath) {
     try {
-        const parsed = JSON.parse(await promises_1.default.readFile(manifestPath, "utf8"));
-        if (parsed.schemaVersion !== artifacts_1.MANIFEST_SCHEMA_VERSION) {
-            throw new Error(`Unsupported manifest schema in ${manifestPath}. Expected schemaVersion ${artifacts_1.MANIFEST_SCHEMA_VERSION}.`);
+        const raw = JSON.parse(await promises_1.default.readFile(manifestPath, "utf8"));
+        const result = artifacts_1.RepoManifestSchema.safeParse(raw);
+        if (!result.success) {
+            const issues = result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
+            throw new Error(`Invalid manifest in ${manifestPath}:\n${issues}`);
         }
-        return {
-            schemaVersion: artifacts_1.MANIFEST_SCHEMA_VERSION,
-            lastSyncedCommit: typeof parsed.lastSyncedCommit === "string" ? parsed.lastSyncedCommit : "",
-            files: parsed.files && typeof parsed.files === "object" ? parsed.files : {}
-        };
+        return result.data;
     }
     catch (error) {
         const nodeError = error;
         if (nodeError.code === "ENOENT") {
             return {
+                $schema: MANIFEST_SCHEMA_URL,
                 schemaVersion: artifacts_1.MANIFEST_SCHEMA_VERSION,
                 lastSyncedCommit: "",
                 files: {}
@@ -210,14 +270,13 @@ async function removeManifestPath(filePath, manifest, manifestPath, summaryDir,
     await deleteSummaryIfUnreferenced(summaryDir, previousHash, refs);
     return true;
 }
-async function ensureSummaryAsset(summaryDir, hash, summaryText, rawCodeSnapshot, includeCodeSnapshot) {
+async function ensureSummaryAsset(summaryDir, hash, metadata, summaryText, rawCodeSnapshot, includeCodeSnapshot) {
     const summaryPath = getSummaryPath(summaryDir, hash);
-    if (await fileExists(summaryPath)) {
-        return;
-    }
     const summary = {
+        $schema: SUMMARY_ASSET_SCHEMA_URL,
         schemaVersion: artifacts_1.SUMMARY_ASSET_SCHEMA_VERSION,
         content_hash: hash,
+        metadata,
         summary: summaryText,
         raw_code_snapshot: includeCodeSnapshot ? rawCodeSnapshot : undefined
     };
@@ -285,7 +344,18 @@ async function runSummarize(options, config) {
         : config.summarize.excludeGlobs.map(normalizeGlobPattern));
     const ignoreFile = options.ignoreFile || config.summarize.ignoreFile;
     const ignoreMatcher = await readIgnoreMatcher(repoPath, ignoreFile);
-    const totals = { scanned: 0, skipped: 0, updated: 0, failed: 0, pruned: 0 };
+    const customPromptHash = getPromptHash(config);
+    const customPromptSource = customPromptHash ? config.summarize.summaryPromptSource : undefined;
+    const summaryFreshnessExpected = (hash) => ({
+        hash,
+        promptVersion: llm_1.SUMMARY_PROMPT_VERSION,
+        summaryFormat: llm_1.SUMMARY_FORMAT,
+        customPromptHash,
+        provider: config.provider,
+        model: config.chat.model,
+        includeCodeSnapshot: options.includeCodeSnapshot
+    });
+    const totals = { scanned: 0, skipped: 0, updated: 0, refreshed: 0, failed: 0, pruned: 0 };
     const failures = [];
     const isJson = options.json;
     const concurrency = config.summarize.concurrency;
@@ -293,20 +363,31 @@ async function runSummarize(options, config) {
     const summaryAssetTasks = new Map();
     async function ensureSummaryAssetForFile(filePath, hash, rawCodeSnapshot) {
         const summaryPath = getSummaryPath(summaryDir, hash);
-        if (await fileExists(summaryPath)) {
-            return;
+        if (!options.refresh && await isSummaryAssetFresh(summaryPath, summaryFreshnessExpected(hash))) {
+            return false;
         }
         let task = summaryAssetTasks.get(hash);
         if (!task) {
             task = (async () => {
-                const summaryText = await (0, llm_1.generateFunctionalSummary)(filePath, rawCodeSnapshot, config.chat);
-                await ensureSummaryAsset(summaryDir, hash, summaryText, rawCodeSnapshot, options.includeCodeSnapshot);
+                const generatedAt = new Date().toISOString();
+                const metadata = buildSummaryMetadata({
+                    filePath,
+                    hash,
+                    rawCodeSnapshot,
+                    config,
+                    generatedAt,
+                    customPromptHash,
+                    customPromptSource
+                });
+                const summaryText = await (0, llm_1.generateFunctionalSummary)(filePath, rawCodeSnapshot, metadata, config.chat, config.summarize.resolvedSummaryPrompt);
+                await ensureSummaryAsset(summaryDir, hash, metadata, summaryText, rawCodeSnapshot, options.includeCodeSnapshot);
+                return true;
             })().finally(() => {
                 summaryAssetTasks.delete(hash);
             });
             summaryAssetTasks.set(hash, task);
         }
-        await task;
+        return task;
     }
     if (!isJson) {
         console.log(`Starting summarize run`);
@@ -403,11 +484,17 @@ async function runSummarize(options, config) {
                 const rawCodeSnapshot = await promises_1.default.readFile(absolutePath, "utf8");
                 const hash = (0, hashing_1.hashFileContent)(rawCodeSnapshot);
                 if (previousHash === hash) {
+                    const regenerated = await ensureSummaryAssetForFile(filePath, hash, rawCodeSnapshot);
                     await withManifestLock(async () => {
-                        totals.skipped += 1;
+                        if (regenerated) {
+                            totals.refreshed += 1;
+                        }
+                        else {
+                            totals.skipped += 1;
+                        }
                         completedModified += 1;
                         if (!isJson) {
-                            console.log(`[${completedModified}/${deltas.modifiedOrAdded.length}] unchanged ${filePath}`);
+                            console.log(`[${completedModified}/${deltas.modifiedOrAdded.length}] ${regenerated ? "refreshed" : "unchanged"} ${filePath}`);
                         }
                     });
                     return;
@@ -481,6 +568,7 @@ async function runSummarize(options, config) {
         console.log(`Summarize complete`);
         console.log(`Scanned: ${totals.scanned}`);
         console.log(`Updated: ${totals.updated}`);
+        console.log(`Refreshed: ${totals.refreshed}`);
         console.log(`Skipped: ${totals.skipped}`);
         console.log(`Pruned: ${totals.pruned}`);
         console.log(`Failed: ${totals.failed}`);

package/dist/commands/validate.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runValidate = runValidate;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const artifacts_1 = require("../types/artifacts");
+const paths_1 = require("../utils/paths");
+function getSummaryDir(manifestPath) {
+    return node_path_1.default.resolve(node_path_1.default.dirname(manifestPath), "summaries");
+}
+async function runValidate(options, config) {
+    const manifestPath = (0, paths_1.resolveDiffdocArtifactPath)(options.manifest, config.baseDir);
+    const issues = [];
+    let manifestValid = false;
+    let summaryAssetsChecked = 0;
+    let summaryAssetsValid = 0;
+    // Validate manifest
+    let manifestData;
+    try {
+        manifestData = JSON.parse(await promises_1.default.readFile(manifestPath, "utf8"));
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === "ENOENT") {
+            issues.push({ file: manifestPath, path: "", message: "Manifest file not found." });
+        }
+        else {
+            issues.push({ file: manifestPath, path: "", message: `Failed to parse JSON: ${error.message}` });
+        }
+        manifestData = undefined;
+    }
+    if (manifestData !== undefined) {
+        const result = artifacts_1.RepoManifestSchema.safeParse(manifestData);
+        if (result.success) {
+            manifestValid = true;
+            // Validate each referenced summary asset
+            const summaryDir = getSummaryDir(manifestPath);
+            const hashes = new Set(Object.values(result.data.files));
+            for (const hash of hashes) {
+                summaryAssetsChecked += 1;
+                const summaryPath = node_path_1.default.resolve(summaryDir, `${hash}.json`);
+                let summaryRaw;
+                try {
+                    summaryRaw = JSON.parse(await promises_1.default.readFile(summaryPath, "utf8"));
+                }
+                catch (error) {
+                    const nodeError = error;
+                    if (nodeError.code === "ENOENT") {
+                        issues.push({ file: summaryPath, path: "", message: "Summary asset file not found." });
+                    }
+                    else {
+                        issues.push({ file: summaryPath, path: "", message: `Failed to parse JSON: ${error.message}` });
+                    }
+                    continue;
+                }
+                const assetResult = artifacts_1.SummaryAssetSchema.safeParse(summaryRaw);
+                if (assetResult.success) {
+                    // Cross-check content_hash matches filename
+                    if (assetResult.data.content_hash !== hash) {
+                        issues.push({ file: summaryPath, path: "content_hash", message: `Expected "${hash}" but got "${assetResult.data.content_hash}".` });
+                    }
+                    else {
+                        summaryAssetsValid += 1;
+                    }
+                }
+                else {
+                    for (const issue of assetResult.error.issues) {
+                        issues.push({ file: summaryPath, path: issue.path.join("."), message: issue.message });
+                    }
+                }
+            }
+        }
+        else {
+            for (const issue of result.error.issues) {
+                issues.push({ file: manifestPath, path: issue.path.join("."), message: issue.message });
+            }
+        }
+    }
+    const report = {
+        valid: manifestValid && issues.length === 0,
+        manifestPath,
+        manifestValid,
+        summaryAssetsChecked,
+        summaryAssetsValid,
+        issues
+    };
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(`Manifest: ${manifestPath}`);
+        console.log(`Manifest valid: ${manifestValid ? "yes" : "NO"}`);
+        console.log(`Summary assets checked: ${summaryAssetsChecked}`);
+        console.log(`Summary assets valid: ${summaryAssetsValid}`);
+        console.log("---");
+        if (issues.length === 0) {
+            console.log("All artifacts pass schema validation.");
+        }
+        else {
+            console.log(`Issues (${issues.length}):`);
+            for (const issue of issues) {
+                const location = issue.path ? `${issue.file} -> ${issue.path}` : issue.file;
+                console.log(`  - ${location}: ${issue.message}`);
+            }
+        }
+    }
+    if (!report.valid) {
+        process.exitCode = 1;
+    }
+}

package/dist/config.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildRuntimeConfig = buildRuntimeConfig;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const schemas_1 = require("./schemas");
 function readOption(value, envName, fallback = "") {
     return value || process.env[envName] || fallback;
 }
@@ -36,6 +37,14 @@ function readPositiveIntegerOption(value, envName, fallback) {
     }
     return parsed;
 }
+function readPromptOption(value, envName) {
+    const option = value ?? process.env[envName];
+    return option && option.trim() ? option : undefined;
+}
+function resolvePromptFile(promptFile) {
+    const resolvedPath = node_path_1.default.resolve(process.cwd(), promptFile);
+    return node_fs_1.default.readFileSync(resolvedPath, "utf8");
+}
 function loadRcFile(configPath) {
     const resolvedPath = node_path_1.default.resolve(process.cwd(), configPath || ".diffdocrc");
     if (!node_fs_1.default.existsSync(resolvedPath)) {
@@ -48,7 +57,12 @@ function loadRcFile(configPath) {
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         throw new Error(`Config file must contain a JSON object: ${resolvedPath}`);
     }
-    return parsed;
+    const result = schemas_1.DiffdocConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
+        throw new Error(`Invalid config file ${resolvedPath}:\n${issues}`);
+    }
+    return result.data;
 }
 function mergeConfigOptions(options) {
     const rcOptions = loadRcFile(options.config);
@@ -73,6 +87,13 @@ function buildRuntimeConfig(options, needs = { chat: true, embeddings: true }) {
     const excludeGlobs = readListOption(mergedOptions.excludeGlobs, "DIFFDOC_EXCLUDE_GLOBS");
     const ignoreFile = readOption(mergedOptions.ignoreFile, "DIFFDOC_IGNORE_FILE", ".diffdocignore");
     const summarizeConcurrency = readPositiveIntegerOption(mergedOptions.summarizeConcurrency, "DIFFDOC_SUMMARIZE_CONCURRENCY", 2);
+    const summaryPrompt = readPromptOption(mergedOptions.summaryPrompt, "DIFFDOC_SUMMARY_PROMPT");
+    const summaryPromptFile = readPromptOption(mergedOptions.summaryPromptFile, "DIFFDOC_SUMMARY_PROMPT_FILE");
+    if (summaryPrompt && summaryPromptFile) {
+        throw new Error("Configure either summaryPrompt or summaryPromptFile, not both.");
+    }
+    const resolvedSummaryPrompt = summaryPromptFile ? resolvePromptFile(summaryPromptFile) : summaryPrompt;
+    const summaryPromptSource = summaryPromptFile ? summaryPromptFile : summaryPrompt ? "inline" : undefined;
     const chatBaseURL = provider === "cloud"
         ? readOption(mergedOptions.cloudLlmEndpoint, "CLOUD_LLM_ENDPOINT", "https://api.openai.com/v1")
         : readOption(mergedOptions.localLlmEndpoint, "LOCAL_LLM_ENDPOINT");
@@ -118,7 +139,11 @@ function buildRuntimeConfig(options, needs = { chat: true, embeddings: true }) {
             includeGlobs,
             excludeGlobs,
             ignoreFile,
-            concurrency: summarizeConcurrency
+            concurrency: summarizeConcurrency,
+            summaryPrompt,
+            summaryPromptFile,
+            resolvedSummaryPrompt,
+            summaryPromptSource
         }
     };
 }

package/dist/index.js

@@ -8,6 +8,7 @@ const init_1 = require("./commands/init");
 const query_1 = require("./commands/query");
 const status_1 = require("./commands/status");
 const summarize_1 = require("./commands/summarize");
+const validate_1 = require("./commands/validate");
 const program = new commander_1.Command();
 function collectOption(value, previous) {
     previous.push(value);
@@ -42,7 +43,7 @@ function addCloudEndpointAndKeyOptions(command) {
 program
     .name("diffdoc")
     .description("Translate repository code shifts into plain-English business context")
-    .version("0.5.0");
+    .version("0.6.0");
 program
     .command("init")
     .description("Initialize DiffDoc configuration for this repository")
@@ -72,6 +73,9 @@ addChatOptions(addBaseOptions(program
     .option("--exclude-glob <pattern>", "exclude glob pattern (repeatable)", collectOption, [])
     .option("--ignore-file <path>", "path to ignore pattern file relative to --path")
     .option("--summarize-concurrency <count>", "number of files to summarize concurrently")
+    .option("--summary-prompt <text>", "additional instructions for summary generation")
+    .option("--summary-prompt-file <path>", "path to additional summary prompt instructions")
+    .option("--refresh", "regenerate summaries even when source and summary metadata are fresh", false)
     .action(async (options) => {
     try {
         const config = (0, config_1.buildRuntimeConfig)(options, { chat: true });
@@ -83,7 +87,8 @@ addChatOptions(addBaseOptions(program
             json: options.json,
             includeGlobs: options.includeGlob,
             excludeGlobs: options.excludeGlob,
-            ignoreFile: options.ignoreFile
+            ignoreFile: options.ignoreFile,
+            refresh: options.refresh
         }, config);
     }
     catch (error) {
@@ -153,6 +158,21 @@ addBaseOptions(program
         process.exit(1);
     }
 });
+addBaseOptions(program
+    .command("validate"))
+    .description("Validate manifest and summary assets against JSON schemas")
+    .option("--manifest <path>", "manifest input path under --base-dir", "manifest.json")
+    .option("--json", "print validation report as JSON for CI", false)
+    .action(async (options) => {
+    try {
+        const config = (0, config_1.buildRuntimeConfig)(options, { embeddings: false, chat: false });
+        await (0, validate_1.runValidate)({ manifest: options.manifest, json: options.json }, config);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 program.parseAsync(process.argv).catch((error) => {
     console.error(error instanceof Error ? error.message : error);
     process.exit(1);

package/dist/schemas.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SummaryAssetSchema = exports.SummaryMetadataSchema = exports.RepoManifestSchema = exports.DiffdocConfigSchema = exports.SUMMARY_ASSET_SCHEMA_VERSION = exports.MANIFEST_SCHEMA_VERSION = void 0;
+const zod_1 = require("zod");
+// ---------------------------------------------------------------------------
+// Schema version constants
+// ---------------------------------------------------------------------------
+exports.MANIFEST_SCHEMA_VERSION = 2;
+exports.SUMMARY_ASSET_SCHEMA_VERSION = 2;
+// ---------------------------------------------------------------------------
+// Configuration schema (.diffdocrc)
+// ---------------------------------------------------------------------------
+exports.DiffdocConfigSchema = zod_1.z.object({
+    baseDir: zod_1.z.string().optional(),
+    aiProvider: zod_1.z.enum(["local", "cloud"]).optional(),
+    localLlmEndpoint: zod_1.z.string().optional(),
+    localEmbedEndpoint: zod_1.z.string().optional(),
+    localChatModel: zod_1.z.string().optional(),
+    localEmbedModel: zod_1.z.string().optional(),
+    cloudLlmEndpoint: zod_1.z.string().optional(),
+    cloudChatModel: zod_1.z.string().optional(),
+    cloudEmbedModel: zod_1.z.string().optional(),
+    embedBatchSize: zod_1.z.union([zod_1.z.number().int().positive(), zod_1.z.string()]).optional(),
+    summarizeConcurrency: zod_1.z.union([zod_1.z.number().int().positive(), zod_1.z.string()]).optional(),
+    openaiApiKey: zod_1.z.string().optional(),
+    includeGlobs: zod_1.z.union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()]).optional(),
+    excludeGlobs: zod_1.z.union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()]).optional(),
+    ignoreFile: zod_1.z.string().optional(),
+    summaryPrompt: zod_1.z.string().optional(),
+    summaryPromptFile: zod_1.z.string().optional()
+}).strict();
+// ---------------------------------------------------------------------------
+// Repository manifest schema
+// ---------------------------------------------------------------------------
+exports.RepoManifestSchema = zod_1.z.object({
+    $schema: zod_1.z.string().optional(),
+    schemaVersion: zod_1.z.literal(exports.MANIFEST_SCHEMA_VERSION),
+    lastSyncedCommit: zod_1.z.string(),
+    files: zod_1.z.record(zod_1.z.string(), zod_1.z.string())
+});
+// ---------------------------------------------------------------------------
+// Summary metadata schema (nested within summary assets)
+// ---------------------------------------------------------------------------
+exports.SummaryMetadataSchema = zod_1.z.object({
+    file_path: zod_1.z.string(),
+    file_name: zod_1.z.string(),
+    extension: zod_1.z.string(),
+    line_count: zod_1.z.number().int().nonnegative(),
+    byte_size: zod_1.z.number().int().nonnegative(),
+    content_hash: zod_1.z.string(),
+    generated_at: zod_1.z.string(),
+    generator: zod_1.z.object({
+        provider: zod_1.z.string(),
+        model: zod_1.z.string()
+    }),
+    prompt_version: zod_1.z.number().int(),
+    summary_format: zod_1.z.string(),
+    custom_prompt_hash: zod_1.z.string().optional(),
+    custom_prompt_source: zod_1.z.string().optional()
+});
+// ---------------------------------------------------------------------------
+// Summary asset schema (individual hash-named JSON files)
+// ---------------------------------------------------------------------------
+exports.SummaryAssetSchema = zod_1.z.object({
+    $schema: zod_1.z.string().optional(),
+    schemaVersion: zod_1.z.literal(exports.SUMMARY_ASSET_SCHEMA_VERSION),
+    content_hash: zod_1.z.string(),
+    metadata: exports.SummaryMetadataSchema.optional(),
+    summary: zod_1.z.string(),
+    raw_code_snapshot: zod_1.z.string().optional()
+});

package/dist/scripts/generate-schemas.js

@@ -0,0 +1,32 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const schemas_1 = require("../schemas");
+const SCHEMA_BASE_URL = "https://raw.githubusercontent.com/sullyTheDev/diffdoc";
+const VERSION = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.resolve(__dirname, "../../package.json"), "utf8")).version;
+const schemas = [
+    { name: "diffdocrc.schema.json", zodSchema: schemas_1.DiffdocConfigSchema },
+    { name: "manifest.schema.json", zodSchema: schemas_1.RepoManifestSchema },
+    { name: "summary-asset.schema.json", zodSchema: schemas_1.SummaryAssetSchema }
+];
+const outDir = node_path_1.default.resolve(__dirname, "../../schemas");
+node_fs_1.default.mkdirSync(outDir, { recursive: true });
+for (const entry of schemas) {
+    const jsonSchema = (0, zod_to_json_schema_1.zodToJsonSchema)(entry.zodSchema, {
+        name: entry.name.replace(".schema.json", ""),
+        $refStrategy: "none"
+    });
+    const schemaWithId = {
+        ...jsonSchema,
+        $id: `${SCHEMA_BASE_URL}/v${VERSION}/schemas/${entry.name}`
+    };
+    const outPath = node_path_1.default.resolve(outDir, entry.name);
+    node_fs_1.default.writeFileSync(outPath, `${JSON.stringify(schemaWithId, null, 2)}\n`);
+    console.log(`Generated: ${outPath}`);
+}
+console.log("Schema generation complete.");

package/dist/types/artifacts.js

@@ -1,5 +1,12 @@
 "use strict";
+// Re-export all schema definitions and types from the canonical source.
+// This file exists for backwards-compatible import paths.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUMMARY_ASSET_SCHEMA_VERSION = exports.MANIFEST_SCHEMA_VERSION = void 0;
-exports.MANIFEST_SCHEMA_VERSION = 2;
-exports.SUMMARY_ASSET_SCHEMA_VERSION = 1;
+exports.DiffdocConfigSchema = exports.SummaryAssetSchema = exports.SummaryMetadataSchema = exports.RepoManifestSchema = exports.SUMMARY_ASSET_SCHEMA_VERSION = exports.MANIFEST_SCHEMA_VERSION = void 0;
+var schemas_1 = require("../schemas");
+Object.defineProperty(exports, "MANIFEST_SCHEMA_VERSION", { enumerable: true, get: function () { return schemas_1.MANIFEST_SCHEMA_VERSION; } });
+Object.defineProperty(exports, "SUMMARY_ASSET_SCHEMA_VERSION", { enumerable: true, get: function () { return schemas_1.SUMMARY_ASSET_SCHEMA_VERSION; } });
+Object.defineProperty(exports, "RepoManifestSchema", { enumerable: true, get: function () { return schemas_1.RepoManifestSchema; } });
+Object.defineProperty(exports, "SummaryMetadataSchema", { enumerable: true, get: function () { return schemas_1.SummaryMetadataSchema; } });
+Object.defineProperty(exports, "SummaryAssetSchema", { enumerable: true, get: function () { return schemas_1.SummaryAssetSchema; } });
+Object.defineProperty(exports, "DiffdocConfigSchema", { enumerable: true, get: function () { return schemas_1.DiffdocConfigSchema; } });

package/dist/utils/hashing.js

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hashFileContent = hashFileContent;
+exports.hashTextContent = hashTextContent;
 const node_crypto_1 = require("node:crypto");
 function hashFileContent(fileContent) {
     return (0, node_crypto_1.createHash)("md5").update(fileContent, "utf8").digest("hex");
 }
+function hashTextContent(textContent) {
+    return (0, node_crypto_1.createHash)("sha256").update(textContent, "utf8").digest("hex");
+}

package/dist/utils/llm.js

@@ -3,17 +3,108 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUMMARY_FORMAT = exports.SUMMARY_PROMPT_VERSION = void 0;
 exports.generateFunctionalSummary = generateFunctionalSummary;
 exports.generateAnswer = generateAnswer;
 exports.generateEmbeddings = generateEmbeddings;
 const openai_1 = __importDefault(require("openai"));
+exports.SUMMARY_PROMPT_VERSION = 1;
+exports.SUMMARY_FORMAT = "structured-functional-v1";
+const SUMMARY_SYSTEM_PROMPT = `Generate a structured DiffDoc functional summary for the provided source file.
+
+Required headings, exactly once and in this order:
+## Metadata
+## Purpose
+## User-Visible Behavior
+## Business Rules
+## Data Inputs And Outputs
+## Side Effects
+## Error And Edge Cases
+## Dependencies
+## Operational Notes
+
+Section guidance:
+
+## Metadata
+Include file-level context useful for search and retrieval. This section is mandatory and must contain every bullet below exactly once, in this order:
+- File path: {copy the provided file path exactly}
+- File name: {copy the provided file name exactly}
+- Extension: {copy the provided extension exactly}
+- Inferred language/type: {infer from file path, file name, extension, and code content}
+- Content hash: {copy the provided content hash exactly}
+- Line count: {copy the provided line count exactly}
+- Byte size: {copy the provided byte size exactly}
+- Summary format: {copy the provided summary format exactly}
+- Notable symbols/classes/functions: {infer from code, or write "None identified."}
+- External dependencies: {infer from imports, packages, runtime services, external APIs, or write "None identified."}
+- Internal dependencies: {infer from project imports, local modules, local artifacts, or write "None identified."}
+- Public API/exports: {infer exported functions, classes, types, routes, commands, tools, or write "None identified."}
+
+## Purpose
+Explain why this file exists and the main responsibility it serves.
+Examples: handles login requests, builds a vector index, loads runtime configuration.
+
+## User-Visible Behavior
+Describe behavior users, operators, developers, or API consumers would observe.
+Examples: CLI output, API responses, UI behavior, created/updated/deleted files, validation errors.
+
+## Business Rules
+Describe implemented rules, constraints, decisions, and policy-like behavior.
+Examples: required fields, valid modes, filtering precedence, defaults, validation rules, skip conditions.
+
+## Data Inputs And Outputs
+Describe what data enters and leaves this file's behavior.
+Examples: input files, config values, environment variables, function arguments, API payloads, generated artifacts, return values.
+
+## Side Effects
+Describe changes caused outside local computation.
+Examples: writes files, deletes files, calls external services, updates indexes, logs output, mutates shared state, sends network requests.
+
+## Error And Edge Cases
+Describe failure handling and unusual conditions.
+Examples: missing files, invalid config, unsupported schemas, empty results, network/model failures, deleted or unchanged files.
+
+## Dependencies
+Describe important internal and external dependencies.
+Examples: imported packages, runtime services, local artifacts, external APIs, models/providers, framework components, project files.
+
+## Operational Notes
+Describe details useful for running, maintaining, scaling, or debugging.
+Examples: concurrency, performance, idempotency, caching/reuse, schema implications, regeneration requirements, security/privacy considerations.
+
+Rules:
+- Use every heading exactly once.
+- Use headings in the required order.
+- Start with ## Metadata.
+- Include provided deterministic metadata values exactly.
+- Do not rename, omit, reorder, or merge Metadata bullets.
+- Infer the language/type from the provided file path, file name, extension, and code content. Prefer code content when extension is ambiguous. If uncertain, provide the best likely language/type and briefly note uncertainty.
+- Let the code identify symbols, classes, functions, and dependencies. Include important identifiers when useful for search.
+- If a section has no applicable content, write "None identified."
+- Do not invent behavior, requirements, dependencies, or intent not supported by the code.
+- Summarize implemented behavior only.
+- Prefer specific behavior over generic descriptions.
+- Use plain English.
+- Provide zero conversational preamble.
+- Do not include Markdown sections outside the required headings.`;
 function createClient(config) {
     return {
         client: new openai_1.default({ apiKey: config.apiKey, baseURL: config.baseURL }),
         model: config.model
     };
 }
-async function generateFunctionalSummary(fileName, codeContent, config) {
+function formatMetadataForPrompt(metadata) {
+    return [
+        `- File path: ${metadata.file_path}`,
+        `- File name: ${metadata.file_name}`,
+        `- Extension: ${metadata.extension || "None"}`,
+        `- Content hash: ${metadata.content_hash}`,
+        `- Line count: ${metadata.line_count}`,
+        `- Byte size: ${metadata.byte_size}`,
+        `- Summary format: ${metadata.summary_format}`
+    ].join("\n");
+}
+async function generateFunctionalSummary(fileName, codeContent, metadata, config, customPrompt) {
     const { client, model } = createClient(config);
     const response = await client.chat.completions.create({
         model,
@@ -21,11 +112,11 @@ async function generateFunctionalSummary(fileName, codeContent, config) {
         messages: [
             {
                 role: "system",
-                content: "Explain what this code does for non-technical stakeholders. Focus on business behavior, user impact, rules, data movement, and visible outcomes. Use plain English, avoid jargon, and provide zero conversational preamble."
+                content: SUMMARY_SYSTEM_PROMPT
             },
             {
                 role: "user",
-                content: `File: ${fileName}\n\nCode:\n${codeContent}`
+                content: `File: ${fileName}\n\nProvided metadata:\n${formatMetadataForPrompt(metadata)}\n\nConsumer instructions:\n${customPrompt && customPrompt.trim() ? customPrompt.trim() : "None."}\n\nCode:\n${codeContent}`
             }
         ]
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffdoc",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Translate repository code shifts into plain-English business context",
   "license": "MIT",
   "author": "Christopher Sullivan",
@@ -20,6 +20,7 @@
   },
   "files": [
     "dist",
+    "schemas",
     "README.md",
     "LICENSE",
     ".diffdocrc.example"
@@ -28,7 +29,8 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node dist/scripts/generate-schemas.js",
+    "generate:schemas": "node dist/scripts/generate-schemas.js",
     "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
     "start": "tsc && node ./dist/index.js",
     "prepare": "npm run build"
@@ -44,6 +46,7 @@
   },
   "devDependencies": {
     "@types/node": "^20.19.41",
-    "typescript": "^5.3.3"
+    "typescript": "^5.3.3",
+    "zod-to-json-schema": "^3.25.2"
   }
 }

package/schemas/diffdocrc.schema.json

@@ -0,0 +1,104 @@
+{
+  "$ref": "#/definitions/diffdocrc",
+  "definitions": {
+    "diffdocrc": {
+      "type": "object",
+      "properties": {
+        "baseDir": {
+          "type": "string"
+        },
+        "aiProvider": {
+          "type": "string",
+          "enum": [
+            "local",
+            "cloud"
+          ]
+        },
+        "localLlmEndpoint": {
+          "type": "string"
+        },
+        "localEmbedEndpoint": {
+          "type": "string"
+        },
+        "localChatModel": {
+          "type": "string"
+        },
+        "localEmbedModel": {
+          "type": "string"
+        },
+        "cloudLlmEndpoint": {
+          "type": "string"
+        },
+        "cloudChatModel": {
+          "type": "string"
+        },
+        "cloudEmbedModel": {
+          "type": "string"
+        },
+        "embedBatchSize": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            },
+            {
+              "type": "string"
+            }
+          ]
+        },
+        "summarizeConcurrency": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            },
+            {
+              "type": "string"
+            }
+          ]
+        },
+        "openaiApiKey": {
+          "type": "string"
+        },
+        "includeGlobs": {
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            {
+              "type": "string"
+            }
+          ]
+        },
+        "excludeGlobs": {
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            {
+              "type": "string"
+            }
+          ]
+        },
+        "ignoreFile": {
+          "type": "string"
+        },
+        "summaryPrompt": {
+          "type": "string"
+        },
+        "summaryPromptFile": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/sullyTheDev/diffdoc/v0.6.1/schemas/diffdocrc.schema.json"
+}

package/schemas/manifest.schema.json

@@ -0,0 +1,34 @@
+{
+  "$ref": "#/definitions/manifest",
+  "definitions": {
+    "manifest": {
+      "type": "object",
+      "properties": {
+        "$schema": {
+          "type": "string"
+        },
+        "schemaVersion": {
+          "type": "number",
+          "const": 2
+        },
+        "lastSyncedCommit": {
+          "type": "string"
+        },
+        "files": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      },
+      "required": [
+        "schemaVersion",
+        "lastSyncedCommit",
+        "files"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/sullyTheDev/diffdoc/v0.6.1/schemas/manifest.schema.json"
+}

package/schemas/summary-asset.schema.json

@@ -0,0 +1,103 @@
+{
+  "$ref": "#/definitions/summary-asset",
+  "definitions": {
+    "summary-asset": {
+      "type": "object",
+      "properties": {
+        "$schema": {
+          "type": "string"
+        },
+        "schemaVersion": {
+          "type": "number",
+          "const": 2
+        },
+        "content_hash": {
+          "type": "string"
+        },
+        "metadata": {
+          "type": "object",
+          "properties": {
+            "file_path": {
+              "type": "string"
+            },
+            "file_name": {
+              "type": "string"
+            },
+            "extension": {
+              "type": "string"
+            },
+            "line_count": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "byte_size": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "content_hash": {
+              "type": "string"
+            },
+            "generated_at": {
+              "type": "string"
+            },
+            "generator": {
+              "type": "object",
+              "properties": {
+                "provider": {
+                  "type": "string"
+                },
+                "model": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "provider",
+                "model"
+              ],
+              "additionalProperties": false
+            },
+            "prompt_version": {
+              "type": "integer"
+            },
+            "summary_format": {
+              "type": "string"
+            },
+            "custom_prompt_hash": {
+              "type": "string"
+            },
+            "custom_prompt_source": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "file_path",
+            "file_name",
+            "extension",
+            "line_count",
+            "byte_size",
+            "content_hash",
+            "generated_at",
+            "generator",
+            "prompt_version",
+            "summary_format"
+          ],
+          "additionalProperties": false
+        },
+        "summary": {
+          "type": "string"
+        },
+        "raw_code_snapshot": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "schemaVersion",
+        "content_hash",
+        "summary"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/sullyTheDev/diffdoc/v0.6.1/schemas/summary-asset.schema.json"
+}