@mohammadhprp/system-prompt 0.10.1

package/framework/skills/laravel-best-practices/references/queue-jobs.md

@@ -0,0 +1,144 @@
+# Queue & Job Best Practices
+
+## Set `retry_after` Greater Than `timeout`
+
+If `retry_after` is shorter than the job's `timeout`, the queue worker re-dispatches the job while it's still running, causing duplicate execution.
+
+Incorrect (`retry_after` ≤ `timeout`):
+```php
+class ProcessReport implements ShouldQueue
+{
+    public $timeout = 120;
+}
+
+// config/queue.php — retry_after: 90 ← job retried while still running!
+```
+
+Correct (`retry_after` > `timeout`):
+```php
+class ProcessReport implements ShouldQueue
+{
+    public $timeout = 120;
+}
+
+// config/queue.php — retry_after: 180 ← safely longer than any job timeout
+```
+
+## Use Exponential Backoff
+
+Use progressively longer delays between retries to avoid hammering failing services.
+
+Incorrect (fixed retry interval):
+```php
+class SyncWithStripe implements ShouldQueue
+{
+    public $tries = 3;
+    // Default: retries immediately, overwhelming the API
+}
+```
+
+Correct (exponential backoff):
+```php
+class SyncWithStripe implements ShouldQueue
+{
+    public $tries = 3;
+    public $backoff = [1, 5, 10];
+}
+```
+
+## Implement `ShouldBeUnique`
+
+Prevent duplicate job processing.
+
+```php
+class GenerateInvoice implements ShouldQueue, ShouldBeUnique
+{
+    public function uniqueId(): string
+    {
+        return $this->order->id;
+    }
+
+    public $uniqueFor = 3600;
+}
+```
+
+## Always Implement `failed()`
+
+Handle errors explicitly — don't rely on silent failure.
+
+```php
+public function failed(?Throwable $exception): void
+{
+    $this->podcast->update(['status' => 'failed']);
+    Log::error('Processing failed', ['id' => $this->podcast->id, 'error' => $exception->getMessage()]);
+}
+```
+
+## Rate Limit External API Calls in Jobs
+
+Use `RateLimited` middleware to throttle jobs calling third-party APIs.
+
+```php
+public function middleware(): array
+{
+    return [new RateLimited('external-api')];
+}
+```
+
+## Batch Related Jobs
+
+Use `Bus::batch()` when jobs should succeed or fail together.
+
+```php
+Bus::batch([
+    new ImportCsvChunk($chunk1),
+    new ImportCsvChunk($chunk2),
+])
+->then(fn (Batch $batch) => Notification::send($user, new ImportComplete))
+->catch(fn (Batch $batch, Throwable $e) => Log::error('Batch failed'))
+->dispatch();
+```
+
+## `retryUntil()` Needs `$tries = 0`
+
+When using time-based retry limits, set `$tries = 0` to avoid premature failure.
+
+```php
+public $tries = 0;
+
+public function retryUntil(): \DateTimeInterface
+{
+    return now()->addHours(4);
+}
+```
+
+## Use `ShouldBeUniqueUntilProcessing` for Early Lock Release
+
+`ShouldBeUnique` holds the lock until the job completes. `ShouldBeUniqueUntilProcessing` releases it when processing starts, allowing new instances to queue.
+
+```php
+class UpdateSearchIndex implements ShouldQueue, ShouldBeUniqueUntilProcessing
+{
+    // Lock releases when processing begins, not when it finishes
+}
+```
+
+## Use Horizon for Complex Queue Scenarios
+
+Use Laravel Horizon when you need monitoring, auto-scaling, failure tracking, or multiple queues with different priorities.
+
+```php
+// config/horizon.php
+'environments' => [
+    'production' => [
+        'supervisor-1' => [
+            'connection' => 'redis',
+            'queue' => ['high', 'default', 'low'],
+            'balance' => 'auto',
+            'minProcesses' => 1,
+            'maxProcesses' => 10,
+            'tries' => 3,
+        ],
+    ],
+],
+```

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

