@mohammadhprp/system-prompt 0.10.1

package/framework/skills/laravel-best-practices/references/passport.md

@@ -0,0 +1,197 @@
+# Passport OAuth2 Authentication
+
+## Documentation First
+
+**Always use `search-docs` before writing Passport code.** The documentation covers every grant type, configuration option, and edge case in detail. This skill teaches you how to navigate Passport — the docs have the implementation specifics.
+
+```
+search-docs(queries: ["Passport installation"], packages: ["laravel/framework@12.x"])
+```
+
+The Passport docs live under the `laravel/framework` package — not `laravel/passport`.
+
+## When to Apply
+
+Activate this skill when:
+
+- Installing or configuring Passport
+- Setting up OAuth2 authorization grants
+- Creating or managing OAuth clients
+- Protecting API routes with token authentication
+- Defining or checking token scopes
+- Configuring SPA cookie-based authentication
+- Choosing between Passport and Sanctum
+
+## Passport vs. Sanctum
+
+**Passport** is a full OAuth2 server — use it when third-party applications need to consume your API and when you need OAuth2 authorization code grants, client credentials for machine-to-machine auth, or device authorization flow.
+
+**Sanctum** is simpler — use it when first-party SPAs, third parties, or mobile apps consume the API but you don't need the full OAuth2 grant flows.
+
+## Installation
+
+Three steps are always required:
+
+### 1. Install Passport
+
+```bash
+php artisan install:api --passport
+```
+
+This publishes migrations, generates encryption keys, and registers routes.
+
+### 2. Configure the User model
+
+The User model needs both the `HasApiTokens` trait AND the `OAuthenticatable` interface. Missing the interface is the most common Passport setup mistake — it causes runtime errors that can be confusing to debug.
+
+```php
+use Laravel\Passport\Contracts\OAuthenticatable;
+use Laravel\Passport\HasApiTokens;
+
+class User extends Authenticatable implements OAuthenticatable
+{
+    use HasApiTokens;
+}
+```
+
+### 3. Configure the auth guard
+
+The `api` guard must use the `passport` driver in `config/auth.php`. Using `token` or `sanctum` here silently breaks Passport authentication.
+
+```php
+'guards' => [
+    'api' => [
+        'driver' => 'passport',
+        'provider' => 'users',
+    ],
+],
+```
+
+## Choosing a Grant Type
+
+Matching the right grant to the use case is the most important Passport decision. Use `search-docs` for implementation details of any grant.
+
+| Use Case | Grant Type | Client Flag |
+|----------|-----------|-------------|
+| Third-party app accessing user data | Authorization Code | (default) |
+| Mobile/SPA without client secret | Authorization Code + PKCE | `--public` |
+| Machine-to-machine, no user context | Client Credentials | `--client` |
+| User-generated API keys | Personal Access Tokens | `--personal` |
+| Smart TV, CLI, IoT devices | Device Authorization | `--device` |
+
+**Legacy grants** (Password, Implicit) are disabled by default and not recommended. They must be explicitly enabled with `Passport::enablePasswordGrant()` or `Passport::enableImplicitGrant()`.
+
+## Client Management
+
+Create clients with the appropriate flag for the grant type:
+
+```bash
+php artisan passport:client              # Authorization code
+
+php artisan passport:client --public     # PKCE (no secret)
+
+php artisan passport:client --client     # Client credentials
+
+php artisan passport:client --personal   # Personal access tokens
+
+php artisan passport:client --device     # Device authorization
+
+```
+
+Additional flags: `--name=`, `--redirect_uri=`, `--provider=`.
+
+Client secrets are hashed by default — the plain-text secret is only shown at creation time and cannot be retrieved later.
+
+## Protecting Routes
+
+Apply `auth:api` middleware. Clients send tokens via the `Authorization: Bearer <token>` header.
+
+```php
+Route::get('/user', function (Request $request) {
+    return $request->user();
+})->middleware('auth:api');
+```
+
+### Scope Enforcement
+
+Scope middleware must come alongside `auth:api`:
+
+- `CheckToken::using('scope1', 'scope2')` — requires ALL listed scopes
+- `CheckTokenForAnyScope::using('scope1', 'scope2')` — requires ANY listed scope
+- `EnsureClientIsResourceOwner::using('scope1')` — restricts to client credential tokens
+
+```php
+use Laravel\Passport\Http\Middleware\CheckToken;
+
+Route::get('/orders', function () {
+    // ...
+})->middleware(['auth:api', CheckToken::using('orders:read')]);
+```
+
+### Programmatic scope checking
+
+```php
+if ($request->user()->tokenCan('place-orders')) {
+    // ...
+}
+```
+
+Use `search-docs` for full scope middleware registration and usage patterns.
+
+## Key Configuration
+
+Configure in `AppServiceProvider::boot()`. Use `search-docs` for the full list of options.
+
+```php
+// Token lifetimes (each is independent)
+Passport::tokensExpireIn(now()->addDays(15));
+Passport::refreshTokensExpireIn(now()->addDays(30));
+Passport::personalAccessTokensExpireIn(now()->addMonths(6));
+
+// Define scopes
+Passport::tokensCan([
+    'place-orders' => 'Place orders',
+    'check-status' => 'Check order status',
+]);
+```
+
+## SPA Cookie Authentication
+
+For first-party SPAs, the `CreateFreshApiToken` middleware issues a `laravel_token` cookie containing an encrypted JWT. The SPA must include CSRF tokens — missing the `X-CSRF-TOKEN` or `X-XSRF-TOKEN` header causes 419 errors.
+
+Use `search-docs` for setup details — this feature has specific CSRF and cookie configuration requirements.
+
+## Testing
+
+Passport provides helpers to bypass full OAuth flows in tests:
+
+```php
+Passport::actingAs($user, ['scope1', 'scope2']);
+Passport::actingAsClient($client, ['scope1']);
+```
+
+## Token Maintenance
+
+```bash
+php artisan passport:purge              # Purge revoked & expired
+
+php artisan passport:purge --revoked    # Only revoked
+
+php artisan passport:purge --expired    # Only expired
+
+```
+
+Schedule `passport:purge` for regular expired token clean-up.
+
+## Events
+
+All in `Laravel\Passport\Events`: `AccessTokenCreated`, `AccessTokenRevoked`, `RefreshTokenCreated`.
+
+## Common Pitfalls
+
+- **Missing `OAuthenticatable` interface** — both the `HasApiTokens` trait and the `OAuthenticatable` interface are required on the User model. Missing the interface causes runtime errors.
+- **Wrong guard driver** — the `api` guard must use `passport`, not `token` or `sanctum`. This fails silently.
+- **Token lifetime confusion** — access token, refresh token, and personal access token lifetimes are all independent settings.
+- **Missing CSRF for SPA cookie auth** — `CreateFreshApiToken` requires CSRF tokens. Use `Passport::ignoreCsrfToken()` only if you understand the security implications.
+- **Client secrets are hashed** — the plain-text secret is only available at creation time.
+- **Legacy grants are disabled** — Password and Implicit grants must be explicitly enabled and are not recommended.

