TenantAtlas/GEMINI.md

# TenantPilot - Agent Guidelines

## Context
TenantPilot is an Intune Management application built with **Laravel** and **Filament**.
It re-implements and extends key features inspired by the IntuneManagement project,
with a focus on admin productivity, safe change management, and auditability.

This repo uses GitHub Spec Kit.
Primary spec artifacts live in `.specify/`.

**Sail-first for local development. Dokploy-first for staging/production.**

## Product Goals
- Provide **Intune policy version control** (diff, history, rollback).
- Enable reliable **backup and restore** of Intune configurations.
- Extend Intune with **admin-focused features** that improve visibility, safety, and velocity.
- Prioritize **auditability**, **least privilege**, and predictable operations.

## Scope Reference
When designing or implementing features, align with:
- Policy inventory & metadata normalization
- Change tracking and version snapshots
- Safe restore flows (dry-run, validation, partial restore)
- Reporting, dashboards, and operational insights
- Tenant-scoped RBAC and audit logs

## Workflow (Spec Kit)
1. Read `.specify/constitution.md`
2. For new work: create/update `specs/<NNN>-<slug>/spec.md`
3. Produce `specs/<NNN>-<slug>/plan.md`
4. Break into `specs/<NNN>-<slug>/tasks.md`
5. Implement changes in small PRs

If requirements change during implementation, update spec/plan before continuing.

## Architecture Assumptions
- Backend: Laravel (latest stable)
- Admin UI: Filament
- Auth: Microsoft identity integration (Entra ID/Azure AD) when applicable
- External API: Microsoft Graph for Intune

Do not assume additional services unless stated in spec.

---

## DevOps & Environments

### Local Development
- Local dev & testing use **Laravel Sail** (Docker).
- Prefer Sail commands when referencing setup or running tests.
- PostgreSQL is used locally via Sail.
- **Drizzle** is used locally for PostgreSQL tooling (e.g., schema inspection, dev workflows)
  **if configured in the repo**.

### Repository
- Repository is hosted on **Gitea**.
- Do not assume GitHub-specific features (Actions, GH-specific PR automation)
  unless explicitly added.
- CI suggestions should be compatible with Gitea pipelines or external CI runners.

### Deployment
- Deployed via **Dokploy** on a **VPS**.
- Two environments:
  - **Staging**
  - **Production**
- Assume container-based deployments.
- Changes that affect runtime must consider:
  - environment variables
  - database migrations
  - queue/cron workers
  - storage persistence/volumes
  - reverse proxy/SSL likely handled by Dokploy

### Release & Promotion Rules
- Staging is the mandatory validation gate for Production.
- Prefer:
  - feature flags for risky admin operations
  - staged rollout for backup/restore/versioning changes
- Schema changes must be validated on Staging before Production.

### Release Safety
- For schema changes:
  - provide safe, incremental migrations
  - avoid long locks
  - document rollback/forward steps
- For Intune-critical flows:
  - prefer dry-run/preview
  - require explicit confirmation
  - ensure audit logs

---

## Data Layer
- Database: **PostgreSQL**
- Prefer **JSONB** to store raw Graph policy snapshots and backup payloads.
- Add appropriate indexes (e.g., **GIN** on JSONB where search/filter is expected).
- Migrations must be reversible where possible.

## Versioning Storage Strategy
- Store **immutable** policy snapshots.
- Track metadata separately (tenant, policy type, platform, created_by, created_at).
- Prefer **full snapshots first** for correctness and simplicity.
- Consider retention policies to prevent unbounded growth.

---

## Engineering Rules
- PHP: follow PSR-12 conventions.
- Prefer Laravel best practices (Service classes, Jobs, Events, Policies).
- Keep Microsoft Graph integration isolated behind a dedicated abstraction layer.
- Use dependency injection and clear interfaces for Graph clients.
- No breaking changes to data structures or API contracts without updating:
  - `specs/<NNN>-<slug>/spec.md`
  - migration notes
  - upgrade steps
- If a TypeScript/JS tooling package exists, use strict typing rules there too.

## Intune Data & Safety Rules
- Treat Intune resources as **critical configuration**.
- Every destructive action must support:
  - explicit confirmation UI
  - audit log entry
  - optional dry-run/preview mode if feasible
- Restore must be defensive:
  - validate inputs
  - detect conflicts
  - allow selective restore
  - show a clear pre-execution summary

## Version Control Semantics
- A "version" should be reproducible and queryable:
  - what changed
  - when
  - by whom
  - source tenant/environment
- Provide diff outputs where possible:
  - human-readable summary
  - structured diff (JSON)

## Observability & Audit
- Log Graph calls at a high-level (no secrets).
- Maintain an audit trail for:
  - backups created
  - restores executed/attempted
  - policy changes detected/imported
