Lucenx9 · Lucenx9 · Mar 6, 2026 · Mar 6, 2026 · Mar 6, 2026
diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
@@ -9,3 +9,8 @@ config:
   MD033: false
   # Allow bare URLs
   MD034: false
+
+# Exclude vendored / virtual-env Markdown
+ignores:
+  - ".venv/**"
+  - ".venv-ci/**"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## [0.3.13] - 2026-03-06
+
+### Added
+
+- `agentinit doctor` command: runs all checks (missing files, TBD content, line budgets, sync drift, llms.txt freshness, contextlint) and prints actionable fix commands with a quick-fix summary.
+- `agentinit sync --diff`: show unified diffs for out-of-sync router files; works standalone or combined with `--check`.
+
+### Changed
+
+- Rewrite README with expanded documentation: installation, quick start, full/minimal modes, how-it-works diagram, CI integration, modular resources, and supported tools table.
+- Deduplicate test helpers: move shared `fill_tbd` to `tests/helpers.py`; add missing `detect`/`yes` defaults to `make_init_args`; add `make_doctor_args` and update `make_sync_args` with `diff` support.
+- Fix misleading test file docstrings (all previously said "Tests for agentinit.cli").
+- Add wiki documentation for architecture, commands, workflows, FAQ, troubleshooting, and contributing.
+
 ## [0.3.12] - 2026-03-06
 
 ### Changed

diff --git a/README.md b/README.md
@@ -1,137 +1,237 @@
 # agentinit
 
