docutrack 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 novolabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,116 +1,160 @@
+<div align="center">
+
 # DocuTrack
 
-**Plugin de Claude Code que documenta automáticamente lo que construyes.**
+**Your AI agent writes code. DocuTrack makes sure it documents what it builds.**
+
+[![npm version](https://img.shields.io/npm/v/docutrack?color=6366f1&label=npm)](https://www.npmjs.com/package/docutrack)
+[![License: MIT](https://img.shields.io/badge/license-MIT-6366f1)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-6366f1)](https://nodejs.org)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-6366f1)](CONTRIBUTING.md)
 
-DocuTrack engancha los lifecycle hooks de Claude Code para registrar cada archivo modificado y generar documentación técnica en tiempo real — sin interrumpir tu flujo de trabajo.
+</div>
 
 ---
 
-## Instalación
+## The problem
+
+Claude Code edits 30 files in a session. When it's done, none of them have updated documentation. You end up with a codebase that works but no one understands — including you, three months later.
+
+## The solution
+
+DocuTrack hooks into Claude Code's lifecycle events to automatically queue every modified file and generate technical documentation using AI — without interrupting your workflow.
 
 ```bash
 npx docutrack init
 ```
 
-Detecta tu stack automáticamente (Next.js, FastAPI, Express, Go, monorepo) y configura todo en segundos.
+That's it. From that point on, every file your AI agent touches gets documented.
 
 ---
 
-## ¿Qué hace?
+## How it works
+
+```
+Claude edits a file
+       ↓
+PostToolUse hook fires → file added to .docutrack/queue.json
+       ↓
+Session ends → documentalista subagent runs
+       ↓
+Docs written to docs/modules/ and docs/api/
+       ↓
+docutrack serve → beautiful web viewer at localhost:4242
+```
+
+DocuTrack installs two hooks in your Claude Code settings:
 
-- **Hook PostToolUse** — cada vez que Claude edita un archivo, lo encola automáticamente
-- **Hook Stop** — al terminar la sesión, el subagente `documentalista` genera los docs de todo lo pendiente
-- **Visor web** — interfaz tipo Notion en `localhost:4242` con sidebar, renderizado Markdown, API Explorer interactivo y Health Check
-- **Generación con IA** — escanea proyectos existentes y genera toda la documentación con un clic desde el visor
-- **Sin dependencias** — llama a la API de Anthropic directo via `https` nativo de Node.js
+- **PostToolUse** — fires after every file edit, queues the file
+- **Stop** — fires at end of session, triggers the documentalista subagent
 
 ---
 
-## Uso rápido
+## Web viewer
+
+Run `docutrack serve` to open a Notion-like documentation viewer at `http://localhost:4242`:
+
+- **Modules** — auto-generated docs for every source file
+- **Architecture** — AI-generated overview of your tech stack, structure, and data flow
+- **API Explorer** — interactive Swagger-like explorer built from your route files
+- **Decisions** — Architecture Decision Records (ADRs)
+- **Health Check** — drift analysis, complexity heatmap, stale doc detection
+- **Multilingual** — generates docs in Spanish or English, switchable from the UI
+
+### Bootstrapping an existing project
+
+Already have a codebase? No problem. Open the viewer and click **"✨ Regenerate docs"** — DocuTrack scans all your source files and generates documentation for everything, no terminal needed.
+
+---
+
+## Quick start
 
 ```bash
-# Inicializar en tu proyecto
+# Initialize in your project
 npx docutrack init
 
-# Abrir el visor de documentación
+# Open the documentation viewer
 docutrack serve
+# → http://localhost:4242
 
-# Escanear un proyecto existente y generar docs
-# → Usar el botón "Regenerar docs" en el visor
+# Check documentation health
+docutrack check
+```
 
-# Ver estado de cobertura
-docutrack status
+To use AI generation, set your Anthropic API key:
 
-# Health check completo (drift, complejidad, stale)
-docutrack check
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+# or add it to .env.local in your project
 ```
 
 ---
 
-## Comandos
+## Commands
 
-| Comando | Descripción |
+| Command | Description |
 |---------|-------------|
-| `docutrack init` | Inicializa DocuTrack en el proyecto actual |
-| `docutrack serve` | Abre el visor web en el puerto 4242 |
-| `docutrack scan` | Encola todos los archivos fuente existentes |
-| `docutrack status` | Muestra cobertura, pendientes y docs desactualizados |
-| `docutrack check` | Health check: drift, complejidad, stale |
-| `docutrack analyze` | Detecta rutas y genera `docs/api/openapi.json` |
-| `docutrack onboard` | Genera `docs/ONBOARDING.md` |
-| `docutrack export` | Exporta a Mintlify o Docusaurus |
-| `docutrack badge` | Genera badge SVG de cobertura |
+| `docutrack init` | Initialize DocuTrack in the current project |
+| `docutrack serve` | Open the web viewer at port 4242 |
+| `docutrack scan` | Queue all existing source files for documentation |
+| `docutrack status` | Show coverage, pending files, and stale docs |
+| `docutrack check` | Full health check: drift, complexity, stale |
+| `docutrack analyze` | Auto-detect routes and generate `docs/api/openapi.json` |
+| `docutrack onboard` | Generate `docs/ONBOARDING.md` for new team members |
+| `docutrack export` | Export to Mintlify or Docusaurus format |
+| `docutrack badge` | Generate coverage badge SVG for your README |
 
 ---
 
-## Templates soportados
+## Stack templates
 
-Detección automática o manual con `--template`:
+DocuTrack auto-detects your stack from `package.json`, `go.mod`, etc. You can also specify it manually:
 
-- `nextjs` — Next.js App Router
-- `fastapi` — Python FastAPI
-- `express` — Node.js Express / Fastify
-- `monorepo` — Turborepo / pnpm workspaces
-- `go` — Go modules
+```bash
+docutrack init --template nextjs    # Next.js App Router
+docutrack init --template fastapi   # Python FastAPI
+docutrack init --template express   # Node.js Express / Fastify
+docutrack init --template monorepo  # Turborepo / pnpm workspaces
+docutrack init --template go        # Go modules
+```
+
+Each template ships with a stack-specific `documentalista` subagent that understands your framework's conventions.
 
 ---
 
-## Estructura generada
+## What gets generated
 
 ```
 docs/
-├── modules/        ← un .md por módulo/componente
-├── api/            ← docs de rutas API + openapi.json
-└── decisions/      ← Architecture Decision Records (ADRs)
-ARCHITECTURE.md     ← vista general del proyecto (auto-generada con IA)
+├── modules/          ← one .md per source file (responsibility, exports, dependencies)
+├── api/              ← one .md per API route + openapi.json
+└── decisions/        ← Architecture Decision Records
+ARCHITECTURE.md       ← AI-generated: tech stack, app structure, data flow, module map
+docs/ONBOARDING.md    ← AI-generated: setup guide, conventions, key modules
 ```
 
 ---
 
-## Visor web
-
-```bash
-docutrack serve
-# → http://localhost:4242
-```
+## Zero dependencies
 
-Incluye:
-- Sidebar con todos los módulos, decisiones y rutas API
-- **API Explorer** interactivo estilo Swagger
-- **Health Check**: drift de código vs docs, mapa de complejidad
-- **Generación desde la UI**: escanea y documenta sin abrir la terminal
-- Toggle de idioma Español / English
+DocuTrack calls the Anthropic API directly using Node.js built-in `https` — no SDK, no extra packages to install, nothing added to your `node_modules`.
 
 ---
 
-## Requisitos
+## Requirements
 
 - Node.js 18+
-- Claude Code CLI
-- `ANTHROPIC_API_KEY` en el entorno o en `.env.local` (solo para generación con IA)
+- [Claude Code](https://claude.ai/code) CLI
+- `ANTHROPIC_API_KEY` (only required for AI doc generation)
+
+---
+
+## Contributing
+
+Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
 
 ---
 
-## Licencia
+## License
 
-MIT — [mnovoaq](https://github.com/mnovoaq)
+MIT © [novolabs](https://github.com/mnovoaq)

package/package.json

@@ -1,38 +1,38 @@
-{
-  "name": "docutrack",
-  "version": "0.1.0",
-  "description": "Claude Code plugin that forces AI agents to document what they build — automatically.",
-  "keywords": [
-    "claude-code",
-    "claude",
-    "documentation",
-    "ai-agents",
-    "architecture",
-    "developer-tools"
-  ],
-  "license": "MIT",
-  "type": "commonjs",
-  "main": "./bin/docutrack.js",
-  "bin": {
-    "docutrack": "bin/docutrack.js"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "templates/"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mnovoaq/docutrack.git"
-  },
-  "homepage": "https://github.com/mnovoaq/docutrack#readme",
-  "bugs": {
-    "url": "https://github.com/mnovoaq/docutrack/issues"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "scripts": {
-    "test": "node --test src/**/*.test.js"
-  }
-}
+{
+  "name": "docutrack",
+  "version": "0.1.1",
+  "description": "Claude Code plugin that forces AI agents to document what they build — automatically.",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "documentation",
+    "ai-agents",
+    "architecture",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./bin/docutrack.js",
+  "bin": {
+    "docutrack": "bin/docutrack.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mnovoaq/docutrack.git"
+  },
+  "homepage": "https://github.com/mnovoaq/docutrack#readme",
+  "bugs": {
+    "url": "https://github.com/mnovoaq/docutrack/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test src/utils/queue.test.js src/viewer/server.test.js"
+  }
+}

package/src/utils/queue.js

@@ -23,24 +23,25 @@ function isIgnored(filePath) {
   return IGNORED_PREFIXES.some(prefix => filePath.startsWith(prefix))
 }
 
-function read() {
-  if (!fs.existsSync(QUEUE_PATH)) return { ...EMPTY_QUEUE }
+function read(queuePath = QUEUE_PATH) {
+  if (!fs.existsSync(queuePath)) return { ...EMPTY_QUEUE }
   try {
-    return JSON.parse(fs.readFileSync(QUEUE_PATH, 'utf8'))
+    return JSON.parse(fs.readFileSync(queuePath, 'utf8'))
   } catch {
     return { ...EMPTY_QUEUE }
   }
 }
 
-function write(queue) {
-  fs.writeFileSync(QUEUE_PATH, JSON.stringify(queue, null, 2))
+function write(queue, queuePath = QUEUE_PATH) {
+  fs.mkdirSync(path.dirname(queuePath), { recursive: true })
+  fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2))
 }
 
-function add(filePath) {
+function add(filePath, queuePath = QUEUE_PATH) {
   const normalized = filePath.replace(/\\/g, '/')
   if (isIgnored(normalized)) return
 
-  const queue = read()
+  const queue = read(queuePath)
   const alreadyQueued = queue.pending.some(e => e.file === normalized)
   if (alreadyQueued) return
 
@@ -48,11 +49,11 @@ function add(filePath) {
     file: normalized,
     addedAt: new Date().toISOString(),
   })
-  write(queue)
+  write(queue, queuePath)
 }
 
-function clear() {
-  write({ pending: [], lastClear: new Date().toISOString() })
+function clear(queuePath = QUEUE_PATH) {
+  write({ pending: [], lastClear: new Date().toISOString() }, queuePath)
 }
 
 function pendingCount() {

package/src/utils/queue.test.js

@@ -0,0 +1,54 @@
+'use strict'
+
+const { describe, it, before, after } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+
+const { read, add, clear } = require('./queue')
+
+let tmpDir
+
+before(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'docutrack-test-'))
+})
+
+after(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true })
+})
+
+describe('queue', () => {
+  it('read returns empty queue when file does not exist', () => {
+    const q = read(path.join(tmpDir, 'nonexistent', 'queue.json'))
+    assert.deepEqual(q.pending, [])
+    assert.equal(q.lastClear, null)
+  })
+
+  it('add writes a file to the queue', () => {
+    const qPath = path.join(tmpDir, 'queue.json')
+    add('src/utils/foo.ts', qPath)
+    const q = read(qPath)
+    assert.equal(q.pending.length, 1)
+    assert.equal(q.pending[0].file, 'src/utils/foo.ts')
+    assert.ok(q.pending[0].addedAt)
+  })
+
+  it('add does not duplicate existing entries', () => {
+    const qPath = path.join(tmpDir, 'queue2.json')
+    const existing = { pending: [{ file: 'src/foo.ts', addedAt: new Date().toISOString() }], lastClear: null }
+    fs.writeFileSync(qPath, JSON.stringify(existing, null, 2))
+    add('src/foo.ts', qPath)
+    const q = read(qPath)
+    assert.equal(q.pending.length, 1)
+  })
+
+  it('clear empties the queue', () => {
+    const qPath = path.join(tmpDir, 'queue3.json')
+    add('src/foo.ts', qPath)
+    clear(qPath)
+    const q = read(qPath)
+    assert.equal(q.pending.length, 0)
+    assert.ok(q.lastClear)
+  })
+})

package/src/viewer/index.html

@@ -287,6 +287,37 @@ html, body { height: 100%; font-family: var(--font); color: var(--text); backgro
 #sidebar::-webkit-scrollbar, #main::-webkit-scrollbar { width: 5px; }
 #sidebar::-webkit-scrollbar-thumb, #main::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
 @media (max-width: 768px) { #app { grid-template-columns: 1fr; } #sidebar { display: none; } #doc-wrap { padding: 24px 20px 60px; } }
+
+/* ── Command Palette ── */
+.palette-overlay { position: fixed; inset: 0; background: rgba(0,0,0,.48); z-index: 500; display: none; align-items: flex-start; justify-content: center; padding-top: 14vh; }
+.palette-overlay.open { display: flex; }
+.palette-box { width: 100%; max-width: 560px; background: var(--bg); border: 1px solid var(--border); border-radius: 10px; box-shadow: 0 24px 64px rgba(0,0,0,.28); overflow: hidden; }
+.palette-input-wrap { display: flex; align-items: center; gap: 10px; padding: 14px 16px; border-bottom: 1px solid var(--border); }
+.palette-search-icon { font-size: 16px; color: var(--text-muted); flex-shrink: 0; }
+#palette-input { flex: 1; border: none; outline: none; font-size: 15px; background: transparent; color: var(--text); }
+#palette-input::placeholder { color: var(--text-muted); }
+.palette-esc { font-size: 11px; background: var(--border); color: var(--text-muted); padding: 2px 7px; border-radius: 4px; flex-shrink: 0; cursor: pointer; }
+.palette-results { max-height: 380px; overflow-y: auto; }
+.palette-group-header { font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: .06em; color: var(--text-muted); padding: 8px 16px 4px; background: var(--bg-sidebar); }
+.palette-item { display: flex; align-items: center; gap: 10px; padding: 10px 16px; cursor: pointer; font-size: 13px; border-left: 2px solid transparent; }
+.palette-item.selected { background: var(--bg-active); color: var(--accent); border-left-color: var(--accent); }
+.palette-item-icon { width: 20px; text-align: center; flex-shrink: 0; }
+.palette-item-name { flex: 1; }
+.palette-item-section { font-size: 11px; color: var(--text-muted); flex-shrink: 0; }
+.palette-item-snippet { font-size: 11px; color: var(--text-muted); flex: 1; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 220px; }
+.palette-empty { padding: 32px; text-align: center; color: var(--text-muted); font-size: 13px; }
+.palette-footer { padding: 8px 16px; border-top: 1px solid var(--border); font-size: 11px; color: var(--text-muted); display: flex; gap: 14px; background: var(--bg-sidebar); }
+.palette-footer kbd { background: var(--border); padding: 1px 5px; border-radius: 3px; font-family: var(--font-mono); }
+
+/* ── Copy button ── */
+.code-block-wrap { position: relative; }
+.copy-btn { position: absolute; top: 8px; right: 8px; padding: 3px 9px; border: 1px solid var(--border); border-radius: 4px; background: var(--bg); color: var(--text-muted); font-size: 11px; cursor: pointer; opacity: 0; transition: opacity .15s; z-index: 1; font-family: var(--font); }
+.code-block-wrap:hover .copy-btn { opacity: 1; }
+.copy-btn.copied { color: var(--green-text); border-color: var(--green); background: var(--green-bg); }
+
+/* ── Heading anchors ── */
+.heading-anchor { opacity: 0; margin-left: 6px; font-size: .72em; color: var(--text-muted); text-decoration: none; transition: opacity .15s; vertical-align: middle; }
+h2:hover .heading-anchor, h3:hover .heading-anchor { opacity: 1; }
 </style>
 </head>
 <body>
@@ -369,6 +400,23 @@ html, body { height: 100%; font-family: var(--font); color: var(--text); backgro
 
 </div>
 
+<!-- Command Palette -->
+<div id="palette-overlay" class="palette-overlay" onclick="onPaletteOverlayClick(event)">
+  <div class="palette-box">
+    <div class="palette-input-wrap">
+      <span class="palette-search-icon">🔍</span>
+      <input id="palette-input" placeholder="Search docs, jump to…" autocomplete="off" spellcheck="false">
+      <span class="palette-esc" onclick="closePalette()">ESC</span>
+    </div>
+    <div id="palette-results" class="palette-results"></div>
+    <div class="palette-footer">
+      <span><kbd>↑↓</kbd> navigate</span>
+      <span><kbd>↵</kbd> open</span>
+      <span><kbd>ESC</kbd> close</span>
+    </div>
+  </div>
+</div>
+
 <script src="https://cdn.jsdelivr.net/npm/marked@9/marked.min.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
 <script>
@@ -406,7 +454,12 @@ marked.use({
       if (lang === 'mermaid') {
         return `<div class="mermaid-wrap"><div class="mermaid">${esc(text)}</div></div>`
       }
-      return `<pre><code class="language-${esc(lang||'')}">${esc(text)}</code></pre>`
+      return `<div class="code-block-wrap"><pre><code class="language-${esc(lang||'')}">${esc(text)}</code></pre><button class="copy-btn" onclick="copyCode(this)">Copy</button></div>`
+    },
+    heading({ text, depth }) {
+      if (depth === 1) return `<h1>${text}</h1>\n`
+      const anchor = text.replace(/<[^>]+>/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+      return `<h${depth} id="${anchor}">${text}<a class="heading-anchor" href="#${anchor}" onclick="copyAnchor(this,event)">#</a></h${depth}>\n`
     }
   }
 })
