AGENTS.md for Laravel

# AGENTS.md

Instructions for coding agents working in this Laravel repository. Cursor, Claude Code, Codex, Copilot, and other agents should follow this file before they guess.

## Stack

This repository is a Laravel application. Routes stay thin, Eloquent owns persistence, and schema changes go through migrations. Use Artisan for the commands the repo already expects.

## Layout

- HTTP entry points live in routes and controllers. Non-trivial rules live in actions, models, or domain classes.
- Form requests validate input. Policies and gates authorize it.
- Database changes ship as migrations. Do not edit a migration that has already run in production.

## Commands

- Dev server: `php artisan serve`
- Tests: `php artisan test`
- Migrate: `php artisan migrate`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Use Eloquent and query scopes. Reach for the query builder only when the ORM cannot say it.
- Validate with a Form Request. Do not read `$request->all()` and hope.
- Authorize with a policy or gate in the same change as the route.
- Queue slow work. Do not send mail or call a third party inside the request if the project already uses jobs.
- Match Pest or PHPUnit, whichever the repo already uses.
- Keep secrets in `.env`. Do not commit `.env` or dump config with secrets into git.

## Testing

Add or update tests when behavior changes.

Cover the Form Request or the action with the repo's Pest or PHPUnit suite. Include one rejection and one success.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Throw or return a validation error for bad input. Let unexpected exceptions hit the project's exception handler.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not call `env()` outside config files. Use `config()` after the config is cached.
- Do not hide N+1 queries. Eager load relations the response actually walks.
- Do not skip authorization because the route is behind `auth`.
- Do not rewrite a vendor class. Use a container binding or an event the framework already fires.

## Done when

- The requested behavior works.
- `php artisan test` passes, and a new migration is included when the schema changed.
- The diff stays inside the task.
- You list anything you could not run.