docutrack 0.1.0

package/src/commands/export.js

@@ -0,0 +1,182 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const FORMATS = ['mintlify', 'docusaurus']
+
+async function run(args) {
+  if (!fs.existsSync('.docutrack')) {
+    console.log('\nDocuTrack is not initialized. Run "npx docutrack init" first.\n')
+    process.exit(1)
+  }
+
+  const formatArg = args.find(a => a.startsWith('--format='))?.split('=')[1]
+    || (args.indexOf('--format') !== -1 ? args[args.indexOf('--format') + 1] : null)
+
+  const outArg = args.find(a => a.startsWith('--out='))?.split('=')[1]
+    || (args.indexOf('--out') !== -1 ? args[args.indexOf('--out') + 1] : null)
+
+  if (!formatArg || !FORMATS.includes(formatArg)) {
+    console.log(`\nUsage: docutrack export --format <${FORMATS.join('|')}> [--out <dir>]\n`)
+    process.exit(1)
+  }
+
+  const outDir = outArg || `docutrack-${formatArg}`
+
+  if (formatArg === 'mintlify') await exportMintlify(outDir)
+  else if (formatArg === 'docusaurus') await exportDocusaurus(outDir)
+}
+
+// ── Mintlify ──────────────────────────────────────────────────────────────
+async function exportMintlify(outDir) {
+  console.log(`\nExporting to Mintlify format → ${outDir}/\n`)
+
+  const nav = []
+  fs.mkdirSync(outDir, { recursive: true })
+
+  // ARCHITECTURE.md → overview.mdx
+  if (fs.existsSync('ARCHITECTURE.md')) {
+    const content = fs.readFileSync('ARCHITECTURE.md', 'utf8')
+    fs.writeFileSync(path.join(outDir, 'overview.mdx'), `---\ntitle: "Architecture"\ndescription: "System architecture overview"\n---\n\n${content}`)
+    nav.push('overview')
+    console.log('  ✓ overview.mdx')
+  }
+
+  // docs/modules/ → modules/
+  const modulesNav = copySection('docs/modules', path.join(outDir, 'modules'), 'mdx')
+  if (modulesNav.length) {
+    nav.push({ group: 'Modules', pages: modulesNav.map(f => `modules/${f}`) })
+    console.log(`  ✓ modules/ (${modulesNav.length} files)`)
+  }
+
+  // docs/decisions/ → decisions/
+  const decisionsNav = copySection('docs/decisions', path.join(outDir, 'decisions'), 'mdx')
+  if (decisionsNav.length) {
+    nav.push({ group: 'Decisions', pages: decisionsNav.map(f => `decisions/${f}`) })
+    console.log(`  ✓ decisions/ (${decisionsNav.length} files)`)
+  }
+
+  // docs/api/ → api-reference/
+  const apiNav = copySection('docs/api', path.join(outDir, 'api-reference'), 'mdx')
+  if (apiNav.length) {
+    nav.push({ group: 'API Reference', pages: apiNav.map(f => `api-reference/${f}`) })
+    console.log(`  ✓ api-reference/ (${apiNav.length} files)`)
+  }
+
+  // Copy openapi.json if exists
+  if (fs.existsSync('docs/api/openapi.json')) {
+    fs.copyFileSync('docs/api/openapi.json', path.join(outDir, 'openapi.json'))
+    console.log('  ✓ openapi.json')
+  }
+
+  // Generate mint.json
+  const mintJson = {
+    $schema: 'https://mintlify.com/schema.json',
+    name: getProjectName(),
+    logo: { light: '/logo/light.svg', dark: '/logo/dark.svg' },
+    favicon: '/favicon.svg',
+    colors: { primary: '#6366f1', light: '#818cf8', dark: '#4f46e5' },
+    topbarLinks: [],
+    topbarCtaButton: { name: 'GitHub', url: 'https://github.com/your-org/your-repo' },
+    tabs: [],
+    anchors: [],
+    navigation: nav,
+    footerSocials: {},
+  }
+  fs.writeFileSync(path.join(outDir, 'mint.json'), JSON.stringify(mintJson, null, 2))
+  console.log('  ✓ mint.json')
+  console.log(`\nDone. To preview:\n  cd ${outDir} && npx mintlify dev\n`)
+}
+
+// ── Docusaurus ─────────────────────────────────────────────────────────────
+async function exportDocusaurus(outDir) {
+  console.log(`\nExporting to Docusaurus format → ${outDir}/\n`)
+
+  const docsDir = path.join(outDir, 'docs')
+  fs.mkdirSync(docsDir, { recursive: true })
+
+  const sidebar = {}
+
+  // ARCHITECTURE.md → docs/overview.md
+  if (fs.existsSync('ARCHITECTURE.md')) {
+    const content = fs.readFileSync('ARCHITECTURE.md', 'utf8')
+    fs.writeFileSync(path.join(docsDir, 'overview.md'), `---\nsidebar_position: 1\n---\n\n${content}`)
+    console.log('  ✓ docs/overview.md')
+  }
+
+  // docs/modules/ → docs/modules/
+  const modulesItems = copySection('docs/modules', path.join(docsDir, 'modules'), 'md')
+  if (modulesItems.length) {
+    sidebar.modules = { label: 'Modules', items: modulesItems }
+    console.log(`  ✓ docs/modules/ (${modulesItems.length} files)`)
+  }
+
+  // docs/decisions/ → docs/decisions/
+  const decisionsItems = copySection('docs/decisions', path.join(docsDir, 'decisions'), 'md')
+  if (decisionsItems.length) {
+    sidebar.decisions = { label: 'Decisions', items: decisionsItems }
+    console.log(`  ✓ docs/decisions/ (${decisionsItems.length} files)`)
+  }
+
+  // docs/api/ → docs/api/
+  const apiItems = copySection('docs/api', path.join(docsDir, 'api'), 'md')
+  if (apiItems.length) {
+    sidebar.api = { label: 'API', items: apiItems }
+    console.log(`  ✓ docs/api/ (${apiItems.length} files)`)
+  }
+
+  // sidebars.js
+  const sidebarJs = `/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebars = {
+  docs: [
+    'overview',
+    ${sidebar.modules ? `{ type: 'category', label: 'Modules', items: ${JSON.stringify(sidebar.modules.items.map(f => `modules/${f}`))} },` : ''}
+    ${sidebar.decisions ? `{ type: 'category', label: 'Decisions', items: ${JSON.stringify(sidebar.decisions.items.map(f => `decisions/${f}`))} },` : ''}
+    ${sidebar.api ? `{ type: 'category', label: 'API', items: ${JSON.stringify(sidebar.api.items.map(f => `api/${f}`))} },` : ''}
+  ],
+}
+module.exports = sidebars`
+  fs.writeFileSync(path.join(outDir, 'sidebars.js'), sidebarJs)
+
+  // Minimal docusaurus.config.js
+  const name = getProjectName()
+  const config = `/** @type {import('@docusaurus/types').Config} */
+const config = {
+  title: '${name}',
+  tagline: 'Generated by DocuTrack',
+  url: 'https://your-domain.com',
+  baseUrl: '/',
+  onBrokenLinks: 'warn',
+  onBrokenMarkdownLinks: 'warn',
+  i18n: { defaultLocale: 'en', locales: ['en'] },
+  presets: [['classic', { docs: { sidebarPath: require.resolve('./sidebars.js'), routeBasePath: '/' }, blog: false, theme: { customCss: [] } }]],
+  themeConfig: { navbar: { title: '${name}', items: [] }, footer: { style: 'dark', copyright: 'Generated by DocuTrack' } },
+}
+module.exports = config`
+  fs.writeFileSync(path.join(outDir, 'docusaurus.config.js'), config)
+  console.log('  ✓ docusaurus.config.js + sidebars.js')
+  console.log(`\nDone. To preview:\n  cd ${outDir} && npx create-docusaurus@latest . classic --skip-install && npm install && npm start\n`)
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+function copySection(srcDir, destDir, ext) {
+  const files = []
+  if (!fs.existsSync(srcDir)) return files
+  fs.mkdirSync(destDir, { recursive: true })
+  for (const entry of fs.readdirSync(srcDir)) {
+    if (!entry.endsWith('.md') || entry === '.gitkeep') continue
+    const base = entry.replace('.md', '')
+    const content = fs.readFileSync(path.join(srcDir, entry), 'utf8')
+    const destFile = `${base}.${ext}`
+    fs.writeFileSync(path.join(destDir, destFile), content)
+    files.push(base)
+  }
+  return files
+}
+
+function getProjectName() {
+  try { return JSON.parse(fs.readFileSync('package.json', 'utf8')).name || 'Project' } catch { return 'Project' }
+}
+
+module.exports = { run }

package/src/commands/init.js

@@ -0,0 +1,182 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { installHooks, SETTINGS_PATH } = require('../utils/settings')
+
+const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates')
+const VALID_TEMPLATES = ['nextjs', 'fastapi', 'express', 'monorepo', 'go']
+
+function copyFile(src, dest) {
+  const dir = path.dirname(dest)
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+  fs.copyFileSync(src, dest)
+}
+
+function copyDir(src, dest) {
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true })
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name)
+    const destPath = path.join(dest, entry.name)
+    if (entry.isDirectory()) copyDir(srcPath, destPath)
+    else copyFile(srcPath, destPath)
+  }
+}
+
+function step(msg) { process.stdout.write(`  ${msg}\n`) }
+
+function autoDetectTemplate() {
+  // Node.js: check package.json
+  try {
+    const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'))
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+    if (deps.next) return 'nextjs'
+    if (pkg.workspaces || fs.existsSync('pnpm-workspace.yaml') || fs.existsSync('turbo.json')) return 'monorepo'
+    if (deps.express || deps['@types/express'] || deps.fastify || deps.koa) return 'express'
+  } catch { /* not a node project */ }
+
+  // Python: check for FastAPI
+  for (const f of ['requirements.txt', 'pyproject.toml', 'Pipfile']) {
+    if (!fs.existsSync(f)) continue
+    const content = fs.readFileSync(f, 'utf8').toLowerCase()
+    if (content.includes('fastapi')) return 'fastapi'
+  }
+
+  // Go
+  if (fs.existsSync('go.mod')) return 'go'
+
+  return null
+}
+
+async function run(args) {
+  console.log('\nDocuTrack — initializing in current project\n')
+
+  // Guard: already initialized
+  if (fs.existsSync('.docutrack')) {
+    console.log('DocuTrack is already initialized in this project.')
+    console.log('Run "docutrack status" to see the current queue.\n')
+    return
+  }
+
+  // Resolve template
+  const templateFlag = args?.find(a => a.startsWith('--template='))?.split('=')[1]
+    || (args?.indexOf('--template') !== -1 ? args[args.indexOf('--template') + 1] : null)
+  const template = (templateFlag && VALID_TEMPLATES.includes(templateFlag))
+    ? templateFlag
+    : autoDetectTemplate()
+
+  if (templateFlag && !VALID_TEMPLATES.includes(templateFlag)) {
+    console.log(`Unknown template: "${templateFlag}". Valid options: ${VALID_TEMPLATES.join(', ')}\n`)
+    process.exit(1)
+  }
+
+  // 1. .docutrack/ structure
+  fs.mkdirSync('.docutrack/hooks', { recursive: true })
+  step('Created .docutrack/')
+
+  // 2. Queue
+  fs.writeFileSync('.docutrack/queue.json', JSON.stringify({ pending: [], lastClear: null }, null, 2))
+  step('Created .docutrack/queue.json')
+
+  // 3. Hook scripts
+  copyFile(path.join(TEMPLATES_DIR, 'hooks', 'post-tool-use.js'), '.docutrack/hooks/post-tool-use.js')
+  copyFile(path.join(TEMPLATES_DIR, 'hooks', 'on-stop.js'), '.docutrack/hooks/on-stop.js')
+  step('Installed hooks → .docutrack/hooks/')
+
+  // 4. /docs structure
+  copyDir(path.join(TEMPLATES_DIR, 'docs'), 'docs')
+  step('Created docs/ (modules/, decisions/, api/)')
+
+  // 5. ARCHITECTURE.md — use stack template if available, else base
+  if (!fs.existsSync('ARCHITECTURE.md')) {
+    const stackArch = template && path.join(TEMPLATES_DIR, 'stacks', template, 'ARCHITECTURE.md')
+    const archSrc = (stackArch && fs.existsSync(stackArch))
+      ? stackArch
+      : path.join(TEMPLATES_DIR, 'ARCHITECTURE.md')
+    copyFile(archSrc, 'ARCHITECTURE.md')
+    step('Created ARCHITECTURE.md' + (template ? ` (${template} template)` : ''))
+  } else {
+    step('ARCHITECTURE.md already exists — skipped')
+  }
+
+  // 6. Slash commands
+  const commandsDir = path.join(TEMPLATES_DIR, 'commands')
+  for (const name of fs.readdirSync(commandsDir)) {
+    copyFile(path.join(commandsDir, name), path.join('.claude', 'commands', name))
+  }
+  step('Installed slash commands → .claude/commands/ (doc-map, arch-review, adr-new, ask-docs)')
+
+  // 7. Documentalista — use stack-specific version if available
+  const stackAgent = template && path.join(TEMPLATES_DIR, 'stacks', template, 'documentalista.md')
+  const agentSrc = (stackAgent && fs.existsSync(stackAgent))
+    ? stackAgent
+    : path.join(TEMPLATES_DIR, 'agents', 'documentalista.md')
+  copyFile(agentSrc, '.claude/agents/documentalista.md')
+  step('Installed documentalista subagent → .claude/agents/documentalista.md' + (template ? ` (${template})` : ''))
+
+  // 8. docutrack.config.json
+  if (!fs.existsSync('docutrack.config.json')) {
+    const cfgSrc = path.join(TEMPLATES_DIR, 'docutrack.config.json')
+    let cfg = JSON.parse(fs.readFileSync(cfgSrc, 'utf8'))
+    if (template) cfg.template = template
+    else delete cfg.template
+    fs.writeFileSync('docutrack.config.json', JSON.stringify(cfg, null, 2))
+    step('Created docutrack.config.json')
+  }
+
+  // 9. Hooks in .claude/settings.json
+  const installed = installHooks()
+  step(installed
+    ? `Registered hooks in ${SETTINGS_PATH}`
+    : `Hooks already registered in ${SETTINGS_PATH} — skipped`)
+
+  // 10. Detect if this is an existing project with source files
+  const hasExistingCode = detectExistingCode()
+
+  // 11. Print next steps
+  const snippetPath = path.join(TEMPLATES_DIR, 'claude-snippet.md')
+  const snippet = fs.readFileSync(snippetPath, 'utf8')
+  copyFile(snippetPath, '.docutrack/claude-snippet.md')
+
+  const templateLine = template
+    ? `\n  Stack template   : ${template}`
+    : ''
+
+  const existingProjectTip = hasExistingCode ? `
+Existing project detected — bootstrap your docs:
+  1. Run: docutrack scan          (queues all source files at once)
+  2. In Claude Code, say: "Run the documentalista to document all pending files"
+  3. Run: docutrack serve         (view the populated docs)
+` : `
+What DocuTrack does from here:
+  • After every file edit → logs the file to .docutrack/queue.json
+  • When the session ends → the documentalista subagent updates the docs
+  • Run "docutrack serve" to open the documentation web viewer
+  • Run "docutrack status" to see coverage, pending, and stale docs
+  • Use /doc-map, /arch-review, /adr-new inside Claude Code sessions
+`
+
+  console.log(`
+Done. DocuTrack is active.${templateLine}
+${existingProjectTip}
+Add this to your CLAUDE.md:
+${'─'.repeat(52)}
+${snippet}${'─'.repeat(52)}
+
+(The snippet is also saved at .docutrack/claude-snippet.md)
+`)
+}
+
+function detectExistingCode() {
+  const SOURCE_DIRS = ['src', 'lib', 'app', 'routes', 'controllers', 'handlers', 'api', 'pkg', 'internal']
+  const SOURCE_EXTS = ['.js', '.ts', '.jsx', '.tsx', '.py', '.go', '.mjs']
+  for (const dir of SOURCE_DIRS) {
+    if (!fs.existsSync(dir)) continue
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isFile() && SOURCE_EXTS.includes(path.extname(entry.name))) return true
+    }
+  }
+  return false
+}
+
+module.exports = { run }

