agents-reverse-engineer 0.2.11 → 0.3.0

package/dist/generation/writers/gemini-md.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Write GEMINI.md at the project root.
+ *
+ * Only writes if Gemini CLI is installed locally (`.gemini` directory exists).
+ * If a user-defined GEMINI.md exists (not generated by us), it will be
+ * preserved as GEMINI.local.md and referenced in the generated file.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Path to written GEMINI.md, or null if Gemini CLI is not installed
+ */
+export declare function writeGeminiMd(projectRoot: string): Promise<string | null>;
+/**
+ * Get the content that would be written to GEMINI.md.
+ * Useful for previewing without writing.
+ */
+export declare function getGeminiMdContent(): string;
+//# sourceMappingURL=gemini-md.d.ts.map

package/dist/generation/writers/gemini-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini-md.d.ts","sourceRoot":"","sources":["../../../src/generation/writers/gemini-md.ts"],"names":[],"mappings":"AA4DA;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4B/E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C"}

package/dist/generation/writers/gemini-md.js

@@ -0,0 +1,96 @@
+import { writeFile, readFile, stat, rename } from 'node:fs/promises';
+import * as path from 'node:path';
+import { isRuntimeInstalledLocally } from '../../installer/paths.js';
+/** Marker comment to identify generated GEMINI.md files */
+const GENERATED_MARKER = '<!-- Generated by agents-reverse-engineer -->';
+/**
+ * Standard GEMINI.md content - simple pointer to AGENTS.md.
+ *
+ * For Google Gemini CLI compatibility.
+ */
+function buildGeminiMdContent(hasLocalFile) {
+    const sections = [];
+    // Generated marker (first line)
+    sections.push(GENERATED_MARKER);
+    sections.push('');
+    // Reference to user-defined local file if it exists
+    if (hasLocalFile) {
+        sections.push('> **Note:** This project has additional documentation in [GEMINI.local.md](./GEMINI.local.md)');
+        sections.push('');
+    }
+    sections.push('# GEMINI.md');
+    sections.push('');
+    sections.push('See [AGENTS.md](./AGENTS.md) for codebase documentation.');
+    sections.push('');
+    sections.push('This file exists for Google Gemini CLI compatibility. The actual documentation');
+    sections.push('is maintained in AGENTS.md files throughout the codebase.');
+    sections.push('');
+    return sections.join('\n');
+}
+/**
+ * Check if a file was generated by us (contains marker).
+ */
+async function isGeneratedFile(filePath) {
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        return content.includes(GENERATED_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a local file exists.
+ */
+async function hasLocalFile(localPath) {
+    try {
+        await stat(localPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write GEMINI.md at the project root.
+ *
+ * Only writes if Gemini CLI is installed locally (`.gemini` directory exists).
+ * If a user-defined GEMINI.md exists (not generated by us), it will be
+ * preserved as GEMINI.local.md and referenced in the generated file.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Path to written GEMINI.md, or null if Gemini CLI is not installed
+ */
+export async function writeGeminiMd(projectRoot) {
+    // Only generate if Gemini CLI is installed locally
+    const isInstalled = await isRuntimeInstalledLocally('gemini', projectRoot);
+    if (!isInstalled) {
+        return null;
+    }
+    const geminiPath = path.join(projectRoot, 'GEMINI.md');
+    const localPath = path.join(projectRoot, 'GEMINI.local.md');
+    // Check if existing GEMINI.md is user-defined (not generated by us)
+    let hasLocal = await hasLocalFile(localPath);
+    try {
+        const existingIsGenerated = await isGeneratedFile(geminiPath);
+        if (!existingIsGenerated) {
+            // User-defined GEMINI.md exists - preserve it
+            await rename(geminiPath, localPath);
+            hasLocal = true;
+        }
+    }
+    catch {
+        // No existing GEMINI.md - that's fine
+    }
+    const content = buildGeminiMdContent(hasLocal);
+    await writeFile(geminiPath, content, 'utf-8');
+    return geminiPath;
+}
+/**
+ * Get the content that would be written to GEMINI.md.
+ * Useful for previewing without writing.
+ */
+export function getGeminiMdContent() {
+    return buildGeminiMdContent(false);
+}
+//# sourceMappingURL=gemini-md.js.map

package/dist/generation/writers/gemini-md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini-md.js","sourceRoot":"","sources":["../../../src/generation/writers/gemini-md.ts"],"names":[],"mappings":"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"}

package/dist/generation/writers/index.d.ts

@@ -1,5 +1,7 @@
 export { writeSumFile, readSumFile, getSumPath, sumFileExists, type SumFileContent, } from './sum.js';
 export { writeAgentsMd, buildAgentsMd, buildDirectoryDoc, type DirectoryDoc, type FileGroup, type FileRef, type SubdirSummary, } from './agents-md.js';
 export { writeClaudeMd, getClaudeMdContent, } from './claude-md.js';
+export { writeGeminiMd, getGeminiMdContent, } from './gemini-md.js';
+export { writeOpencodeMd, getOpencodeMdContent, } from './opencode-md.js';
 export { writeArchitectureMd, writeStackMd, buildArchitectureMd, buildStackMd, analyzePackageJson, type SupplementaryConfig, type StackInfo, } from './supplementary.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/generation/writers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/generation/writers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,WAAW,EACX,UAAU,EACV,aAAa,EACb,KAAK,cAAc,GACpB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,aAAa,EACb,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,SAAS,GACf,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/generation/writers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,WAAW,EACX,UAAU,EACV,aAAa,EACb,KAAK,cAAc,GACpB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,aAAa,EACb,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,aAAa,EACb,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,eAAe,EACf,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,SAAS,GACf,MAAM,oBAAoB,CAAC"}

package/dist/generation/writers/index.js

@@ -1,5 +1,7 @@
 export { writeSumFile, readSumFile, getSumPath, sumFileExists, } from './sum.js';
 export { writeAgentsMd, buildAgentsMd, buildDirectoryDoc, } from './agents-md.js';
 export { writeClaudeMd, getClaudeMdContent, } from './claude-md.js';
+export { writeGeminiMd, getGeminiMdContent, } from './gemini-md.js';
+export { writeOpencodeMd, getOpencodeMdContent, } from './opencode-md.js';
 export { writeArchitectureMd, writeStackMd, buildArchitectureMd, buildStackMd, analyzePackageJson, } from './supplementary.js';
 //# sourceMappingURL=index.js.map

package/dist/generation/writers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/generation/writers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,WAAW,EACX,UAAU,EACV,aAAa,GAEd,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,aAAa,EACb,aAAa,EACb,iBAAiB,GAKlB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,aAAa,EACb,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,GAGnB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/generation/writers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,WAAW,EACX,UAAU,EACV,aAAa,GAEd,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,aAAa,EACb,aAAa,EACb,iBAAiB,GAKlB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,aAAa,EACb,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,aAAa,EACb,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,eAAe,EACf,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,GAGnB,MAAM,oBAAoB,CAAC"}

package/dist/generation/writers/opencode-md.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Write OPENCODE.md at the project root.
+ *
+ * Only writes if OpenCode is installed locally (`.opencode` directory exists).
+ * If a user-defined OPENCODE.md exists (not generated by us), it will be
+ * preserved as OPENCODE.local.md and referenced in the generated file.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Path to written OPENCODE.md, or null if OpenCode is not installed
+ */
+export declare function writeOpencodeMd(projectRoot: string): Promise<string | null>;
+/**
+ * Get the content that would be written to OPENCODE.md.
+ * Useful for previewing without writing.
+ */
+export declare function getOpencodeMdContent(): string;
+//# sourceMappingURL=opencode-md.d.ts.map

package/dist/generation/writers/opencode-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opencode-md.d.ts","sourceRoot":"","sources":["../../../src/generation/writers/opencode-md.ts"],"names":[],"mappings":"AA4DA;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4BjF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}

package/dist/generation/writers/opencode-md.js

@@ -0,0 +1,96 @@
+import { writeFile, readFile, stat, rename } from 'node:fs/promises';
+import * as path from 'node:path';
+import { isRuntimeInstalledLocally } from '../../installer/paths.js';
+/** Marker comment to identify generated OPENCODE.md files */
+const GENERATED_MARKER = '<!-- Generated by agents-reverse-engineer -->';
+/**
+ * Standard OPENCODE.md content - simple pointer to AGENTS.md.
+ *
+ * For OpenCode compatibility.
+ */
+function buildOpencodeMdContent(hasLocalFile) {
+    const sections = [];
+    // Generated marker (first line)
+    sections.push(GENERATED_MARKER);
+    sections.push('');
+    // Reference to user-defined local file if it exists
+    if (hasLocalFile) {
+        sections.push('> **Note:** This project has additional documentation in [OPENCODE.local.md](./OPENCODE.local.md)');
+        sections.push('');
+    }
+    sections.push('# OPENCODE.md');
+    sections.push('');
+    sections.push('See [AGENTS.md](./AGENTS.md) for codebase documentation.');
+    sections.push('');
+    sections.push('This file exists for OpenCode compatibility. The actual documentation');
+    sections.push('is maintained in AGENTS.md files throughout the codebase.');
+    sections.push('');
+    return sections.join('\n');
+}
+/**
+ * Check if a file was generated by us (contains marker).
+ */
+async function isGeneratedFile(filePath) {
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        return content.includes(GENERATED_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a local file exists.
+ */
+async function hasLocalFile(localPath) {
+    try {
+        await stat(localPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write OPENCODE.md at the project root.
+ *
+ * Only writes if OpenCode is installed locally (`.opencode` directory exists).
+ * If a user-defined OPENCODE.md exists (not generated by us), it will be
+ * preserved as OPENCODE.local.md and referenced in the generated file.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Path to written OPENCODE.md, or null if OpenCode is not installed
+ */
+export async function writeOpencodeMd(projectRoot) {
+    // Only generate if OpenCode is installed locally
+    const isInstalled = await isRuntimeInstalledLocally('opencode', projectRoot);
+    if (!isInstalled) {
+        return null;
+    }
+    const opencodePath = path.join(projectRoot, 'OPENCODE.md');
+    const localPath = path.join(projectRoot, 'OPENCODE.local.md');
+    // Check if existing OPENCODE.md is user-defined (not generated by us)
+    let hasLocal = await hasLocalFile(localPath);
+    try {
+        const existingIsGenerated = await isGeneratedFile(opencodePath);
+        if (!existingIsGenerated) {
+            // User-defined OPENCODE.md exists - preserve it
+            await rename(opencodePath, localPath);
+            hasLocal = true;
+        }
+    }
+    catch {
+        // No existing OPENCODE.md - that's fine
+    }
+    const content = buildOpencodeMdContent(hasLocal);
+    await writeFile(opencodePath, content, 'utf-8');
+    return opencodePath;
+}
+/**
+ * Get the content that would be written to OPENCODE.md.
+ * Useful for previewing without writing.
+ */
+export function getOpencodeMdContent() {
+    return buildOpencodeMdContent(false);
+}
+//# sourceMappingURL=opencode-md.js.map

package/dist/generation/writers/opencode-md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opencode-md.js","sourceRoot":"","sources":["../../../src/generation/writers/opencode-md.ts"],"names":[],"mappings":"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"}

package/dist/generation/writers/sum.d.ts

@@ -3,7 +3,7 @@ import type { SummaryMetadata } from '../types.js';
  * Content structure for a .sum file.
  */
 export interface SumFileContent {
-    /** Main summary text */
+    /** Main summary text (detailed description) */
     summary: string;
     /** Extracted metadata */
     metadata: SummaryMetadata;
@@ -11,6 +11,8 @@ export interface SumFileContent {
     fileType: string;
     /** Generation timestamp */
     generatedAt: string;
+    /** SHA-256 hash of source file content (for change detection) */
+    contentHash: string;
 }
 /**
  * Parse a .sum file back into structured content.

package/dist/generation/writers/sum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sum.d.ts","sourceRoot":"","sources":["../../../src/generation/writers/sum.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,QAAQ,EAAE,eAAe,CAAC;IAC1B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAOjF;AA0DD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAIxE"}
+{"version":3,"file":"sum.d.ts","sourceRoot":"","sources":["../../../src/generation/writers/sum.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,QAAQ,EAAE,eAAe,CAAC;IAC1B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAOjF;AA8HD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAIxE"}

package/dist/generation/writers/sum.js

@@ -13,6 +13,32 @@ export async function readSumFile(sumPath) {
         return null;
     }
 }
+/**
+ * Parse a YAML-style array from frontmatter.
+ * Supports both inline [a, b, c] and multi-line formats.
+ */
+function parseYamlArray(frontmatter, key) {
+    // Try inline format first: key: [a, b, c]
+    const inlineMatch = frontmatter.match(new RegExp(`${key}:\\s*\\[([^\\]]*)\\]`));
+    if (inlineMatch) {
+        return inlineMatch[1]
+            .split(',')
+            .map(s => s.trim().replace(/^["']|["']$/g, ''))
+            .filter(s => s.length > 0);
+    }
+    // Try multi-line format:
+    // key:
+    //   - item1
+    //   - item2
+    const multiLineMatch = frontmatter.match(new RegExp(`${key}:\\s*\\n((?:\\s+-\\s+.+\\n?)+)`, 'm'));
+    if (multiLineMatch) {
+        return multiLineMatch[1]
+            .split('\n')
+            .map(line => line.replace(/^\s*-\s*/, '').trim())
+            .filter(s => s.length > 0);
+    }
+    return [];
+}
 /**
  * Parse .sum file content into structured data.
  */
@@ -27,41 +53,75 @@ function parseSumFile(content) {
         // Parse frontmatter (simple YAML-like parsing)
         const fileType = frontmatter.match(/file_type:\s*(.+)/)?.[1]?.trim() ?? 'generic';
         const generatedAt = frontmatter.match(/generated_at:\s*(.+)/)?.[1]?.trim() ?? '';
-        // Parse metadata sections
+        const contentHash = frontmatter.match(/content_hash:\s*(.+)/)?.[1]?.trim() ?? '';
+        // Parse purpose (single line value)
+        const purpose = frontmatter.match(/purpose:\s*(.+)/)?.[1]?.trim() ?? '';
+        // Parse metadata arrays
         const metadata = {
-            purpose: '',
-            publicInterface: [],
-            dependencies: [],
-            patterns: [],
+            purpose,
+            publicInterface: parseYamlArray(frontmatter, 'public_interface'),
+            dependencies: parseYamlArray(frontmatter, 'dependencies'),
+            patterns: parseYamlArray(frontmatter, 'patterns'),
         };
-        // Extract purpose from summary (first paragraph after any heading)
-        const purposeMatch = summary.match(/##?\s*Purpose\n([\s\S]*?)(?=\n##|\n\n##|$)/i);
-        if (purposeMatch) {
-            metadata.purpose = purposeMatch[1].trim();
+        // Parse optional fields
+        const criticalTodos = parseYamlArray(frontmatter, 'critical_todos');
+        if (criticalTodos.length > 0) {
+            metadata.criticalTodos = criticalTodos;
+        }
+        const relatedFiles = parseYamlArray(frontmatter, 'related_files');
+        if (relatedFiles.length > 0) {
+            metadata.relatedFiles = relatedFiles;
         }
         return {
             summary,
             metadata,
             fileType,
             generatedAt,
+            contentHash,
         };
     }
     catch {
         return null;
     }
 }
+/**
+ * Format a YAML array for frontmatter.
+ * Uses inline format for short arrays, multi-line for longer ones.
+ */
+function formatYamlArray(key, values) {
+    if (values.length === 0) {
+        return `${key}: []`;
+    }
+    if (values.length <= 3 && values.every(v => v.length < 40)) {
+        // Inline format for short arrays
+        return `${key}: [${values.join(', ')}]`;
+    }
+    // Multi-line format for longer arrays
+    return `${key}:\n${values.map(v => `  - ${v}`).join('\n')}`;
+}
 /**
  * Format .sum file content for writing.
  */
 function formatSumFile(content) {
-    const frontmatter = [
+    const lines = [
         '---',
         `file_type: ${content.fileType}`,
         `generated_at: ${content.generatedAt}`,
-        '---',
-        '',
-    ].join('\n');
-    return frontmatter + content.summary;
+        `content_hash: ${content.contentHash}`,
+        `purpose: ${content.metadata.purpose}`,
+        formatYamlArray('public_interface', content.metadata.publicInterface),
+        formatYamlArray('dependencies', content.metadata.dependencies),
+        formatYamlArray('patterns', content.metadata.patterns),
+    ];
+    // Add optional fields if present
+    if (content.metadata.criticalTodos && content.metadata.criticalTodos.length > 0) {
+        lines.push(formatYamlArray('critical_todos', content.metadata.criticalTodos));
+    }
+    if (content.metadata.relatedFiles && content.metadata.relatedFiles.length > 0) {
+        lines.push(formatYamlArray('related_files', content.metadata.relatedFiles));
+    }
+    lines.push('---', '');
+    return lines.join('\n') + content.summary;
 }
 /**
  * Write a .sum file alongside a source file.

package/dist/generation/writers/sum.js.map

@@ -1 +1 @@
-{"version":3,"file":"sum.js","sourceRoot":"","sources":["../../../src/generation/writers/sum.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sum.js","sourceRoot":"","sources":["../../../src/generation/writers/sum.ts"],"names":[],"mappings":"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"}

package/dist/generation/writers/supplementary.d.ts

@@ -33,21 +33,27 @@ export interface StackInfo {
  * This generates a template that the host LLM will expand with actual
  * architectural analysis.
  */
-export declare function buildArchitectureMd(metrics: ComplexityMetrics, projectName: string): string;
+export declare function buildArchitectureMd(metrics: ComplexityMetrics, projectName: string, hasLocalFile?: boolean): string;
 /**
  * Build STACK.md content from package.json analysis.
  */
-export declare function buildStackMd(stackInfo: StackInfo, projectName: string): string;
+export declare function buildStackMd(stackInfo: StackInfo, projectName: string, hasLocalFile?: boolean): string;
 /**
  * Parse package.json to extract stack information.
  */
 export declare function analyzePackageJson(packageJsonPath: string): Promise<StackInfo | null>;
 /**
  * Write ARCHITECTURE.md to the configured location.
+ *
+ * If a user-defined ARCHITECTURE.md exists (not generated by us), it will be
+ * preserved as ARCHITECTURE.local.md and referenced in the generated file.
  */
 export declare function writeArchitectureMd(projectRoot: string, metrics: ComplexityMetrics, config: SupplementaryConfig): Promise<string | null>;
 /**
  * Write STACK.md to the configured location.
+ *
+ * If a user-defined STACK.md exists (not generated by us), it will be
+ * preserved as STACK.local.md and referenced in the generated file.
  */
 export declare function writeStackMd(projectRoot: string, config: SupplementaryConfig): Promise<string | null>;
 //# sourceMappingURL=supplementary.d.ts.map

package/dist/generation/writers/supplementary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supplementary.d.ts","sourceRoot":"","sources":["../../../src/generation/writers/supplementary.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,oBAAoB,EAAE,OAAO,CAAC;IAC9B,mCAAmC;IACnC,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IACzF,wBAAwB;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,iBAAiB,EAC1B,WAAW,EAAE,MAAM,GAClB,MAAM,CAsCR;AA4BD;;GAEG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,MAAM,GAClB,MAAM,CAoCR;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CA+D3B;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAexB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoBxB"}
+{"version":3,"file":"supplementary.d.ts","sourceRoot":"","sources":["../../../src/generation/writers/supplementary.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAK1D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,oBAAoB,EAAE,OAAO,CAAC;IAC9B,mCAAmC;IACnC,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IACzF,wBAAwB;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA+CD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,iBAAiB,EAC1B,WAAW,EAAE,MAAM,EACnB,YAAY,GAAE,OAAe,GAC5B,MAAM,CAgDR;AA4BD;;GAEG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,MAAM,EACnB,YAAY,GAAE,OAAe,GAC5B,MAAM,CA8CR;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CA+D3B;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoBxB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyBxB"}

package/dist/generation/writers/supplementary.js

@@ -1,13 +1,66 @@
-import { writeFile, readFile, mkdir } from 'node:fs/promises';
+import { writeFile, readFile, mkdir, stat, rename } from 'node:fs/promises';
 import * as path from 'node:path';
+/** Marker comment to identify generated files */
+const GENERATED_MARKER = '<!-- Generated by agents-reverse-engineer -->';
+/**
+ * Check if a file was generated by us (contains marker).
+ */
+async function isGeneratedFile(filePath) {
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        return content.includes(GENERATED_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a local file exists.
+ */
+async function hasLocalFile(localPath) {
+    try {
+        await stat(localPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Preserve user-defined file by renaming to .local.md
+ * Returns whether a local file exists (either already existed or was just created)
+ */
+async function preserveUserFile(filePath, localPath) {
+    let hasLocal = await hasLocalFile(localPath);
+    try {
+        const existingIsGenerated = await isGeneratedFile(filePath);
+        if (!existingIsGenerated) {
+            // User-defined file exists - preserve it
+            await rename(filePath, localPath);
+            hasLocal = true;
+        }
+    }
+    catch {
+        // No existing file - that's fine
+    }
+    return hasLocal;
+}
 /**
  * Build ARCHITECTURE.md content from complexity metrics.
  *
  * This generates a template that the host LLM will expand with actual
  * architectural analysis.
  */
-export function buildArchitectureMd(metrics, projectName) {
+export function buildArchitectureMd(metrics, projectName, hasLocalFile = false) {
     const sections = [];
+    // Generated marker (first line)
+    sections.push(GENERATED_MARKER);
+    sections.push('');
+    // Reference to user-defined local file if it exists
+    if (hasLocalFile) {
+        sections.push('> **Note:** This project has additional architecture documentation in [ARCHITECTURE.local.md](./ARCHITECTURE.local.md)');
+        sections.push('');
+    }
     // Header
     sections.push(`# Architecture: ${projectName}\n`);
     sections.push(`> Auto-generated architecture overview. ${metrics.fileCount} files analyzed.\n`);
@@ -63,8 +116,16 @@ function getTopLevelDirectories(directories) {
 /**
  * Build STACK.md content from package.json analysis.
  */
-export function buildStackMd(stackInfo, projectName) {
+export function buildStackMd(stackInfo, projectName, hasLocalFile = false) {
     const sections = [];
+    // Generated marker (first line)
+    sections.push(GENERATED_MARKER);
+    sections.push('');
+    // Reference to user-defined local file if it exists
+    if (hasLocalFile) {
+        sections.push('> **Note:** This project has additional stack documentation in [STACK.local.md](./STACK.local.md)');
+        sections.push('');
+    }
     // Header
     sections.push(`# Technology Stack: ${projectName}\n`);
     // Runtime
@@ -158,6 +219,9 @@ export async function analyzePackageJson(packageJsonPath) {
 }
 /**
  * Write ARCHITECTURE.md to the configured location.
+ *
+ * If a user-defined ARCHITECTURE.md exists (not generated by us), it will be
+ * preserved as ARCHITECTURE.local.md and referenced in the generated file.
  */
 export async function writeArchitectureMd(projectRoot, metrics, config) {
     if (!config.generateArchitecture)
@@ -166,14 +230,20 @@ export async function writeArchitectureMd(projectRoot, metrics, config) {
         ? path.join(projectRoot, config.outputDir)
         : projectRoot;
     await mkdir(outputDir, { recursive: true });
-    const projectName = path.basename(projectRoot);
-    const content = buildArchitectureMd(metrics, projectName);
     const filePath = path.join(outputDir, 'ARCHITECTURE.md');
+    const localPath = path.join(outputDir, 'ARCHITECTURE.local.md');
+    // Preserve user-defined file if it exists
+    const hasLocal = await preserveUserFile(filePath, localPath);
+    const projectName = path.basename(projectRoot);
+    const content = buildArchitectureMd(metrics, projectName, hasLocal);
     await writeFile(filePath, content, 'utf-8');
     return filePath;
 }
 /**
  * Write STACK.md to the configured location.
+ *
+ * If a user-defined STACK.md exists (not generated by us), it will be
+ * preserved as STACK.local.md and referenced in the generated file.
  */
 export async function writeStackMd(projectRoot, config) {
     if (!config.generateStack)
@@ -186,9 +256,12 @@ export async function writeStackMd(projectRoot, config) {
         ? path.join(projectRoot, config.outputDir)
         : projectRoot;
     await mkdir(outputDir, { recursive: true });
-    const projectName = path.basename(projectRoot);
-    const content = buildStackMd(stackInfo, projectName);
     const filePath = path.join(outputDir, 'STACK.md');
+    const localPath = path.join(outputDir, 'STACK.local.md');
+    // Preserve user-defined file if it exists
+    const hasLocal = await preserveUserFile(filePath, localPath);
+    const projectName = path.basename(projectRoot);
+    const content = buildStackMd(stackInfo, projectName, hasLocal);
     await writeFile(filePath, content, 'utf-8');
     return filePath;
 }