docutrack 0.1.0 → 0.1.6

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,165 @@
+<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)
+
+</div>
+
+---
+
+## 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 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.
+DocuTrack hooks into Claude Code's lifecycle to automatically track every file your AI agent touches. When the session ends, a specialized subagent documents everything — in your language, at your preferred depth.
 
 ---
 
-## Instalación
+## Install once, use everywhere
 
 ```bash
-npx docutrack init
+npm install -g docutrack
+docutrack install-global
 ```
 
-Detecta tu stack automáticamente (Next.js, FastAPI, Express, Go, monorepo) y configura todo en segundos.
+`install-global` does two things:
+
+1. Registers global PostToolUse and Stop hooks in `~/.claude/settings.json` — active in every Claude Code session from now on
+2. Writes a `~/.claude/CLAUDE.md` snippet that teaches Claude how to set up DocuTrack for any project
+
+After this, you never think about DocuTrack again — Claude handles the rest.
 
 ---
 
-## ¿Qué hace?
+## How it works per project
 
-- **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
+### The recommended flow — let Claude do it
 
----
+Open any project in Claude Code and ask:
+
+> *"Build me an inventory API and use docutrack for documentation"*
 
-## Uso rápido
+Claude will:
+1. Ask you four quick questions in the chat (in your language)
+2. Run `docutrack init --lang=… --description="…" --audience=… --depth=…`
+3. Build your project — every file created is queued automatically via the global hooks
+4. At session end, run the documentalista subagent to write all docs
+5. Start the viewer at `http://localhost:4242`
+
+### The manual flow — you control the init
 
 ```bash
-# Inicializar en tu proyecto
-npx docutrack init
+cd my-project
+docutrack init        # interactive questionnaire in the terminal
+```
 
-# Abrir el visor de documentación
-docutrack serve
+Then open Claude Code. It reads `CLAUDE.md`, sees pending files, and documents everything without being asked.
 
-# Escanear un proyecto existente y generar docs
-# → Usar el botón "Regenerar docs" en el visor
+---
 
-# Ver estado de cobertura
-docutrack status
+## The questionnaire
 
-# Health check completo (drift, complejidad, stale)
-docutrack check
-```
+Whether run interactively or via Claude, DocuTrack asks four questions before setting up:
+
+| Question | Options |
+|----------|---------|
+| Documentation language | Spanish, English, or any other |
+| Project description | One sentence |
+| Who reads the docs | `team` · `onboarding` · `mixed` |
+| Documentation depth | `concise` · `standard` · `detailed` |
+
+These preferences are saved to `docutrack.config.json` and used by every documentation run.
 
 ---
 
-## Comandos
+## What gets generated
 
-| Comando | Descripción |
-|---------|-------------|
-| `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 |
+```
+docs/
+├── modules/        ← one .md per source file
+│                      responsibility · public API · dependencies · data shapes · notes
+├── api/            ← one .md per API router + openapi.json
+├── decisions/      ← Architecture Decision Records (ADRs)
+└── ONBOARDING.md   ← assembled guide for new team members
+ARCHITECTURE.md     ← tech stack · module map · data flow · env vars
+```
 
 ---
 
-## Templates soportados
+## The web viewer
 
-Detección automática o manual con `--template`:
+`docutrack serve` opens a local documentation browser at `http://localhost:4242`:
 
-- `nextjs` — Next.js App Router
-- `fastapi` — Python FastAPI
-- `express` — Node.js Express / Fastify
-- `monorepo` — Turborepo / pnpm workspaces
-- `go` — Go modules
+- Browse modules, API docs, decisions, and architecture in one place
+- Full-text search with `Cmd/Ctrl+K`
+- Mermaid diagram rendering
+- Dark/light mode
+- Persistent URLs — reload lands on the same page
 
 ---
 
-## Estructura generada
+## Commands
 
