Save this content to: AGENTS.md

# AGENTS.md

Laravel **package** (not an app): `mortezamasumi/fb-auth`, a Filament v5 plugin providing four auth flows (`link`, `code`, `mobile`, `user`) via `config('fb-auth.auth_type')`. Stack: PHP 8.5, Laravel 12, Filament 5, Orchestra Testbench + Pest.

## Commands

```bash
composer test            # pest (tests/Tests)
composer analyse         # phpstan level 8 on src/ (larastan)
composer pint            # fix style (CI runs vendor/bin/pint --test)
npm run build            # rebuild assets -> resources/dist (see below)
vendor/bin/pest tests/Tests/CodeLoginPageTest.php   # single test file
```

CI (`.github/workflows/ci.yml`) runs in this order and all must pass before push to `main`/`next`: `pint --test` → `phpstan analyse` → `pest --ci`.

## Gotchas

- **Commits must follow Conventional Commits** (`feat:`, `fix:`, `chore:`) — semantic-release auto-releases from pushes to `main`/`next`.
- **`resources/dist/` is committed.** After changing `resources/css/index.css` or `resources/js/index.js`, run `npm run build` and commit the output — the plugin serves assets from `resources/dist` (registered in `FbAuthServiceProvider::getAssets()`).
- **Translations are bilingual** (Persian `fa` + English `en`): any UI string change must update both `resources/lang/{en,fa}/fb-auth.php`.
- `toEN()` on TextInput is a runtime macro registered by the sibling package **fb-essentials**, not a real method — PHPStan ignores it via `phpstan.neon.dist`; don't "fix" it away.
- Mobile flow depends on sibling packages `mortezamasumi/fb-sms` (SMS gateway, needs `fb-sms.operator` config) and `ariaieboy/filament-jalali`.

## Architecture

- `src/FbAuthPlugin.php` is the wiring point: based on `Enums/AuthType`, it substitutes default page classes for Filament's login/register/password-reset/email-verification pages (`src/Pages/`). It only fills defaults the panel hasn't overridden.
- `FbAuth` service (`src/FbAuth.php`, accessed via `FbAuth` facade) generates/caches OTP codes under cache key `otp-{identifier}` (identifier = `mobile` for the mobile flow, else `email`). All send/verify actions rate-limit at 2/min.
- Code delivery goes through Laravel notifications (`src/Notifications/`): email codes inline, mobile codes via fb-sms.
- Verification replaces Filament's signed-link flow only when the panel calls `->emailVerification()` and the user model implements `MustVerifyEmail`.

## Testing

- Pest, tests in `tests/Tests/`, named by flow prefix: `Link*`, `Code*`, `Mobile*`, `User*`, plus `PluginFlowTest` and `FbAuthServiceTest`.
- `tests/TestCase.php` builds the whole environment inline: creates `users` + `password_reset_tokens` tables, registers an `admin` Filament panel at path `/` with every feature + `FbAuthPlugin`, and loads provider lists for Filament/Livewire/fb-essentials/fb-sms. New providers go there.
- Test user model is `tests/Services/User.php`, set as `AUTH_MODEL` in `phpunit.xml.dist`; DB is SQLite `:memory:` with `RefreshDatabase`.

## Notes

- Implementation plans live in `docs/superpowers/plans/`.
- Releases/CHANGELOG are generated by semantic-release; don't hand-edit version numbers.