@mohammadhprp/system-prompt 0.12.1 → 0.12.3

package/framework/skills/jira-cli/references/troubleshooting.md

@@ -0,0 +1,114 @@
+# Jira CLI Troubleshooting
+
+Common `jira` CLI error scenarios and solutions.
+
+## Table of Contents
+
+- [Command not found](#command-not-found)
+- [Authentication errors (401/403)](#authentication-errors-401403)
+- [Configuration problems](#configuration-problems)
+- [Command hangs in scripts](#command-hangs-in-scripts)
+- [Transition errors](#transition-errors)
+- [Empty or wrong issue lists](#empty-or-wrong-issue-lists)
+- [Epic or issue creation fails on-premises](#epic-or-issue-creation-fails-on-premises)
+- [Custom fields not applied](#custom-fields-not-applied)
+- [Multiple Jira instances or projects](#multiple-jira-instances-or-projects)
+- [View command pager issues](#view-command-pager-issues)
+
+## Command not found
+
+**Symptom:** `command not found: jira`
+
+**Fix:**
+1. Install jira-cli: download a binary from the [releases page](https://github.com/ankitpokhrel/jira-cli/releases), or use Homebrew (`brew install ankitpokhrel/jira-cli/jira-cli`)
+2. Verify: `jira --version`
+
+## Authentication errors (401/403)
+
+**Symptom:** API errors like `GET .../myself: 401 Unauthorized` or 403 on every command.
+
+**Fix:**
+1. Verify the token is exported: `echo "${JIRA_API_TOKEN:?not set}"`
+2. Jira Cloud: use an API token from https://id.atlassian.com/manage-profile/security/api-tokens (your email is the login; basic auth is the default)
+3. On-premises with a Personal Access Token: set `JIRA_AUTH_TYPE=bearer`
+4. On-premises with login credentials: export the password as `JIRA_API_TOKEN` (basic auth, the default)
+5. Re-check with `jira me`
+6. Tokens can also be supplied via `.netrc` or `keychain` instead of the environment variable
+
+## Configuration problems
+
+**Symptom:** `Please select installation type`, or prompts for server/project on every command.
+
+**Fix:**
+1. Run `jira init` and complete the wizard (installation type Cloud/Local, auth type, login, project, board)
+2. To start over, re-run `jira init` and answer the regeneration prompt
+3. Confirm the config path with `jira --help`; override it per command with `-c /path/to/config.yaml` or `JIRA_CONFIG_FILE`
+
+## Command hangs in scripts
+
+**Symptom:** `jira issue list` (and other list commands) never returns in CI or non-interactive shells.
+
+**Cause:** list and create commands open an interactive TUI by default.
+
+**Fix:**
+1. Add `--plain` (or `--table`, `--raw`, `--csv`) to list commands
+2. Add `--no-input` and all required flags to create/edit/move/assign commands
+3. Pipe bodies via stdin instead of letting them prompt: `echo "Body" | jira issue create -s"Summary" -tTask --no-input`
+
+## Transition errors
+
+**Symptom:** `jira issue move ISSUE-1 "Done"` fails or reports an unknown transition.
+
+**Fix:**
+1. Status names are case-sensitive and must match the workflow exactly (e.g. `"In Progress"`, not `in progress`)
+2. Run `jira issue move` with no arguments to list valid transitions for the issue
+3. If a workflow field (comment, resolution, assignee) is rejected during a move, the Jira workflow does not allow it on that transition — drop the flag or ask an admin to enable it
+
+## Empty or wrong issue lists
+
+**Symptom:** `jira issue list` returns nothing, or issues from the wrong project.
+
+**Fix:**
+1. The CLI is scoped to the project/board chosen during `jira init` — re-run `jira init` to change it
+2. Target another project for a single command: `jira issue list -pXYZ --plain`
+3. Reset filters one at a time to isolate the culprit (`-a`, `-s`, `--created`, ...)
+4. Sprint views only show the 25 most recent sprints; older sprints are not listed
+
+## Epic or issue creation fails on-premises
+
+**Symptom:** Creation fails or misbehaves on a non-English Jira Server/Data Center installation.
+
+**Cause:** older Jira APIs do not return untranslated issue type names.
+
+**Fix:** manually fill `epic.name`, `epic.link`, and `issue.types.*.handle` fields in the generated config file.
+
+## Custom fields not applied
+
+**Symptom:** `--custom "key=value"` appears to be ignored or errors.
+
+**Fix:**
+1. Custom fields must be configured in the generated config file to map names to field IDs
+2. See the jira-cli discussion on custom fields for the exact config format
+3. Validate the value type matches the field (text, option, user, ...)
+
+## Multiple Jira instances or projects
+
+**Symptom:** Need to work against two servers or project contexts.
+
+**Fix:**
+1. Generate a config per context with `jira init`
+2. Switch with `jira issue list -c ./other_config.yaml` or `export JIRA_CONFIG_FILE=./other_config.yaml`
+
+## View command pager issues
+
+**Symptom:** `jira issue view` output is truncated or opens an unwanted pager.
+
+**Fix:** `view` uses `less` by default; pipe output (`jira issue view ISSUE-1 | cat`) or configure a custom pager when embedding in scripts.
+
+## mtls authentication issues
+
+**Symptom:** Certificate errors with auth type `mtls`.
+
+**Fix:**
+1. Re-run `jira init`, select installation type `Local`, auth type `mtls`, and provide the CA cert, client key, and client cert
+2. If `JIRA_API_TOKEN` is set, it is used together with `mtls`

package/framework/skills/laravel-best-practices/SKILL.md

@@ -1,229 +1,69 @@
 ---
 name: laravel-best-practices
-description: "Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code."
-version: 0.1.0
+description: "Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns."
+license: MIT
+metadata:
+  author: laravel
 ---
 
 # Laravel Best Practices
 
-Best practices for Laravel, prioritized by impact. Each rule teaches what to do and why. For exact API syntax, verify with `search-docs`.
+Best practices for Laravel, organized as an index of reference files. Each reference file teaches what to do and why. For exact API syntax, verify with `search-docs`.
 
 ## Consistency First
 
-Before applying any rule, check what the application already does. Laravel offers multiple valid approaches — the best choice is the one the codebase already uses, even if another pattern would be theoretically better. Inconsistency is worse than a suboptimal pattern.
+Before applying any reference, check what the application already does. Laravel offers multiple valid approaches, and the best choice is the one the codebase already uses, even if another pattern would be theoretically better. Inconsistency is worse than a suboptimal pattern.
 
-Check sibling files, related controllers, models, or tests for established patterns. If one exists, follow it — don't introduce a second way. These rules are defaults for when no pattern exists yet, not overrides.
-
-## Quick Reference
-
-### 1. Database Performance → `references/db-performance.md`
-
-- Eager load with `with()` to prevent N+1 queries
-- Enable `Model::preventLazyLoading()` in development
-- Select only needed columns, avoid `SELECT *`
-- `chunk()` / `chunkById()` for large datasets
-- Index columns used in `WHERE`, `ORDER BY`, `JOIN`
-- `withCount()` instead of loading relations to count
-- `cursor()` for memory-efficient read-only iteration
-- Never query in Blade templates
-
-### 2. Advanced Query Patterns → `references/advanced-queries.md`
-
-- `addSelect()` subqueries over eager-loading entire has-many for a single value
-- Dynamic relationships via subquery FK + `belongsTo`
-- Conditional aggregates (`CASE WHEN` in `selectRaw`) over multiple count queries
-- `setRelation()` to prevent circular N+1 queries
-- `whereIn` + `pluck()` over `whereHas` for better index usage
-- Two simple queries can beat one complex query
-- Compound indexes matching `orderBy` column order
-- Correlated subqueries in `orderBy` for has-many sorting (avoid joins)
-
-### 3. Security → `references/security.md`, `references/passport.md`, `references/spatie-laravel-permission.md`
-
-- Define `$fillable` or `$guarded` on every model, authorize every action via policies or gates
-- No raw SQL with user input — use Eloquent or query builder
-- `{{ }}` for output escaping, `@csrf` on all POST/PUT/DELETE forms, `throttle` on auth and API routes
-- Validate MIME type, extension, and size for file uploads
-- Never commit `.env`, use `config()` for secrets, `encrypted` cast for sensitive DB fields
-
-### 4. Caching → `references/caching.md`
-
-- `Cache::remember()` over manual get/put
-- `Cache::flexible()` for stale-while-revalidate on high-traffic data
-- `Cache::memo()` to avoid redundant cache hits within a request
-- Cache tags to invalidate related groups
-- `Cache::add()` for atomic conditional writes
-- `once()` to memoize per-request or per-object lifetime
-- `Cache::lock()` / `lockForUpdate()` for race conditions
-- Failover cache stores in production
-
-### 5. Eloquent Patterns → `references/eloquent.md`
-
-- Correct relationship types with return type hints
-- Local scopes for reusable query constraints
-- Global scopes sparingly — document their existence
-- Attribute casts in the `casts()` method
-- Cast date columns, use Carbon instances in templates
-- `whereBelongsTo($model)` for cleaner queries
-- Never hardcode table names — use `(new Model)->getTable()` or Eloquent queries
-
-### 6. Validation & Forms → `references/validation.md`
-
-- Form Request classes, not inline validation
-- Array notation `['required', 'email']` for new code; follow existing convention
-- `$request->validated()` only — never `$request->all()`
-- `Rule::when()` for conditional validation
-- `after()` instead of `withValidator()`
-
-### 7. Configuration → `references/config.md`
-
-- `env()` only inside config files
-- `App::environment()` or `app()->isProduction()`
-- Config, lang files, and constants over hardcoded text
-
-### 8. Testing Patterns → `references/testing.md`, `references/pest-testing.md`
-
-- `LazilyRefreshDatabase` over `RefreshDatabase` for speed
-- `assertModelExists()` over raw `assertDatabaseHas()`
-- Factory states and sequences over manual overrides
-- Use fakes (`Event::fake()`, `Exceptions::fake()`, etc.) — but always after factory setup, not before
-- `recycle()` to share relationship instances across factories
-
-### 9. Queue & Job Patterns → `references/queue-jobs.md`
-
-- `retry_after` must exceed job `timeout`; use exponential backoff `[1, 5, 10]`
-- `ShouldBeUnique` to prevent duplicates; `ShouldBeUniqueUntilProcessing` for early lock release
-- Always implement `failed()`; with `retryUntil()`, set `$tries = 0`
-- `RateLimited` middleware for external API calls; `Bus::batch()` for related jobs
-- Horizon for complex multi-queue scenarios
-
-### 10. Routing & Controllers → `references/routing.md`
-
-- Implicit route model binding
-- Scoped bindings for nested resources
-- `Route::resource()` or `apiResource()`
-- Methods under 10 lines — extract to actions/services
-- Type-hint Form Requests for auto-validation
-
-### 11. HTTP Client → `references/http-client.md`
-
-- Explicit `timeout` and `connectTimeout` on every request
-- `retry()` with exponential backoff for external APIs
-- Check response status or use `throw()`
-- `Http::pool()` for concurrent independent requests
-- `Http::fake()` and `preventStrayRequests()` in tests
-
-### 12. Events, Notifications & Mail → `references/events-notifications.md`, `references/mail.md`
-
-- Event discovery over manual registration; `event:cache` in production
-- `ShouldDispatchAfterCommit` / `afterCommit()` inside transactions
-- Queue notifications and mailables with `ShouldQueue`
-- On-demand notifications for non-user recipients
-- `HasLocalePreference` on notifiable models
-- `assertQueued()` not `assertSent()` for queued mailables
-- Markdown mailables for transactional emails
-
-### 13. Error Handling → `references/error-handling.md`
-
-- `report()`/`render()` on exception classes or in `bootstrap/app.php` — follow existing pattern
-- `ShouldntReport` for exceptions that should never log
-- Throttle high-volume exceptions to protect log sinks
-- `dontReportDuplicates()` for multi-catch scenarios
-- Force JSON rendering for API routes
-- Structured context via `context()` on exception classes
-
-### 14. Task Scheduling → `references/scheduling.md`
-
-- `withoutOverlapping()` on variable-duration tasks
-- `onOneServer()` on multi-server deployments
-- `runInBackground()` for concurrent long tasks
-- `environments()` to restrict to appropriate environments
-- `takeUntilTimeout()` for time-bounded processing
-- Schedule groups for shared configuration
-
-### 15. Architecture → `references/architecture.md`
-
-- Single-purpose Action classes; dependency injection over `app()` helper
-- Prefer official Laravel packages and follow conventions, don't override defaults
-- Default to `ORDER BY id DESC` or `created_at DESC`; `mb_*` for UTF-8 safety
-- `defer()` for post-response work; `Context` for request-scoped data; `Concurrency::run()` for parallel execution
-
-### 16. Migrations → `references/migrations.md`
-
-- Generate migrations with `php artisan make:migration`
-- `constrained()` for foreign keys
-- Never modify migrations that have run in production
-- Add indexes in the migration, not as an afterthought
-- Mirror column defaults in model `$attributes`
-- Reversible `down()` by default; forward-fix migrations for intentionally irreversible changes
-- One concern per migration — never mix DDL and DML
-
-### 17. Collections → `references/collections.md`
-
-- Higher-order messages for simple collection operations
-- `cursor()` vs. `lazy()` — choose based on relationship needs
-- `lazyById()` when updating records while iterating
-- `toQuery()` for bulk operations on collections
-
-### 18. Blade & Views → `references/blade-views.md`, `references/tailwindcss.md`
-
-- `$attributes->merge()` in component templates
-- Blade components over `@include`; `@pushOnce` for per-component scripts
-- View Composers for shared view data
-- `@aware` for deeply nested component props
-
-### 19. Conventions & Style → `references/style.md`
-
-- Follow Laravel naming conventions for all entities
-- Prefer Laravel helpers (`Str`, `Arr`, `Number`, `Uri`, `Str::of()`, `$request->string()`) over raw PHP functions
-- No JS/CSS in Blade, no HTML in PHP classes
-- Code should be readable; comments only for config files
-
-### 20. Feature Flags → `references/pennant.md`
-
-- `Feature::define()` to define features with resolver callbacks
-- `Feature::active()` / `@feature` Blade directive to check features
-- Scope features to specific users/entities with `Feature::for()`
-- `Feature::activate()` / `deactivate()` for runtime control
-
-### 21. Monitoring → `references/pulse.md`
-
-- Gate-protect the dashboard with `viewPulse` gate
-- Configure built-in recorders in `config/pulse.php` (SlowQueries, SlowRequests, Exceptions, Queues, etc.)
-- Redis ingest for production performance; run `pulse:work` to drain the stream
-- Custom cards via Livewire components extending `Pulse\Card`
-- `Pulse::filter()` to exclude entries; `Pulse::resolveAuthenticatedUserId()` for multi-model apps
-- `pulse:check` daemon required for Servers card
-
-### 22. Full-Text Search → `references/scout.md`
-
-- Add `Searchable` trait to models for automatic index sync
-- Choose engine: Database, Collection, Algolia, Meilisearch, Typesense
-- `toSearchableArray()` to control indexed data; `searchableAs()` for custom index names
-- `Model::search('query')->where(...)->paginate()` for search queries
-- `scout:import` / `scout:flush` for index management; `scout:sync-index-settings` for engine config
-- `Model::withoutSyncingToSearch()` / `SCOUT_DRIVER=null` for testing
-
-### 23. Backup → `references/spatie-laravel-backup.md`
-
-- Schedule `backup:run`, `backup:clean`, `backup:monitor` in console kernel
-- Configure sources, destinations, notifications in `config/backup.php`
-- Custom cleanup strategies extending `CleanupStrategy`
-- Custom health checks extending `HealthCheck`
-- Enable encryption and Gzip compression via config
-
-### 24. Media Library → `references/spatie-medialibrary.md`
-
-- Implement `HasMedia` interface + `InteractsWithMedia` trait on models
-- `addMedia()` / `addMediaFromRequest()` for file uploads
-- Media collections to organize related files per model
-- Conversions for image processing (thumbnails, crops, etc.)
-- Responsive images via conversion `withResponsiveImages()`
+Check sibling files, related controllers, models, or tests for established patterns. If one exists, follow it. Don't introduce a second way. These references are defaults for when no pattern exists yet, not overrides.
 
 ## How to Apply
 
-Always use a sub-agent to read rule files and explore this skill's content.
-
-1. Identify the file type and select relevant sections (e.g., migration → §16, controller → §1, §3, §5, §6, §10)
-2. Check sibling files for existing patterns — follow those first per Consistency First
-3. Verify API syntax with `search-docs` for the installed Laravel version
+1. Check the changed files, nearby code, project configuration, and relevant tests for established patterns. Deviate only for a correctness or security defect, and call the deviation out.
+2. Map every affected concern to the reference index below. Read each mapped reference file before editing. Skip unrelated reference files.
+3. Make the smallest coherent change. Keep the application's architecture and naming instead of introducing a second pattern for the same job.
+4. Verify version-sensitive Laravel APIs for the installed version with `search-docs`, or inspect the installed framework when it is unavailable.
+5. Run the narrowest relevant tests first, then the project's formatting and static-analysis checks when the change warrants them.
+6. Re-read the diff against every mapped reference before finishing.
+
+## References Index
+
+Cross-cutting changes often need more than one reference file.
+
+| Concern | Read |
+| --- | --- |
+| Query count, eager loading, indexes, large datasets | [`references/db-performance.md`](references/db-performance.md) |
+| Production monitoring, slow queries, exception dashboards | [`references/pulse.md`](references/pulse.md) |
+| Subqueries, aggregates, complex ordering and query plans | [`references/advanced-queries.md`](references/advanced-queries.md) |
+| Models, relationships, scopes, casts | [`references/eloquent.md`](references/eloquent.md) |
+| Full-text search, indexing, searchable models | [`references/scout.md`](references/scout.md) |
+| Authentication, authorization, input safety, secrets, uploads | [`references/security.md`](references/security.md) |
+| OAuth2 servers, clients, token authentication | [`references/passport.md`](references/passport.md) |
+| Roles and permissions with spatie/laravel-permission | [`references/spatie-laravel-permission.md`](references/spatie-laravel-permission.md) |
+| Model media uploads, conversions, responsive images | [`references/spatie-medialibrary.md`](references/spatie-medialibrary.md) |
+| Form Requests and validation references | [`references/validation.md`](references/validation.md) |
+| Controllers, route binding, resources, middleware | [`references/routing.md`](references/routing.md) |
+| Schema changes, columns, foreign keys, indexes | [`references/migrations.md`](references/migrations.md) |
+| Jobs, retries, uniqueness, batches, Horizon | [`references/queue-jobs.md`](references/queue-jobs.md) |
+| Cache lifetime, invalidation, locks, memoization | [`references/caching.md`](references/caching.md) |
+| Outbound requests, retries, timeouts, fakes | [`references/http-client.md`](references/http-client.md) |
+| Exceptions, reporting, rendering, log context | [`references/error-handling.md`](references/error-handling.md) |
+| Events and notifications | [`references/events-notifications.md`](references/events-notifications.md) |
+| Mailables and mail assertions | [`references/mail.md`](references/mail.md) |
+| Scheduled tasks and overlap protection | [`references/scheduling.md`](references/scheduling.md) |
+| Database backups, cleanup, monitoring, notifications | [`references/spatie-laravel-backup.md`](references/spatie-laravel-backup.md) |
+| Collections, lazy iteration, bulk operations | [`references/collections.md`](references/collections.md) |
+| Blade components, attributes, composers | [`references/blade-views.md`](references/blade-views.md) |
+| Tailwind CSS classes, v4 configuration, extraction | [`references/tailwindcss.md`](references/tailwindcss.md) |
+| Environment values and application configuration | [`references/config.md`](references/config.md) |
+| Feature flags and per-user feature checks | [`references/pennant.md`](references/pennant.md) |
+| Pest/PHPUnit patterns, factories, fakes | [`references/testing.md`](references/testing.md) |
+| Pest 4 syntax, datasets, browser and architecture tests | [`references/pest-testing.md`](references/pest-testing.md) |
+| Naming, helpers, file boundaries, PHP style | [`references/style.md`](references/style.md) |
+| Actions, services, dependencies, application structure | [`references/architecture.md`](references/architecture.md) |
+| Detecting and recording this app's conventions as rules | [`references/infer-conventions.md`](references/infer-conventions.md) |
+
+## Decision rule
+
+- Prefer framework features and existing application abstractions over new helpers or dependencies.
+- Avoid speculative abstractions. Extract code when it creates a clear domain boundary, removes meaningful duplication, or makes behavior independently testable.
+- Keep database access out of Blade views and prevent hidden N+1 queries across controllers, resources, jobs, and serialization.

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

@@ -9,7 +9,7 @@ class CreateOrderAction
 {
     public function __construct(private InventoryService $inventory) {}
 
-    public function execute(array $data): Order
+    public function handle(array $data): Order
     {
         $order = Order::create($data);
         $this->inventory->reserve($order);

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

@@ -0,0 +1,139 @@
+# Detection Checklist
+
+Every dimension here is a genuine fork: Laravel offers two or more valid approaches, the app's choice changes what the next agent writes, and no active project tool can pick for you. Left out on purpose: pure formatting (Pint owns it), any form an installed and enabled Rector rule rewrites to one canonical shape (`$casts` to `casts()`, `$fillable` to attributes, pipe-string rules to arrays, named to anonymous migrations, `$signature` to `#[Signature]`), and framework defaults any agent writes unprompted (`ShouldQueue` jobs, relation return types, `HasFactory`).
+
+Each item gives the fork, then a hint (a grep or dir to spot which side the app takes). Hints are only a start. Read the matched files, never record on a raw count. Apply the ground rules to every verdict: a consistent choice that is a default or a tool's target form is not a pattern. Rows tagged (architecture) are the highest-signal, so record presence and deliberate absence.
+
+---
+
+## A. Validation & HTTP input
+
+1. Validation entry point: inline `$request->validate()` vs Form Request classes vs `Validator::make()`.
+   - Hint: `ls app/Http/Requests`; grep `->validate(` / `Validator::make(` in `app/Http/Controllers`.
+2. Custom rule location: invokable rule objects in `app/Rules` vs inline closures vs `Validator::extend()` in a provider. Rule objects are the default `make:rule` path, so record only if the app leans on closures or `Validator::extend` instead. "No rule objects" alone is just no-signal.
+   - Hint: `ls app/Rules`; grep `Validator::extend` in `app/Providers`.
+3. Typed input retrieval: typed getters (`$request->string()`, `->integer()`, `->enum()`, `->date()`) vs raw `$request->input()` / dynamic properties.
+   - Hint: grep `->string(` / `->integer(` / `->enum(` vs `->input(` in `app/Http`.
+4. Custom messages/attributes: `lang/*/validation.php` vs Form Request `messages()` / `attributes()` methods.
+   - Hint: `ls lang`; grep `function messages`, `function attributes` in `app/Http/Requests`.
+
+## B. Controllers & routing
+
+1. Controller shape: invokable single-action (`__invoke`) vs resource controllers vs plain multi-method.
+   - Hint: grep `__invoke` in controllers; `Route::resource` / `apiResource` vs verb routes.
+2. Business-logic location (architecture): fat controllers vs delegated to Actions / Services / Jobs.
+   - Hint: read a few controller methods; `ls app/Actions app/Services`.
+3. Route handler style: closures in `routes/*.php` vs controller classes.
+   - Hint: count `function ()` vs `::class` in `routes/web.php`, `routes/api.php`.
+4. Middleware assignment: route/group `->middleware()` vs controller `HasMiddleware::middleware()` vs `#[Middleware]` attribute.
+   - Hint: grep `implements HasMiddleware`, `#[Middleware(` in controllers vs `->middleware(` in routes.
+5. Route model binding: implicit (type-hinted models) vs explicit `Route::bind` vs manual `findOrFail`.
+   - Hint: typed model params in signatures vs `findOrFail(` in controllers; grep `Route::bind`.
+6. Rate limiting: named `RateLimiter::for()` + `throttle:name` vs inline `throttle:60,1`.
+   - Hint: grep `RateLimiter::for` in providers vs `throttle:` in route files.
+
+## C. Authorization
+
+1. Authorization home: Gates (`Gate::define`) vs Policy classes in `app/Policies`.
+   - Hint: `ls app/Policies`; grep `Gate::define` in `app/Providers`.
+2. Authorization call site: `$this->authorize()` / `Gate::authorize()` vs `$user->can()` vs `can` middleware vs `#[Authorize]` vs `@can` in Blade.
+   - Hint: grep `authorize(`, `->can(`, `middleware('can:`, `#[Authorize(`, `@can(`.
+
+## D. Eloquent & models
+
+1. Mass assignment: `$fillable` allow-list vs `$guarded` block-list.
+   - Hint: grep `protected $fillable` / `protected $guarded` in `app/Models`.
+2. Accessors/mutators: modern `Attribute` class vs legacy `getXxxAttribute()` / `setXxxAttribute()`. Record a legacy hold, it goes against the tool's grain.
+   - Hint: grep `: Attribute` / `Attribute::make` vs `function get[A-Z].*Attribute` in `app/Models`.
+3. Primary keys: auto-increment vs `HasUuids` vs `HasUlids`.
+   - Hint: grep `HasUuids` / `HasUlids` in `app/Models`; migration `id()` vs `uuid('id')`.
+4. Custom casts: dedicated `CastsAttributes` classes (`app/Casts`) vs inline `Attribute` vs built-in cast strings.
+   - Hint: `ls app/Casts`; grep `Cast::class`, `AsStringable::class` in models.
+5. Data/query layer (architecture): Eloquent directly in controllers vs repositories vs dedicated query objects (e.g. classes exposing `builder(): Builder`).
+   - Hint: `ls app/Repositories app/Queries`; see where non-trivial queries are built.
+6. Query scopes: local `scope`/`#[Scope]` methods vs dedicated builder classes.
+   - Hint: grep `function scope` / `#[Scope]` in models; `ls app/*/Builders`.
+7. Model events: observers (`app/Observers`, `#[ObservedBy]`) vs `booted()` closures vs event classes.
+   - Hint: `ls app/Observers`; grep `booted`, `::observe`, `#[ObservedBy]`.
+8. Eager-load posture: explicit per-query `->with()` vs model-level `$with` defaults. Treat `preventLazyLoading()` separately as a development guard because it can complement either posture.
+   - Hint: grep `protected $with`, `->with(`, and separately `preventLazyLoading` in `app/`.
+
+## E. Architecture & organization
+
+1. Action/Service structure (architecture): Action classes (invoked via `handle` / `execute` / `__invoke`) vs service objects vs neither. Cross-check the Step 0 `app/` map: any `Actions`/`Services`/`Pipelines`/`Jobs`-as-actions folder is this pattern, so record how it is invoked.
+   - Hint: `ls app/` (the whole tree, not just `Actions`/`Services`); grep the invocation method in the folder you find.
+2. DTOs (architecture): spatie/laravel-data vs plain readonly classes vs arrays everywhere.
+   - Hint: `ls app/Data`; grep `extends Data`, `readonly class` in `app/`.
+3. Dependency acquisition: constructor/method injection vs `app()` / `resolve()` / `App::make()` service location.
+   - Hint: grep `app(` / `resolve(` / `::make(` in `app/` vs promoted constructor deps.
+4. Decoupling: events + listeners vs direct service calls.
+   - Hint: `ls app/Events app/Listeners`; grep `event(`, `::dispatch(`.
+5. Helper vs facade idiom: global helpers (`config()`, `auth()`, `response()`) vs facades (`Config::`, `Auth::`, `Response::`).
+   - Hint: ratio of `config(` vs `Config::` (etc.) across `app/`.
+6. Namespace layout (architecture): default `app/` skeleton vs domain/module folders (`app/Domain/**`, modules).
+   - Hint: `ls app/`, look for `Domain/`, `Modules/`, bounded-context folders.
+7. Enums: backed vs pure; case naming; where they live.
+   - Hint: `ls app/Enums`; grep `enum .*: string`, `enum .*: int`.
+
+## F. Frontend & views
+
+This app ships a frontend stack, so the items below apply.
+
+1. Frontend stack: Blade+Livewire vs Inertia (Vue/React/Svelte) vs Blade-only / API + separate SPA.
+   - Hint: `composer.json` + `package.json`; `ls resources/js/pages`, `resources/views`.
+2. Blade composition: class `<x-*>` components vs anonymous components (`@props`) vs `@include` partials.
+   - Hint: `ls app/View/Components`; grep `<x-`, `@include` in `resources/views`.
+3. Livewire component format: Volt functional/class components, native Livewire 4 single-file (SFC), multi-file (MFC), view-based, or class-based components. Evaluate full-page vs nested separately because it is an independent usage choice.
+   - Hint: check the installed Livewire major and `livewire/volt`; inspect `app/Livewire`, `resources/views/livewire`, and Livewire 4 component/page directories for `@volt`, SFC, MFC, view-based, and class-based formats.
+4. Localization: short keys (`lang/*/*.php` + `__('messages.welcome')`) vs JSON string keys (`lang/*.json` + `__('Full sentence')`).
+   - Hint: `ls lang`; grep dotted `__('` vs sentence keys.
+
+## G. Database & migrations
+
+1. Foreign keys: `foreignId()->constrained()` vs `foreignIdFor(Model::class)` vs manual `foreign()->references()->on()`.
+   - Hint: grep `foreignId(`, `foreignIdFor(`, `->foreign(` in `database/migrations`.
+2. `down()` methods: real reverse logic vs omitted / one-way migrations.
+   - Hint: grep `function down` vs the migration count.
+3. Enum storage: DB `enum()` column vs `string()` + PHP-enum cast on the model.
+   - Hint: grep `->enum(` in migrations vs string columns cast to enums.
+4. Transactions: `DB::transaction(fn ...)` closure vs manual `beginTransaction` / `commit` / `rollBack`.
+   - Hint: grep `DB::transaction`, `beginTransaction` in `app/`.
+5. Idempotent writes: `upsert` / `updateOrCreate` / `firstOrCreate` vs find-then-save.
+   - Hint: grep `upsert(`, `updateOrCreate(`, `firstOrCreate(` in `app/`.
+
+## H. Testing
+
+1. Framework: Pest (`it()` / `test()` / `expect()`) vs PHPUnit classes.
+   - Hint: `ls tests/Pest.php`; grep `it(` / `test(` vs `extends TestCase`.
+2. DB reset: `RefreshDatabase` vs `DatabaseTruncation` vs `DatabaseMigrations`.
+   - Hint: grep those trait names in `tests/`.
+3. Fixtures: compare how equivalent test-owned records are created, such as factories vs manual inserts. Track seeders separately for shared reference data because `$this->seed()` commonly and legitimately coexists with factories.
+   - Hint: grep `::factory(` and direct inserts in `tests/`; separately inspect `$this->seed(` calls and what those seeders provide.
+4. Collaborator isolation: how the app doubles its own classes, Mockery `mock()` / `spy()` vs real integration. Ignore facade fakes like `Mail::fake()` here, they isolate framework services by default and are not a fork against Mockery.
+   - Hint: grep `->mock(`, `->spy(`, `Mockery::` in `tests/`.
+5. Endpoint assertions: array `assertJson([...])` / `assertJsonFragment` vs fluent `AssertableJson`.
+   - Hint: grep `AssertableJson`, `assertJsonFragment` in `tests/`.
+
+## I. Responses & API resources
+
+1. Response shape: API Resource classes vs `response()->json()` vs returning models/arrays directly.
+   - Hint: `ls app/Http/Resources`; grep `JsonResource`, `->json(` in controllers.
+2. Resource relationship inclusion: `whenLoaded()` guards vs unconditional relationship access. Do not count ordinary scalar attributes as rivals to conditional relationships, and evaluate general `when()` fields separately.
+   - Hint: compare relationship fields using `whenLoaded(` with unconditional relationship property access in `app/Http/Resources`.
+3. Pagination contracts: within comparable endpoint categories, length-aware `paginate()` vs `simplePaginate()` vs `cursorPaginate()`. These have different totals, navigation, ordering, and performance contracts, so record only a stable path-scoped API policy, never a project-wide majority.
+   - Hint: grep those in `app/`, then group matches by endpoint type and client contract before comparing them.
+4. Web redirects/URLs: `route('name')` vs `url('/path')` vs `action([...])`.
+   - Hint: grep `route('`, `url('/`, `action([` in `app/Http` and views.
+
+## J. Strings, collections & dates
+
+1. Iteration idiom: `collect()->map()->filter()` pipelines vs `array_map` / `foreach`.
+   - Hint: grep `collect(`, `->map(` vs `array_map`, `foreach` density in `app/`.
+2. String API: fluent `Str::of()->...` (Stringable) vs static `Str::` vs native (`trim`, `strtoupper`).
+   - Hint: grep `Str::of(` vs `Str::` vs native string funcs.
+3. Dates: compare equivalent construction call styles (`now()` / `today()` helpers vs `Carbon::`) separately from the application's mutable/immutable date policy. `Date::use(CarbonImmutable::class)` can make helpers return immutable dates, so those signals are complementary rather than conflicting.
+   - Hint: grep `now(` and `Carbon::` for call style; separately inspect `CarbonImmutable` and `Date::use` for mutability policy.
+
+---
+
+Genuine forks only. Every row survived the "no tool can decide this, and it isn't the default" filter. Give each applicable dimension exactly one verdict: pattern, conflict, default, no-signal, tooling-owned, or already-recorded. The rows tagged (architecture) are where the highest-value rules come from.

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

@@ -30,7 +30,8 @@ $articles = Article::whereHas('user', function ($q) {
 
 Correct:
 ```php
-public function scopeActive(Builder $query): Builder
+#[Scope]
+protected function active(Builder $query): Builder
 {
     return $query->where('verified', true)->whereNotNull('activated_at');
 }
@@ -58,7 +59,8 @@ class PublishedScope implements Scope
 
 Correct (local scope you opt into):
 ```php
-public function scopePublished(Builder $query): Builder
+#[Scope]
+protected function published(Builder $query): Builder
 {
     return $query->where('published', true);
 }