Rebase 2026 08 17 copilot fix

.ai/guidelines/snipe-it-architecture.md

@@ -0,0 +1,71 @@
+# Snipe-IT Architecture
+
+## Controllers
+
+Two parallel controller trees:
+
+- `app/Http/Controllers/` — web/UI controllers returning Blade views.
+- `app/Http/Controllers/Api/` — REST API controllers returning JSON, consumed by datatables and select2.
+
+Both trees use the same subdirectory groupings: `Assets/`, `Licenses/`, `Users/`, `Accessories/`, `Consumables/`, `Components/`, `Kits/`, `Account/`, `Auth/`.
+
+## API Transformers
+
+Every API controller returns data through a **Transformer** in `app/Http/Transformers/`. Never return raw model attributes from an API controller. `DatatablesTransformer` wraps paginated results.
+
+```php
+return (new AssetsTransformer)->transformAssets($assets, $assets->count());
+```
+
+This supersedes the generic advice to reach for Eloquent API Resources — follow the existing transformer convention.
+
+## Authorization
+
+- All authorization goes through **Policies** in `app/Policies/`.
+- `CheckoutablePermissionsPolicy` is the base for assets, licenses, accessories, and consumables.
+- Its `checkout()` / `checkin()` methods accept `$item = null`, so `@can('checkout', \App\Models\Asset::class)` works without an instance.
+
+## Routes
+
+- UI routes live in `routes/web.php` **and** in the per-entity files under `routes/web/` (`hardware.php`, `users.php`, `licenses.php`, `accessories.php`, `components.php`, `consumables.php`, `kits.php`, `models.php`, `fields.php`, `locations.php`). Check both when adding or locating a UI route.
+- API routes are in `routes/api.php`.
+- Breadcrumbs are defined inline with `->breadcrumbs(fn (Trail $trail) => ...)` from `tabuna/breadcrumbs`. **Every UI route should have a breadcrumb.**
+- Some route names contain slashes rather than dots. For example, use `route('reports/unaccepted_assets')`.
+
+## Full Multiple Company Support (FMCS)
+
+`Setting::getSettings()->full_multiple_companies_support == '1'` gates company-scoped filtering. The select2 endpoints (`selectlist()` methods) accept a `companyId` query param:
+
+```php
+if ((Setting::getSettings()->full_multiple_companies_support == '1') && ($request->filled('companyId'))) {
+    $query->where('table.company_id', $request->input('companyId'));
+}
+```
+
+Wire it up from Blade with `data-company-id="{{ $user->company_id }}"`.
+
+## Select2 AJAX Dropdowns
+
+Use `class="js-data-ajax"` with `data-endpoint="hardware|licenses|consumables|..."`. `snipeit.js` auto-initializes these, forwarding `data-company-id` as `companyId` and `data-asset-status-type` as `statusType` to the API.
+
+## Checkout Redirect Flow
+
+After checkout, `Helper::getRedirectOption()` reads `$request->redirect_option`. To redirect back to the assigned user, the form must set:
+
+- `redirect_option=target`
+- `checkout_to_type=user`
+- `assigned_user={{ $user->id }}`
+
+## Translations
+
+UI strings are translation keys in `resources/lang/en-US/general.php` and its sibling files. Always add a new key rather than hard-coding English in a view.
+
+## Global View Variables
+
+`$snipeSettings` is shared with every view by `SettingsServiceProvider`. Use it directly in Blade — do not pass `Setting::getSettings()` from the controller.
+
+## Key Helper Methods (`app/Helpers/Helper.php`)
+
+- `Helper::deployableStatusLabelList()` — status labels for checkout forms.
+- `Helper::defaultChartColors(int $index = 0)` — 10-color chart palette.
+- `Helper::getRedirectOption($request, $id, $table, $item_id = null)` — post-checkout redirect logic.

.ai/guidelines/snipe-it-stack.md

