# Agent Guidelines for zynktime

## Setup
- **Install dependencies**: `pip install -r requirements.txt`
- **Set environment**: `export KLEER_API_KEY=your_key_here` (required)
- **Optional env vars**: `KLEER_USERNAME`, `KLEER_COMPANY_ID`

## Run Commands
- **Run API server**: `python main.py` (starts FastAPI on port 8000)
- **Run CLI mode**: `python main.py cli`
- **Run tests**: `pytest` or `pytest test_main.py -v`
- **Run single test**: `pytest test_main.py::TestServices::test_validate_date_valid -v`

## Project Structure
- **config.py**: Application configuration and environment variables
- **models.py**: Pydantic models for data validation
- **api_client.py**: Kleer API client with error handling
- **services.py**: Business logic (CSV parsing, time extraction, event creation)
- **main.py**: FastAPI application and endpoints
- **cli.py**: CLI interface for interactive time reporting
- **test_main.py**: Unit tests with pytest

## Code Style

**Imports**: Standard library first, third-party second, local imports last. Group by category with blank lines between groups.

**Formatting**: 4 spaces indentation, no trailing whitespace. Use type hints from `typing` (List, Dict, Any, Optional).

**Naming**: snake_case for functions/variables, PascalCase for classes, UPPER_CASE for constants. Be descriptive.

**Error Handling**: Use specific exceptions. Log with `logging.error()`. For API endpoints, raise `HTTPException` with proper status codes (404, 500, 502).

**Logging**: Use appropriate levels - INFO (normal ops), WARNING (skippable issues), ERROR (failures), DEBUG (detailed info).

**Configuration**: Use `Config` class from config.py. Never hardcode values - use Config constants or environment variables.

**API Design**: Use Pydantic models for validation. Document endpoints with docstrings. Return meaningful error messages.

**Testing**: Write tests for new features. Use mocks for external API calls. Maintain test coverage.