diffdoc 0.5.0 → 0.6.0

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

@@ -34,8 +34,8 @@ async function readManifest(manifestPath) {
 }
 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}.`);
+    if (typeof parsed.schemaVersion !== "number" || parsed.schemaVersion < 1 || parsed.schemaVersion > artifacts_1.SUMMARY_ASSET_SCHEMA_VERSION) {
+        throw new Error(`Unsupported summary schema in ${summaryPath}. Expected schemaVersion 1-${artifacts_1.SUMMARY_ASSET_SCHEMA_VERSION}.`);
     }
     if (typeof parsed.content_hash !== "string") {
         throw new Error(`Invalid summary hash in ${summaryPath}.`);
@@ -44,14 +44,15 @@ async function readSummaryAsset(summaryPath) {
         throw new Error(`Invalid summary text in ${summaryPath}.`);
     }
     return {
-        schemaVersion: artifacts_1.SUMMARY_ASSET_SCHEMA_VERSION,
+        schemaVersion: parsed.schemaVersion,
         content_hash: parsed.content_hash,
+        metadata: parsed.metadata && typeof parsed.metadata === "object" ? parsed.metadata : undefined,
         summary: parsed.summary,
         raw_code_snapshot: typeof parsed.raw_code_snapshot === "string" ? parsed.raw_code_snapshot : undefined
     };
 }
-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 +97,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/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");
 }
@@ -64,10 +65,37 @@ async function getSummaryStats(manifestPath, manifest) {
             missingFromManifestCount += 1;
         }
     }
+    let staleCount = 0;
+    for (const hash of manifestHashes) {
+        if (!summaryHashes.has(hash)) {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(await promises_1.default.readFile(node_path_1.default.resolve(summaryDir, `${hash}.json`), "utf8"));
+            const metadata = parsed.metadata && typeof parsed.metadata === "object" && !Array.isArray(parsed.metadata)
+                ? parsed.metadata
+                : undefined;
+            if (parsed.schemaVersion !== artifacts_1.SUMMARY_ASSET_SCHEMA_VERSION ||
+                parsed.content_hash !== hash ||
+                !metadata ||
+                typeof metadata.file_path !== "string" ||
+                typeof metadata.file_name !== "string" ||
+                typeof metadata.extension !== "string" ||
+                metadata.content_hash !== hash ||
+                metadata.prompt_version !== llm_1.SUMMARY_PROMPT_VERSION ||
+                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 +148,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 +216,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 +225,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

@@ -71,15 +71,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,6 +90,72 @@ 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"));
@@ -210,14 +267,12 @@ 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 = {
         schemaVersion: artifacts_1.SUMMARY_ASSET_SCHEMA_VERSION,
         content_hash: hash,
+        metadata,
         summary: summaryText,
         raw_code_snapshot: includeCodeSnapshot ? rawCodeSnapshot : undefined
     };
@@ -285,7 +340,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 +359,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 +480,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 +564,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/config.js

@@ -36,6 +36,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)) {
@@ -73,6 +81,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 +133,11 @@ function buildRuntimeConfig(options, needs = { chat: true, embeddings: true }) {
             includeGlobs,
             excludeGlobs,
             ignoreFile,
-            concurrency: summarizeConcurrency
+            concurrency: summarizeConcurrency,
+            summaryPrompt,
+            summaryPromptFile,
+            resolvedSummaryPrompt,
+            summaryPromptSource
         }
     };
 }

package/dist/index.js

@@ -42,7 +42,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 +72,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 +86,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) {

package/dist/types/artifacts.js

@@ -2,4 +2,4 @@
 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.SUMMARY_ASSET_SCHEMA_VERSION = 2;

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.0",
   "description": "Translate repository code shifts into plain-English business context",
   "license": "MIT",
   "author": "Christopher Sullivan",