guidelines: standardise & improve guidelines

Author: ashleyhindle

.ai/boost/core.blade.php

@@ -1,31 +1,34 @@
-# URLs
-Whenever you create a URL use the `get-absolute-url` tool to ensure you're using the correct scheme, domain / IP, and port.
+## Boost
+- Boost MCP comes with powerful tools designed specifically for this application. Use them.
 
-# Artisan
-Use the `list-artisan-commands` tool when you need to call an artisan command to triple check the available parameters.
+## URLs
+- 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.
 
-# Tinker / Debugging
-You should use the `tinker` tool from Boost MCP when you need to run PHP to debug code or query Eloquent models directly.
+## Artisan
+- Use the `list-artisan-commands` tool when you need to call an artisan command to triple check the available parameters.
 
-Use the `database-query` tool when you only need to read from the database.
+## Tinker / Debugging
+- You should use the `tinker` tool from Boost MCP when you need to run PHP to debug code or query Eloquent models directly.
+- Use the `database-query` tool when you only need to read from the database.
 
-# Reading browser logs
-Only recent browser logs will be useful, discard any that are older than two hours or so.
+@if(config('boost.browser_logs', true) !== false || config('boost.browser_logs_watcher', true) !== false)
+## Reading browser logs with the `browser-logs` tool
+- You can read browser logs, errors, and exceptions with the `browser-logs` tool from Boost.
+- Only recent browser logs will be useful, ignore old logs.
+@endif
 
-# Searching documentation
-Check the docs before making code changes to ensure we are approaching this in the correct way. Use multiple simple topic based queries.
+## Searching documentation (critically important)
+- Boost comes with a powerful `search-docs` tool you should use before any other approaches. This tool automatically passes a list of installed packages and their versions to the remote Boost API, so it returns only version-specific documentation specific for the user's circumstance. You should pass an array of packages to filter docs on if you know you need docs for particular packages.
+- The 'search-docs' tool is perfect for all Laravel related packages. Laravel, Inertia, Pest, Livewire, Nova, Nightwatch, etc..
+- You must use this tool to search for Laravel-ecosystem docs before falling back to other approaches.
+- Search the docs before making code changes to ensure we are approaching this in the correct way.
+- Use multiple broad simple topic based queries to start, i.e. `rate limiting##routing rate limiting##routing`.
 
-Boost comes with a powerful `search-docs` tool you should use before any other approaches. This tool automatically passes a list of installed packages and their versions to the remote Boost API, so it returns only version-specific documentation specific for the user's circumstance. You should pass an array of packages to filter docs on if you know you need docs for particular packages.
-
-The 'search-docs' tool is perfect for all Laravel related packages. Laravel, Inertia, Pest, Livewire, Nova, Nightwatch, and more.
-
-You must use this tool to search for Laravel-ecosystem docs before falling back to other approaches.
-
-## Available search syntax
-You can and should pass multiple queries at once, the most relevant will be returned first. Start specific, broaden after.
+### Available search syntax
+- You can and should pass multiple queries at once, the most relevant results will be returned first.
 
 1. Simple Word Searches with auto-stemming - query=authentication - finds 'authenticate' and 'auth'
-2. Multiple Words (AND Logic) - query=rate limit - finds knowledge containing both "queue" AND "worker"
+2. Multiple Words (AND Logic) - query=rate limit - finds knowledge containing both "rate" AND "limit"
 3. Quoted Phrases (Exact Position) - query="infinite scroll - Words must be adjacent and in that order
 4. Mixed Queries - query=middleware "rate limit" - "middleware" AND exact phrase "rate limit"
 5. Multiple Queries - queries=["authentication", "middleware"] - ANY of these terms

.ai/enforce-tests.blade.php

@@ -1 +1,2 @@
-- Every change must be programmatically tested. Write a new test, or update an existing test, then run the tests to make sure they pass.
+- 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.
+- Run the minimum number of tests needed to ensure code quality and speed. Use `php artisan test` with a specific filename or filter.

.ai/folio/core.blade.php

@@ -6,16 +6,17 @@
 - `pages/auth/login.blade.php` → `/auth/login`
 - List available Folio routes using `artisan folio:list` or using Boost's `list-routes` tool.
 
-### New pages & routes
+### Folio: New pages & routes
 - Always create new `folio` pages and routes using `artisan folio:page [name]` following existing naming conventions.
 
 @verbatim
 <code-snippet name="Example folio:page commands for automatic routing" lang="shell">
+    // Creates: resources/views/pages/products.blade.php → /products
     php artisan folio:page 'products'
-    # Creates: resources/views/pages/products.blade.php → /products
 
+
+    // Creates: resources/views/pages/products/[id].blade.php → /products/{id}
     php artisan folio:page 'products/[id]'
-    # Creates: resources/views/pages/products/[id].blade.php → /products/{id}
 </code-snippet>
 @endverbatim
 
@@ -29,7 +30,7 @@
 @endverbatim
 
 
