npx @next/codemod@canary agents-md --output <TARGET_FILE>
**What this does**:
- Auto-detects the Next.js version from package.json
- Downloads version-matching documentation from Vercel's servers
- Injects a compressed pipe-delimited index into the target file
- Downloads full docs to `.next-docs/` and adds it to `.gitignore`
- Non-interactive mode (no prompts)

**Important**:
- Requires network access
- Non-destructive: updates existing file without overwriting content
- Compresses ~40KB of docs into ~8KB (Vercel's agent evals showed 100% pass rate vs 53% baseline)

#### Option B: FastAPI Projects

Use a custom Python script to inject FastAPI best practices:

1. **Fetch the best practices content**:
 ```bash
 # Use WebFetch or curl to get the README from fastapi-best-practices
 # Store in temporary file for processing
 2. **Generate compressed documentation** from the repository content covering:
 - Domain-driven project organization
 - Async/sync routing patterns
 - Pydantic validation best practices
 - Dependency injection patterns
 - Database integration (SQLAlchemy, Alembic)
 - Error handling conventions
 - Testing patterns
 - Code quality tools (Ruff)

3. **Inject into CLAUDE.md**:
 - Check if a "FastAPI Best Practices" section already exists
 - If exists, update it; otherwise append to the end
 - Use clear section headers for easy navigation

**Template for FastAPI injection** (see `references/fastapi-best-practices.md` for full content):

```markdown
## FastAPI Best Practices

### Project Structure
- Use domain-driven organization (by feature), not file-type organization
- Each domain is self-contained: router, schemas, models, service, dependencies
- Structure per domain:
 - `router.py` - API endpoints
 - `schemas.py` - Pydantic request/response models
 - `models.py` - Database models (SQLAlchemy)
 - `service.py` - Business logic
 - `dependencies.py` - Route-level dependencies
 - `constants.py`, `config.py`, `exceptions.py`, `utils.py`

### Async Patterns
- Use `async def` for non-blocking I/O (database queries, HTTP calls)
- Use `def` for blocking operations (FastAPI handles threadpool automatically)
- **NEVER** use `time.sleep` in async functions (blocks event loop)
- Use `await asyncio.sleep` for delays
- CPU-intensive work requires multiprocessing/Celery (not threads due to GIL)
- Prefer async database drivers (SQLAlchemy 2.0+ with asyncio)

### Import Discipline
- Use explicit imports with module names: `from src.auth import constants as auth_constants`
- Avoids hidden coupling and improves maintainability
- Critical when importing services or dependencies from other packages

### Validation & Dependencies
- Leverage Pydantic's built-in validation (regex, enums, email, URL, constraints)
- Create custom BaseModel for application-wide consistency
- Use dependencies for business logic validation (DB constraints, authorization, token parsing)
- Dependencies cache within request scope - chain them to avoid redundant computations

### Response Serialization
- Always use `response_model` parameter on endpoints
- Create custom encoders for special types (datetime, UUID)
- FastAPI auto-generates OpenAPI schemas from type hints

### Error Handling
- Define module-specific exception classes
- Raise from dependencies and service layer
- FastAPI auto-converts to HTTP responses
- Use HTTP status codes correctly (400 for client errors, 500 for server errors)

### Database Integration
- SQL-first design: design schema first, then models
- Enforce naming conventions at database level
- Use Alembic for migrations
- Prefer async drivers for scalability

### Testing
- Use async test clients from day one
- Configure fixtures for async operations
- Test at multiple levels: unit (service), integration (router), e2e

### Code Quality
- Use Ruff for linting and formatting (Python-focused, fast)
- Always include type hints for OpenAPI generation
- Enforce strict mypy or pyright type checking
- Use pre-commit hooks for quality gates

### REST Conventions
- Use correct HTTP methods: GET (read), POST (create), PUT/PATCH (update), DELETE (remove)
- Docstrings on endpoints for clarity in auto-generated docs
- Leverage FastAPI's OpenAPI `/docs` as primary API documentation

---

**Reference**: [FastAPI Best Practices by zhanymkanov](https://github.com/zhanymkanov/fastapi-best-practices)
### Phase 2: Verify Results

After injection completes:

1. **Confirm the target file was updated**:
 - Read the file to verify it contains framework documentation
 - For Next.js: Look for pipe-delimited Next.js entries
 - For FastAPI: Look for "FastAPI Best Practices" section

2. **Check content integrity**:
 - Verify the injected content is properly formatted Markdown
 - Ensure existing content was not corrupted

3. **Report to user**:
 - Which framework was detected
 - Which file was updated (CLAUDE.md or AGENTS.md)
 - Approximate size of the injected documentation
 - Summary of what was added

### Phase 3: Report & Cleanup

Provide a summary to the user:

**For Next.js**:

Detected FastAPI 0.115.0 in pyproject.toml
Updated CLAUDE.md with FastAPI best practices (~6KB)

Review the changes and commit when ready:
 git add CLAUDE.md && git commit -m "docs: add FastAPI best practices reference"
## Usage

```bash
# Auto-detect framework
inject-docs

# Explicit framework selection
inject-docs nextjs
inject-docs fastapi
## Examples

### Example 1: Next.js Project

> inject-docs

Detected FastAPI 0.115.0 in pyproject.toml
Found existing CLAUDE.md - will inject documentation there
Fetching FastAPI best practices from zhanymkanov/fastapi-best-practices...
✓ Updated CLAUDE.md (3.2 KB → 9.5 KB)
✓ Injected FastAPI Best Practices section

Review the changes and commit when ready:
 git add CLAUDE.md && git commit -m "docs: add FastAPI best practices reference"
### Example 3: Explicit Framework Selection