Save this content to: AGENTS.md

<laravel-boost-guidelines>
=== .ai/bladewell-starter-kit rules ===

# Bladewell Starter Kit

This app was built from the Bladewell starter kit: Blade pages, Tailwind CSS v4 and Bladewell widgets, with no React, Vue, Inertia or Alpine. Follow these rules on top of the Laravel ones.

## Widgets

- How to find, add and use the widgets is in the Bladewell rules below, from the `bladewell/bladewell` package. In this app the widget files are in `resources/views/components/widget/`, `resources/js/widget/`, `resources/css/widget/` and `app/View/Widget/`.
- Laravel Pint leaves widget files as they are, but don't run Prettier or another formatter over them: a reformatted file counts as edited and stops getting updates.

## Security

- Every security setting lives in `config/security.php`, each with a comment. Change settings there, never by weakening `app/Http/Middleware/SecurityHeaders.php`. `SECURITY.md` lists which setting a given feature needs.
- The Content Security Policy blocks inline scripts, inline event handlers (`onclick=""`) and `style=""` attributes. Put JavaScript in a module under `resources/js/` imported from `app.js`, and styling in classes. To load a script from another site, add its domain to `config/security.php`; never add `'unsafe-inline'` or `'unsafe-eval'`.
- The one inline script is `resources/js/theme-boot.js`, allowed by its hash, which `SecurityHeaders` computes from the file. Keep it tiny; anything that can wait belongs in `resources/js/theme.js`.
- The kit starts with no database, accounts or pages but the home page. When adding accounts, follow "Adding accounts" in `SECURITY.md`.
- Queries for a signed-in person's data go through their relations (`$request->user()->orders()`), so they can only reach their own rows. Records people share need a policy.
- Sort and filter columns from the query string are checked against a fixed list before they reach the query.
- Print with `{{ }}`. Use `{!! !!}` only for markup the app built itself, with a comment saying why.

## Tests

- Every feature and every protection has a test in `tests/Feature`. Run `php artisan test` and `vendor/bin/pint --test` before you say a change is done.
- A security change needs a test that fails without it.

=== .ai/working-style rules ===

# Working Style

## 1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

## 3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

=== foundation rules ===

# Laravel Boost Guidelines

## Foundational Context

This application is a Laravel application running on PHP 8.3. Always use the APIs that match the installed major version of each package — do not assume a version.

Before relying on a package's API, confirm its installed version:
- PHP packages: run `composer show --direct` to list direct dependencies with versions, or `composer show <vendor/package>` for a single package.
- JS packages: check `package.json` for the installed versions.

## Skills Activation

This project has domain-specific skills available in `**/skills/**`. You MUST activate the relevant skill whenever you work in that domain—don't wait until you're stuck.

## Conventions

- 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.
- Use descriptive names for variables and methods. For example, `isRegisteredForDiscounts`, not `discount()`.
- Check for existing components to reuse before writing a new one.

## Verification Scripts

- Do not create verification scripts or tinker when tests cover that functionality and prove they work. Unit and feature tests are more important.

## Application Structure & Architecture

- Stick to existing directory structure; don't create new base folders without approval.
- Do not change the application's dependencies without approval.

## Frontend Bundling

- If a frontend change doesn't show in the UI or you get a "Unable to locate file in Vite manifest" error, run `npm run build` or ask the user to run `npm run dev` or `composer run dev`.

## Documentation Files

- You must only create documentation files if explicitly requested by the user.

=== boost rules ===

# Laravel Boost

## Tools

- Laravel Boost is an MCP server with tools designed specifically for this application. Prefer Boost tools over manual alternatives like shell commands or file reads.
- Use `database-query` to run read-only queries against the database instead of writing raw SQL in tinker.
- Use `database-schema` to inspect table structure before writing migrations or models.
- Use `get-absolute-url` to resolve the correct scheme, domain, and port for project URLs. Always use this before sharing a URL with the user.
- Use `browser-logs` to read browser logs, errors, and exceptions. Only recent logs are useful, ignore old entries.