-### Support & Docs
+### Folio: Support & Docs
 - Folio supports: middleware, serving pages from multiple paths, subdomain routing, named routes, nested routes, index routes, route parameters, and route model binding.
 - If available, use Boost's `search-docs` tool to use Folio to its full potential and help the user effectively.
 

.ai/herd/core.blade.php

@@ -1,2 +1,2 @@
-- The site is made available by Herd, and will be available at: https?://[kebab-case-project-dir].test. Use the `get-absolute-url` tool to generate URLs.
+- The site is made available by Herd, and will be available at: https?://[kebab-case-project-dir].test. Use the `get-absolute-url` tool to generate URLs for the user to ensure user satisfaction and valid URLs.
 - You must not run any commands to make the site available via HTTP(s). It is _always_ available through Herd.

.ai/inertia-laravel/core.blade.php

@@ -1,12 +1,12 @@
 ## Inertia Core
 
-- Inertia.js components should be placed in the `resources/js/Pages` directory.
+- Inertia.js components should be placed in the `resources/js/Pages` directory, unless specified differently in the JS bundler (ie. vite.config.js).
 - Use `Inertia::render()` for server-side routing instead of traditional Blade views.
 <code-snippet lang="php" name="Inertia::render example">
-    // routes/web.php example
-    Route::get('/users', function () {
+// routes/web.php example
+Route::get('/users', function () {
     return Inertia::render('Users/Index', [
-    'users' => User::all()
+        'users' => User::all()
     ]);
-    });
+});
 </code-snippet>

.ai/laravel/10/core.blade.php

@@ -1 +1,10 @@
-## Laravel 10 Core
+## Laravel 10
+- Use `search-docs` tool, if available, to get version specific documentation.
+
+- Middleware typically lives in `app/Http/Middleware/` and service providers in `app/Providers/`.
+- There is no `bootstrap/app.php` application configuration in Laravel 10:
+    - Middleware registration happens in `app/Http/Kernel.php`
+    - Exception handling is in `app/Exceptions/Handler.php`
+    - Console commands and schedule register in `app/Console/Kernel.php`
+    - Rate limits likely exist in `RouteServiceProvider` or `app/Http/Kernel.php`
+- Model Casts: you must use `protected $casts = [];` not the `casts()` method. The `casts()` method isn't available on models in Laravel 10.

.ai/laravel/11/core.blade.php

@@ -1,4 +1,39 @@
-## Laravel 11 Core
+## Laravel 11
+- Use `search-docs` tool, if available, to get version specific documentation.
 
