rsc-universal 0.1.1

package/skills/laravel/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: laravel
+description: "Use when building or extending a Laravel 11/12 app - Eloquent models/migrations/relationships, routing + controllers + Form Requests, queues and background jobs, framework-native security (validation, mass-assignment, policies, signed URLs, rate limiting), and Pest/PHPUnit feature tests. Triggers: \"add a queued job with retries\", \"create an Eloquent model and migration\", \"write a Pest feature test\", \"where did app/Http/Kernel.php go\", \"my job runs immediately in tests instead of queueing\", \"configura una cua amb Horizon i Redis\", \"crea una migración con relaciones\", editing bootstrap/app.php / routes/console.php / app/Models. NOT pure PHP language/toolchain work (that is php)."
+tags: [laravel, php, eloquent, queues, pest, artisan]
+recommends: [php, mysql, redis, api-design, secure-coding, testing-web]
+origin: risco
+---
+
+# Laravel (11/12 era)
+
+Build Laravel the way the framework ships **today** — Laravel 12 (released 2025-02-24,
+PHP 8.2–8.4), continuing the slimmed Laravel 11 skeleton. That means **no
+`app/Http/Kernel.php` and no `app/Console/Kernel.php`**: middleware, routing, exception
+handling and providers are all configured in **`bootstrap/app.php`**, and scheduled tasks
+live in **`routes/console.php`**. Generate that structure, not 2019 Laravel.
+
+This skill owns the **framework surface**: Eloquent, routing/controllers, queues, the
+artisan-shaped project, and in-framework Pest tests. The PHP *language and toolchain
+underneath* (types, enums, Composer/PSR-4, PHPStan, Pint) is the
+[../php/SKILL.md](../php/SKILL.md) skill — its boundary line literally reads "NOT
+Eloquent/Blade/Artisan (that is laravel)"; this is the mirror.
+
+## Orient before you scaffold
+
+A wrong version assumption generates dead code. Detect the version and skeleton first.
+
+```bash
+composer show laravel/framework            # exact installed version
+ls bootstrap/app.php                        # present  -> L11/12 slim skeleton
+ls app/Http/Kernel.php 2>/dev/null          # present  -> L10 or older (Kernel era)
+php artisan --version                       # confirms runtime + version
+```
+
+If `bootstrap/app.php` exists and `app/Http/Kernel.php` does **not**, you are on L11/12 —
+use the modern idioms below. Then pick your path:
+
+| Situation | Do |
+|---|---|
+| Greenfield | `laravel new <app>`, then a starter kit: React (React 19 + TS + Inertia 2 + shadcn/ui), Vue (Vue 3 + Inertia 2 + shadcn-vue), or Livewire (Livewire 3 + Volt + Flux UI). Optional WorkOS AuthKit for auth. |
+| Brownfield L11/12 | Follow the repo's existing conventions; do not "reorganize" into folders it dropped. |
+| Pre-11 (Kernel era) | Migrate to `bootstrap/app.php` deliberately; move Kernel middleware to `withMiddleware()`, schedule to `routes/console.php`. Treat as a project, not an inline tweak. |
+
+## The slim structure (where things live now)
+
+```text
+bootstrap/app.php      # withRouting(), withMiddleware(), withExceptions(), withProviders()
+routes/web.php         # web routes (CSRF-protected, session)
+routes/api.php         # api routes (stateless) — present once you opt in
+routes/console.php     # closures + the SCHEDULER (Schedule::command(...)->daily())
+app/Models/            # Eloquent models
+app/Http/Controllers/  # thin controllers
+app/Http/Requests/     # Form Requests (validation + authorization)
+app/Jobs/              # queued jobs
+app/Policies/          # authorization policies
+```
+
+```php
+// Bad: hunting for or editing app/Http/Kernel.php to register middleware (L11/12 deleted it).
+// Good: bootstrap/app.php
+return Application::configure(basePath: dirname(__DIR__))
+    ->withRouting(web: __DIR__.'/../routes/web.php', commands: __DIR__.'/../routes/console.php')
+    ->withMiddleware(function (Middleware $middleware) {
+        $middleware->alias(['subscribed' => EnsureUserIsSubscribed::class]);
+        $middleware->web(append: [TrackLastSeen::class]);
+    })
+    ->withExceptions(function (Exceptions $exceptions) {
+        $exceptions->dontReport(InvalidOrderException::class);
+    })->create();
+```
+
+## Eloquent
+
+**Mass assignment is the #1 Laravel footgun.** A model must declare an allowlist; an open
+blocklist on user input lets a request set any column (`is_admin`, `balance`).
+
+```php
+// Bad: anything in the request body can be written, including columns you never meant to expose.
+class Post extends Model {
+    protected $guarded = [];
+}
+
+// Good: explicit allowlist. Casts give you typed attributes back out of the DB.
+class Post extends Model {
+    protected $fillable = ['title', 'body', 'published_at'];
+
+    protected function casts(): array {
+        return [
+            'published_at' => 'datetime',
+            'status'       => PostStatus::class,   // backed-enum cast
+            'meta'         => 'array',             // json <-> array
+            'api_token'    => 'encrypted',         // at-rest encryption
+        ];
+    }
+
+    public function tags(): BelongsToMany { return $this->belongsToMany(Tag::class); }
+}
+```
+
+**N+1 is the most common Laravel performance bug** — a query per row instead of one. Eager
+load.
+
+```php
+// Bad: 1 query for posts + 1 per post for its author = N+1.
+foreach (Post::all() as $post) { echo $post->author->name; }
+
+// Good: eager load up front -> 2 queries total.
+foreach (Post::with('author')->get() as $post) { echo $post->author->name; }
+```
+
+Migrations define the schema; the `casts()` method (L11+ method form, not the old
+`$casts` array) maps columns to enums/arrays/encrypted values. Relationship deep dives
+(polymorphic, has-many-through, scopes, observers, custom casts, accessors via the
+`Attribute` class) live in [references/eloquent-patterns.md](references/eloquent-patterns.md).
+
+## Routing, controllers, validation
+
+Keep controllers thin: they take a validated request, call a service/model, return a
+response. Push branching logic out of routes — **business logic in `routes/web.php` is
+untestable and unreusable**.
+
+**Form Requests do validation AND authorization in one object** — the `authorize()` gate
+runs before `rules()`, so an unauthorized request never reaches your validation or
+controller.
+
+```php
+// app/Http/Requests/StoreOrderRequest.php
+final class StoreOrderRequest extends FormRequest {
+    public function authorize(): bool {
+        return $this->user()->can('create', Order::class);   // policy check, before rules
+    }
+
+    public function rules(): array {
+        return [
+            'sku'      => ['required', 'string', 'exists:products,sku'],
+            'quantity' => ['required', 'integer', 'min:1', 'max:100'],
+        ];
+    }
+}
+
+// Controller: route-model binding + the Form Request = a tiny method.
+public function store(StoreOrderRequest $request): RedirectResponse {
+    $order = Order::create($request->validated());          // only allow-listed, validated data
+    ProcessOrder::dispatch($order);
+    return to_route('orders.show', $order);
+}
+```
+
+For JSON APIs, shape output with **API Resources** (`JsonResource`). The transport
+*contract* — resource naming, versioning, status-code semantics, pagination shape — is the
+**api-design** skill, not this one; this skill covers implementing it in Laravel.
+
+## Queues & scheduling
+
+A job that implements `ShouldQueue` is pushed to the queue and runs out-of-band instead of
+inline — that is what gets a slow email/payment off the request cycle.
+
+```php
+final class ProcessOrder implements ShouldQueue {
+    use Queueable, Batchable;
+
+    public int $tries = 3;                       // attempts before it lands in failed_jobs
+    public int $timeout = 120;                   // seconds before the worker kills it
+
+    public function backoff(): array { return [10, 60, 300]; }  // exponential-ish retry spacing
+
+    public function __construct(public Order $order) {}
+
+    public function handle(): void {
+        if ($this->batch()?->cancelled()) return; // respect a cancelled batch
+        // ... charge, fulfil ...
+    }
+}
+
+ProcessOrder::dispatch($order);                   // queued (or inline if driver is sync)
+```
+
+Batches let you fan out and react when the group finishes; `allowFailures()` keeps the
+batch going when individual jobs fail.
+
+```php
+Bus::batch([new ProcessOrder($a), new ProcessOrder($b)])
+    ->allowFailures()
+    ->then(fn (Batch $b) => Log::info("done: {$b->totalJobs}"))
+    ->dispatch();
+```
+
+**Driver choice:**
+
+| Need | Use |
+|---|---|
+| Simple, low volume, no extra infra | `database` driver (a `jobs` table) |
+| High throughput + a dashboard (retries, runtime, failures) | **Redis + Horizon** — Horizon manages the workers and gives you the monitor |
+
+Schedule recurring work in `routes/console.php` (the L11/12 home for the scheduler — there
+is no `app/Console/Kernel.php`):
+
+```php
+// routes/console.php
+Schedule::command('orders:reconcile')->dailyAt('02:00');
+Schedule::job(new PruneStaleCarts)->hourly();
+```
+
+Worker deployment, Horizon config, the retry/backoff/timeout matrix, `failed_jobs` +
+`queue:retry`, and supervisor/`queue:work` flags are in
+[references/queues-and-scheduling.md](references/queues-and-scheduling.md).
+
+## Security (framework-native)
+
+| Control | Use | Why |
+|---|---|---|
+| Validation | Form Request `rules()` | reject malformed input at the edge, before the controller |
+| Mass-assignment guard | `$fillable` allowlist (see Eloquent) | stops a request writing columns you never exposed |
+| Authorization | Policies + Gates, `$user->can(...)`, `authorize()` | keeps authz out of controllers and consistent |
+| Tamper-proof links | signed URLs (`URL::signedRoute`, `signed` middleware) | unsubscribe/verify links that can't be forged |
+| Abuse limiting | rate limiting (`throttle` middleware, `RateLimiter::for`) | caps brute-force / scraping per user or IP |
+| Secrets at rest | `Hash::make`/`Hash::check` for passwords, `Crypt` for reversible data | bcrypt/argon2 hashing; never store plaintext |
+
+CSRF protection is automatic on `web` routes; do not disable it. **Read config through
+`config()`, never `env()` outside `config/*.php`** — once configs are cached (`config:cache`
+in prod) `env()` returns `null` everywhere else. Cross-stack OWASP/threat-modeling is the
+**secure-coding** skill; the table above is the framework-native layer this skill owns.
+
+## Testing
+
+Pest is the default runner in new Laravel apps (PHPUnit still fully supported). Use
+`RefreshDatabase` for a clean schema per test and model factories for data.
+
+```php
+uses(RefreshDatabase::class);
+
+it('processes a paid order', function () {
+    $user = User::factory()->create();
+    $this->actingAs($user)
+        ->post('/orders', ['sku' => 'ABC', 'quantity' => 2])
+        ->assertRedirect();
+
+    $this->assertDatabaseHas('orders', ['sku' => 'ABC', 'quantity' => 2]);
+});
+```
+
+**The sync-driver gotcha.** Tests use the `sync` queue driver by default, so a dispatched
+job runs **inline** during the test — it does not sit on a queue. If you assert "the email
+was sent" you are accidentally testing execution. To test that work was *dispatched*, fake
+the queue first:
+
+```php
+it('dispatches order processing', function () {
+    Queue::fake();                               // jobs are now recorded, not run
+    $order = Order::factory()->create();
+
+    ProcessOrder::dispatch($order);
+
+    Queue::assertPushed(ProcessOrder::class);    // assert dispatch, not side effects
+});
+```
+
+`Http::fake()` and `Event::fake()` work the same way for outbound HTTP and events.
+Cross-stack browser/E2E (Playwright/Cypress) strategy is the **testing-web** skill; this
+skill covers in-framework Pest/PHPUnit feature and unit tests.
+
+## Ecosystem (reach for these by name)
+
+Pennant (feature flags / A-B), Pulse (real-time perf: slow queries, job throughput),
+Folio (page-based routing), Horizon (Redis queue dashboard). First-party — prefer them
+over rolling your own.
+
+## Anti-patterns
+
+| Pattern | Why it is bad | Do instead |
+|---|---|---|
+| `protected $guarded = []` on a user-facing model | any request column becomes mass-assignable (`is_admin`, `balance`) | explicit `$fillable` allowlist |
+| Hunting for / re-creating `app/Http/Kernel.php` on L11/12 | the file was deleted; your middleware never registers | configure in `bootstrap/app.php` `withMiddleware()` |
+| Lazy access inside a loop/Blade (`$post->author` per row) | N+1 — one query per row | eager load with `with()` |
+| Fat controllers / logic in `routes/web.php` | untestable, unreusable, no authz boundary | thin controller + Form Request + service/model |
+| Asserting a queued job's *side effects* in a test | sync driver runs it inline — you test execution, not dispatch | `Queue::fake()` + `Queue::assertPushed()` |
+| `env()` outside `config/*.php` | returns `null` once `config:cache` runs in prod | read via `config()`; `env()` only inside config files |
+| `$tries` unset on a flaky job | one transient failure = permanent failure | set `$tries` + `backoff()` |
+| Committing real secrets in `.env` | leaks credentials into history | `.env` is git-ignored; commit `.env.example` only |
+| Old `$casts = [...]` array (deprecated form) | misses the L11+ `casts()` method idioms | the `casts(): array` method |
+
+## Verify
+
+Run [scripts/verify.sh](scripts/verify.sh) from a Laravel project root. It validates
+`composer.json`, checks the framework version, runs Pint (style, read-only `--test`) and
+the test runner (Pest/`artisan test`) if present, and greps for `protected $guarded = []`
+under `app/Models`. It degrades gracefully — prints a skip notice and exits 0 — when there
+is no Laravel project or no `vendor/` dir, so it never blocks a non-Laravel repo.
+
+## References & siblings
+
+- [references/eloquent-patterns.md](references/eloquent-patterns.md) — relationship catalog
+  (polymorphic, has-many-through), eager-load strategies, query/local scopes, observers,
+  attribute casts + custom casts, accessors/mutators via the `Attribute` class.
+- [references/queues-and-scheduling.md](references/queues-and-scheduling.md) — driver
+  selection, Horizon install/config, retry/backoff/timeout matrix, batch chaining,
+  `failed_jobs` + `queue:retry`, worker deployment (supervisor, `queue:work` flags),
+  graceful restarts.
+- PHP language/toolchain underneath Laravel: [../php/SKILL.md](../php/SKILL.md).
+- Cross-stack OWASP/threat-modeling: [../secure-coding/SKILL.md](../secure-coding/SKILL.md).
+- API contract design, MySQL/Redis server tuning, browser E2E strategy: the **api-design**,
+  **mysql** / **redis**, and **testing-web** skills respectively.

