# AGENTS.md - Time Tracker Development Guide

## Build/Test Commands

- **Run main application**: `python time_tracker.py`
- **Run single test**: `python tests/test_mark_logic.py` or `python tests/test_mark_billed.py`
- **Clean archive data**: `python tests/clean_archive.py`

## Code Style Guidelines

### Imports & Structure
- Standard library imports first (os, json, csv, datetime, collections)
- Third-party imports next (tkinter, ttk, messagebox, filedialog)
- Group related imports together
- Use absolute imports consistently

### Naming Conventions
- **Classes**: PascalCase (e.g., `ClickableCell`, `TimeTracker`)
- **Functions/Methods**: snake_case (e.g., `load_settings`, `update_day_total`)
- **Variables**: snake_case (e.g., `time_cells`, `data_rows`)
- **Constants**: UPPER_SNAKE_CASE (e.g., `drag_info` global dict)
- **Private methods**: prefix with underscore (e.g., `_refresh_dropdowns`)

### Error Handling
- Use try/except blocks for file operations
- Show user-friendly messages via `messagebox.showerror()` or `messagebox.showwarning()`
- Log errors with context but never expose sensitive data
- Gracefully handle missing files and directories

### GUI Patterns
- Use `ttk.Combobox` for dropdowns with `state="readonly"`
- Frame-based layout with grid/pack geometry managers
- Bind events consistently (`<Button-1>`, `<B1-Motion>`, `<ButtonRelease-1>`)
- Separate data models from UI presentation
- Use consistent widget naming: `*_var` for StringVar/IntVar, `*_frame` for containers

### Data Handling
- CSV files use UTF-8 encoding
- Store settings in `~/.config/time-tracker.json` (UNIX-compliant)
- Use `defaultdict` for pivot table operations
- Validate user input before processing
- Archive format: `['Job', 'TaskName', 'Note', 'Customer', 'Hours', 'Date', 'username', 'Billable', 'Billed']`

### Testing
- Test files in `tests/` directory with `test_` prefix
- Create sample data fixtures for consistent testing
- Test logic separately from UI components
- Verify both success and failure scenarios