From 5c92e92a29ce747c5202ad1eb890dc2b53438c25 Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Wed, 28 Jan 2026 14:08:45 +0000
Subject: [PATCH] docs: update CLAUDE.md to reflect package structure

Previous version described the application template, but this repository
is the core-content package. Updated to document actual namespace,
structure, models, API routes, rate limiters, and configuration.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 123 ++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 77 insertions(+), 46 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 138e17b..c2652e1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,66 +1,97 @@
-# 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-content`, a Laravel package providing headless CMS functionality for the Core PHP Framework. It handles content management, AI generation, revisions, webhooks, and search.
+
+**Namespace:** `Core\Mod\Content\`
 
 ## 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
+composer run lint             # Laravel Pint (PSR-12)
+composer run test             # Pest tests
+./vendor/bin/pint --dirty     # Format changed files only
+./vendor/bin/pest --filter=ContentSearch  # Run specific tests
 ```
 
-## Module Structure
+## Architecture
 
-```
-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
+### Boot.php (Service Provider)
+
+The entry point extending `ServiceProvider` with event-driven registration:
+
+```php
+public static array $listens = [
+    WebRoutesRegistering::class => 'onWebRoutes',
+    ApiRoutesRegistering::class => 'onApiRoutes',
+    ConsoleBooting::class => 'onConsole',
+    McpToolsRegistering::class => 'onMcpTools',
+];
 ```
 
-## Packages
+### Package Structure
 
-| 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 |
+```
+Boot.php              # Service provider + event listeners
+config.php            # Package configuration
+Models/               # Eloquent: ContentItem, ContentBrief, ContentRevision, etc.
+Services/             # Business logic: ContentSearchService, ContentRender, etc.
+Controllers/Api/      # REST API controllers
+Mcp/Handlers/         # MCP tools for AI agent integration
+Jobs/                 # Queue jobs: GenerateContentJob, ProcessContentWebhook
+View/Modal/           # Livewire components (Web/ and Admin/)
+View/Blade/           # Blade templates
+Migrations/           # Database migrations
+routes/               # web.php, api.php, console.php
+```
+
+### Key Models
+
+| Model | Purpose |
+|-------|---------|
+| `ContentItem` | Published content with revisions |
+| `ContentBrief` | Content generation requests/queue |
+| `ContentRevision` | Version history for content items |
+| `ContentMedia` | Attached media files |
+| `ContentTaxonomy` | Categories and tags |
+| `ContentWebhookEndpoint` | External webhook configurations |
+
+### API Routes (routes/api.php)
+
+- `/api/content/briefs` - Content brief CRUD
+- `/api/content/generate/*` - AI generation (rate limited)
+- `/api/content/media` - Media management
+- `/api/content/search` - Full-text search
+- `/api/content/webhooks/{endpoint}` - External webhooks (no auth, signature verified)
 
 ## Conventions
 
 - UK English (colour, organisation, centre)
-- PSR-12 coding style (Laravel Pint)
-- Pest for testing
-- Livewire + Flux Pro for UI
+- `declare(strict_types=1);` in all PHP files
+- Type hints on all parameters and return types
+- Pest for testing (not PHPUnit syntax)
+- Livewire + Flux Pro for UI components
+- Font Awesome Pro for icons (not Heroicons)
+
+## Rate Limiters
+
+Defined in `Boot::configureRateLimiting()`:
+- `content-generate` - AI generation (10/min authenticated)
+- `content-briefs` - Brief creation (30/min)
+- `content-webhooks` - Incoming webhooks (60/min per endpoint)
+- `content-search` - Search queries (configurable, default 60/min)
+
+## Configuration (config.php)
+
+Key settings exposed via environment:
+- `CONTENT_GENERATION_TIMEOUT` - AI generation timeout
+- `CONTENT_MAX_REVISIONS` - Revision limit per item
+- `CONTENT_SEARCH_BACKEND` - Search driver (database, scout_database, meilisearch)
+- `CONTENT_CACHE_TTL` - Content cache duration
 
 ## 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 (European Union Public Licence)
\ No newline at end of file