## Searching Documentation (IMPORTANT)

- Use `search-docs` before changes that depend on Laravel ecosystem APIs, behavior, configuration, or version-specific syntax. Skip it for copy-only edits and other changes where package documentation is irrelevant. Reuse sufficient results already in context instead of searching again.
- Pass a `packages` array to scope results when you know which packages are relevant.
- Use multiple broad, topic-based queries: `['rate limiting', 'routing rate limiting', 'routing']`. Expect the most relevant results first.
- Do not add package names to queries because package info is already shared. Use `test resource table`, not `filament 4 test resource table`.

### Search Syntax

1. Use words for auto-stemmed AND logic: `rate limit` matches both "rate" AND "limit".
2. Use `"quoted phrases"` for exact position matching: `"infinite scroll"` requires adjacent words in order.
3. Combine words and phrases for mixed queries: `middleware "rate limit"`.
4. Use multiple queries for OR logic: `queries=["authentication", "middleware"]`.

## Project Rules

- This project contains committed, area-grouped rules in `.ai/rules` when that directory exists, including path-scoped framework guidelines under `.ai/rules/boost`. Before you enter plan mode or create/edit any file, you MUST first: open @.ai/rules/index.md (it maps file globs to rule files), read every rule file whose globs cover the path(s) in scope, and run `grep -rin 'keyword' .ai/rules` to catch what a path match alone misses. Do not write code until you have read and are following every matching rule. If `.ai/rules` does not exist, continue without it.

## Artisan

- Run Artisan commands directly via the command line (e.g., `php artisan route:list`). Use `php artisan list` to discover available commands and `php artisan [command] --help` to check parameters.
- Inspect routes with `php artisan route:list`. Filter with: `--method=GET`, `--name=users`, `--path=api`, `--except-vendor`, `--only-vendor`.
- Read configuration values using dot notation: `php artisan config:show app.name`, `php artisan config:show database.default`. Or read config files directly from the `config/` directory.

## Tinker

- Execute PHP in app context for debugging and testing code. Do not create models without user approval, prefer tests with factories instead. Prefer existing Artisan commands over custom tinker code.
- Always use single quotes to prevent shell expansion: `php artisan tinker --execute 'Your::code();'`
  - Double quotes for PHP strings inside: `php artisan tinker --execute 'User::where("active", true)->count();'`

=== php rules ===

# PHP

- Always use curly braces for control structures, even for single-line bodies.
- Use PHP 8 constructor property promotion: `public function __construct(public GitHub $github) { }`. Do not leave empty zero-parameter `__construct()` methods unless the constructor is private.
- Use explicit return type declarations and type hints for all method parameters: `function isAccessible(User $user, ?string $path = null): bool`
- Use TitleCase for Enum keys: `FavoritePerson`, `BestLake`, `Monthly`.
- Prefer PHPDoc blocks over inline comments. Only add inline comments for exceptionally complex logic.
- Use array shape type definitions in PHPDoc blocks.

=== deployments rules ===

# Deployment

