# VPN Access Server - Agent Guidelines

## Commands
- **Install deps**: `uv install`
- **Run CLI**: `uv run vpn-access-server [command]` (auth, session, init-db, seed-data, test, health-check, status, gen-client)
- **Run all tests**: `uv run pytest tests/`
- **Run single test**: `uv run pytest tests/test_specific.py::TestClass::test_method`
- **Database setup**: `uv run vpn-access-server init-db && uv run vpn-access-server seed-data`

## Architecture
- **Python 3.13+** VPN server extending OpenVPN with MAC validation and session management
- **MySQL database** for users, MAC addresses, and session tracking
- **FastAPI** for client config generation and management
- **Modular structure**: `access/` (core auth/session logic), `tests/` (unit tests), `scripts/` (DB setup), `util/` (client tools)

## Code Style
- **Type hints** required for all function parameters and return values
- **Docstrings** mandatory for all functions, classes, and modules
- **Snake_case** for functions/variables, PascalCase for classes
- **Logging** via `setup_logging()` with structured format
- **Error handling** with try/except, custom exit codes (0=success, 1=auth fail, 2=config error)
- **Imports** grouped: stdlib, third-party, local modules
- **Security** paramount: parameterized SQL, secure logging, environment variables for secrets