docutrack 0.1.1 → 0.1.6

package/src/commands/init.js

@@ -2,10 +2,96 @@
 
 const fs = require('fs')
 const path = require('path')
+const readline = require('readline')
+const { exec } = require('child_process')
 const { installHooks, SETTINGS_PATH } = require('../utils/settings')
+const { isPortInUse, startServerDaemon, isServerRunning } = require('../utils/daemon')
+const { write: writeQueue } = require('../utils/queue')
+
+// ── Questionnaire strings (bilingual) ─────────────────────────
+const Q = {
+  es: {
+    q2: '  Describe el proyecto en una oración:\n  > ',
+    q3: '\n  ¿Quién lee estos docs?\n  [1] Solo yo / equipo pequeño  (técnico, conciso)\n  [2] Incorporamos devs nuevos  (más contexto y explicación)\n  [3] Mixto\n  > ',
+    q4: '\n  ¿Profundidad de los docs?\n  [1] Conciso   — resumen + API pública\n  [2] Estándar  — + decisiones de diseño y gotchas  (recomendado)\n  [3] Detallado — + ejemplos y contexto completo\n  > ',
+    saved: '✓  Preferencias guardadas',
+  },
+  en: {
+    q2: '  Describe this project in one sentence:\n  > ',
+    q3: '\n  Who reads these docs?\n  [1] Just me / small team  (technical, concise)\n  [2] Onboarding new devs  (more context and explanation)\n  [3] Mixed\n  > ',
+    q4: '\n  Documentation depth?\n  [1] Concise   — summary + public API\n  [2] Standard  — + design decisions and gotchas  (recommended)\n  [3] Detailed  — + examples and full context\n  > ',
+    saved: '✓  Preferences saved',
+  },
+}
+
+function parseFlags(args) {
+  const get = (name) => {
+    const eq = args?.find(a => a.startsWith(`--${name}=`))
+    if (eq) return eq.slice(`--${name}=`.length)
+    const idx = args?.indexOf(`--${name}`)
+    if (idx !== undefined && idx !== -1 && args[idx + 1] && !args[idx + 1].startsWith('--')) return args[idx + 1]
+    return null
+  }
+  return { lang: get('lang'), description: get('description'), audience: get('audience'), depth: get('depth') }
+}
+
+async function runQuestionnaire(args) {
+  // Flags override everything — Claude (or CI) passes these directly
+  const flags = parseFlags(args)
+  if (flags.lang) {
+    const audience = ['onboarding', 'mixed', 'team'].includes(flags.audience) ? flags.audience : 'team'
+    const docDepth  = ['concise', 'detailed', 'standard'].includes(flags.depth) ? flags.depth : 'standard'
+    return { lang: flags.lang, projectDescription: flags.description || '', audience, docDepth }
+  }
+
+  // In non-interactive mode (CI, pipes) without flags: silent defaults
+  if (!process.stdin.isTTY) {
+    return { lang: 'en', projectDescription: '', audience: 'team', docDepth: 'standard' }
+  }
+
+  // Single readline instance for the whole questionnaire
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  const ask = (prompt) => new Promise(resolve => rl.question(prompt, a => resolve(a.trim())))
+
+  console.log('')
+
+  // Q1: Language — always bilingual so any developer understands it
+  const langRaw = await ask(
+    '  Documentation language? / ¿Idioma de la documentación?\n' +
+    '  [1] Español  [2] English  [3] Otro/Other: ___\n' +
+    '  > '
+  )
+
+  let lang
+  const l = langRaw.toLowerCase()
+  if (l === '1' || l.startsWith('es') || l.startsWith('sp')) lang = 'es'
+  else if (l === '2' || l.startsWith('en')) lang = 'en'
+  else lang = langRaw || 'en'
+
+  const s = Q[lang] || Q.en
+
+  // Q2–Q4 in the chosen language
+  const description = await ask('\n' + s.q2)
+  const audRaw     = await ask(s.q3)
+  const depthRaw   = await ask(s.q4)
+
+  rl.close()
+
+  const audience = audRaw === '2' ? 'onboarding' : audRaw === '3' ? 'mixed' : 'team'
+  const docDepth  = depthRaw === '1' ? 'concise'   : depthRaw === '3' ? 'detailed' : 'standard'
+
+  console.log(`\n  ${s.saved}\n`)
+  return { lang, projectDescription: description, audience, docDepth }
+}
 
 const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates')
 const VALID_TEMPLATES = ['nextjs', 'fastapi', 'express', 'monorepo', 'go']