@@ -0,0 +1,32 @@
+# Snipe-IT Stack & Tooling
+
+## Frontend Is Laravel Mix, Not Vite
+
+- Assets are built with **Laravel Mix (webpack)** via `webpack.mix.js`. This project has no `vite.config.js` and no Vite manifest.
+- There is **no `npm run build` script**. Ignore any generic guidance that tells you to run it. Use:
+    - `npm run dev` — development build
+    - `npm run watch` — rebuild on change
+    - `npm run prod` — production build
+- If the user doesn't see a frontend change, ask them to run `npm run dev` or `npm run watch`.
+
+## UI Layer
+
+- **AdminLTE 2 / Bootstrap 3** Blade views. There is no Inertia.
+- **Livewire v4 is installed** and used for discrete widgets in `app/Livewire` (e.g. `Importer`, `CustomFieldEditor`, `LdapSettings`). It is not the primary UI layer.
+- Default to a Blade view plus a standard controller. Only reach for Livewire when extending an existing Livewire component or when the user asks for it.
+
+## Charts
+
+- **Chart.js v2.9.4**, bundled at `public/js/dist/Chart.min.js`.
+- Use the **v2 API**, not v3. For example, the chart type is `horizontalBar` (v3 removed it in favor of `indexAxis`).
+- Use `Helper::defaultChartColors()` for the 10-color palette.
+
+## Commands
+
+```bash
+# Clear caches after config/route changes
+php artisan optimize:clear
+
+# Coverage reports (served by Laravel Herd)
+herd coverage
+```

.ai/guidelines/snipe-it-testing.md

@@ -0,0 +1,12 @@
+# Snipe-IT Testing
+
+- Feature tests live in `tests/Feature/`, organized by entity (e.g. `tests/Feature/Assets/AssetsTest.php`). Unit tests live in `tests/Unit/`.
+- Feature tests hit the database. The test environment uses `array` drivers for cache, session, and mail.
+- Always build test data with model factories. Check for an existing custom state before setting attributes by hand.
+- Test methods are named in snake_case: `test_page_renders()`, `test_requires_permission()`. Never camelCase.
+- UI GET routes should have both a `test_page_renders` test and a `test_requires_permission` test.
+
+```bash
+php artisan test tests/Feature/Assets/AssetsTest.php   # single file
+php artisan test --filter test_some_method             # single method
+```

.ai/rules/actions.md

@@ -0,0 +1,11 @@
+---
+paths:
+  - 'app/Actions/**'
+---
+
+# Actions
+
+## Actions expose a single static run() method
+An Action is a class in `app/Actions/<Entity>/` named `<Verb><Entity>Action`, with one `public static function run(...)` and no constructor. Call it statically: `DestroySupplierAction::run(supplier: $supplier)`.
+
+Do not use `handle()`, `execute()`, `__invoke()`, or instantiate the class.

.ai/rules/api.md

@@ -0,0 +1,38 @@
+---
+paths:
+  - 'app/Http/Controllers/Api/**'
+---
+
+# Api
+
+## Wrap API responses in the standard envelope
+Every API response goes through the shared envelope:
+
+`return response()->json(Helper::formatStandardApiResponse('success', $payload, trans('...')));`
+
+Use `'error'` with a `null` payload for failures, and a translation key for the message. There are no Eloquent API Resources in this project.
+
+## Page API lists with offset and limit
+API list endpoints (`index()`) page with `offset`/`limit` request params, resolved through the container as `app('api_offset_value')` and `app('api_limit_value')`, then applied with `->skip($offset)->take($limit)->get()`.
+
+Do not use `paginate()`, `simplePaginate()`, or `cursorPaginate()` there.
+
+## Select2 endpoints are the pagination exception
+`selectlist()` methods must return a `LengthAwarePaginator`. `SelectlistTransformer::transformSelectlist()` type-hints one and derives select2's `pagination.more`, `total_count`, and `page_count` from `currentPage()`, `lastPage()`, `perPage()`, and `total()`, which drives select2's infinite scroll. A skip/take collection cannot be passed to it.
+
+Use `->paginate(50)`:
+
+```php
+$users = $users->paginate(50);
+
+return (new SelectlistTransformer)->transformSelectlist($users);
+```
+
+When the results have to be sorted or formatted as a collection first, `->get()` and wrap with `Helper::paginateCollection()`, which builds the paginator from `app('api_current_page')` and `app('api_limit_value')`:
+
+```php
+$companies = $companies->orderBy('name', 'ASC')->get();
+// ...sorting/formatting...
+
+return (new SelectlistTransformer)->transformSelectlist(Helper::paginateCollection($sorted));
+```

