# AGENTS.md

This file provides guidance to code agents when working with code in this repository.

## Project Overview

See README.md

## Development Workflow

This is a greenfield project and hence there is no need to support legacy features, configuration options etc when newer aproaches replace them.

### Environment Setup

```bash
# Activate virtual environment
source .venv/bin/activate

# Install dependencies
uv pip install -e ".[dev]"
```

### Running Tests and Checks

**CRITICAL**: All changes must pass `make check` before completion.

```bash
# Run all quality checks (tests + lint + typecheck)
make check

# Individual commands
make test           # Run pytest
make lint          # Run ruff linter
make typecheck     # Run mypy type checker
make format        # Auto-fix with ruff

# Test with verbosity
make test-verbose
pytest -v

# Run single test file
pytest tests/test_sink_decorator.py

# Run single test function
pytest tests/test_sink_decorator.py::test_function_name
```

## Testing Patterns

- Unit tests in `tests/test_*.py`
- Acceptance tests in `tests/test_acceptance.py`
- PydanticAI integration tests in `tests/test_pydantic_ai_*.py`
- All tests use `pytest-asyncio` with `asyncio_mode = "auto"`
- Test fixtures in `tests/conftest.py`

Add tests for all meaningful new features.

## Project Conventions

- Default audit log path is `rgltr-audit.jsonl` at project root (configurable).
- Minimum Python version is 3.11; minimum `pydantic-ai` is 0.0.49.

## Integration Tests

- Remote MCP integration tests use Context7 (`https://mcp.context7.com/mcp`) and require network.
- Run with `pytest -m integration` (or exclude with `-m "not integration"`).

## Type Safety

The codebase uses strict mypy configuration:
- All functions must have type annotations
- Generic types use `TypeVar` and `ParamSpec` properly
- No `type: ignore` without justification