- Ensure logs are tenant-scoped and RBAC-respecting.

## Security
- Enforce least privilege.
- Never store secrets in config or code.
- Use Laravel encrypted storage or secure secret management where applicable.
- Validate all tenant identifiers and Graph scopes.

---

## Commands

### Sail (preferred locally)
- `./vendor/bin/sail up -d`
- `./vendor/bin/sail down`
- `./vendor/bin/sail composer install`
- `./vendor/bin/sail artisan migrate`
- `./vendor/bin/sail artisan test`
- `./vendor/bin/sail artisan` (general)

### Drizzle (local DB tooling, if configured)
- Use only for local/dev workflows.
- Prefer running via package scripts, e.g.:
  - `pnpm drizzle:generate`
  - `pnpm drizzle:migrate`
  - `pnpm drizzle:studio`

(Agents should confirm the exact script names in `package.json` before suggesting them.)

### Non-Docker fallback (only if needed)
- `composer install`
- `php artisan serve`
- `php artisan migrate`
- `php artisan test`

### Frontend/assets/tooling (if present)
- `pnpm install`
- `pnpm dev`
- `pnpm test`
- `pnpm lint`

---

## Where to look first
- `.specify/`
- `AGENTS.md`
- `README.md`
- `app/`
- `database/`
- `routes/`
- `resources/`
- `config/`

---

## Definition of Done
- Spec + Plan + Tasks aligned with implementation.
- Tests added/updated.
- UI includes clear admin-safe affordances for backup/restore/versioning.
- Audit logging implemented for sensitive flows.
- Documentation updated (README or in-app help).
- Deployment impact assessed for:
  - Staging
  - Production
  - migrations, env vars, queues

---

## AI Usage Note
All AI agents must read:
- `AGENTS.md`
- `.specify/*`

before proposing or implementing changes.

## Reference Materials
- PowerShell scripts from IntuneManagement are stored under `/references/IntuneManagement-master`
  for implementation guidance only.
- They must not be treated as production runtime dependencies.

===

<laravel-boost-guidelines>
=== .ai/filament-v5-blueprint rules ===

## Source of Truth
If any Filament behavior is uncertain, lookup the exact section in:
- docs/research/filament-v5-notes.md
and prefer that over guesses.

# SECTION B — FILAMENT V5 BLUEPRINT (EXECUTABLE RULES)

# Filament Blueprint (v5)

## 1) Non-negotiables
- Filament v5 requires Livewire v4.0+.
- Laravel 11+: register panel providers in `bootstrap/providers.php` (never `bootstrap/app.php`).
- Global search hard rule: If a Resource should appear in Global Search, it must have an Edit or View page; otherwise it will return no results.
- Destructive actions must execute via `Action::make(...)->action(...)` and include `->requiresConfirmation()` (no exceptions).
- Prefer render hooks + CSS hook classes over publishing Filament internal views.

Sources:
- https://filamentphp.com/docs/5.x/upgrade-guide
- https://filamentphp.com/docs/5.x/panel-configuration
- https://filamentphp.com/docs/5.x/resources/global-search
- https://filamentphp.com/docs/5.x/actions/modals
- https://filamentphp.com/docs/5.x/advanced/render-hooks
- https://filamentphp.com/docs/5.x/styling/css-hooks

## 2) Directory & naming conventions
- Default to Filament discovery conventions for Resources/Pages/Widgets unless you adopt modular architecture.
- Clusters: directory layout is recommended, not mandatory; functional behavior depends on `$cluster`.

Sources:
- https://filamentphp.com/docs/5.x/navigation/clusters
- https://filamentphp.com/docs/5.x/advanced/modular-architecture

## 3) Panel setup defaults
- Default to a single `/admin` panel unless multiple audiences/configs demand multiple panels.
- Verify provider registration (Laravel 11+: `bootstrap/providers.php`) when adding a panel.
- Use `path()` carefully; treat `path('')` as a high-risk change requiring route conflict review.
- Assets policy:
  - Panel-only assets: register via panel config.
  - Shared/plugin assets: register via `FilamentAsset::register()`.
  - Deployment must include `php artisan filament:assets`.

Sources:
- https://filamentphp.com/docs/5.x/panel-configuration
- https://filamentphp.com/docs/5.x/advanced/assets

## 4) Navigation & information architecture
- Use nav groups + sort order intentionally; apply conditional visibility for clarity, but enforce authorization separately.
- Use clusters to introduce hierarchy and sub-navigation when sidebar complexity grows.
- Treat cluster code structure as a recommendation (organizational benefit), not a required rule.
- User menu:
  - Configure via `userMenuItems()` with Action objects.
  - Never put destructive actions there without confirmation + authorization.

