golem-cc 2.1.2 → 3.0.0

package/.golem/lib/document.mjs

@@ -0,0 +1,792 @@
+import { readFile, mkdir, writeFile as fsWriteFile, readdir, unlink } from 'node:fs/promises';
+import { execSync } from 'node:child_process';
+import { join, resolve, basename, relative } from 'node:path';
+import { detectProject, loadConfig } from './config.mjs';
+import { runClaude, checkClaudeCli } from './claude.mjs';
+import { attachDisplay } from './display.mjs';
+import { header, info, warn, fail, success, spinner } from './output.mjs';
+import { runGates } from './gates.mjs';
+
+const GIT_OPTS = { cwd: process.cwd(), stdio: 'pipe' };
+
+function waitForClaude(emitter) {
+  let error = false;
+  return new Promise((res) => {
+    emitter.on('close', () => res(error));
+    emitter.on('error', (err) => {
+      fail(`Claude error: ${err.message}`);
+      error = true;
+      res(error);
+    });
+  });
+}
+
+function gitSnapshot() {
+  return execSync('git rev-parse HEAD', GIT_OPTS).toString().trim();
+}
+
+function gitRestore(sha) {
+  execSync('git checkout .', GIT_OPTS);
+  execSync('git clean -fd', GIT_OPTS);
+  execSync(`git reset --hard ${sha}`, GIT_OPTS);
+}
+
+const EXTENSION_MAP = {
+  javascript: ['.js', '.mjs', '.cjs', '.jsx'],
+  typescript: ['.ts', '.tsx', '.mts', '.cts'],
+  python: ['.py'],
+};
+
+const ALWAYS_INCLUDED = ['.vue', '.sql'];
+
+const EXCLUDE_PATTERNS = [
+  /\.test\.[^.]+$/,
+  /\.spec\.[^.]+$/,
+  /__tests__\//,
+  /__mocks__\//,
+  /\.stories\.[^.]+$/,
+  /\.min\.[^.]+$/,
+  /node_modules\//,
+  /dist\//,
+  /build\//,
+  /\.next\//,
+  /\.nuxt\//,
+  /\.output\//,
+  /coverage\//,
+  /package-lock\.json$/,
+  /pnpm-lock\.yaml$/,
+  /yarn\.lock$/,
+  /\.lock$/,
+  /\.generated\.[^.]+$/,
+  /\.d\.ts$/,
+];
+
+function gitListFiles(basePath) {
+  try {
+    const output = execSync('git ls-files', {
+      cwd: resolve(basePath),
+      stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf-8',
+    });
+    return output.trim().split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function discoverSourceFiles(basePath, detection) {
+  const extensions = [...(EXTENSION_MAP[detection?.language] || EXTENSION_MAP.javascript), ...ALWAYS_INCLUDED];
+  const files = gitListFiles(basePath);
+
+  return files
+    .filter(f => extensions.some(ext => f.endsWith(ext)) && !EXCLUDE_PATTERNS.some(p => p.test(f)))
+    .sort();
+}
+
+const MAX_FILES_PER_BATCH = 30;
+
+function formatProjectType(detection) {
+  const fields = [
+    ['Language', detection.language],
+    ['Framework', detection.framework, 'none'],
+    ['Module system', detection.moduleSystem, 'n/a'],
+    ['Database tooling', detection.databaseTooling, 'none'],
+    ['Inline doc standard', detection.inlineDocStandard],
+  ];
+  return fields
+    .filter(([, val, skip]) => val && val !== skip)
+    .map(([label, val]) => `${label}: ${val}`)
+    .join('\n');
+}
+
+export function buildInlinePrompt(template, detection, files) {
+  const projectType = formatProjectType(detection);
+  const fileList = files.map(f => `- ${f}`).join('\n');
+  return template
+    .replace('{{PROJECT_TYPE}}', projectType)
+    .replace('{{FILES}}', fileList);
+}
+
+function batchFiles(files, batchSize) {
+  return Array.from({ length: Math.ceil(files.length / batchSize) }, (_, i) =>
+    files.slice(i * batchSize, (i + 1) * batchSize)
+  );
+}
+
+async function loadInlineTemplate() {
+  try {
+    return await readFile(join(process.cwd(), '.golem/prompts/document-inline.md'), 'utf-8');
+  } catch {
+    return 'Add inline documentation to the following files. Follow the project type conventions.\n\n## Project Type\n\n{{PROJECT_TYPE}}\n\n## Target Files\n\n{{FILES}}';
+  }
+}
+
+export async function runDocumentInline(options = {}) {
+  if (!checkClaudeCli()) {
+    fail('Claude CLI not found. Install it from https://docs.anthropic.com/en/docs/claude-code');
+    return;
+  }
+
+  const basePath = options.path || process.cwd();
+  const detection = await detectProject(basePath);
+  const files = discoverSourceFiles(basePath, detection);
+
+  if (files.length === 0) {
+    warn('No source files found to document.');
+    return;
+  }
+
+  header('Golem Document Inline');
+  info(`Project: ${detection.language} / ${detection.framework} (${detection.inlineDocStandard})`);
+  info(`Found ${files.length} source file(s)`);
+
+  const config = await loadConfig();
+  const template = await loadInlineTemplate();
+  const batches = batchFiles(files, MAX_FILES_PER_BATCH);
+  const skipValidation = options.skipGates === true;
+
+  for (let i = 0; i < batches.length; i++) {
+    const batch = batches[i];
+    if (batches.length > 1) {
+      info(`Batch ${i + 1}/${batches.length} (${batch.length} files)`);
+    }
+
+    const snapshot = gitSnapshot();
+
+    const prompt = buildInlinePrompt(template, detection, batch);
+    const model = options.model || 'opus';
+    const emitter = runClaude(prompt, { model });
+    attachDisplay(emitter);
+
+    const claudeError = await waitForClaude(emitter);
+
+    if (claudeError || skipValidation) continue;
+
+    info('Running validation gates...');
+    const gateResult = await runGates(config);
+
+    for (const r of gateResult.results) {
+      if (r.skipped) continue;
+      const dur = `(${(r.duration / 1000).toFixed(1)}s)`;
+      const log = r.passed ? success : fail;
+      log(`[Gate] ${r.name} ${r.passed ? 'PASS' : 'FAIL'} ${dur}`);
+    }
+
+    if (!gateResult.passed) {
+      warn(`Validation failed — reverting inline doc changes for batch ${i + 1}`);
+      gitRestore(snapshot);
+      continue;
+    }
+    success('Validation passed — inline docs preserved');
+  }
+}
+
+const API_PATTERNS = [
+  /routes\//,
+  /api\//,
+  /controllers\//,
+  /endpoints\//,
+  /server\//,
+];
+
+const DB_PATTERNS = [
+  /prisma\//,
+  /drizzle/,
+  /migrations?\//,
+  /schema\.prisma$/,
+  /\.sql$/,
+  /knexfile/,
+  /models?\//,
+];
+
+const GUIDE_WORKFLOWS = [
+  { pattern: /api\/|routes\/|controllers\//, name: 'adding-api-endpoint' },
+  { pattern: /components?\//, name: 'creating-component' },
+  { pattern: /migrations?\//, name: 'database-migration' },
+  { pattern: /\.test\.|\.spec\./, name: 'writing-tests' },
+];
+
+const EXCLUDED_DIRS = new Set(['node_modules', 'dist', 'build', 'coverage', 'test', 'tests', '__tests__']);
+
+function detectModules(files) {
+  const dirs = new Set(
+    files
+      .filter(f => f.includes('/'))
+      .map(f => f.split('/')[0])
+      .filter(d => !d.startsWith('.') && !EXCLUDED_DIRS.has(d))
+  );
+  return [...dirs].sort();
+}
+
+function detectGuideWorkflows(files) {
+  return GUIDE_WORKFLOWS
+    .filter(({ pattern }) => files.some(f => pattern.test(f)))
+    .map(({ name }) => name);
+}
+
+function makeFrontmatter(title, description, order) {
+  return `---\ntitle: "${title}"\ndescription: "${description}"\nnavigation:\n  order: ${order}\n---\n`;
+}
+
+async function loadMarkdownTemplate() {
+  try {
+    return await readFile(join(process.cwd(), '.golem/prompts/document-markdown.md'), 'utf-8');
+  } catch {
+    return 'Generate markdown documentation for the project.\n\n## Output Directory\n\n{{DOCS_PATH}}\n\n## Project Structure\n\n{{PROJECT_STRUCTURE}}';
+  }
+}
+
+export function buildMarkdownPrompt(template, docsPath, projectStructure) {
+  return template
+    .replace('{{DOCS_PATH}}', docsPath)
+    .replace('{{PROJECT_STRUCTURE}}', projectStructure);
+}
+
+function buildProjectStructure(files, detection, modules, hasApi, hasDb, workflows) {
+  const lines = [];
+  lines.push(`Language: ${detection.language}`);
+  if (detection.framework !== 'none') lines.push(`Framework: ${detection.framework}`);
+  if (detection.moduleSystem !== 'n/a') lines.push(`Module system: ${detection.moduleSystem}`);
+  if (detection.databaseTooling !== 'none') lines.push(`Database tooling: ${detection.databaseTooling}`);
+  lines.push('');
+  lines.push(`Total files: ${files.length}`);
+  lines.push('');
+  lines.push('Directories:');
+  for (const m of modules) {
+    const count = files.filter(f => f.startsWith(m + '/')).length;
+    lines.push(`  ${m}/ (${count} files)`);
+  }
+  if (hasApi) lines.push('\nHas API/route layer: yes');
+  if (hasDb) lines.push(`Has database layer: yes (${detection.databaseTooling})`);
+  if (workflows.length > 0) {
+    lines.push('\nDetected workflows:');
+    for (const w of workflows) lines.push(`  - ${w}`);
+  }
+  lines.push('\nFile listing (top 100):');
+  for (const f of files.slice(0, 100)) {
+    lines.push(`  ${f}`);
+  }
+  if (files.length > 100) lines.push(`  ... (${files.length - 100} more files)`);
+  return lines.join('\n');
+}
+
+async function writeDocFile(dir, filename, title, desc, order) {
+  await mkdir(dir, { recursive: true });
+  const filePath = join(dir, filename);
+  await fsWriteFile(filePath, makeFrontmatter(title, desc, order) + `\n# ${title}\n`, 'utf-8');
+  return filePath;
+}
+
+export async function createDocsStructure(docsPath, detection, files) {
+  const modules = detectModules(files);
+  const hasApi = files.some(f => API_PATTERNS.some(p => p.test(f)));
+  const hasDb = (detection?.databaseTooling && detection.databaseTooling !== 'none') || files.some(f => DB_PATTERNS.some(p => p.test(f)));
+  const workflows = detectGuideWorkflows(files);
+  const hasDeprecated = files.some(f => f.startsWith(docsPath + '/deprecated/') || f.startsWith(docsPath + 'deprecated/'));
+
+  await mkdir(docsPath, { recursive: true });
+
+  const created = [];
+
+  const baseFiles = [
+    { name: 'index.md', title: 'Project Overview', desc: 'Overview of the project, its purpose, and structure', order: 1 },
+    { name: 'architecture.md', title: 'Architecture', desc: 'System design and how components connect', order: 2 },
+    { name: 'getting-started.md', title: 'Getting Started', desc: 'Setup, installation, prerequisites, and first run', order: 3 },
+    { name: 'configuration.md', title: 'Configuration', desc: 'All configuration options with explanations', order: 4 },
+  ];
+
+  for (const { name, title, desc, order } of baseFiles) {
+    created.push(await writeDocFile(docsPath, name, title, desc, order));
+  }
+
+  if (modules.length > 0) {
+    const modulesDir = join(docsPath, 'modules');
+    for (let i = 0; i < modules.length; i++) {
+      created.push(await writeDocFile(modulesDir, `${modules[i]}.md`, modules[i], `Documentation for the ${modules[i]} module`, i + 1));
+    }
+  }
+
+  if (hasApi) {
+    created.push(await writeDocFile(join(docsPath, 'api'), 'index.md', 'API Reference', 'API endpoints and resources', 1));
+  }
+
+  if (hasDb) {
+    created.push(await writeDocFile(join(docsPath, 'database'), 'schema.md', 'Database Schema', 'Full schema overview with relationships', 1));
+  }
+
+  if (workflows.length > 0) {
+    const guidesDir = join(docsPath, 'guides');
+    created.push(await writeDocFile(guidesDir, 'setup.md', 'Development Setup', 'Dev environment setup guide', 1));
+
+    for (let i = 0; i < workflows.length; i++) {
+      const wf = workflows[i];
+      const title = wf.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+      created.push(await writeDocFile(guidesDir, `${wf}.md`, title, `Guide for ${wf.replace(/-/g, ' ')}`, i + 2));
+    }
+  }
+
+  if (hasDeprecated) {
+    await mkdir(join(docsPath, 'deprecated'), { recursive: true });
+  }
+
+  return { created, modules, hasApi, hasDb, workflows, hasDeprecated };
+}
+
+export async function runDocumentMarkdown(options = {}) {
+  if (!checkClaudeCli()) {
+    fail('Claude CLI not found. Install it from https://docs.anthropic.com/en/docs/claude-code');
+    return;
+  }
+
+  const basePath = options.path || process.cwd();
+  const config = await loadConfig();
+  const docsPath = resolve(basePath, options.docsPath || config.docsPath || 'docs');
+  const detection = await detectProject(basePath);
+  const files = gitListFiles(basePath);
+
+  if (files.length === 0) {
+    warn('No project files found.');
+    return;
+  }
+
+  header('Golem Document Markdown');
+  info(`Project: ${detection.language} / ${detection.framework}`);
+  info(`Docs path: ${docsPath}`);
+  info(`Found ${files.length} project file(s)`);
+
+  const { created, modules, hasApi, hasDb, workflows } = await createDocsStructure(docsPath, detection, files);
+
+  info(`Created ${created.length} documentation file(s)`);
+  if (modules.length > 0) info(`Modules: ${modules.join(', ')}`);
+  if (hasApi) info('API documentation: yes');
+  if (hasDb) info(`Database documentation: yes (${detection.databaseTooling})`);
+  if (workflows.length > 0) info(`Guides: ${workflows.join(', ')}`);
+
+  const template = await loadMarkdownTemplate();
+  const projectStructure = buildProjectStructure(files, detection, modules, hasApi, hasDb, workflows);
+  const prompt = buildMarkdownPrompt(template, docsPath, projectStructure);
+
+  const model = options.model || config.model || 'opus';
+  const emitter = runClaude(prompt, { model });
+  attachDisplay(emitter);
+
+  const claudeError = await waitForClaude(emitter);
+
+  if (claudeError) {
+    warn('Claude encountered an error — skeleton docs preserved');
+  } else {
+    success('Markdown documentation generated');
+  }
+}
+
+async function getLastChangelogDate(basePath) {
+  try {
+    const changelogPath = join(basePath, 'CHANGELOG.md');
+    const content = await readFile(changelogPath, 'utf-8');
+    const match = content.match(/^## (\d{4}-\d{2}-\d{2})/m);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+export function getGitLog(basePath, since) {
+  const cmd = `git log --pretty='format:%H|%ai|%s' --no-merges${since ? ` --since=${since}` : ''}`;
+  try {
+    const output = execSync(cmd, {
+      cwd: resolve(basePath),
+      stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf-8',
+    });
+    const trimmed = output.trim();
+    if (!trimmed) return [];
+    return trimmed.split('\n').map(line => {
+      const [hash, date, ...msgParts] = line.split('|');
+      return { hash, date: date.split(' ')[0], message: msgParts.join('|') };
+    });
+  } catch {
+    return [];
+  }
+}
+
+export function groupCommitsByDate(commits) {
+  const groups = {};
+  for (const c of commits) {
+    (groups[c.date] ??= []).push(c);
+  }
+  return Object.entries(groups)
+    .sort(([a], [b]) => b.localeCompare(a))
+    .map(([date, items]) => ({ date, commits: items }));
+}
+
+export function buildChangelogPrompt(grouped) {
+  const lines = [
+    'You are writing a CHANGELOG for a non-technical audience (managers, stakeholders).',
+    'Translate the following git commits into plain-language sections.',
+    '',
+    'Rules:',
+    '- Group changes under these sections: **New Features**, **Improvements**, **Bug Fixes**',
+    '- Only include sections that have entries — omit empty sections',
+    '- Use simple, jargon-free language focused on user-facing impact',
+    '- Do NOT reference file names, function names, or technical implementation details',
+    '- Each entry should be a single clear sentence',
+    '- Group by the date headings provided',
+    '- Output ONLY valid markdown — no code fences, no preamble, no explanation',
+    '- Start with a top-level heading: # Changelog',
+    '- Use ## YYYY-MM-DD for date headings',
+    '- Use ### for section headings (New Features, Improvements, Bug Fixes)',
+    '- Use bullet points for entries',
+    '',
+    'Commits:',
+    '',
+  ];
+  for (const { date, commits } of grouped) {
+    lines.push(`Date: ${date}`);
+    for (const c of commits) {
+      lines.push(`  - ${c.message}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+export async function generateChangelog(config = {}) {
+  const basePath = config.path || process.cwd();
+
+  if (!checkClaudeCli()) {
+    fail('Claude CLI not found. Install it from https://docs.anthropic.com/en/docs/claude-code');
+    return;
+  }
+
+  const since = await getLastChangelogDate(basePath);
+  const commits = getGitLog(basePath, since);
+
+  if (commits.length === 0) {
+    warn('No commits found for changelog generation.');
+    return;
+  }
+
+  header('Golem Changelog');
+  info(`Found ${commits.length} commit(s)${since ? ` since ${since}` : ''}`);
+
+  const grouped = groupCommitsByDate(commits);
+  const prompt = buildChangelogPrompt(grouped);
+
+  const model = config.model || 'sonnet';
+  const emitter = runClaude(prompt, { model, allowedTools: [] });
+  attachDisplay(emitter);
+
+  let result = '';
+  emitter.on('assistant', (event) => {
+    if (event.message?.content) {
+      for (const block of event.message.content) {
+        if (block.type === 'text') {
+          result += block.text;
+        }
+      }
+    }
+  });
+
+  const claudeError = await waitForClaude(emitter);
+
+  if (claudeError || !result.trim()) {
+    warn('Changelog generation failed — no output from Claude');
+    return;
+  }
+
+  const changelogPath = join(basePath, 'CHANGELOG.md');
+  await fsWriteFile(changelogPath, result.trim() + '\n', 'utf-8');
+  success(`CHANGELOG.md written (${commits.length} commits)`);
+}
+
+async function readProjectInfo(basePath) {
+  // Try package.json first
+  try {
+    const pkgPath = join(basePath, 'package.json');
+    const content = await readFile(pkgPath, 'utf-8');
+    const pkg = JSON.parse(content);
+    return {
+      name: pkg.name || 'Untitled Project',
+      description: pkg.description || '',
+      language: 'javascript',
+    };
+  } catch {
+    // Ignore package.json errors
+  }
+
+  // Try pyproject.toml
+  try {
+    const pyPath = join(basePath, 'pyproject.toml');
+    const content = await readFile(pyPath, 'utf-8');
+    const nameMatch = content.match(/^\s*name\s*=\s*"([^"]+)"/m);
+    const descMatch = content.match(/^\s*description\s*=\s*"([^"]+)"/m);
+    return {
+      name: nameMatch ? nameMatch[1] : 'Untitled Project',
+      description: descMatch ? descMatch[1] : '',
+      language: 'python',
+    };
+  } catch {
+    // Ignore pyproject.toml errors
+  }
+
+  return {
+    name: 'Untitled Project',
+    description: '',
+    language: 'unknown',
+  };
+}
+
+const README_MARKERS = {
+  start: '<!-- GOLEM_GENERATED_START -->',
+  end: '<!-- GOLEM_GENERATED_END -->',
+};
+
+function buildReadmeContent(projectInfo, docsPath) {
+  const lines = [];
+  lines.push(`# ${projectInfo.name}`);
+  lines.push('');
+  if (projectInfo.description) {
+    lines.push(projectInfo.description);
+    lines.push('');
+  }
+  lines.push('## Documentation');
+  lines.push('');
+  lines.push(`This project includes comprehensive documentation in the [\`${docsPath}/\`](./${docsPath}/) directory:`);
+  lines.push('');
+  lines.push(`- [Overview](./${docsPath}/index.md) — Project overview and structure`);
+  lines.push(`- [Architecture](./${docsPath}/architecture.md) — System design and component connections`);
+  lines.push(`- [Getting Started](./${docsPath}/getting-started.md) — Setup and installation guide`);
+  lines.push(`- [Configuration](./${docsPath}/configuration.md) — All configuration options`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+async function readExistingReadme(basePath) {
+  try {
+    return await readFile(join(basePath, 'README.md'), 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+function extractUserContent(existing) {
+  if (!existing) return null;
+
+  const startIdx = existing.indexOf(README_MARKERS.start);
+  const endIdx = existing.indexOf(README_MARKERS.end);
+
+  if (startIdx === -1 || endIdx === -1) {
+    // No markers found — treat entire README as user content
+    return existing;
+  }
+
+  // Extract content before and after markers
+  const before = existing.slice(0, startIdx).trim();
+  const after = existing.slice(endIdx + README_MARKERS.end.length).trim();
+
+  if (!before && !after) return null;
+  return { before, after };
+}
+
+function mergeReadmeContent(generated, userContent) {
+  if (!userContent) {
+    return `${README_MARKERS.start}\n${generated}\n${README_MARKERS.end}\n`;
+  }
+
+  if (typeof userContent === 'string') {
+    // Entire README was user content — prepend generated section
+    return `${README_MARKERS.start}\n${generated}\n${README_MARKERS.end}\n\n${userContent}`;
+  }
+
+  // User content was split around markers
+  const parts = [];
+  if (userContent.before) parts.push(userContent.before);
+  parts.push(`${README_MARKERS.start}\n${generated}\n${README_MARKERS.end}`);
+  if (userContent.after) parts.push(userContent.after);
+  return parts.join('\n\n') + '\n';
+}
+
+export async function generateReadme(detection, config = {}) {
+  const basePath = config.path || process.cwd();
+  const docsPath = config.docsPath || 'docs';
+
+  const projectInfo = await readProjectInfo(basePath);
+  const existing = await readExistingReadme(basePath);
+  const userContent = extractUserContent(existing);
+
+  const generated = buildReadmeContent(projectInfo, docsPath);
+  const final = mergeReadmeContent(generated, userContent);
+
+  const readmePath = join(basePath, 'README.md');
+  await fsWriteFile(readmePath, final, 'utf-8');
+
+  if (existing) {
+    success('README.md updated (preserved existing content)');
+  } else {
+    success('README.md created');
+  }
+}
+
+function addDeprecatedFrontmatter(content, date) {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) {
+    // No frontmatter — add one with deprecated fields
+    const fm = `---\ndeprecated_date: "${date}"\nreplaced_by: ""\n---\n`;
+    return fm + content;
+  }
+
+  let frontmatter = fmMatch[1];
+  // Add deprecated_date and replaced_by before closing ---
+  frontmatter += `\ndeprecated_date: "${date}"\nreplaced_by: ""`;
+  return `---\n${frontmatter}\n---` + content.slice(fmMatch[0].length);
+}
+
+async function listMdFiles(dir) {
+  try {
+    const entries = await readdir(dir);
+    return entries.filter(f => f.endsWith('.md'));
+  } catch {
+    return [];
+  }
+}
+
+export async function archiveDeprecated(docsPath, basePath) {
+  const projectRoot = basePath || process.cwd();
+  const files = gitListFiles(projectRoot);
+  const today = new Date().toISOString().split('T')[0];
+  const moved = [];
+
+  // Scan modules/ docs
+  const modulesDir = join(docsPath, 'modules');
+  const moduleDocs = await listMdFiles(modulesDir);
+
+  for (const docFile of moduleDocs) {
+    const moduleName = docFile.replace(/\.md$/, '');
+    const hasSource = files.some(f => f.startsWith(moduleName + '/'));
+
+    if (!hasSource) {
+      const srcPath = join(modulesDir, docFile);
+      const deprecatedDir = join(docsPath, 'deprecated');
+      await mkdir(deprecatedDir, { recursive: true });
+      const destPath = join(deprecatedDir, docFile);
+
+      const content = await readFile(srcPath, 'utf-8');
+      const updated = addDeprecatedFrontmatter(content, today);
+      await fsWriteFile(destPath, updated, 'utf-8');
+
+      // Remove original (move = write to dest + delete source)
+      await unlink(srcPath);
+
+      moved.push({ from: srcPath, to: destPath, module: moduleName });
+    }
+  }
+
+  return { moved, date: today };
+}
+
+export async function runDocument(opts = {}) {
+  const basePath = opts.path || process.cwd();
+  const config = await loadConfig();
+  const docsPath = opts.docsPath || config.docsPath || 'docs';
+  const dryRun = opts.dryRun === true;
+  const inlineOnly = opts.inlineOnly === true;
+  const markdownOnly = opts.markdownOnly === true;
+
+  header('Golem Document');
+  const detection = await detectProject(basePath);
+  info(`Project: ${detection.language} / ${detection.framework} (${detection.inlineDocStandard})`);
+  info(`Docs path: ${docsPath}`);
+
+  if (dryRun) {
+    info('Dry run — no files will be changed');
+  }
+
+  const summary = { inlineFiles: 0, markdownFiles: 0, changelogCommits: 0, readmeAction: 'none', deprecated: 0 };
+
+  // Step 1: Inline docs (unless --markdown-only)
+  if (!markdownOnly) {
+    const files = discoverSourceFiles(basePath, detection);
+    summary.inlineFiles = files.length;
+    if (dryRun) {
+      info(`[dry-run] Would document ${files.length} source file(s) with inline ${detection.inlineDocStandard}`);
+    } else if (files.length > 0) {
+      await runDocumentInline({ path: basePath, model: opts.model || config.model });
+    } else {
+      warn('No source files found for inline documentation.');
+    }
+  }
+
+  // Step 2: Markdown generation (unless --inline-only)
+  if (!inlineOnly) {
+    const allFiles = gitListFiles(basePath);
+    const modules = detectModules(allFiles);
+    const hasApi = allFiles.some(f => API_PATTERNS.some(p => p.test(f)));
+    const hasDb = (detection?.databaseTooling && detection.databaseTooling !== 'none') || allFiles.some(f => DB_PATTERNS.some(p => p.test(f)));
+    const workflows = detectGuideWorkflows(allFiles);
+
+    if (dryRun) {
+      const resolvedDocsPath = resolve(basePath, docsPath);
+      info(`[dry-run] Would generate markdown docs in ${resolvedDocsPath}`);
+      info(`[dry-run]   Base files: index.md, architecture.md, getting-started.md, configuration.md`);
+      if (modules.length > 0) info(`[dry-run]   Module docs: ${modules.join(', ')}`);
+      if (hasApi) info('[dry-run]   API documentation: yes');
+      if (hasDb) info(`[dry-run]   Database documentation: yes (${detection.databaseTooling})`);
+      if (workflows.length > 0) info(`[dry-run]   Guides: ${workflows.join(', ')}`);
+      summary.markdownFiles = 4 + modules.length + (hasApi ? 1 : 0) + (hasDb ? 1 : 0) + (workflows.length > 0 ? 1 + workflows.length : 0);
+    } else {
+      await runDocumentMarkdown({ path: basePath, docsPath, model: opts.model || config.model });
+    }
+
+    // Step 3: Changelog
+    const commits = getGitLog(basePath);
+    summary.changelogCommits = commits.length;
+    if (dryRun) {
+      info(`[dry-run] Would generate CHANGELOG.md from ${commits.length} commit(s)`);
+    } else if (commits.length > 0) {
+      await generateChangelog({ path: basePath, model: opts.model || config.model });
+    } else {
+      warn('No commits found for changelog.');
+    }
+
+    // Step 4: README
+    try {
+      const existing = await readFile(join(basePath, 'README.md'), 'utf-8');
+      summary.readmeAction = 'update';
+    } catch {
+      summary.readmeAction = 'create';
+    }
+    if (dryRun) {
+      info(`[dry-run] Would ${summary.readmeAction} README.md`);
+    } else {
+      await generateReadme(detection, { path: basePath, docsPath });
+    }
+
+    // Step 5: Archive deprecated
+    const resolvedDocsPath = resolve(basePath, docsPath);
+    if (dryRun) {
+      info('[dry-run] Would check for deprecated documentation to archive');
+    } else {
+      const { moved } = await archiveDeprecated(resolvedDocsPath, basePath);
+      summary.deprecated = moved.length;
+      if (moved.length > 0) {
+        info(`Archived ${moved.length} deprecated doc(s)`);
+      }
+    }
+  }
+
+  // Summary
+  header('Document Summary');
+  if (!markdownOnly) info(`Inline docs: ${summary.inlineFiles} source file(s)`);
+  if (!inlineOnly) {
+    info(`Markdown files: ${summary.markdownFiles || 'generated'}`);
+    info(`Changelog: ${summary.changelogCommits} commit(s)`);
+    info(`README: ${summary.readmeAction}`);
+    if (summary.deprecated > 0) info(`Deprecated: ${summary.deprecated} archived`);
+  }
+
+  if (dryRun) {
+    success('Dry run complete — no changes made');
+  } else {
+    success('Documentation pass complete');
+  }
+}