# docagent

> Repository documentation agent for humans and coding agents that treats documentation as a set of verifiable artifacts driven by a DAG, generated by an LLM backend, and validated by a deterministic-first pipeline anchored on ground-citation comments. <!-- ground: pyproject.toml:5-13 --> <!-- ground: README.md:7-7 -->

DocAgent ships a Typer-based CLI (`docagent init|update|verify`) and registers v1 artifacts — `readme`, `python_docstrings`, `api_reference`, `how_to_guides`, `agents_md`, `claude_md`, `llms_txt`. <!-- ground: docagent/cli.py:224-238 --> <!-- ground: docagent/artifacts/builtins.py:72-86 --> Two backends are available: the default Claude Agent SDK and an opt-in LiteLLM backend for Gemini / OpenRouter / Anthropic-direct. <!-- ground: pyproject.toml:50-55 --> <!-- ground: docagent/cli.py:25-33 -->

## docs

- [README.md](README.md): project overview, install, provider setup, quickstart.
- [AGENTS.md](AGENTS.md): setup, lint, project structure for coding agents.
- [CLAUDE.md](CLAUDE.md): Claude-specific working notes and gotchas.
- [docs/how-to/](docs/how-to/): task-oriented Diátaxis how-to guides (install, configure, run, verify, score).
- [docs/reference/](docs/reference/): per-module reference pages for `docagent.*` and the benchmark harness.

## code

- [docagent/cli.py](docagent/cli.py): Typer app exposing `init`, `update`, `verify`, and `--backend` selection. <!-- ground: docagent/cli.py:224-238 -->
- [docagent/core/orchestrator.py](docagent/core/orchestrator.py): drives `plan → generate → verify → write` with budget telemetry. <!-- ground: docagent/core/orchestrator.py:97-127 -->
- [docagent/artifacts/builtins.py](docagent/artifacts/builtins.py): registers v1 artifacts via `register_v1_builtins`. <!-- ground: docagent/artifacts/builtins.py:72-86 -->
- [docagent/artifacts/_cleaners.py](docagent/artifacts/_cleaners.py): `clean_markdown_output`, `MIN_CLEAN_BYTES` floor, `OutputTooSmallError`. <!-- ground: docagent/artifacts/_cleaners.py:12-75 -->
- [docagent/backends/agent_sdk.py](docagent/backends/agent_sdk.py): Agent SDK backend with read-only Read/Glob/Grep tools. <!-- ground: docagent/backends/agent_sdk.py:5-11 -->
- [docagent/adapters/](docagent/adapters/): language adapters (Python via libcst, TypeScript, tree-sitter fallback).
- [pyproject.toml](pyproject.toml): package metadata, deps, optional `multi` extra, ruff/mypy/pytest config. <!-- ground: pyproject.toml:5-55 -->

## tests

- [tests/unit/](tests/unit/): unit tests for cleaners, adapters, orchestrator, gates.
- [tests/golden/](tests/golden/): recorded-backend snapshot tests over the `tinylib` fixture. <!-- ground: tests/golden/fixtures/tinylib/pyproject.toml:1-1 -->
- [tests/golden/snapshots/](tests/golden/snapshots/): committed snapshots refreshed via `UPDATE_SNAPSHOTS=1`. <!-- ground: tests/golden/_harness.py:44-50 -->

## optional

- [benchmarks/regeneration/](benchmarks/regeneration/): regeneration benchmark harness, scorer, and corpus.
- [docs/reference/benchmarks.regeneration.run.md](docs/reference/benchmarks.regeneration.run.md): reference for the benchmark runner module.
- [docs/reference/benchmarks.regeneration.score.md](docs/reference/benchmarks.regeneration.score.md): reference for the LLM-judge scoring module.
- [.planning/](.planning/): phase plans, research notes, and ADRs (historical, load only if working on roadmap or architecture).
- [docs/how-to/run-the-regeneration-benchmark-from-the-cli.md](docs/how-to/run-the-regeneration-benchmark-from-the-cli.md): how to invoke the benchmark.