-![CI](https://github.com/Lucenx9/agentinit/actions/workflows/ci.yml/badge.svg) [![PyPI](https://img.shields.io/pypi/v/agentinit.svg)](https://pypi.org/project/agentinit/) [![Python Versions](https://img.shields.io/pypi/pyversions/agentinit.svg)](https://pypi.org/project/agentinit/)
+Scaffold and maintain context files for AI coding agents.
+
+![CI](https://github.com/Lucenx9/agentinit/actions/workflows/ci.yml/badge.svg)
+[![PyPI](https://img.shields.io/pypi/v/agentinit.svg)](https://pypi.org/project/agentinit/)
+[![Python 3.10+](https://img.shields.io/pypi/pyversions/agentinit.svg)](https://pypi.org/project/agentinit/)
 
 <img src="https://raw.githubusercontent.com/Lucenx9/agentinit/main/assets/preview.png" width="900" alt="agentinit preview" />
 
-Scaffold and maintain **agent context files** for modern coding assistants, with a deterministic, standard-library-only CLI.
+`agentinit` generates a structured set of context files that modern AI coding assistants (Claude Code, Cursor, GitHub Copilot, Gemini CLI) read automatically. It uses a **router-first architecture**: you write your project rules once in `AGENTS.md`, and agentinit keeps the vendor-specific files in sync.
+
+No runtime dependencies. Pure Python standard library. Works on Linux, macOS, and Windows.
 
-`agentinit` creates a clean router-first setup around `AGENTS.md`, plus companion files for Claude, Cursor, Copilot, Gemini CLI, and `llms.txt`.
+## Why agentinit
 
-## Why agentinit 🎯
+AI coding agents perform better when they have clear, structured context about your project. Without it, they guess at your stack, conventions, and constraints.
 
-- **Single source of truth:** keep high-level rules in `AGENTS.md`.
-- **Low drift workflow:** regenerate and verify router files with `sync --check`.
-- **Lean context model:** keep short entry files and push detail into `docs/`.
-- **No runtime dependencies:** pure Python stdlib.
+**agentinit solves this by:**
 
-## Quick Start 🚀
+- **One source of truth** -- Write project rules in `AGENTS.md`. Vendor files (`CLAUDE.md`, `GEMINI.md`, `.cursor/rules/`, `.github/copilot-instructions.md`) are generated routers that import it.
+- **Low-drift workflow** -- `sync --check` and `status --check` detect when files fall out of date. Run them in CI to catch drift early.
+- **Lean context model** -- Keep always-loaded files short (under 300 lines). Push details into `docs/` where agents load them on demand.
+- **Deterministic output** -- No LLM calls, no network requests. Every command produces the same output from the same input.
 
-Requires **Python 3.10+**.
+## Installation
+
+Requires Python 3.10 or later.
 
 ```sh
-# Install (recommended)
+# With pipx (recommended, installs in an isolated environment)
 pipx install agentinit
 
-# Initialize in an existing repository
+# With pip
+pip install agentinit
+
+# Verify
+agentinit --version
+```
+
+## Quick start
+
+### Add context files to an existing project
+
+```sh
 cd your-project
-agentinit init --minimal
+agentinit init
 ```
 
-Minimal profile generates:
+This creates the full set of context files:
+
+```text
+your-project/
+├── AGENTS.md                          # Primary agent instructions (source of truth)
+├── CLAUDE.md                          # Claude Code router → imports AGENTS.md
+├── GEMINI.md                          # Gemini CLI router → imports AGENTS.md
+├── llms.txt                           # Project discovery index
+├── .claude/rules/                     # Claude Code modular rules
+│   ├── coding-style.md
+│   ├── testing.md
+│   └── repo-map.md
+├── .cursor/rules/project.mdc          # Cursor rule routing
+├── .github/copilot-instructions.md    # GitHub Copilot context
+├── .contextlintrc.json                # Lint configuration
+└── docs/
+    ├── PROJECT.md                     # Stack, commands, layout, constraints
+    ├── CONVENTIONS.md                 # Style, naming, testing, git workflow
+    ├── TODO.md                        # Task tracking for agents
+    ├── DECISIONS.md                   # Architecture decision records
+    └── STATE.md                       # Session handoff notes
+```
+
+### Minimal mode
+
+For smaller projects, generate only the essential files:
+
+```sh
+agentinit init --minimal
+```
 
 ```text
 your-project/
-├── llms.txt
 ├── AGENTS.md
 ├── CLAUDE.md
+├── llms.txt
 └── docs/
     ├── PROJECT.md
     └── CONVENTIONS.md
 ```
 
-Full profile (`agentinit init`) also includes `GEMINI.md`, `docs/STATE.md`, `docs/TODO.md`, `docs/DECISIONS.md`, Cursor/Copilot/Claude rule files, and `.contextlintrc.json`.
+### After scaffolding
+
+1. Open `docs/PROJECT.md` and describe your project, stack, and commands.
+2. Fill in `docs/CONVENTIONS.md` with your team's standards.
+3. Run your coding agent -- it reads `AGENTS.md` (or its vendor-specific router) automatically.
 
-## Core Workflow 🧭
+Track the generated files in git so your agents can find them:
 
 ```sh
-# 1) Bootstrap context files
-agentinit init --detect --purpose "AI code review assistant"
+git add AGENTS.md CLAUDE.md GEMINI.md llms.txt docs/
+```
 
-# 2) Keep llms.txt aligned with project docs
-agentinit refresh-llms
+## How it works
 
-# 3) Add modular resources
-agentinit add skill code-reviewer
-agentinit add mcp github
-agentinit add security
+agentinit uses a **router-first** design. Each AI tool has its own context file format, but the content should be consistent. Instead of maintaining multiple files manually, agentinit generates thin router files that all point back to `AGENTS.md`:
 
-# 4) Validate quality gates
-agentinit status --check
-agentinit sync --check
-agentinit lint
+```text
+AGENTS.md            ← You edit this (source of truth)
+  ├── CLAUDE.md      ← @AGENTS.md  (auto-generated router)
+  ├── GEMINI.md      ← @AGENTS.md  (auto-generated router)
+  ├── .cursor/rules/ ← @AGENTS.md  (auto-generated router)
+  └── .github/copilot-instructions.md  (auto-generated router)
 ```
 
-For minimal projects, both `status --check` and `sync --check` auto-detect the generated minimal profile. `status --minimal --check` and `sync --minimal --check` remain available if you want to force that mode explicitly.
+When you run `agentinit sync`, it regenerates the router files from templates. When you run `agentinit sync --check`, it exits with code 1 if any router has drifted from the template -- useful in CI to prevent silent staleness.
+
+The `docs/` directory holds detailed project context that agents load on demand. This keeps the always-loaded router files short and focused.
+
+## Commands
+
+### Scaffolding
+
+| Command | Description |
+| --- | --- |
+| `agentinit init` | Add missing context files to the current directory |
+| `agentinit init --minimal` | Generate only the minimal file set |
+| `agentinit minimal` | Shortcut for `init --minimal` |
+| `agentinit new <name>` | Create a new project directory and scaffold context files |
+| `agentinit remove` | Delete agentinit-managed files (with confirmation) |
+
+Common flags for `init`, `minimal`, and `new`:
 
-### Command Reference
+| Flag | Effect |
+| --- | --- |
+| `--detect` | Auto-detect stack and commands from `pyproject.toml`, `package.json`, `Cargo.toml`, or `go.mod` |
+| `--purpose "..."` | Set the project purpose non-interactively |
+| `--prompt` | Run the interactive setup wizard (default on TTY) |
+| `--translate-purpose` | Translate non-English purpose text to English for `docs/` files |
+| `--skeleton fastapi` | Copy a starter project boilerplate after scaffolding |
+| `--force` / `--yes` / `-y` | Overwrite existing files without confirmation |
 
-- `agentinit init` add missing context files in current directory
-- `agentinit minimal` shortcut for `init --minimal`
-- `agentinit new <project>` create a new project and scaffold context
-- `agentinit refresh-llms` (alias: `refresh`) regenerate `llms.txt`
-- `agentinit sync` reconcile router files from templates
-- `agentinit status` show missing/incomplete files and line budgets
-- `agentinit lint` run `contextlint` checks
-- `agentinit add <type> <name>` install resources (`skill`, `mcp`, `security`, `soul`)
-- `agentinit remove` remove or archive managed files
+### Maintenance
 
-## CI Example ✅
+| Command | Description |
+| --- | --- |
+| `agentinit sync` | Regenerate vendor router files from templates |
+| `agentinit sync --check` | Exit 1 if routers have drifted (CI mode) |
+| `agentinit sync --diff` | Show unified diff for out-of-sync routers |
+| `agentinit refresh-llms` | Regenerate `llms.txt` from project files |
+| `agentinit add <type> <name>` | Install a modular resource (see below) |
+| `agentinit remove --archive` | Move managed files to `.agentinit-archive/` instead of deleting |
 
-Use both structure and drift checks:
+### Validation
+
+| Command | Description |
+| --- | --- |
+| `agentinit status` | Show missing files, incomplete content, and line budget warnings |
+| `agentinit status --check` | Exit 1 if any issues found (CI mode) |
+| `agentinit lint` | Run contextlint checks (broken refs, bloat, duplication) |
+| `agentinit doctor` | Run all checks and suggest fix commands |
+
+### Modular resources (`add`)
+
+Add reusable agent instructions to your project:
 
 ```sh
-agentinit sync --check
-agentinit status --check
-agentinit lint
-```
+# List available resources of a type
+agentinit add skill --list
+
+# Install a skill (copies to .agents/skills/ or .claude/skills/)
+agentinit add skill code-reviewer
+agentinit add skill testing
+agentinit add skill frontend-reviewer
 
-## Tool Compatibility 🤝
+# Install MCP integration guides (copies to .agents/)
+agentinit add mcp github
+agentinit add mcp postgres
 
-`agentinit` is designed to work with common agentic workflows by generating:
+# Install security guardrails
+agentinit add security
 
-- `AGENTS.md` as primary router
-- `CLAUDE.md` for Claude Code memory/routing
-- `.cursor/rules/project.mdc` for Cursor rule routing
-- `.github/copilot-instructions.md` for GitHub Copilot context
-- `GEMINI.md` for Gemini CLI context routing
-- `llms.txt` as project discovery index
+# Install agent personality definition
+agentinit add soul
+```
 
-## Troubleshooting 🛠️
+Each `add` command also appends a reference to the resource in `AGENTS.md`.
 
-If your agent cannot find context files:
+## CI integration
 
-- track files in git (`git add AGENTS.md CLAUDE.md GEMINI.md llms.txt docs/`)
-- verify ignored files (`git status --ignored`)
-- regenerate derived files (`agentinit refresh-llms` and `agentinit sync`)
-- replace managed symlinks with regular files inside the repo; unsafe managed paths are skipped by design
+Add these checks to your CI pipeline to catch documentation drift:
 
-## Documentation 📚
+```yaml
+# .github/workflows/ci.yml
+- name: Check agent context
+  run: |
+    pip install agentinit
+    agentinit sync --check    # Fail if router files drifted from templates
+    agentinit status --check  # Fail if files are missing or incomplete
+    agentinit lint            # Fail on broken refs, bloat, or duplication
+```
 
-Wiki (full usage and examples):
+For minimal-profile projects, `sync --check` and `status --check` auto-detect the profile. You can also force it with `--minimal`.
 
-- [Changelog](CHANGELOG.md)
-- [Wiki Home](https://github.com/Lucenx9/agentinit/wiki)
-- [Quick Start](https://github.com/Lucenx9/agentinit/wiki/Quick-Start)
-- [Commands](https://github.com/Lucenx9/agentinit/wiki/Commands)
-- [Workflows](https://github.com/Lucenx9/agentinit/wiki/Workflows)
-- [Troubleshooting](https://github.com/Lucenx9/agentinit/wiki/Troubleshooting)
-- [FAQ](https://github.com/Lucenx9/agentinit/wiki/FAQ)
-- [Contributing to the Wiki](https://github.com/Lucenx9/agentinit/wiki/Contributing-to-the-Wiki)
+## Supported tools
+
+| Tool | Generated file | How it works |
+| --- | --- | --- |
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `CLAUDE.md` | Router that `@`-imports `AGENTS.md` and `docs/` files |
+| [Cursor](https://cursor.com) | `.cursor/rules/project.mdc` | Project-level rules pointing to `AGENTS.md` |
+| [GitHub Copilot](https://github.com/features/copilot) | `.github/copilot-instructions.md` | Repository-level instructions referencing `AGENTS.md` |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `GEMINI.md` | Router that imports `AGENTS.md` and `docs/` files |
+| [llms.txt](https://llmstxt.org/) | `llms.txt` | Standard discovery index with project summary and key files |
 
-## Development 🧪
+## Development
 
 ```sh
 python3 -m venv .venv
 . .venv/bin/activate
 pip install -e . --group dev
+
+# Run tests
+python3 -m pytest tests/ -v
+
+# Lint and format check
 python3 -m ruff check agentinit tests cli
 python3 -m ruff format --check agentinit tests cli
-python3 -m pytest tests/ -v
 ```
 
-On distro-managed Python installs that enforce PEP 668, run the development
-commands inside a virtual environment instead of the system interpreter.
+On distro-managed Python installs that enforce PEP 668, use a virtual environment instead of the system interpreter.
+
+## Documentation
+
+- [Changelog](CHANGELOG.md)
+- [Wiki](https://github.com/Lucenx9/agentinit/wiki) -- detailed guides, workflows, architecture, and FAQ
 
 ## License