# DocPilot

`@bageri/doc-pilot` is a NestJS-based CLI-first MCP package for resolving the right documentation source for dependencies and integrations used in a repo.

The primary path is now:

1. classify package
2. resolve best docs source with layered signals
3. verify quickly
4. read 1-3 useful docs pages
5. optionally cache the confirmed source

Broad local syncing is still supported, but it is now a secondary workflow.

## Hybrid Docs Resolver

The resolver pipeline is confidence-based and retrieval-first:

- Tier 0: package triage (`direct`, `map`, `skip`)
- Tier 1: curated registry
- Tier 2: npm package metadata signals
- Tier 3: ecosystem resolvers
- Tier 4: docs conventions (`/llms.txt`, `/docs`, `/documentation`)
- Tier 5: live search
- Tier 6: verification fetch
- Tier 7: optional local cache in `.agent-doc-sync/resolved-sources.json`

Every resolution result includes:

- source type
- confidence score
- rationale
- canonical package
- docs URL
- resolution status

## MCP Tools

DocPilot exposes resolver-first MCP tools:

- `classify_package(name, rootDir?)`
- `resolve_docs_source(name, version?, sourceUrl?, rootDir?)`
- `compare_docs_sources(name, rootDir?)`
- `refresh_cached_source(name, rootDir?)`
- `search_docs(name, query?, rootDir?)`
- `verify_docs_source(url)`
- `read_docs_page(nameOrUrl, topic?, rootDir?)`
- `cache_docs_source(name, url?, rootDir?)`
- `sync_cached_source(name, rootDir?)`
- `detect_references(taskText, rootDir?, filePaths?)`
- `resolve_task_docs(taskText, rootDir?, filePaths?)`
- `brief_task_docs(taskText, rootDir?, filePaths?)`
- `lookup_docs(question, packageHint?, rootDir?, filePaths?)`
- `ensure_task_docs(taskText, rootDir?, filePaths?)`

Resources include:

- curated registry
- resolved sources cache
- per-package cached resolution entries
- synced local doc indexes when sync has been run

## CLI Usage

```bash
npm install
npm run build

node dist/cli.js classify @nestjs/axios
node dist/cli.js resolve better-auth
node dist/cli.js compare better-auth
node dist/cli.js refresh better-auth
node dist/cli.js search nestjs authentication
node dist/cli.js verify https://docs.stripe.com
node dist/cli.js read prisma migrations
node dist/cli.js task-docs "add JWT auth to this NestJS API"
node dist/cli.js brief "add Stripe checkout flow"
node dist/cli.js lookup "how do I add Stripe checkout here?" --package stripe
node dist/cli.js cache stripe
node dist/cli.js sync stripe
node dist/cli.js mcp
```

## Optional Sync

`sync` is intentionally no longer the main path.

Use it only when a resolved and verified source should also be materialized locally under `docs/`.

## Notes

- MCP stdio mode keeps stdout reserved for protocol traffic.
- Diagnostics and fetch errors go to stderr.
- Browser rendering remains optional and is not part of the default path.
- The default runtime stays lightweight and `npx`-friendly.