docs: add CLAUDE.md project instructions

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

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Package Overview
 
-This is `host-uk/core-api`, a Laravel package providing REST API infrastructure: OpenAPI documentation, rate limiting, webhook signing, and secure API key management. Part of the Core PHP Framework monorepo ecosystem.
+This is `lthn/php-api`, a Laravel package providing REST API infrastructure: OpenAPI documentation, rate limiting, webhook signing, API versioning, and secure API key management. Part of the Core PHP Framework monorepo ecosystem.
 
 ## Commands
 
@@ -13,41 +13,21 @@ This is `host-uk/core-api`, a Laravel package providing REST API infrastructure:
 ./vendor/bin/pest --filter=ApiKey    # Run tests matching "ApiKey"
 ./vendor/bin/pint --dirty            # Format changed files
 ./vendor/bin/pint src/               # Format specific directory
+./vendor/bin/pint --test             # Check formatting without changes (CI uses this)
 ```
 
-## Package Structure
-
-```
-src/
-├── Api/                        # Core\Api namespace
-│   ├── Boot.php               # Service provider, event listeners
-│   ├── config.php             # Package configuration
-│   ├── Middleware/            # API auth, rate limiting, scopes
-│   ├── Models/                # ApiKey, WebhookEndpoint, etc.
-│   ├── Services/              # Business logic (webhooks, keys)
-│   ├── Documentation/         # OpenAPI spec generation
-│   │   ├── Attributes/        # #[ApiTag], #[ApiResponse], etc.
-│   │   ├── Extensions/        # API docs extensions
-│   │   └── OpenApiBuilder.php # Spec generator
-│   ├── RateLimit/             # Per-endpoint rate limiting
-│   ├── Resources/             # API JSON resources
-│   └── Tests/Feature/         # Package tests
-│
-└── Website/Api/               # Core\Website\Api namespace
-    ├── Boot.php               # Web routes service provider
-    ├── Controllers/           # DocsController
-    ├── Routes/web.php         # /api/docs, /api/guides routes
-    ├── Services/              # OpenApiGenerator
-    └── View/Blade/            # API docs UI templates
-```
+Tests live in `src/Api/Tests/Feature/`, not the root `tests/` directory.
 
 ## Architecture
 
-**Two-namespace design:**
-- `Core\Api\` — Backend API logic (middleware, models, services)
-- `Core\Website\Api\` — Frontend documentation UI (controllers, views)
+**Three-namespace design:**
+- `Core\Front\Api\` (`src/Front/Api/`) — API frontage: middleware group, versioning middleware, rate limiter config. **This is the Laravel auto-discovered provider** (registered in `composer.json extra.laravel.providers`). It fires `ApiRoutesRegistering` during boot.
+- `Core\Api\` (`src/Api/`) — Backend API logic: authentication, scopes, models, webhook services, OpenAPI docs. Uses the event-driven `$listens` pattern to register lazily when `ApiRoutesRegistering` fires.
+- `Core\Website\Api\` (`src/Website/Api/`) — Frontend documentation UI: controllers, views, web routes for `/api/docs`.
 
-**Event-driven boot** via `$listens` array in Boot classes:
+**Boot chain:** `Front\Api\Boot` (auto-discovered) → fires `ApiRoutesRegistering` → `Api\Boot` registers middleware aliases and routes via event handler.
+
+**Event-driven boot** via `$listens` array in `Core\Api\Boot`:
 ```php
 public static array $listens = [
     AdminPanelBooting::class => 'onAdminPanel',
@@ -56,11 +36,18 @@ public static array $listens = [
 ];
 ```
 
-**Key components:**
-- `AuthenticateApiKey` — Validates API keys (bcrypt + legacy SHA-256)
-- `EnforceApiScope` — Scope-based permissions (`read`, `write`, wildcards)
-- `RateLimitApi` — Tier-based rate limiting with burst allowance
-- `WebhookService` — HMAC-SHA256 signed webhook delivery
+**Middleware aliases** registered via events (not `bootstrap/app.php`):
+- `api.auth` / `auth.api` → `AuthenticateApiKey` (bcrypt + legacy SHA-256 key validation)
+- `api.scope` / `api.scope.enforce` → `CheckApiScope` / `EnforceApiScope` (wildcard-capable permissions)
+- `api.rate` → `RateLimitApi` (tier-based with burst allowance)
+- `api.version` → `ApiVersion` (URL/header version parsing)
+- `api.sunset` → `ApiSunset` (deprecation headers)
+
+**Key services:**
+- `WebhookService` — HMAC-SHA256 signed delivery with exponential backoff retries
+- `RateLimitService` — Sliding window, per-workspace, tier-based (`free` → `enterprise`)
+- `IpRestrictionService` — API key IP whitelisting with CIDR support
+- `OpenApiBuilder` — Generates spec from PHP attributes on controllers
 
 ## OpenAPI Documentation Attributes
 
@@ -88,4 +75,4 @@ class ProductController
 
 ## License
 
-EUPL-1.2 (copyleft applies to Core\ namespace)
+EUPL-1.2 (copyleft applies to Core\ namespace)