# Repository Guidelines

## Project Structure & Module Organization
- `app/`: Laravel application code (models, controllers, policies, jobs).
- `routes/`: HTTP routes (`web.php`, `api.php`).
- `resources/`: Frontend (Vue 3 + Vite, Tailwind). Components in `resources/js`, views in `resources/views`.
- `database/`: Migrations, factories, seeders.
- `public/`: Web root for built assets.
- `tests/`: Pest test suites (`Feature`, `Unit`).
- Config and bootstrap in `config/`, `bootstrap/`; static/storage in `storage/`.

## Build, Test, and Development Commands
- Install: `composer install && npm ci`
- One‑time setup: `composer run setup` (env, key, migrate, build).
- Dev server (PHP, queue, logs, Vite): `composer run dev`
- SSR dev (optional): `composer run dev:ssr`
- Frontend: `npm run dev` (serve), `npm run build` (prod build)
- Tests: `composer test` (runs `php artisan test` via Pest)

## Coding Style & Naming Conventions
- PHP: PSR‑12 via Laravel Pint. Format with `./vendor/bin/pint -v`.
- JS/TS/Vue: ESLint + Prettier. Lint with `npm run lint`; format with `npm run format` or check via `npm run format:check`.
- Naming: PHP classes `StudlyCase`; Vue components `PascalCase.vue`; files and directories kebab‑case in `resources/js`.
- Commits and code should be in English and present tense.

## Testing Guidelines
- Framework: Pest + Laravel. Place tests under `tests/Feature` or `tests/Unit` as `*Test.php`.
- Write fast, isolated unit tests; prefer feature tests for HTTP flows.
- Run with coverage (if Xdebug/PCOV available): `php artisan test --coverage`.
- Seed data only when necessary; prefer factories.

## Commit & Pull Request Guidelines
- Commit style: use clear prefixes (e.g., `feat:`, `fix:`, `refactor:`, or `User:` area tags seen in history) followed by a concise summary.
- PRs must include: scope/goal, before/after notes, steps to test, screenshots for UI, and linked issues.
- Keep PRs small and focused; ensure `composer test`, `npm run lint`, and `./vendor/bin/pint` pass.

## Security & Configuration Tips
- Never commit `.env` or secrets; copy from `.env.example` then `php artisan key:generate`.
- Validate and sanitize uploads; prefer queued jobs for long tasks.
- Run `php artisan migrate --force` in CI/CD; build assets with `npm run build`.

## Agent‑Specific Instructions
- Using Codex: prefer available skills (`skill-installer`, `skill-creator`) and keep diffs minimal. Touch only necessary files, reuse existing scripts, and avoid bulk loading unrelated context.