Sources:
- https://filamentphp.com/docs/5.x/navigation/overview
- https://filamentphp.com/docs/5.x/navigation/clusters
- https://filamentphp.com/docs/5.x/navigation/user-menu

## 5) Resource patterns
- Default to Resources for CRUD; use custom pages for non-CRUD tools/workflows.
- Global search:
  - If a resource is intended for global search: ensure Edit/View page exists.
  - Otherwise disable global search for that resource (don’t “expect it to work”).
  - If global search renders relationship-backed details: eager-load via global search query override.
  - For very large datasets: consider disabling term splitting (only when needed).

Sources:
- https://filamentphp.com/docs/5.x/resources/overview
- https://filamentphp.com/docs/5.x/resources/global-search

## 6) Page lifecycle & query rules
- Treat relationship-backed rendering in aggregate contexts (global search details, list summaries) as requiring eager loading.
- Prefer render hooks for layout injection; avoid publishing internal views.

Sources:
- https://filamentphp.com/docs/5.x/resources/global-search
- https://filamentphp.com/docs/5.x/advanced/render-hooks

## 7) Infolists vs RelationManagers (decision tree)
- Interactive CRUD / attach / detach under owner record → RelationManager.
- Pick existing related record(s) inside owner form → Select / CheckboxList relationship fields.
- Inline CRUD inside owner form → Repeater.
- Default performance stance: RelationManagers stay lazy-loaded unless explicit UX justification exists.

Sources:
- https://filamentphp.com/docs/5.x/resources/managing-relationships
- https://filamentphp.com/docs/5.x/infolists/overview

## 8) Form patterns (validation, reactivity, state)
- Default: minimize server-driven reactivity; only use it when schema/visibility/requirements must change server-side.
- Prefer “on blur” semantics for chatty inputs when using reactive behavior (per docs patterns).
- Custom field views must obey state binding modifiers.

Sources:
- https://filamentphp.com/docs/5.x/forms/overview
- https://filamentphp.com/docs/5.x/forms/custom-fields

## 9) Table & action patterns
- Tables: always define a meaningful empty state (and empty-state actions where appropriate).
- Actions:
  - Execution actions use `->action(...)`.
  - Destructive actions add `->requiresConfirmation()`.
  - Navigation-only actions should use `->url(...)`.
  - UNVERIFIED: do not assert modal/confirmation behavior for URL-only actions unless verified.

Sources:
- https://filamentphp.com/docs/5.x/tables/empty-state
- https://filamentphp.com/docs/5.x/actions/modals

## 10) Authorization & security
- Enforce panel access in non-local environments as documented.
- UI visibility is not security; enforce policies/access checks in addition to hiding UI.
- Bulk operations: explicitly decide between “Any” policy methods vs per-record authorization.

Sources:
- https://filamentphp.com/docs/5.x/users/overview
- https://filamentphp.com/docs/5.x/resources/deleting-records

## 11) Notifications & UX feedback
- Default to explicit success/error notifications for user-triggered mutations that aren’t instantly obvious.
- Treat polling as a cost; set intervals intentionally where polling is used.

Sources:
- https://filamentphp.com/docs/5.x/notifications/overview
- https://filamentphp.com/docs/5.x/widgets/stats-overview

## 12) Performance defaults
- Heavy assets: prefer on-demand loading (`loadedOnRequest()` + `x-load-css` / `x-load-js`) for heavy dependencies.
- Styling overrides use CSS hook classes; layout injection uses render hooks; avoid view publishing.

Sources:
- https://filamentphp.com/docs/5.x/advanced/assets
- https://filamentphp.com/docs/5.x/styling/css-hooks
- https://filamentphp.com/docs/5.x/advanced/render-hooks

## 13) Testing requirements
- Test pages/relation managers/widgets as Livewire components.
- Test actions using Filament’s action testing guidance.
- Do not mount non-Livewire classes in Livewire tests.

Sources:
- https://filamentphp.com/docs/5.x/testing/overview
- https://filamentphp.com/docs/5.x/testing/testing-actions

## 14) Forbidden patterns
- Mixing Filament v3/v4 APIs into v5 code.
- Any mention of Livewire v3 for Filament v5.
- Registering panel providers in `bootstrap/app.php` on Laravel 11+.
- Destructive actions without `->requiresConfirmation()`.
- Shipping heavy assets globally when on-demand loading fits.
- Publishing Filament internal views as a default customization technique.

Sources:
- https://filamentphp.com/docs/5.x/upgrade-guide
- https://filamentphp.com/docs/5.x/panel-configuration
- https://filamentphp.com/docs/5.x/actions/modals
- https://filamentphp.com/docs/5.x/advanced/assets