-```
-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)
-```
+| Command | Description |
+|---------|-------------|
+| `docutrack install-global` | **One-time setup** — registers global hooks and Claude instructions |
+| `docutrack init` | Initialize DocuTrack in a project (interactive questionnaire) |
+| `docutrack init --lang=es --description="…" --audience=team --depth=standard` | Non-interactive init (used by Claude Code) |
+| `docutrack init --template <name>` | Init with a specific stack template |
+| `docutrack serve` | Open the web viewer at `http://localhost:4242` |
+| `docutrack scan` | Queue all existing source files for documentation |
+| `docutrack scan --dry-run` | Preview what would be queued |
+| `docutrack status` | Show coverage, pending files, and stale docs |
+| `docutrack status --json` | Machine-readable output for CI |
+| `docutrack clear` | Clear the documentation queue |
+| `docutrack check` | Full health check: drift, complexity, stale docs |
+| `docutrack analyze` | Scan routes and generate `docs/api/openapi.json` |
+| `docutrack onboard` | Generate `docs/ONBOARDING.md` |
+| `docutrack badge` | Generate a coverage badge SVG |
+| `docutrack export --format mintlify` | Export docs to Mintlify format |
+| `docutrack export --format docusaurus` | Export docs to Docusaurus format |
 
 ---
 
-## Visor web
+## Stack templates
+
+DocuTrack auto-detects your stack from `package.json`, `go.mod`, etc.
 
 ```bash
-docutrack serve
-# → http://localhost:4242
+docutrack init --template nextjs     # Next.js App Router
+docutrack init --template fastapi    # Python FastAPI
+docutrack init --template express    # Node.js Express / Fastify / Koa
+docutrack init --template monorepo   # Turborepo / pnpm workspaces
+docutrack init --template go         # Go modules
 ```
 
-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
+---
+
+## How the hooks work
+
+DocuTrack registers two hooks globally (via `install-global`) and per-project (via `init`):
+
+- **PostToolUse** — fires after every Write/Edit, adds the file to `.docutrack/queue.json`
+- **Stop** — fires when the session ends; scans for any files that were missed, then prompts Claude to run the documentalista
+
+The global hooks silently skip projects that haven't been initialized. No noise in other projects.
 
 ---
 
-## 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)
 
 ---
 
-## Licencia
+## License
 