package/skills/laravel/evals/README.md

@@ -0,0 +1,10 @@
+# Evals: laravel
+
+`cases.yaml` is read by the skills harness/eval runner, not an automated PHP test suite.
+`should_trigger` and `should_not_trigger` gauge whether the SKILL.md `description` routes
+correctly — a model reading only the frontmatter should fire on the trigger prompts (including
+the non-obvious "where did Kernel.php go" and "my job runs inline in tests" cases and the
+Spanish/Catalan phrasings) and defer the negatives to the named sibling (`php`, `api-design`,
+`secure-coding`, `testing-web`, `mysql`). The single `capability` case gauges body coverage:
+run the scenario and check the response against the `must_include` rubric by hand. Nothing here
+spins up Laravel or runs Pest — that is what `scripts/verify.sh` does against a real project.

package/skills/laravel/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: laravel
+
+should_trigger:
+  - prompt: "Add a queued job to send order confirmation emails with retries and backoff."
+    why: "Core queues — ShouldQueue + $tries/backoff is the center of this skill."
+  - prompt: "Create an Eloquent model and migration for posts with a many-to-many tags relationship."
+    why: "Core Eloquent — models, migrations, belongsToMany are the framework surface this skill owns."
+  - prompt: "Write a Pest feature test for the checkout endpoint with RefreshDatabase."
+    why: "In-framework Pest feature testing — explicitly this skill's testing section."
+  - prompt: "My job runs immediately during tests instead of going to the queue — how do I assert it was dispatched?"
+    why: "Non-obvious: the sync-driver gotcha. No 'Laravel' keyword, but it is exactly Queue::fake/assertPushed territory."
+  - prompt: "Where did app/Http/Kernel.php go? I can't find it to register my middleware."
+    why: "Non-obvious orientation trigger — the L11/12 slim skeleton moved middleware to bootstrap/app.php."
+  - prompt: "Configura una cua amb Horizon i Redis per processar pagaments."
+    why: "Catalan phrasing for Redis+Horizon queue setup — queues are this skill's core."
+  - prompt: "Crea una migración con relaciones para una tabla de pedidos."
+    why: "Spanish phrasing for an Eloquent migration with relationships — core Eloquent."
+
+should_not_trigger:
+  - prompt: "Write a strict-typed PHP value object with readonly props and set up PHPStan at max level."
+    route_to: php
+    why: "Language/toolchain work (types, readonly, PHPStan) with no framework surface — the php skill."
+  - prompt: "Design the REST contract: versioning, status codes, and pagination shape for our public API."
+    route_to: api-design
+    why: "Transport-agnostic contract design discipline, not implementing an API in Laravel."
+  - prompt: "Do an OWASP threat-model and security review of our auth flow across the whole stack."
+    route_to: secure-coding
+    why: "Cross-stack appsec discipline; Laravel keeps only framework-native guards."
+  - prompt: "Set up Playwright browser E2E tests for the signup funnel."
+    route_to: testing-web
+    why: "Browser/E2E strategy, not in-framework Pest feature tests."
+  - prompt: "Tune the indexes and slow-query plan for this MySQL database."
+    route_to: mysql
+    why: "DB engine schema/index tuning; Laravel covers Eloquent + queue config, not server tuning."
+
+capability:
+  - scenario: "Implement order processing: a ProcessOrder queued job with retries, a StoreOrderRequest Form Request doing validation and authorization, and a Pest feature test that asserts the job was dispatched (not executed). Target Laravel 11/12."
+    must_include:
+      - "a job implementing ShouldQueue with $tries and a backoff (method or property)"
+      - "a Form Request with both authorize() and rules()"
+      - "$fillable allowlist on the model (never protected $guarded = [])"
+      - "Queue::fake() with Queue::assertPushed() to assert dispatch rather than side effects"
+      - "RefreshDatabase in the Pest test"
+      - "L11/12 awareness: config in bootstrap/app.php / schedule in routes/console.php, no app/Http/Kernel.php or app/Console/Kernel.php"
+      - "no pre-11 idioms (no editing Kernel.php, no legacy $casts array where casts() is meant)"