## 15) Agent output contract
For any implementation request, the agent must explicitly state:
1) Livewire v4.0+ compliance.
2) Provider registration location (Laravel 11+: `bootstrap/providers.php`).
3) For each globally searchable resource: whether it has Edit/View page (or global search is disabled).
4) Which actions are destructive and how confirmation + authorization is handled.
5) Asset strategy: global vs on-demand and where `filament:assets` runs in deploy.
6) Testing plan: which pages/widgets/relation managers/actions are covered.

Sources:
- https://filamentphp.com/docs/5.x/upgrade-guide
- https://filamentphp.com/docs/5.x/panel-configuration
- https://filamentphp.com/docs/5.x/resources/global-search
- https://filamentphp.com/docs/5.x/advanced/assets
- https://filamentphp.com/docs/5.x/testing/testing-actions

=== .ai/filament-v5-checklist rules ===

# SECTION C — AI REVIEW CHECKLIST (STRICT CHECKBOXES)

## Version Safety
- [ ] Filament v5 explicitly targets Livewire v4.0+ (no Livewire v3 references anywhere).
  - Source: https://filamentphp.com/docs/5.x/upgrade-guide — “Upgrading Livewire”
- [ ] All references are Filament `/docs/5.x/` only (no v3/v4 docs, no legacy APIs).
- [ ] Upgrade assumptions match the v5 upgrade guide requirements and steps.
  - Source: https://filamentphp.com/docs/5.x/upgrade-guide — “New requirements”

## Panel & Navigation
- [ ] Laravel 11+: panel providers are registered in `bootstrap/providers.php` (not `bootstrap/app.php`).
  - Source: https://filamentphp.com/docs/5.x/panel-configuration — “Creating a new panel”
- [ ] Panel `path()` choices are intentional and do not conflict with existing routes (especially `path('')`).
  - Source: https://filamentphp.com/docs/5.x/panel-configuration — “Changing the path”
- [ ] Cluster usage is correctly configured (discovery + `$cluster` assignments).
  - Source: https://filamentphp.com/docs/5.x/navigation/clusters — “Creating a cluster”
- [ ] Cluster semantics (sub-navigation + grouped navigation behavior) are understood and verified against the clusters docs.
  - Source: https://filamentphp.com/docs/5.x/navigation/clusters — “Introduction”
- [ ] Cluster directory structure is treated as recommended, not mandatory.
  - Source: https://filamentphp.com/docs/5.x/navigation/clusters — “Code structure recommendations for panels using clusters”
- [ ] User menu items are registered via `userMenuItems()` and permission-gated where needed.
  - Source: https://filamentphp.com/docs/5.x/navigation/user-menu — “Introduction”

## Resource Structure
- [ ] `$recordTitleAttribute` is set for any resource intended for global search.
  - Source: https://filamentphp.com/docs/5.x/resources/overview — “Record titles”
- [ ] Hard rule enforced: every globally searchable resource has an Edit or View page; otherwise global search is disabled for it.
  - Source: https://filamentphp.com/docs/5.x/resources/global-search — “Setting global search result titles”
- [ ] Relationship-backed global search details are eager-loaded via the global search query override.
  - Source: https://filamentphp.com/docs/5.x/resources/global-search — “Adding extra details to global search results”

## Infolists & Relations
- [ ] Each relationship uses the correct tool (RelationManager vs Select/CheckboxList vs Repeater) based on required interaction.
  - Source: https://filamentphp.com/docs/5.x/resources/managing-relationships — “Choosing the right tool for the job”
- [ ] RelationManagers remain lazy-loaded by default unless there’s an explicit UX justification.
  - Source: https://filamentphp.com/docs/5.x/resources/managing-relationships — “Disabling lazy loading”

## Forms
- [ ] Server-driven reactivity is minimal; chatty inputs do not trigger network requests unnecessarily.
  - Source: https://filamentphp.com/docs/5.x/forms/overview — “Reactive fields on blur”
- [ ] Custom field views obey state binding modifiers (no hardcoded `wire:model` without modifiers).
  - Source: https://filamentphp.com/docs/5.x/forms/custom-fields — “Obeying state binding modifiers”

## Tables & Actions
- [ ] Tables define a meaningful empty state (and empty-state actions where appropriate).
  - Source: https://filamentphp.com/docs/5.x/tables/empty-state — “Adding empty state actions”
- [ ] All destructive actions execute via `->action(...)` and include `->requiresConfirmation()`.
  - Source: https://filamentphp.com/docs/5.x/actions/modals — “Confirmation modals”
- [ ] No checklist rule assumes confirmation/modals for `->url(...)` actions unless verified in docs (UNVERIFIED behavior must not be asserted as fact).
  - Source: https://filamentphp.com/docs/5.x/actions/modals — “Confirmation modals”

