@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/kotlin-android/scripts/verify.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# verify.sh — static, SDK-free lint for native Android (Kotlin + Gradle).
+#
+# Greps the target dir for stale/banned Android patterns and missing modern ones.
+# No Android SDK, no Gradle, no network required — runs in CI or a bare checkout.
+#
+#   bash scripts/verify.sh [DIR]   # DIR defaults to the current directory
+#
+# FAIL (exit 1): a banned pattern is present.
+# WARN (exit 0): a modern pattern looks missing — review, don't necessarily block.
+# An empty or clean target exits 0 with "all checks passed".
+#
+# Portable to stock macOS bash 3.2 (no mapfile, no associative arrays).
+set -eu
+
+DIR="${1:-.}"
+
+RED=$'\033[0;31m'
+YELLOW=$'\033[1;33m'
+GREEN=$'\033[0;32m'
+RESET=$'\033[0m'
+
+fails=0
+warns=0
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$1"; fails=$((fails + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$RESET" "$1"; warns=$((warns + 1)); }
+
+if [ ! -d "$DIR" ]; then
+  warn "target '$DIR' is not a directory — nothing to check"
+  exit 0
+fi
+
+# Collect target files. Exclude build output and this skill's own references.
+kt_files=$(find "$DIR" -type f -name '*.kt' \
+  -not -path '*/build/*' -not -path '*/.gradle/*' 2>/dev/null || true)
+gradle_files=$(find "$DIR" -type f -name '*.gradle.kts' \
+  -not -path '*/build/*' 2>/dev/null || true)
+xml_layouts=$(find "$DIR" -type f -path '*/res/layout/*.xml' \
+  -not -path '*/build/*' 2>/dev/null || true)
+
+if [ -z "$kt_files" ] && [ -z "$gradle_files" ] && [ -z "$xml_layouts" ]; then
+  printf '%sno Kotlin/Gradle/layout files under %s — nothing to check.%s\n' "$GREEN" "$DIR" "$RESET"
+  exit 0
+fi
+
+# grep helper: returns 0 (and prints) when PATTERN is found in $kt_files.
+kt_grep() { [ -n "$kt_files" ] && printf '%s\n' "$kt_files" | xargs grep -nE "$1" 2>/dev/null; }
+gradle_grep() { [ -n "$gradle_files" ] && printf '%s\n' "$gradle_files" | xargs grep -nE "$1" 2>/dev/null; }
+
+# ---- FAIL checks: banned patterns -----------------------------------------
+[ -n "$xml_layouts" ] && fail "XML layout files under res/layout — use Jetpack Compose:
+$(printf '%s\n' "$xml_layouts" | sed 's/^/    /')"
+
+hit=$(kt_grep '\bfindViewById\b') && [ -n "$hit" ] && \
+  fail "findViewById (no Compose):"$'\n'"$(printf '%s' "$hit" | sed 's/^/    /')"
+
+hit=$(kt_grep '\bAsyncTask\b') && [ -n "$hit" ] && \
+  fail "AsyncTask (removed API) — use coroutines:"$'\n'"$(printf '%s' "$hit" | sed 's/^/    /')"
+
+hit=$(kt_grep 'GlobalScope\.(launch|async)') && [ -n "$hit" ] && \
+  fail "GlobalScope coroutine (leaks) — use viewModelScope/a scoped CoroutineScope:"$'\n'"$(printf '%s' "$hit" | sed 's/^/    /')"
+
+hit=$(kt_grep 'import +androidx\.lifecycle\.LiveData') && [ -n "$hit" ] && \
+  fail "LiveData import — use StateFlow + collectAsStateWithLifecycle():"$'\n'"$(printf '%s' "$hit" | sed 's/^/    /')"
+
+hit=$(gradle_grep '\bkapt\b') && [ -n "$hit" ] && \
+  fail "kapt in Gradle (legacy/slow) — use KSP for Room/Hilt:"$'\n'"$(printf '%s' "$hit" | sed 's/^/    /')"
+
+# Public mutable state surface: a 'val' exposing MutableStateFlow/mutableStateOf
+# without a 'private' modifier is a leaked source of truth.
+hit=$(kt_grep '^[[:space:]]*(public[[:space:]]+)?val[[:space:]].*(MutableStateFlow|mutableStateOf)\(') \
+  && [ -n "$hit" ] && \
+  fail "public val exposing MutableStateFlow/mutableStateOf — keep mutable private, expose StateFlow via asStateFlow():"$'\n'"$(printf '%s' "$hit" | sed 's/^/    /')"
+
+# ---- WARN checks: missing modern patterns ----------------------------------
+# collectAsState( without the Lifecycle variant in the same set of files.
+if [ -n "$kt_files" ]; then
+  plain=$(printf '%s\n' "$kt_files" | xargs grep -lE 'collectAsState\(' 2>/dev/null || true)
+  lifecycle=$(printf '%s\n' "$kt_files" | xargs grep -lE 'collectAsStateWithLifecycle\(' 2>/dev/null || true)
+  # Files that use collectAsState but never the lifecycle variant.
+  for f in $plain; do
+    case " $lifecycle " in
+      *" $f "*) : ;;
+      *) warn "collectAsState() without collectAsStateWithLifecycle() in: $f" ;;
+    esac
+  done
+fi
+
+hit=$(gradle_grep 'composeOptions[[:space:]]*\{') && [ -n "$hit" ] && \
+  warn "legacy composeOptions block — use the Kotlin Compose plugin (org.jetbrains.kotlin.plugin.compose):"$'\n'"$(printf '%s' "$hit" | sed 's/^/    /')"
+
+if [ -n "$gradle_files" ]; then
+  if ! printf '%s\n' "$gradle_files" | xargs grep -qE 'compose-bom|platform\(.*compose' 2>/dev/null; then
+    warn "no compose-bom platform() pin found in Gradle — pin Compose artifacts via the BOM."
+  fi
+fi
+
+# ---- summary ---------------------------------------------------------------
+printf -- '----\n'
+if [ "$fails" -gt 0 ]; then
+  printf '%s%d failure(s)%s, %d warning(s).\n' "$RED" "$fails" "$RESET" "$warns"
+  exit 1
+fi
+if [ "$warns" -gt 0 ]; then
+  printf '%s%d warning(s)%s, no failures.%s\n' "$YELLOW" "$warns" "$RESET" "$RESET"
+  exit 0
+fi
+printf '%sall checks passed.%s\n' "$GREEN" "$RESET"
+exit 0

package/skills/shared/laravel/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: laravel
+description: "Use when building or extending a Laravel 11/12 app — Eloquent models, migrations and relationships, routing with controllers and Form Requests, queues and background jobs, framework-native security (validation, mass-assignment, policies, signed URLs, rate limiting), and Pest/PHPUnit feature tests. NOT pure PHP language or toolchain work (that is `php`)."
+tags: [laravel, php, eloquent, queues, pest, artisan]
+recommends: [php, mysql, redis, api-design, secure-coding, testing-web]
+origin: ai-hub
+---
+
+# 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/shared/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/shared/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/shared/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.