package/framework/skills/laravel-best-practices/references/pennant.md

@@ -0,0 +1,61 @@
+# Pennant Features
+
+## Documentation
+
+Use `search-docs` for detailed Pennant patterns and documentation.
+
+## Basic Usage
+
+### Defining Features
+
+<!-- Defining Features -->
+```php
+use Laravel\Pennant\Feature;
+
+Feature::define('new-dashboard', function (User $user) {
+    return $user->isAdmin();
+});
+```
+
+### Checking Features
+
+<!-- Checking Features -->
+```php
+if (Feature::active('new-dashboard')) {
+    // Feature is active
+}
+
+// With scope
+if (Feature::for($user)->active('new-dashboard')) {
+    // Feature is active for this user
+}
+```
+
+### Blade Directive
+
+<!-- Blade Directive -->
+```blade
+@feature('new-dashboard')
+    <x-new-dashboard />
+@else
+    <x-old-dashboard />
+@endfeature
+```
+
+### Activating / Deactivating
+
+<!-- Activating Features -->
+```php
+Feature::activate('new-dashboard');
+Feature::for($user)->activate('new-dashboard');
+```
+
+## Verification
+
+1. Check feature flag is defined
+2. Test with different scopes/users
+
+## Common Pitfalls
+
+- Forgetting to scope features for specific users/entities
+- Not following existing naming conventions

package/framework/skills/laravel-best-practices/references/pest-testing.md

@@ -0,0 +1,166 @@
+---
+name: pest-testing
+description: "Use this skill for Pest PHP testing in Laravel projects only. Trigger whenever any test is being written, edited, fixed, or refactored — including fixing tests that broke after a code change, adding assertions, converting PHPUnit to Pest, adding datasets, and TDD workflows. Always activate when the user asks how to write something in Pest, mentions test files or directories (tests/Feature, tests/Unit, tests/Browser), or needs browser testing, smoke testing multiple pages for JS errors, or architecture tests. Covers: test()/it()/expect() syntax, datasets, mocking, browser testing (visit/click/fill), smoke testing, arch(), Livewire component tests, RefreshDatabase, and all Pest 4 features. Do not use for factories, seeders, migrations, controllers, models, or non-test PHP code."
+license: MIT
+metadata:
+  author: laravel
+---
+
+# Pest Testing 4
+
+## Documentation
+
+Use `search-docs` for detailed Pest 4 patterns and documentation.
+
+## Basic Usage
+
+### Creating Tests
+
+All tests must be written using Pest. Use `php artisan make:test --pest {name}`.
+
+The `{name}` argument should include only the path and test name, but should not include the test suite.
+- Incorrect: `php artisan make:test --pest Feature/SomeFeatureTest` will generate `tests/Feature/Feature/SomeFeatureTest.php`
+- Correct: `php artisan make:test --pest SomeControllerTest` will generate `tests/Feature/SomeControllerTest.php`
+- Incorrect: `php artisan make:test --pest --unit Unit/SomeServiceTest` will generate `tests/Unit/Unit/SomeServiceTest.php`
+- Correct: `php artisan make:test --pest --unit SomeServiceTest` will generate `tests/Unit/SomeServiceTest.php`
+
+### Test Organization
+
+- Unit/Feature tests: `tests/Feature` and `tests/Unit` directories.
+- Browser tests: `tests/Browser/` directory.
+- Do NOT remove tests without approval - these are core application code.
+
+### Basic Test Structure
+
+Pest supports both `test()` and `it()` functions. Before writing new tests, check existing test files in the same directory to match the project's convention. Use `test()` if existing tests use `test()`, or `it()` if they use `it()`.
+
+<!-- Basic Pest Test Example -->
+```php
+it('is true', function () {
+    expect(true)->toBeTrue();
+});
+```
+
+### Running Tests
+
+- Run minimal tests with filter before finalizing: `php artisan test --compact --filter=testName`.
+- Run all tests: `php artisan test --compact`.
+- Run file: `php artisan test --compact tests/Feature/ExampleTest.php`.
+
+## Assertions
+
+Use specific assertions (`assertSuccessful()`, `assertNotFound()`) instead of `assertStatus()`:
+
+<!-- Pest Response Assertion -->
+```php
+it('returns all', function () {
+    $this->postJson('/api/docs', [])->assertSuccessful();
+});
+```
+
+| Use | Instead of |
+|-----|------------|
+| `assertSuccessful()` | `assertStatus(200)` |
+| `assertNotFound()` | `assertStatus(404)` |
+| `assertForbidden()` | `assertStatus(403)` |
+
+## Mocking
+
+Import mock function before use: `use function Pest\Laravel\mock;`
+
+## Datasets
+
+Use datasets for repetitive tests (validation rules, etc.):
+
+<!-- Pest Dataset Example -->
+```php
+it('has emails', function (string $email) {
+    expect($email)->not->toBeEmpty();
+})->with([
+    'james' => 'james@laravel.com',
+    'taylor' => 'taylor@laravel.com',
+]);
+```
+
+## Pest 4 Features
+
+| Feature | Purpose |
+|---------|---------|
+| Browser Testing | Full integration tests in real browsers |
+| Smoke Testing | Validate multiple pages quickly |
+| Visual Regression | Compare screenshots for visual changes |
+| Test Sharding | Parallel CI runs |
+| Architecture Testing | Enforce code conventions |
+
+### Browser Test Example
+
+Browser tests run in real browsers for full integration testing:
+
+- Browser tests live in `tests/Browser/`.
+- Use Laravel features like `Event::fake()`, `assertAuthenticated()`, and model factories.
+- Use `RefreshDatabase` for clean state per test.
+- Interact with page: click, type, scroll, select, submit, drag-and-drop, touch gestures.
+- Test on multiple browsers (Chrome, Firefox, Safari) if requested.
+- Test on different devices/viewports (iPhone 14 Pro, tablets) if requested.
+- Switch color schemes (light/dark mode) when appropriate.
+- Take screenshots or pause tests for debugging.
+
+<!-- Pest Browser Test Example -->
+```php
+it('may reset the password', function () {
+    Notification::fake();
+
+    $this->actingAs(User::factory()->create());
+
+    $page = visit('/sign-in');
+
+    $page->assertSee('Sign In')
+        ->assertNoJavaScriptErrors()
+        ->click('Forgot Password?')
+        ->fill('email', 'nuno@laravel.com')
+        ->click('Send Reset Link')
+        ->assertSee('We have emailed your password reset link!');
+
+    Notification::assertSent(ResetPassword::class);
+});
+```
+
+### Smoke Testing
+
+Quickly validate multiple pages have no JavaScript errors:
+
+<!-- Pest Smoke Testing Example -->
+```php
+$pages = visit(['/', '/about', '/contact']);
+
+$pages->assertNoJavaScriptErrors()->assertNoConsoleLogs();
+```
+
+### Visual Regression Testing
+
+Capture and compare screenshots to detect visual changes.
+
+### Test Sharding
+
+Split tests across parallel processes for faster CI runs.
+
+### Architecture Testing
+
+Pest 4 includes architecture testing (from Pest 3):
+
+<!-- Architecture Test Example -->
+```php
+arch('controllers')
+    ->expect('App\Http\Controllers')
+    ->toExtendNothing()
+    ->toHaveSuffix('Controller');
+```
+
+## Common Pitfalls
+
+- Not importing `use function Pest\Laravel\mock;` before using mock
+- Using `assertStatus(200)` instead of `assertSuccessful()`
+- Forgetting datasets for repetitive validation tests
+- Deleting tests without approval
+- Forgetting `assertNoJavaScriptErrors()` in browser tests
+- Prefixing `Feature/` or `Unit/` in `{name}` when using `make:test`

package/framework/skills/laravel-best-practices/references/pulse.md

@@ -0,0 +1,196 @@
+# Laravel Pulse Development
+
+## Documentation
+
+Use `search-docs` for detailed Laravel Pulse patterns and documentation, including card layout customization, user resolver configuration, all recorder options, sampling, dedicated database connections, Vite/CSS integration, Tailwind scoping, blade card components, and lazy loading.
+
+## Installation
+
+Pulse stores data in your application's database. The current package supports MySQL, MariaDB, PostgreSQL, and SQLite.
+
+```bash
+composer require laravel/pulse
+php artisan vendor:publish --provider="Laravel\Pulse\PulseServiceProvider"
+php artisan migrate
+```
+
+The dashboard is available at `/pulse`. 
+
+## Dashboard Authorization
+
+Define the `viewPulse` gate in `AppServiceProvider::boot()` to enable production access:
+
+<!-- Pulse Dashboard Authorization -->
+```php
+use App\Models\User;
+use Illuminate\Support\Facades\Gate;
+
+Gate::define('viewPulse', function (User $user) {
+    return $user->isAdmin();
+});
+```
+
+Without this gate, the dashboard is inaccessible in all non-local environments.
+
+## Recorders
+
+All 10 built-in recorders are configurable in `config/pulse.php`:
+
+| Recorder | Key Config Options |
+|---|---|
+| `CacheInteractions` | `sample_rate`, `ignore`, `groups` (regex find/replace) |
+| `Exceptions` | `sample_rate`, `ignore`, `location` |
+| `Queues` | `sample_rate`, `ignore` |
+| `SlowJobs` | `threshold` (ms, per-job regex map), `sample_rate`, `ignore` |
+| `SlowOutgoingRequests` | `threshold` (ms, per-URL regex map), `sample_rate`, `ignore`, `groups` |
+| `SlowQueries` | `threshold` (ms, per-query regex map), `sample_rate`, `ignore`, `location` |
+| `SlowRequests` | `threshold` (ms, per-route regex map), `sample_rate`, `ignore` |
+| `Servers` | `PULSE_SERVER_NAME` env var, monitored disk paths |
+| `UserJobs` | `sample_rate`, `ignore` |
+| `UserRequests` | `sample_rate`, `ignore` |
+
+Per-route and per-job threshold overrides use a regex-keyed map with a `default` fallback:
+
+<!-- Per-Route Threshold Override -->
+```php
+Recorders\SlowRequests::class => [
+    'threshold' => [
+        '#^/api/reports#' => 5000,
+        'default'         => env('PULSE_SLOW_REQUESTS_THRESHOLD', 1000),
+    ],
+],
+```
+
+The `Servers` recorder requires `pulse:check` running as a persistent daemon (Supervisor recommended).
+
+### Filtering Entries
+
+Use `Pulse::filter()` in `AppServiceProvider::boot()` to exclude entries globally. Return `true` to record, `false` to skip:
+
+<!-- Pulse Entry Filter -->
+```php
+use Laravel\Pulse\Entry;
+use Laravel\Pulse\Facades\Pulse;
+use Laravel\Pulse\Value;
+use Illuminate\Support\Facades\Auth;
+
+Pulse::filter(function (Entry|Value $entry) {
+    return Auth::user()?->isNotAdmin() ?? true;
+});
+```
+
+## Performance
+
+### Redis Ingest
+
+Offload entry writes from the request cycle to a Redis stream (requires Redis 6.2+ and `phpredis` or `predis`):
+
+```ini
+PULSE_INGEST_DRIVER=redis
+PULSE_REDIS_CONNECTION=pulse
+```
+
+Run a worker to drain the Redis stream into the database:
+
+```bash
+php artisan pulse:work
+```
+
+Signal a graceful restart during deployment (requires a working cache driver):
+
+```bash
+php artisan pulse:restart
+```
+
+## Custom Cards
+
+Custom cards are Livewire components extending Pulse's base `Card` class.
+
+### Recording Entries
+
+Call `Pulse::record()` from a recorder, listener, or observer. Chain aggregation methods (`avg`, `count`, `max`, `min`, `sum`) in a single call:
+
+<!-- Record Pulse Entry -->
+```php
+use Laravel\Pulse\Facades\Pulse;
+
+Pulse::record('user_sale', $user->id, $sale->amount)
+    ->sum()
+    ->count();
+```
+
+When the entry is tied to the authenticated user, use `Pulse::resolveAuthenticatedUserId()` instead of `Auth::id()` to respect custom user resolvers.
+
+### Card Component
+
+<!-- Custom Pulse Card -->
+```php
+namespace App\Livewire\Pulse;
+
+use Laravel\Pulse\Facades\Pulse;
+use Laravel\Pulse\Livewire\Card;
+use Livewire\Attributes\Lazy;
+
+#[Lazy]
+class TopSellers extends Card
+{
+    public function render(): \Illuminate\View\View
+    {
+        $aggregates = $this->aggregate('user_sale', ['sum', 'count']);
+        $users = Pulse::resolveUsers($aggregates->pluck('key'));
+
+        return view('livewire.pulse.top-sellers', [
+            'sellers' => $aggregates->map(fn ($row) => (object) [
+                'user'  => $users->find($row->key),
+                'sum'   => $row->sum,
+                'count' => $row->count,
+            ]),
+        ]);
+    }
+}
+```
+
+`$this->aggregate(type, aggregates)` returns a `Collection` of `stdClass` objects with `key` and one property per aggregation method. `$this->aggregateTotal(type, aggregate)` returns a single scalar.
+
+### Custom Recorders
+
+A recorder is a plain class with a `$listen` array of Laravel events:
+
+<!-- Custom Pulse Recorder -->
+```php
+class SaleRecorder
+{
+    public array $listen = [
+        \App\Events\SaleCompleted::class,
+    ];
+
+    public function record(\App\Events\SaleCompleted $event): void
+    {
+        \Laravel\Pulse\Facades\Pulse::record('user_sale', $event->user->id, $event->sale->amount)
+            ->sum()
+            ->count();
+    }
+}
+```
+
+Register the recorder in the `recorders` array in `config/pulse.php`.
+
+## Verification
+
+1. Run migrations and confirm `/pulse` is accessible in local
+2. Define `viewPulse` gate and verify production access
+3. Confirm `pulse:check` is running for the Servers card
+4. If using Redis ingest, confirm `pulse:work` is running
+
+## Common Pitfalls
+
+- An empty dashboard or database errors usually mean the Pulse tables have not been published and migrated yet.
+- The dashboard is local-only by default. Define the `viewPulse` gate to enable production access.
+- The Servers card shows no data unless `pulse:check` runs as a persistent process. Supervisor is recommended.
+- Redis ingest silently queues data. The dashboard appears empty if `pulse:work` is not running.
+- `pulse:restart` requires a working cache driver. Without it, the signal is never received.
+- Pulse exceptions fail silently. Use `Pulse::handleExceptionsUsing()` to surface errors during development.
+- Multiple `Authenticatable` models can cause incorrect user tracking. Use `Pulse::resolveAuthenticatedUserId()` when recording user-keyed entries.
+- SQS queues may appear duplicated in the Queue card. Use `ignore` regex patterns to suppress them.
+- Sampled dashboard values are approximate and prefixed with `~`. They are not suitable for financial or audit reporting.
+- Always use `search-docs` for the latest Pulse documentation rather than relying on this skill alone.