docutrack 0.1.1 → 0.1.6

package/README.md

@@ -7,7 +7,6 @@
 [![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)
 
 </div>
 
@@ -19,139 +18,145 @@ Claude Code edits 30 files in a session. When it's done, none of them have updat
 
 ## 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.
+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.
+
+---
+
+## Install once, use everywhere
 
 ```bash
-npx docutrack init
+npm install -g docutrack
+docutrack install-global
 ```
 
-That's it. From that point on, every file your AI agent touches gets documented.
+`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
 
-## How it works
+After this, you never think about DocuTrack again — Claude handles the rest.
 
-```
-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:
+## How it works per project
 
-- **PostToolUse** — fires after every file edit, queues the file
-- **Stop** — fires at end of session, triggers the documentalista subagent
+### The recommended flow — let Claude do it
 
----
+Open any project in Claude Code and ask:
 
-## Web viewer
+> *"Build me an inventory API and use docutrack for documentation"*
 
-Run `docutrack serve` to open a Notion-like documentation viewer at `http://localhost:4242`:
+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`
 
-- **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
+### The manual flow — you control the init
 
-### Bootstrapping an existing project
+```bash
+cd my-project
+docutrack init        # interactive questionnaire in the terminal
+```
 
-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.
+Then open Claude Code. It reads `CLAUDE.md`, sees pending files, and documents everything without being asked.
 
 ---
 
-## Quick start
+## The questionnaire
 
-```bash
-# Initialize in your project
-npx docutrack init
+Whether run interactively or via Claude, DocuTrack asks four questions before setting up:
 
-# Open the documentation viewer
-docutrack serve
-# → http://localhost:4242
+| 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` |
 
-# Check documentation health
-docutrack check
-```
+These preferences are saved to `docutrack.config.json` and used by every documentation run.
+
+---
 
-To use AI generation, set your Anthropic API key:
+## What gets generated
 
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
-# or add it to .env.local in your project
+```
+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
 ```
 
 ---
 
+## The web viewer
+
+`docutrack serve` opens a local documentation browser at `http://localhost:4242`:
+
+- 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
+
+---
+
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `docutrack init` | Initialize DocuTrack in the current project |
-| `docutrack serve` | Open the web viewer at port 4242 |
+| `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 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 |
+| `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 |
 
 ---
 
 ## Stack templates
 
-DocuTrack auto-detects your stack from `package.json`, `go.mod`, etc. You can also specify it manually:
+DocuTrack auto-detects your stack from `package.json`, `go.mod`, etc.
 
 ```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
+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
 ```
 
-Each template ships with a stack-specific `documentalista` subagent that understands your framework's conventions.
-
 ---
 
-## What gets generated
+## How the hooks work
 
-```
-docs/
-├── 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
-```
-
----
+DocuTrack registers two hooks globally (via `install-global`) and per-project (via `init`):
 
-## Zero dependencies
+- **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
 
-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`.
+The global hooks silently skip projects that haven't been initialized. No noise in other projects.
 
 ---
 
 ## Requirements
 
 - Node.js 18+
-- [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.
+- [Claude Code](https://claude.ai/code)
 
 ---
 

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,14 +1,16 @@
 {
   "name": "docutrack",
-  "version": "0.1.1",
-  "description": "Claude Code plugin that forces AI agents to document what they build — automatically.",
+  "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"
+    "developer-tools",
+    "living-docs",
+    "docutrack"
   ],
   "license": "MIT",
   "type": "commonjs",