docs: rewrite CLAUDE.md for core-api package specifics

Replace generic monorepo instructions with package-specific guidance:
- Document actual src/ structure with Core\Api and Core\Website\Api namespaces
- Add package-relevant commands (pest, pint)
- Document key middleware components and OpenAPI attributes
- Remove irrelevant app/Mod/ module structure references

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

CLAUDE.md

@@ -1,66 +1,91 @@
-# 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`.
+## Package Overview
 
-**Event-driven registration:**
+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.
-```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)
+./vendor/bin/pest                    # Run all tests
-php artisan serve             # Laravel dev server
+./vendor/bin/pest --filter=ApiKey    # Run tests matching "ApiKey"
-npm run dev                   # Vite
+./vendor/bin/pint --dirty            # Format changed files
-./vendor/bin/pint --dirty     # Format changed files
+./vendor/bin/pint src/               # Format specific directory
-php artisan test              # All tests
-php artisan make:mod Blog     # Create module
 ```
 
-## Module Structure
+## Package Structure
 
 ```
-app/Mod/Blog/
+src/
-├── Boot.php              # Event listeners
+├── Api/                        # Core\Api namespace
-├── Models/               # Eloquent models
+│   ├── Boot.php               # Service provider, event listeners
-├── Routes/
+│   ├── config.php             # Package configuration
-│   ├── web.php          # Web routes
+│   ├── Middleware/            # API auth, rate limiting, scopes
-│   └── api.php          # API routes
+│   ├── Models/                # ApiKey, WebhookEndpoint, etc.
-├── Views/               # Blade templates
+│   ├── Services/              # Business logic (webhooks, keys)
-├── Livewire/            # Livewire components
+│   ├── Documentation/         # OpenAPI spec generation
-├── Migrations/          # Database migrations
+│   │   ├── Attributes/        # #[ApiTag], #[ApiResponse], etc.
-└── Tests/               # Module tests
+│   │   ├── 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
 ```
 
-## Packages
+## Architecture
 
-| Package | Purpose |
+**Two-namespace design:**
-|---------|---------|
+- `Core\Api\` — Backend API logic (middleware, models, services)
-| `host-uk/core` | Core framework, events, module discovery |
+- `Core\Website\Api\` — Frontend documentation UI (controllers, views)
-| `host-uk/core-admin` | Admin panel, Livewire modals |
+
-| `host-uk/core-api` | REST API, scopes, rate limiting, webhooks |
+**Event-driven boot** via `$listens` array in Boot classes:
-| `host-uk/core-mcp` | Model Context Protocol for AI agents |
+```php
+public static array $listens = [
+    AdminPanelBooting::class => 'onAdminPanel',
+    ApiRoutesRegistering::class => 'onApiRoutes',
+    ConsoleBooting::class => 'onConsole',
+];
+```
+
+**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
+
+## OpenAPI Documentation Attributes
+
+```php
+use Core\Api\Documentation\Attributes\{ApiTag, ApiResponse, ApiParameter, ApiSecurity, ApiHidden};
+
+#[ApiTag('Products')]
+#[ApiResponse(200, ProductResource::class)]
+#[ApiSecurity('apiKey')]
+class ProductController
+{
+    #[ApiParameter('filter', 'query', 'string', 'Filter products')]
+    public function index() { }
+}
+```
 
 ## Conventions
 
 - UK English (colour, organisation, centre)
-- PSR-12 coding style (Laravel Pint)
+- PSR-12 with `declare(strict_types=1);`
-- Pest for testing
+- Type hints on all parameters and return types
-- Livewire + Flux Pro for UI
+- Pest for testing (not PHPUnit directly)
+- Font Awesome Pro icons (not Heroicons)
+- Flux Pro components (not vanilla Alpine)
 
 ## License
 
-- `Core\` namespace and vendor packages: EUPL-1.2 (copyleft)
+EUPL-1.2 (copyleft applies to Core\ namespace)
-- `app/Mod/*`, `app/Website/*`: Your choice (no copyleft)
-
-See LICENSE for full details.