@@ -0,0 +1,99 @@
+# Routing & Controllers Best Practices
+
+## Use Implicit Route Model Binding
+
+Let Laravel resolve models automatically from route parameters.
+
+Incorrect:
+```php
+public function show(int $id)
+{
+    $post = Post::findOrFail($id);
+}
+```
+
+Correct:
+```php
+public function show(Post $post)
+{
+    return view('posts.show', ['post' => $post]);
+}
+```
+
+## Use Scoped Bindings for Nested Resources
+
+Enforce parent-child relationships automatically.
+
+```php
+Route::get('/users/{user}/posts/{post}', function (User $user, Post $post) {
+    // $post is automatically scoped to $user
+})->scopeBindings();
+```
+
+## Use Resource Controllers
+
+Use `Route::resource()` or `apiResource()` for RESTful endpoints.
+
+```php
+Route::resource('posts', PostController::class);
+// In routes/api.php — the /api prefix is applied automatically
+Route::apiResource('posts', Api\PostController::class);
+```
+
+## Keep Controllers Thin
+
+Aim for under 10 lines per method. Extract business logic to action or service classes.
+
+Incorrect:
+```php
+public function store(Request $request)
+{
+    $validated = $request->validate([...]);
+    if ($request->hasFile('image')) {
+        $request->file('image')->move(public_path('images'));
+    }
+    $post = Post::create($validated);
+    $post->tags()->sync($validated['tags']);
+    event(new PostCreated($post));
+    return redirect()->route('posts.show', $post);
+}
+```
+
+Correct:
+```php
+public function store(StorePostRequest $request, CreatePostAction $create)
+{
+    $post = $create->execute($request->validated());
+
+    return redirect()->route('posts.show', $post);
+}
+```
+
+## Type-Hint Form Requests
+
+Type-hinting Form Requests triggers automatic validation and authorization before the method executes.
+
+Incorrect:
+```php
+public function store(Request $request): RedirectResponse
+{
+    $validated = $request->validate([
+        'title' => ['required', 'max:255'],
+        'body' => ['required'],
+    ]);
+
+    Post::create($validated);
+
+    return redirect()->route('posts.index');
+}
+```
+
+Correct:
+```php
+public function store(StorePostRequest $request): RedirectResponse
+{
+    Post::create($request->validated());
+
+    return redirect()->route('posts.index');
+}
+```

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

@@ -0,0 +1,39 @@
+# Task Scheduling Best Practices
+
+## Use `withoutOverlapping()` on Variable-Duration Tasks
+
+Without it, a long-running task spawns a second instance on the next tick, causing double-processing or resource exhaustion.
+
+## Use `onOneServer()` on Multi-Server Deployments
+
+Without it, every server runs the same task simultaneously. Requires a shared cache driver (Redis, database, Memcached).
+
+## Use `runInBackground()` for Concurrent Long Tasks
+
+By default, tasks at the same tick run sequentially. A slow first task delays all subsequent ones. `runInBackground()` runs them as separate processes.
+
+## Use `environments()` to Restrict Tasks
+
+Prevent accidental execution of production-only tasks (billing, reporting) on staging.
+
+```php
+Schedule::command('billing:charge')->monthly()->environments(['production']);
+```
+
+## Use `takeUntilTimeout()` for Time-Bounded Processing
+
+A task running every 15 minutes that processes an unbounded cursor can overlap with the next run. Bound execution time.
+
+## Use Schedule Groups for Shared Configuration
+
+Avoid repeating `->onOneServer()->timezone('America/New_York')` across many tasks.
+
+```php
+Schedule::daily()
+    ->onOneServer()
+    ->timezone('America/New_York')
+    ->group(function () {
+        Schedule::command('emails:send --force');
+        Schedule::command('emails:prune');
+    });
+```

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