+const PORT = 4242
+
+const SOURCE_DIRS = ['src', 'lib', 'app', 'pkg', 'internal', 'api', 'routes', 'controllers', 'handlers', 'packages']
+const SOURCE_EXTS = new Set(['.js', '.ts', '.mjs', '.jsx', '.tsx', '.py', '.go'])
+const IGNORE_DIRS = new Set(['node_modules', '.next', '.git', 'dist', 'build', '__pycache__', '.docutrack', 'docs', '.worktrees', 'coverage', '.turbo'])
+const IGNORE_RE = [/\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/, /\.d\.ts$/, /\.min\.js$/]
 
 function copyFile(src, dest) {
   const dir = path.dirname(dest)
@@ -25,8 +111,16 @@ function copyDir(src, dest) {
 
 function step(msg) { process.stdout.write(`  ${msg}\n`) }
 
+function openBrowser(url) {
+  try {
+    const cmd = process.platform === 'win32' ? `start "" "${url}"`
+      : process.platform === 'darwin' ? `open "${url}"`
+      : `xdg-open "${url}"`
+    exec(cmd)
+  } catch { /* best-effort */ }
+}
+
 function autoDetectTemplate() {
-  // Node.js: check package.json
   try {
     const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'))
     const deps = { ...pkg.dependencies, ...pkg.devDependencies }
@@ -34,31 +128,65 @@ function autoDetectTemplate() {
     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'
+    if (fs.readFileSync(f, 'utf8').toLowerCase().includes('fastapi')) return 'fastapi'
   }
-
-  // Go
   if (fs.existsSync('go.mod')) return 'go'
-
   return null
 }
 
+function collectSourceFiles(root) {
+  const files = []
+  const seen = new Set()
+  const walk = (dir, depth = 0) => {
+    if (depth > 8 || !fs.existsSync(dir)) return
+    let entries
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        if (!IGNORE_DIRS.has(e.name) && !e.name.startsWith('.')) walk(path.join(dir, e.name), depth + 1)
+      } else if (e.isFile() && SOURCE_EXTS.has(path.extname(e.name).toLowerCase())) {
+        if (!IGNORE_RE.some(re => re.test(e.name))) {
+          const rel = path.relative(root, path.join(dir, e.name)).replace(/\\/g, '/')
+          if (!seen.has(rel)) { seen.add(rel); files.push(rel) }
+        }
+      }
+    }
+  }
+  // Walk from root — handles any project structure, not just known conventions
+  walk(root)
+  return files
+}
+
 async function run(args) {
-  console.log('\nDocuTrack — initializing in current project\n')
+  const root = process.cwd()
+  const noServe = args?.includes('--no-serve')
 
-  // Guard: already initialized
+  // ── 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')
+    // If called again, just ensure server is running
+    if (!noServe) {
+      const portBusy = await isPortInUse(PORT)
+      const alive = isServerRunning(root)
+      if (!portBusy && !alive) {
+        const { pid } = startServerDaemon(root, PORT)
+        await new Promise(r => setTimeout(r, 900))
+        console.log(`\n  DocuTrack viewer → http://localhost:${PORT}  (pid ${pid})\n`)
+        openBrowser(`http://localhost:${PORT}`)
+      } else {
+        console.log(`\n  DocuTrack already active → http://localhost:${PORT}\n`)
+        openBrowser(`http://localhost:${PORT}`)
+      }
+    } else {
+      console.log('\n  DocuTrack already initialized. Run "docutrack status" to see the queue.\n')
+    }
     return
   }
 
-  // Resolve template
+  console.log('\n  DocuTrack — setting up your project\n  ' + '─'.repeat(42))
+
+  // ── 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))
@@ -66,117 +194,154 @@ async function run(args) {
     : autoDetectTemplate()
 
   if (templateFlag && !VALID_TEMPLATES.includes(templateFlag)) {
-    console.log(`Unknown template: "${templateFlag}". Valid options: ${VALID_TEMPLATES.join(', ')}\n`)
+    console.error(`Unknown template: "${templateFlag}". Valid options: ${VALID_TEMPLATES.join(', ')}\n`)
     process.exit(1)
   }
 
-  // 1. .docutrack/ structure
+  // ── 1. .docutrack/ structure ───────────────────────────────────
   fs.mkdirSync('.docutrack/hooks', { recursive: true })
-  step('Created .docutrack/')
+  step('✓  Created .docutrack/')
 
-  // 2. Queue
+  // ── 2. Queue ───────────────────────────────────────────────────
   fs.writeFileSync('.docutrack/queue.json', JSON.stringify({ pending: [], lastClear: null }, null, 2))
-  step('Created .docutrack/queue.json')
 
-  // 3. Hook scripts
+  // ── 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/')
+  step('✓  Installed hooks (PostToolUse + Stop)')
 
-  // 4. /docs structure
+  // ── 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
+  // ── 5. ARCHITECTURE.md ─────────────────────────────────────────
   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')
   }
+  step(`✓  Created docs/ and ARCHITECTURE.md${template ? ` (${template})` : ''}`)
 
-  // 6. Slash commands
+  // ── 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
+  // ── 7. Documentalista subagent ─────────────────────────────────
   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})` : ''))
+  step('✓  Installed slash commands + documentalista subagent')
+
+  // ── 8. Hooks in .claude/settings.json ────────────────────────
+  const installed = installHooks()
+  step(installed
+    ? `✓  Registered hooks in ${SETTINGS_PATH}`
+    : `✓  Hooks already registered`)
+
+  // ── 9. Questionnaire — language, description, audience, depth ─
+  console.log('\n  ' + '─'.repeat(42))
+  const prefs = await runQuestionnaire(args)
 
-  // 8. docutrack.config.json
-  if (!fs.existsSync('docutrack.config.json')) {
+  // ── 10. docutrack.config.json — merge template + prefs ────────
+  {
     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
+    cfg.lang = prefs.lang
+    cfg.projectDescription = prefs.projectDescription
+    cfg.audience = prefs.audience
+    cfg.docDepth = prefs.docDepth
     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
+  // ── 12. Auto-write snippet to CLAUDE.md (with language injected) ─
   const snippetPath = path.join(TEMPLATES_DIR, 'claude-snippet.md')
-  const snippet = fs.readFileSync(snippetPath, 'utf8')
+  const snippetBase = 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)
-`)
-}
+  // Inject the configured language so Claude always knows — without needing to read config.json
+  const LANG_LINE = {
+    es: '> **Idioma de documentación**: Español. Escribe TODA la documentación en español, sin excepción.',
+    en: '> **Documentation language**: English. Write ALL documentation in English.',
+  }
+  const langLine = LANG_LINE[prefs.lang] || `> **Documentation language**: ${prefs.lang}. Write ALL documentation in ${prefs.lang}.`
+  // Insert lang note after the first line (the heading) — avoids em-dash encoding mismatches
+  const snippetLines = snippetBase.split('\n')
+  snippetLines.splice(1, 0, '', langLine)
+  const snippet = snippetLines.join('\n')
 
