# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **Laravel application** bootstrapped with
[CleaniqueCoders Kickoff](https://github.com/cleaniquecoders/kickoff), providing a standardized
structure with pre-configured packages and conventions.

- **Framework**: Laravel 13+ with PHP 8.4+
- **Frontend**: Livewire 4 + TailwindCSS v4 + Alpine.js
- **Testing**: Pest PHP (not PHPUnit syntax)
- **Database**: MySQL with dual-key pattern (auto-increment `id` for internal relations + `uuid` column for public-facing identifiers)

### Architecture decisions (ADRs)

Significant architectural choices are recorded as ADRs under [`docs/adr/`](docs/adr/). Read the
relevant ADR before changing core abstractions (identity, money, audit, identifiers, swappable
drivers). See [`docs/adr/README.md`](docs/adr/README.md) for the template and when to write one.

## Common Commands

```bash
# Development
composer dev              # Start server, queue, logs, and Vite concurrently
npm run dev               # Vite dev server with HMR
npm run build             # Build production assets

# Testing
composer test             # Run the full suite (Xdebug pinned off)
composer test-parallel    # Full suite in parallel
composer test-arch        # Architecture tests only
composer test-tia         # Fast loop — only tests impacted by your changes (needs pcov)
composer test-tia-fresh   # Discard the TIA graph and re-record
composer test-coverage    # Run tests with coverage (needs pcov)

# Code Quality
composer format           # Format code with Laravel Pint
composer analyse          # Run PHPStan static analysis
composer rector           # Run Rector for automated refactoring
composer lint             # Check PHP syntax

# Database
php artisan migrate       # Run migrations
php artisan reload:db     # Drop, migrate, and seed (fresh start)

# Single test file
./vendor/bin/pest tests/Feature/ExampleTest.php
./vendor/bin/pest --filter="test name"
```

## Architecture & Key Concepts

### Models - CRITICAL

**ALL models MUST extend `App\Models\Base`** instead of `Illuminate\Database\Eloquent\Model`.

Laravel 13 uses **PHP attributes** for model properties instead of `$fillable`, `$guarded`, `$hidden`:

```php
namespace App\Models;

use App\Models\Base as Model;
use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Attributes\Hidden;

#[Fillable(['name', 'description', 'status'])]
#[Hidden(['id'])]
class Product extends Model
{
    // Auto-increment id (internal) + uuid column (public-facing) - automatic
    // Auditing - automatic
    // Media support - automatic
}
```

The Base model provides:

- Dual-key pattern: auto-increment `id` + auto-generated `uuid` column (`InteractsWithUuid`)
- Auditing via owen-it/laravel-auditing
- Media attachments via Spatie Media Library
- User tracking (created_by, updated_by)
- Resource route helpers

### Database Conventions

- **Primary keys**: Auto-increment `id` for internal DB relations + `uuid` column for public-facing identifiers (`$table->id()` + `$table->uuid('uuid')->index()`)
- **Soft deletes**: Use for all user-facing models
- **Column naming**: snake_case
- **Credentials columns**: Always cast with `encrypted:array` (not manual `encrypt()`)

> **Gotcha:** Using `encrypt()` manually when the model already has `encrypted:array` cast
> causes double-encryption. The cast handles encryption transparently — just assign the plain array.

### Enums

Use enums for all status/type fields. Place in `app/Enums/`.
Custom stub at `stubs/enum.stub` generates the correct template via `php artisan make:enum`.

```php
namespace App\Enums;

use CleaniqueCoders\Traitify\Contracts\Enum as Contract;
use CleaniqueCoders\Traitify\Concerns\InteractsWithEnum;

enum Status: string implements Contract
{
    use InteractsWithEnum;

    case DRAFT = 'draft';
    case ACTIVE = 'active';

    public function label(): string
    {
        return match ($this) {
            self::DRAFT => 'Draft',
            self::ACTIVE => 'Active',
        };
    }

    public function description(): string
    {
        return match ($this) {
            self::DRAFT => 'Item is in draft state.',
            self::ACTIVE => 'Item is active.',
        };
    }
}
```

All enums must implement `CleaniqueCoders\Traitify\Contracts\Enum` and use the
`InteractsWithEnum` trait. This provides `values()`, `labels()`, and `options()` methods.

### Authorization

Use **Spatie Laravel Permission** with policies:

```php
// Permission naming: module.action.target
$user->can('users.view.list');
$user->can('products.create.item');

// In controllers
$this->authorize('update', $product);
```

Default roles: `superadmin`, `administrator`, `user`

### Application Settings (Spatie Laravel Settings)

Application-level settings are stored in the **database** via `spatie/laravel-settings` — NOT in `.env`.

**Settings classes** in `app/Settings/`:
- `GeneralSettings` — `site_name`
- `MailSettings` — `from_address`, `from_name`
- `NotificationSettings` — `enabled`, `channels`
- `SeoSettings` — meta defaults, Open Graph, canonical toggle, robots.txt, GA4/GTM IDs, organization schema

**How it works**: `AppServiceProvider::boot()` reads from DB and overrides `config()` values, so all existing `config('app.name')`, `config('mail.from.*')`, `config('notification.*')` calls automatically use DB values.

```php
// Reading (via config — already overridden at runtime)
config('app.name');

// Reading (via Settings class directly)
app(GeneralSettings::class)->site_name;

// Writing
$settings = app(GeneralSettings::class);
$settings->site_name = 'New Name';
$settings->save();
```

**Admin UI**: Managed at Admin > Settings (site name, mail from, notifications).

**What stays in .env**: Infrastructure settings (`APP_ENV`, `APP_DEBUG`, SMTP credentials, DB, Redis).

> **Gotcha:** Never write to `.env` at runtime. Use Spatie Settings for any value that admins should be able to change from the UI.

### SEO & Analytics

All SEO surface is admin-editable at **Admin > Settings > SEO & Analytics** (`SeoSettings`, overlaid onto `config('seo.*')` at boot). See `docs/02-development/17-seo.md` for the full guide.

- Meta/OG/Twitter/canonical tags render from `partials/seo.blade.php` (included by `partials/head.blade.php` in every layout). Per-page override: `<x-layouts.app :title="..." :description="...">`.
- GA4/GTM snippets (`partials/analytics.blade.php` + `analytics-noscript.blade.php`) render **only when an ID is set** — never hardcode tracking snippets in views.
- `/robots.txt` and `/sitemap.xml` are routes in `routes/web/seo.php` — do NOT create static `public/robots.txt`/`public/sitemap.xml` by hand (a static file shadows the route). For big sites, schedule `php artisan seo:generate-sitemap`.
- Structured data: `Organization` + `WebSite` schemas render automatically; page-level schemas use the `seo_schema_*()` helpers in `support/seo.php` (breadcrumb, faq, article, product, course, event, webpage). Do NOT hand-write `<script type="application/ld+json">` in views.

### Deploy Operations (post-deploy data tasks)

For **one-off post-deploy tasks** that don't belong in migrations — backfills, data fixes,
permission seeding, third-party sync, cache warm-up — use
[`dragon-code/laravel-deploy-operations`](https://github.com/TheDragonCode/laravel-deploy-operations).
Operations live in `operations/`, run once per environment, and are tracked in the `operations` table.

```bash
php artisan make:operation backfill_user_uuids   # scaffold
php artisan operations                            # run pending
php artisan operations --force                    # run in production (no prompt)
php artisan operations:status                     # show ran/pending
php artisan operations:rollback                   # rollback last batch
php artisan operations:fresh                      # re-run all from scratch
```

`bin/deploy` runs `php artisan operations --force` automatically after `migrate --force`.

| Use Case | Tool |
|---|---|
| Schema change (add column, create table) | **Migration** |
| One-off data backfill or fix | **Deploy Operation** |
| Re-runnable seed data (roles, default settings) | Seeder |
| Code change only | Just deploy — no operation needed |

See `docs/04-deployment/01-deployment.md` for full guidance.

### Helper Functions

Located in `support/` directory, auto-loaded via Composer:

```php
user();                           // Get authenticated user
flash('success', 'Message');      // Flash messages
money_format(1234.56);            // Format: "1,234.56"
```

### Directory Conventions

When the project grows, follow these directory conventions for organizing business logic:

| Directory | Purpose | When to Create |
|---|---|---|
| `app/Services/` | Business logic services (e.g., `PaymentService`, `ReportService`) | When logic doesn't belong in a model, controller, or action |
| `app/DataTransferObjects/` | Typed DTOs for passing structured data between layers | When passing 3+ related values between classes |
| `app/Contracts/` | Interfaces for services and abstractions | When you need swappable implementations or test doubles |
| `app/Actions/` | Single-purpose action classes | When an operation is reusable across controllers/commands |

These directories are not scaffolded by default — create them as needed. The architecture tests
already enforce `app/Contracts/` contains only interfaces and `app/Concerns/` contains only traits.

## File Organization

```text
app/
├── Actions/        # Single-purpose action classes (Builder/Menu already included)
├── Concerns/       # Traits (InteractsWithLivewireForm, HasMedia, etc.)
├── Console/        # Artisan commands (24+ included: seeders, cache, code generation)
├── Contracts/      # Interfaces (HeadingMenuBuilder, AuthorizedMenuBuilder)
├── Enums/          # Status/type enums
├── Exceptions/     # Custom exceptions (ActionException, ThrowException)
├── Livewire/       # Livewire components
├── Models/         # Eloquent models (extend Base)
├── Notifications/  # Notification classes
├── Mail/           # Mailable classes
├── Policies/       # Authorization policies
├── Settings/       # Spatie Settings classes
support/            # Helper functions by domain (16 files)
routes/web/         # Modular web routes (auth, admin, security, pages, etc.)
stubs/              # Custom Artisan stubs (model, migration, enum, pest, policy)
bin/                # Deployment and utility scripts (7 scripts)
docs/               # Project documentation (getting started, development guides)
config/             # Custom configs (access-control, admin, audit, horizon, etc.)
```

## Testing with Pest

`composer test` runs the full Pest 5 suite with `XDEBUG_MODE` pinned off.
`composer test-tia` is the opt-in fast loop — Test Impact Analysis, where only tests impacted
by your uncommitted changes execute. TIA refuses PHPUnit-class-style tests, so always write
tests in Pest syntax either way. CI always runs the full suite.

> **Gotcha:** **TIA is not free and cannot be the zero-config default.** It records *per-test*
> coverage before it can skip anything, so it needs a coverage driver. Under Xdebug a cold
> record of a mid-sized suite runs to ~90 minutes, and Composer's default 300-second process
> timeout kills it part way through, leaving `worker-edges-*.json` and **no** `graph.json` — an
> unusable graph, so the next run re-records from scratch and hits the same wall, forever.
> Under pcov the same record is ~72s and a replay ~5s. Install pcov before using `test-tia`:
> see `build/php-ini/README.md`.

> **Gotcha:** **Pin `XDEBUG_MODE` in every test script.** A machine with `xdebug.mode=coverage`
> in its ini pays roughly **3×** on every run. Use the **array + `@putenv`** form in
> `composer.json`, not an inline `VAR=x` prefix: it keeps `@php` (so Composer picks the PHP
> binary), works on Windows, and still forwards extra CLI args. And never `php -d` — ParaTest
> spawns its workers without the parent's `-d` flags, so only an environment variable reaches
> them. `PHP_INI_SCAN_DIR` is used for the same reason.

> **Gotcha:** The TIA graph lives in `~/.pest/tia/<project-key>/`, **not** in the repo
> (`pest --baseline` prints the path), so the absence of a `.pest/` directory tells you nothing.
> `tests/Pest.php` may set `->filtered()` but deliberately **not** `->locally()` or `->always()`
> — those mark TIA *enabled* and put the record cost on every local run. TIA normalises content,
> so a comment-only edit correctly yields "No affected tests found"; that is not a bug.

> **Gotcha:** Tests run on **SQLite in-memory** (`phpunit.xml`) — the most permissive engine
> there is. A green suite is not evidence a migration is portable, and it is not evidence that
> anything in Alpine or a Flux custom element works. See the Database Portability and Alpine.js
> gotchas.

Use Pest syntax (not PHPUnit):

```php
it('can create a product', function () {
    $user = User::factory()->create();

    actingAs($user)
        ->post('/products', ['name' => 'Test'])
        ->assertRedirect('/products');

    expect(Product::count())->toBe(1);
});
```

### Livewire Testing

```php
use Livewire\Livewire;

Livewire::test(ProductForm::class)
    ->set('name', 'Test Product')
    ->call('save')
    ->assertHasNoErrors()
    ->assertDispatched('toast');
```

### Architecture Tests

Located in `tests/Feature/ArchitectureTest.php`. Enforces:

- No `dd()`, `dump()`, `ray()` in application code
- No `url()` helper usage — use `route()` instead
- `env()` only used in `config/` files
- No raw DB queries (`DB::raw`, `DB::select`, etc.)
- Controllers have `Controller` suffix
- Policies are classes with `Policy` suffix
- Mailables extend `Illuminate\Mail\Mailable`
- Concerns are traits, Enums are enums, Contracts are interfaces

## Livewire Patterns

### Toast Notifications (Primary)

Use the `<x-toast />` Alpine.js component (already mounted in sidebar layout) for all
user-facing notifications. Dispatch from any Livewire component:

```php
// Success notification
$this->dispatch('toast', type: 'success', message: 'Item saved successfully.');

// Error notification
$this->dispatch('toast', type: 'error', message: 'Something went wrong.');

// Warning / Info
$this->dispatch('toast', type: 'warning', message: 'Check your input.');
$this->dispatch('toast', type: 'info', message: 'Processing started.');
```

After redirect — flash to session, pick up on target page:

```php
session()->flash('toast', ['message' => 'Done!', 'type' => 'success']);
return $this->redirect('/products');
```

From Alpine.js directly:

```html
<button @click="$dispatch('toast', { type: 'info', message: 'Hello from Alpine!' })">
```

> **Gotcha:** For user feedback messages, use `$this->dispatch('toast', type: 'success', message: '...')`
> which renders via the `<x-toast />` component already in the sidebar layout. Toast types:
> `success`, `error`, `warning`, `info`. Do NOT create custom alert modal components for simple
> feedback — toast notifications are the standard pattern.

### Confirmations

Use Livewire's native `wire:confirm` on the triggering element. The browser shows the
dialog client-side and, on confirm, calls the wired method directly — no separate modal
component to mount.

```blade
<flux:menu.item icon="trash-2" variant="danger"
    wire:click="delete('{{ $item->uuid }}')"
    wire:confirm="{{ __('Are you sure you want to delete :name?', ['name' => $item->name]) }}">
    {{ __('Delete') }}
</flux:menu.item>
```

```php
public function delete(string $uuid): void
{
    $item = Item::where('uuid', $uuid)->firstOrFail();
    $this->authorize('delete', $item);

    $item->delete();
    $this->dispatch('toast', type: 'success', message: __('Deleted.'));
}
```

> For destructive confirmations that need typed input (GitHub-style), use a `flux:modal`.

### Flyout vs Modal vs Dedicated Page — when to use which

Pick the surface by **what the interaction is**, not by habit:

- **Dedicated page** = a *destination*: deep-linkable/bookmarkable URL, dense or multi-section content, tabs, nested/related lists, print/export, primary place the user goes to and stays.
- **Flyout (side panel)** = a *quick side task in the context of a list*: view or light-edit one record without leaving the list, especially when hopping between rows. Default for "open this row".
- **Modal (centered dialog)** = a *focused interruption*: confirmations and 1–2 field quick edits.

Decision signals:

| Signal | Page | Flyout | Modal |
|---|---|---|---|
| Needs a shareable/bookmarkable URL (link in email, ticket, audit reference) | ✅ | ❌ | ❌ |
| Content density | high (sections/tabs/sub-tables) | low–medium (one record) | tiny (one message/field) |
| Opened repeatedly across rows (open A, close, open B) | painful | ✅ ideal | ok for confirms |
| Has nested/related lists inside | ✅ | avoid | ❌ |
| Print / export / SEO | ✅ | ❌ | ❌ |

Heuristics:

- **Default to a flyout** for "view/edit one row" when it fits one scroll and the user bounces between rows. **Promote to a page** the moment it gains tabs, nested lists, a deep-link need, or a long/multi-step form.
- **Modal only** for confirmations and 1–2 field quick edits (use `<x-form-modal>` without `variant`).
- **Don't offer two doors** to the same detail — make row-click the primary entry and keep the 3-dot menu for *write* actions (edit/delete/etc.).
- Audits/records that are referenced elsewhere keep a **dedicated page** (deep-linkable); a flyout quick-peek may be *added* but should not replace the URL.

**Row-click → detail flyout pattern** (parent list component owns the state):

```php
public ?string $detailUuid = null;
public bool $showDetail = false;
public int $detailKey = 0;   // bump each open so the child re-mounts cleanly

public function openDetail(string $uuid): void
{
    $this->detailUuid = $uuid;
    $this->detailKey++;
    $this->showDetail = true;
}
```

```blade
{{-- Row opens the flyout; the actions cell stops propagation so the 3-dot menu still works --}}
<tr wire:key="row-{{ $item->uuid }}" wire:click="openDetail('{{ $item->uuid }}')"
    class="cursor-pointer hover:bg-zinc-50 dark:hover:bg-zinc-700/50">
    {{-- cells --}}
    <td @click.stop>{{-- <flux:dropdown> 3-dot write actions --}}</td>
</tr>

<x-flyout name="item-detail" size="lg" wire:model="showDetail">
    @if ($detailUuid)
        <livewire:item.detail :uuid="$detailUuid" :key="'item-detail-'.$detailKey" />
    @endif
</x-flyout>
```

### Form Modal vs Flyout — Standard

Two shared components live at the top of `resources/views/components/`:

- **`<x-form-modal>`** (`form-modal.blade.php`) — for inline create/edit forms. Renders heading/subheading scaffolding and switches between modal and flyout via the `variant` prop.
- **`<x-flyout>`** (`flyout.blade.php`) — a low-level flyout primitive (just `<flux:modal variant="flyout">` + size class). Use directly when you need a side panel for **non-form** content (detail view, filter panel, preview, etc.). `<x-form-modal variant="flyout">` delegates to this internally.

For forms, always use `<x-form-modal>` and pick the variant based on form size — never roll a custom `<flux:modal>` wrapper.

| Form size | Variant | When |
|---|---|---|
| **Flyout** (default for forms) | `variant="flyout"` | 3+ fields, rich content (RTE), multi-section panels, embedded lists / role grids, anything that benefits from a tall scroll area |
| **Modal** | `max-width="md"` (omit `variant`) | 1–2 simple fields, quick single-purpose edits (e.g. tag name + slug) |

Flyout (wide side panel, the default for non-trivial forms):

```blade
<x-form-modal
    name="banner-form"
    :heading="$editingUuid ? __('Edit Banner') : __('New Banner')"
    wire:model="showForm"
    variant="flyout"
>
    @if ($showForm)
        <livewire:admin.banners.form :uuid="$editingUuid" :key="'banner-form-'.$formKey" />
    @endif
</x-form-modal>
```

Modal (compact, only for genuinely small forms):

```blade
<x-form-modal
    name="tag-form"
    :heading="$editingUuid ? __('Edit Tag') : __('New Tag')"
    wire:model="showForm"
    max-width="md"
>
    @if ($showForm)
        <livewire:admin.tags.form :uuid="$editingUuid" :key="'tag-form-'.$formKey" />
    @endif
</x-form-modal>
```

Standalone flyout (non-form content — detail panel, filters, preview):

```blade
<x-flyout name="user-detail" size="lg">
    @if ($selectedUuid)
        <livewire:users.detail :uuid="$selectedUuid" :key="'detail-'.$selectedUuid" />
    @endif
</x-flyout>
```

`<x-flyout>` accepts `size`: `sm` | `default` | `lg` | `xl`.

The parent Index component owns flyout/modal state with the same shape across the codebase:

```php
public bool $showForm = false;
public ?string $editingUuid = null;
public int $formKey = 0;   // bumped each open so the child component re-mounts cleanly

public function openCreate(): void { $this->editingUuid = null; $this->formKey++; $this->showForm = true; }
public function openEdit(string $uuid): void { /* authorize, set $editingUuid, bump $formKey, $showForm = true */ }

#[On('<resource>-form-saved')]
public function onFormSaved(): void { $this->showForm = false; $this->editingUuid = null; }
```

The child form dispatches `<resource>-form-saved` after `$this->validate()` + persist, and
the form view ends with a footer that includes `<flux:modal.close>` for Cancel and a primary
Save button.

> **Gotcha:** Don't add a `variant="default"` value — the component defaults to a modal when
> `variant` is omitted, and using `variant="default"` is treated identically. Either set
> `variant="flyout"` for flyout, or omit `variant` (and optionally set `max-width`) for modal.

> **Gotcha:** Always wrap the child `<livewire:...>` inside `@if ($showForm)` and pass a
> `:key="...$formKey"` that increments on each open. Without the guard + key, edits to one
> record bleed state into the next open.

### Page Container

The `x-layouts.app` layout already wraps page content in `<flux:main container>`, which
provides `max-w-7xl` + `mx-auto` + `p-6 lg:p-8`. **Render page content directly inside the
layout — do NOT re-wrap in another `max-w-7xl` / `px-*` div**, or you get doubled horizontal
padding (content too narrow).

```blade
{{-- DO: content sits directly under the layout --}}
<x-layouts.app title="Products">
    <x-breadcrumbs class="mb-6" />
    {{-- page content --}}
</x-layouts.app>

{{-- DON'T: an extra max-w-7xl/px-* wrapper double-pads against flux:main --}}
<x-layouts.app title="Products">
    <div class="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8"> ... </div>
</x-layouts.app>
```

### Page Header Pattern

All pages should follow this consistent header structure:

```blade
<x-breadcrumbs class="mb-6" />
<div class="flex items-end justify-between">
    <div>
        <flux:heading size="xl" level="1">Products</flux:heading>
        <flux:text class="mt-2">Manage your products.</flux:text>
    </div>
    <div class="flex items-center gap-2">
        {{-- Action buttons here --}}
    </div>
</div>
<flux:separator variant="subtle" class="my-6" />
```

### Breadcrumbs — derived from the menu (`<x-breadcrumbs>`)

**Never hand-write `<flux:breadcrumbs>` in a page.** Use the `<x-breadcrumbs>` component,
which derives the trail from the SAME menu tree that renders the sidebar
(`app/Actions/Builder/Menu/*` via `App\Actions\Builder\Breadcrumb`). This keeps breadcrumbs
and navigation in lock-step — e.g. a page registered under `Administration > Settings` in the
menu automatically gets `Dashboard > Administration > Settings > General` as its trail. The
trail always roots at Dashboard, and the **last crumb is the current page** (rendered without
a link). Group headings (url `#`) render as plain text.

Three usage forms cover every page:

```blade
{{-- 1. The page IS a menu leaf → fully automatic (matches the current route by URL) --}}
<x-breadcrumbs class="mb-6" />

{{-- 2. A detail page that is NOT a menu leaf → resolve its parent, append a leaf --}}
<x-breadcrumbs class="mb-6" for="admin.roles.index" leaf="Role Details" />

{{-- 3. A hub / non-menu page → give the trail explicitly (Dashboard auto-prepended) --}}
<x-breadcrumbs class="mb-6" :items="[['label' => __('Administration')]]" />
```

For a brand-new section, **add it to the menu builder first** (`Administration.php` etc.);
the breadcrumb then resolves automatically — no per-page breadcrumb markup needed. The
component injects no margin of its own, so pass `class="mb-6"` (or rely on a `gap-*` flex
wrapper) for spacing.

> **Gotcha:** The breadcrumb trail is matched by **URL** against the menu. If a leaf's route
> doesn't exist or its gate fails for the current user, the item is absent from the menu and
> `<x-breadcrumbs />` resolves to an empty trail (renders nothing). Pages that are hubs or
> not in any menu (e.g. the Administration index itself) must use the `:items` form.

> **Gotcha:** In a **full-page Livewire component** (`Route::livewire(...)` or
> `Route::get(..., Component::class)`), the breadcrumb lives inside the component root and is
> re-rendered on every Livewire update — at which point `request()->url()` is `/livewire/update`,
> not the page URL, so bare `<x-breadcrumbs />` (which uses `Breadcrumb::current()`) would
> resolve to nothing after the first interaction. Pin the route instead:
> `<x-breadcrumbs for="settings.mcp-tokens.show" />`. The `for`/`:items` forms don't depend on
> the request URL, so they're stable across wire updates. (Pages whose breadcrumb sits in the
> outer `x-layouts.app` blade — i.e. anything rendered via `Route::view`/a controller that only
> *embeds* Livewire with `@livewire(...)` — are unaffected and can use bare `<x-breadcrumbs />`.)

> **Gotcha:** **Vendor** full-page Livewire screens (config-backup, config-sso, config-webhook)
> render their own view, so you can't add `<x-breadcrumbs>` to it. Instead they render into a
> host layout set via config (`config-backup.route.layout`, `config-sso.admin.layout`,
> `config-webhook.ui.layout`), all pointed at `components.layouts.app-breadcrumbs` — a thin
> wrapper around `x-layouts.app` that injects `<x-breadcrumbs />`. The breadcrumb lives in the
> layout (rendered once on GET, not on wire updates), so `current()` matches the real page URL
> and the trail comes straight from the menu. To give a new vendor admin screen breadcrumbs,
> point its layout config at `components.layouts.app-breadcrumbs` and add the page to the menu.

### Mail — Always Queued

In Livewire components, **always use queued Mailables** instead of synchronous `Mail::send()`:

```php
// DO — queued, non-blocking
Mail::to($user)->queue(new OrderConfirmation($order));

// DON'T — synchronous, blocks Livewire's HTTP response
Mail::send('emails.order', $data, function ($message) { ... });
```

> **Gotcha:** `Mail::send()` is synchronous — it blocks until the SMTP server responds. In
> Livewire components this prevents redirects and UI updates from firing. Always use queued
> Mailables: `Mail::to(...)->queue(new MyMailable(...))`.

> **Gotcha:** `Mail::send()` cannot render `<x-mail::message>` Markdown mail components —
> it renders templates as regular Blade views, causing "No hint path defined for [mail]"
> error. Use proper Mailable classes with `->markdown()`, or use plain HTML Blade views.

## Important Conventions

### UI Requirements — MUST HAVE

- **Responsive**: All pages MUST be fully responsive (mobile, tablet, desktop). Use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`) consistently.
- **Dark mode**: All pages MUST support dark mode. Use `dark:` variants for all custom styling. Flux UI components handle this automatically — only add `dark:` for custom HTML/Tailwind elements.
- **Data tables — max 5 visible columns** (excluding actions). If a model has more than 5 displayable columns, combine related columns into a single column (e.g., "Name + Email" in one cell, "Created + Updated" in one cell). Never render wide, horizontally-scrolling tables.
- **Action buttons — always use 3-dot menu** (`...` / ellipsis / kebab menu). Never render inline action buttons (Edit, Delete, View) as separate buttons in table rows. Always group actions behind a `<flux:dropdown>` triggered by a 3-dot icon button.

```blade
{{-- Action column pattern (import icons first: php artisan flux:icon ellipsis eye pencil trash-2) --}}
<flux:dropdown>
    <flux:button variant="ghost" size="sm" icon="ellipsis" />
    <flux:menu>
        <flux:menu.item icon="eye" href="{{ route('products.show', $product) }}">View</flux:menu.item>
        <flux:menu.item icon="pencil" href="{{ route('products.edit', $product) }}">Edit</flux:menu.item>
        <flux:menu.item icon="trash-2" variant="danger" wire:click="delete({{ $product->id }})">Delete</flux:menu.item>
    </flux:menu>
</flux:dropdown>
```

### Icons — Lucide via Flux (NOT Heroicons)

This project uses **Lucide icons** imported via Flux's built-in command, NOT Heroicons. When you need an icon beyond Flux's bundled Heroicons, import from Lucide.

**Before using any icon**, confirm it exists in [Lucide's icon set](https://lucide.dev/icons) and import it:

```bash
# Import Lucide icons (no prefix needed — just the icon name)
php artisan flux:icon pencil trash-2 eye ellipsis plus
```

**Usage in Blade** (no `lucide-` prefix — use the plain icon name after import):

```blade
{{-- Flux components --}}
<flux:icon.crown />
<flux:button icon="pencil">Edit</flux:button>
<flux:button icon="ellipsis" variant="ghost" size="sm" />

{{-- Standalone via blade-lucide-icons package --}}
@svg('lucide-eye', 'w-4 h-4')
```

> **Gotcha:** Flux's `php artisan flux:icon` imports Lucide icons so they work with the **same syntax** as Heroicons — just `icon="pencil"`, NOT `icon="lucide-pencil"`. The `lucide-` prefix is only needed when using the `@svg()` Blade directive from `mallardduck/blade-lucide-icons`. If a Flux component renders a blank/missing icon, you likely forgot to run `php artisan flux:icon <name>`.

### DO

- Extend `App\Models\Base` for all models
- Use PHP attributes for model properties: `#[Fillable([...])]`, `#[Guarded([...])]`, `#[Hidden([...])]`
- Use dual-key pattern: auto-increment `id` (internal) + `uuid` column (public-facing, URLs, APIs)
- Use enums for status/type fields with `Enum` contract and `InteractsWithEnum` trait
- Use Pest syntax for tests
- Use policies for authorization
- Use Form Requests for validation
- Use `route()` helper for URLs
- Use queued Mailables (`Mail::to()->queue()`) in Livewire components
- Use `$this->dispatch('toast', ...)` for user feedback notifications
- Add `cursor-pointer` class to clickable buttons (TailwindCSS v4 default)
- Register new queue names in `config/horizon.php` supervisor queue list
- Import Lucide icons with `php artisan flux:icon <name>` before using them in Flux components
- Confirm icon exists in Lucide's icon set before importing
- Make all pages responsive (mobile-first with `sm:`, `md:`, `lg:` breakpoints)
- Support dark mode on all pages (use `dark:` variants for custom elements)
- Use 3-dot dropdown menu for row actions in data tables
- Combine columns when table has more than 5 data columns (excluding actions)
- Use **Deploy Operations** (`make:operation`) for one-off post-deploy data tasks — backfills, data fixes, third-party sync

### DON'T

- Extend `Illuminate\Database\Eloquent\Model` directly
- Use `protected $fillable`, `$guarded`, or `$hidden` properties — use PHP attributes instead
- Expose auto-increment `id` in URLs or APIs — use `uuid` for public-facing identifiers
- Use `url()` helper — use `route()` instead
- Use `dd()`, `dump()` in production code
- Use raw SQL queries — use Eloquent
- Use PHPUnit syntax — use Pest
- Write to `.env` at runtime — use Spatie Settings for admin-configurable values
- Expose `APP_ENV`, `APP_DEBUG`, or SMTP credentials in admin UI
- Use `Mail::send()` in Livewire — use queued Mailables instead
- Use `encrypt()` manually when model has `encrypted:array` cast (double-encryption)
- Render inline action buttons (Edit, Delete, View) in table rows — use 3-dot dropdown menu
- Create tables with more than 5 visible data columns — combine related columns instead
- Skip responsive design or dark mode support on any page
- Use Heroicon-specific names (e.g., `pencil-square`) — use Lucide equivalents (e.g., `pencil`) instead
- Use icons without importing them first via `php artisan flux:icon <name>`
- Use the `deploy-operations:*` command namespace — the correct prefix is `operations:*` (e.g., `operations:install`, NOT `deploy-operations:install`)
- Put one-off data backfills inside migrations — use a **Deploy Operation** instead

## Release Workflow

When asked to commit, push, tag, and release:

1. **Commit** the changes (do NOT update CHANGELOG.md — it is auto-generated by GitHub Actions)
2. **Push** to the remote branch
3. **Tag** with the next version. Determine next version by checking the latest tag with `git tag --sort=-v:refname | head -1`
4. **Push the tag** with `git push origin <tag>`
5. **Create a GitHub release** using `gh release create <tag> --title "<tag>" --notes "<release notes>"` with a concise summary of changes. Always include a **Full Changelog** compare link at the bottom of the release notes: `**Full Changelog**: https://github.com/<owner>/<repo>/compare/<previous-tag>...<new-tag>`

## Code Quality Checklist

Before committing:

- [ ] Models extend `App\Models\Base`
- [ ] Status fields use enums
- [ ] Tests use Pest syntax
- [ ] `composer format` passes
- [ ] `composer analyse` passes
- [ ] `composer test` passes

## Packages

### Core

- **spatie/laravel-permission**: Roles and permissions
- **spatie/laravel-settings**: Application settings stored in database
- **spatie/laravel-sitemap**: Sitemap generation (`seo:generate-sitemap` + on-the-fly `/sitemap.xml`)
- **spatie/laravel-medialibrary**: File/media management
- **owen-it/laravel-auditing**: Audit trail
- **cleaniquecoders/traitify**: Common traits and contracts
- **dragon-code/laravel-deploy-operations**: One-off post-deploy tasks (backfills, data fixes) — `operations:*` namespace

### Development

- **laravel/telescope**: Debugging (access via /telescope)
- **laravel/horizon**: Queue monitoring (access via /horizon)
- **barryvdh/laravel-debugbar**: Debug toolbar
- **laravel/doctor**: First-party diagnostics — `php artisan doctor` runs health checks (`--fix` auto-repairs, `--format=github` for CI); scaffold custom checks with `php artisan make:diagnostic`

### Frontend

- **livewire/livewire**: Reactive components
- **livewire/flux**: UI components
- **mallardduck/blade-lucide-icons**: Icons via `@svg('lucide-icon-name')`

## Docker Services

The project includes a `docker-compose.yml` with the following services:

| Service     | Port(s)        | Description              |
| ----------- | -------------- | ------------------------ |
| MySQL       | 3306           | Database server          |
| Redis       | 6379           | Cache & session store    |
| Mailpit     | 1025, 8025     | Mail testing (SMTP + UI) |
| Meilisearch | 7700           | Full-text search engine  |
| MinIO       | 9000, 9001     | S3-compatible storage    |

```bash
# Start all services
docker compose up -d

# Stop all services
docker compose down

# View logs
docker compose logs -f
```

Access points:
- **Mailpit UI**: http://localhost:8025
- **MinIO Console**: http://localhost:9001
- **Meilisearch**: http://localhost:7700

## Environment Variables

Key variables in `.env`:

```env
# Superadmin (seeded on fresh install)
SUPERADMIN_NAME="Admin"
SUPERADMIN_EMAIL="admin@example.com"
SUPERADMIN_PASSWORD=CHANGE_ME_BEFORE_DEPLOY

# Features
ACCESS_CONTROL_ENABLED=true
TELESCOPE_ENABLED=true   # exception watcher only; dashboard gated to local/staging

# Security
SESSION_ENCRYPT=true
PASSWORD_MIN_LENGTH=12
AUDIT_CONSOLE=true
BACKUP_RETENTION_DAYS=30

# Docker Services
DB_ROOT_PASSWORD=CHANGE_ME_BEFORE_DEPLOY
MAILPIT_UI_PORT=8025
MEILI_MASTER_KEY=CHANGE_ME_BEFORE_DEPLOY
MINIO_ROOT_USER=CHANGE_ME_BEFORE_DEPLOY
MINIO_ROOT_PASSWORD=CHANGE_ME_BEFORE_DEPLOY
```

## Security & SOC 2 Compliance

This project includes SOC 2-aligned security controls. See `docs/05-security/soc2-compliance.md` for full details.

### Key Security Features
- **Security Headers**: Global middleware (HSTS, X-Frame-Options, CSP)
- **Rate Limiting**: Applied to all auth, admin, and security routes
- **Password Policy**: Configurable via `config/security.php` (min 12 chars, mixed case, numbers, symbols)
- **2FA**: Fortify two-factor authentication with confirmation
- **Audit Trail**: Immutable audit records on all models, including console commands
- **PII Protection**: `EncryptsPii` trait for field-level encryption, `RedactsPiiInAudit` for audit masking
- **Backup Encryption**: Optional GPG encryption on all backup scripts with retention policy
- **Deployment Safety**: Maintenance mode, health check, auto-rollback on failure

### Security Conventions
- Never commit real credentials — use `CHANGE_ME_BEFORE_DEPLOY` placeholders
- Use `EncryptsPii` for sensitive fields (but NOT fields used in WHERE clauses)
- Use `RedactsPiiInAudit` on models with PII to mask audit trail values
- Schedule `data:purge` for retention compliance
- Run `composer audit` regularly for dependency vulnerabilities

## Quick Reference

```bash
# Generate with proper stubs
php artisan make:model Product           # Extends Base automatically
php artisan make:policy ProductPolicy --model=Product
php artisan make:test ProductTest --pest

# Deployment
bin/deploy -b main                       # Deploy specific branch
bin/backup-app                           # Backup application + database
bin/backup-db                            # Database backup only
bin/backup-media                         # Media files backup

# Data Retention
php artisan data:purge --dry-run         # Preview what would be purged
php artisan data:purge                   # Purge expired data

# Deploy Operations (post-deploy data tasks)
php artisan make:operation <name>        # Scaffold a new operation
php artisan operations                   # Run pending operations
php artisan operations:status            # Show ran/pending operations
```

## Gotchas

### Laravel Boost

> **Gotcha:** `boost:install` requires interactive input for third-party package selection.
> If Boost was not fully configured during project setup, run `php artisan boost:install`
> manually to select AI guidelines, skills, and MCP server configuration.

### Laravel 13

> **Gotcha:** Laravel 13 uses **PHP attributes** for model properties (`#[Fillable([...])]`,
> `#[Guarded([...])]`, `#[Hidden([...])]`) instead of `protected $fillable`, `$guarded`, `$hidden`.
> Always use the attribute syntax for new models. Import from `Illuminate\Database\Eloquent\Attributes`.

> **Gotcha:** CSRF middleware was renamed from `VerifyCsrfToken` to `PreventRequestForgery` in
> Laravel 13. If you customize CSRF behavior, use the new class name.

> **Gotcha:** Cache serialization defaults to `serializable_classes: false` in Laravel 13.
> If you need to cache PHP objects (not just strings/arrays), explicitly set
> `'serializable_classes' => true` in `config/cache.php`.

### Livewire 4

> **Gotcha:** Livewire 4 does not support the `rules()` method for dynamic validation.
> Calling `$this->validate()` without rules throws `MissingRulesException`.
> Always pass rules inline: `$this->validate($rules)`.

> **Gotcha:** `<script>` tags inside Livewire components don't re-execute on `wire:navigate`.
> For Alpine.js components, use inline `x-data="{...}"` objects instead of `Alpine.data()`
> registered via `document.addEventListener('alpine:init', ...)` in a `<script>` block.

> **Gotcha:** Livewire 4's `addNamespace()` takes precedence over `component()` for namespaced
> components (those with `::`). The `Finder::resolveClassComponentClassName()` checks
> `classNamespaces` first and never falls through to `classComponents`.

### Flux UI

> **Gotcha:** Flux UI's `description` prop on `<flux:input>` renders the text **above** the
> input, between label and field, which breaks left/right alignment. Use
> **`description:trailing`** instead — it renders below the input, which is what you want
> nearly always. In a multi-column grid row, don't put a description inside a cell at all:
> the taller cell stretches its neighbour. Render the help as a full-width
> `<p class="text-sm text-zinc-500 dark:text-zinc-400">` below the row.

> **Gotcha:** **Flux renders `<ui-checkbox>`, not `<input type="checkbox">`** — a custom
> element carrying `data-flux-checkbox` and `role="checkbox"`. Any JavaScript that counts or
> queries checkboxes with `input[type=checkbox]` matches **zero elements** and reports a
> confident, wrong answer forever; `:checked` does not apply either, though the element does
> expose a `.checked` property. Match `[data-flux-checkbox], input[type=checkbox]` and read
> `.checked` — and **pin the marker in a test**, so a Flux upgrade fails CI rather than
> silently returning your count to zero.

> **Gotcha:** `flux:tab.group` / `flux:tabs` is **Flux Pro only** — not available in the free
> version. Use Alpine.js `x-data`/`x-show` for tabs instead, with `cursor-pointer`, hover/active
> states, and URL deep linking via `window.history.replaceState`.

> **Gotcha:** `@json()` Blade directive inside HTML attributes causes parse errors due to
> bracket conflicts. Use `{!! json_encode(...) !!}` instead when outputting JSON in attributes.

### TailwindCSS v4

> **Gotcha:** TailwindCSS v4 does not add `cursor: pointer` to `<button>` elements by
> default. Always add `cursor-pointer` class to clickable buttons explicitly.

### Alpine.js

> **Gotcha:** **`x-cloak` does nothing without a CSS rule.** It is only an attribute Alpine
> *removes* on init; the hiding is entirely `[x-cloak] { display: none !important; }`, which
> lives in `resources/css/app.css`. Without it every `x-show="false"` element renders
> **visible on first paint** and disappears a moment later — 2FA challenges, tab panels and
> disclosure bodies all flashing their hidden state. Nothing errors, so no test catches it.
> Do not remove that rule.

> **Gotcha:** **A double quote anywhere inside an `x-data` (or any Alpine) attribute ends the
> attribute.** Blade does not escape what you write there, so a comment containing
> `role="checkbox"` truncates the expression mid-way, leaves a stray `checkbox"` attribute on
> the element, and un-Alpines the whole subtree — with **no console error**, just a panel that
> never reacts. Keep Alpine attributes free of double quotes entirely (single quotes for JS
> strings; put `{{-- --}}` Blade comments *outside* the tag for anything that needs prose), and
> prefer `/* */` over `//` inside multi-line attributes, since a line comment swallows the rest
> if the newlines are ever collapsed.

> **Gotcha:** **A Livewire assertion proves the server rendered a string, never that the
> browser does anything with it.** `assertSee` passes just as happily for markup whose Alpine
> expression is broken, whose selector matches nothing, or whose `x-cloak` is inert — all three
> of the gotchas above shipped green suites and were found only by driving the real page.
> Anything whose behaviour lives in Alpine or in a Flux-rendered element needs a browser
> **once**, and then the markup contract it depends on pinned in a test. Related: `wire:model`
> is **deferred**, so any badge or counter derived from it is a round trip behind what the
> operator can see — compute it client-side, and seed the initial value from the server so
> first paint is right.

### User Suspension vs. Soft Delete

> **Gotcha:** Users have TWO independent "inactive" states: `suspended_at` (sign-in blocked,
> still visible to admins, enforced by `EnsureUserIsNotSuspended` middleware) and `deleted_at`
> (soft-deleted, hidden). Never overload soft deletes to mean suspension. Status display is
> derived via `User::status()` returning the `UserStatus` enum — do not store a status column.

### Cookies Written by JavaScript

> **Gotcha:** Laravel encrypts cookies by default, so a cookie written by JavaScript
> (e.g. the sidebar's `sidebar_collapsed` toggle state) comes back as `null` from
> `request()->cookie()` unless excluded:
> `$middleware->encryptCookies(except: ['cookie_name'])` in `bootstrap/app.php`.
> Prefer a plain cookie over localStorage when Blade needs the value server-side
> (e.g. to render UI state under `wire:navigate` without flicker).

### Forms & Grid Layout

> **Gotcha:** When adding fields to a 2-column `sm:grid-cols-2` form, always maintain proper
> left-right pairing. An odd field inserted in the middle shifts all subsequent fields and
> breaks visual alignment. Place new fields to preserve existing pairs.

### Rate Limiting in Tests

> **Gotcha:** `$middleware->throttleWithRedis()` makes throttling talk straight to Redis,
> bypassing the `CACHE_STORE=array` override in `phpunit.xml` — rate-limit state then leaks
> across test runs and even from the dev server, causing intermittent 429s (TIA mode makes
> this visible fast because it re-runs the same tests in tight loops). `bootstrap/app.php`
> therefore only enables Redis throttling outside the `testing` environment, reading
> `$_SERVER['APP_ENV']` directly — the middleware callback runs before the container's env
> binding exists, and `env()` is reserved for `config/` by the architecture tests. Keep that
> guard when touching middleware config.

### Horizon & Queues

> **Gotcha:** When adding new queue names (e.g., `backups`, `webhooks`), they must be
> registered in `config/horizon.php` supervisor queue list — otherwise Horizon won't pick
> up jobs dispatched to those queues. Also ensure supervisor `timeout` >= job `$timeout`.

### Deploy Operations

> **Gotcha:** `dragon-code/laravel-deploy-operations` exposes its artisan commands under the
> `operations:*` namespace, NOT `deploy-operations:*`. The correct commands are
> `operations`, `operations:install`, `operations:status`, `operations:rollback`,
> `operations:fresh`, and `make:operation` (not `make:deploy-operation`). The tracking
> table is `operations`, not `deploy_operations`. Using the `deploy-operations:*` prefix
> will fail with *"There are no commands defined in the 'deploy-operations' namespace."*

> **Gotcha:** Deploy operations should be **idempotent where possible**. Even though each
> operation runs once per environment, a failed run mid-execution can leave partial state.
> Wrap multi-step changes in transactions or guard with existence checks.

> **Gotcha:** **A deploy operation is not a console command.**
> `DragonCode\LaravelDeployOperations\Operation` has no `line()`, `info()` or `$this->command`,
> so a progress message inside one throws — **after** the work it was reporting has already
> been done. The operation's effects land, the command reports failure, and `bin/deploy` then
> correctly stops with the application left in **maintenance mode**: production serves 503 over
> a change that actually succeeded. It hides on a re-run too, because by then the loop has
> nothing left to process and the throwing line is never reached. Keep operations silent. And
> note the related rule: `bin/deploy` leaves maintenance mode **on** when an operation fails,
> deliberately — a half-applied release must not go live — so a failed deploy needs
> `php artisan up` after the fix.

### Settings vs `.env`

> **Gotcha:** **`.env` is not the source of truth for mail — `App\Settings\MailSettings` is.**
> The DB-backed settings overlay `config('mail.*')` at boot, so a host with a perfectly correct
> `MAIL_MAILER=smtp` block still resolves to whatever the settings row says. After
> `migrate:fresh` that row is the seeded default, `log` — and `app:test-send-mail` then
> **exits 0 and records a row in `mail_histories` while writing the message to
> `storage/logs`**. Nothing distinguishes that from a delivered email; the only reliable check
> is `config('mail.default')`, never `env('MAIL_MAILER')`. The same applies to every other
> `app/Settings/*` group (SEO, general, notifications). Fix mail through Admin > Settings >
> Mail or by saving `MailSettings`, and keep `.env` in step so the two never disagree.

> **Gotcha:** Some hosts block outbound SMTP on ports 25, 465 and 587 (DigitalOcean does, on
> every droplet), so a correctly configured relay fails with *"Connection could not be
> established … Connection timed out"* there and works everywhere else. SparkPost, Mailgun and
> SendGrid all publish **2525** for exactly this reason — use it. This is a network-level
> block, not a firewall rule you can open with `ufw`.

### Seeders

> **Gotcha:** **`db:seed` wraps seeding in `Model::unguarded()`, so a seeder can mass-assign a
> column that is not `#[Fillable]` — and only there.** `$user->update(['email_verified_at' =>
> now()])` works through the artisan command and silently drops the column when the same seeder
> is instantiated directly from a test. Never let seeder logic lean on ambient unguarded state:
> write the non-fillable column through `forceFill()` or the model's own method
> (`markEmailAsVerified()`), and instantiate the seeder directly in its test so the difference
> cannot hide.

> **Gotcha:** **A production confirmation prompt with no TTY is a silent no-op.** `db:seed`
> called without `--force` prints "APPLICATION IN PRODUCTION", cancels, and **exits 0**. Run
> after `migrate:fresh` that leaves a migrated but unseeded database — no roles, no superadmin,
> no way to log in — and a caller that believes it succeeded. `seed:prepare` forwards `--force`
> unconditionally because it is the production install path; `seed:dev` / `seed:demo` take an
> opt-in `--force`. Any command that may run unattended in production must forward it.

> **Gotcha:** **A seeder that mixes catalogue data with tenancy cannot be run for either half
> alone.** One seeder, one layer, runnable on its own — and nothing in the `PrepareSeeder` path
> that a production operator would have to delete afterwards. Demo deployments, sample orgs and
> dashboard fodder belong in `seed:dev` / `seed:demo`.

> **Gotcha:** **Never seed from `beforeEach`.** A seeder whose output is identical for every
> test belongs in `protected $seeder = MySeeder::class;` on `Tests\TestCase`, where
> `RefreshDatabase` runs it once per process as part of `migrate:fresh`. Because every test
> still executes inside a transaction that rolls back, the visible state is **identical** either
> way — the per-test call buys nothing and can cost half the suite's wall clock.

### Models & Traitify

> **Gotcha:** Traitify's `InteractsWithUser` (on `App\Models\Base`) auto-fills any column
> literally named `user_id` with the authenticated user on create. That is right when `user_id`
> means "who made this row", but wrong when it is a **scope** column — on an org-scoped table it
> would silently turn every organisation-wide row into a personal one. Disable it on such models
> with `protected $user_id_column = '<non-existent column>';` (the trait's `Schema::hasColumn()`
> check then short-circuits).

> **Gotcha:** **An undefined Eloquent relation resolves to `null`, it does not error.** A guard
> written against a misnamed relation (`$model->user` where the relation is `owner()`) silently
> passes everything, and PHPStan cannot see it because dynamic model properties are `mixed`. The
> same applies to a misspelled attribute. Whenever a guard's whole job is to say "no", write a
> test that proves it says no: a guard that never fires is indistinguishable from one that never
> runs.

### Static Analysis (Larastan)

> **Gotcha:** **A class docblock must sit above the PHP attributes, not between them and the
> class.** `#[Fillable([...])]` followed by `/** @property … */` followed by `class Foo` parses
> fine and the annotations are **silently ignored** — PHPStan carries on inferring `string` for
> every cast column, and the errors it then reports point at the *call sites*, not at the model.

> **Gotcha:** **Larastan cannot see casts declared through the `casts()` method**, only the
> `$casts` property — so an array-cast column with no `@property` annotation is inferred from the
> column type as `?string`, and `(array) $model->some_json_column` reads as a one-element list
> where every offset is "non-existent". Annotate any array-cast column before reading keys off it.

> **Gotcha:** Adding a generic annotation (`@return BelongsTo<Foo, $this>`) to a widely-used
> relation improves inference *at every call site*, which can invalidate `phpstan-baseline.neon`
> entries elsewhere and fail `composer analyse` with `ignore.unmatched`. Prefer annotating a
> relation only your new code uses — or regenerate the baseline deliberately. The converse trap
> is real too: leaving a cast un-annotated to avoid baseline churn makes PHPStan read an enum
> column as `string` and report every correct `=== Status::Active` as always-false. An annotation
> that makes correct code look broken is not a saving.

### Authorization & Tenancy

> **Gotcha:** **A capability permission is not a tenancy scope, and `App\Policies\*` does not
> supply one either.** There are **no global scopes** in the baseline — `create()` on a policy is
> a bare `$user->can('resource.create.item')` with no organisation check — so every list and
> every lookup has to scope itself. Passing the policy proves a user may do the *kind* of thing,
> never that they may do it to *this row*. Route every lookup through one scoped finder so
> ownership cannot be remembered at five call sites and forgotten at the sixth, and **never
> resolve a client-supplied uuid with a bare `where('uuid', …)`**.

> **Gotcha:** **`is_default` (and any "exactly one row carries this flag" rule) is per-tenant, so
> the reset must be too.** `Model::whereKeyNot($id)->update(['is_default' => false])` reads as the
> obvious singleton guard and is a cross-tenant write: one tenant saving a default silently clears
> every other organisation's choice. Any uniqueness rule stated as "only one row may carry this
> flag" needs the scope it is unique *within* written into the query.

> **Gotcha:** **A surface authenticating on a non-default guard must pin the guard it checks
> permissions against.** Browser routes run on `web`, but an API or MCP surface authenticating on
> `sanctum` (or Passport) gets a bare `$user->can(...)` evaluated under *that* guard, where the
> user has no permissions — so everything denies, superadmin included, and the failure looks like
> a misconfigured role rather than a guard mismatch. Use
> `$user->hasPermissionTo($ability, 'web')` and fail closed on an unknown permission.

> **Gotcha:** An audited **denial** must be written **outside** the transaction that performs the
> check. Throwing from inside rolls the audit record back along with the (empty) write set,
> losing the evidence exactly when it matters.

### Database Portability

> **Gotcha:** **MySQL needs an index whose *leading* column backs each foreign key.** Dropping a
> unique before creating its replacement fails with errno 1553 — while PostgreSQL and SQLite
> accept either order. Always **create the replacement index first, then drop the old one** (and
> reverse it in `down()`). Note it is about the leading column, not about an index merely
> existing: if the FK column is not leading anywhere, it needs a plain index of its own.

> **Gotcha:** **MySQL and Oracle have no transactional DDL.** A migration that fails halfway
> leaves the table half-changed *and* unrecorded, so the next `migrate` reports a confusing
> "Duplicate column" instead of the real error. Guard multi-step migrations with
> `Schema::hasColumn()` so a partially-applied database recovers on re-run instead of needing
> manual repair.

> **Gotcha:** **`Schema::hasIndex()` can return false mid-migration for an index that plainly
> exists**, silently skipping the `dropUnique()` guarded by it — the swap reports DONE and the old
> index survives. Read `Schema::getIndexes($table)` and match the name yourself
> (case-insensitively; the drivers disagree on casing).

> **Gotcha:** **`down()` hits errno 1553 where `up()` does not.** A composite unique leading with
> a foreign-key column becomes the only index backing that constraint, so MySQL refuses to drop it
> while the FK stands — drop the foreign key first, then the index, then the column. Always run
> `migrate` → `rollback` → `migrate` **against MySQL**: tests run on SQLite in-memory, the most
> permissive engine of the lot, and it rebuilds the whole table on ALTER. A green suite is not
> evidence a migration is portable.

> **Gotcha:** `dropConstrainedForeignId()` guesses the *conventional* constraint name
> (`{table}_{column}_foreign`). A migration that named its FK explicitly via
> `constrained(indexName: '…')` must drop it by that name, or MySQL fails with errno 1091.

### Passkeys

> **Gotcha:** **Rotating `APP_KEY` invalidates every registered passkey.**
> `config/passkeys.php` derives `user_handle_secret` from `config('app.key')`, and the WebAuthn
> user handle is what binds a credential to an account — change the key and every passkey on file
> stops resolving to its user, with no error that says so. Set `PASSKEYS_USER_HANDLE_SECRET`
> explicitly (it is in `.env.example`) before any key rotation.

### BackedEnum

> **Gotcha:** `BackedEnum` objects cannot be cast to string with `(string)`. Use
> `$value instanceof \BackedEnum ? $value->value : $value` when normalizing model
> attributes for comparison (e.g., snapshot diffs, array comparisons).

### Secure Media (cleaniquecoders/laravel-media-secure)

All private-disk media is served through this package via `secure_media_url()`
(`support/media.php`). The published `config/laravel-media-secure.php` **middleware**
stack must contain all three, in order:

```php
'middleware' => [
    'web',                    // StartSession — without it the session cookie is
                              // never read, so auth:sanctum can't see the logged-in
                              // user and embedded <img> requests redirect to /login
    'auth:sanctum',
    ValidateMediaAccess::class, // mandatory: resolves media by uuid, runs the policy,
                              // attaches media to the request (else controller aborts 422)
],
```

> **Gotcha:** The package registers its route with `->hasRoute('web')` which uses
> `loadRoutesFrom` — this does **not** apply Laravel's `web` middleware group. You must
> add `'web'` explicitly in the config middleware. Symptom of a missing `web`: a logged-in
> user sees broken `<img>` thumbnails and `GET /media/view/{uuid}` returns `302 → /login`
> even with a valid session cookie. Verify with `php artisan route:list --path=media` — the
> `media/{type}/{uuid}` route must list `web` first.

> **Gotcha:** `actingAs()` in tests sets the user directly on the guard and bypasses
> session middleware, so a feature test using `actingAs()` will **pass even when `web` is
> missing** from the route. To catch session/middleware regressions, verify with a real
> login flow (cookie jar) against the running server, not just `actingAs()`.

> **Gotcha:** Strict mode (`LARAVEL_MEDIA_SECURE_STRICT=true`, the default) delegates
> authorization to the owning model's policy. For `view` URLs the model policy needs a
> `view` method; `stream`/`download` URLs need matching `stream`/`download` methods —
> a missing method means a 403. Any model whose media is served via `secure_media_url()`
> must expose all three.

---

## Claude Self-Update Practice — CRITICAL

This file is a **living document**. Claude must update `CLAUDE.md` whenever:

1. **User corrects a mistake** — e.g., "jangan guna MySQL, kita pakai PostgreSQL"
2. **User expresses a preference** — e.g., "aku tak suka pattern ni, guna cara lain"
3. **A better pattern is discovered** during implementation
4. **A gotcha or edge case is found** that could cause future mistakes

### How to Update

When a correction or preference is identified:

1. Apply the fix to the current task
2. Immediately update the relevant section in `CLAUDE.md` to reflect the new rule
3. If it's a DO/DON'T, add it to the **DO / DON'T** section
4. If it's architectural, update the relevant architecture section
5. If it's a new gotcha, add it under the relevant section with a `> **Gotcha:**` callout

### Format for Gotchas

```markdown
> **Gotcha:** PostgreSQL `uuid-ossp` extension must be enabled before using
> `DB::raw('uuid_generate_v4()')`. Prefer letting Laravel handle UUID generation
> from PHP side via `InteractsWithUuid` trait instead.
```

### What NOT to Record

- One-off task-specific decisions that don't affect future work
- Things already covered by Laravel or package documentation
- Preferences that are already obvious from existing conventions

> **Rule**: When in doubt — record it. A slightly redundant note is better than repeating a mistake.

## Claude Operating Principles

### 1. Plan Mode Default

- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
- If something goes sideways, STOP and re-plan immediately — don't keep pushing
- Use plan mode for verification steps, not just building
- Write detailed specs upfront to reduce ambiguity

### 2. Subagent Strategy

- Use subagents liberally to keep main context window clean
- Offload research, exploration, and parallel analysis to subagents
- For complex problems, throw more compute at it via subagents
- One task per subagent for focused execution
- Only parallelize truly independent queries — avoid redundant searches

### 3. Self-Improvement Loop

- After ANY correction from the user: record the pattern in `CLAUDE.md` (gotcha / preference /
  DO-DON'T) — never in a local `tasks/lessons.md`
- Write rules for yourself that prevent the same mistake
- Ruthlessly iterate on these lessons until mistake rate drops
- Review `CLAUDE.md` at session start for relevant project

### 4. Verification Before Done

- Never mark a task complete without proving it works
- Diff behavior between main and your changes when relevant
- Ask yourself: "Would a staff engineer approve this?"
- Run tests, check logs, demonstrate correctness

### 5. Demand Elegance (Balanced)

- For non-trivial changes: pause and ask "is there a more elegant way?"
- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
- Skip this for simple, obvious fixes — don't over-engineer
- Challenge your own work before presenting it

### 6. Autonomous Bug Fixing

- When given a bug report: just fix it. Don't ask for hand-holding
- Point at logs, errors, failing tests — then resolve them
- Zero context switching required from the user
- Go fix failing CI tests without being told how

### Task Management

**All task tracking lives on GitHub.** Do NOT create local tracking files — no `tasks/todo.md`,
no `tasks/lessons.md`, no `tasks/` directory in the repository at all.

1. **Plan First**: Create a GitHub issue with a `- [ ]` task checklist in the body
   (`gh issue create`)
2. **Verify Plan**: Check in before starting implementation
3. **Track Progress**: Tick checklist items with `gh issue edit` as you go
4. **Explain Changes**: High-level summary at each step
5. **Document Results**: Comment the result/review on the issue, then close it
6. **Capture Lessons**: Record corrections in `CLAUDE.md` (gotchas / preferences), not in a
   local file

Reference the issue in commit messages and PRs. Scale process to task size — simple fixes skip
steps 1–2.

> **Gotcha:** A lesson recorded in a local file is a lesson only this checkout has. `CLAUDE.md`
> is read at the start of every session in every clone; `tasks/lessons.md` is read by nobody.
> The same applies to plans: an issue is visible to the team and survives a fresh clone.

### Core Principles

- **Simplicity First**: Make every change as simple as possible. Impact minimal code.
- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
- **Match Effort to Impact**: Don't refactor surrounding code unless asked.