updating to current main

.claude/skills/autonomous-coding-workflow/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: autonomous-coding-workflow
+description: Governs safe, incremental, repository-wide development workflow with continuous validation gates
+---
+
 # Autonomous Coding Workflow
 
 ## Goal

.claude/skills/ci-schema-invariant-gate/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ci-schema-gate
+name: ci-schema-invariant-gate
 description: Ensures correct execution order of migrations, seeders, and tests in CI
 ---
 

.claude/skills/dto-contract/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: dto-contracts
+name: dto-contract
 description: Defines DTO structure, lifecycle, and transformation rules across the application
 license: MIT
 metadata:

.claude/skills/filament-multi-tenancy/SKILL.md

@@ -105,21 +105,9 @@ Filament::setTenant($companyA, isQuiet: true);
 
 ## Tenant Middleware Stack
 
-The company panel uses three tenant middlewares (in order):
-
-1. `SetTenantFromQueryString` — reads `?tenant=search_code`, validates access
-2. `ConfigureTenant` — resolves tenant from route/query/session/user default, writes to session
-3. `EnsureUserCanAccessCompany` — enforces authorization (elevated roles bypass; regular users must own the company)
-
-These are registered as persistent tenant middleware in `CompanyPanelProvider`:
-
-```php
-->tenantMiddleware([
-    SetTenantFromQueryString::class,
-    ConfigureTenant::class,
-    EnsureUserCanAccessCompany::class,
-], isPersistent: true)
-```
+See the `tenant-middleware` skill for the full middleware chain. In short: three
+persistent middlewares run on every company panel request in this order:
+`SetTenantFromQueryString` → `ConfigureTenant` → `EnsureUserCanAccessCompany`.
 
 ## Tenant in Tests Setup
 

.claude/skills/filament-panel-setup/SKILL.md

@@ -8,12 +8,15 @@ metadata:
 
 # Filament Panel Setup
 
-This app has two panels:
+This app has three panels:
 
-| Panel | Provider | Id | Default? | Tenant |
-|-------|----------|----|----------|--------|
-| Company | `CompanyPanelProvider` | `company` | No | `Company::class` |
-| Admin | `AdminPanelProvider` | `admin` | Yes | None |
+| Panel | Provider | Id | Default? | Tenant | Access |
+|-------|----------|----|----------|--------|--------|
+| Company | `CompanyPanelProvider` | `company` | Yes (root) | `Company::class` | `client_admin`, `client` |
+| Admin | `AdminPanelProvider` | `admin` | No | None | `super_admin`, `admin`, `assist` |
+| User | `UserPanelProvider` | `user` | No | None | minimal, future use |
+
+All three providers live at `Modules/Core/Providers/`.
 
 ## Registering Module Resources
 

.claude/skills/filament-resource-pages/SKILL.md

@@ -1,126 +1,196 @@
 ---
-name: service-layer
-description: Defines application service structure and business orchestration boundaries
+name: filament-resource-pages
+description: "Defines the Filament v4 resource page structure used in this project: Resource + Pages + Schemas + Tables split, action patterns, and BaseResource conventions."
 license: MIT
 metadata:
   author: project
 ---
 
-# Service Layer
+# Filament Resource Pages
 
-Services define business orchestration and are the primary boundary for business logic execution.
+## Resource Directory Layout
 
-They are framework-agnostic and represent application behavior independent of UI or transport layers.
+Every resource lives under `Modules/{Name}/Filament/{Panel}/Resources/{Model}/`:
 
----
-
-# 1. Responsibility
-
-Services MUST:
-
-- contain business logic
-- coordinate models and repositories
-- enforce domain rules
-- return models or internally used DTOs
-- encapsulate persistence logic
-
-Services MUST NOT:
+```
+{Model}Resource.php          ← extends BaseResource; declares model, nav, pages
+Pages/
+  List{Model}.php             ← extends ListRecords
+  Create{Model}.php           ← extends CreateRecord
+  Edit{Model}.php             ← extends EditRecord
+Schemas/
+  {Model}Form.php             ← static configure(Schema $schema): Schema
+Tables/
+  {Model}sTable.php           ← static configure(Table $table): Table
+RelationManagers/             ← optional
+```
 
-- use Filament
-- depend on HTTP layer (requests/responses)
-- contain UI logic
-- use service locators (`app()`, `resolve()`)
-- depend on transport concerns
+Schemas and Tables are **separate classes**, never defined inline inside the Resource.
 
 ---
 
-# 2. Dependency Rule
-
-Services MUST use constructor injection:
+## Resource Class
 
 ```php
-public function __construct(
-    private InvoiceRepository $repository
-) {}
+class InvoiceResource extends BaseResource
+{
+    protected static ?string $model = Invoice::class;
+    protected static string|BackedEnum|null $navigationIcon = Heroicon::OutlinedBanknotes;
+    protected static ?int $navigationSort = 10;
+    protected static bool $isScopedToTenant = true;
+
+    public static function form(Schema $schema): Schema
+    {
+        return InvoiceForm::configure($schema);
+    }
+
+    public static function table(Table $table): Table
+    {
+        return InvoicesTable::configure($table);
+    }
+
+    public static function getPages(): array
+    {
+        return [
+            'index'  => Pages\ListInvoices::route('/'),
+            'create' => Pages\CreateInvoice::route('/create'),
+            'edit'   => Pages\EditInvoice::route('/{record}/edit'),
+        ];
+    }
+}
 ```
 