-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
+  const CLAUDE_MD = 'CLAUDE.md'
+  const SNIPPET_MARKER = 'DocuTrack — documentation auto-pilot'
+  if (!fs.existsSync(CLAUDE_MD)) {
+    fs.writeFileSync(CLAUDE_MD, snippet + '\n')
+    step('✓  Created CLAUDE.md with DocuTrack auto-pilot')
+  } else {
+    const existing = fs.readFileSync(CLAUDE_MD, 'utf8')
+    if (!existing.includes(SNIPPET_MARKER)) {
+      fs.writeFileSync(CLAUDE_MD, existing.trimEnd() + '\n\n---\n\n' + snippet + '\n')
+      step('✓  Added DocuTrack auto-pilot to existing CLAUDE.md')
+    } else {
+      step('✓  CLAUDE.md already has DocuTrack auto-pilot')
     }
   }
-  return false
+
+  // ── 13. Scan existing source files ────────────────────────────
+  const sourceFiles = collectSourceFiles(root)
+  if (sourceFiles.length > 0) {
+    const now = new Date().toISOString()
+    writeQueue({ pending: sourceFiles.map(f => ({ file: f, addedAt: now })), lastClear: null })
+    step(`✓  Scanned ${sourceFiles.length} existing source file(s) — queued for documentation`)
+  } else {
+    step('✓  No existing source files — starting fresh')
+  }
+
+  // ── 14. Start viewer server ────────────────────────────────────
+  if (!noServe) {
+    const portBusy = await isPortInUse(PORT)
+    if (!portBusy) {
+      const { pid } = startServerDaemon(root, PORT)
+      await new Promise(r => setTimeout(r, 900))
+      step(`✓  Viewer started → http://localhost:${PORT}  (pid ${pid})`)
+      openBrowser(`http://localhost:${PORT}`)
+    } else {
+      step(`✓  Viewer already running → http://localhost:${PORT}`)
+      openBrowser(`http://localhost:${PORT}`)
+    }
+  }
+
+  // ── Done ───────────────────────────────────────────────────────
+  console.log('\n  ' + '─'.repeat(42))
+
+  // Briefing message — copied to clipboard so the user can paste it into an open Claude session
+  const isEs = prefs.lang === 'es'
+  const briefing = isEs
+    ? 'DocuTrack fue inicializado en este proyecto. Revisa el CLAUDE.md actualizado y ejecuta el documentalista para los archivos pendientes. Para el resto de esta sesión documenta manualmente cada archivo nuevo que crees.'
+    : 'DocuTrack was just initialized in this project. Read the updated CLAUDE.md and run the documentalista for pending files. For the rest of this session, manually document each new file you create.'
+
+  copyToClipboard(briefing)
+
+  const queueNote = sourceFiles.length > 0
+    ? (isEs ? `${sourceFiles.length} archivo(s) en cola.` : `${sourceFiles.length} file(s) queued.`)
+    : (isEs ? 'Listo para nuevos archivos.' : 'Ready for new files.')
+
+  console.log(isEs
+    ? `\n  DocuTrack listo. ${queueNote}\n\n  Si ya tienes Claude Code abierto en este proyecto, pega esto (ya está en el portapapeles):\n\n  ${briefing}\n\n  Si no, abre Claude Code — documentará todo automáticamente.\n`
+    : `\n  DocuTrack ready. ${queueNote}\n\n  If Claude Code is already open in this project, paste this (already in clipboard):\n\n  ${briefing}\n\n  Otherwise, open Claude Code — it will document everything automatically.\n`
+  )
+}
+
+function copyToClipboard(text) {
+  try {
+    const { spawnSync } = require('child_process')
+    if (process.platform === 'win32') spawnSync('clip', [], { input: text, encoding: 'utf8' })
+    else if (process.platform === 'darwin') spawnSync('pbcopy', [], { input: text, encoding: 'utf8' })
+  } catch { /* best-effort */ }
 }
 
 module.exports = { run }