-- **No app\Console\Kernel.php** - use `bootstrap/app.php` for console configurations.
+@if (file_exists(base_path('app/Http/Kernel.php')))
+{{-- Migrated from L10 to L11, but did't migrate to the new L11 Structure --}}
+- This project upgraded from Laravel 10 without migrating to the new streamlined Laravel 11 file structure.
+- This is **perfectly fine** and recommended by Laravel. Follow the existing structure from Laravel 10. We do not to need migrate to the Laravel 11 structure unless the user explicitly requests that.
+
+### Laravel 10 Structure
+- Middleware typically lives in `app/Http/Middleware/` and service providers in `app/Providers/`.
+- There is no `bootstrap/app.php` application configuration in a Laravel 10 structure:
+    - Middleware registration happens in `app/Http/Kernel.php`
+    - Exception handling is in `app/Exceptions/Handler.php`
+    - Console commands and schedule register in `app/Console/Kernel.php`
+    - Rate limits likely exist in `RouteServiceProvider` or `app/Http/Kernel.php`
+@else
+{{-- Laravel 11 project anew, or upgraded & migrated structure --}}
+- Laravel 11 brought a new streamlined file structure which this project uses.
+
+### Laravel 11 Structure
+- No middleware files in `app/Http/Middleware/`.
+- `bootstrap/app.php` is the file to register middleware, exceptions, and routing files.
+- `bootstrap/providers.php` for project specific service providers.
+- **No app\Console\Kernel.php** - use `bootstrap/app.php` or `routes/console.php` for console configurations.
 - **Commands auto-register** - files in `app/Console/Commands/` are automatically available.
+@endif
+
+### Database
+- 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.
+- Laravel 11 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`
+
+### Models
+- Casts can/should be set in a `casts()` method on a model, rather than the `$casts` property. Follow existing conventions from other models.
+
+### New artisan commands
+- List artisan commands using Boost's MCP tool, if available. New commands:
+    - `php artisan make:enum`
+    - `php artisan make:class`
+    - `php artisan make:interface`

.ai/laravel/12/core.blade.php

@@ -1,4 +1,29 @@
-## Laravel 12 Core
+## Laravel 12
+- Use `search-docs` tool, if available, to get version specific documentation.
+
+@if (file_exists(base_path('app/Http/Kernel.php')))
+    {{-- Migrated from L10 to L12, but did't migrate to the new L11 Structure --}}
+    - This project upgraded from Laravel 10 without migrating to the new streamlined Laravel file structure.
+    - This is **perfectly fine** and recommended by Laravel. Follow the existing structure from Laravel 10. We do not to need migrate to the new Laravel structure unless the user explicitly requests that.
+
+    ### Laravel 10 Structure
+    - Middleware typically lives in `app/Http/Middleware/` and service providers in `app/Providers/`.
+    - There is no `bootstrap/app.php` application configuration in a Laravel 10 structure:
+    - Middleware registration happens in `app/Http/Kernel.php`
+    - Exception handling is in `app/Exceptions/Handler.php`
+    - Console commands and schedule register in `app/Console/Kernel.php`
+    - Rate limits likely exist in `RouteServiceProvider` or `app/Http/Kernel.php`
+@else
+    {{-- Laravel 12 project anew, or upgraded & migrated structure --}}
+    - Laravel brought a new streamlined file structure which this project uses.
+
+    ### Laravel file Structure
+    - No middleware files in `app/Http/Middleware/`.
+    - `bootstrap/app.php` is the file to register middleware, exceptions, and routing files.
+    - `bootstrap/providers.php` for project specific service providers.
+    - **No app\Console\Kernel.php** - use `bootstrap/app.php` or `routes/console.php` for console configurations.
+    - **Commands auto-register** - files in `app/Console/Commands/` are automatically available.
+@endif
+
+
 
-- **No app\Console\Kernel.php** - use `bootstrap/app.php` for console configurations.
-- **Commands auto-register** - files in `app/Console/Commands/` are automatically available.

.ai/laravel/core.blade.php

@@ -1,20 +1,23 @@
 ## Do Things the Laravel Way
-- Use `./artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.).
+- Use `./artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available artisan commands with the `list-artisan-commands` tool.
 - If you're creating a generic PHP class, use `artisan make:class`.
 
 ## Database
 - **Model relationships**: Always use proper Eloquent relationship methods with return type hints. Prefer relationship methods over raw queries or manual joins.
-- **Eloquent first approach**: Use Eloquent models and relationships before suggesting raw database queries - Avoid `DB::`; use `Model::query()` only. Generate code that leverages Laravel's ORM capabilities rather than bypassing them.
-- **Form request validation**: Always create Form Request classes for validation rather than inline validation in controllers. Include both validation rules and custom error messages.
+- **Eloquent first approach**: Use Eloquent models and relationships before suggesting raw database queries
+- Avoid `DB::`; prefer `Model::query()`. Generate code that leverages Laravel's ORM capabilities rather than bypassing them.
 - **DB N+1**: Generate code that prevents N+1 query problems by using eager loading.
-- For DB pivot tables, use correct alphabetical order, like "project_role" instead of "role_project"
 - Use Laravel's query builder for very complex database operations.
 
+## Controllers and validation
+- **Form request validation**: Always create Form Request classes for validation rather than inline validation in controllers. Include both validation rules and custom error messages.
+- **Validation rule style**: Check sibling form requests to see if the project uses array or string based validation rules.
+
 ## Model Creation
-- When creating new models, create factories and seeders for them too. Ask the user if they need any other things, use `list-artisan-commands` to check the available options to `./artisan make:model`
+- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, use `list-artisan-commands` to check the available options to `./artisan make:model`
 
 ## APIs and Eloquent Resources
-- For APIs, use Eloquent API Resources and API versioning
+- For APIs, default to using Eloquent API Resources and API versioning, unless existing API routes do not, then you should follow existing convention.
 
 ## Queues
 - **Job and queue patterns**: Use queued jobs for time-consuming operations with the `ShouldQueue` interface.
@@ -27,9 +30,10 @@
 
 ## Testing
 - 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.
+- Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`.
 
 ## Vite Error
 - If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `npm run build` or ask the user to run `npm run dev` or `composer run dev`.
 
 ## URL Generation
-- When generating links to other pages, always prefer named routes and the `route()` function.
+- When generating links to other pages, prefer named routes and the `route()` function.

.ai/pest/core.blade.php

@@ -14,11 +14,11 @@
 </code-snippet>
 
 # Running Tests
-- Run the minimal number of tests, using an appropriate filter, before finalizing.
+- Run the minimal number of tests, using an appropriate filter, before finalizing code edits.
 - Run all tests: `php artisan test`.
 - Run all tests in a file: `php artisan test tests/Feature/ExampleTest.php`.
 - Filter on particular test name: `php artisan test --filter=testName` (recommended after making a change to a related file).
-- When the tests relating to your feature are passing, make sure to also run the entire test suite to ensure everything is still passing.
+- When the tests relating to your changes are passing, ask the user if they'd like to run the entire test suite to ensure everything is still passing.
 
 ## Pest Assertions
 - When asserting status codes on a response, use the specific method like `assertForbidden`, `assertNotFound` etc, instead of using `assertStatus(403)` or similar, e.g.: