laravel-11-12-app-guidelines

# Laravel 11/12 App Guidelines

## Overview

Apply a consistent workflow for Laravel 11/12 apps with optional frontend stacks, Dockerized commands, and Laravel Boost tooling.

## Quick Start

- Read repository instructions first: `AGENTS.md`. If `docs/` exists, read `docs/README.md` and relevant module docs before decisions.
- Detect the stack and command locations; do not guess.
- Use Laravel Boost `search-docs` for Laravel ecosystem guidance; use Context7 only if Boost docs are unavailable.
- Follow repo conventions for naming, UI language, docs-first policies, and existing component patterns.

## Stack Detection

- Check `composer.json`, `package.json`, `docker-compose.*`, and `config/*` to confirm:
  - Docker Compose/Sail vs host commands
  - API-only vs full-stack
  - Frontend framework (Inertia/React, Livewire, Vue, Blade)
  - Auth (Fortify, Sanctum, Passport, custom)

## Laravel 11/12 Core Conventions

- Use the Laravel 11/12 structure: configure middleware, exceptions, and routes in `bootstrap/app.php`; service providers in `bootstrap/providers.php`; console configuration in `routes/console.php`.
- Use Eloquent models and relationships first; avoid raw queries and `DB::` unless truly necessary.
- Create Form Request classes for validation instead of inline validation.
- Prefer named routes and `route()` for URL generation.
- When altering columns, include all existing attributes in the migration to avoid dropping them.
- Ask before destructive database operations (e.g., reset/rollback/fresh).

## API-Only Mode

- Use `routes/api.php`; avoid Inertia and frontend assumptions.
- Prefer API Resources and versioning if the repo already uses them.
- Follow the repo's auth stack (Sanctum/Passport/custom) and response format conventions.
- Do not require Vite/Tailwind/NPM unless the repo already includes them.

## Inertia + React + Wayfinder (if present)

- Use `Inertia::render()` for server-side routing; place pages under `resources/js/Pages` unless the repo says o