package/src/commands/install-global.js

@@ -0,0 +1,93 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+
+const GLOBAL_SETTINGS  = path.join(os.homedir(), '.claude', 'settings.json')
+const GLOBAL_CLAUDE_MD = path.join(os.homedir(), '.claude', 'CLAUDE.md')
+const MARKER = '<!-- docutrack -->'
+
+const GLOBAL_SNIPPET = `
+## DocuTrack — documentation auto-pilot
+
+DocuTrack is installed globally on this machine. When a user asks to use DocuTrack,
+or asks to build a project "with docutrack" or "with documentation":
+
+**Step 1 — ask these questions in the chat** (in the user's language):
+1. Documentation language? (e.g. Español, English, Português…)
+2. Describe the project in one sentence
+3. Who reads the docs? → \`team\` (technical) / \`onboarding\` (new devs) / \`mixed\`
+4. Documentation depth? → \`concise\` / \`standard\` / \`detailed\`
+
+**Step 2 — run init with the answers as flags:**
+\`\`\`bash
+docutrack init --lang=<es|en|…> --description="<desc>" --audience=<team|onboarding|mixed> --depth=<concise|standard|detailed>
+\`\`\`
+
+**Step 3 — build the project normally.**
+Files you create will be queued automatically. When the session ends, run the
+documentalista subagent to document everything.
+
+If the project already has \`.docutrack/\` (already initialized), skip to Step 3.
+`
+
+async function run() {
+  const hooksDir    = path.join(__dirname, '..', 'hooks')
+  const postHookPath = path.join(hooksDir, 'global-post-tool-use.js')
+  const stopHookPath = path.join(hooksDir, 'global-on-stop.js')
+  const dir = path.dirname(GLOBAL_SETTINGS)
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+
+  // ── 1. settings.json — hooks ───────────────────────────────────
+  let settings = {}
+  if (fs.existsSync(GLOBAL_SETTINGS)) {
+    try { settings = JSON.parse(fs.readFileSync(GLOBAL_SETTINGS, 'utf8')) } catch {}
+  }
+
+  const hooksAlreadyInstalled = settings?.hooks?.PostToolUse?.some(h =>
+    h.hooks?.some(c => c.command?.includes('global-post-tool-use'))
+  )
+
+  if (!hooksAlreadyInstalled) {
+    if (!settings.hooks) settings.hooks = {}
+    if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = []
+    settings.hooks.PostToolUse.push({
+      matcher: 'Write|Edit|MultiEdit',
+      hooks: [{ type: 'command', command: `node "${postHookPath}"` }],
+    })
+    if (!settings.hooks.Stop) settings.hooks.Stop = []
+    settings.hooks.Stop.push({
+      hooks: [{ type: 'command', command: `node "${stopHookPath}"` }],
+    })
+    fs.writeFileSync(GLOBAL_SETTINGS, JSON.stringify(settings, null, 2))
+    console.log(`  ✓  Hooks registered → ${GLOBAL_SETTINGS}`)
+  } else {
+    console.log(`  ✓  Hooks already registered`)
+  }
+
+  // ── 2. CLAUDE.md — global instructions ────────────────────────
+  const claudeMdAlreadyInstalled = fs.existsSync(GLOBAL_CLAUDE_MD) &&
+    fs.readFileSync(GLOBAL_CLAUDE_MD, 'utf8').includes(MARKER)
+
+  if (!claudeMdAlreadyInstalled) {
+    const existing = fs.existsSync(GLOBAL_CLAUDE_MD)
+      ? fs.readFileSync(GLOBAL_CLAUDE_MD, 'utf8').trimEnd() + '\n\n---\n'
+      : ''
+    fs.writeFileSync(GLOBAL_CLAUDE_MD, existing + MARKER + GLOBAL_SNIPPET)
+    console.log(`  ✓  Global instructions written → ${GLOBAL_CLAUDE_MD}`)
+  } else {
+    console.log(`  ✓  Global instructions already present`)
+  }
+
+  console.log(`
+  DocuTrack is ready globally.
+
+  From now on, in any Claude Code session just say:
+  "build me X and use docutrack for documentation"
+
+  Claude will ask for your preferences and set everything up automatically.
+`)
+}
+
+module.exports = { run }