## Authorization & Security
- [ ] Panel access is enforced for non-local environments as documented.
  - Source: https://filamentphp.com/docs/5.x/users/overview — “Authorizing access to the panel”
- [ ] UI visibility is not treated as authorization; policies/access checks still enforce boundaries.
- [ ] Bulk operations intentionally choose between “Any” policy methods vs per-record authorization where required.
  - Source: https://filamentphp.com/docs/5.x/resources/deleting-records — “Authorization”

## UX & Notifications
- [ ] User-triggered mutations provide explicit success/error notifications when outcomes aren’t instantly obvious.
  - Source: https://filamentphp.com/docs/5.x/notifications/overview — “Introduction”
- [ ] Polling (widgets/notifications) is configured intentionally (interval set or disabled) to control load.
  - Source: https://filamentphp.com/docs/5.x/widgets/stats-overview — “Live updating stats (polling)”

## Performance
- [ ] Heavy frontend assets are loaded on-demand using `loadedOnRequest()` + `x-load-css` / `x-load-js` where appropriate.
  - Source: https://filamentphp.com/docs/5.x/advanced/assets — “Lazy loading CSS” / “Lazy loading JavaScript”
- [ ] Styling overrides use CSS hook classes discovered via DevTools (no brittle selectors by default).
  - Source: https://filamentphp.com/docs/5.x/styling/css-hooks — “Discovering hook classes”

## Testing
- [ ] Livewire tests mount Filament pages/relation managers/widgets (Livewire components), not static resource classes.
  - Source: https://filamentphp.com/docs/5.x/testing/overview — “What is a Livewire component when using Filament?”
- [ ] Actions that mutate data are covered using Filament’s action testing guidance.
  - Source: https://filamentphp.com/docs/5.x/testing/testing-actions — “Testing actions”

## Deployment / Ops
- [ ] `php artisan filament:assets` is included in the deployment process when using registered assets.
  - Source: https://filamentphp.com/docs/5.x/advanced/assets — “The FilamentAsset facade”

=== foundation rules ===

# Laravel Boost Guidelines

The Laravel Boost guidelines are specifically curated by Laravel maintainers for this application. These guidelines should be followed closely to enhance the user's satisfaction building Laravel applications.

## Foundational Context
This application is a Laravel application and its main Laravel ecosystems package & versions are below. You are an expert with them all. Ensure you abide by these specific packages & versions.

- php - 8.4.15
- filament/filament (FILAMENT) - v5
- laravel/framework (LARAVEL) - v12
- laravel/prompts (PROMPTS) - v0
- laravel/socialite (SOCIALITE) - v5
- livewire/livewire (LIVEWIRE) - v4
- laravel/mcp (MCP) - v0
- laravel/pint (PINT) - v1
- laravel/sail (SAIL) - v1
- pestphp/pest (PEST) - v4
- phpunit/phpunit (PHPUNIT) - v12
- tailwindcss (TAILWINDCSS) - v4

## 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 it works. 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 the user doesn't see a frontend change reflected in the UI, it could mean they need to run `vendor/bin/sail npm run build`, `vendor/bin/sail npm run dev`, or `vendor/bin/sail composer run dev`. Ask them.

## Replies
- Be concise in your explanations - focus on what's important rather than explaining obvious details.

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

=== boost rules ===

## Laravel Boost
- Laravel Boost is an MCP server that comes with powerful tools designed specifically for this application. Use them.

## Artisan
- Use the `list-artisan-commands` tool when you need to call an Artisan command to double-check the available parameters.

## URLs
- Whenever you share a project URL with the user, you should use the `get-absolute-url` tool to ensure you're using the correct scheme, domain/IP, and port.

## Tinker / Debugging
- You should use the `tinker` tool when you need to execute PHP to debug code or query Eloquent models directly.
- Use the `database-query` tool when you only need to read from the database.

## Reading Browser Logs With the `browser-logs` Tool
- You can read browser logs, errors, and exceptions using the `browser-logs` tool from Boost.
- Only recent browser logs will be useful - ignore old logs.

## Searching Documentation (Critically Important)
- Boost comes with a powerful `search-docs` tool you should use before any other approaches when dealing with Laravel or Laravel ecosystem packages. This tool automatically passes a list of installed packages and their versions to the remote Boost API, so it returns only version-specific documentation for the user's circumstance. You should pass an array of packages to filter on if you know you need docs for particular packages.
- The `search-docs` tool is perfect for all Laravel-related packages, including Laravel, Inertia, Livewire, Filament, Tailwind, Pest, Nova, Nightwatch, etc.
- You must use this tool to search for Laravel ecosystem documentation before falling back to other approaches.
- Search the documentation before making code changes to ensure we are taking the correct approach.
- Use multiple, broad, simple, topic-based queries to start. For example: `['rate limiting', 'routing rate limiting', 'routing']`.
- Do not add package names to queries; package information is already shared. For example, use `test resource table`, not `filament 4 test resource table`.

