# AI Agent Instructions - Attendance PDF Generator

## Project Overview
Excel → PDF converter for German attendance lists. Reads attendance data from multi-sheet Excel files (monthly) and generates personalized PDF reports with form filling. Critical: This is a **professional Windows terminal project** for business use.

## Architecture & Data Flow

### Core Components
```
generate.py              # CLI entry point (Click-based)
src/config_loader.py     # Loads config.json and schema.json
src/excel_reader.py      # Reads attendance data from Excel file
src/models.py            # Data models (participant, month, days)
src/validators.py        # Validation logic for Excel input data
src/pdf_filler.py        # Fills PDF form fields from model data
src/exceptions.py        # Custom exceptions for the entire pipeline
```

### PDF Structure (Form Fields)
- `person.name`: Person's full name
- `monat_jahr`: Month/Year in format "MM/YYYY"
- `datum.0` through `datum.22`: Date fields (23 rows max)
- `anwesend.0` through `anwesend.22`: Dropdown fields (X, K, KK, E, F, P, U)
- `plan.0-22`, `ist.0-22`: Hours fields (controlled by JavaScript - see below)

## Development Workflows

### Setup
```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt  # includes pytest
```

### CLI Usage (Click-based)
```bash
# Main entry point
python generate.py <command>
```

### Testing
```bash
pytest tests/ -v
```

**Test philosophy**: File-independent. Tests validate config mappings and business logic, NOT specific Excel files. Never hardcode "Max, Mustermann" or specific filenames in tests.

### Code Inspection Tools
```bash
python src/test_pdf_fields.py  # Inspect PDF template fields (creates TEST_FIELDS.pdf)
```

## Code Conventions

### Configuration Over Code

Config, settings, temporals and any kind of Data must be read from and written into json files in the directory /data

## Language & Style
- All config labels/descriptions: German only
- Code comments: English
- User-facing messages: German preferred

## When Making Changes
1. Update `./schema.json` first (single source of truth) and config.json if needed
2. Run tests after any edit: `pytest tests/ -v`
3. Check CLI still works: `python fill_pdf.py validate`
4. Never modify test data files in `data/` directory
5. Git commit messages: Describe business logic changes, not just code changes

## Questions Before Implementing
Per project conventions (`.github/instructions/main.instructions.md`):
- Ask clarifying questions instead of guessing
- Suggest step-by-step approach rather than implementing everything at once
- Confirm understanding of business requirements before coding