@@ -0,0 +1,176 @@
+# Scout Full-Text Search
+
+## Documentation First
+
+**Always use `search-docs` before writing Scout code.** The documentation covers every engine, configuration option, and edge case in detail. This skill teaches you how to navigate Scout — the docs have the implementation specifics.
+
+```
+search-docs(queries: ["Scout installation"], packages: ["laravel/framework@12.x"])
+```
+
+The Scout docs live under the `laravel/framework` package — not `laravel/scout`.
+
+Effective search patterns:
+
+- Installation & setup: `"Scout installation"`, `"Scout queueing"`
+- Engine setup: `"Scout Algolia"`, `"Scout Meilisearch"`, `"Scout Typesense"`
+- Model configuration: `"Scout configuring searchable data"`, `"Scout configuring model indexes"`
+- Searching: `"Scout searching"`, `"Scout where clauses"`, `"Scout pagination"`
+- Indexing: `"Scout batch import"`, `"Scout adding records"`, `"Scout removing records"`
+- Advanced: `"Scout soft deleting"`, `"Scout customizing engine searches"`, `"Scout custom engines"`
+
+The docs are organized into these main sections: Installation, Driver Prerequisites, Configuration, Database/Collection Engines, Indexing, Searching, Custom Engines. Use these section names as search anchors.
+
+## When to Apply
+
+Activate this skill when:
+
+- Installing or configuring Scout
+- Choosing a search engine for a Laravel application
+- Making Eloquent models searchable
+- Customizing indexed data or index names
+- Writing search queries, filters, or pagination
+- Importing or flushing search indexes
+- Troubleshooting search results or indexing issues
+- Choosing between search engines
+
+## Installation
+
+Before installing, check if Scout is already in the project — look for `laravel/scout` in `composer.json` and `config/scout.php`. If already installed, skip to the relevant section (engine configuration, model setup, or searching).
+
+### 1. Install Scout
+
+```bash
+composer require laravel/scout
+php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"
+```
+
+### 2. Add the Searchable trait
+
+```php
+use Illuminate\Database\Eloquent\Model;
+use Laravel\Scout\Searchable;
+
+class Post extends Model
+{
+    use Searchable;
+}
+```
+
+This registers a model observer that automatically keeps your search index in sync with Eloquent records.
+
+## Choosing an Engine
+
+Before presenting engine options, check if Scout is already configured in the application:
+
+1. Check `.env` for `SCOUT_DRIVER` — if set, the application already has a configured engine.
+2. Check `config/scout.php` for the `driver` key and any engine-specific settings.
+3. Check `composer.json` for engine SDKs (`algolia/algoliasearch-client-php`, `meilisearch/meilisearch-php`, `typesense/typesense-php`).
+
+If an engine is already configured, skip the engine selection step and work with the existing setup. Only present the engine comparison if Scout is not yet installed or the user explicitly wants to switch engines.
+
+When no engine is configured, present these options and let the user decide — never choose for them.
+
+| Engine | Type | Best For | Tradeoffs |
+|--------|------|----------|-----------|
+| **Database** | Built-in | Typical applications, simple search | No external deps. MySQL/PostgreSQL only. LIKE + full-text indexes. No typo tolerance. |
+| **Collection** | Built-in | Local dev, tiny datasets (<500 records) | Loads all records into memory. Most portable but least efficient. |
+| **Algolia** | Hosted SaaS | Advanced search without managing infra | Typo tolerance, analytics, faceting. Paid service. No self-hosting. |
+| **Meilisearch** | Self-hosted / Cloud | Teams wanting infrastructure control | Fast, open-source. Self-hostable or cloud. Requires filterable attribute config. |
+| **Typesense** | Self-hosted / Cloud | Keyword, semantic, geo, vector search | Open-source. Self-hostable or cloud. Strict schema requirements. |
+
+After the user chooses, use `search-docs` for that engine's prerequisites and configuration.
+
+Set the engine in `.env`:
+
+```ini
+SCOUT_DRIVER=database
+```
+
+For third-party engines (Algolia, Meilisearch, Typesense): install their PHP SDK and strongly consider enabling queue support in `config/scout.php` for production.
+
+## Model Configuration
+
+Use `search-docs` for full configuration details. Key customization points:
+
+```php
+// Control what data gets indexed
+public function toSearchableArray(): array
+{
+    return [
+        'id' => $this->id,
+        'title' => $this->title,
+        'body' => $this->body,
+    ];
+}
+
+// Custom index name (no effect with database engine)
+public function searchableAs(): string
+{
+    return 'posts_index';
+}
+```
+
+For Algolia/Meilisearch/Typesense: configure index settings (filterable, sortable, searchable attributes) in `config/scout.php`, then sync:
+
+```bash
+php artisan scout:sync-index-settings
+```
+
+## Searching
+
+Basic patterns:
+
+```php
+// Simple search
+$results = Model::search('query')->get();
+
+// With filtering
+$results = Model::search('query')->where('status', 'active')->get();
+
+// Paginated
+$results = Model::search('query')->paginate(15);
+
+// Eager load relationships on results
+$results = Model::search('query')
+    ->query(fn ($q) => $q->with('category'))
+    ->get();
+
+// Raw engine results
+$results = Model::search('query')->raw();
+```
+
+Use `search-docs` for advanced querying — `whereIn`, `whereNotIn`, soft deletes, custom indexes, and engine-specific options.
+
+## Key Artisan Commands
+
+| Command | Purpose |
+|---------|---------|
+| `php artisan scout:import "App\Models\Post"` | Import model records into search index |
+| `php artisan scout:queue-import "App\Models\Post"` | Import via queued jobs (large datasets) |
+| `php artisan scout:flush "App\Models\Post"` | Remove all model records from search index |
+| `php artisan scout:sync-index-settings` | Sync index settings to the search engine |
+| `php artisan scout:index posts` | Create a search index |
+| `php artisan scout:delete-index posts` | Delete a search index |
+
+## Testing
+
+Scout does **not** have a `Scout::fake()` method. Available approaches:
+
+- **NullEngine** — set `SCOUT_DRIVER=null` to disable all indexing in tests
+- **CollectionEngine** — set `SCOUT_DRIVER=collection` for in-memory search without external services
+- **`Model::withoutSyncingToSearch(fn() => ...)`** — temporarily pause indexing in a callback
+- **`Model::disableSearchSyncing()`** — globally disable syncing in test setUp
+
+Use `search-docs` for detailed testing patterns.
+
+## Common Pitfalls
+
+- **Meilisearch filterable attributes** — you must configure filterable attributes in `config/scout.php` under `meilisearch.index-settings` and run `scout:sync-index-settings` **before** using `where`, `whereIn`, or `whereNotIn`. Without this, filtering silently returns wrong results.
+- **Meilisearch data type casting** — `toSearchableArray()` must return properly cast values: integers as `(int)`, floats as `(float)`. Wrong types cause silent filter failures.
+- **Database engine limitations** — `searchableAs()`, `getScoutKey()`, `getScoutKeyName()`, and `shouldBeSearchable()` have no effect with the database engine. It queries your actual tables directly.
+- **Global scopes break pagination** — search engines are not aware of Eloquent global scopes. Recreate scope constraints using Scout `where` clauses instead.
+- **`query()` is not for filtering** — with third-party engines, the `query()` callback runs after results are already retrieved. Use Scout `where` clauses for filtering; use `query()` only for eager-loading or customizing the Eloquent hydration query.
+- **Missing queue configuration** — third-party engines should always have `scout.queue` enabled in production. Without it, indexing runs synchronously and slows down requests.
+- **Typesense schema requirements** — `id` must be cast as `(string)` and timestamps as Unix integers (`$this->created_at->timestamp`).
+- **`shouldBeSearchable()` bypass** — this method only applies via `save()`, `create()`, queries, or relationships. Calling `searchable()` directly on a model or collection bypasses it entirely.

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

