docs: add CLAUDE.md project instructions

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

CLAUDE.md

@@ -6,6 +6,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Modular monolith using Core PHP Framework (Laravel 12). Modules live in `app/Mod/{Name}/Boot.php` and register via events.
 
+**Bootstrap chain:** `bootstrap/app.php` loads four Core providers in order:
+1. `Core\LifecycleEventProvider` — fires lifecycle events that modules listen to
+2. `Core\Website\Boot` — website layer
+3. `Core\Front\Boot` — frontend/middleware layer
+4. `Core\Mod\Boot` — discovers and registers all modules from paths in `config/core.php`
+
 **Event-driven registration:**
 ```php
 class Boot
@@ -24,7 +30,12 @@ class Boot
 }
 ```
 
-**Module paths:** `app/Core/`, `app/Mod/`, `app/Website/` (configured in `config/core.php`)
+**Module paths (three layers):**
+- `app/Core/` — framework-level overrides (EUPL-1.2 copyleft)
+- `app/Mod/` — feature modules (your licence)
+- `app/Website/` — website-specific features (your licence)
+
+**Routing:** The top-level `routes/web.php` and `routes/api.php` are boilerplate stubs. All real routes are registered by modules via `Boot.php` event listeners.
 
 ## Commands
 
@@ -69,10 +80,17 @@ app/Mod/Blog/
 
 | Package | Namespace | Purpose |
 |---------|-----------|---------|
-| `host-uk/core` | `Core\` | Framework core, events, module discovery |
-| `host-uk/core-admin` | `Core\Admin\` | Admin panel, Livewire modals |
-| `host-uk/core-api` | `Core\Api\` | REST API, scopes, rate limiting, webhooks |
-| `host-uk/core-mcp` | `Core\Mcp\` | Model Context Protocol for AI agents |
+| `lthn/php` | `Core\` | Framework core, events, module discovery |
+| `lthn/php-admin` | `Core\Admin\` | Admin panel, Livewire modals |
+| `lthn/php-api` | `Core\Api\` | REST API, scopes, rate limiting, webhooks |
+| `lthn/php-mcp` | `Core\Mcp\` | Model Context Protocol for AI agents |
+
+## Testing
+
+- Pest 3 (not PHPUnit syntax)
+- `RefreshDatabase` is auto-applied to all Feature tests via `tests/Pest.php`
+- Tests use in-memory SQLite (`phpunit.xml`)
+- CI runs against PHP 8.2, 8.3, 8.4
 
 ## Conventions
 
@@ -81,8 +99,9 @@ app/Mod/Blog/
 **PHP:**
 - `declare(strict_types=1);` in all files
 - Full type hints on parameters and return types
+- Final classes by default unless inheritance is intended
 - PSR-12 formatting (Laravel Pint)
-- Pest for testing (not PHPUnit syntax)
+- Don't create controllers for Livewire pages
 
 **Naming:**
 - Models: Singular PascalCase (`Post`)
@@ -96,7 +115,13 @@ app/Mod/Blog/
 - Font Awesome Pro for icons (not Heroicons)
 - Tailwind CSS for styling
 
-## License
+**Indentation** (`.editorconfig`): 4 spaces for PHP, 2 spaces for JS/TS/JSON/YAML.
+
+## Known Limitations
+
+- `tailwind.config.js` only scans `resources/` — module view paths (`app/Mod/*/Views/`) are not yet included
+
+## Licence
 
 - `Core\` namespace and vendor packages: EUPL-1.2 (copyleft)
 - `app/Mod/*`, `app/Website/*`: Your choice (no copyleft)