@@ -422,9 +475,25 @@ async function boot() {
     state.query = e.target.value.trim()
     renderNav()
   })
+  document.getElementById('palette-input').addEventListener('input', e => {
+    renderPaletteResults(e.target.value.trim())
+  })
   document.addEventListener('keydown', e => {
-    if ((e.metaKey || e.ctrlKey) && e.key === 'k') { e.preventDefault(); document.getElementById('search').focus() }
-    if (e.key === 'Escape') document.getElementById('search').blur()
+    const palOpen = document.getElementById('palette-overlay').classList.contains('open')
+    if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+      e.preventDefault()
+      palOpen ? closePalette() : openPalette()
+      return
+    }
+    if (e.key === 'Escape') {
+      if (palOpen) { closePalette(); return }
+      document.getElementById('search').blur()
+    }
+    if (palOpen) {
+      if (e.key === 'ArrowDown') { e.preventDefault(); paletteIdx = Math.min(paletteIdx + 1, paletteItems.length - 1); updatePaletteSelection(); scrollPaletteItem() }
+      else if (e.key === 'ArrowUp') { e.preventDefault(); paletteIdx = Math.max(paletteIdx - 1, 0); updatePaletteSelection(); scrollPaletteItem() }
+      else if (e.key === 'Enter') { e.preventDefault(); selectPaletteItem(paletteIdx) }
+    }
   })
 }
 
