From 1da124a92a29b21f3f21dfeb6857302c5adb7e29 Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Wed, 28 Jan 2026 14:06:13 +0000
Subject: [PATCH] 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 | 115 +++++++++++++++++++++++++++++++++---------------------
 1 file changed, 70 insertions(+), 45 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 138e17b..754d7ab 100644
--- a/CLAUDE.md
+++ b/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:**
-```php
-class Boot
-{
-    public static array $listens = [
-        WebRoutesRegistering::class => 'onWebRoutes',
-        ApiRoutesRegistering::class => 'onApiRoutes',
-        AdminPanelBooting::class => 'onAdminPanel',
-    ];
-}
-```
+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.
 
 ## Commands
 
 ```bash
-composer run dev              # Dev server (if configured)
-php artisan serve             # Laravel dev server
-npm run dev                   # Vite
-./vendor/bin/pint --dirty     # Format changed files
-php artisan test              # All tests
-php artisan make:mod Blog     # Create module
+./vendor/bin/pest                    # Run all tests
+./vendor/bin/pest --filter=ApiKey    # Run tests matching "ApiKey"
+./vendor/bin/pint --dirty            # Format changed files
+./vendor/bin/pint src/               # Format specific directory
 ```
 
-## Module Structure
+## Package Structure
 
 ```
-app/Mod/Blog/
-├── Boot.php              # Event listeners
-├── Models/               # Eloquent models
-├── Routes/
-│   ├── web.php          # Web routes
-│   └── api.php          # API routes
-├── Views/               # Blade templates
-├── Livewire/            # Livewire components
-├── Migrations/          # Database migrations
-└── Tests/               # Module tests
+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
 ```
 
-## Packages
+## Architecture
 
-| Package | Purpose |
-|---------|---------|
-| `host-uk/core` | Core framework, events, module discovery |
-| `host-uk/core-admin` | Admin panel, Livewire modals |
-| `host-uk/core-api` | REST API, scopes, rate limiting, webhooks |
-| `host-uk/core-mcp` | Model Context Protocol for AI agents |
+**Two-namespace design:**
+- `Core\Api\` — Backend API logic (middleware, models, services)
+- `Core\Website\Api\` — Frontend documentation UI (controllers, views)
+
+**Event-driven boot** via `$listens` array in Boot classes:
+```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)
-- Pest for testing
-- Livewire + Flux Pro for UI
+- PSR-12 with `declare(strict_types=1);`
+- Type hints on all parameters and return types
+- 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)
-- `app/Mod/*`, `app/Website/*`: Your choice (no copyleft)
-
-See LICENSE for full details.
+EUPL-1.2 (copyleft applies to Core\ namespace)
\ No newline at end of file