# Agent Instructions

These rules apply repository-wide unless a more specific `AGENTS.md` overrides them.

## Scope and safety

- Work only inside this repository, inspect existing code before editing, and preserve existing functionality.
- Never attempt server access unless explicitly authorized in a later milestone, and never mark server testing as passed without server feedback.
- Keep changes within the requested milestone and report incomplete work honestly.
- Follow the requested scope exactly. A documentation-only task must not edit application code, configuration, workflows, tests, manifests, or lockfiles.
- Do not commit, push, merge, deploy, change remote resources, or run destructive commands without explicit authorization.
- Never expose or commit secrets, credentials, `.env` contents, production data, or personally identifiable information (PII), and never modify `.env`.
- Make minimal, reviewable changes; do not refactor unrelated code.
- Inspect current implementations and all affected callers before editing.

## Supported stack

- Preserve Laravel 13 and PHP 8.3+ compatibility.
- Use MySQL 8 as the production database target.
- Preserve Node.js 20+ compatibility; CI currently verifies Node.js 20.
- Follow existing Livewire 4, Flux 2, Filament 5, Fortify, Spatie Permission, Vite 8, and Tailwind CSS 4 patterns.
- Manage dependencies with Composer or npm. Do not hand-edit lockfiles, add dependencies, or change versions without approval.

## Architecture

- Treat the application as a modular monolith; see `docs/ARCHITECTURE.md`.
- Never invent business rules or trust frontend-calculated prices or totals; all business validation belongs on the server.
- Put new business capabilities under `app/Domain/<Domain>` only when real behavior is implemented.
- Never create empty domain directories, placeholder classes, speculative interfaces, or unused abstractions.
- Keep HTTP, Livewire, and Filament concerns thin. Put reusable business behavior in domain actions/services and authorization in policies/permissions.
- Communicate across domains through explicit public actions, contracts, value objects, or events; do not reach into another domain's internals.
- Keep framework-wide shared code small and genuinely cross-cutting.

## Implementation conventions

- Use strict types where the surrounding code does, explicit return/property types, constructor injection, and existing naming/import conventions.
- Use Eloquent relationships and query scopes consistently; avoid hidden N+1 queries.
- Validate untrusted input and authorize every privileged operation server-side.
- Use migrations for every schema change. Keep them forward-compatible and safe for rolling application rollback; never edit an applied production migration.
- Use queued jobs for slow or retryable work; make jobs idempotent where practical.
- Do not use `env()` outside configuration files, or add debug calls such as `dd`, `dump`, or `ray`.

## Quality

- Update existing tests for behavior changes; add focused tests only when the task permits test edits.
- Prefer the smallest relevant check, then run the full gate before completion when practical: `composer quality`.
- Formatting check: `composer format-check`; apply formatting: `composer format`.
- Static analysis: `composer analyse`; tests: `composer test`; assets: `npm run build`.
- Do not weaken tests, static-analysis levels, authentication, authorization, or security controls to make a change pass.

## Operations and documentation

- Preserve the production `APP_KEY`; never regenerate it during deployment.
- Production must use `APP_ENV=production`, `APP_DEBUG=false`, HTTPS, a real mail transport, the scheduler cron, and a supervised queue worker when an asynchronous queue driver is selected.
- Keep the web document root at `public/`; only `storage/` and `bootstrap/cache/` should be writable by the web process.
- Treat workflow and artifact documentation as factual: **Quality** (`quality.yml`) verifies pushes and pull requests; **Build deployment artifact** (`release-artifact.yml`) accepts a manual `ref` input and uploads `threegoats-club-<short-SHA>.zip` containing `BUILD_INFO.txt`.
- Update relevant documentation whenever setup, architecture, environment, operational, or deployment behavior changes.
- Never state that a server was validated or deployed unless that action actually occurred and evidence was recorded.