@@ -664,6 +733,13 @@ async function runScan() {
   await refreshStatus()
 }
 
+function confirmRegen() {
+  const total = state.generationTotal || '?'
+  const lang = state.lang === 'es' ? 'español' : 'inglés'
+  if (!confirm(`¿Regenerar toda la documentación en ${lang}?\n\nEsto sobreescribirá todos los archivos .md existentes.`)) return
+  runGenerate(true)
+}
+
 function setLang(lang) {
   state.lang = lang
   const es = document.getElementById('lang-es')
@@ -743,6 +819,7 @@ async function runGenerate(force = false) {
   state.generationTotal = total
   state.generationDone = 0
   state.generationLog = []
+  state.generationStartMs = Date.now()
 }
 
 function handleProgressEvent(raw) {
@@ -767,7 +844,16 @@ function handleProgressEvent(raw) {
   const log = document.getElementById('gen-log')
 
   if (bar) bar.style.width = `${Math.round((done / total) * 100)}%`
-  if (cnt) cnt.textContent = `${done} / ${total}`
+  if (cnt) {
+    let eta = ''
+    if (done > 2 && state.generationStartMs) {
+      const elapsed = (Date.now() - state.generationStartMs) / 1000
+      const secsPerFile = elapsed / done
+      const remaining = Math.round(secsPerFile * (total - done))
+      eta = remaining > 5 ? ` — ~${remaining}s restantes` : ''
+    }
+    cnt.textContent = `${done} / ${total}${eta}`
+  }
   if (!log) return
 
   const row = document.createElement('div')
@@ -867,7 +953,7 @@ function showRegenPanel() {
         </div>
       </div>
 
-      <button class="bootstrap-btn" id="gen-btn" onclick="runGenerate(true)" style="max-width:300px">
+      <button class="bootstrap-btn" id="gen-btn" onclick="confirmRegen()" style="max-width:300px">
         <span id="gen-btn-icon">✨</span>
         <span id="gen-btn-label">Regenerar todos los docs</span>
       </button>
@@ -1405,6 +1491,150 @@ function statusClass(code) {
   return 'status-2xx'
 }
 
+// ── Command Palette ───────────────────────────────────────────────────────────
+let paletteIdx = 0
+let paletteItems = []
+let paletteSearchTimer = null
+
+function openPalette() {
+  document.getElementById('palette-overlay').classList.add('open')
+  const inp = document.getElementById('palette-input')
+  inp.value = ''
+  inp.focus()
+  renderPaletteResults('')
+}
+
+function closePalette() {
+  document.getElementById('palette-overlay').classList.remove('open')
+}
+
+function onPaletteOverlayClick(e) {
+  if (e.target === document.getElementById('palette-overlay')) closePalette()
+}
+
+function renderPaletteResults(q) {
+  const { tree } = state
+  paletteItems = []
+  const lq = q.toLowerCase()
+
+  if (tree) {
+    if (tree.architecture && (!q || 'architecture'.includes(lq))) {
+      paletteItems.push({ icon: '🏗', name: 'Architecture', section: 'Overview', action: () => loadFile(tree.architecture) })
+    }
+    const addItems = (items, icon, section, fn) => {
+      if (!items?.length) return
+      for (const item of items) {
+        const name = fmtName(item.name)
+        if (!q || name.toLowerCase().includes(lq) || item.name.toLowerCase().includes(lq)) {
+          paletteItems.push({ icon, name, section, action: () => fn(item) })
+        }
+      }
+    }
+    addItems(tree.modules, '📦', 'Modules', m => loadFile(m.path))
+    addItems(tree.decisions, '📝', 'Decisions', d => loadFile(d.path))
+    addItems(tree.api, '📄', 'API', a => loadFile(a.path))
+  }
+  if (!q || 'api explorer'.includes(lq)) paletteItems.push({ icon: '⚡', name: 'API Explorer', section: 'Views', action: showApiExplorer })
+  if (!q || 'health check'.includes(lq)) paletteItems.push({ icon: '🩺', name: 'Health Check', section: 'Views', action: showHealthCheck })
+  if (!q || 'regenerate docs'.includes(lq)) paletteItems.push({ icon: '✨', name: 'Regenerate docs', section: 'Actions', action: showRegenPanel })
+
+  paintPalette()
+
+  // Debounced content search
+  clearTimeout(paletteSearchTimer)
+  if (q.length >= 2) {
+    paletteSearchTimer = setTimeout(() => fetchContentResults(q), 250)
+  }
+}
+
+async function fetchContentResults(q) {
+  try {
+    const r = await fetch(`/api/search?q=${encodeURIComponent(q)}`)
+    if (!r.ok) return
+    const hits = await r.json()
+    if (!hits.length) return
+    // Append content hits (avoid duplicates with name matches)
+    const existing = new Set(paletteItems.map(i => i._path).filter(Boolean))
+    for (const hit of hits) {
+      if (existing.has(hit.path)) continue
+      paletteItems.push({ icon: '🔎', name: hit.title, section: 'Content', snippet: hit.snippet, _path: hit.path, action: () => loadFile(hit.path) })
+    }
+    paintPalette()
+  } catch { /* ok */ }
+}
+
+function paintPalette() {
+  const container = document.getElementById('palette-results')
+  if (!container) return
+
+  if (!paletteItems.length) {
+    container.innerHTML = '<div class="palette-empty">No results</div>'
+    return
+  }
+
+  const groups = {}
+  for (const item of paletteItems) {
+    if (!groups[item.section]) groups[item.section] = []
+    groups[item.section].push(item)
+  }
+
+  let flatIdx = 0
+  let html = ''
+  for (const [section, items] of Object.entries(groups)) {
+    html += `<div class="palette-group-header">${esc(section)}</div>`
+    for (const item of items) {
+      const i = flatIdx++
+      const sel = i === paletteIdx ? ' selected' : ''
+      html += `<div class="palette-item${sel}" onmouseenter="paletteIdx=${i};updatePaletteSelection()" onclick="selectPaletteItem(${i})">
+        <span class="palette-item-icon">${item.icon}</span>
+        <span class="palette-item-name">${esc(item.name)}</span>
+        ${item.snippet ? `<span class="palette-item-snippet">${esc(item.snippet)}</span>` : `<span class="palette-item-section">${esc(item.section)}</span>`}
+      </div>`
+    }
+  }
+  container.innerHTML = html
+}
+
+function selectPaletteItem(i) {
+  closePalette()
+  paletteItems[i]?.action()
+}
+
+function updatePaletteSelection() {
+  document.querySelectorAll('#palette-results .palette-item').forEach((el, i) => {
+    el.classList.toggle('selected', i === paletteIdx)
+  })
+}
+
+function scrollPaletteItem() {
+  const items = document.querySelectorAll('#palette-results .palette-item')
+  items[paletteIdx]?.scrollIntoView({ block: 'nearest' })
+}
+
+// ── Copy code ────────────────────────────────────────────────────────────────
+function copyCode(btn) {
+  const code = btn.previousElementSibling?.querySelector('code')
+  if (!code) return
+  navigator.clipboard.writeText(code.textContent).then(() => {
+    btn.textContent = '✓ Copied'
+    btn.classList.add('copied')
+    setTimeout(() => { btn.textContent = 'Copy'; btn.classList.remove('copied') }, 1500)
+  }).catch(() => {})
+}
+
+// ── Heading anchors ──────────────────────────────────────────────────────────
+function copyAnchor(a, e) {
+  e.preventDefault()
+  const url = location.href.split('#')[0] + a.getAttribute('href')
+  navigator.clipboard.writeText(url).then(() => {
+    const orig = a.textContent
+    a.textContent = '✓'
+    setTimeout(() => { a.textContent = orig }, 1200)
+  }).catch(() => {
+    location.hash = a.getAttribute('href')
+  })
+}
+
 boot()
 </script>
 </body>

package/src/viewer/server.js

@@ -44,6 +44,7 @@ class DocuTrackServer {
     if (p === '/api/scan' && req.method === 'POST')          return this.serveScan(res)
     if (p === '/api/generate' && req.method === 'POST')      return this.serveGenerate(res, req)
     if (p === '/api/generate-arch' && req.method === 'POST') return this.serveGenerateArch(res, req)
+    if (p === '/api/search')                                 return this.serveSearch(res, reqUrl.searchParams.get('q'))
     if (p === '/events')                                     return this.serveSSE(req, res)
 
     res.writeHead(404, { 'Content-Type': 'text/plain' })
@@ -572,6 +573,47 @@ Instructions:
       .replace(/\[([^\]]+)\]/g, '{$1}')
   }
 
+  serveSearch(res, q) {
+    res.writeHead(200, { 'Content-Type': 'application/json' })
+    if (!q || q.length < 2) return res.end(JSON.stringify([]))
+
+    const lq = q.toLowerCase()
+    const results = []
+
+    const searchFile = (fullPath, relPath) => {
+      if (results.length >= 8) return
+      try {
+        const content = fs.readFileSync(fullPath, 'utf8')
+        const lc = content.toLowerCase()
+        const idx = lc.indexOf(lq)
+        if (idx === -1) return
+        const start = Math.max(0, idx - 50)
+        const end = Math.min(content.length, idx + lq.length + 100)
+        const snippet = (start > 0 ? '…' : '') + content.slice(start, end).replace(/[#*`\n]/g, ' ').replace(/\s+/g, ' ').trim() + (end < content.length ? '…' : '')
+        const titleMatch = content.match(/^#\s+(.+)/m)
+        const title = titleMatch ? titleMatch[1].trim() : path.basename(relPath, '.md')
+        results.push({ path: relPath.replace(/\\/g, '/'), title, snippet })
+      } catch { /* skip */ }
+    }
+
+    const archPath = path.join(this.root, 'ARCHITECTURE.md')
+    if (fs.existsSync(archPath)) searchFile(archPath, 'ARCHITECTURE.md')
+
+    const walk = (dir) => {
+      if (results.length >= 8 || !fs.existsSync(dir)) return
+      for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (e.isDirectory()) walk(path.join(dir, e.name))
+        else if (e.name.endsWith('.md') && e.name !== '.gitkeep') {
+          const full = path.join(dir, e.name)
+          searchFile(full, path.relative(this.root, full))
+        }
+      }
+    }
+    walk(path.join(this.root, 'docs'))
+
+    res.end(JSON.stringify(results))
+  }
+
   serveSSE(req, res) {
     res.writeHead(200, {
       'Content-Type': 'text/event-stream',

package/src/viewer/server.test.js

@@ -0,0 +1,50 @@
+'use strict'
+
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+
+const DocuTrackServer = require('./server')
+
+const s = new DocuTrackServer('/fake/root', 4242)
+
+describe('moduleDocName', () => {
+  it('drops leading src/ for shallow files', () => {
+    assert.equal(s.moduleDocName('src/utils.ts'), 'utils')
+  })
+
+  it('uses last 2 segments for deeper paths', () => {
+    assert.equal(s.moduleDocName('app/dashboard/SearchBar.tsx'), 'dashboard-SearchBar')
+  })
+
+  it('handles lib/ prefix', () => {
+    assert.equal(s.moduleDocName('lib/rules-engine.ts'), 'rules-engine')
+  })
+
+  it('handles deeply nested paths', () => {
+    assert.equal(s.moduleDocName('src/components/ui/Button.tsx'), 'ui-Button')
+  })
+})
+
+describe('routeDocName', () => {
+  it('converts simple route', () => {
+    assert.equal(s.routeDocName('app/api/documentos/route.ts'), 'documentos')
+  })
+
+  it('strips dynamic segments brackets', () => {
+    assert.equal(s.routeDocName('app/api/documentos/[id]/evaluar/route.ts'), 'documentos-id-evaluar')
+  })
+
+  it('handles nested api routes', () => {
+    assert.equal(s.routeDocName('app/api/metricas/route.ts'), 'metricas')
+  })
+})
+
+describe('fileToApiPath', () => {
+  it('converts dynamic segments to OpenAPI params', () => {
+    assert.equal(s.fileToApiPath('app/api/documentos/[id]/route.ts'), '/api/documentos/{id}')
+  })
+
+  it('handles simple routes', () => {
+    assert.equal(s.fileToApiPath('app/api/status/route.ts'), '/api/status')
+  })
+})