# Repository Guidelines

## Project Structure & Module Organization
- `src/guardden/` is the main package: `bot.py` (bot lifecycle), `cogs/` (Discord commands/events), `services/` (business logic), `models/` (SQLAlchemy models), `config.py` (settings), and `utils/` (shared helpers).
- `tests/` holds pytest suites (`test_*.py`) for services and utilities.
- `migrations/` and `alembic.ini` define database migrations.
- `docker-compose.yml` and `Dockerfile` support containerized development/deployments.
- `.env.example` provides the configuration template.

## Build, Test, and Development Commands
- `pip install -e ".[dev,ai]"` installs dev tooling plus optional AI providers.
- `python -m guardden` runs the bot locally.
- `pytest` runs the full test suite; `pytest tests/test_verification.py::TestVerificationService::test_verify_correct` runs a single test.
- `ruff check src tests` lints; `ruff format src tests` formats.
- `mypy src` runs strict type checks.
- `docker compose up -d` starts the full stack; `docker compose up db -d` starts only Postgres.

## Coding Style & Naming Conventions
- Python 3.11 with 4-space indentation; keep lines within 100 chars (Ruff config).
- Prefer type hints and clean async patterns; mypy runs in strict mode.
- Naming: `snake_case` for modules/functions, `CamelCase` for classes, `UPPER_SNAKE` for constants.
- New cogs live in `src/guardden/cogs/` and should be wired in `_load_cogs()` in `src/guardden/bot.py`.

## Testing Guidelines
- Tests use pytest + pytest-asyncio (`asyncio_mode=auto`).
- Follow `test_*.py` file names and `test_*` function names; group related cases in `Test*` classes.
- Add or update tests for new services, automod rules, or AI provider behavior.

## Commit & Pull Request Guidelines
- Commit messages are short, imperative, and capitalized (e.g., `Fix: initialize guild config...`, `Add Discord bot setup...`).
- PRs should include a concise summary, tests run, and any config or migration notes; link related issues when available.

## Security & Configuration Tips
- Store secrets in `.env` (never commit); configuration keys are prefixed with `GUARDDEN_`.
- PostgreSQL is required; default URL is `postgresql://guardden:guardden@localhost:5432/guardden`.
- AI features require `GUARDDEN_AI_PROVIDER` plus the matching API key.