-No service locator usage is allowed inside services.
+`BaseResource` handles tenant-scoped queries automatically — do NOT add manual `company_id` filters.
 
 ---
 
-# 3. DTO Rule (Refined)
-
-DTOs are NOT required for UI → Service communication.
-
-DTO usage depends on coupling, not layer type:
-
-## DTOs are required when:
-- crossing system boundaries (API, external integrations, queues)
-- multiple consumers share a contract
-- transformation logic must be standardized
-- stability across versions is required
+## List Page
 
-## DTOs are NOT required when:
-- input originates from trusted UI layer (e.g. Filament Forms)
-- single consumer exists
-- payload is short-lived and not reused elsewhere
-
-### Rule of thumb:
-> DTOs exist to stabilize unstable or shared contracts, not to formalize trusted UI input.
-
-Services MAY still use DTOs internally if they improve clarity or structure.
+```php
+class ListInvoices extends ListRecords
+{
+    protected static string $resource = InvoiceResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [
+            CreateAction::make()
+                ->modalWidth('full')
+                ->action(function (array $data) {
+                    app(InvoiceService::class)->createInvoice($data);
+                }),
+        ];
+    }
+}
+```
 
 ---
 
-# 4. Filament Boundary Rule
-
-Filament is a UI orchestration layer.
+## Edit Page
 
-## Allowed usage:
+Override `save()` when you need to route the update through the service layer:
 
-### Pages / Resources
-- constructor injection preferred
-- `app(Service::class)` allowed as fallback when needed
+```php
+class EditInvoice extends EditRecord
+{
+    protected static string $resource = InvoiceResource::class;
+
+    public function save(bool $shouldRedirect = true, bool $shouldSendSavedNotification = true): void
+    {
+        $this->authorizeAccess();
+        $this->callHook('beforeValidate');
+        $data = $this->form->getState();
+        $this->callHook('afterValidate');
+        $data = $this->mutateFormDataBeforeSave($data);
+        $this->callHook('beforeSave');
+
+        app(InvoiceService::class)->updateInvoice($data, $this->getRecord());
+
+        $this->callHook('afterSave');
+
+        if ($shouldRedirect) {
+            $this->redirect($this->getRedirectUrl());
+        }
+    }
+
+    protected function getHeaderActions(): array
+    {
+        return [DeleteAction::make()];
+    }
+}
+```
 
-### Table Actions / Closures
-- `app(Service::class)` is allowed
-- constructor injection is not guaranteed in closure scope
+---
 
-Example:
+## Schema Class
 
 ```php
-Action::make('create')
-    ->action(function (array $data) {
-        app(InvoiceService::class)->createInvoice($data);
-    });
+class InvoiceForm
+{
+    public static function configure(Schema $schema): Schema
+    {
+        return $schema->components([
+            Grid::make(2)->schema([
+                Section::make('Details')->schema([
+                    Select::make('customer_id')->relationship('customer', 'company_name')->required(),
+                    DatePicker::make('invoice_date')->required(),
+                ]),
+            ]),
+        ]);
+    }
+}
 ```
 
-This is acceptable boundary-layer behavior.
-
 ---
 
-# 5. Standard Service Shape
+## Table Class
 
-```
-Modules/{Name}/src/Services/{Model}Service.php
+```php
+class InvoicesTable
+{
+    public static function configure(Table $table): Table
+    {
+        return $table
+            ->columns([
+                TextColumn::make('invoice_number')->searchable()->sortable(),
+                TextColumn::make('invoice_status')->badge(),
+            ])
+            ->actions([
+                EditAction::make(),
+                DeleteAction::make(),
+            ])
+            ->bulkActions([
+                BulkActionGroup::make([DeleteBulkAction::make()]),
+            ]);
+    }
+}
 ```
 
 ---
 
-# 6. Standard Methods
+## Action Closure Rule
+
+Filament action closures do NOT support constructor injection. Always use `app()`:
 
-- createX
-- updateX
-- deleteX
-- findOrFail
-- listForCompany
+```php
+->action(function (array $data) {
+    app(InvoiceService::class)->createInvoice($data);
+})
+```
+
+This is the only place `app()` is acceptable. Services themselves must never use it.
 
 ---
 
-# 7. Core Principle
+## Panel Registration
 
-Services are pure business units.
+Resources are discovered per module in `CompanyPanelProvider`:
 
-They MUST remain independent of framework execution context.
+```php
+->discoverResources(
+    in: base_path('modules/invoices/src/Filament/Company/Resources'),
+    for: 'Modules\\Invoices\\Filament\\Company\\Resources'
+)
+```
 
-UI layers may use service locator as a pragmatic escape hatch where DI is not available.
+The `in` parameter uses the filesystem path (lowercase with `src/`), while `for` uses the PHP namespace.