.ai/rules/app.md

@@ -0,0 +1,9 @@
+---
+paths:
+  - 'app/**'
+---
+
+# App
+
+## Use trans(), never __()
+Translate with `trans('admin/hardware/message.some_key')` using short dotted keys from `resources/lang/<locale>/`. Never use `__()` — it appears nowhere in this codebase. Add a new key rather than hard-coding English.

.ai/rules/controllers.md

@@ -0,0 +1,9 @@
+---
+paths:
+  - 'app/Http/Controllers/**'
+---
+
+# Controllers
+
+## No DTOs or repository layer
+Controllers build Eloquent queries inline and pass models, collections, and arrays around. There are no DTO or repository classes — do not introduce them. Extract to an Action or a Presenter when a controller method gets heavy.

.ai/rules/index.md

@@ -0,0 +1,18 @@
+# Project Rules Index
+
+Before planning or editing, find the row whose globs match the file's path and read that rule file.
+
+| Applies to | Rule file |
+| --- | --- |
+| app/Actions/** | .ai/rules/actions.md |
+| app/Http/Controllers/Api/** | .ai/rules/api.md |
+| app/** | .ai/rules/app.md |
+| app/Http/Controllers/** | .ai/rules/controllers.md |
+| app/Livewire/** | .ai/rules/livewire.md |
+| database/migrations/** | .ai/rules/migrations.md |
+| app/Models/** | .ai/rules/models.md |
+| app/Presenters/** | .ai/rules/presenters.md |
+| app/Providers/** | .ai/rules/providers.md |
+| app/Http/Requests/** | .ai/rules/requests.md |
+| tests/** | .ai/rules/tests.md |
+| resources/views/** | .ai/rules/views.md |

.ai/rules/livewire.md

@@ -0,0 +1,9 @@
+---
+paths:
+  - 'app/Livewire/**'
+---
+
+# Livewire
+
+## Livewire components are class-based with a separate view
+A Livewire component is a class in `app/Livewire` plus a kebab-case Blade view in `resources/views/livewire`. Livewire 4 is installed, but this project uses none of its single-file, multi-file, or Volt formats — match the class-plus-view shape.

.ai/rules/migrations.md

@@ -0,0 +1,9 @@
+---
+paths:
+  - 'database/migrations/**'
+---
+
+# Migrations
+
+## No foreign-key constraints
+Relationship columns are plain `integer('other_id')` columns (nullable and indexed as needed). Do not add `foreignId()`, `foreignIdFor()`, `constrained()`, or `->foreign()->references()` — this schema has no FK constraints and referential integrity is enforced in application code.

.ai/rules/models.md

@@ -0,0 +1,27 @@
+---
+paths:
+  - 'app/Models/**'
+---
+
+# Models
+
+## Models validate themselves with watson/validating
+Models carry their own validation: `use Watson\Validating\ValidatingTrait` plus a `protected $rules` array. `$model->save()` returns false when validation fails and `$model->getErrors()` holds the messages.
+
+This is a second layer on top of the Form Request, not a replacement for it.
+
+## Declare a presenter on the model
+A model that renders in the UI sets `protected $presenter = \App\Presenters\<Entity>Presenter::class` and `use App\Presenters\Presentable`, exposing `$model->present()`.
+
+## Share model behavior through opt-in traits
+Cross-cutting model behavior comes from traits in `app/Models/Traits`, opted into per model: `CompanyableTrait` (FMCS scoping), `Loggable` (action log), `Searchable` (API/datatable search), `Requestable`, `Acceptable`, `HasUploads`.
+
+Add behavior as a trait rather than pushing it into a base class.
+
+## Casts go in the $casts property
+Declare casts with `protected $casts = [...]`, not a `casts()` method, even though Laravel 12 supports the method form.
+
+## New-style Attribute accessors need @return Attribute generics for Larastan
+If a model attribute has a new-style accessor (`protected function locationId(): Attribute`), Larastan drops the property entirely unless the method has a generic PHPDoc: `/** @return Attribute<TGet, TSet> */` (e.g. `Attribute<int|null, int|null>`). Without it, the DB-column extension defers to the accessor extension, the accessor extension requires strict generics, and the property reads as "undefined" — that is why `@property` tags crept into model docblocks (e.g. PR #19480). Fix by adding the `@return Attribute<...>` generic instead of `@property` tags; plain columns without accessors are inferred from migrations automatically and need no annotation.
+
+TGet is the readable type; **TSet is the writable one — the setter's argument, i.e. what may be assigned**, not what the setter stores. Reserve `never` for attributes genuinely never written: no `set:` closure **and** nothing assigns to them (computed values like `expiresDiffInDays()`). No `set:` closure alone is not enough — an accessor decorating a real column still gets assigned elsewhere, and `never` turns each assignment into `Property Setting::$header_color (never) does not accept mixed`; use `mixed` there. Same reasoning for a setter that narrows: `requestable()` stores `(int) filter_var(...)` but accepts an untyped `$value`, so it is `Attribute<int, mixed>`.

.ai/rules/presenters.md

@@ -0,0 +1,11 @@
+---
+paths:
+  - 'app/Presenters/**'
+---
+
+# Presenters
+
+## Presenters own display and datatable config
+Display formatting and Bootstrap-table column config belong in `app/Presenters/<Entity>Presenter.php`, reached from the model via `$model->present()`.
+
+Keep this logic out of controllers, transformers, and Blade.

.ai/rules/providers.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - 'app/Providers/**'
+---
+
+# Providers
+
+## Named validation rules live in ValidationServiceProvider
+Add a new named validation rule as a `Validator::extend()` (or `extendImplicit()`) closure in `app/Providers/ValidationServiceProvider.php`, then reference it by its string name in `$rules`.
+
+`app/Rules` is reserved for the encrypted-custom-field rule objects — do not add general-purpose rules there.
+
+## Register observers in AppServiceProvider
+Wire an observer with `Model::observe(ModelObserver::class)` in `AppServiceProvider::boot()`. Do not use the `#[ObservedBy]` attribute on the model.