package/src/commands/scan.js

@@ -4,7 +4,7 @@ const fs = require('fs')
 const path = require('path')
 const { write: writeQueue, read: readQueue } = require('../utils/queue')
 
-const SOURCE_DIRS = ['src', 'lib', 'app', 'pkg', 'internal', 'api', 'routes', 'controllers', 'handlers']
+const SOURCE_DIRS = ['src', 'lib', 'app', 'pkg', 'internal', 'api', 'routes', 'controllers', 'handlers', 'packages']
 const SOURCE_EXTS = new Set(['.js', '.ts', '.mjs', '.jsx', '.tsx', '.py', '.go'])
 const IGNORE_DIRS = new Set(['node_modules', '.next', '.git', 'dist', 'build', '__pycache__', '.docutrack', 'docs', '.worktrees', 'coverage', '.turbo'])
 const IGNORE_PATTERNS = [/\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/, /\.d\.ts$/, /\.min\.js$/]
@@ -24,24 +24,12 @@ async function run(args) {
   const existing = readQueue(root)
   const alreadyQueued = new Set(existing.pending.map(e => e.file))
 
-  // Find all source files
+  // Find all source files — walk from root to handle any project structure
   const files = []
-  for (const dir of SOURCE_DIRS) {
-    const full = path.join(root, dir)
-    if (fs.existsSync(full)) walk(full, files, root)
-  }
-
-  // Also scan root-level source files (index.js, server.js, main.go, etc.)
-  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-    if (entry.isFile() && SOURCE_EXTS.has(path.extname(entry.name))) {
-      const rel = entry.name
-      if (!IGNORE_PATTERNS.some(re => re.test(rel))) files.push(rel)
-    }
-  }
+  walk(root, files, root)
 
   if (files.length === 0) {
     console.log('  No source files found to scan.\n')
-    console.log('  Checked: ' + SOURCE_DIRS.join(', ') + '\n')
     return
   }