AGENTS.md

1<laravel-boost-guidelines>
2=== foundation rules ===
3 
4# Laravel Boost Guidelines
5 
6The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to enhance the user's satisfaction building Laravel applications.
7 
8## Foundational Context
9This application is a Laravel application and its main Laravel ecosystems package & versions are below. You are an expert with them all. Ensure you abide by these specific packages & versions.
10 
11- php - 8.4.20
12- laravel/framework (LARAVEL) - v12
13- laravel/nightwatch (NIGHTWATCH) - v1
14- laravel/prompts (PROMPTS) - v0
15- laravel/sanctum (SANCTUM) - v4
16- laravel/scout (SCOUT) - v10
17- laravel/socialite (SOCIALITE) - v5
18- larastan/larastan (LARASTAN) - v3
19- laravel/mcp (MCP) - v0
20- phpunit/phpunit (PHPUNIT) - v11
21- vue (VUE) - v3
22- laravel-echo (ECHO) - v2
23- tailwindcss (TAILWINDCSS) - v4
24 
25## Conventions
26- You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming.
27- Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`.
28- Check for existing components to reuse before writing a new one.
29 
30## Verification Scripts
31- Do not create verification scripts or tinker when tests cover that functionality and prove it works. Unit and feature tests are more important.
32 
33## Application Structure & Architecture
34- Stick to existing directory structure; don't create new base folders without approval.
35- Do not change the application's dependencies without approval.
36 
37## Frontend Bundling
38- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `pnpm run build`, `pnpm run dev`, or `composer run dev`. Ask them.
39 
40## Replies
41- Be concise in your explanations - focus on what's important rather than explaining obvious details.
42 
43## Documentation Files
44- You must only create documentation files if explicitly requested by the user.
45 
46=== boost rules ===
47 
48## Laravel Boost
49- Laravel Boost is an MCP server that comes with powerful tools designed specifically for this application. Use them.
50 
51## Artisan
52- Use the `list-artisan-commands` tool when you need to call an Artisan command to double-check the available parameters.
53 
54## URLs
55- Whenever you share a project URL with the user, you should use the `get-absolute-url` tool to ensure you're using the correct scheme, domain/IP, and port.
56 
57## Tinker / Debugging
58- You should use the `tinker` tool when you need to execute PHP to debug code or query Eloquent models directly.
59- Use the `database-query` tool when you only need to read from the database.
60 
61## Reading Browser Logs With the `browser-logs` Tool
62- You can read browser logs, errors, and exceptions using the `browser-logs` tool from Boost.
63- Only recent browser logs will be useful - ignore old logs.
64 
65## Searching Documentation (Critically Important)
66- Boost comes with a powerful `search-docs` tool you should use before any other approaches when dealing with Laravel or Laravel ecosystem packages. This tool automatically passes a list of installed packages and their versions to the remote Boost API, so it returns only version-specific documentation for the user's circumstance. You should pass an array of packages to filter on if you know you need docs for particular packages.
67- The `search-docs` tool is perfect for all Laravel-related packages, including Laravel, Inertia, Livewire, Filament, Tailwind, Pest, Nova, Nightwatch, etc.
68- You must use this tool to search for Laravel ecosystem documentation before falling back to other approaches.
69- Search the documentation before making code changes to ensure we are taking the correct approach.
70- Use multiple, broad, simple, topic-based queries to start. For example: `['rate limiting', 'routing rate limiting', 'routing']`.
71- Do not add package names to queries; package information is already shared. For example, use `test resource table`, not `filament 4 test resource table`.
72 
73### Available Search Syntax
74- You can and should pass multiple queries at once. The most relevant results will be returned first.
75 
761. Simple Word Searches with auto-stemming - query=authentication - finds 'authenticate' and 'auth'.
772. Multiple Words (AND Logic) - query=rate limit - finds knowledge containing both "rate" AND "limit".
783. Quoted Phrases (Exact Position) - query="infinite scroll" - words must be adjacent and in that order.
794. Mixed Queries - query=middleware "rate limit" - "middleware" AND exact phrase "rate limit".
805. Multiple Queries - queries=["authentication", "middleware"] - ANY of these terms.
81 
82=== php rules ===
83 
84## PHP
85 
86- Always use curly braces for control structures, even if it has one line.
87 
88### Constructors
89- Use PHP 8 constructor property promotion in `__construct()`.
90    - <code-snippet>public function __construct(public GitHub $github) { }</code-snippet>
91- Do not allow empty `__construct()` methods with zero parameters unless the constructor is private.
92 
93### Type Declarations
94- Always use explicit return type declarations for methods and functions.
95- Use appropriate PHP type hints for method parameters.
96 
97<code-snippet name="Explicit Return Types and Method Params" lang="php">
98protected function isAccessible(User $user, ?string $path = null): bool
99{
100    ...
101}
102</code-snippet>
103 
104## Comments
105- Prefer PHPDoc blocks over inline comments. Never use comments within the code itself unless there is something very complex going on.
106 
107## PHPDoc Blocks
108- Add useful array shape type definitions for arrays when appropriate.
109 
110## Enums
111- Typically, keys in an Enum should be TitleCase. For example: `FavoritePerson`, `BestLake`, `Monthly`.
112 
113=== tests rules ===
114 
115## Test Enforcement
116 
117- Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass.
118- Run the minimum number of tests needed to ensure code quality and speed. Use `php artisan test --compact` with a specific filename or filter.
119 
120=== laravel/core rules ===
121 
122## Do Things the Laravel Way
123 
124- Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool.
125- If you're creating a generic PHP class, use `php artisan make:class`.
126- Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior.
127 
128### Database
129- Always use proper Eloquent relationship methods with return type hints. Prefer relationship methods over raw queries or manual joins.
130- Use Eloquent models and relationships before suggesting raw database queries.
131- Avoid `DB::`; prefer `Model::query()`. Generate code that leverages Laravel's ORM capabilities rather than bypassing them.
132- Generate code that prevents N+1 query problems by using eager loading.
133- Use Laravel's query builder for very complex database operations.
134 
135### Model Creation
136- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `php artisan make:model`.
137 
138### APIs & Eloquent Resources
139- For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention.
140 
141### Controllers & Validation
142- Always create Form Request classes for validation rather than inline validation in controllers. Include both validation rules and custom error messages.
143- Check sibling Form Requests to see if the application uses array or string based validation rules.
144 
145### Queues
146- Use queued jobs for time-consuming operations with the `ShouldQueue` interface.
147 
148### Authentication & Authorization
149- Use Laravel's built-in authentication and authorization features (gates, policies, Sanctum, etc.).
150 
151### URL Generation
152- When generating links to other pages, prefer named routes and the `route()` function.
153 
154### Configuration
155- Use environment variables only in configuration files - never use the `env()` function directly outside of config files. Always use `config('app.name')`, not `env('APP_NAME')`.
156 
157### Testing
158- When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model.
159- Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`.
160- When creating tests, make use of `php artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests.
161 
162### Vite Error
163- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `pnpm run build` or ask the user to run `pnpm run dev` or `composer run dev`.
164 
165=== laravel/v12 rules ===
166 
167## Laravel 12
168 
169- Use the `search-docs` tool to get version-specific documentation.
170- Since Laravel 11, Laravel has a new streamlined file structure which this project uses.
171 
172### Laravel 12 Structure
173- In Laravel 12, middleware are no longer registered in `app/Http/Kernel.php`.
174- Middleware are configured declaratively in `bootstrap/app.php` using `Application::configure()->withMiddleware()`.
175- `bootstrap/app.php` is the file to register middleware, exceptions, and routing files.
176- `bootstrap/providers.php` contains application specific service providers.
177- The `app\Console\Kernel.php` file no longer exists; use `bootstrap/app.php` or `routes/console.php` for console configuration.
178- Console commands in `app/Console/Commands/` are automatically available and do not require manual registration.
179 
180### Database
181- When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost.
182- Laravel 12 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`.
183 
184### Models
185- Casts can and likely should be set in a `casts()` method on a model rather than the `$casts` property. Follow existing conventions from other models.
186 
187=== phpunit/core rules ===
188 
189## PHPUnit
190 
191- This application uses PHPUnit for testing. All tests must be written as PHPUnit classes. Use `php artisan make:test --phpunit {name}` to create a new test.
192- If you see a test using "Pest", convert it to PHPUnit.
193- Every time a test has been updated, run that singular test.
194- When the tests relating to your feature are passing, ask the user if they would like to also run the entire test suite to make sure everything is still passing.
195- Tests should test all of the happy paths, failure paths, and weird paths.
196- You must not remove any tests or test files from the tests directory without approval. These are not temporary or helper files; these are core to the application.
197 
198### Running Tests
199- Run the minimal number of tests, using an appropriate filter, before finalizing.
200- To run all tests: `php artisan test --compact`.
201- To run all tests in a file: `php artisan test --compact tests/Feature/ExampleTest.php`.
202- To filter on a particular test name: `php artisan test --compact --filter=testName` (recommended after making a change to a related file).
203 
204=== tailwindcss/core rules ===
205 
206## Tailwind CSS
207 
208- Use Tailwind CSS classes to style HTML; check and use existing Tailwind conventions within the project before writing your own.
209- Offer to extract repeated patterns into components that match the project's conventions (i.e. Blade, JSX, Vue, etc.).
210- Think through class placement, order, priority, and defaults. Remove redundant classes, add classes to parent or child carefully to limit repetition, and group elements logically.
211- You can use the `search-docs` tool to get exact examples from the official documentation when needed.
212 
213### Spacing
214- When listing items, use gap utilities for spacing; don't use margins.
215 
216<code-snippet name="Valid Flex Gap Spacing Example" lang="html">
217    <div class="flex gap-8">
218        <div>Superior</div>
219        <div>Michigan</div>
220        <div>Erie</div>
221    </div>
222</code-snippet>
223 
224### Dark Mode
225- If existing pages and components support dark mode, new pages and components must support dark mode in a similar way, typically using `dark:`.
226 
227=== tailwindcss/v4 rules ===
228 
229## Tailwind CSS 4
230 
231- Always use Tailwind CSS v4; do not use the deprecated utilities.
232- `corePlugins` is not supported in Tailwind v4.
233- In Tailwind v4, configuration is CSS-first using the `@theme` directive — no separate `tailwind.config.js` file is needed.
234 
235<code-snippet name="Extending Theme in CSS" lang="css">
236@theme {
237  --color-brand: oklch(0.72 0.11 178);
238}
239</code-snippet>
240 
241- In Tailwind v4, you import Tailwind using a regular CSS `@import` statement, not using the `@tailwind` directives used in v3:
242 
243<code-snippet name="Tailwind v4 Import Tailwind Diff" lang="diff">
244   - @tailwind base;
245   - @tailwind components;
246   - @tailwind utilities;
247   + @import "tailwindcss";
248</code-snippet>
249 
250### Replaced Utilities
251- Tailwind v4 removed deprecated utilities. Do not use the deprecated option; use the replacement.
252- Opacity values are still numeric.
253 
254| Deprecated |	Replacement |
255|------------+--------------|
256| bg-opacity-* | bg-black/* |
257| text-opacity-* | text-black/* |
258| border-opacity-* | border-black/* |
259| divide-opacity-* | divide-black/* |
260| ring-opacity-* | ring-black/* |
261| placeholder-opacity-* | placeholder-black/* |
262| flex-shrink-* | shrink-* |
263| flex-grow-* | grow-* |
264| overflow-ellipsis | text-ellipsis |
265| decoration-slice | box-decoration-slice |
266| decoration-clone | box-decoration-clone |
267</laravel-boost-guidelines>
268 
269## Architecture
270- Koel loads data progressively — there is no method to fetch all songs at once. Songs are loaded lazily per screen/context. This is by design for large libraries. Never assume the playable store vault contains all songs.
271 
272## Code Organization
273- Traits must be placed in a `Concerns` subfolder (namespace) relative to their consumers (e.g. `App\Ai\Tools\Concerns\PlaysMusic`).
274- Interfaces must be placed in a `Contracts` subfolder (namespace) relative to their consumers (e.g. `App\Ai\Tools\Contracts\SomeInterface`).
275 
276## Spelling
277- Use US English spelling for all identifiers (PHP method/class/property names, TS/Vue variables and components), comments, docstrings, doc pages, and user-visible strings: `serialize` / `serializer` (not `serialise`), `color` (not `colour`), `initialize` (not `initialise`), `behavior` (not `behaviour`), `organize` / `organization`, `favorite`, `analyze`. Koel's codebase — and PHP's SPL (`JsonSerializable`) — is uniformly American; don't drift British by reflex.
278 
279## Self-Explanatory Code
280- Code should read on its own. If a piece of code needs a comment to be understood, that's a signal the code is wrong, not that the comment is needed — refactor it: extract a named helper, rename a variable to encode intent, lift a condition into a named flag, pull a block into a small function. Use a comment only when refactoring genuinely can't carry the intent (a hidden invariant, a workaround tied to a specific external bug, behaviour a reader would otherwise misjudge). Never write comments that narrate the next line, summarise the surrounding block, or restate what well-named identifiers already say.
281- Don't use single-letter variable names. The only allowed ones are `i` / `j` for loop counters, `h` for the test harness, and `$e` for the exception variable in `catch (Throwable|Exception|Error $e)` blocks (PHP's universal idiom — analogous to `e` for events in JS/TS event handlers). For everything else (callback params, destructured fields, lambda args, etc.) pick a name that says what it is.
282- Never combine assignment with return. Always `$x = expr;` then `return $x;` on a separate line — `return $x = expr;` cramming two effects into one statement is forbidden in PHP, TS, and JS.
283 
284## PHP Conventions
285- Always prefer Laravel's built-in helpers over custom implementations (e.g. `str()->plural()`, `Str::slug()`, `Arr::flatten()`, etc.). Do not reimplement what Laravel already provides.
286- For guard clauses that throw on a condition, always reach for `throw_if($condition, ExceptionClass::class, ...$args)` / `throw_unless($condition, ExceptionClass::class, ...$args)` before writing `if (…) { throw new …; }`. The Laravel helpers read as a single declarative line, and the extra args are forwarded to the exception constructor. Plain `if`/`throw` is only correct when the throw branch has to do additional work (logging, side effects) before throwing.
287- All methods must have explicit visibility (`public`, `protected`, or `private`). Never omit the visibility keyword, even on interface methods or static methods.
288- Methods that don't reference `$this` must be declared `static`, unless the class is injectable (DI service) — in that case, prefer instance methods for better testability and decoupling.
289- Always use the least visibility possible. Use `private` by default; only use `protected` or `public` when required by inheritance or external access.
290- Never use `empty()` to check arrays. If the variable is known to be an array, use `!$array` instead. Don't compare to `[]` either.
291- When a string contains quotes, don't use escaped double quotes (e.g. `"Playlist \"$name\" created"`). Use `sprintf()` with a single-quoted format string instead (e.g. `sprintf('Playlist "%s" created', $name)`).
292- Never query models directly (e.g. `Model::query()->where(...)`) outside of the corresponding Repository class. All model lookups and queries must go through the appropriate Repository (e.g. `PlaylistRepository`, `SongRepository`).
293- Repositories are read-only — they must never create, update, or delete records. Write operations belong in services or on the models directly.
294- For config values needed by services, use the `#[Config('key')]` attribute on constructor parameters (from `Illuminate\Container\Attributes\Config`) — never call `config()` inside the service.
295- All closure parameters must be type-hinted. Never use untyped closure arguments (e.g. `function (Builder $query)`, not `function ($query)`).
296- When parsing or manipulating URLs, use `Illuminate\Support\Uri` instead of `parse_url()`.
297- Do not add return type declarations to controller methods — controller responses are too dynamic/flexible for strict return types.
298- Keep controllers thin. A controller method's job is: parse input → authorize → delegate → shape the response (resources/JSON). When a method starts accumulating data-loading orchestration, eager-load bookkeeping, multi-collection merges, or any multi-step domain logic, push that work into a service. Prefer extending an existing service in the same domain (e.g. `MediaBrowser` for browse-side folder operations) over creating a new one. Services return raw domain objects (Collections, Models) — Resource/JSON wrapping stays in the controller. Authorization stays in the controller too, so unauthorized requests fail before expensive data loads.
299- NEVER perform direct Eloquent writes from a controller — no `$model->update(...)`, `->save()`, `->create(...)`, `->delete()`, `->fill()->save()`, relationship `attach`/`detach`/`sync`, or `Model::query()->update/delete`. Every persistence operation goes through a service method (the service may write on the model directly). Controllers only read (via repositories), authorize, and delegate. Even a one-line `$model->update($changes)` belongs in a service — it's the seam where validation, events, and transactions later live. When the obvious service method is a full-update path that doesn't fit (e.g. a partial patch, or one with side effects like folder re-attachment or rule-wiping you don't want), add a focused service method (e.g. `PlaylistService::patchDetails`) rather than writing inline or misusing the heavy one.
300- Value objects in `app/Values/` must use a `final readonly class` with a `private __construct(...)` and a `public static function make(...): self` factory. Call sites construct them via `Foo::make(...)`, never `new Foo(...)`. The reference shape is `App\Values\Radio\RadioStationCreateData`.
301 
302## Environment Variables Documentation
303- When adding, removing, or modifying environment variables in `.env.example`, always update `docs/environment-variables.md` to stay in sync.
304 
305## Documentation Pages
306- Every doc page under `docs/` must have a `description` in its YAML frontmatter. When creating or editing a doc page, ensure the description accurately summarizes the page content.
307- The docs use `vitepress-plugin-llms` to generate `llms.txt` and `llms-full.txt` on build; descriptions are surfaced there.
308- Run `bash docs/.vitepress/check-frontmatter.sh` to verify all pages have descriptions.
309- **Write docs for users, not engineers.** Be concise, use simple words, be friendly. Lead with the action ("To upgrade: 1. Download. 2. Extract. 3. Restart."), not the rationale. Don't explain how launcher scripts or commands work internally — users want to know *what to do*, not *how the script reasons about it*. Cut corporate-speak ("turnkey path", "conceptually immutable", "provisions with the conventional layout"), nerdy parentheticals ("(`migrate` is idempotent — Laravel skips already-applied ones)"), and redundant warnings already covered elsewhere on the page.
310- **Don't inject your own judgment into docs.** No "isn't straightforward", "is usually easier", "you'd need to", "this is the recommended path", "for most users", "if you really want to". Don't editorialize difficulty, opinion-rate alternatives, or steer the reader toward what *you* think they should do. Users decided to read this section; just give them the steps.
311- **No clever bash one-liners for trivial tasks.** Don't reach for `diff <(grep -oE … | sort -u) <(…)` when the instruction is "compare two files" — users can eyeball them. Process substitution, awk, sed pipelines, and similar are nerd-bait. If the task is "look at the difference between A and B", say that in English. Reserve shell snippets for things the user actually needs the exact incantation for.
312 
313## Git Commits
314- Use [Conventional Commits](https://www.conventionalcommits.org/) for all commit messages (e.g. `fix:`, `feat:`, `chore:`, `test:`, `refactor:`, `docs:`, `ci:`, etc.).
315- Focus on the feature/purpose, not implementation details. For example, prefer "feat: show current playing song during radio stream" over "feat: radio station ICY metadata now-playing". Same applies to PR titles.
316- Never attribute work to AI in any artifact: no "Generated with Claude Code", "Assisted by AI", "Co-Authored-By: Claude/ChatGPT/Copilot/AI" lines, no AI-tool mentions in commits, PR titles, PR descriptions, issue comments, code comments, or doc pages. The author is the human running the tool.
317- When the implementation of a PR changes (e.g. during code review), always update the PR title and description to reflect the current state of the changes.
318 
319## Releasing
320- To release a new version, run `php artisan koel:release` (interactive) or `php artisan koel:release {patch|minor|major|vX.Y.Z}`. The command handles the version bump, commit, tag, `latest` tag move, and `release` branch sync.
321- Do not bump `.version`, create release tags, or move the `latest` tag manually — always use `php artisan koel:release`.
322- After the command finishes, the draft release is **not** immediately available on https://github.com/koel/koel/releases. The tag push triggers the `Upload Release Assets` GitHub Action (`.github/workflows/release.yml`), which sets up PHP/Node, builds assets, packages the zip/tarball, and only then creates the draft release. This typically takes several minutes.
323- Wait for the workflow to finish before opening the releases page. Poll with `gh run list --workflow=release.yml --limit 1` or block on it with `gh run watch` (pick the most recent run). Once it's `completed/success`, the draft release exists and can be edited/published on GitHub.
324- For minor/patch releases, you may be asked to write the release notes. Follow the convention of prior releases (e.g. v9.1.1, v9.1.0, v8.3.1):
325    - Title: `vX.Y.Z` (no codename — codenames are reserved for major versions like "Beethoven" in v9.0.0, "Tchaikovsky" in v8.0.0).
326    - Body matches GitHub's auto-generated format. Easiest way: `gh api repos/koel/koel/releases/generate-notes -F tag_name=vX.Y.Z -F previous_tag_name=vPREV --jq .body` to fetch the auto-generated body, then apply it with `gh release edit vX.Y.Z --repo koel/koel --notes-file -`.
327    - Required structure: a `## What's Changed` section with bullets in the form `* <full conventional-commit subject> by @<author> in <PR or commit URL>`, optionally a `## New Contributors` section, and a trailing `**Full Changelog**: https://github.com/koel/koel/compare/vPREV...vX.Y.Z` line.
328    - Do not rewrite or summarize commit subjects — keep them verbatim. Direct-to-master commits without PRs link to the commit SHA URL instead of a PR URL.
329    - **Publish (un-draft) the release before tagging koel/franken or koel/docker.** Both downstream build scripts `curl https://github.com/koel/koel/releases/download/vX.Y.Z/koel-vX.Y.Z.tar.gz`, and that URL returns 404 for draft releases — the build fails. Apply notes and publish in one shot: `gh release edit vX.Y.Z --repo koel/koel --notes-file /tmp/notes.md --draft=false`. Only leave it as a draft if you're releasing koel/koel in isolation (no franken/docker companion).
330- If a downstream build fails because koel/koel was still a draft at the time, recover with `gh workflow run release.yml --repo koel/franken -f koel_version=vX.Y.Z` for franken. koel/docker has no such input — koel/docker#226 removed `workflow_dispatch` so a tag push is the only way to release — so recover there with `gh run rerun <failed-run-id> --repo koel/docker`, which replays the build against the tag that already exists.
331 
332## AI Assistant Tools
333- When AI assistant tool capabilities change (added, removed, or updated), always update the sample prompts in `AiSamplePrompts.vue` to reflect the current abilities.
334 
335## Lucide Icons
336- When importing icons from `lucide-vue-next`, always use the `Icon` suffix (e.g. `SparklesIcon`, not `Sparkles`; `SearchIcon`, not `Search`).
337 
338## TypeScript Conventions
339- Always prefer generics over type casting when the API supports it (e.g. `container.querySelector<HTMLElement>('.foo')` instead of `container.querySelector('.foo') as HTMLElement`).
340- Do not add explicit return types when they can be inferred by the compiler. Only annotate return types when inference is insufficient or ambiguous.
341- When using `setTimeout`, `setInterval`, or `requestAnimationFrame`, always ensure they are cleaned up: on component unmount (`onBeforeUnmount`), on state transitions that invalidate them (e.g. drop cancels a pending expand), and when the operation completes. Treat every timer/rAF as a resource that must be explicitly released.
342 
343## Vue Template Conventions
344- Always use Vue's same-name shorthand for bindings: `:foo` instead of `:foo="foo"`. This applies to props, components, and any v-bind where the attribute name matches the variable name.
345 
346## Vue Forms
347- Any Vue surface that takes user input and commits it on submit must use the `useForm` composable from `@/composables/useForm` — including inline composers, popovers, and mini name-prompts that aren't named `*Form.vue`. Don't roll your own `ref<string>('')` + manual submit handling.
348- Pair it with the canonical wiring: `<form @submit.prevent="handleSubmit" @keydown.esc="maybeClose">`, inputs use `v-koel-focus` (not manual `onMounted` focus) and `required` (not manual `:disabled`), Save is `<Btn type="submit">`, Cancel is `<Btn type="button" @click.prevent="maybeClose">`, and `maybeClose` does `if (isPristine() || (await showConfirmDialog(...))) emit('cancel')`.
349- For purely-local submits (no server call), pass `useOverlay: false` and have `onSubmit` just emit. Use the optional `validator` callback for non-HTML5 rules (e.g. trim/whitespace).
350- Read `resources/assets/js/components/playlist/CreatePlaylistFolderForm.vue` before writing a new form — that's the reference shape.
351 
352## Vue Component Decomposition
353- Always try to break Vue components into smaller, self-managed-state subcomponents. A component that hosts multiple stages, multiple modes, or multiple distinct UI shapes should split each into its own focused child. The parent becomes a thin orchestrator (state machine + API calls + composition); each child owns one shape with clear props in and events out, no service dependencies of its own, and is testable in isolation with minimal mocks. Reference shape: `TwoFactorAuthSettings.vue` (orchestrator) → `TwoFactorEnrollment.vue` / `TwoFactorRecoveryCodes.vue` / `TwoFactorManageActions.vue` (focused children).
354 
355## Vue Component Styling
356- Put shared/base Tailwind classes directly on the HTML element via the `class` attribute.
357- For variant-specific styles (e.g. modes, states), use custom CSS classes (`.initial`, `.chat`, `.user`, `.error`, etc.) with `@apply` in a scoped `<style>` block.
358- Do NOT build class strings in JavaScript arrays or computed properties.
359 
360## Testing Assertions
361- When asserting two Eloquent models are the same, use `assertTrue($modelA->is($modelB))` instead of comparing IDs.
362- Never resort to `ReflectionClass` / `ReflectionProperty` / `ReflectionMethod` in tests to peek at private state, instantiate classes with private constructors, or invoke private methods. If a test "needs" reflection, the smell is the test or the code: the production class should expose what's necessary via a public factory, the dependency should be injectable, or the test should construct the dependency itself (TOTP and similar deterministic primitives need no shared instance). Refactor instead of reaching for reflection.
363 
364## Model Factories
365- Use `createOne()` to create a single model and `createMany()` to create a collection. Never use `create()` directly, as its return type is ambiguous (single model or collection depending on arguments).
366- Wire parent relationships with `->for($parent)` instead of passing foreign keys in the attributes array. For polymorphic relations, pass the relation name as the second argument: `->for($song, 'rateable')` (sets both `*_id` and `*_type`). Prefer `Rating::factory()->for($user)->for($song, 'rateable')->createOne(['rating' => 5])` over the equivalent `createOne(['user_id' => $user->id, 'rateable_id' => $song->id, 'rateable_type' => $song->getMorphClass(), 'rating' => 5])`.
367 
368## Frontend Testing
369- Prefer semantic queries (`getByRole`, `getByLabelText`, `getByText`) via `screen` from `@testing-library/vue`. Use `data-testid` only as a last resort when no semantic query is available.
370- `getBy*` queries already throw if the element is not found, so never wrap them in `expect().toBeTruthy()`. Just call `screen.getByTestId('foo')` directly — the throw is the assertion. Use `expect(screen.queryBy*()).toBeNull()` to assert absence.
371 
372## Test Class Namespacing
373- Unit test classes must mirror the namespace of the class under test. Replace `App\` with `Tests\Unit\` and add a `Test` suffix (e.g. `App\Ai\Services\FavoriteableEntityResolver` → `Tests\Unit\Ai\Services\FavoriteableEntityResolverTest`).
374- The test file path must match the namespace (e.g. `tests/Unit/Ai/Services/FavoriteableEntityResolverTest.php`).
375 
376## Code Reviews
377- When addressing PR review comments, do NOT blindly follow them. Always use your own knowledge and logic to evaluate whether the feedback makes sense. If it doesn't, push back and explain why.
378- CodeRabbit (and similar bots) split their output across two GitHub layers. Before claiming a review has been addressed, query **both**:
379  - `gh api repos/{owner}/{repo}/pulls/{n}/comments` — inline review comments on specific file/line positions (🟡 Minor / 🟠 Major / 🔴 Critical / ⚠️ Potential issue).
380  - `gh api repos/{owner}/{repo}/issues/{n}/comments` — issue-level (conversation) comments. CodeRabbit's PR-level summary lives here, and the **Nitpick comments** are bundled in a collapsible section inside that summary's body.
381  - Hitting only `/pulls/{n}/comments` misses every nitpick. Scan the issue-level summary body for `<details><summary>Nitpick` sections and triage each independently alongside the inline findings.
382 
383## Linting & Static Analysis
384- When running lint or static analysis (backend or frontend), fix ALL warnings and errors to ensure 100% clean output — even pre-existing issues unrelated to current changes.
385- **Before creating or updating any PR that touches PHP files**, run all backend gates locally and confirm green: `composer cs` (format check), `composer lint` (mago lint), `composer analyze` (phpstan). Do NOT rely on the pre-commit hook alone — it only catches formatting. Lint and static-analysis failures must be caught locally, not by CI, so the PR isn't created/updated red.
386 
387## Vite+ Toolchain
388 
389This project uses **Vite+**, a unified toolchain wrapping Vite, Vitest, Oxlint, Oxfmt, and more via a single global CLI called `vp`. Run `vp help` for available commands.
390 
391### Key Commands
392- `vp dev` — development server
393- `vp build` — production build
394- `vp test` — run frontend tests (Vitest)
395- `vp lint` — lint code (Oxlint)
396- `vp fmt` — format code (Oxfmt)
397- `vp check` — run format + lint + type checks
398- `vp install` / `vp add` / `vp remove` — package management (delegates to pnpm)
399- `vp run <script>` — run a package.json script (equivalent of `pnpm run <script>`)
400 
401### Imports
402- Import from `vite-plus` instead of `vite` (e.g. `import { defineConfig } from 'vite-plus'`)
403- Import from `vite-plus/test` instead of `vitest` (e.g. `import { describe, expect, it, vi } from 'vite-plus/test'`)
404- Do NOT install `vitest`, `oxlint`, or `oxfmt` directly — Vite+ wraps these tools
405 
406### Common Pitfalls
407- Do not use `vp vitest` or `vp oxlint` — use `vp test` and `vp lint` instead
408- `vp test` runs the built-in test command; `vp run test` runs the `test` script from package.json
409- Use `vp check` for validation loops (combines fmt + lint + typecheck)
410- Prefer `vp check resources/assets` to scope checks to frontend code
411