2026 05 04 codex 5 5 goal

.agents/skills/developing-with-fortify/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: developing-with-fortify
+description: Laravel Fortify headless authentication backend development. Activate when implementing authentication features including login, registration, password reset, email verification, two-factor authentication (2FA/TOTP), profile updates, headless auth, authentication scaffolding, or auth guards in Laravel applications.
+---
+
+# Laravel Fortify Development
+
+Fortify is a headless authentication backend that provides authentication routes and controllers for Laravel applications.
+
+## Documentation
+
+Use `search-docs` for detailed Laravel Fortify patterns and documentation.
+
+## Usage
+
+- **Routes**: Use `list-routes` with `only_vendor: true` and `action: "Fortify"` to see all registered endpoints
+- **Actions**: Check `app/Actions/Fortify/` for customizable business logic (user creation, password validation, etc.)
+- **Config**: See `config/fortify.php` for all options including features, guards, rate limiters, and username field
+- **Contracts**: Look in `Laravel\Fortify\Contracts\` for overridable response classes (`LoginResponse`, `LogoutResponse`, etc.)
+- **Views**: All view callbacks are set in `FortifyServiceProvider::boot()` using `Fortify::loginView()`, `Fortify::registerView()`, etc.
+
+## Available Features
+
+Enable in `config/fortify.php` features array:
+
+- `Features::registration()` - User registration
+- `Features::resetPasswords()` - Password reset via email
+- `Features::emailVerification()` - Requires User to implement `MustVerifyEmail`
+- `Features::updateProfileInformation()` - Profile updates
+- `Features::updatePasswords()` - Password changes
+- `Features::twoFactorAuthentication()` - 2FA with QR codes and recovery codes
+
+> Use `search-docs` for feature configuration options and customization patterns.
+
+## Setup Workflows
+
+### Two-Factor Authentication Setup
+
+```
+- [ ] Add TwoFactorAuthenticatable trait to User model
+- [ ] Enable feature in config/fortify.php
+- [ ] Run migrations for 2FA columns
+- [ ] Set up view callbacks in FortifyServiceProvider
+- [ ] Create 2FA management UI
+- [ ] Test QR code and recovery codes
+```
+
+> Use `search-docs` for TOTP implementation and recovery code handling patterns.
+
+### Email Verification Setup
+
+```
+- [ ] Enable emailVerification feature in config
+- [ ] Implement MustVerifyEmail interface on User model
+- [ ] Set up verifyEmailView callback
+- [ ] Add verified middleware to protected routes
+- [ ] Test verification email flow
+```
+
+> Use `search-docs` for MustVerifyEmail implementation patterns.
+
+### Password Reset Setup
+
+```
+- [ ] Enable resetPasswords feature in config
+- [ ] Set up requestPasswordResetLinkView callback
+- [ ] Set up resetPasswordView callback
+- [ ] Define password.reset named route (if views disabled)
+- [ ] Test reset email and link flow
+```
+
+> Use `search-docs` for custom password reset flow patterns.
+
+### SPA Authentication Setup
+
+```
+- [ ] Set 'views' => false in config/fortify.php
+- [ ] Install and configure Laravel Sanctum
+- [ ] Use 'web' guard in fortify config
+- [ ] Set up CSRF token handling
+- [ ] Test XHR authentication flows
+```
+
+> Use `search-docs` for integration and SPA authentication patterns.
+
+## Best Practices
+
+### Custom Authentication Logic
+
+Override authentication behavior using `Fortify::authenticateUsing()` for custom user retrieval or `Fortify::authenticateThrough()` to customize the authentication pipeline. Override response contracts in `AppServiceProvider` for custom redirects.
+
+### Registration Customization
+
+Modify `app/Actions/Fortify/CreateNewUser.php` to customize user creation logic, validation rules, and additional fields.
+
+### Rate Limiting
+
+Configure via `fortify.limiters.login` in config. Default configuration throttles by username + IP combination.
+
+## Key Endpoints
+
+| Feature                | Method   | Endpoint                                    |
+|------------------------|----------|---------------------------------------------|
+| Login                  | POST     | `/login`                                    |
+| Logout                 | POST     | `/logout`                                   |
+| Register               | POST     | `/register`                                 |
+| Password Reset Request | POST     | `/forgot-password`                          |
+| Password Reset         | POST     | `/reset-password`                           |
+| Email Verify Notice    | GET      | `/email/verify`                             |
+| Resend Verification    | POST     | `/email/verification-notification`          |
+| Password Confirm       | POST     | `/user/confirm-password`                    |
+| Enable 2FA             | POST     | `/user/two-factor-authentication`           |
+| Confirm 2FA            | POST     | `/user/confirmed-two-factor-authentication` |
+| 2FA Challenge          | POST     | `/two-factor-challenge`                     |
+| Get QR Code            | GET      | `/user/two-factor-qr-code`                  |
+| Recovery Codes         | GET/POST | `/user/two-factor-recovery-codes`           |

.agents/skills/fluxui-development/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: fluxui-development
+description: "Use this skill for Flux UI development in Livewire applications only. Trigger when working with <flux:*> components, building or customizing Livewire component UIs, creating forms, modals, tables, or other interactive elements. Covers: flux: components (buttons, inputs, modals, forms, tables, date-pickers, kanban, badges, tooltips, etc.), component composition, Tailwind CSS styling, Heroicons/Lucide icon integration, validation patterns, responsive design, and theming. Do not use for non-Livewire frameworks or non-component styling."
+license: MIT
+metadata:
+  author: laravel
+---
+
+# Flux UI Development
+
+## Documentation
+
+Use `search-docs` for detailed Flux UI patterns and documentation.
+
+## Basic Usage
+
+This project uses the free edition of Flux UI, which includes all free components and variants but not Pro components.
+
+Flux UI is a component library for Livewire built with Tailwind CSS. It provides components that are easy to use and customize.
+
+Use Flux UI components when available. Fall back to standard Blade components when no Flux component exists for your needs.
+
+<!-- Basic Button -->
+```blade
+<flux:button variant="primary">Click me</flux:button>
+```
+
+## Available Components (Free Edition)
+
+Available: avatar, badge, brand, breadcrumbs, button, callout, checkbox, dropdown, field, heading, icon, input, modal, navbar, otp-input, profile, radio, select, separator, skeleton, switch, text, textarea, tooltip
+
+## Icons
+
+Flux includes [Heroicons](https://heroicons.com/) as its default icon set. Search for exact icon names on the Heroicons site - do not guess or invent icon names.
+
+<!-- Icon Button -->
+```blade
+<flux:button icon="arrow-down-tray">Export</flux:button>
+```
+
+For icons not available in Heroicons, use [Lucide](https://lucide.dev/). Import the icons you need with the Artisan command:
+
+```bash
+php artisan flux:icon crown grip-vertical github
+```
+
+## Common Patterns
+
+### Form Fields
+
+<!-- Form Field -->
+```blade
+<flux:field>
+    <flux:label>Email</flux:label>
+    <flux:input type="email" wire:model="email" />
+    <flux:error name="email" />
+</flux:field>
+```
+
+### Modals
+
+<!-- Modal -->
+```blade
+<flux:modal wire:model="showModal">
+    <flux:heading>Title</flux:heading>
+    <p>Content</p>
+</flux:modal>
+```
+
+## Verification
+
+1. Check component renders correctly
+2. Test interactive states
+3. Verify mobile responsiveness
+
+## Common Pitfalls
+
+- Trying to use Pro-only components in the free edition
+- Not checking if a Flux component exists before creating custom implementations
+- Forgetting to use the `search-docs` tool for component-specific documentation
+- Not following existing project patterns for Flux usage

.agents/skills/laravel-best-practices/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: laravel-best-practices
+description: "Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns."
+license: MIT
+metadata:
+  author: laravel
+---
+
+# Laravel Best Practices
+
+Best practices for Laravel, prioritized by impact. Each rule teaches what to do and why. For exact API syntax, verify with `search-docs`.
+
+## Consistency First
+
+Before applying any rule, check what the application already does. Laravel offers multiple valid approaches — the best choice is the one the codebase already uses, even if another pattern would be theoretically better. Inconsistency is worse than a suboptimal pattern.
+
+Check sibling files, related controllers, models, or tests for established patterns. If one exists, follow it — don't introduce a second way. These rules are defaults for when no pattern exists yet, not overrides.
+
+## Quick Reference
+
+### 1. Database Performance → `rules/db-performance.md`
+
+- Eager load with `with()` to prevent N+1 queries
+- Enable `Model::preventLazyLoading()` in development
+- Select only needed columns, avoid `SELECT *`
+- `chunk()` / `chunkById()` for large datasets
+- Index columns used in `WHERE`, `ORDER BY`, `JOIN`
+- `withCount()` instead of loading relations to count
+- `cursor()` for memory-efficient read-only iteration
+- Never query in Blade templates
+
+### 2. Advanced Query Patterns → `rules/advanced-queries.md`
+
+- `addSelect()` subqueries over eager-loading entire has-many for a single value
+- Dynamic relationships via subquery FK + `belongsTo`
+- Conditional aggregates (`CASE WHEN` in `selectRaw`) over multiple count queries
+- `setRelation()` to prevent circular N+1 queries
+- `whereIn` + `pluck()` over `whereHas` for better index usage
+- Two simple queries can beat one complex query
+- Compound indexes matching `orderBy` column order
+- Correlated subqueries in `orderBy` for has-many sorting (avoid joins)
+
+### 3. Security → `rules/security.md`
+
+- Define `$fillable` or `$guarded` on every model, authorize every action via policies or gates
+- No raw SQL with user input — use Eloquent or query builder
+- `{{ }}` for output escaping, `@csrf` on all POST/PUT/DELETE forms, `throttle` on auth and API routes
+- Validate MIME type, extension, and size for file uploads
+- Never commit `.env`, use `config()` for secrets, `encrypted` cast for sensitive DB fields
+
+### 4. Caching → `rules/caching.md`
+
+- `Cache::remember()` over manual get/put
+- `Cache::flexible()` for stale-while-revalidate on high-traffic data
+- `Cache::memo()` to avoid redundant cache hits within a request
+- Cache tags to invalidate related groups
+- `Cache::add()` for atomic conditional writes
+- `once()` to memoize per-request or per-object lifetime
+- `Cache::lock()` / `lockForUpdate()` for race conditions
+- Failover cache stores in production
+
+### 5. Eloquent Patterns → `rules/eloquent.md`
+
+- Correct relationship types with return type hints
+- Local scopes for reusable query constraints
+- Global scopes sparingly — document their existence
+- Attribute casts in the `casts()` method
+- Cast date columns, use Carbon instances in templates
+- `whereBelongsTo($model)` for cleaner queries
+- Never hardcode table names — use `(new Model)->getTable()` or Eloquent queries
+
+### 6. Validation & Forms → `rules/validation.md`
+
+- Form Request classes, not inline validation
+- Array notation `['required', 'email']` for new code; follow existing convention
+- `$request->validated()` only — never `$request->all()`
+- `Rule::when()` for conditional validation
+- `after()` instead of `withValidator()`
+
+### 7. Configuration → `rules/config.md`
+
+- `env()` only inside config files
+- `App::environment()` or `app()->isProduction()`
+- Config, lang files, and constants over hardcoded text
+
+### 8. Testing Patterns → `rules/testing.md`
+
+- `LazilyRefreshDatabase` over `RefreshDatabase` for speed
+- `assertModelExists()` over raw `assertDatabaseHas()`
+- Factory states and sequences over manual overrides
+- Use fakes (`Event::fake()`, `Exceptions::fake()`, etc.) — but always after factory setup, not before
+- `recycle()` to share relationship instances across factories
+
+### 9. Queue & Job Patterns → `rules/queue-jobs.md`
+
+- `retry_after` must exceed job `timeout`; use exponential backoff `[1, 5, 10]`
+- `ShouldBeUnique` to prevent duplicates; `ShouldBeUniqueUntilProcessing` for early lock release
+- Always implement `failed()`; with `retryUntil()`, set `$tries = 0`
+- `RateLimited` middleware for external API calls; `Bus::batch()` for related jobs
+- Horizon for complex multi-queue scenarios
+
+### 10. Routing & Controllers → `rules/routing.md`
+
+- Implicit route model binding
+- Scoped bindings for nested resources
+- `Route::resource()` or `apiResource()`
+- Methods under 10 lines — extract to actions/services
+- Type-hint Form Requests for auto-validation
+
+### 11. HTTP Client → `rules/http-client.md`
+
+- Explicit `timeout` and `connectTimeout` on every request
+- `retry()` with exponential backoff for external APIs
+- Check response status or use `throw()`
+- `Http::pool()` for concurrent independent requests
+- `Http::fake()` and `preventStrayRequests()` in tests
+
+### 12. Events, Notifications & Mail → `rules/events-notifications.md`, `rules/mail.md`
+
+- Event discovery over manual registration; `event:cache` in production
+- `ShouldDispatchAfterCommit` / `afterCommit()` inside transactions
+- Queue notifications and mailables with `ShouldQueue`
+- On-demand notifications for non-user recipients
+- `HasLocalePreference` on notifiable models
+- `assertQueued()` not `assertSent()` for queued mailables
+- Markdown mailables for transactional emails
+
+### 13. Error Handling → `rules/error-handling.md`
+
+- `report()`/`render()` on exception classes or in `bootstrap/app.php` — follow existing pattern
+- `ShouldntReport` for exceptions that should never log
+- Throttle high-volume exceptions to protect log sinks
+- `dontReportDuplicates()` for multi-catch scenarios
+- Force JSON rendering for API routes
+- Structured context via `context()` on exception classes
+
+### 14. Task Scheduling → `rules/scheduling.md`
+
+- `withoutOverlapping()` on variable-duration tasks
+- `onOneServer()` on multi-server deployments
+- `runInBackground()` for concurrent long tasks
+- `environments()` to restrict to appropriate environments
+- `takeUntilTimeout()` for time-bounded processing
+- Schedule groups for shared configuration
+
+### 15. Architecture → `rules/architecture.md`
+
+- Single-purpose Action classes; dependency injection over `app()` helper
+- Prefer official Laravel packages and follow conventions, don't override defaults
+- Default to `ORDER BY id DESC` or `created_at DESC`; `mb_*` for UTF-8 safety
+- `defer()` for post-response work; `Context` for request-scoped data; `Concurrency::run()` for parallel execution
+
+### 16. Migrations → `rules/migrations.md`
+
+- Generate migrations with `php artisan make:migration`
+- `constrained()` for foreign keys
+- Never modify migrations that have run in production
+- Add indexes in the migration, not as an afterthought
+- Mirror column defaults in model `$attributes`
+- Reversible `down()` by default; forward-fix migrations for intentionally irreversible changes
+- One concern per migration — never mix DDL and DML
+
+### 17. Collections → `rules/collections.md`
+
+- Higher-order messages for simple collection operations
+- `cursor()` vs. `lazy()` — choose based on relationship needs
+- `lazyById()` when updating records while iterating
+- `toQuery()` for bulk operations on collections
+
+### 18. Blade & Views → `rules/blade-views.md`
+
+- `$attributes->merge()` in component templates
+- Blade components over `@include`; `@pushOnce` for per-component scripts
+- View Composers for shared view data
+- `@aware` for deeply nested component props
+
+### 19. Conventions & Style → `rules/style.md`
+
+- Follow Laravel naming conventions for all entities
+- Prefer Laravel helpers (`Str`, `Arr`, `Number`, `Uri`, `Str::of()`, `$request->string()`) over raw PHP functions
+- No JS/CSS in Blade, no HTML in PHP classes
+- Code should be readable; comments only for config files
+
+## How to Apply
+
+Always use a sub-agent to read rule files and explore this skill's content.
+
+1. Identify the file type and select relevant sections (e.g., migration → §16, controller → §1, §3, §5, §6, §10)
+2. Check sibling files for existing patterns — follow those first per Consistency First
+3. Verify API syntax with `search-docs` for the installed Laravel version