### Available Search Syntax
- You can and should pass multiple queries at once. The most relevant results will be returned first.

1. Simple Word Searches with auto-stemming - query=authentication - finds 'authenticate' and 'auth'.
2. Multiple Words (AND Logic) - query=rate limit - finds knowledge containing both "rate" AND "limit".
3. Quoted Phrases (Exact Position) - query="infinite scroll" - words must be adjacent and in that order.
4. Mixed Queries - query=middleware "rate limit" - "middleware" AND exact phrase "rate limit".
5. Multiple Queries - queries=["authentication", "middleware"] - ANY of these terms.

=== php rules ===

## PHP

- Always use curly braces for control structures, even if it has one line.

### Constructors
- Use PHP 8 constructor property promotion in `__construct()`.
    - <code-snippet>public function __construct(public GitHub $github) { }</code-snippet>
- Do not allow empty `__construct()` methods with zero parameters unless the constructor is private.

### Type Declarations
- Always use explicit return type declarations for methods and functions.
- Use appropriate PHP type hints for method parameters.

<code-snippet name="Explicit Return Types and Method Params" lang="php">
protected function isAccessible(User $user, ?string $path = null): bool
{
    ...
}
</code-snippet>

## Comments
- Prefer PHPDoc blocks over inline comments. Never use comments within the code itself unless there is something very complex going on.

## PHPDoc Blocks
- Add useful array shape type definitions for arrays when appropriate.

## Enums
- Typically, keys in an Enum should be TitleCase. For example: `FavoritePerson`, `BestLake`, `Monthly`.

=== sail rules ===

## Laravel Sail

- This project runs inside Laravel Sail's Docker containers. You MUST execute all commands through Sail.
- Start services using `vendor/bin/sail up -d` and stop them with `vendor/bin/sail stop`.
- Open the application in the browser by running `vendor/bin/sail open`.
- Always prefix PHP, Artisan, Composer, and Node commands with `vendor/bin/sail`. Examples:
    - Run Artisan Commands: `vendor/bin/sail artisan migrate`
    - Install Composer packages: `vendor/bin/sail composer install`
    - Execute Node commands: `vendor/bin/sail npm run dev`
    - Execute PHP scripts: `vendor/bin/sail php [script]`
- View all available Sail commands by running `vendor/bin/sail` without arguments.

=== tests rules ===

## Test Enforcement

- Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass.
- Run the minimum number of tests needed to ensure code quality and speed. Use `vendor/bin/sail artisan test --compact` with a specific filename or filter.

=== laravel/core rules ===

## Do Things the Laravel Way

- Use `vendor/bin/sail artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool.
- If you're creating a generic PHP class, use `vendor/bin/sail 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.

### Database
- Always use proper Eloquent relationship methods with return type hints. Prefer relationship methods over raw queries or manual joins.
- Use Eloquent models and relationships before suggesting raw database queries.
- Avoid `DB::`; prefer `Model::query()`. Generate code that leverages Laravel's ORM capabilities rather than bypassing them.
- Generate code that prevents N+1 query problems by using eager loading.
- Use Laravel's query builder for very complex database operations.

### Model Creation
- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `vendor/bin/sail artisan make:model`.

### 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.

### Controllers & Validation
- Always create Form Request classes for validation rather than inline validation in controllers. Include both validation rules and custom error messages.
- Check sibling Form Requests to see if the application uses array or string based validation rules.

### Queues
- Use queued jobs for time-consuming operations with the `ShouldQueue` interface.

### Authentication & Authorization
- Use Laravel's built-in authentication and authorization features (gates, policies, Sanctum, etc.).

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

### Configuration
- Use environment variables only in configuration files - never use the `env()` function directly outside of config files. Always use `config('app.name')`, not `env('APP_NAME')`.

### 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 `vendor/bin/sail artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests.

### Vite Error
- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `vendor/bin/sail npm run build` or ask the user to run `vendor/bin/sail npm run dev` or `vendor/bin/sail composer run dev`.

=== laravel/v12 rules ===

## Laravel 12

- Use the `search-docs` tool to get version-specific documentation.
- Since Laravel 11, Laravel has a new streamlined file structure which this project uses.

### Laravel 12 Structure
- In Laravel 12, middleware are no longer registered in `app/Http/Kernel.php`.
- Middleware are configured declaratively in `bootstrap/app.php` using `Application::configure()->withMiddleware()`.
- `bootstrap/app.php` is the file to register middleware, exceptions, and routing files.
- `bootstrap/providers.php` contains application specific service providers.
- The `app\Console\Kernel.php` file no longer exists; use `bootstrap/app.php` or `routes/console.php` for console configuration.
- Console commands in `app/Console/Commands/` are automatically available and do not require manual registration.

