# PairingPal Agent Instructions

## Project
PairingPal is a Laravel learning project for a Yii2-experienced developer.
Goal: build a clean Laravel CRUD app first, then evolve toward a flight-attendant scheduling app.

## Stack
- Laravel
- MySQL
- Herd locally on Windows
- DBngin locally
- GitHub remote on main branch

## Cloud Codex environment
- Use environment variables/secrets supplied by the Codex environment
- Do not modify .env manually unless explicitly asked
- Use file/session/cache defaults suitable for development

## Current status
- Laravel app created
- Pairing model, controller, migration, and request classes created
- pairings table migrated
- repo pushed to GitHub

## Coding standards
- Keep controllers thin
- Use Form Requests for validation
- Use Eloquent directly
- Use Blade views first
- Do not add Vue/Vuetify yet
- Do not add Docker
- Do not add GitHub workflows
- Keep explanations friendly to a Yii2 developer

## Pairing fields
- title
- pairing_code
- report_at
- release_at
- origin
- destination
- status
- notes

## Commands
- composer install
- php artisan optimize:clear
- php artisan migrate --force
- php artisan test

## Build next
1. Update Pairing model fillable and casts
2. Add validation rules to StorePairingRequest and UpdatePairingRequest
3. Implement PairingController CRUD
4. Add resource route in routes/web.php
5. Create Blade views:
   - resources/views/layouts/app.blade.php
   - resources/views/pairings/index.blade.php
   - resources/views/pairings/create.blade.php
   - resources/views/pairings/edit.blade.php
   - resources/views/pairings/show.blade.php
6. Make the CRUD work end to end
7. Keep commits small and clear

## Domain modeling guidance

PairingPal is a monthly crew-planning app, not a generic trip CRUD app.

The database should be organized around:
- bid_periods: month/base planning context
- pairings: master trip definitions
- monthly_schedules: one employee + one month + one version
- schedule_events: normalized day/event calendar records
- source_documents: provenance for imported PDFs

Do not flatten all imported data into the pairings table.

### Current source data shapes
1. Monthly bid package metadata
2. Pairing definitions with multiple legs
3. Employee monthly roster/event grids
4. Bid preference structures from NavBlue

### Preferred first implementation layer
- bases
- employees
- source_documents
- bid_periods
- pairings
- pairing_legs
- monthly_schedules
- schedule_events

### Parser/import guidance
The parser should output structured payloads for:
- bid period metadata
- pairing master records
- pairing legs
- employee monthly schedules
- schedule events preserving original codes like VAC/STT/BST/V07/S05/FAT/CRM/REC/CARRYIN

### Important
Keep raw source values where interpretation may evolve.
Prefer normalized relations plus raw JSON/text snapshots over lossy flattening.