# Blog AGENTS.md

## Stack
- Python 3.13+, FastAPI, pydantic, uvicorn
- Package manager: `uv`
- CI: Woodpecker (lint, test, type on push/PR to `dev`)

## Commands
```bash
uv sync --group dev         # Install all dev dependencies
uv run pytest               # Run tests (coverage >= 70% required)
uv run pytest tests/unit/   # Run single test directory
uv run ruff check . --fix   # Lint
uv run ruff format          # Format
uv run isort .              # Sort imports
uv run mypy .               # Type check (strict mode)
uv run blog                 # Start dev server (port 8000)
```

## Pre-commit order
`ruff check --fix` → `ruff format` → `isort` → `mypy`

## Architecture
```
app/
  main.py          # Entry point, uvicorn.run(app_factory)
  core/config.py   # Settings from .env via pydantic-settings
  core/exceptions.py
  common/error_handler.py
  api/v1/
  modules/
tests/
  unit/
  integration/
  e2e/
  api/
```

## Key conventions
- All commands use `uv run` prefix
- pytest: asyncio_mode=auto, coverage on `app/`
- mypy: strict=true with pydantic plugin
- isort: black profile, filter_files=true
- `.env` loaded by pydantic-settings (not in repo)