- Laravel can be deployed using [Laravel Cloud](https://cloud.laravel.com/), which is the fastest way to deploy and scale production Laravel applications.

=== tests rules ===

# Test Enforcement

- Add or update tests for behavior and logic changes when a test provides meaningful regression coverage.
- Pure copy, styling, and layout-only changes do not require new or updated tests.
- When test coverage applies, run the affected tests and ensure they pass.
- Test the changed behavior and its important failure modes, but do not add tests beyond them.
- Read the `testing-best-practices` skill before writing tests.

=== laravel/core rules ===

# Do Things the Laravel Way

- Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using `php artisan list` and check their parameters with `php artisan [command] --help`.
- If you're creating a generic PHP class, use `php artisan make:class`.
- 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.

### Model Creation

- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `php artisan make:model --help` to check the available options.

## APIs & Eloquent Resources

- For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention.

## URL Generation

- When generating links to other pages, prefer named routes and the `route()` function.

## 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()`.
- 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.

=== pint/core rules ===

# Laravel Pint Code Formatter

- If you have modified any PHP files, you must run `vendor/bin/pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style.
- Do not run `vendor/bin/pint --test --format agent`, simply run `vendor/bin/pint --format agent` to fix any formatting issues.

=== phpunit/core rules ===

# PHPUnit

- This project uses PHPUnit. Create tests with `php artisan make:test --phpunit {name}`.
- Do not include the test suite directory in `{name}`. Use `SomeFeatureTest`, not `Feature/SomeFeatureTest`.
- Read the `testing-best-practices` skill for guidance on coverage, naming, structure, dependency isolation, and review.

## Running Tests

- Run the narrowest set of tests that covers the change. Pass a file path or `--filter=testName` to `php artisan test --compact`.
- Rerun a test after each change to it.
- Run `vendor/bin/phpunit` to call the test runner directly. It accepts the same file path and `--filter=testName` arguments.

=== bladewell/bladewell/core rules ===

# Bladewell

Bladewell widgets are Blade components, each with a small vanilla JS module, copied into this app by `php artisan bladewell:add`. The copied files belong to the app.

- Build UI from `<x-widget.*>` components before writing markup of your own. Find one with `php artisan bladewell:list --json` (what each widget does, its props and examples), or the `bladewell` MCP server's `list_components` and `get_component` tools, which give a widget's props, examples and usage notes (such as the endpoint a search or tree calls).
- Add a widget with `php artisan bladewell:add {name}`: it also copies what the widget needs and records it in `bladewell.lock`. Never copy widget files by hand. `php artisan bladewell:add --installed` updates them, but leaves alone any file that was edited, so prefer props, slots and classes over editing a widget, and don't reformat its files.
- Widget JavaScript hooks onto `data-*` attributes and works under a strict Content Security Policy: don't add Alpine, jQuery, inline `<script>`, `onclick=""` or `style=""`.
- Form controls take `name` (or `wire:model`), `label` and `info`, and show the validation error for their name themselves: don't add `@error` markup. Use `readonly`, not `disabled`, for a value that is shown and submitted but can't be changed; a disabled control isn't submitted.
- In Livewire, don't wrap widgets in `wire:ignore`: they already shield what their scripts build, and a wrapped form control stops showing values set in PHP and its errors. Only a bar driven by `progress.set()`, or a third-party script you add, goes in one. Set a picker's, select's, number's, tag field's, OTP's, phone's, colour picker's or slider's value from the server or Livewire: one set by a script or Alpine doesn't show.
- The URLs a widget calls (`suggest-url`, `search-url`, `children-url`, `upload-url`) are named routes in `routes/web.php`, not `routes/api.php`: they share the page's sign-in and CSRF protection, so they can check who is asking. Throttle the ones that run as people type, and authorize as for any page.
- For "Are you sure?", put `confirm="…"` on `<x-widget.button>` or `<x-widget.dropdown.item>` rather than writing a script.
- Toasts: `return back()->with('success', 'Saved.')` from a controller, `$this->dispatch('toast', type: 'success', message: 'Saved.')` from Livewire, `data-toast="success" data-toast-message="Saved."` on a clickable element, or `toast.success('Saved.')` in a script. The layout needs `<x-widget.toast />` once.
- In a long table, render the row menu once, `<x-widget.dropdown.menu id="order-actions">`, and give each row only its trigger, `<x-widget.dropdown menu="order-actions" :values="['id' => $order->id]" />`, with `:id` placeholders in the menu's links: `route('orders.edit', ':id')`.
- Scripts reach widgets through `window.modal`, `window.toast`, `window.dropdown`, `window.popover`, `window.tabs` and the others, by id or element.
- The date picker submits `Y-m-d` and stops at today unless given `:max="false"`. Validate past dates with `new \App\Rules\NotAfterToday`, not `before_or_equal:today`, which uses the server's UTC date.

</laravel-boost-guidelines>