package/skills/laravel/references/eloquent-patterns.md

@@ -0,0 +1,126 @@
+# Eloquent patterns (deep dive)
+
+Offloaded depth from SKILL.md §Eloquent. The non-negotiables (`$fillable` allowlist, eager
+loading to kill N+1) live in the body; this file is the catalog you reach for when a
+relationship, scope, or cast gets non-trivial.
+
+## Relationship catalog
+
+| Relationship | Method | Use when |
+|---|---|---|
+| One-to-one | `hasOne` / `belongsTo` | a user has one profile |
+| One-to-many | `hasMany` / `belongsTo` | a post has many comments |
+| Many-to-many | `belongsToMany` (pivot table) | posts ↔ tags |
+| Has-many-through | `hasManyThrough` | a country's posts via its users |
+| Polymorphic one-to-many | `morphMany` / `morphTo` | comments on posts *and* videos |
+| Polymorphic many-to-many | `morphToMany` / `morphedByMany` | tags on posts *and* videos |
+
+```php
+// Polymorphic: one Comment model attaches to many parent types.
+class Comment extends Model {
+    public function commentable(): MorphTo { return $this->morphTo(); }
+}
+class Post extends Model {
+    public function comments(): MorphMany { return $this->morphMany(Comment::class, 'commentable'); }
+}
+```
+
+Pivot tables: name the table alphabetically (`post_tag`, singular), or set `->using()` for a
+custom pivot model when the pivot carries its own columns/casts. Use `withPivot('role')` and
+`withTimestamps()` to surface extra pivot columns.
+
+## Eager loading strategies
+
+| Strategy | API | When |
+|---|---|---|
+| Eager load | `Model::with('rel')->get()` | you know up front you need the relation |
+| Nested | `with('posts.comments')` | load a relation of a relation in one go |
+| Constrained | `with(['posts' => fn ($q) => $q->where('published', true)])` | only some related rows |
+| Lazy eager | `$collection->load('rel')` | you already have the models and decided you need it |
+| Counts only | `withCount('comments')` | you need `comments_count`, not the rows |
+
+Catch N+1 in dev by enabling strict mode so a lazy load throws instead of silently
+fanning out:
+
+```php
+// AppServiceProvider::boot()
+Model::preventLazyLoading(! app()->isProduction());
+```
+
+## Scopes
+
+```php
+// Global scope: applied to every query for the model (e.g. multi-tenant isolation).
+class Post extends Model {
+    protected static function booted(): void {
+        static::addGlobalScope('published', fn (Builder $q) => $q->where('published', true));
+    }
+
+    // Local scope: opt-in, chainable.
+    public function scopeForUser(Builder $q, User $u): Builder {
+        return $q->where('user_id', $u->id);
+    }
+}
+
+Post::forUser($user)->get();
+Post::withoutGlobalScope('published')->get();   // escape hatch when you need drafts
+```
+
+## Observers & model events
+
+Observers centralize lifecycle hooks (`creating`, `updated`, `deleting`) instead of
+scattering them. Register in a service provider.
+
+```php
+class OrderObserver {
+    public function creating(Order $order): void { $order->reference ??= Str::ulid(); }
+    public function deleting(Order $order): void { $order->lineItems()->delete(); }
+}
+// AppServiceProvider::boot(): Order::observe(OrderObserver::class);
+```
+
+Keep observers thin and synchronous-cheap. Heavy work (emails, external calls) belongs in a
+queued job dispatched from the observer, not in the hook itself.
+
+## Casts
+
+| Cast | Maps | Note |
+|---|---|---|
+| `'datetime'` | column ↔ `Carbon` | add a format: `'datetime:Y-m-d'` |
+| `EnumName::class` | column ↔ backed enum | invalid DB value throws — keep the column constrained |
+| `'array'` / `'collection'` | json text ↔ array/Collection | the DB column is `json` |
+| `'encrypted'` / `'encrypted:array'` | plaintext ↔ at-rest ciphertext | uses the app key; rotating the key breaks old rows |
+| `'hashed'` | plaintext ↔ bcrypt on set | for password columns |
+| `AsStringable::class` | string ↔ `Stringable` | fluent string ops |
+
+Use the L11+ `casts()` **method**, not the legacy `protected $casts = []` array.
+
+### Custom casts & value objects
+
+```php
+// A custom cast turns a column into a value object both ways.
+class MoneyCast implements CastsAttributes {
+    public function get($model, string $key, $value, array $attrs): Money {
+        return new Money((int) $value);   // cents -> value object
+    }
+    public function set($model, string $key, $value, array $attrs): array {
+        return [$key => $value instanceof Money ? $value->cents() : $value];
+    }
+}
+// casts(): ['price' => MoneyCast::class]
+```
+
+## Accessors & mutators (the Attribute class)
+
+The modern form is one `Attribute`-returning method, not the old `getXAttribute`/`setXAttribute` pair:
+
+```php
+protected function fullName(): Attribute {
+    return Attribute::make(
+        get: fn ($value, array $attrs) => "{$attrs['first_name']} {$attrs['last_name']}",
+    )->shouldCache();   // cache a computed accessor that is hit repeatedly
+}
+```
+
+A `set` closure on the same `Attribute` handles the write side. Prefer this over the legacy
+magic-method accessors — it is the form current Laravel generates and documents.

