docs: tailor CLAUDE.md to core-commerce package

Replace generic Core PHP Framework template with documentation specific
to this commerce package, including service layer architecture, payment
gateways, domain events, and correct directory structure.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CLAUDE.md

@@ -1,66 +1,112 @@
-# Core PHP Framework Project
+# CLAUDE.md
 
-## Architecture
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-Modular monolith using Core PHP Framework. Modules live in `app/Mod/{Name}/Boot.php`.
+## What This Is
 
-**Event-driven registration:**
+`host-uk/core-commerce` - A Laravel package providing orders, subscriptions, invoices, and payment processing. Namespace: `Core\Mod\Commerce`.
-```php
-class Boot
-{
-    public static array $listens = [
-        WebRoutesRegistering::class => 'onWebRoutes',
-        ApiRoutesRegistering::class => 'onApiRoutes',
-        AdminPanelBooting::class => 'onAdminPanel',
-    ];
-}
-```
 
 ## Commands
 
 ```bash
-composer run dev              # Dev server (if configured)
+composer run lint          # vendor/bin/pint
-php artisan serve             # Laravel dev server
+composer run test          # vendor/bin/pest
-npm run dev                   # Vite
+vendor/bin/pint --dirty    # Format changed files only
-./vendor/bin/pint --dirty     # Format changed files
+vendor/bin/pest --filter=CheckoutFlowTest  # Run single test file
-php artisan test              # All tests
-php artisan make:mod Blog     # Create module
 ```
 
-## Module Structure
+## Architecture
 
-```
+### Boot & Event System
-app/Mod/Blog/
+
-├── Boot.php              # Event listeners
+This is a **Laravel package** (not a standalone app). `Boot.php` extends `ServiceProvider` and uses the Core Framework's event-driven lazy-loading:
-├── Models/               # Eloquent models
+
-├── Routes/
+```php
-│   ├── web.php          # Web routes
+public static array $listens = [
-│   └── api.php          # API routes
+    AdminPanelBooting::class => 'onAdminPanel',
-├── Views/               # Blade templates
+    ApiRoutesRegistering::class => 'onApiRoutes',
-├── Livewire/            # Livewire components
+    WebRoutesRegistering::class => 'onWebRoutes',
-├── Migrations/          # Database migrations
+    ConsoleBooting::class => 'onConsole',
-└── Tests/               # Module tests
+];
 ```
 
-## Packages
+### Service Layer
 
-| Package | Purpose |
+Business logic lives in `Services/`. All services are registered as singletons in `Boot::register()`:
-|---------|---------|
+
-| `host-uk/core` | Core framework, events, module discovery |
+- **CommerceService** - Order orchestration
-| `host-uk/core-admin` | Admin panel, Livewire modals |
+- **SubscriptionService** - Subscription lifecycle
-| `host-uk/core-api` | REST API, scopes, rate limiting, webhooks |
+- **InvoiceService** - Invoice generation
-| `host-uk/core-mcp` | Model Context Protocol for AI agents |
+- **TaxService** - Jurisdiction-based tax calculation
+- **CouponService** - Discount validation and application
+- **CurrencyService** - Multi-currency support with exchange rates
+- **DunningService** - Failed payment retry logic
+- **UsageBillingService** - Metered/usage-based billing
+- **ReferralService** - Affiliate tracking and commissions
+- **PaymentMethodService** - Stored payment methods
+
+### Payment Gateways
+
+Pluggable via `PaymentGatewayContract`:
+- `StripeGateway` - Primary (SaaS)
+- `BTCPayGateway` - Cryptocurrency
+
+### Domain Events
+
+Events in `Events/` trigger listeners for loose coupling:
+- `OrderPaid` - Payment succeeded
+- `SubscriptionCreated`, `SubscriptionRenewed`, `SubscriptionUpdated`, `SubscriptionCancelled`
+
+### Livewire Components
+
+Located in `View/Modal/` (not `Livewire/`):
+- `View/Modal/Web/` - User-facing (checkout, invoices, subscription management)
+- `View/Modal/Admin/` - Admin panel (managers for orders, coupons, products, etc.)
+
+## Key Directories
+
+```
+Boot.php              # ServiceProvider, event registration
+config.php            # Currencies, gateways, tax rules
+Models/               # Eloquent models (Order, Subscription, Invoice, etc.)
+Services/             # Business logic layer
+View/Modal/           # Livewire components
+Routes/               # web.php, api.php, admin.php, console.php
+Migrations/           # Database schema
+Events/               # Domain events
+Listeners/            # Event subscribers
+tests/Feature/        # Pest feature tests
+```
 
 ## Conventions
 
-- UK English (colour, organisation, centre)
+- **UK English** - colour, organisation, centre
-- PSR-12 coding style (Laravel Pint)
+- **PSR-12** via Laravel Pint
-- Pest for testing
+- **Pest** for testing (not PHPUnit syntax)
-- Livewire + Flux Pro for UI
+- **Strict types** - `declare(strict_types=1);` in all files
+- **Livewire + Flux Pro** for UI components
+- **Font Awesome Pro** for icons (not Heroicons)
 
-## License
+## Namespaces
 
-- `Core\` namespace and vendor packages: EUPL-1.2 (copyleft)
+```php
-- `app/Mod/*`, `app/Website/*`: Your choice (no copyleft)
+use Core\Mod\Commerce\Models\Order;
+use Core\Mod\Commerce\Services\SubscriptionService;
+use Core\Service\Commerce\SomeUtility;  // Alternative service namespace
+```
 
-See LICENSE for full details.
+## Testing
+
+Tests are in `tests/` with Pest:
+
+```php
+test('user can checkout', function () {
+    // ...
+});
+```
+
+Run a specific test:
+```bash
+vendor/bin/pest --filter="checkout"
+vendor/bin/pest tests/Feature/CheckoutFlowTest.php
+```