-MIT — [mnovoaq](https://github.com/mnovoaq)
+MIT © [novolabs](https://github.com/mnovoaq)

package/bin/docutrack.js

@@ -1,67 +1,73 @@
-#!/usr/bin/env node
-
-'use strict'
-
-const [, , command, ...args] = process.argv
-
-const commands = {
-  init: () => require('../src/commands/init'),
-  serve: () => require('../src/commands/serve'),
-  analyze: () => require('../src/commands/analyze'),
-  status: () => require('../src/commands/status'),
-  clear: () => require('../src/commands/clear'),
-  badge: () => require('../src/commands/badge'),
-  export: () => require('../src/commands/export'),
-  check: () => require('../src/commands/check'),
-  onboard: () => require('../src/commands/onboard'),
-  scan: () => require('../src/commands/scan'),
-}
-
-if (!command || command === '--help' || command === '-h') {
-  console.log(`
-docutrack — Claude Code documentation plugin
-
-Usage:
-  npx docutrack init                      Initialize DocuTrack in the current project
-  docutrack init --template <name>        Init with a specific stack template
-  docutrack serve                         Start the documentation web viewer (port 4242)
-  docutrack analyze                       Scan routes and generate docs/api/openapi.json
-  docutrack status                        Show coverage, pending files, and stale docs
-  docutrack status --json                 Machine-readable output for CI
-  docutrack badge                         Generate docs/badge.svg for your README
-  docutrack clear                         Clear the documentation queue
-  docutrack export --format mintlify      Export docs to Mintlify format
-  docutrack export --format docusaurus    Export docs to Docusaurus format
-  docutrack export --format <f> --out <dir>   Export to a custom output directory
-  docutrack check                             Full health: drift, complexity, stale docs
-  docutrack check --json                      Machine-readable health report for CI
-  docutrack onboard                           Generate docs/ONBOARDING.md
-  docutrack onboard --force                   Regenerate ONBOARDING.md
-  docutrack scan                              Queue ALL existing source files for initial documentation
-  docutrack scan --dry-run                    Preview what would be queued
-
-Templates (auto-detected from project files):
-  nextjs, fastapi, express, monorepo, go
-
-Options:
-  --help, -h              Show this help message
-  --version, -v           Show version
-`)
-  process.exit(0)
-}
-
-if (command === '--version' || command === '-v') {
-  console.log(require('../package.json').version)
-  process.exit(0)
-}
-
-const handler = commands[command]
-if (!handler) {
-  console.error(`Unknown command: ${command}\nRun "docutrack --help" for usage.`)
-  process.exit(1)
-}
-
-handler().run(args).catch(err => {
-  console.error(`\nError: ${err.message}`)
-  process.exit(1)
-})
+#!/usr/bin/env node
+
+'use strict'
+
+const [, , command, ...args] = process.argv
+
+const commands = {
+  'install-global': () => require('../src/commands/install-global'),
+  setup: () => require('../src/commands/setup'),
+  init: () => require('../src/commands/init'),
+  serve: () => require('../src/commands/serve'),
+  analyze: () => require('../src/commands/analyze'),
+  status: () => require('../src/commands/status'),
+  clear: () => require('../src/commands/clear'),
+  badge: () => require('../src/commands/badge'),
+  export: () => require('../src/commands/export'),
+  check: () => require('../src/commands/check'),
+  onboard: () => require('../src/commands/onboard'),
+  scan: () => require('../src/commands/scan'),
+}
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(`
+docutrack — Claude Code documentation plugin
+
+Usage:
+  docutrack install-global                Install hooks globally — run once after npm install
+  docutrack setup                         One-command setup: init + scan + start viewer
+  docutrack init                          Initialize DocuTrack (runs interactive questionnaire)
+  docutrack init --lang=es --description="<desc>" --audience=team --depth=standard
+                                          Non-interactive init (for Claude Code or CI)
+  docutrack init --template <name>        Init with a specific stack template
+  docutrack serve                         Start the documentation web viewer (port 4242)
+  docutrack analyze                       Scan routes and generate docs/api/openapi.json
+  docutrack status                        Show coverage, pending files, and stale docs
+  docutrack status --json                 Machine-readable output for CI
+  docutrack badge                         Generate docs/badge.svg for your README
+  docutrack clear                         Clear the documentation queue
+  docutrack export --format mintlify      Export docs to Mintlify format
+  docutrack export --format docusaurus    Export docs to Docusaurus format
+  docutrack export --format <f> --out <dir>   Export to a custom output directory
+  docutrack check                             Full health: drift, complexity, stale docs
+  docutrack check --json                      Machine-readable health report for CI
+  docutrack onboard                           Generate docs/ONBOARDING.md
+  docutrack onboard --force                   Regenerate ONBOARDING.md
+  docutrack scan                              Queue ALL existing source files for initial documentation
+  docutrack scan --dry-run                    Preview what would be queued
+
+Templates (auto-detected from project files):
+  nextjs, fastapi, express, monorepo, go
+
+Options:
+  --help, -h              Show this help message
+  --version, -v           Show version
+`)
+  process.exit(0)
+}
+
+if (command === '--version' || command === '-v') {
+  console.log(require('../package.json').version)
+  process.exit(0)
+}
+
+const handler = commands[command]
+if (!handler) {
+  console.error(`Unknown command: ${command}\nRun "docutrack --help" for usage.`)
+  process.exit(1)
+}
+
+handler().run(args).catch(err => {
+  console.error(`\nError: ${err.message}`)
+  process.exit(1)
+})

package/package.json

@@ -1,38 +1,40 @@
-{
-  "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.6",
+  "description": "Claude Code plugin — your AI agent writes code, DocuTrack documents it automatically.",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "documentation",
+    "ai-agents",
+    "architecture",
+    "developer-tools",
+    "living-docs",
+    "docutrack"
+  ],
+  "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"
+  }
+}