docs: add CLAUDE.md project instructions

Co-Authored-By: Virgil <virgil@lethean.io>

CLAUDE.md

@@ -4,67 +4,59 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Overview
 
-This is the **Core Admin Package** (`host-uk/core-admin`) - an admin panel and service layer for the Core PHP Framework. It provides the Hub dashboard, form components with authorization, global search, and Livewire modals.
+This is the **Core Admin Package** (`lthn/php-admin`) - an admin panel and service layer for the Core PHP Framework. It provides the Hub dashboard, form components with authorisation, global search, Livewire modals, and honeypot security monitoring.
 
 ## Commands
 
 ```bash
 php artisan serve             # Laravel dev server
-npm run dev                   # Vite dev server
+npm run dev                   # Vite dev server (Tailwind v4)
+npm run build                 # Production asset build
 ./vendor/bin/pint --dirty     # Format changed files only
 ./vendor/bin/pest             # Run all tests
 ./vendor/bin/pest --filter=SearchTest  # Run specific test
 ```
 
+CI matrix: PHP 8.2, 8.3, 8.4.
+
 ## Architecture
 
-This package contains three Boot.php files that wire up different concerns:
+Four Boot.php files wire up different concerns via event-driven registration:
 
 | File | Namespace | Purpose |
 |------|-----------|---------|
-| `src/Boot.php` | `Core\Admin\` | Main package provider - form components, search registry |
+| `src/Boot.php` | `Core\Admin\` | Main package provider - form components (`core-forms` prefix), search registry singleton |
-| `src/Website/Hub/Boot.php` | `Website\Hub\` | Admin dashboard frontend - routes, Livewire components, menu |
+| `src/Website/Hub/Boot.php` | `Website\Hub\` | Admin frontend - routes, Livewire components, menu. Activates via domain pattern matching (`/^(hub\.)?core\.(test\|localhost)$/`) |
-| `src/Mod/Hub/Boot.php` | `Core\Admin\Mod\Hub\` | Admin backend - models, migrations, 20+ Livewire modals |
+| `src/Mod/Hub/Boot.php` | `Core\Admin\Mod\Hub\` | Admin backend - models, migrations, 30+ Livewire modals. Lazy-loads on `AdminPanelBooting` event |
-| `Service/Boot.php` | `Core\Service\Admin\` | Service definition for platform_services table |
+| `Service/Boot.php` | `Core\Service\Admin\` | Service definition for `platform_services` table |
+
+**Key pattern — event-driven lazy loading:**
+Boot classes declare a static `$listens` array mapping events to handler methods. Modules only register their components when the relevant event fires (e.g., `AdminPanelBooting`), not at application boot. This is important to understand when adding new features — registration happens in event handlers, not in `register()`/`boot()`.
 
-**Event-driven registration pattern:**
 ```php
-class Boot extends ServiceProvider
+public static array $listens = [
-{
+    AdminPanelBooting::class => 'onAdminPanel',
-    public static array $listens = [
+    DomainResolving::class => 'onDomainResolving',
-        AdminPanelBooting::class => 'onAdminPanel',
+];
-        DomainResolving::class => 'onDomainResolving',
-    ];
-}
 ```
 
 ### Key Systems
 
-**Form Components** (`src/Forms/`) - Blade components with authorization via `HasAuthorizationProps` trait:
+**Form Components** (`src/Forms/`) - Class-backed Blade components with `core-forms` prefix and authorisation via `HasAuthorizationProps` trait:
-- `<x-core-forms.input />`, `<x-core-forms.select />`, `<x-core-forms.toggle />`, etc.
 - Props: `canGate`, `canResource`, `canHide` for permission-based disable/hide
+- Authorisation only checks when BOTH `canGate` AND `canResource` are set; explicit `disabled` prop takes precedence
+- 7 components: Input, Textarea, Select, Checkbox, Button, Toggle, FormGroup
 
-**Search System** (`src/Search/`) - Extensible provider-based search:
+**Search System** (`src/Search/`) - Provider-based search with fuzzy matching and relevance scoring:
-- Implement `SearchProvider` interface with `search()`, `searchType()`, `getUrl()`
+- Implement `SearchProvider` interface: `search()`, `searchType()`, `searchLabel()`, `searchIcon()`, `getUrl()`, `searchPriority()`, `isAvailable()`
-- Register providers via `SearchProviderRegistry`
+- `SearchProviderRegistry` aggregates providers, sorts by priority (lower = higher), calculates relevance scores (100=exact, 90=starts-with, 80=whole-word, 70=substring, 60=word-start, 40=fuzzy)
+- Built-in `AdminPageSearchProvider` covers 13 admin pages at priority 10
 
-**Admin Menu** - Implement `AdminMenuProvider` interface to add menu items
+**Admin Menu** - Implement `AdminMenuProvider` interface. Items have `group` (dashboard, workspaces, settings, admin), `priority`, `icon`, and optional `'admin' => true` flag. Menu registration uses closures for deferred route resolution.
 
-### Directory Structure
+**Honeypot Security** (`src/Mod/Hub/Models/HoneypotHit`) - Tracks attacks with severity levels ("warning" for robots.txt violations, "critical" for admin probing). Includes bot detection for 23+ patterns and IP/geo tracking.
 
-```
+**Livewire Modals** - Full-page Livewire components using `->layout('hub::admin.layouts.app')`. Routes are GET-based (Livewire handles forms internally). Routes prefixed with `/hub`, named `hub.*`.
-src/
-├── Boot.php                    # Package service provider
-├── Forms/                      # Form components with authorization
-├── Search/                     # Global search system
-├── Website/Hub/                # Admin dashboard frontend
-│   ├── Routes/admin.php        # Admin web routes
-│   └── View/                   # Blade templates + Livewire components
-└── Mod/Hub/                    # Admin backend module
-    ├── Models/                 # Service, HoneypotHit
-    ├── Migrations/             # platform_services, honeypot_hits
-    └── Boot.php                # Module registration + 20 Livewire modals
-```
 
 ## Conventions
 
@@ -73,17 +65,18 @@ src/
 - **Type hints** - All parameters and return types
 - **Flux Pro** - Use Flux components, not vanilla Alpine
 - **Font Awesome Pro** - Use FA icons, not Heroicons
-- **Pest** - Write tests using Pest syntax
+- **Pest** - Write tests using Pest `describe`/`it` syntax with `expect()` assertions
+- **Immutable DTOs** - Use readonly properties; mutation methods return new instances (see `SearchResult::withTypeAndIcon()`)
 
 ## Packages
 
 | Package | Purpose |
 |---------|---------|
-| `host-uk/core` | Core framework, events, module discovery |
+| `lthn/php` | Core framework, events, module discovery |
-| `host-uk/core-admin` | This package - admin panel, modals |
+| `lthn/php-admin` | This package - admin panel, modals |
-| `host-uk/core-api` | REST API, scopes, rate limiting |
+| `lthn/php-api` | REST API, scopes, rate limiting |
-| `host-uk/core-mcp` | Model Context Protocol for AI agents |
+| `lthn/php-mcp` | Model Context Protocol for AI agents |
 
 ## License
 
-EUPL-1.2 (copyleft) - See LICENSE for details.
+EUPL-1.2 (copyleft) - See LICENSE for details.