.ai/rules/requests.md

@@ -0,0 +1,16 @@
+---
+paths:
+  - 'app/Http/Requests/**'
+---
+
+# Requests
+
+## Form Requests are the validation entry point
+Validate HTTP input with a Form Request class, not inline `$request->validate()` or `Validator::make()`.
+
+Extend `App\Http\Requests\Request` and declare rules in the `protected $rules` property — the base class returns it from `rules()`. When the request handles file uploads, extend `ImageUploadRequest` instead and call `$request->handleImages($model)` in the controller.
+
+## Always call parent::prepareForValidation()
+`ImageUploadRequest` inherits `prepareForValidation()` from the `ConvertsBase64ToFiles` trait, which turns base64 payloads into `UploadedFile` instances before rules run.
+
+If a child request overrides `prepareForValidation()`, it MUST call `parent::prepareForValidation()` — usually first. Forgetting it silently breaks base64 image uploads with no validation error to point at. This has bitten us before.

.ai/rules/tests.md

@@ -0,0 +1,15 @@
+---
+paths:
+  - 'tests/**'
+---
+
+# Tests
+
+## Database refresh comes from the base TestCase
+`Tests\TestCase` already applies `LazilyRefreshDatabase` and seeds settings via `InitializesSettings`. Do not add `RefreshDatabase`, `DatabaseTransactions`, or `DatabaseMigrations` to an individual test.
+
+## Test methods are snake_case
+Name test methods in snake_case: `test_page_renders()`, `test_requires_permission()`. Never camelCase.
+
+## Authenticate API tests with actingAsForApi()
+Use `$this->actingAsForApi($user)` in API tests and `$this->actingAs($user)` in UI tests.

.ai/rules/views.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - 'resources/views/**'
+---
+
+# Views
+
+## Use trans(), never __()
+Translate with `trans('general.some_key')` using short dotted keys from `resources/lang/<locale>/`. Never use `__()` — it appears nowhere in this codebase. Add a new key rather than hard-coding English.
+
+## Blade composition: layouts plus anonymous components
+Pages `@extends` a layout. Reusable markup is an anonymous Blade component: a file in `resources/views/components/` declaring `@props([...])`, used as `<x-name />`.
+
+Do not create class-based components — there is no `app/View/Components` directory.