package/skills/laravel/references/queues-and-scheduling.md

@@ -0,0 +1,153 @@
+# Queues & scheduling (deep dive)
+
+Offloaded depth from SKILL.md §Queues & scheduling. The body covers `ShouldQueue`, `$tries`,
+`backoff()`, batches with `allowFailures()`, and the database-vs-Redis driver decision. This
+file covers the operational layer: Horizon, the failure pipeline, and worker deployment.
+
+## Driver selection (expanded)
+
+| Driver | Infra | Choose when |
+|---|---|---|
+| `sync` | none (runs inline) | local debugging only; **the default in tests** — jobs run inline |
+| `database` | a `jobs` + `job_batches` + `failed_jobs` table | low/medium volume, no Redis, simplest ops |
+| `redis` | Redis | high throughput, low latency; pair with Horizon |
+| `sqs` / others | cloud | you already run on that provider's queue |
+
+Create the tables for the database driver:
+
+```bash
+php artisan make:queue-table
+php artisan make:queue-batches-table
+php artisan migrate
+```
+
+## Horizon (Redis only)
+
+Horizon is the first-party dashboard + supervisor for Redis queues — throughput, runtime,
+retries, failed jobs, and tag-based metrics, configured in code (not a separate UI to wire).
+
+```bash
+composer require laravel/horizon
+php artisan horizon:install
+php artisan horizon            # runs the supervised workers (instead of queue:work)
+```
+
+```php
+// config/horizon.php — environment-specific worker pools.
+'environments' => [
+    'production' => [
+        'supervisor-1' => [
+            'connection' => 'redis',
+            'queue'      => ['high', 'default'],
+            'balance'    => 'auto',     // scale processes to load
+            'maxProcesses' => 10,
+            'tries'      => 3,
+            'timeout'    => 120,
+        ],
+    ],
+],
+```
+
+In production run `php artisan horizon` under a process supervisor (below). Deploys call
+`php artisan horizon:terminate` so workers gracefully finish the current job and restart on
+the new code.
+
+## Retry / backoff / timeout matrix
+
+| Knob | Where | Meaning |
+|---|---|---|
+| `$tries` | job property | max attempts before the job is marked failed |
+| `$maxExceptions` | job property | fail after N exceptions even if `$tries` not hit |
+| `backoff()` | job method (array) | seconds to wait between attempts (`[10, 60, 300]`) |
+| `$timeout` | job property | seconds the worker allows before killing the job |
+| `retryUntil()` | job method | a `DateTime` after which it stops retrying (overrides `$tries`) |
+| `$backoff` on worker | `queue:work --backoff=` | default wait when a job has no own backoff |
+
+Set `$timeout` **less** than the queue connection's `retry_after` (config/queue.php) — if a
+job runs longer than `retry_after`, the queue releases it to a second worker and you get
+duplicate processing.
+
+## The failure pipeline
+
+A job that exhausts `$tries` lands in `failed_jobs`. Inspect and replay:
+
+```bash
+php artisan queue:failed              # list failed jobs with their UUIDs
+php artisan queue:retry <uuid>        # requeue one
+php artisan queue:retry all           # requeue everything
+php artisan queue:forget <uuid>       # drop one
+php artisan queue:flush               # clear the failed table
+```
+
+Add a `failed()` method to the job for compensating actions (notify, refund, mark record):
+
+```php
+public function failed(\Throwable $e): void {
+    $this->order->update(['status' => 'failed']);
+    Notification::route('slack', config('alerts.ops'))->notify(new JobFailed($e));
+}
+```
+
+For batches, `catch()` fires on the first failed job and `finally()` always runs:
+
+```php
+Bus::batch($jobs)
+    ->allowFailures()
+    ->catch(fn (Batch $b, \Throwable $e) => Log::error('batch member failed', ['e' => $e]))
+    ->finally(fn (Batch $b) => Log::info("batch {$b->id} done, failures: {$b->failedJobs}"))
+    ->dispatch();
+```
+
+## Worker deployment
+
+Run workers as a long-lived supervised process — **never** `queue:work` in a bare shell in
+prod (it dies with the SSH session and won't restart).
+
+```ini
+; /etc/supervisor/conf.d/laravel-worker.conf
+[program:laravel-worker]
+process_name=%(program_name)s_%(process_num)02d
+command=php /var/www/app/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
+autostart=true
+autorestart=true
+numprocs=4
+stopwaitsecs=3600   ; let in-flight jobs finish on stop (must exceed longest job)
+```
+
+Useful `queue:work` flags:
+
+| Flag | Effect |
+|---|---|
+| `--max-time=3600` | exit after an hour so a fresh worker reclaims leaked memory |
+| `--max-jobs=1000` | exit after N jobs (same memory hygiene) |
+| `--tries=3` | default attempts (job's own `$tries` wins) |
+| `--queue=high,default` | priority order — drain `high` first |
+| `--once` | process a single job then exit (handy in tests/scripts) |
+
+## Graceful restarts on deploy
+
+```bash
+php artisan queue:restart       # signals workers to finish the current job then exit
+# (supervisor / horizon:terminate then restarts them on the new code)
+```
+
+Workers hold the **old** code in memory until restarted — forget `queue:restart` in your
+deploy script and you ship a bug fix that never reaches the queue.
+
+## Scheduling
+
+The scheduler lives in `routes/console.php` (L11/12 — no `app/Console/Kernel.php`). One
+system cron entry drives it:
+
+```cron
+* * * * * cd /var/www/app && php artisan schedule:run >> /dev/null 2>&1
+```
+
+```php
+// routes/console.php
+Schedule::command('orders:reconcile')->dailyAt('02:00')->onOneServer()->withoutOverlapping();
+Schedule::job(new PruneStaleCarts)->hourly();
+```
+
+`->onOneServer()` (needs a shared cache lock) stops a multi-server fleet running the same
+task N times; `->withoutOverlapping()` skips a run if the previous one is still going.