package/src/commands/onboard.js

@@ -0,0 +1,288 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { findStale } = require('../utils/stale')
+
+async function run(args) {
+  if (!fs.existsSync('.docutrack')) {
+    console.log('\nDocuTrack is not initialized. Run "npx docutrack init" first.\n')
+    process.exit(1)
+  }
+
+  const root = process.cwd()
+  const force = args.includes('--force')
+  const outPath = path.join(root, 'docs', 'ONBOARDING.md')
+
+  if (fs.existsSync(outPath) && !force) {
+    console.log(`\nONBOARDING.md already exists. Use --force to regenerate.\n`)
+    console.log(`  Location: ${outPath}\n`)
+    return
+  }
+
+  console.log('\nDocuTrack — generating ONBOARDING.md\n')
+
+  const sections = []
+
+  // ── Project name + description ──────────────────────────
+  const meta = getProjectMeta(root)
+  sections.push(`# ${meta.name} — Onboarding Guide\n\n> Auto-generated by DocuTrack on ${new Date().toISOString().slice(0, 10)}.`)
+
+  // ── What is this project? ───────────────────────────────
+  const arch = readFile(root, 'ARCHITECTURE.md')
+  if (arch) {
+    // Extract intro paragraph (content before first ## header)
+    const intro = arch.split(/^##\s/m)[0].replace(/^#[^\n]*\n/, '').trim()
+    if (intro) {
+      sections.push(`## What Is This?\n\n${intro}`)
+    }
+  }
+
+  // ── Stack + framework ───────────────────────────────────
+  const stackInfo = getStackInfo(root)
+  if (stackInfo) sections.push(`## Stack\n\n${stackInfo}`)
+
+  // ── Setup ───────────────────────────────────────────────
+  const setup = getSetupInstructions(root, meta)
+  sections.push(`## Getting Started\n\n${setup}`)
+
+  // ── Module map ──────────────────────────────────────────
+  const moduleDocs = loadModuleDocs(root)
+  if (moduleDocs.length > 0) {
+    const table = buildModuleTable(moduleDocs)
+    sections.push(`## Module Map\n\n${table}`)
+  }
+
+  // ── API surface ─────────────────────────────────────────
+  const apiInfo = getApiSummary(root)
+  if (apiInfo) sections.push(`## API Surface\n\n${apiInfo}`)
+
+  // ── Architecture highlights ─────────────────────────────
+  if (arch) {
+    const highlights = extractArchSection(arch, ['## Architecture', '## System Design', '## Design'])
+    if (highlights) sections.push(`## Architecture Overview\n\n${highlights}`)
+  }
+
+  // ── ADRs ────────────────────────────────────────────────
+  const adrs = loadAdrs(root)
+  if (adrs.length > 0) {
+    const adrList = adrs.map(a => `- **${a.title}** — ${a.status} · \`${a.file}\``).join('\n')
+    sections.push(`## Key Decisions (ADRs)\n\n${adrList}\n\nRead the full ADRs in \`docs/decisions/\`.`)
+  }
+
+  // ── Documentation health ────────────────────────────────
+  const healthSection = getHealthSummary(root)
+  if (healthSection) sections.push(`## Documentation Health\n\n${healthSection}`)
+
+  // ── Workflow ────────────────────────────────────────────
+  sections.push(`## Development Workflow
+
+1. Make your changes in a feature branch
+2. Run \`docutrack status\` to see what needs documenting
+3. Use the \`/arch-review\` slash command to check coverage
+4. The documentalista subagent will update docs when the session ends
+5. Run \`docutrack check\` to validate doc health before opening a PR
+
+### Useful Commands
+
+\`\`\`bash
+docutrack status          # Coverage, pending files, stale docs
+docutrack check           # Full health check: drift, complexity, stale
+docutrack serve           # Open docs in browser at localhost:4242
+docutrack analyze         # Re-scan API endpoints
+docutrack badge           # Regenerate README badge
+\`\`\`
+
+### Slash Commands (in Claude Code)
+
+| Command | Purpose |
+|---------|---------|
+| \`/doc-map\` | Visual map of all modules and endpoints |
+| \`/arch-review\` | Coverage audit — which files lack docs |
+| \`/adr-new\` | Guided ADR creation wizard |
+| \`/ask-docs\` | Ask a question about the codebase using docs |
+`)
+
+  // ── Write output ────────────────────────────────────────
+  fs.mkdirSync(path.dirname(outPath), { recursive: true })
+  fs.writeFileSync(outPath, sections.join('\n\n---\n\n'))
+
+  console.log(`  ✓ Generated: ${path.relative(root, outPath)}`)
+  console.log(`  ${moduleDocs.length} modules documented`)
+  if (adrs.length > 0) console.log(`  ${adrs.length} ADRs referenced`)
+  console.log(`\nShare this with new contributors or serve it with "docutrack serve".\n`)
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function getProjectMeta(root) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))
+    return { name: pkg.name || path.basename(root), version: pkg.version, description: pkg.description }
+  } catch { /* ok */ }
+  try {
+    const mod = fs.readFileSync(path.join(root, 'go.mod'), 'utf8')
+    const m = mod.match(/^module\s+(\S+)/m)
+    return { name: m?.[1]?.split('/').pop() || path.basename(root), version: null }
+  } catch { /* ok */ }
+  return { name: path.basename(root), version: null }
+}
+
+function getStackInfo(root) {
+  const lines = []
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+    const runtime = `Node.js ${pkg.engines?.node || '18+'}`
+    lines.push(`| Runtime | ${runtime} |`)
+    const fw = deps.next ? 'Next.js' : deps.express ? 'Express' : deps.fastify ? 'Fastify' : deps.koa ? 'Koa' : 'Node.js'
+    lines.push(`| Framework | ${fw} |`)
+    if (pkg.scripts) {
+      const scripts = Object.entries(pkg.scripts).slice(0, 5).map(([k, v]) => `\`npm run ${k}\` — ${v}`).join('<br>')
+      lines.push(`| Scripts | ${scripts} |`)
+    }
+  } catch { /* ok */ }
+  try {
+    const req = fs.readFileSync(path.join(root, 'requirements.txt'), 'utf8')
+    if (req.toLowerCase().includes('fastapi')) {
+      lines.push('| Runtime | Python 3.10+ |')
+      lines.push('| Framework | FastAPI |')
+    }
+  } catch { /* ok */ }
+  try {
+    const mod = fs.readFileSync(path.join(root, 'go.mod'), 'utf8')
+    const ver = mod.match(/^go\s+([\d.]+)/m)?.[1]
+    if (ver) lines.push(`| Runtime | Go ${ver} |`)
+  } catch { /* ok */ }
+
+  if (!lines.length) return null
+  return `| | |\n|---|---|\n${lines.join('\n')}`
+}
+
+function getSetupInstructions(root, meta) {
+  const lines = []
+  const hasPkg = fs.existsSync(path.join(root, 'package.json'))
+  const hasPy = fs.existsSync(path.join(root, 'requirements.txt')) || fs.existsSync(path.join(root, 'pyproject.toml'))
+  const hasGo = fs.existsSync(path.join(root, 'go.mod'))
+
+  lines.push('```bash')
+  lines.push('# Clone the repo')
+  lines.push(`git clone <repo-url> && cd ${meta.name}`)
+
+  if (hasPkg) {
+    lines.push('')
+    lines.push('# Install dependencies')
+    const hasPnpm = fs.existsSync(path.join(root, 'pnpm-lock.yaml'))
+    const hasYarn = fs.existsSync(path.join(root, 'yarn.lock'))
+    lines.push(hasPnpm ? 'pnpm install' : hasYarn ? 'yarn install' : 'npm install')
+  }
+  if (hasPy) {
+    lines.push('')
+    lines.push('# Python setup')
+    lines.push('python -m venv .venv && source .venv/bin/activate')
+    lines.push(fs.existsSync(path.join(root, 'pyproject.toml')) ? 'pip install -e ".[dev]"' : 'pip install -r requirements.txt')
+  }
+  if (hasGo) {
+    lines.push('')
+    lines.push('go mod download')
+  }
+
+  lines.push('```')
+
+  // Check for .env.example
+  if (fs.existsSync(path.join(root, '.env.example'))) {
+    lines.push('\n**Environment variables:**\n```bash\ncp .env.example .env\n# Edit .env with your values\n```')
+  }
+
+  return lines.join('\n')
+}
+
+function loadModuleDocs(root) {
+  const docsDir = path.join(root, 'docs', 'modules')
+  if (!fs.existsSync(docsDir)) return []
+  const modules = []
+  for (const file of fs.readdirSync(docsDir)) {
+    if (!file.endsWith('.md')) continue
+    const content = fs.readFileSync(path.join(docsDir, file), 'utf8')
+    // Extract responsibility line
+    const resp = content.match(/\*\*Responsibility\*\*:?\s*(.+)/)?.[1]?.trim()
+      || content.match(/^##?\s*Responsibility\s*\n+(.+)/m)?.[1]?.trim()
+      || content.split('\n').filter(l => l.trim() && !l.startsWith('#'))[0]?.slice(0, 100)
+    modules.push({ name: file.replace('.md', ''), responsibility: resp || '—', file: `docs/modules/${file}` })
+  }
+  return modules
+}
+
+function buildModuleTable(modules) {
+  const rows = modules.map(m => `| \`${m.name}\` | ${m.responsibility} |`)
+  return `| Module | Responsibility |\n|--------|----------------|\n${rows.join('\n')}`
+}
+
+function getApiSummary(root) {
+  const specPath = path.join(root, 'docs', 'api', 'openapi.json')
+  if (!fs.existsSync(specPath)) return null
+  try {
+    const spec = JSON.parse(fs.readFileSync(specPath, 'utf8'))
+    const pathCount = Object.keys(spec.paths || {}).length
+    if (pathCount === 0) return null
+    const methods = {}
+    for (const p of Object.values(spec.paths)) {
+      for (const m of Object.keys(p)) methods[m] = (methods[m] || 0) + 1
+    }
+    const summary = Object.entries(methods).map(([m, n]) => `${n} ${m.toUpperCase()}`).join(', ')
+    const tags = [...new Set(Object.values(spec.paths).flatMap(p => Object.values(p).flatMap(op => op.tags || [])))]
+    return `**${pathCount} endpoints** (${summary})\\\nGroups: ${tags.map(t => `\`${t}\``).join(', ')}\n\nRun \`docutrack serve\` and open **API Explorer** to try endpoints interactively.`
+  } catch { return null }
+}
+
+function extractArchSection(content, headerNames) {
+  for (const header of headerNames) {
+    const re = new RegExp(`${header.replace('## ', '^## ')}[\\s\\S]*?(?=^## |$)`, 'm')
+    const match = content.match(re)
+    if (match) return match[0].replace(/^## [^\n]*\n/, '').trim().slice(0, 800)
+  }
+  return null
+}
+
+function loadAdrs(root) {
+  const dir = path.join(root, 'docs', 'decisions')
+  if (!fs.existsSync(dir)) return []
+  const adrs = []
+  for (const file of fs.readdirSync(dir)) {
+    if (!file.endsWith('.md') || file === '.gitkeep') continue
+    const content = fs.readFileSync(path.join(dir, file), 'utf8')
+    const title = content.match(/^#\s+(.+)/m)?.[1] || file.replace('.md', '')
+    const status = content.match(/##?\s*Status\s*:?\s*(.+)/i)?.[1]?.trim() || 'Unknown'
+    adrs.push({ file: `docs/decisions/${file}`, title, status })
+  }
+  return adrs.slice(0, 10)
+}
+
+function getHealthSummary(root) {
+  try {
+    const queue = JSON.parse(fs.readFileSync(path.join(root, '.docutrack', 'queue.json'), 'utf8'))
+    const stale = findStale(root)
+    const docCount = countDocs(root)
+    const pending = queue.pending?.length || 0
+    const lines = [
+      `| Metric | Value |`,
+      `|--------|-------|`,
+      `| Documented modules | ${docCount} |`,
+      `| Pending queue | ${pending} files |`,
+      `| Stale docs | ${stale.length} |`,
+    ]
+    return lines.join('\n')
+  } catch { return null }
+}
+
+function countDocs(root) {
+  const d = path.join(root, 'docs', 'modules')
+  if (!fs.existsSync(d)) return 0
+  return fs.readdirSync(d).filter(f => f.endsWith('.md')).length
+}
+
+function readFile(root, file) {
+  try { return fs.readFileSync(path.join(root, file), 'utf8') } catch { return null }
+}
+
+module.exports = { run }