@@ -0,0 +1,198 @@
+# Security Best Practices
+
+## Mass Assignment Protection
+
+Every model must define `$fillable` (whitelist) or `$guarded` (blacklist).
+
+Incorrect:
+```php
+class User extends Model
+{
+    protected $guarded = []; // All fields are mass assignable
+}
+```
+
+Correct:
+```php
+class User extends Model
+{
+    protected $fillable = [
+        'name',
+        'email',
+        'password',
+    ];
+}
+```
+
+Never use `$guarded = []` on models that accept user input.
+
+## Authorize Every Action
+
+Use policies or gates in controllers. Never skip authorization.
+
+Incorrect:
+```php
+public function update(UpdatePostRequest $request, Post $post)
+{
+    $post->update($request->validated());
+}
+```
+
+Correct:
+```php
+public function update(UpdatePostRequest $request, Post $post)
+{
+    Gate::authorize('update', $post);
+
+    $post->update($request->validated());
+}
+```
+
+Or via Form Request:
+
+```php
+public function authorize(): bool
+{
+    return $this->user()->can('update', $this->route('post'));
+}
+```
+
+## Prevent SQL Injection
+
+Always use parameter binding. Never interpolate user input into queries.
+
+Incorrect:
+```php
+DB::select("SELECT * FROM users WHERE name = '{$request->name}'");
+```
+
+Correct:
+```php
+User::where('name', $request->name)->get();
+
+// Raw expressions with bindings
+User::whereRaw('LOWER(name) = ?', [strtolower($request->name)])->get();
+```
+
+## Escape Output to Prevent XSS
+
+Use `{{ }}` for HTML escaping. Only use `{!! !!}` for trusted, pre-sanitized content.
+
+Incorrect:
+```blade
+{!! $user->bio !!}
+```
+
+Correct:
+```blade
+{{ $user->bio }}
+```
+
+## CSRF Protection
+
+Include `@csrf` in all POST/PUT/DELETE Blade forms. In Inertia apps, the `@csrf` directive is automatically applied.
+
+Incorrect:
+```blade
+<form method="POST" action="/posts">
+    <input type="text" name="title">
+</form>
+```
+
+Correct:
+```blade
+<form method="POST" action="/posts">
+    @csrf
+    <input type="text" name="title">
+</form>
+```
+
+## Rate Limit Auth and API Routes
+
+Apply `throttle` middleware to authentication and API routes.
+
+```php
+RateLimiter::for('login', function (Request $request) {
+    return Limit::perMinute(5)->by($request->ip());
+});
+
+Route::post('/login', LoginController::class)->middleware('throttle:login');
+```
+
+## Validate File Uploads
+
+Validate extension, MIME type, and size. The `mimes` rule checks extensions; use `mimetypes` for actual MIME type validation. Never trust client-provided filenames.
+
+```php
+public function rules(): array
+{
+    return [
+        'avatar' => ['required', 'image', 'mimes:jpg,jpeg,png,webp', 'max:2048'],
+    ];
+}
+```
+
+Store with generated filenames:
+
+```php
+$path = $request->file('avatar')->store('avatars', 'public');
+```
+
+## Keep Secrets Out of Code
+
+Never commit `.env`. Access secrets via `config()` only.
+
+Incorrect:
+```php
+$key = env('API_KEY');
+```
+
+Correct:
+```php
+// config/services.php
+'api_key' => env('API_KEY'),
+
+// In application code
+$key = config('services.api_key');
+```
+
+## Audit Dependencies
+
+Run `composer audit` periodically to check for known vulnerabilities in dependencies. Automate this in CI to catch issues before deployment.
+
+```bash
+composer audit
+```
+
+## Encrypt Sensitive Database Fields
+
+Use `encrypted` cast for API keys/tokens and mark the attribute as `hidden`.
+
+Incorrect:
+```php
+class Integration extends Model
+{
+    protected function casts(): array
+    {
+        return [
+            'api_key' => 'string',
+        ];
+    }
+}
+```
+
+Correct:
+```php
+class Integration extends Model
+{
+    protected $hidden = ['api_key', 'api_secret'];
+
+    protected function casts(): array
+    {
+        return [
+            'api_key' => 'encrypted',
+            'api_secret' => 'encrypted',
+        ];
+    }
+}
+```