### Database
- When modifying a column, the migration must include all of the attributes that were previously defined on the column. Otherwise, they will be dropped and lost.
- Laravel 12 allows limiting eagerly loaded records natively, without external packages: `$query->latest()->limit(10);`.

### Models
- Casts can and likely should be set in a `casts()` method on a model rather than the `$casts` property. Follow existing conventions from other models.

=== livewire/core rules ===

## Livewire

- Use the `search-docs` tool to find exact version-specific documentation for how to write Livewire and Livewire tests.
- Use the `vendor/bin/sail artisan make:livewire [Posts\CreatePost]` Artisan command to create new components.
- State should live on the server, with the UI reflecting it.
- All Livewire requests hit the Laravel backend; they're like regular HTTP requests. Always validate form data and run authorization checks in Livewire actions.

## Livewire Best Practices
- Livewire components require a single root element.
- Use `wire:loading` and `wire:dirty` for delightful loading states.
- Add `wire:key` in loops:

    ```blade
    @foreach ($items as $item)
        <div wire:key="item-{{ $item->id }}">
            {{ $item->name }}
        </div>
    @endforeach
    ```

- Prefer lifecycle hooks like `mount()`, `updatedFoo()` for initialization and reactive side effects:

<code-snippet name="Lifecycle Hook Examples" lang="php">
    public function mount(User $user) { $this->user = $user; }
    public function updatedSearch() { $this->resetPage(); }
</code-snippet>

## Testing Livewire

<code-snippet name="Example Livewire Component Test" lang="php">
    Livewire::test(Counter::class)
        ->assertSet('count', 0)
        ->call('increment')
        ->assertSet('count', 1)
        ->assertSee(1)
        ->assertStatus(200);
</code-snippet>

<code-snippet name="Testing Livewire Component Exists on Page" lang="php">
    $this->get('/posts/create')
    ->assertSeeLivewire(CreatePost::class);
</code-snippet>

=== pint/core rules ===

## Laravel Pint Code Formatter

- You must run `vendor/bin/sail bin pint --dirty` before finalizing changes to ensure your code matches the project's expected style.
- Do not run `vendor/bin/sail bin pint --test`, simply run `vendor/bin/sail bin pint` to fix any formatting issues.

=== pest/core rules ===

## Pest
### Testing
- If you need to verify a feature is working, write or update a Unit / Feature test.

### Pest Tests
- All tests must be written using Pest. Use `vendor/bin/sail artisan make:test --pest {name}`.
- You must not remove any tests or test files from the tests directory without approval. These are not temporary or helper files - these are core to the application.
- Tests should test all of the happy paths, failure paths, and weird paths.
- Tests live in the `tests/Feature` and `tests/Unit` directories.
- Pest tests look and behave like this:
<code-snippet name="Basic Pest Test Example" lang="php">
it('is true', function () {
    expect(true)->toBeTrue();
});
</code-snippet>

### Running Tests
- Run the minimal number of tests using an appropriate filter before finalizing code edits.
- To run all tests: `vendor/bin/sail artisan test --compact`.
- To run all tests in a file: `vendor/bin/sail artisan test --compact tests/Feature/ExampleTest.php`.
- To filter on a particular test name: `vendor/bin/sail artisan test --compact --filter=testName` (recommended after making a change to a related file).
- When the tests relating to your changes are passing, ask the user if they would like to run the entire test suite to ensure everything is still passing.

### Pest Assertions
- When asserting status codes on a response, use the specific method like `assertForbidden` and `assertNotFound` instead of using `assertStatus(403)` or similar, e.g.:
<code-snippet name="Pest Example Asserting postJson Response" lang="php">
it('returns all', function () {
    $response = $this->postJson('/api/docs', []);

    $response->assertSuccessful();
});
</code-snippet>

### Mocking
- Mocking can be very helpful when appropriate.
- When mocking, you can use the `Pest\Laravel\mock` Pest function, but always import it via `use function Pest\Laravel\mock;` before using it. Alternatively, you can use `$this->mock()` if existing tests do.
- You can also create partial mocks using the same import or self method.

### Datasets
- Use datasets in Pest to simplify tests that have a lot of duplicated data. This is often the case when testing validation rules, so consider this solution when writing tests for validation rules.

<code-snippet name="Pest Dataset Example" lang="php">
it('has emails', function (string $email) {
    expect($email)->not->toBeEmpty();
})->with([
    'james' => 'james@laravel.com',
    'taylor' => 'taylor@laravel.com',
]);
</code-snippet>

=== pest/v4 rules ===

## Pest 4

- Pest 4 is a huge upgrade to Pest and offers: browser testing, smoke testing, visual regression testing, test sharding, and faster type coverage.
- Browser testing is incredibly powerful and useful for this project.
- Browser tests should live in `tests/Browser/`.
- Use the `search-docs` tool for detailed guidance on utilizing these features.

### Browser Testing
- You can use Laravel features like `Event::fake()`, `assertAuthenticated()`, and model factories within Pest 4 browser tests, as well as `RefreshDatabase` (when needed) to ensure a clean state for each test.
- Interact with the page (click, type, scroll, select, submit, drag-and-drop, touch gestures, etc.) when appropriate to complete the test.
- If requested, test on multiple browsers (Chrome, Firefox, Safari).
- If requested, test on different devices and viewports (like iPhone 14 Pro, tablets, or custom breakpoints).
- Switch color schemes (light/dark mode) when appropriate.
- Take screenshots or pause tests for debugging when appropriate.

### Example Tests

<code-snippet name="Pest Browser Test Example" lang="php">
it('may reset the password', function () {
    Notification::fake();

    $this->actingAs(User::factory()->create());

    $page = visit('/sign-in'); // Visit on a real browser...

    $page->assertSee('Sign In')
        ->assertNoJavascriptErrors() // or ->assertNoConsoleLogs()
        ->click('Forgot Password?')
        ->fill('email', 'nuno@laravel.com')
        ->click('Send Reset Link')
        ->assertSee('We have emailed your password reset link!')

    Notification::assertSent(ResetPassword::class);
});
</code-snippet>

<code-snippet name="Pest Smoke Testing Example" lang="php">
$pages = visit(['/', '/about', '/contact']);

$pages->assertNoJavascriptErrors()->assertNoConsoleLogs();
</code-snippet>

=== tailwindcss/core rules ===

## Tailwind CSS

- Use Tailwind CSS classes to style HTML; check and use existing Tailwind conventions within the project before writing your own.
- Offer to extract repeated patterns into components that match the project's conventions (i.e. Blade, JSX, Vue, etc.).
- Think through class placement, order, priority, and defaults. Remove redundant classes, add classes to parent or child carefully to limit repetition, and group elements logically.
- You can use the `search-docs` tool to get exact examples from the official documentation when needed.

### Spacing
- When listing items, use gap utilities for spacing; don't use margins.

<code-snippet name="Valid Flex Gap Spacing Example" lang="html">
    <div class="flex gap-8">
        <div>Superior</div>
        <div>Michigan</div>
        <div>Erie</div>
    </div>
</code-snippet>

### Dark Mode
- If existing pages and components support dark mode, new pages and components must support dark mode in a similar way, typically using `dark:`.

=== tailwindcss/v4 rules ===

## Tailwind CSS 4

- Always use Tailwind CSS v4; do not use the deprecated utilities.
- `corePlugins` is not supported in Tailwind v4.
- In Tailwind v4, configuration is CSS-first using the `@theme` directive — no separate `tailwind.config.js` file is needed.

<code-snippet name="Extending Theme in CSS" lang="css">
@theme {
  --color-brand: oklch(0.72 0.11 178);
}
</code-snippet>

- In Tailwind v4, you import Tailwind using a regular CSS `@import` statement, not using the `@tailwind` directives used in v3:

<code-snippet name="Tailwind v4 Import Tailwind Diff" lang="diff">
   - @tailwind base;
   - @tailwind components;
   - @tailwind utilities;
   + @import "tailwindcss";
</code-snippet>

### Replaced Utilities
- Tailwind v4 removed deprecated utilities. Do not use the deprecated option; use the replacement.
- Opacity values are still numeric.

| Deprecated |	Replacement |
|------------+--------------|
| bg-opacity-* | bg-black/* |
| text-opacity-* | text-black/* |
| border-opacity-* | border-black/* |
| divide-opacity-* | divide-black/* |
| ring-opacity-* | ring-black/* |
| placeholder-opacity-* | placeholder-black/* |
| flex-shrink-* | shrink-* |
| flex-grow-* | grow-* |
| overflow-ellipsis | text-ellipsis |
| decoration-slice | box-decoration-slice |
| decoration-clone | box-decoration-clone |
</laravel-boost-guidelines>

## Recent Changes
- 064-auth-structure: Added PHP 8.4 + Laravel 12, Filament v5, Livewire v4
- 063-entra-signin: Added PHP 8.4 + `laravel/framework:^12`, `livewire/livewire:^4`, `filament/filament:^5`, `laravel/socialite:^5.0`
- 062-tenant-rbac-v1: Added PHP 8.4 + Laravel 12, Filament v5, Livewire v4

## Active Technologies
- PostgreSQL (with a new `platform_users` table) (064-auth-structure)