` system.
+
+## Files
+
+- **group.blade.php** -- Tab group container. Wraps tab triggers and manages selected state.
+- **panel.blade.php** -- Tab content panel. Shows/hides based on which tab is selected.
+
+## Usage
+
+```blade
+
+ General
+ Advanced
+
+General content
+Advanced content
+```
diff --git a/src/Core/Front/Components/View/Blade/table/CLAUDE.md b/src/Core/Front/Components/View/Blade/table/CLAUDE.md
new file mode 100644
index 0000000..2f475ac
--- /dev/null
+++ b/src/Core/Front/Components/View/Blade/table/CLAUDE.md
@@ -0,0 +1,28 @@
+# Blade/table
+
+Table sub-components for data tables.
+
+## Files
+
+- **cell.blade.php** -- Individual table cell (`| `)
+- **column.blade.php** -- Column header (` | `) with optional sorting
+- **columns.blade.php** -- Column header row container (``)
+- **row.blade.php** -- Table row (` `)
+- **rows.blade.php** -- Table body container (` | `)
+
+## Usage
+
+```blade
+
+
+ Name
+ Status
+
+
+
+ Item 1
+ Active
+
+
+
+```
diff --git a/src/Core/Front/Components/View/Blade/web/CLAUDE.md b/src/Core/Front/Components/View/Blade/web/CLAUDE.md
new file mode 100644
index 0000000..26715d9
--- /dev/null
+++ b/src/Core/Front/Components/View/Blade/web/CLAUDE.md
@@ -0,0 +1,11 @@
+# Blade/web
+
+Public-facing page templates for workspace websites. Registered under the `web::` namespace.
+
+## Files
+
+- **home.blade.php** -- Workspace homepage template
+- **page.blade.php** -- Generic content page template
+- **waitlist.blade.php** -- Pre-launch waitlist/signup page template
+
+These are rendered for workspace domains resolved by `FindDomainRecord` middleware. Used via `web::home`, `web::page`, `web::waitlist` view references.
diff --git a/src/Core/Front/Services/CLAUDE.md b/src/Core/Front/Services/CLAUDE.md
new file mode 100644
index 0000000..2b987d5
--- /dev/null
+++ b/src/Core/Front/Services/CLAUDE.md
@@ -0,0 +1,18 @@
+# Front/Services
+
+Shared services for the Front module.
+
+## Files
+
+- **DeviceDetectionService.php** -- User-Agent parser for device type, OS, browser, in-app browser, and bot detection. Detects 14 social platform in-app browsers (Instagram, Facebook, TikTok, Twitter, LinkedIn, Snapchat, Threads, Pinterest, Reddit, WeChat, LINE, Telegram, Discord, WhatsApp) plus generic WebView. Identifies strict content platforms (Meta, TikTok, Twitter, Snapchat, LinkedIn) and Meta-owned platforms. Platform-specific methods: `isInstagram()`, `isFacebook()`, `isTikTok()`, etc. Full parse returns `{device_type, os_name, browser_name, in_app_browser, is_in_app}`.
+
+## Usage
+
+```php
+$service = new DeviceDetectionService();
+$info = $service->parse($request->userAgent());
+
+if ($service->isStrictContentPlatform($ua)) {
+ // Hide restricted content for platform compliance
+}
+```
diff --git a/src/Core/Front/Stdio/CLAUDE.md b/src/Core/Front/Stdio/CLAUDE.md
new file mode 100644
index 0000000..dbe3975
--- /dev/null
+++ b/src/Core/Front/Stdio/CLAUDE.md
@@ -0,0 +1,7 @@
+# Front/Stdio
+
+Stdio frontage for terminal/pipe-based I/O.
+
+## Files
+
+- **Boot.php** -- ServiceProvider for stdin/stdout transport. Handles non-HTTP contexts: Artisan commands, MCP stdio transport (agents connecting via pipes), and interactive CLI tools. Currently a placeholder with empty command registration -- core CLI commands will be registered here. No HTTP middleware -- this is a different transport entirely.
diff --git a/src/Core/Front/Tests/Unit/CLAUDE.md b/src/Core/Front/Tests/Unit/CLAUDE.md
new file mode 100644
index 0000000..acf6a7e
--- /dev/null
+++ b/src/Core/Front/Tests/Unit/CLAUDE.md
@@ -0,0 +1,13 @@
+# Front/Tests/Unit
+
+Unit tests for the Front module.
+
+## Files
+
+- **DeviceDetectionServiceTest.php** -- Tests for `DeviceDetectionService`. Covers in-app browser detection (Instagram, Facebook, TikTok, Twitter, LinkedIn, Snapchat, Threads, Pinterest, Reddit, WeChat, WhatsApp), standard browser exclusion, platform-specific methods, strict content platform identification, Meta platform detection, display names, device type/OS/browser detection, bot detection, and full parse output. Uses PHPUnit DataProvider for UA string coverage.
+
+## Running
+
+```bash
+composer test -- --filter=DeviceDetectionServiceTest
+```
diff --git a/src/Core/Front/Web/Blade/components/CLAUDE.md b/src/Core/Front/Web/Blade/components/CLAUDE.md
new file mode 100644
index 0000000..988f95c
--- /dev/null
+++ b/src/Core/Front/Web/Blade/components/CLAUDE.md
@@ -0,0 +1,21 @@
+# Front/Web/Blade/components
+
+Anonymous Blade components for the public web frontage. Used via `` tag syntax.
+
+## Components
+
+- **nav-item.blade.php** -- Navigation list item with icon and active state highlighting.
+ - Props: `href` (required), `icon` (string|null), `active` (bool)
+ - Uses `` for icon rendering.
+
+- **page.blade.php** -- Simple page wrapper for public web pages with optional title and description.
+ - Props: `title` (string|null), `description` (string|null)
+ - Provides max-width container with responsive padding.
+
+## Usage
+
+```blade
+
+ Content here
+
+```
diff --git a/src/Core/Front/Web/Blade/layouts/CLAUDE.md b/src/Core/Front/Web/Blade/layouts/CLAUDE.md
new file mode 100644
index 0000000..147fac6
--- /dev/null
+++ b/src/Core/Front/Web/Blade/layouts/CLAUDE.md
@@ -0,0 +1,10 @@
+# Front/Web/Blade/layouts
+
+Layout templates for public web pages.
+
+## Files
+
+- **app.blade.php** -- Base HTML shell for public web pages. Includes dark mode support (cookie-based), CSRF meta tag, Vite assets (app.css + app.js), Flux appearance/scripts, and font loading via `layouts::partials.fonts`.
+ - Props: `title` (string, defaults to `core.app.name` config)
+ - Slots: `$head` (extra head content), `$scripts` (extra scripts before ``)
+ - Prevents white flash with inline critical CSS for dark mode.
diff --git a/src/Core/Front/Web/Boot.php b/src/Core/Front/Web/Boot.php
index 9de1177..f098906 100644
--- a/src/Core/Front/Web/Boot.php
+++ b/src/Core/Front/Web/Boot.php
@@ -15,9 +15,15 @@
use Core\Front\Web\Middleware\ResilientSession;
use Core\Headers\SecurityHeaders;
use Core\LifecycleEventProvider;
+use Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse;
+use Illuminate\Cookie\Middleware\EncryptCookies;
use Illuminate\Foundation\Configuration\Middleware;
+use Illuminate\Foundation\Http\Middleware\ValidateCsrfToken;
+use Illuminate\Routing\Middleware\SubstituteBindings;
+use Illuminate\Session\Middleware\StartSession;
use Illuminate\Support\Facades\Blade;
use Illuminate\Support\ServiceProvider;
+use Illuminate\View\Middleware\ShareErrorsFromSession;
/**
* Web frontage - public marketing stage.
@@ -33,13 +39,13 @@ class Boot extends ServiceProvider
public static function middleware(Middleware $middleware): void
{
$middleware->group('web', [
- \Illuminate\Cookie\Middleware\EncryptCookies::class,
- \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
- \Illuminate\Session\Middleware\StartSession::class,
+ EncryptCookies::class,
+ AddQueuedCookiesToResponse::class,
+ StartSession::class,
ResilientSession::class,
- \Illuminate\View\Middleware\ShareErrorsFromSession::class,
- \Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
- \Illuminate\Routing\Middleware\SubstituteBindings::class,
+ ShareErrorsFromSession::class,
+ ValidateCsrfToken::class,
+ SubstituteBindings::class,
SecurityHeaders::class,
FindDomainRecord::class,
]);
diff --git a/src/Core/Front/Web/CLAUDE.md b/src/Core/Front/Web/CLAUDE.md
new file mode 100644
index 0000000..bfb9267
--- /dev/null
+++ b/src/Core/Front/Web/CLAUDE.md
@@ -0,0 +1,21 @@
+# Front/Web
+
+Public-facing web frontage. Service provider that configures the `web` middleware group and registers `` Blade tag syntax.
+
+## Files
+
+- **Boot.php** -- ServiceProvider that configures the `web` middleware stack (cookies, session, CSRF, security headers, domain resolution), registers the `web::` Blade namespace, fires `WebRoutesRegistering` lifecycle event, and aliases `livewire` as `admin` for Flux compatibility.
+- **WebTagCompiler.php** -- Blade precompiler enabling `` tag syntax (like ``). Compiles to anonymous components in the `web::` namespace.
+
+## Middleware Stack
+
+The `web` group includes: EncryptCookies, AddQueuedCookiesToResponse, StartSession, ResilientSession, ShareErrorsFromSession, ValidateCsrfToken, SubstituteBindings, SecurityHeaders, FindDomainRecord.
+
+## Tag Syntax
+
+```blade
+Content here
+About
+```
+
+Resolves to anonymous components in `Web/Blade/components/` and `Components/View/Blade/web/`.
diff --git a/src/Core/Front/Web/Middleware/CLAUDE.md b/src/Core/Front/Web/Middleware/CLAUDE.md
new file mode 100644
index 0000000..8a0141f
--- /dev/null
+++ b/src/Core/Front/Web/Middleware/CLAUDE.md
@@ -0,0 +1,9 @@
+# Front/Web/Middleware
+
+HTTP middleware for public web requests.
+
+## Files
+
+- **FindDomainRecord.php** -- Resolves the current workspace from the incoming domain. Sets `workspace_model` and `workspace` attributes on the request. Core domains (base domain, www, localhost) pass through. Checks custom domains first, then subdomain slugs. Requires `Core\Tenant` module.
+- **RedirectIfAuthenticated.php** -- Redirects logged-in users away from guest-only pages (e.g., login). Redirects to `/` on the current domain instead of a global dashboard route.
+- **ResilientSession.php** -- Catches session corruption (decryption errors, DB failures) and recovers gracefully by clearing cookies and retrying. Prevents 503 errors from APP_KEY changes or session table issues. Returns JSON for AJAX requests.
diff --git a/src/Core/Front/Web/Middleware/FindDomainRecord.php b/src/Core/Front/Web/Middleware/FindDomainRecord.php
index b634723..6dfae3f 100644
--- a/src/Core/Front/Web/Middleware/FindDomainRecord.php
+++ b/src/Core/Front/Web/Middleware/FindDomainRecord.php
@@ -12,6 +12,7 @@
namespace Core\Front\Web\Middleware;
use Closure;
+use Core\Tenant\Models\Workspace;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
@@ -84,12 +85,12 @@ protected function isCoreDomain(string $host): bool
protected function resolveWorkspaceFromDomain(string $host): ?object
{
// Check if Tenant module is installed
- if (! class_exists(\Core\Tenant\Models\Workspace::class)) {
+ if (! class_exists(Workspace::class)) {
return null;
}
// Check for custom domain first
- $workspace = \Core\Tenant\Models\Workspace::where('domain', $host)->first();
+ $workspace = Workspace::where('domain', $host)->first();
if ($workspace) {
return $workspace;
}
@@ -104,7 +105,7 @@ protected function resolveWorkspaceFromDomain(string $host): ?object
if (count($parts) >= 1) {
$workspaceSlug = $parts[0];
- return \Core\Tenant\Models\Workspace::where('slug', $workspaceSlug)
+ return Workspace::where('slug', $workspaceSlug)
->where('is_active', true)
->first();
}
diff --git a/src/Core/Front/Web/Middleware/ResilientSession.php b/src/Core/Front/Web/Middleware/ResilientSession.php
index 04c562a..6493bab 100644
--- a/src/Core/Front/Web/Middleware/ResilientSession.php
+++ b/src/Core/Front/Web/Middleware/ResilientSession.php
@@ -13,6 +13,7 @@
use Closure;
use Illuminate\Contracts\Encryption\DecryptException;
+use Illuminate\Database\QueryException;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Symfony\Component\HttpFoundation\Response;
@@ -43,7 +44,7 @@ public function handle(Request $request, Closure $next): Response
return $next($request);
} catch (DecryptException $e) {
return $this->handleSessionError($request, $e, 'decrypt');
- } catch (\Illuminate\Database\QueryException $e) {
+ } catch (QueryException $e) {
// Only catch session-related query exceptions
if ($this->isSessionError($e)) {
return $this->handleSessionError($request, $e, 'database');
diff --git a/src/Core/Headers/CLAUDE.md b/src/Core/Headers/CLAUDE.md
new file mode 100644
index 0000000..6f79cab
--- /dev/null
+++ b/src/Core/Headers/CLAUDE.md
@@ -0,0 +1,72 @@
+# Headers
+
+HTTP security headers, CSP nonce generation, device detection, and GeoIP lookup.
+
+## What It Does
+
+Four concerns bundled as a single module:
+
+1. **SecurityHeaders** middleware -- Adds HSTS, CSP, Permissions-Policy, X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Referrer-Policy to all responses
+2. **CspNonceService** -- Per-request cryptographic nonce for inline scripts/styles, integrated with Vite
+3. **DetectDevice** -- User-Agent parsing for device type, OS, browser, in-app browser detection (14 platforms)
+4. **DetectLocation** -- GeoIP from CloudFlare headers, custom headers, or MaxMind database
+
+## Key Classes
+
+| Class | Purpose |
+|-------|---------|
+| `Boot` | ServiceProvider: config, singletons, Blade directives (`@cspnonce`, `@cspnoncevalue`), `csp_nonce()` helper, Livewire `header-configuration-manager` component |
+| `SecurityHeaders` | Middleware. CSP built from: base directives -> env overrides -> nonces -> CDN sources -> external services -> dev WebSocket -> report URI. Supports report-only mode |
+| `CspNonceService` | Generates one nonce per request (128-bit, base64). Auto-registers with `Vite::useCspNonce()`. Methods: `getNonce()`, `getCspNonceDirective()`, `getNonceAttribute()` |
+| `DetectDevice` | `parse($ua)` returns `{device_type, os_name, browser_name, in_app_browser, is_in_app}`. Helpers: `isBot()`, `isInstagram()`, `isFacebook()`, `isTikTok()`, `isMetaPlatform()`, `isStrictContentPlatform()` |
+| `DetectLocation` | `lookup($ip, $request)` returns `{country_code, region, city}`. Checks CF headers first, then MaxMind DB. Cached 24h. Skips private IPs |
+| `HeaderConfigurationManager` | Livewire component for admin-panel header config editing |
+
+## Testing Support
+
+| Class | Purpose |
+|-------|---------|
+| `HeaderAssertions` | Test assertion helpers for security headers |
+| `SecurityHeaderTester` | Pre-built test scenarios |
+
+## CSP Configuration
+
+Config in `config/headers.php` (published via Boot):
+
+```php
+'csp' => [
+ 'enabled' => env('SECURITY_CSP_ENABLED', true),
+ 'report_only' => env('SECURITY_CSP_REPORT_ONLY', false),
+ 'nonce_enabled' => env('SECURITY_CSP_NONCE_ENABLED', true),
+ 'directives' => [...],
+ 'environment' => [
+ 'local' => ['script-src' => ["'unsafe-inline'", "'unsafe-eval'"]],
+ ],
+ 'nonce_skip_environments' => ['local', 'development'],
+ 'external' => [
+ 'jsdelivr' => ['enabled' => env('SECURITY_CSP_JSDELIVR', false)],
+ 'google_analytics' => [...],
+ ],
+],
+```
+
+## Blade Usage
+
+```blade
+
+
+
+```
+
+## In-App Browser Detection
+
+Detects 14 platforms: Instagram, Facebook, TikTok, Twitter/X, LinkedIn, Snapchat, Pinterest, Reddit, Threads, WeChat, LINE, Telegram, Discord, WhatsApp, plus generic WebView fallback.
+
+Key distinction: `isStrictContentPlatform()` returns true for platforms that enforce content policies (useful for adult content warnings).
+
+## Integration
+
+- `SecurityHeaders` middleware is included in both `web` and `admin` middleware groups (configured in `Front/Web/Boot` and `Front/Admin/Boot`)
+- Nonces auto-removed in `nonce_skip_environments` to not break HMR/dev tools
+- HSTS only added in production
+- Dev environments get WebSocket sources for Vite HMR (`localhost:8080`)
diff --git a/src/Core/Headers/Livewire/CLAUDE.md b/src/Core/Headers/Livewire/CLAUDE.md
new file mode 100644
index 0000000..899f20c
--- /dev/null
+++ b/src/Core/Headers/Livewire/CLAUDE.md
@@ -0,0 +1,7 @@
+# Headers/Livewire/ — Header Configuration UI
+
+## Components
+
+| Component | Purpose |
+|-----------|---------|
+| `HeaderConfigurationManager` | Livewire component for managing security header configuration in the admin panel. Provides UI for configuring CSP directives, HSTS settings, Permissions Policy features, and other security headers. |
diff --git a/src/Core/Headers/Livewire/HeaderConfigurationManager.php b/src/Core/Headers/Livewire/HeaderConfigurationManager.php
index 9af1c9b..5f493f7 100644
--- a/src/Core/Headers/Livewire/HeaderConfigurationManager.php
+++ b/src/Core/Headers/Livewire/HeaderConfigurationManager.php
@@ -11,6 +11,7 @@
namespace Core\Headers\Livewire;
+use Illuminate\Contracts\View\View;
use Illuminate\Support\Facades\Config;
use Livewire\Component;
@@ -451,7 +452,7 @@ public function clearMessages(): void
/**
* Render the component.
*/
- public function render(): \Illuminate\Contracts\View\View
+ public function render(): View
{
return view('core::headers.livewire.header-configuration-manager');
}
diff --git a/src/Core/Headers/Testing/CLAUDE.md b/src/Core/Headers/Testing/CLAUDE.md
new file mode 100644
index 0000000..ef8889c
--- /dev/null
+++ b/src/Core/Headers/Testing/CLAUDE.md
@@ -0,0 +1,10 @@
+# Headers/Testing/ — Security Header Test Utilities
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `HeaderAssertions` | Trait with assertion methods for testing security headers in HTTP responses. Provides `assertHasSecurityHeaders()`, `assertCspContains()`, etc. |
+| `SecurityHeaderTester` | Standalone static helper for validating security headers. Can be used without traits for flexible testing scenarios. |
+
+Used by feature tests (`SecurityHeadersTest`) to verify CSP, HSTS, X-Frame-Options, and other security headers.
diff --git a/src/Core/Headers/Views/livewire/CLAUDE.md b/src/Core/Headers/Views/livewire/CLAUDE.md
new file mode 100644
index 0000000..f96d298
--- /dev/null
+++ b/src/Core/Headers/Views/livewire/CLAUDE.md
@@ -0,0 +1,7 @@
+# Headers/Views/livewire/ — Header Configuration Blade Template
+
+## Templates
+
+| File | Purpose |
+|------|---------|
+| `header-configuration-manager.blade.php` | Blade template for the `HeaderConfigurationManager` Livewire component. Renders the security header configuration form with CSP, HSTS, and Permissions Policy controls. |
diff --git a/src/Core/Helpers/CLAUDE.md b/src/Core/Helpers/CLAUDE.md
new file mode 100644
index 0000000..0242619
--- /dev/null
+++ b/src/Core/Helpers/CLAUDE.md
@@ -0,0 +1,39 @@
+# Core\Helpers
+
+Shared utility classes registered as singletons. The `Boot` service provider also registers backward-compat aliases from the old `App\Support\*` namespace.
+
+## Key Classes
+
+| Class | Purpose |
+|-------|---------|
+| `RecoveryCode` | Generates 2FA recovery codes (`XXXXX-XXXXX` format) |
+| `LoginRateLimiter` | Brute-force protection: 5 attempts / 60s per email+IP |
+| `RateLimit` | Generic sliding-window rate limiter (cache-backed) |
+| `PrivacyHelper` | GDPR IP anonymisation (truncation + daily-rotating SHA256 hashes) |
+| `HadesEncrypt` | Hybrid AES-256-GCM + RSA encryption of exceptions for error pages |
+| `File` | Base64-to-UploadedFile conversion, remote URL fetching, Content-Disposition parsing |
+| `Cdn` | CDN asset URL generation with optional `cdn.{domain}` subdomain and file-hash cache busting |
+| `UtmHelper` | UTM parameter extraction from Request, array, or URL string |
+| `TimezoneList` | Timezone list generator with GMT offset formatting, grouped by continent |
+| `HorizonStatus` | Laravel Horizon supervisor status check (inactive/paused/active) |
+| `SystemLogs` | Reads `storage/logs/*.log` files, caps at 3 MB per file |
+| `CommandResult` | Value object for remote command output (exitCode, output, error) |
+| `ServiceCollection` | Typed collection of service provider classes with group/filter/metadata methods |
+| `Log` | Social module logging facade, routes to configurable `social.log_channel` |
+
+## Sub-directory
+
+- `Rules/HexRule` -- Validation rule for hex colour codes (#fff or #ffffff). `forceFull` option rejects 3-digit codes.
+
+## Patterns
+
+- All classes are stateless or cache-backed -- no database models.
+- `PrivacyHelper` has two anonymisation levels: standard (last octet) and strong (last 2 octets). IPv6 is fully handled.
+- `HadesEncrypt` uses a hardcoded RSA public key (safe to commit) with env-var override. The HTML comment includes a whimsical "Hades" explanation for curious visitors.
+- `Boot::registerBackwardCompatAliases()` uses `class_alias` to map old `App\Support\*` names -- remove these once the migration is complete.
+
+## Integration
+
+- `PrivacyHelper` is used by Analytics Center and BioHost for consistent IP handling.
+- `RateLimit` cache keys are prefixed `social:` -- consider making this configurable.
+- `Cdn` reads from `config('cdn.enabled')` and `config('core.cdn.subdomain')`.
diff --git a/src/Core/Helpers/Rules/CLAUDE.md b/src/Core/Helpers/Rules/CLAUDE.md
new file mode 100644
index 0000000..7a897c6
--- /dev/null
+++ b/src/Core/Helpers/Rules/CLAUDE.md
@@ -0,0 +1,13 @@
+# Helpers/Rules/ — Custom Validation Rules
+
+## Rules
+
+| Rule | Purpose |
+|------|---------|
+| `HexRule` | Validates hexadecimal colour codes. Supports 3-digit (`#fff`) and 6-digit (`#ffffff`) formats. Hash symbol required. Constructor option `forceFull: true` rejects 3-digit codes. |
+
+Usage:
+```php
+'colour' => ['required', new HexRule()]
+'colour' => ['required', new HexRule(forceFull: true)]
+```
diff --git a/src/Core/Input/CLAUDE.md b/src/Core/Input/CLAUDE.md
new file mode 100644
index 0000000..46e09d2
--- /dev/null
+++ b/src/Core/Input/CLAUDE.md
@@ -0,0 +1,51 @@
+# Core\Input
+
+Pre-boot input sanitisation. Strips dangerous control characters from `$_GET` and `$_POST` before Laravel even creates the Request object.
+
+## Key Classes
+
+| Class | Purpose |
+|-------|---------|
+| `Input` | Static `capture()` method -- sanitises superglobals then delegates to `Request::capture()` |
+| `Sanitiser` | Configurable filter pipeline: Unicode NFC normalisation, control char stripping, HTML filtering, presets, max length, transformation hooks |
+
+## Sanitiser Pipeline
+
+Execution order per string value:
+
+1. Before hooks (global, then field-specific)
+2. Unicode NFC normalisation (via `intl` extension)
+3. Control character stripping (`FILTER_UNSAFE_RAW` + `FILTER_FLAG_STRIP_LOW`)
+4. HTML tag filtering (strip_tags with allowed tags)
+5. Preset application (email, url, phone, alpha, alphanumeric, numeric, slug)
+6. Additional schema-defined `filter_var` filters
+7. Max length enforcement (`mb_substr`)
+8. After hooks (global, then field-specific)
+9. Audit logging (if enabled and value changed)
+
+## Public API
+
+```php
+// Immutable builder pattern (returns cloned instance)
+$s = (new Sanitiser)
+ ->richText() // allow safe HTML tags
+ ->maxLength(1000) // truncate to 1000 chars
+ ->email('email_field') // apply email preset to specific field
+ ->slug('url_slug') // apply slug preset
+ ->beforeFilter(fn($v, $f) => trim($v))
+ ->transformField('username', fn($v) => strtolower($v));
+
+$clean = $s->filter(['email_field' => $raw, 'url_slug' => $raw2]);
+```
+
+## Conventions
+
+- **Sanitiser sanitises, Laravel validates.** This is explicitly called out in the class docblock.
+- Immutable: all `with*` / fluent methods return `clone $this`.
+- Presets are static and extensible via `Sanitiser::registerPreset()`.
+- The `*` wildcard key in schema applies to all fields as a default.
+- Field-specific schema merges over global (`*`) schema.
+
+## Tests
+
+Pest tests at `Tests/Unit/InputFilteringTest.php` cover: clean passthrough, control char stripping, full Unicode preservation (CJK, Arabic, Russian, emojis), and edge cases.
diff --git a/src/Core/Input/Tests/Unit/CLAUDE.md b/src/Core/Input/Tests/Unit/CLAUDE.md
new file mode 100644
index 0000000..cfadd77
--- /dev/null
+++ b/src/Core/Input/Tests/Unit/CLAUDE.md
@@ -0,0 +1,9 @@
+# Input/Tests/Unit/ — Input Filtering Tests
+
+## Test Files
+
+| File | Purpose |
+|------|---------|
+| `InputFilteringTest.php` | Pest unit tests for the `Sanitiser` class. Covers clean input passthrough (ASCII, punctuation, UTF-8), XSS prevention, SQL injection stripping, null byte removal, and edge cases. |
+
+Tests the WAF layer that `Core\Init` uses to sanitise `$_GET` and `$_POST` before Laravel processes the request.
diff --git a/src/Core/Lang/CLAUDE.md b/src/Core/Lang/CLAUDE.md
new file mode 100644
index 0000000..2997e7f
--- /dev/null
+++ b/src/Core/Lang/CLAUDE.md
@@ -0,0 +1,55 @@
+# Core\Lang
+
+Internationalisation subsystem with ICU message formatting, translation memory with fuzzy matching, TMX import/export, and translation coverage analysis.
+
+## Key Classes
+
+| Class | Purpose |
+|-------|---------|
+| `LangServiceProvider` | Auto-discovered provider: registers ICU formatter, TM, coverage, fallback chain, missing key validation |
+| `IcuMessageFormatter` | ICU MessageFormat support (plurals, select, number/date formatting) with intl fallback |
+| `Boot` | Empty marker class -- all work done in LangServiceProvider |
+
+### TranslationMemory/
+
+| Class | Purpose |
+|-------|---------|
+| `TranslationMemory` | Facade service: store, get, suggest (fuzzy), import/export TMX |
+| `FuzzyMatcher` | Multi-algorithm similarity: Levenshtein + token (Jaccard) + n-gram (Dice coefficient), configurable weights |
+| `TranslationMemoryEntry` | Immutable value object with quality scores (0.0-1.0), usage counts, metadata |
+| `JsonTranslationMemoryRepository` | File-backed repo: JSON files per locale pair, in-memory cache + dirty tracking |
+| `TranslationMemoryRepository` (contract) | Interface for storage backends (JSON, database) |
+| `TmxImporter` / `TmxExporter` | TMX 1.4b format import/export with locale normalisation and metadata preservation |
+
+### Coverage/
+
+| Class | Purpose |
+|-------|---------|
+| `TranslationCoverage` | Scans PHP/Blade/JS/Vue for translation keys, compares against lang files |
+| `TranslationCoverageReport` | Report object with missing/unused keys, per-locale stats, text/JSON output |
+
+### Console Commands
+
+- `lang:coverage` -- Find missing and unused translation keys
+- `lang:tm` -- Translation memory management (not fully read but registered)
+
+## Architecture
+
+- **Fallback chain**: `en_GB` -> `en` -> configured fallback. Built via `determineLocalesUsing()`.
+- **Missing key validation**: Only in local/dev/testing. Logs at configurable level, triggers `trigger_deprecation` in local.
+- **ICU formatter**: Caches compiled `MessageFormatter` instances (max 100, LRU eviction). Falls back to simple `{name}` placeholder replacement when intl is unavailable.
+- **Fuzzy matching**: Combined algorithm weights: Levenshtein 0.25, token 0.50, n-gram 0.25. Confidence = similarity * 0.7 + quality * 0.3.
+- **Translation Memory IDs**: Generated via `xxh128` hash of `sourceLocale:targetLocale:source`.
+
+## Configuration
+
+All under `config('core.lang.*')`:
+- `fallback_chain`, `validate_keys`, `log_missing_keys`, `missing_key_log_level`
+- `icu_enabled`
+- `translation_memory.enabled`, `translation_memory.driver` (json/database), `translation_memory.fuzzy.*`
+
+## Integration
+
+- Translations loaded under the `core` namespace: `__('core::core.brand.name')`
+- Override by publishing to `resources/lang/vendor/core/`
+- Translation files live in `en_GB/core.php` within this directory
diff --git a/src/Core/Lang/Console/Commands/CLAUDE.md b/src/Core/Lang/Console/Commands/CLAUDE.md
new file mode 100644
index 0000000..936503e
--- /dev/null
+++ b/src/Core/Lang/Console/Commands/CLAUDE.md
@@ -0,0 +1,10 @@
+# Lang/Console/Commands/ — Translation CLI Commands
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `TranslationCoverageCommand` | Reports translation coverage across the codebase. Scans code for translation key usage and compares against translation files to identify missing and unused keys. |
+| `TranslationMemoryCommand` | CLI interface for managing translation memory — view statistics, browse entries, import/export TMX files, fuzzy match queries. |
+
+Part of the Lang subsystem's developer tooling.
diff --git a/src/Core/Lang/Console/Commands/TranslationCoverageCommand.php b/src/Core/Lang/Console/Commands/TranslationCoverageCommand.php
index 1cc95ed..ce20d14 100644
--- a/src/Core/Lang/Console/Commands/TranslationCoverageCommand.php
+++ b/src/Core/Lang/Console/Commands/TranslationCoverageCommand.php
@@ -12,7 +12,10 @@
namespace Core\Lang\Console\Commands;
use Core\Lang\Coverage\TranslationCoverage;
+use Core\Lang\Coverage\TranslationCoverageReport;
use Illuminate\Console\Command;
+use Symfony\Component\Console\Completion\CompletionInput;
+use Symfony\Component\Console\Completion\CompletionSuggestions;
/**
* Report translation coverage across the codebase.
@@ -164,7 +167,7 @@ protected function displaySummary(array $summary): void
/**
* Display per-locale statistics.
*
- * @param \Core\Lang\Coverage\TranslationCoverageReport $report
+ * @param TranslationCoverageReport $report
*/
protected function displayLocaleStats($report): void
{
@@ -201,7 +204,7 @@ protected function displayLocaleStats($report): void
/**
* Display missing keys.
*
- * @param \Core\Lang\Coverage\TranslationCoverageReport $report
+ * @param TranslationCoverageReport $report
*/
protected function displayMissingKeys($report, bool $verbose): void
{
@@ -241,7 +244,7 @@ protected function displayMissingKeys($report, bool $verbose): void
/**
* Display unused keys.
*
- * @param \Core\Lang\Coverage\TranslationCoverageReport $report
+ * @param TranslationCoverageReport $report
*/
protected function displayUnusedKeys($report, bool $verbose): void
{
@@ -291,8 +294,8 @@ protected function shortenPath(string $path): string
* Get shell completion suggestions.
*/
public function complete(
- \Symfony\Component\Console\Completion\CompletionInput $input,
- \Symfony\Component\Console\Completion\CompletionSuggestions $suggestions
+ CompletionInput $input,
+ CompletionSuggestions $suggestions
): void {
if ($input->mustSuggestOptionValuesFor('locale')) {
// Suggest available locales
diff --git a/src/Core/Lang/Console/Commands/TranslationMemoryCommand.php b/src/Core/Lang/Console/Commands/TranslationMemoryCommand.php
index 9958769..5eeadac 100644
--- a/src/Core/Lang/Console/Commands/TranslationMemoryCommand.php
+++ b/src/Core/Lang/Console/Commands/TranslationMemoryCommand.php
@@ -11,8 +11,11 @@
namespace Core\Lang\Console\Commands;
+use Core\Lang\TranslationMemory\FuzzyMatcher;
use Core\Lang\TranslationMemory\TranslationMemory;
use Illuminate\Console\Command;
+use Symfony\Component\Console\Completion\CompletionInput;
+use Symfony\Component\Console\Completion\CompletionSuggestions;
/**
* Translation Memory management command.
@@ -388,7 +391,7 @@ protected function handleSuggest(TranslationMemory $tm): int
$confidence = $suggestion['confidence'];
$similarityColor = $similarity >= 0.9 ? 'green' : ($similarity >= 0.75 ? 'yellow' : 'red');
- $category = \Core\Lang\TranslationMemory\FuzzyMatcher::categorizeSimilarity($similarity);
+ $category = FuzzyMatcher::categorizeSimilarity($similarity);
$this->line(" ".sprintf('%.0f%%', $similarity * 100).' match ('.$category.')');
$this->line(" Source: {$entry->getSource()}");
@@ -566,8 +569,8 @@ protected function formatBytes(int $bytes): string
* Get shell completion suggestions.
*/
public function complete(
- \Symfony\Component\Console\Completion\CompletionInput $input,
- \Symfony\Component\Console\Completion\CompletionSuggestions $suggestions
+ CompletionInput $input,
+ CompletionSuggestions $suggestions
): void {
if ($input->mustSuggestArgumentValuesFor('action')) {
$suggestions->suggestValues([
diff --git a/src/Core/Lang/Coverage/CLAUDE.md b/src/Core/Lang/Coverage/CLAUDE.md
new file mode 100644
index 0000000..a566f93
--- /dev/null
+++ b/src/Core/Lang/Coverage/CLAUDE.md
@@ -0,0 +1,10 @@
+# Lang/Coverage/ — Translation Coverage Analysis
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `TranslationCoverage` | Scans PHP, Blade, and JS/Vue files for translation key usage (`__()`, `trans()`, `@lang`, etc.) and compares against translation files. Reports missing keys (used but undefined) and unused keys (defined but unused). |
+| `TranslationCoverageReport` | DTO containing analysis results — missing keys, unused keys, coverage statistics per locale, and usage locations. Implements `Arrayable`. |
+
+Used by the `lang:coverage` Artisan command for translation quality assurance.
diff --git a/src/Core/Lang/TranslationMemory/CLAUDE.md b/src/Core/Lang/TranslationMemory/CLAUDE.md
new file mode 100644
index 0000000..0e77121
--- /dev/null
+++ b/src/Core/Lang/TranslationMemory/CLAUDE.md
@@ -0,0 +1,14 @@
+# Lang/TranslationMemory/ — Translation Memory System
+
+Stores and retrieves previous translations for reuse and consistency.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `TranslationMemory` | Unified service — store, retrieve, suggest translations. Supports exact and fuzzy matching with confidence scoring. |
+| `TranslationMemoryEntry` | DTO for a single translation unit — source text, target text, metadata, quality score (0.0-1.0). |
+| `FuzzyMatcher` | Finds similar translations via Levenshtein distance, token/word matching, and n-gram matching. Combines with quality score for confidence rating. |
+| `JsonTranslationMemoryRepository` | File-based storage backend — JSON files organised by locale pairs. |
+| `TmxExporter` | Exports to TMX (Translation Memory eXchange) standard XML format. |
+| `TmxImporter` | Imports from TMX files for interoperability with other translation tools. |
diff --git a/src/Core/Lang/TranslationMemory/Contracts/CLAUDE.md b/src/Core/Lang/TranslationMemory/Contracts/CLAUDE.md
new file mode 100644
index 0000000..ef180cf
--- /dev/null
+++ b/src/Core/Lang/TranslationMemory/Contracts/CLAUDE.md
@@ -0,0 +1,9 @@
+# Lang/TranslationMemory/Contracts/ — TM Repository Interface
+
+## Interfaces
+
+| Interface | Purpose |
+|-----------|---------|
+| `TranslationMemoryRepository` | Storage backend contract. Methods: `store(entry)`, `find(source, locale)`, `search(query, locale)`, `all(locale)`, `delete(id)`. Implementations may use JSON files, databases, or external services. |
+
+The default implementation is `JsonTranslationMemoryRepository`.
diff --git a/src/Core/Lang/en_GB/CLAUDE.md b/src/Core/Lang/en_GB/CLAUDE.md
new file mode 100644
index 0000000..da004f1
--- /dev/null
+++ b/src/Core/Lang/en_GB/CLAUDE.md
@@ -0,0 +1,9 @@
+# Lang/en_GB/ — British English Translations
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `core.php` | British English translation strings for the Core framework. Returns a keyed array of translatable strings used throughout the UI, emails, and error messages. |
+
+This is the primary locale — the framework uses UK English as its base language (colour, organisation, centre).
diff --git a/src/Core/LifecycleEventProvider.php b/src/Core/LifecycleEventProvider.php
index 8ff9ee9..af6160c 100644
--- a/src/Core/LifecycleEventProvider.php
+++ b/src/Core/LifecycleEventProvider.php
@@ -20,6 +20,8 @@
use Core\Events\McpToolsRegistering;
use Core\Events\QueueWorkerBooting;
use Core\Events\WebRoutesRegistering;
+use Core\Front\Mcp\Contracts\McpToolHandler;
+use Illuminate\Routing\Router;
use Illuminate\Support\Facades\Route;
use Illuminate\Support\ServiceProvider;
use Livewire\Livewire;
@@ -252,7 +254,7 @@ public function boot(): void
*/
protected static function processMiddleware(Events\LifecycleEvent $event): void
{
- /** @var \Illuminate\Routing\Router $router */
+ /** @var Router $router */
$router = app('router');
foreach ($event->middlewareRequests() as [$alias, $class]) {
@@ -484,7 +486,7 @@ public static function fireMcpRoutes(): void
*
* @return array Fully qualified class names of McpToolHandler implementations
*
- * @see \Core\Front\Mcp\Contracts\McpToolHandler (in php-mcp package)
+ * @see McpToolHandler (in php-mcp package)
*/
public static function fireMcpTools(): array
{
diff --git a/src/Core/Mail/CLAUDE.md b/src/Core/Mail/CLAUDE.md
new file mode 100644
index 0000000..50c4370
--- /dev/null
+++ b/src/Core/Mail/CLAUDE.md
@@ -0,0 +1,49 @@
+# Core\Mail
+
+Email validation and disposable domain blocking service with statistics tracking.
+
+## Key Classes
+
+| Class | Purpose |
+|-------|---------|
+| `EmailShield` | Main service: validate emails, block disposable domains, MX lookup, normalisation, async validation |
+| `EmailShieldStat` | Eloquent model for daily validation stats (valid/invalid/disposable counts) |
+| `EmailValidationResult` | Value object with named constructors: `valid()`, `invalid()`, `disposable()` |
+| `Rules\ValidatedEmail` | Laravel validation rule wrapping EmailShield |
+| `Boot` | Service provider: registers EmailShield singleton + backward-compat aliases |
+
+## EmailShield Features
+
+- **Disposable domain blocking**: 100k+ domains from community-maintained GitHub list, cached 24h, stored at `storage/app/email-shield/disposable-domains.txt`
+- **MX record validation**: Cached 1h per domain, suppresses DNS warnings
+- **Validation caching**: Results cached 5 min to avoid repeated checks
+- **Email normalisation**: Gmail dot-stripping, plus-addressing removal, googlemail.com -> gmail.com
+- **Async validation**: Immediate format+disposable check, queues MX lookup for background processing
+- **Statistics**: Atomic daily counters via `insertOrIgnore` + `increment`
+
+## Public API
+
+```php
+$shield = app(EmailShield::class);
+
+// Validate
+$result = $shield->validate('user@example.com'); // EmailValidationResult
+$result->passes(); // bool
+$result->isDisposable; // bool
+
+// Normalise
+$shield->normalize('J.O.H.N+spam@gmail.com'); // 'john@gmail.com'
+$shield->isSameMailbox('john@gmail.com', 'j.o.h.n@googlemail.com'); // true
+
+// Update blocklist
+$shield->updateDisposableDomainsList();
+
+// In validation rules
+'email' => ['required', new ValidatedEmail(blockDisposable: true)]
+```
+
+## Conventions
+
+- Disposable domain list update validates minimum 100 domains to prevent corrupted lists.
+- `EmailShieldStat::pruneOldRecords(90)` for cleanup (called by Console PruneEmailShieldStatsCommand).
+- Backward-compat aliases map `App\Services\Email\*` to `Core\Mail\*`.
diff --git a/src/Core/Mail/Rules/CLAUDE.md b/src/Core/Mail/Rules/CLAUDE.md
new file mode 100644
index 0000000..0a7afee
--- /dev/null
+++ b/src/Core/Mail/Rules/CLAUDE.md
@@ -0,0 +1,14 @@
+# Mail/Rules/ — Email Validation Rules
+
+## Rules
+
+| Rule | Purpose |
+|------|---------|
+| `ValidatedEmail` | Laravel validation rule using the `EmailShield` service. Validates email format and optionally blocks disposable email domains. Constructor takes `blockDisposable: true` (default). |
+
+Usage:
+```php
+'email' => ['required', new ValidatedEmail(blockDisposable: true)]
+```
+
+Part of the Mail subsystem's input validation layer.
diff --git a/src/Core/Media/Abstracts/CLAUDE.md b/src/Core/Media/Abstracts/CLAUDE.md
new file mode 100644
index 0000000..d033935
--- /dev/null
+++ b/src/Core/Media/Abstracts/CLAUDE.md
@@ -0,0 +1,10 @@
+# Media/Abstracts/ — Media Base Classes
+
+## Abstract Classes
+
+| Class | Purpose |
+|-------|---------|
+| `Image` | Base class for image handling operations. |
+| `MediaConversion` | Abstract base for all media conversions (image resizing, thumbnail generation, video processing). Provides common functionality: queueing for large files (threshold configurable via `media.queue_threshold_mb`), progress reporting via `ConversionProgress` event, and storage abstraction. |
+
+Concrete implementations in `Core\Media\Conversions\`.
diff --git a/src/Core/Media/Abstracts/MediaConversion.php b/src/Core/Media/Abstracts/MediaConversion.php
index 9e4fe2e..f0a779a 100644
--- a/src/Core/Media/Abstracts/MediaConversion.php
+++ b/src/Core/Media/Abstracts/MediaConversion.php
@@ -15,6 +15,7 @@
use Core\Media\Jobs\ProcessMediaConversion;
use Core\Media\Support\ConversionProgressReporter;
use Core\Media\Support\MediaConversionData;
+use Illuminate\Contracts\Filesystem\Filesystem;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Str;
@@ -463,7 +464,7 @@ protected function buildQueueOptions(): array
/**
* Get a filesystem instance for the given disk.
*/
- protected function filesystem(string $disk): \Illuminate\Contracts\Filesystem\Filesystem
+ protected function filesystem(string $disk): Filesystem
{
return Storage::disk($disk);
}
diff --git a/src/Core/Media/CLAUDE.md b/src/Core/Media/CLAUDE.md
new file mode 100644
index 0000000..caecb3a
--- /dev/null
+++ b/src/Core/Media/CLAUDE.md
@@ -0,0 +1,39 @@
+# Core\Media
+
+Image processing, media conversion pipeline, and on-demand thumbnail generation.
+
+## Directory Structure
+
+```
+Media/
+ Abstracts/ MediaConversion base class, Image abstract
+ Conversions/ MediaImageResizerConversion, MediaVideoThumbConversion
+ Events/ ConversionProgress event
+ Image/ ImageOptimization, ImageOptimizer, ExifStripper, ModernFormatSupport, OptimizationResult
+ Jobs/ GenerateThumbnail, ProcessMediaConversion
+ Routes/ web.php (thumbnail routes)
+ Support/ ConversionProgressReporter, TemporaryFile, TemporaryDirectory, ImageResizer, MediaConversionData
+ Thumbnail/ ThumbnailController, LazyThumbnail, helpers.php
+ Boot.php Service provider
+ config.php Media configuration
+```
+
+## Key Concepts
+
+- **Media Conversions**: Abstract pipeline (`MediaConversion`) for processing uploaded media. Concrete implementations handle image resizing and video thumbnail extraction.
+- **Thumbnail System**: On-demand thumbnail generation via `ThumbnailController` with `LazyThumbnail` for deferred processing. Routes registered in `Routes/web.php`.
+- **Image Optimization**: `ImageOptimizer` handles format conversion, EXIF stripping, and compression. `ModernFormatSupport` detects WebP/AVIF browser support.
+- **Progress Reporting**: `ConversionProgressReporter` + `ConversionProgress` event for tracking long-running media conversions.
+- **Temporary Files**: `TemporaryFile` and `TemporaryDirectory` helpers for safe cleanup of processing artifacts.
+
+## Jobs
+
+- `GenerateThumbnail` -- Queued job for thumbnail generation
+- `ProcessMediaConversion` -- Queued job for media conversion pipeline
+
+## Integration
+
+- Boot provider registers config from `config.php`
+- Thumbnail routes are web routes (not API)
+- Conversion data flows through `MediaConversionData` DTO
+- `ImageResizer` in Support handles the actual resize operations
diff --git a/src/Core/Media/Conversions/CLAUDE.md b/src/Core/Media/Conversions/CLAUDE.md
new file mode 100644
index 0000000..630e15e
--- /dev/null
+++ b/src/Core/Media/Conversions/CLAUDE.md
@@ -0,0 +1,12 @@
+# Media/Conversions/ — Media Conversion Implementations
+
+Concrete implementations of `MediaConversion` for specific processing tasks.
+
+## Conversions
+
+| Class | Purpose |
+|-------|---------|
+| `MediaImageResizerConversion` | Resizes images to specified dimensions while maintaining aspect ratio. Prevents upscaling. Skips GIF files to preserve animation. Uses `ImageResizer`. |
+| `MediaVideoThumbConversion` | Extracts thumbnail frames from video files for preview display. |
+
+Both extend `Core\Media\Abstracts\MediaConversion` and can be queued via `ProcessMediaConversion` job.
diff --git a/src/Core/Media/Events/CLAUDE.md b/src/Core/Media/Events/CLAUDE.md
new file mode 100644
index 0000000..5642b47
--- /dev/null
+++ b/src/Core/Media/Events/CLAUDE.md
@@ -0,0 +1,7 @@
+# Media/Events/ — Media System Events
+
+## Events
+
+| Event | Fired When | Purpose |
+|-------|-----------|---------|
+| `ConversionProgress` | During media conversion processing | Reports progress stages for UI progress bars, logging, and monitoring. |
diff --git a/src/Core/Media/Image/CLAUDE.md b/src/Core/Media/Image/CLAUDE.md
new file mode 100644
index 0000000..15a79ef
--- /dev/null
+++ b/src/Core/Media/Image/CLAUDE.md
@@ -0,0 +1,13 @@
+# Media/Image/ — Image Processing
+
+Image optimisation and processing utilities.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `ImageOptimizer` | Main optimiser — resizes, compresses, and converts images. Includes memory safety checks (GD needs 5-6x image size). |
+| `ImageOptimization` | Optimisation configuration and pipeline orchestration. |
+| `ExifStripper` | Removes EXIF metadata from images for privacy (GPS coordinates, camera info). |
+| `ModernFormatSupport` | Detects and enables WebP/AVIF support based on server capabilities. |
+| `OptimizationResult` | DTO containing optimisation results — original size, optimised size, savings percentage, format used. |
diff --git a/src/Core/Media/Image/ImageOptimization.php b/src/Core/Media/Image/ImageOptimization.php
index e30c242..831941f 100644
--- a/src/Core/Media/Image/ImageOptimization.php
+++ b/src/Core/Media/Image/ImageOptimization.php
@@ -15,6 +15,7 @@
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\MorphTo;
+use Illuminate\Support\Carbon;
/**
* Image optimisation record.
@@ -30,8 +31,8 @@
* @property int|null $workspace_id
* @property string|null $optimizable_type
* @property int|null $optimizable_id
- * @property \Illuminate\Support\Carbon|null $created_at
- * @property \Illuminate\Support\Carbon|null $updated_at
+ * @property Carbon|null $created_at
+ * @property Carbon|null $updated_at
*/
class ImageOptimization extends Model
{
diff --git a/src/Core/Media/Jobs/CLAUDE.md b/src/Core/Media/Jobs/CLAUDE.md
new file mode 100644
index 0000000..1b4ecc1
--- /dev/null
+++ b/src/Core/Media/Jobs/CLAUDE.md
@@ -0,0 +1,8 @@
+# Media/Jobs/ — Media Background Jobs
+
+## Jobs
+
+| Job | Purpose |
+|-----|---------|
+| `ProcessMediaConversion` | Queued job for running media conversions asynchronously. Dispatches `ConversionProgress` events during processing. Logs failures. |
+| `GenerateThumbnail` | Queued job for generating thumbnails on demand. Called by `LazyThumbnail` when a thumbnail doesn't exist yet. |
diff --git a/src/Core/Media/Routes/CLAUDE.md b/src/Core/Media/Routes/CLAUDE.md
new file mode 100644
index 0000000..824dfce
--- /dev/null
+++ b/src/Core/Media/Routes/CLAUDE.md
@@ -0,0 +1,7 @@
+# Media/Routes/ — Media Web Routes
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `web.php` | Web route definitions for media serving — thumbnail endpoints, image serving routes. Registered via the `WebRoutesRegistering` lifecycle event. |
diff --git a/src/Core/Media/Support/CLAUDE.md b/src/Core/Media/Support/CLAUDE.md
new file mode 100644
index 0000000..6b7aac4
--- /dev/null
+++ b/src/Core/Media/Support/CLAUDE.md
@@ -0,0 +1,11 @@
+# Media/Support/ — Media Processing Utilities
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `ImageResizer` | Image resizing with aspect ratio preservation and memory safety checks. Prevents upscaling and OOM crashes. |
+| `ConversionProgressReporter` | Reports media conversion progress to listeners via `ConversionProgress` event. |
+| `MediaConversionData` | DTO carrying conversion parameters — source path, output path, dimensions, format, quality. |
+| `TemporaryDirectory` | Manages temporary directories for media processing with automatic cleanup. |
+| `TemporaryFile` | Manages temporary files for media processing with automatic cleanup. |
diff --git a/src/Core/Media/Thumbnail/CLAUDE.md b/src/Core/Media/Thumbnail/CLAUDE.md
new file mode 100644
index 0000000..14a6760
--- /dev/null
+++ b/src/Core/Media/Thumbnail/CLAUDE.md
@@ -0,0 +1,11 @@
+# Media/Thumbnail/ — Lazy Thumbnail Generation
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `LazyThumbnail` | On-demand thumbnail generation service. Generates thumbnails when first requested rather than eagerly on upload. Caches generated thumbnails. Dispatches `GenerateThumbnail` job for async processing. |
+| `ThumbnailController` | HTTP controller serving thumbnail requests. Generates on-the-fly if not cached. |
+| `helpers.php` | Helper functions for thumbnail URL generation in Blade templates. |
+
+Thumbnails are generated lazily to avoid processing overhead on upload and to only create sizes that are actually requested.
diff --git a/src/Core/Rules/CLAUDE.md b/src/Core/Rules/CLAUDE.md
new file mode 100644
index 0000000..5a5099b
--- /dev/null
+++ b/src/Core/Rules/CLAUDE.md
@@ -0,0 +1,51 @@
+# Core\Rules
+
+Security-focused Laravel validation rules. No service provider -- use directly in validation arrays.
+
+## Rules
+
+### SafeWebhookUrl
+
+SSRF protection for webhook delivery URLs.
+
+**Blocks:**
+- Localhost and loopback (127.0.0.0/8, ::1)
+- Private networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
+- Link-local, reserved ranges, special-use addresses
+- Local domain names (.local, .localhost, .internal)
+- Decimal IP encoding (2130706433 = 127.0.0.1)
+- IPv4-mapped IPv6 (::ffff:127.0.0.1)
+- Non-HTTPS schemes
+
+**Service mode:** Optionally restrict to known webhook domains (Discord, Slack, Telegram). Known service domains skip SSRF checks.
+
+```php
+'url' => [new SafeWebhookUrl] // any HTTPS, no SSRF
+'url' => [new SafeWebhookUrl('discord')] // discord.com/discordapp.com only
+```
+
+### SafeJsonPayload
+
+Protects against malicious JSON payloads stored in the database.
+
+**Validates:**
+- Maximum total size (default 10 KB)
+- Maximum nesting depth (default 3)
+- Maximum total keys across all levels (default 50)
+- Maximum string value length (default 1000 chars)
+
+**Factory methods:**
+- `SafeJsonPayload::default()` -- 10 KB, depth 3, 50 keys
+- `SafeJsonPayload::small()` -- 2 KB, depth 2, 20 keys
+- `SafeJsonPayload::large()` -- 100 KB, depth 5, 200 keys
+- `SafeJsonPayload::metadata()` -- 5 KB, depth 2, 30 keys, 256 char strings
+
+```php
+'payload' => ['array', SafeJsonPayload::metadata()]
+```
+
+## Conventions
+
+- Both rules implement `Illuminate\Contracts\Validation\ValidationRule`.
+- `SafeWebhookUrl` resolves hostnames and checks ALL returned IPs against blocklists.
+- These are standalone -- no Boot provider, no config. Import and use directly.
diff --git a/src/Core/Search/Analytics/CLAUDE.md b/src/Core/Search/Analytics/CLAUDE.md
new file mode 100644
index 0000000..0435491
--- /dev/null
+++ b/src/Core/Search/Analytics/CLAUDE.md
@@ -0,0 +1,15 @@
+# Search/Analytics/ — Search Analytics
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SearchAnalytics` | Tracks search queries, results, and user interactions. Features: query tracking with timestamps and result counts, click-through tracking, zero-result query tracking for content gap analysis, popular search trending. |
+
+Part of the Search subsystem. Data feeds into `SearchSuggestions` for autocomplete.
+
+## Migrations
+
+| File | Purpose |
+|------|---------|
+| `migrations/2024_01_01_000001_create_search_analytics_tables.php` | Creates tables for search query tracking, result counts, and click-through data. |
diff --git a/src/Core/Search/Analytics/SearchAnalytics.php b/src/Core/Search/Analytics/SearchAnalytics.php
index 03a248c..3582211 100644
--- a/src/Core/Search/Analytics/SearchAnalytics.php
+++ b/src/Core/Search/Analytics/SearchAnalytics.php
@@ -11,6 +11,7 @@
namespace Core\Search\Analytics;
+use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
@@ -210,9 +211,9 @@ public function trackClick(
*
* @param int $limit Maximum number of queries to return
* @param int $days Number of days to look back
- * @return \Illuminate\Support\Collection
+ * @return Collection
*/
- public function getPopularQueries(int $limit = 10, int $days = 7): \Illuminate\Support\Collection
+ public function getPopularQueries(int $limit = 10, int $days = 7): Collection
{
if (! $this->isEnabled()) {
return collect();
@@ -232,9 +233,9 @@ public function getPopularQueries(int $limit = 10, int $days = 7): \Illuminate\S
*
* @param int $limit Maximum number of queries to return
* @param int $days Number of days to look back
- * @return \Illuminate\Support\Collection
+ * @return Collection
*/
- public function getZeroResultQueries(int $limit = 20, int $days = 30): \Illuminate\Support\Collection
+ public function getZeroResultQueries(int $limit = 20, int $days = 30): Collection
{
if (! $this->isEnabled()) {
return collect();
@@ -254,9 +255,9 @@ public function getZeroResultQueries(int $limit = 20, int $days = 30): \Illumina
* Get search trend over time.
*
* @param int $days Number of days to look back
- * @return \Illuminate\Support\Collection
+ * @return Collection
*/
- public function getTrend(int $days = 30): \Illuminate\Support\Collection
+ public function getTrend(int $days = 30): Collection
{
if (! $this->isEnabled()) {
return collect();
diff --git a/src/Core/Search/Analytics/migrations/CLAUDE.md b/src/Core/Search/Analytics/migrations/CLAUDE.md
new file mode 100644
index 0000000..757dd6a
--- /dev/null
+++ b/src/Core/Search/Analytics/migrations/CLAUDE.md
@@ -0,0 +1,7 @@
+# Search/Analytics/migrations/ — Search Analytics Schema
+
+## Migrations
+
+| File | Purpose |
+|------|---------|
+| `2024_01_01_000001_create_search_analytics_tables.php` | Creates tables for search query tracking, result counts, and click-through data used by the `SearchAnalytics` service. |
diff --git a/src/Core/Search/Boot.php b/src/Core/Search/Boot.php
index f67ade4..be8042e 100644
--- a/src/Core/Search/Boot.php
+++ b/src/Core/Search/Boot.php
@@ -11,6 +11,7 @@
namespace Core\Search;
+use App\Services\Search\UnifiedSearchService;
use Core\Search\Analytics\SearchAnalytics;
use Core\Search\Suggestions\SearchSuggestions;
use Illuminate\Support\ServiceProvider;
@@ -72,8 +73,8 @@ protected function publishConfig(): void
*/
protected function registerBackwardCompatAliases(): void
{
- if (! class_exists(\App\Services\Search\UnifiedSearchService::class)) {
- class_alias(Unified::class, \App\Services\Search\UnifiedSearchService::class);
+ if (! class_exists(UnifiedSearchService::class)) {
+ class_alias(Unified::class, UnifiedSearchService::class);
}
}
}
diff --git a/src/Core/Search/CLAUDE.md b/src/Core/Search/CLAUDE.md
new file mode 100644
index 0000000..9525e99
--- /dev/null
+++ b/src/Core/Search/CLAUDE.md
@@ -0,0 +1,62 @@
+# Core\Search
+
+Unified search across system components with analytics tracking, autocomplete suggestions, and result highlighting.
+
+## Key Classes
+
+| Class | Purpose |
+|-------|---------|
+| `Unified` | Main search service: searches MCP tools/resources, API endpoints, patterns, assets, todos, agent plans |
+| `Analytics\SearchAnalytics` | Tracks queries, clicks, zero-result queries, trends. Privacy-aware (daily-rotating IP hashes, sensitive pattern exclusion) |
+| `Suggestions\SearchSuggestions` | Autocomplete from popular queries, recent searches, and content. Logarithmic popularity scoring |
+| `Support\SearchHighlighter` | Highlights matched terms in results with configurable HTML wrapper, snippet extraction with context |
+| `Boot` | Service provider: merges config, registers singletons, loads migrations |
+
+## Search Sources (Unified)
+
+| Type | Source | Model/Data |
+|------|--------|------------|
+| `mcp_tool` | YAML files | `resource_path('mcp/servers/*.yaml')` |
+| `mcp_resource` | YAML files | Same |
+| `api_endpoint` | Config | `config('core.search.api_endpoints')` |
+| `pattern` | Database | `Core\Mod\Uptelligence\Models\Pattern` |
+| `asset` | Database | `Core\Mod\Uptelligence\Models\Asset` |
+| `todo` | Database | `Core\Mod\Uptelligence\Models\UpstreamTodo` |
+| `plan` | Database | `Core\Mod\Agentic\Models\AgentPlan` |
+
+## Scoring Algorithm
+
+Configurable weights via `config/search.php`:
+- Exact match: 20 (30 if field equals query exactly)
+- Starts-with: 15
+- Word match: 5 (7.5 for exact word)
+- Position factor: earlier fields in the array score higher
+- Fuzzy: Levenshtein distance, 0.5x score multiplier, min 4 char query
+
+## Analytics
+
+- Queries stored in `search_analytics` table with `query_hash` (xxh3) for grouping
+- Click tracking in `search_analytics_clicks`
+- Sensitive patterns excluded: password, secret, token, key, credit, ssn
+- IP hashed with daily-rotating salt
+- `prune()` respects `retention_days` config (default 90)
+
+## Suggestions
+
+Three sources (configurable priority): `popular`, `recent`, `content`
+- Popular: From analytics, log-scale scoring, queries with results only
+- Recent: Per-user cache (30 days), session fallback for guests
+- Content: Prefix matching on model names
+- Trending: Growth comparison between recent and earlier period
+
+## Configuration
+
+All in `config/search.php` (publishable):
+- `scoring.*` -- match weights
+- `fuzzy.*` -- Levenshtein settings
+- `suggestions.*` -- autocomplete settings
+- `analytics.*` -- tracking and retention
+
+## LIKE injection protection
+
+`escapeLikeQuery()` escapes `%` and `_` wildcards. If more than 3 wildcards, strips them entirely to prevent DoS.
diff --git a/src/Core/Search/Suggestions/CLAUDE.md b/src/Core/Search/Suggestions/CLAUDE.md
new file mode 100644
index 0000000..5b47673
--- /dev/null
+++ b/src/Core/Search/Suggestions/CLAUDE.md
@@ -0,0 +1,9 @@
+# Search/Suggestions/ — Search Autocomplete
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SearchSuggestions` | Type-ahead suggestion service. Sources: popular queries from SearchAnalytics, recent searches (per user/session), prefix matching, content-based suggestions from searchable items. Cached for performance. |
+
+Part of the Search subsystem. Provides autocomplete data for search UIs.
diff --git a/src/Core/Search/Suggestions/SearchSuggestions.php b/src/Core/Search/Suggestions/SearchSuggestions.php
index 7a2aacd..4c33d4d 100644
--- a/src/Core/Search/Suggestions/SearchSuggestions.php
+++ b/src/Core/Search/Suggestions/SearchSuggestions.php
@@ -11,6 +11,9 @@
namespace Core\Search\Suggestions;
+use Core\Mod\Uptelligence\Models\Asset;
+use Core\Mod\Uptelligence\Models\Pattern;
+use Core\Search\Analytics\SearchAnalytics;
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\DB;
@@ -43,7 +46,7 @@
* 'sources' => ['popular', 'recent', 'content'],
* ]
*
- * @see \Core\Search\Analytics\SearchAnalytics For search tracking integration
+ * @see SearchAnalytics For search tracking integration
*/
class SearchSuggestions
{
@@ -259,9 +262,9 @@ public function getContentSuggestions(string $prefix, int $limit = 10): Collecti
$escaped = $this->escapeLikeQuery($prefix);
// Search patterns if available
- if (class_exists(\Core\Mod\Uptelligence\Models\Pattern::class)) {
+ if (class_exists(Pattern::class)) {
try {
- $patterns = \Core\Mod\Uptelligence\Models\Pattern::where('name', 'like', "{$escaped}%")
+ $patterns = Pattern::where('name', 'like', "{$escaped}%")
->limit($limit)
->pluck('name')
->map(fn ($name) => [
@@ -278,9 +281,9 @@ public function getContentSuggestions(string $prefix, int $limit = 10): Collecti
}
// Search assets if available
- if (class_exists(\Core\Mod\Uptelligence\Models\Asset::class)) {
+ if (class_exists(Asset::class)) {
try {
- $assets = \Core\Mod\Uptelligence\Models\Asset::where('name', 'like', "{$escaped}%")
+ $assets = Asset::where('name', 'like', "{$escaped}%")
->limit($limit)
->pluck('name')
->map(fn ($name) => [
diff --git a/src/Core/Search/Support/CLAUDE.md b/src/Core/Search/Support/CLAUDE.md
new file mode 100644
index 0000000..10797df
--- /dev/null
+++ b/src/Core/Search/Support/CLAUDE.md
@@ -0,0 +1,9 @@
+# Search/Support/ — Search Utilities
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SearchHighlighter` | Highlights search query terms within result text. Multi-word support, case-insensitive matching with original case preserved, HTML-safe output, context extraction (snippets around matches), configurable highlight styles. |
+
+Used by search result rendering to show users why a result matched their query.
diff --git a/src/Core/Search/Unified.php b/src/Core/Search/Unified.php
index c76550b..671908e 100644
--- a/src/Core/Search/Unified.php
+++ b/src/Core/Search/Unified.php
@@ -11,6 +11,10 @@
namespace Core\Search;
+use Core\Mod\Agentic\Models\AgentPlan;
+use Core\Mod\Uptelligence\Models\Asset;
+use Core\Mod\Uptelligence\Models\Pattern;
+use Core\Mod\Uptelligence\Models\UpstreamTodo;
use Core\Search\Analytics\SearchAnalytics;
use Core\Search\Suggestions\SearchSuggestions;
use Illuminate\Support\Collection;
@@ -410,14 +414,14 @@ protected function searchApiEndpoints(string $query): Collection
*/
protected function searchPatterns(string $query): Collection
{
- if (! class_exists(\Core\Mod\Uptelligence\Models\Pattern::class)) {
+ if (! class_exists(Pattern::class)) {
return collect();
}
$escaped = $this->escapeLikeQuery($query);
try {
- return \Core\Mod\Uptelligence\Models\Pattern::where('name', 'like', "%{$escaped}%")
+ return Pattern::where('name', 'like', "%{$escaped}%")
->orWhere('description', 'like', "%{$escaped}%")
->orWhere('category', 'like', "%{$escaped}%")
->limit(20)
@@ -448,14 +452,14 @@ protected function searchPatterns(string $query): Collection
*/
protected function searchAssets(string $query): Collection
{
- if (! class_exists(\Core\Mod\Uptelligence\Models\Asset::class)) {
+ if (! class_exists(Asset::class)) {
return collect();
}
$escaped = $this->escapeLikeQuery($query);
try {
- return \Core\Mod\Uptelligence\Models\Asset::where('name', 'like', "%{$escaped}%")
+ return Asset::where('name', 'like', "%{$escaped}%")
->orWhere('slug', 'like', "%{$escaped}%")
->orWhere('description', 'like', "%{$escaped}%")
->limit(20)
@@ -487,14 +491,14 @@ protected function searchAssets(string $query): Collection
*/
protected function searchTodos(string $query): Collection
{
- if (! class_exists(\Core\Mod\Uptelligence\Models\UpstreamTodo::class)) {
+ if (! class_exists(UpstreamTodo::class)) {
return collect();
}
$escaped = $this->escapeLikeQuery($query);
try {
- return \Core\Mod\Uptelligence\Models\UpstreamTodo::where('title', 'like', "%{$escaped}%")
+ return UpstreamTodo::where('title', 'like', "%{$escaped}%")
->orWhere('description', 'like', "%{$escaped}%")
->limit(20)
->get()
@@ -525,14 +529,14 @@ protected function searchTodos(string $query): Collection
*/
protected function searchPlans(string $query): Collection
{
- if (! class_exists(\Core\Mod\Agentic\Models\AgentPlan::class)) {
+ if (! class_exists(AgentPlan::class)) {
return collect();
}
$escaped = $this->escapeLikeQuery($query);
try {
- return \Core\Mod\Agentic\Models\AgentPlan::where('title', 'like', "%{$escaped}%")
+ return AgentPlan::where('title', 'like', "%{$escaped}%")
->orWhere('slug', 'like', "%{$escaped}%")
->orWhere('description', 'like', "%{$escaped}%")
->limit(20)
diff --git a/src/Core/Seo/Analytics/CLAUDE.md b/src/Core/Seo/Analytics/CLAUDE.md
new file mode 100644
index 0000000..c8cb584
--- /dev/null
+++ b/src/Core/Seo/Analytics/CLAUDE.md
@@ -0,0 +1,7 @@
+# Seo/Analytics/ — SEO Score Tracking
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SeoScoreTrend` | Tracks SEO scores over time to show improvement or regression trends. Reads from `SeoScoreHistory` model. Provides daily, weekly, and monthly aggregation. |
diff --git a/src/Core/Seo/Boot.php b/src/Core/Seo/Boot.php
index 875b930..321f590 100644
--- a/src/Core/Seo/Boot.php
+++ b/src/Core/Seo/Boot.php
@@ -11,6 +11,7 @@
namespace Core\Seo;
+use App\Services\Content\SchemaService;
use Core\Seo\Analytics\SeoScoreTrend;
use Core\Seo\Console\Commands\AuditCanonicalUrls;
use Core\Seo\Console\Commands\RecordSeoScores;
@@ -105,8 +106,8 @@ protected function registerCommands(): void
protected function registerBackwardCompatAliases(): void
{
// Schema (high-level JSON-LD generator)
- if (! class_exists(\App\Services\Content\SchemaService::class)) {
- class_alias(Schema::class, \App\Services\Content\SchemaService::class);
+ if (! class_exists(SchemaService::class)) {
+ class_alias(Schema::class, SchemaService::class);
}
// Services
diff --git a/src/Core/Seo/CLAUDE.md b/src/Core/Seo/CLAUDE.md
new file mode 100644
index 0000000..4df8c86
--- /dev/null
+++ b/src/Core/Seo/CLAUDE.md
@@ -0,0 +1,73 @@
+# Core\Seo
+
+SEO metadata management, JSON-LD schema generation, structured data validation, OG image handling, and score trend tracking.
+
+## Key Classes
+
+| Class | Purpose |
+|-------|---------|
+| `Schema` | High-level JSON-LD generator: auto-detects Article, HowTo, FAQ, Breadcrumb from content |
+| `SeoMetadata` | Eloquent model (polymorphic): title, description, canonical, OG, Twitter, schema markup, score, issues |
+| `HasSeoMetadata` | Trait for models: `seoMetadata()` morphOne, `updateSeo()`, `getSeoHeadTagsAttribute()` |
+| `Boot` | Service provider: registers singletons + artisan commands |
+
+### Services/
+
+| Class | Purpose |
+|-------|---------|
+| `SchemaBuilderService` | Lower-level schema building blocks |
+| `ServiceOgImageService` | OG image generation for service pages |
+
+### Validation/
+
+| Class | Purpose |
+|-------|---------|
+| `SchemaValidator` | Validates schema against schema.org specifications |
+| `StructuredDataTester` | Tests structured data, checks rich results eligibility, generates reports |
+| `CanonicalUrlValidator` | Validates URL format and detects conflicts between records |
+| `OgImageValidator` | Validates OG image dimensions and requirements |
+
+### Analytics/
+
+| Class | Purpose |
+|-------|---------|
+| `SeoScoreTrend` | Daily/weekly score trend tracking |
+| `Models\SeoScoreHistory` | Historical score records |
+
+## Schema Generation
+
+`Schema::generateSchema($item)` builds a `@graph` containing:
+1. Organisation schema (always, from config)
+2. Article schema (TechArticle by default)
+3. Breadcrumb schema
+4. HowTo schema (if content has numbered steps)
+5. FAQ schema (if content has FAQ section with Q&A pairs)
+
+Content detection uses regex on `display_content`. Steps extracted from JSON blocks or numbered lists. FAQs from `## FAQ` sections.
+
+## SeoMetadata Model
+
+- **Lazy schema_markup**: Custom accessor/mutator defers JSON parsing until accessed
+- **Meta tag generation**: `meta_tags` attribute produces complete HTML ``, `<meta>`, `<link rel="canonical">`, OG, Twitter tags
+- **JSON-LD output**: `json_ld` attribute wraps schema in `<script type="application/ld+json">` with XSS-safe `JSON_HEX_TAG`
+- **Score tracking**: `recordScore()`, `getScoreHistory()`, `getDailyScoreTrend()`, `hasScoreImproved()`
+- **Validation**: `validateOgImage()`, `validateCanonicalUrl()`, `checkCanonicalConflict()`, `validateStructuredData()`, `getRichResultsEligibility()`
+
+## Console Commands
+
+- `seo:record-scores` -- Record SEO scores for trend tracking
+- `seo:test-structured-data` -- Test structured data against schema.org
+- `seo:audit-canonical` -- Audit canonical URLs for conflicts
+- `seo:generate-og-images` -- Generate OG images for services
+
+## Configuration
+
+Under `config/seo.php`:
+- `trends.enabled`, `trends.retention_days`, `trends.record_on_save`, `trends.min_interval_hours`
+- `structured_data.external_validation`, `structured_data.google_api_key`, `structured_data.cache_validation`
+
+## Integration
+
+- Use `HasSeoMetadata` trait on any Eloquent model to add polymorphic SEO data
+- `Schema` reads organisation config from `core.organisation.*` and `core.social.*`
+- Uses UK English in code: `colour`, `organisation`
diff --git a/src/Core/Seo/Console/Commands/CLAUDE.md b/src/Core/Seo/Console/Commands/CLAUDE.md
new file mode 100644
index 0000000..a6d5d96
--- /dev/null
+++ b/src/Core/Seo/Console/Commands/CLAUDE.md
@@ -0,0 +1,10 @@
+# Seo/Console/Commands/ — SEO Artisan Commands
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `AuditCanonicalUrls` | Audits canonical URLs across all SEO metadata for conflicts and misconfigurations. |
+| `GenerateServiceOgImages` | Batch-generates OG images for service/product pages. |
+| `RecordSeoScores` | Records current SEO scores to history for trend tracking. Designed for scheduled execution. |
+| `TestStructuredData` | Validates structured data (JSON-LD) across pages against schema.org specs. |
diff --git a/src/Core/Seo/Console/Commands/GenerateServiceOgImages.php b/src/Core/Seo/Console/Commands/GenerateServiceOgImages.php
index 10231a2..f51fbbb 100644
--- a/src/Core/Seo/Console/Commands/GenerateServiceOgImages.php
+++ b/src/Core/Seo/Console/Commands/GenerateServiceOgImages.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
/*
* Core PHP Framework
*
diff --git a/src/Core/Seo/Controllers/CLAUDE.md b/src/Core/Seo/Controllers/CLAUDE.md
new file mode 100644
index 0000000..b2c7644
--- /dev/null
+++ b/src/Core/Seo/Controllers/CLAUDE.md
@@ -0,0 +1,8 @@
+# Seo/Controllers/ — SEO HTTP Controllers
+
+## Controllers
+
+| Controller | Purpose |
+|------------|---------|
+| `SitemapController` | Generates XML sitemaps — sitemap index pointing to child sitemaps (pages, posts, etc.). |
+| `OgImageController` | Serves dynamically generated Open Graph images for social media previews. |
diff --git a/src/Core/Seo/Jobs/CLAUDE.md b/src/Core/Seo/Jobs/CLAUDE.md
new file mode 100644
index 0000000..87605a0
--- /dev/null
+++ b/src/Core/Seo/Jobs/CLAUDE.md
@@ -0,0 +1,7 @@
+# Seo/Jobs/ — SEO Background Jobs
+
+## Jobs
+
+| Job | Purpose |
+|-----|---------|
+| `GenerateOgImageJob` | Queued job to generate Open Graph images for pages. Uses `DynamicOgImageService` to render and store OG images. |
diff --git a/src/Core/Seo/Jobs/GenerateOgImageJob.php b/src/Core/Seo/Jobs/GenerateOgImageJob.php
index 7b4204c..c0e33b2 100644
--- a/src/Core/Seo/Jobs/GenerateOgImageJob.php
+++ b/src/Core/Seo/Jobs/GenerateOgImageJob.php
@@ -11,6 +11,8 @@
namespace Core\Seo\Jobs;
+use Core\Mod\Web\Models\Page;
+use Core\Mod\Web\Services\DynamicOgImageService;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
@@ -64,20 +66,20 @@ public function __construct(
public function handle(): void
{
// Check if required Web module classes exist
- if (! class_exists(\Core\Mod\Web\Models\Page::class)) {
+ if (! class_exists(Page::class)) {
Log::warning('OG image generation skipped: Web module not installed');
return;
}
- if (! class_exists(\Core\Mod\Web\Services\DynamicOgImageService::class)) {
+ if (! class_exists(DynamicOgImageService::class)) {
Log::warning('OG image generation skipped: DynamicOgImageService not available');
return;
}
- $ogService = app(\Core\Mod\Web\Services\DynamicOgImageService::class);
- $page = \Core\Mod\Web\Models\Page::find($this->pageId);
+ $ogService = app(DynamicOgImageService::class);
+ $page = Page::find($this->pageId);
if (! $page) {
Log::warning("OG image generation skipped: page {$this->pageId} not found");
diff --git a/src/Core/Seo/Models/CLAUDE.md b/src/Core/Seo/Models/CLAUDE.md
new file mode 100644
index 0000000..ec73f62
--- /dev/null
+++ b/src/Core/Seo/Models/CLAUDE.md
@@ -0,0 +1,7 @@
+# Seo/Models/ — SEO Eloquent Models
+
+## Models
+
+| Model | Purpose |
+|-------|---------|
+| `SeoScoreHistory` | Historical SEO score records. Polymorphic (`seoable_type`/`seoable_id`) for any model with SEO metadata. Stores point-in-time snapshots of scores and issues. Supports daily and weekly aggregation for trend analysis. |
diff --git a/src/Core/Seo/Models/SeoScoreHistory.php b/src/Core/Seo/Models/SeoScoreHistory.php
index 10fc96c..76d4f1f 100644
--- a/src/Core/Seo/Models/SeoScoreHistory.php
+++ b/src/Core/Seo/Models/SeoScoreHistory.php
@@ -11,6 +11,8 @@
namespace Core\Seo\Models;
+use Carbon\Carbon;
+use Core\Seo\SeoMetadata;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\MorphTo;
@@ -42,8 +44,8 @@
* @property array<string>|null $issues
* @property array<string>|null $suggestions
* @property array<string, mixed>|null $snapshot
- * @property \Carbon\Carbon $recorded_at
- * @property \Carbon\Carbon $created_at
+ * @property Carbon $recorded_at
+ * @property Carbon $created_at
*/
class SeoScoreHistory extends Model
{
@@ -100,7 +102,7 @@ public function seoable(): MorphTo
*/
public function seoMetadata(): BelongsTo
{
- return $this->belongsTo(\Core\Seo\SeoMetadata::class, 'seo_metadata_id');
+ return $this->belongsTo(SeoMetadata::class, 'seo_metadata_id');
}
/**
@@ -224,11 +226,11 @@ public static function latestForModel(string $type, int $id): ?static
/**
* Get scores recorded within a date range.
*
- * @param \Carbon\Carbon $from Start date
- * @param \Carbon\Carbon $to End date
+ * @param Carbon $from Start date
+ * @param Carbon $to End date
* @return Collection<int, static>
*/
- public static function inDateRange(\Carbon\Carbon $from, \Carbon\Carbon $to): Collection
+ public static function inDateRange(Carbon $from, Carbon $to): Collection
{
return static::whereBetween('recorded_at', [$from, $to])
->orderByDesc('recorded_at')
diff --git a/src/Core/Seo/SeoMetadata.php b/src/Core/Seo/SeoMetadata.php
index 471653f..3cb6485 100644
--- a/src/Core/Seo/SeoMetadata.php
+++ b/src/Core/Seo/SeoMetadata.php
@@ -13,6 +13,8 @@
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphTo;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Collection;
/**
* SEO metadata for any model.
@@ -31,8 +33,8 @@
* @property int|null $seo_score
* @property array<string>|null $seo_issues
* @property array<string>|null $seo_suggestions
- * @property \Illuminate\Support\Carbon|null $created_at
- * @property \Illuminate\Support\Carbon|null $updated_at
+ * @property Carbon|null $created_at
+ * @property Carbon|null $updated_at
*/
class SeoMetadata extends Model
{
@@ -317,7 +319,7 @@ public function validateCanonicalUrl(): array
/**
* Check if this canonical URL conflicts with other records.
*
- * @return array{has_conflict: bool, count: int, records: \Illuminate\Support\Collection}
+ * @return array{has_conflict: bool, count: int, records: Collection}
*/
public function checkCanonicalConflict(): array
{
@@ -370,9 +372,9 @@ public function recordScore(bool $force = false): ?Models\SeoScoreHistory
* Get score history for this metadata.
*
* @param int $limit Maximum records to return
- * @return \Illuminate\Support\Collection<int, Models\SeoScoreHistory>
+ * @return Collection<int, Models\SeoScoreHistory>
*/
- public function getScoreHistory(int $limit = 100): \Illuminate\Support\Collection
+ public function getScoreHistory(int $limit = 100): Collection
{
$trend = app(Analytics\SeoScoreTrend::class);
@@ -383,9 +385,9 @@ public function getScoreHistory(int $limit = 100): \Illuminate\Support\Collectio
* Get daily score trend for this metadata.
*
* @param int $days Days to look back
- * @return \Illuminate\Support\Collection<int, object>
+ * @return Collection<int, object>
*/
- public function getDailyScoreTrend(int $days = 30): \Illuminate\Support\Collection
+ public function getDailyScoreTrend(int $days = 30): Collection
{
$trend = app(Analytics\SeoScoreTrend::class);
@@ -396,9 +398,9 @@ public function getDailyScoreTrend(int $days = 30): \Illuminate\Support\Collecti
* Get weekly score trend for this metadata.
*
* @param int $weeks Weeks to look back
- * @return \Illuminate\Support\Collection<int, object>
+ * @return Collection<int, object>
*/
- public function getWeeklyScoreTrend(int $weeks = 12): \Illuminate\Support\Collection
+ public function getWeeklyScoreTrend(int $weeks = 12): Collection
{
$trend = app(Analytics\SeoScoreTrend::class);
diff --git a/src/Core/Seo/Services/CLAUDE.md b/src/Core/Seo/Services/CLAUDE.md
new file mode 100644
index 0000000..46beb80
--- /dev/null
+++ b/src/Core/Seo/Services/CLAUDE.md
@@ -0,0 +1,8 @@
+# Seo/Services/ — SEO Service Layer
+
+## Services
+
+| Service | Purpose |
+|---------|---------|
+| `SchemaBuilderService` | Generates JSON-LD structured data for schema.org types: Article, BlogPosting, HowTo, FAQ, BreadcrumbList, Organization, WebSite. Uses `SchemaValidator` for validation. |
+| `ServiceOgImageService` | Generates Open Graph images for service/product pages. |
diff --git a/src/Core/Seo/Validation/CLAUDE.md b/src/Core/Seo/Validation/CLAUDE.md
new file mode 100644
index 0000000..e04b539
--- /dev/null
+++ b/src/Core/Seo/Validation/CLAUDE.md
@@ -0,0 +1,10 @@
+# Seo/Validation/ — SEO Validation
+
+## Validators
+
+| Class | Purpose |
+|-------|---------|
+| `CanonicalUrlValidator` | Detects canonical URL conflicts across SEO metadata. Finds multiple pages pointing to the same canonical URL. |
+| `OgImageValidator` | Validates OG images — checks dimensions, file size, format, and accessibility. |
+| `SchemaValidator` | Validates JSON-LD structured data against schema.org requirements. |
+| `StructuredDataTester` | Comprehensive structured data testing — validates all JSON-LD on a page against schema.org specs. |
diff --git a/src/Core/Storage/CLAUDE.md b/src/Core/Storage/CLAUDE.md
new file mode 100644
index 0000000..4d28042
--- /dev/null
+++ b/src/Core/Storage/CLAUDE.md
@@ -0,0 +1,53 @@
+# Core\Storage
+
+Cache resilience infrastructure: tiered caching, Redis circuit breaker, and cache warming.
+
+## Key Classes
+
+| Class | Purpose |
+|-------|---------|
+| `TieredCacheStore` | Multi-tier cascading cache: Memory -> Redis -> Database. Reads check fastest first, promotes hits upward. Writes go to all tiers with tier-specific TTLs |
+| `CircuitBreaker` | Prevents cascading failures: Closed (normal) -> Open (skip Redis) -> Half-Open (test recovery). Configurable failure threshold, recovery timeout, success threshold |
+| `ResilientRedisStore` | Redis wrapper that falls back gracefully on connection failure |
+| `CacheResilienceProvider` | Wires up the resilience stack |
+| `TierConfiguration` | Configuration DTO for cache tiers (name, driver, TTL) |
+| `CacheWarmer` | Pre-populates cache with frequently accessed data |
+| `StorageMetrics` | Tracks cache hits/misses per tier |
+
+### Commands/
+
+- `WarmCacheCommand` -- Artisan command to warm the cache
+
+### Events/
+
+- `RedisFallbackActivated` -- Dispatched when Redis fails and fallback is activated
+
+## Tiered Cache Architecture
+
+```
+get("key")
+ |
+ v
+[Memory/Array] -- miss --> [Redis] -- miss --> [Database]
+ 60s TTL 1h TTL 24h TTL
+```
+
+- On hit at a lower tier, value is promoted to all faster tiers
+- Writes propagate to all enabled tiers with per-tier TTLs
+- Configuration via `config('core.storage.tiered_cache.tiers')`
+
+## Circuit Breaker States
+
+| State | Behaviour |
+|-------|-----------|
+| Closed | Normal: requests go to Redis |
+| Open | Redis failing: requests go directly to fallback, skip Redis |
+| Half-Open | Testing: allows limited requests to check if Redis recovered |
+
+Defaults: 5 failures to open, 30s recovery timeout, 2 successes to close.
+
+## Integration
+
+- `RedisFallbackActivated` event allows monitoring/alerting when Redis goes down
+- `StorageMetrics` integrates with the tiered cache for hit/miss tracking
+- No Boot.php in this directory -- the resilience stack is wired via `CacheResilienceProvider`
diff --git a/src/Core/Storage/CacheResilienceProvider.php b/src/Core/Storage/CacheResilienceProvider.php
index e79be1d..905a156 100644
--- a/src/Core/Storage/CacheResilienceProvider.php
+++ b/src/Core/Storage/CacheResilienceProvider.php
@@ -17,6 +17,7 @@
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\ServiceProvider;
+use Predis\Client;
/**
* Provides resilient cache/session configuration.
@@ -178,7 +179,7 @@ protected function isRedisAvailable(): bool
}
// Fall back to Predis library
- if (class_exists(\Predis\Client::class)) {
+ if (class_exists(Client::class)) {
return $this->checkPredis($host, $port, $password, $timeout);
}
@@ -233,7 +234,7 @@ protected function checkPredis(string $host, int $port, ?string $password, float
$options['password'] = $password;
}
- $client = new \Predis\Client($options, [
+ $client = new Client($options, [
'exceptions' => true,
]);
diff --git a/src/Core/Storage/Commands/CLAUDE.md b/src/Core/Storage/Commands/CLAUDE.md
new file mode 100644
index 0000000..afdcc24
--- /dev/null
+++ b/src/Core/Storage/Commands/CLAUDE.md
@@ -0,0 +1,9 @@
+# Storage/Commands/ — Storage Artisan Commands
+
+## Commands
+
+| Command | Signature | Purpose |
+|---------|-----------|---------|
+| `WarmCacheCommand` | `cache:warm` | Pre-populates cache with frequently accessed data. Options: `--stale` (only warm missing items), `--status` (show warming status), `--key=foo` (warm specific key). Prevents cold cache problems after deployments. |
+
+Uses the `CacheWarmer` service which modules register their warmable items with.
diff --git a/src/Core/Storage/Commands/WarmCacheCommand.php b/src/Core/Storage/Commands/WarmCacheCommand.php
index 45338b7..5d5e17b 100644
--- a/src/Core/Storage/Commands/WarmCacheCommand.php
+++ b/src/Core/Storage/Commands/WarmCacheCommand.php
@@ -13,6 +13,8 @@
use Core\Storage\CacheWarmer;
use Illuminate\Console\Command;
+use Symfony\Component\Console\Completion\CompletionInput;
+use Symfony\Component\Console\Completion\CompletionSuggestions;
/**
* Warm registered cache items.
@@ -271,8 +273,8 @@ protected function displayResults(array $results, bool $staleOnly): void
* Get shell completion suggestions for options.
*/
public function complete(
- \Symfony\Component\Console\Completion\CompletionInput $input,
- \Symfony\Component\Console\Completion\CompletionSuggestions $suggestions
+ CompletionInput $input,
+ CompletionSuggestions $suggestions
): void {
if ($input->mustSuggestOptionValuesFor('store')) {
// Suggest common cache stores
diff --git a/src/Core/Storage/Events/CLAUDE.md b/src/Core/Storage/Events/CLAUDE.md
new file mode 100644
index 0000000..fab0cef
--- /dev/null
+++ b/src/Core/Storage/Events/CLAUDE.md
@@ -0,0 +1,9 @@
+# Storage/Events/ — Storage System Events
+
+## Events
+
+| Event | Fired When | Properties |
+|-------|-----------|------------|
+| `RedisFallbackActivated` | Redis becomes unavailable and fallback driver is activated | `context`, `errorMessage`, `fallbackDriver` (default: `database`) |
+
+Listeners can use this for alerting, monitoring, or graceful degradation when Redis fails.
diff --git a/src/Core/Tests/Feature/AdminComponentsTest.php b/src/Core/Tests/Feature/AdminComponentsTest.php
index c5346b6..715196f 100644
--- a/src/Core/Tests/Feature/AdminComponentsTest.php
+++ b/src/Core/Tests/Feature/AdminComponentsTest.php
@@ -17,6 +17,7 @@
*/
use Illuminate\Support\Facades\Blade;
+use Illuminate\View\Compilers\BladeCompiler;
use Illuminate\View\Component;
uses()->group('admin-components');
@@ -307,7 +308,7 @@
$errors = [];
foreach ($files as $file) {
try {
- $compiler = app(\Illuminate\View\Compilers\BladeCompiler::class);
+ $compiler = app(BladeCompiler::class);
$compiler->compile($file);
} catch (Throwable $e) {
$errors[] = [
diff --git a/src/Core/Tests/Feature/AdminRouteSmokeTest.php b/src/Core/Tests/Feature/AdminRouteSmokeTest.php
index b84b20a..7fb8aae 100644
--- a/src/Core/Tests/Feature/AdminRouteSmokeTest.php
+++ b/src/Core/Tests/Feature/AdminRouteSmokeTest.php
@@ -53,7 +53,7 @@
try {
$response = $this->actingAs($this->hadesUser)->get('/'.$uri);
- } catch (\Throwable $e) {
+ } catch (Throwable $e) {
$failures[] = [
'uri' => $uri,
'status' => 500,
@@ -338,7 +338,7 @@
* Uses middleware detection to find admin routes, not URL patterns.
* This catches all routes with 'admin' middleware regardless of URL structure.
*
- * @return array<\Illuminate\Routing\Route>
+ * @return array<Illuminate\Routing\Route>
*/
function discoverAdminRoutes(): array
{
@@ -383,7 +383,7 @@ function discoverAdminRoutes(): array
/**
* Discover all hub GET routes (hub/*) from Laravel's route registrar.
*
- * @return array<\Illuminate\Routing\Route>
+ * @return array<Illuminate\Routing\Route>
*/
function discoverHubRoutes(): array
{
diff --git a/src/Core/Tests/Feature/CLAUDE.md b/src/Core/Tests/Feature/CLAUDE.md
new file mode 100644
index 0000000..cc1ddb8
--- /dev/null
+++ b/src/Core/Tests/Feature/CLAUDE.md
@@ -0,0 +1,27 @@
+# Tests/Feature/ — Core Feature Tests
+
+Pest feature (integration) tests for the Core PHP framework.
+
+## Test Files
+
+| File | Tests |
+|------|-------|
+| `AdminComponentsTest.php` | Admin panel Livewire component rendering |
+| `AdminRouteSmokeTest.php` | Admin route accessibility |
+| `BladeViewCompilationTest.php` | Blade template compilation |
+| `CdnIntegrationTest.php` | CDN URL building and asset delivery |
+| `CoreComponentsTest.php` | Core UI component rendering |
+| `DatabaseMigrationTest.php` | Migration execution |
+| `EmailShieldTest.php` | Email validation and disposable blocking |
+| `ErrorPagesTest.php` | Custom error page rendering |
+| `ImageOptimizerTest.php` | Image optimisation pipeline |
+| `MailConfigurationTest.php` | Mail driver configuration |
+| `ModuleScannerIntegrationTest.php` | Full module discovery flow |
+| `OffloadMigrateCommandTest.php` | Storage offload migration command |
+| `PerformanceBaselineTest.php` | Response time baselines |
+| `ResilientSessionTest.php` | Session fallback handling |
+| `RewriteOffloadedUrlsTest.php` | URL rewriting for offloaded assets |
+| `SecurityFixesTest.php` | Security vulnerability patches |
+| `SecurityHeadersTest.php` | HTTP security header enforcement |
+| `StorageOffloadTest.php` | File offloading to remote storage |
+| `ValidationRulesTest.php` | Custom validation rule behaviour |
diff --git a/src/Core/Tests/Feature/CdnIntegrationTest.php b/src/Core/Tests/Feature/CdnIntegrationTest.php
index 477d045..df53cf8 100644
--- a/src/Core/Tests/Feature/CdnIntegrationTest.php
+++ b/src/Core/Tests/Feature/CdnIntegrationTest.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
/*
* Core PHP Framework
*
@@ -12,10 +14,12 @@
use Core\Cdn\Services\AssetPipeline;
use Core\Cdn\Services\CdnUrlBuilder;
use Core\Cdn\Services\StorageUrlResolver;
+use Illuminate\Contracts\Filesystem\Filesystem;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\Config;
use Illuminate\Support\Facades\Storage;
+use PHPUnit\Framework\Attributes\Group;
use Tests\TestCase;
/**
@@ -27,7 +31,7 @@
* - CDN delivery
* - vBucket isolation
*/
-#[\PHPUnit\Framework\Attributes\Group('slow')]
+#[Group('slow')]
class CdnIntegrationTest extends TestCase
{
use RefreshDatabase;
@@ -309,14 +313,14 @@ public function test_url_resolver_returns_public_disk_instance(): void
{
$disk = $this->urlResolver->publicDisk();
- $this->assertInstanceOf(\Illuminate\Contracts\Filesystem\Filesystem::class, $disk);
+ $this->assertInstanceOf(Filesystem::class, $disk);
}
public function test_url_resolver_returns_private_disk_instance(): void
{
$disk = $this->urlResolver->privateDisk();
- $this->assertInstanceOf(\Illuminate\Contracts\Filesystem\Filesystem::class, $disk);
+ $this->assertInstanceOf(Filesystem::class, $disk);
}
public function test_asset_pipeline_handles_large_files(): void
diff --git a/src/Core/Tests/Feature/Config/CLAUDE.md b/src/Core/Tests/Feature/Config/CLAUDE.md
new file mode 100644
index 0000000..bef1fe9
--- /dev/null
+++ b/src/Core/Tests/Feature/Config/CLAUDE.md
@@ -0,0 +1,8 @@
+# Tests/Feature/Config/ — Config Feature Tests
+
+## Test Files
+
+| File | Purpose |
+|------|---------|
+| `ChannelTest.php` | Tests for the `Channel` model — creation, inheritance chain, cycle detection, workspace scoping, `byCode()` lookup. |
+| `ConfigValueTest.php` | Tests for `ConfigValue` model — value storage, encryption of sensitive keys, FINAL lock semantics, typed value retrieval. |
diff --git a/src/Core/Tests/Feature/Config/ChannelTest.php b/src/Core/Tests/Feature/Config/ChannelTest.php
index 3f076dc..5c1caba 100644
--- a/src/Core/Tests/Feature/Config/ChannelTest.php
+++ b/src/Core/Tests/Feature/Config/ChannelTest.php
@@ -10,9 +10,10 @@
declare(strict_types=1);
use Core\Config\Models\Channel;
+use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Log;
-uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
+uses(RefreshDatabase::class);
describe('Channel', function () {
describe('inheritanceChain', function () {
diff --git a/src/Core/Tests/Feature/Config/ConfigValueTest.php b/src/Core/Tests/Feature/Config/ConfigValueTest.php
index 4451872..38fc061 100644
--- a/src/Core/Tests/Feature/Config/ConfigValueTest.php
+++ b/src/Core/Tests/Feature/Config/ConfigValueTest.php
@@ -16,8 +16,9 @@
use Core\Config\Models\ConfigProfile;
use Core\Config\Models\ConfigResolved;
use Core\Config\Models\ConfigValue;
+use Illuminate\Foundation\Testing\RefreshDatabase;
-uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
+uses(RefreshDatabase::class);
beforeEach(function () {
// Create essential test fixtures
diff --git a/src/Core/Tests/Feature/CoreComponentsTest.php b/src/Core/Tests/Feature/CoreComponentsTest.php
index 48c86c9..99d2d6f 100644
--- a/src/Core/Tests/Feature/CoreComponentsTest.php
+++ b/src/Core/Tests/Feature/CoreComponentsTest.php
@@ -18,6 +18,13 @@
* Run with: php artisan test app/Core/Tests/Feature/CoreComponentsTest.php
*/
+use Core\Front\Components\Button;
+use Core\Front\Components\Card;
+use Core\Front\Components\Heading;
+use Core\Front\Components\Layout;
+use Core\Front\Components\NavList;
+use Core\Front\Components\Text;
+use Core\Pro;
use Illuminate\Support\Facades\Blade;
use Illuminate\Support\Facades\File;
use Illuminate\View\Compilers\BladeCompiler;
@@ -28,56 +35,56 @@
it('detects Flux Pro installation', function () {
// Flux Pro is installed in this project
- expect(\Core\Pro::hasFluxPro())->toBeTrue();
+ expect(Pro::hasFluxPro())->toBeTrue();
});
it('identifies Flux Pro components', function () {
- expect(\Core\Pro::requiresFluxPro('calendar'))->toBeTrue();
- expect(\Core\Pro::requiresFluxPro('editor'))->toBeTrue();
- expect(\Core\Pro::requiresFluxPro('chart'))->toBeTrue();
- expect(\Core\Pro::requiresFluxPro('chart.line'))->toBeTrue(); // Nested component
- expect(\Core\Pro::requiresFluxPro('core:kanban'))->toBeTrue(); // With prefix
+ expect(Pro::requiresFluxPro('calendar'))->toBeTrue();
+ expect(Pro::requiresFluxPro('editor'))->toBeTrue();
+ expect(Pro::requiresFluxPro('chart'))->toBeTrue();
+ expect(Pro::requiresFluxPro('chart.line'))->toBeTrue(); // Nested component
+ expect(Pro::requiresFluxPro('core:kanban'))->toBeTrue(); // With prefix
// Free components
- expect(\Core\Pro::requiresFluxPro('button'))->toBeFalse();
- expect(\Core\Pro::requiresFluxPro('input'))->toBeFalse();
- expect(\Core\Pro::requiresFluxPro('modal'))->toBeFalse();
+ expect(Pro::requiresFluxPro('button'))->toBeFalse();
+ expect(Pro::requiresFluxPro('input'))->toBeFalse();
+ expect(Pro::requiresFluxPro('modal'))->toBeFalse();
});
it('respects FontAwesome Pro config', function () {
- \Core\Pro::clearCache();
+ Pro::clearCache();
config(['core.fontawesome.pro' => false]);
- expect(\Core\Pro::hasFontAwesomePro())->toBeFalse();
+ expect(Pro::hasFontAwesomePro())->toBeFalse();
- \Core\Pro::clearCache();
+ Pro::clearCache();
config(['core.fontawesome.pro' => true]);
- expect(\Core\Pro::hasFontAwesomePro())->toBeTrue();
+ expect(Pro::hasFontAwesomePro())->toBeTrue();
// Clean up
- \Core\Pro::clearCache();
+ Pro::clearCache();
});
it('provides correct FA styles based on Pro/Free', function () {
- \Core\Pro::clearCache();
+ Pro::clearCache();
config(['core.fontawesome.pro' => false]);
- $freeStyles = \Core\Pro::fontAwesomeStyles();
+ $freeStyles = Pro::fontAwesomeStyles();
expect($freeStyles)->toContain('solid');
expect($freeStyles)->toContain('regular');
expect($freeStyles)->toContain('brands');
expect($freeStyles)->not->toContain('jelly');
expect($freeStyles)->not->toContain('light');
- \Core\Pro::clearCache();
+ Pro::clearCache();
config(['core.fontawesome.pro' => true]);
- $proStyles = \Core\Pro::fontAwesomeStyles();
+ $proStyles = Pro::fontAwesomeStyles();
expect($proStyles)->toContain('jelly');
expect($proStyles)->toContain('light');
expect($proStyles)->toContain('thin');
// Clean up
- \Core\Pro::clearCache();
+ Pro::clearCache();
});
});
@@ -670,7 +677,7 @@
describe('Core PHP Builders', function () {
it('Button builder renders HTML', function () {
- $button = \Core\Front\Components\Button::make()
+ $button = Button::make()
->label('Save')
->primary(); // Use the actual API method
@@ -682,7 +689,7 @@
});
it('Card builder renders with title and body', function () {
- $card = \Core\Front\Components\Card::make()
+ $card = Card::make()
->title('Card Title')
->body('Card content goes here');
@@ -694,7 +701,7 @@
});
it('Heading builder renders with level', function () {
- $heading = \Core\Front\Components\Heading::make()
+ $heading = Heading::make()
->text('Page Title')
->level(1);
@@ -706,7 +713,7 @@
});
it('Text builder renders with variant', function () {
- $text = \Core\Front\Components\Text::make()
+ $text = Text::make()
->content('Some text')
->muted();
@@ -717,7 +724,7 @@
it('NavList builder renders items', function () {
// NavList::item() signature is: label, href, active, icon
- $navlist = \Core\Front\Components\NavList::make()
+ $navlist = NavList::make()
->item('Dashboard', '/dashboard', false, 'home')
->item('Settings', '/settings', false, 'cog');
@@ -732,7 +739,7 @@
it('Layout builder renders HLCRF structure', function () {
// Layout uses short method names: h(), c(), f()
- $layout = \Core\Front\Components\Layout::make('HCF')
+ $layout = Layout::make('HCF')
->h('Header Content')
->c('Main Content')
->f('Footer Content');
@@ -810,7 +817,7 @@
it('core:icon falls back to solid for jelly when FA Free', function () {
// Without FA Pro config, jelly icons should fall back to solid
- \Core\Pro::clearCache();
+ Pro::clearCache();
config(['core.fontawesome.pro' => false]);
$html = Blade::render('<core:icon name="globe" />');
@@ -820,7 +827,7 @@
it('core:icon uses jelly style when FA Pro enabled', function () {
// With FA Pro config, jelly icons should use fa-jelly
- \Core\Pro::clearCache();
+ Pro::clearCache();
config(['core.fontawesome.pro' => true]);
$html = Blade::render('<core:icon name="globe" />');
@@ -828,7 +835,7 @@
expect($html)->toContain('fa-jelly');
// Clean up
- \Core\Pro::clearCache();
+ Pro::clearCache();
config(['core.fontawesome.pro' => false]);
});
@@ -841,7 +848,7 @@
});
it('core:icon falls back pro-only styles to free equivalents', function () {
- \Core\Pro::clearCache();
+ Pro::clearCache();
config(['core.fontawesome.pro' => false]);
// Light → Regular
diff --git a/src/Core/Tests/Feature/DatabaseMigrationTest.php b/src/Core/Tests/Feature/DatabaseMigrationTest.php
index 79e40da..07f15bc 100644
--- a/src/Core/Tests/Feature/DatabaseMigrationTest.php
+++ b/src/Core/Tests/Feature/DatabaseMigrationTest.php
@@ -8,6 +8,9 @@
*/
declare(strict_types=1);
+use Core\Mod\Commerce\Database\Seeders\TaxRateSeeder;
+use Core\Tenant\Database\Seeders\PackageSeeder;
+use Database\Seeders\DatabaseSeeder;
/**
* Database Migration Tests
@@ -84,15 +87,15 @@
});
it('DatabaseSeeder class exists and has run method', function () {
- expect(class_exists(\Database\Seeders\DatabaseSeeder::class))->toBeTrue();
- expect(method_exists(\Database\Seeders\DatabaseSeeder::class, 'run'))->toBeTrue();
+ expect(class_exists(DatabaseSeeder::class))->toBeTrue();
+ expect(method_exists(DatabaseSeeder::class, 'run'))->toBeTrue();
});
it('critical seeder classes exist in modules', function () {
// Check for module seeders - these live in Mod namespaces
$moduleSeederClasses = [
- \Core\Tenant\Database\Seeders\PackageSeeder::class,
- \Core\Mod\Commerce\Database\Seeders\TaxRateSeeder::class,
+ PackageSeeder::class,
+ TaxRateSeeder::class,
];
$found = 0;
diff --git a/src/Core/Tests/Feature/EmailShieldTest.php b/src/Core/Tests/Feature/EmailShieldTest.php
index 5f88af5..64462b9 100644
--- a/src/Core/Tests/Feature/EmailShieldTest.php
+++ b/src/Core/Tests/Feature/EmailShieldTest.php
@@ -14,10 +14,11 @@
use Core\Mail\EmailShieldStat;
use Core\Mail\EmailValidationResult;
use Core\Mail\Rules\ValidatedEmail;
+use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Validator;
-uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
+uses(RefreshDatabase::class);
beforeEach(function () {
// Clear the cache before each test to ensure clean state
diff --git a/src/Core/Tests/Feature/ErrorPagesTest.php b/src/Core/Tests/Feature/ErrorPagesTest.php
index f18291e..4412c0a 100644
--- a/src/Core/Tests/Feature/ErrorPagesTest.php
+++ b/src/Core/Tests/Feature/ErrorPagesTest.php
@@ -16,6 +16,8 @@
* Error handling is configured in bootstrap/app.php.
*/
+use App\Support\HadesEncrypt;
+use Core\Tenant\Models\User;
use Illuminate\Support\Facades\Config;
describe('Static Error Files', function () {
@@ -87,7 +89,7 @@
describe('403 Error Page', function () {
it('returns 403 for forbidden access', function () {
// Create a regular user (not hades)
- $user = \Core\Tenant\Models\User::factory()->create([
+ $user = User::factory()->create([
'account_type' => 'apollo',
]);
@@ -152,11 +154,11 @@
describe('HADES Encryption', function () {
it('HadesEncrypt class exists and is functional', function () {
- expect(class_exists(\App\Support\HadesEncrypt::class))->toBeTrue();
+ expect(class_exists(HadesEncrypt::class))->toBeTrue();
// Test encryption with a sample exception
- $exception = new \Exception('Test error message');
- $encrypted = \App\Support\HadesEncrypt::encrypt($exception);
+ $exception = new Exception('Test error message');
+ $encrypted = HadesEncrypt::encrypt($exception);
// Should return encrypted string or null if no public key
expect($encrypted === null || is_string($encrypted))->toBeTrue();
diff --git a/src/Core/Tests/Feature/ImageOptimizerTest.php b/src/Core/Tests/Feature/ImageOptimizerTest.php
index 48dc07c..c856759 100644
--- a/src/Core/Tests/Feature/ImageOptimizerTest.php
+++ b/src/Core/Tests/Feature/ImageOptimizerTest.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
/*
* Core PHP Framework
*
@@ -110,7 +112,7 @@
$optimizer = new ImageOptimizer;
$optimizer->optimize('/path/to/nonexistent/file.jpg');
- })->throws(\InvalidArgumentException::class, 'File not found');
+ })->throws(InvalidArgumentException::class, 'File not found');
it('handles invalid image files gracefully', function () {
// Create a text file pretending to be an image
diff --git a/src/Core/Tests/Feature/MailConfigurationTest.php b/src/Core/Tests/Feature/MailConfigurationTest.php
index b57e0fa..363c3d1 100644
--- a/src/Core/Tests/Feature/MailConfigurationTest.php
+++ b/src/Core/Tests/Feature/MailConfigurationTest.php
@@ -9,6 +9,8 @@
declare(strict_types=1);
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Mail\SendQueuedMailable;
use Illuminate\Support\Facades\Config;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\Queue;
@@ -68,12 +70,12 @@
Mail::to('recipient@example.com')->queue($mailable);
- Queue::assertPushed(\Illuminate\Mail\SendQueuedMailable::class);
+ Queue::assertPushed(SendQueuedMailable::class);
});
it('ContactFormSubmission implements ShouldQueue', function () {
expect(ContactFormSubmission::class)
- ->toImplement(\Illuminate\Contracts\Queue\ShouldQueue::class);
+ ->toImplement(ShouldQueue::class);
});
});
diff --git a/src/Core/Tests/Feature/ModuleScannerIntegrationTest.php b/src/Core/Tests/Feature/ModuleScannerIntegrationTest.php
index 7f0384d..383f182 100644
--- a/src/Core/Tests/Feature/ModuleScannerIntegrationTest.php
+++ b/src/Core/Tests/Feature/ModuleScannerIntegrationTest.php
@@ -10,6 +10,7 @@
declare(strict_types=1);
use Core\Events\AdminPanelBooting;
+use Core\Events\WebRoutesRegistering;
use Core\LazyModuleListener;
use Core\ModuleScanner;
use Illuminate\Support\ServiceProvider;
@@ -27,8 +28,8 @@
// Common events should have listeners
$commonEvents = [
- \Core\Events\AdminPanelBooting::class,
- \Core\Events\WebRoutesRegistering::class,
+ AdminPanelBooting::class,
+ WebRoutesRegistering::class,
];
foreach ($commonEvents as $event) {
diff --git a/src/Core/Tests/Feature/OffloadMigrateCommandTest.php b/src/Core/Tests/Feature/OffloadMigrateCommandTest.php
index ade68cc..9728958 100644
--- a/src/Core/Tests/Feature/OffloadMigrateCommandTest.php
+++ b/src/Core/Tests/Feature/OffloadMigrateCommandTest.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
/*
* Core PHP Framework
*
diff --git a/src/Core/Tests/Feature/RewriteOffloadedUrlsTest.php b/src/Core/Tests/Feature/RewriteOffloadedUrlsTest.php
index 959d1a7..7ecef19 100644
--- a/src/Core/Tests/Feature/RewriteOffloadedUrlsTest.php
+++ b/src/Core/Tests/Feature/RewriteOffloadedUrlsTest.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
/*
* Core PHP Framework
*
diff --git a/src/Core/Tests/Feature/SecurityFixesTest.php b/src/Core/Tests/Feature/SecurityFixesTest.php
index 53ba7cb..306eb51 100644
--- a/src/Core/Tests/Feature/SecurityFixesTest.php
+++ b/src/Core/Tests/Feature/SecurityFixesTest.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
/*
* Core PHP Framework
*
@@ -19,12 +21,23 @@
use Core\Mod\Analytics\Models\AnalyticsWebsite;
use Core\Mod\Commerce\Models\Order;
use Core\Mod\Commerce\Models\Payment;
+use Core\Mod\Commerce\Services\PaymentGateway\BTCPayGateway;
+use Core\Mod\Commerce\View\Modal\Web\CheckoutCancel;
+use Core\Mod\Commerce\View\Modal\Web\CheckoutSuccess;
+use Core\Mod\Social\View\Modal\Admin\MediaPicker;
+use Core\Mod\Social\View\Modal\Admin\TemplateIndex;
use Core\Tenant\Models\Package;
use Core\Tenant\Models\User;
use Core\Tenant\Models\Workspace;
use Core\Tenant\Services\EntitlementService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Auth;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Route;
+use Livewire\Livewire;
-uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
+uses(RefreshDatabase::class);
beforeEach(function () {
$this->user = User::factory()->create();
@@ -51,10 +64,10 @@
]);
// Test authorization via component mount logic
- $component = new \Core\Mod\Commerce\View\Modal\Web\CheckoutSuccess;
+ $component = new CheckoutSuccess;
// Use reflection to call protected authorizeOrder
- \Illuminate\Support\Facades\Auth::login($this->user);
+ Auth::login($this->user);
$reflection = new ReflectionClass($component);
$method = $reflection->getMethod('authorizeOrder');
$method->setAccessible(true);
@@ -77,9 +90,9 @@
]);
// Test authorization via component logic
- $component = new \Core\Mod\Commerce\View\Modal\Web\CheckoutSuccess;
+ $component = new CheckoutSuccess;
- \Illuminate\Support\Facades\Auth::login($this->user);
+ Auth::login($this->user);
$reflection = new ReflectionClass($component);
$method = $reflection->getMethod('authorizeOrder');
$method->setAccessible(true);
@@ -106,9 +119,9 @@
]);
// Test authorization via component logic
- $component = new \Core\Mod\Commerce\View\Modal\Web\CheckoutCancel;
+ $component = new CheckoutCancel;
- \Illuminate\Support\Facades\Auth::login($this->user);
+ Auth::login($this->user);
$reflection = new ReflectionClass($component);
$method = $reflection->getMethod('authorizeOrder');
$method->setAccessible(true);
@@ -233,7 +246,7 @@
it('eager loads website relationship on show', function () {
// Skip if route not registered (Analytics API routes not wired up in Boot.php)
- if (! \Illuminate\Support\Facades\Route::has('api.analytics.goals.show')) {
+ if (! Route::has('api.analytics.goals.show')) {
$this->markTestSkipped('Analytics goals API route not registered');
}
@@ -248,13 +261,13 @@
]);
// Count queries
- \Illuminate\Support\Facades\DB::enableQueryLog();
+ DB::enableQueryLog();
$response = $this->actingAs($this->user)
->getJson("/api/v1/analytics/goals/{$goal->id}");
- $queries = \Illuminate\Support\Facades\DB::getQueryLog();
- \Illuminate\Support\Facades\DB::disableQueryLog();
+ $queries = DB::getQueryLog();
+ DB::disableQueryLog();
// Should be 200 OK
expect($response->status())->toBe(200);
@@ -321,11 +334,11 @@
'commerce.gateways.btcpay.webhook_secret' => 'test_webhook_secret',
]);
- $gateway = new \Core\Mod\Commerce\Services\PaymentGateway\BTCPayGateway;
+ $gateway = new BTCPayGateway;
// Mock HTTP to fail so we test the error path
- \Illuminate\Support\Facades\Http::fake([
- '*' => \Illuminate\Support\Facades\Http::response(['error' => 'Test error'], 400),
+ Http::fake([
+ '*' => Http::response(['error' => 'Test error'], 400),
]);
$result = $gateway->refund($payment, 50.00, 'Test refund');
@@ -356,11 +369,11 @@
'commerce.gateways.btcpay.webhook_secret' => 'test_webhook_secret',
]);
- $gateway = new \Core\Mod\Commerce\Services\PaymentGateway\BTCPayGateway;
+ $gateway = new BTCPayGateway;
// Mock HTTP to succeed
- \Illuminate\Support\Facades\Http::fake([
- '*' => \Illuminate\Support\Facades\Http::response([
+ Http::fake([
+ '*' => Http::response([
'id' => 'refund_123',
'status' => 'processed',
], 200),
@@ -394,7 +407,7 @@
describe('LIKE Wildcard Injection Fix', function () {
it('escapes LIKE wildcards in MediaPicker search', function () {
// Test the escapeLikeWildcards helper directly
- $component = new \Core\Mod\Social\View\Modal\Admin\MediaPicker;
+ $component = new MediaPicker;
$reflection = new ReflectionClass($component);
$method = $reflection->getMethod('escapeLikeWildcards');
@@ -410,7 +423,7 @@
});
it('does not affect normal search terms', function () {
- $component = new \Core\Mod\Social\View\Modal\Admin\MediaPicker;
+ $component = new MediaPicker;
$reflection = new ReflectionClass($component);
$method = $reflection->getMethod('escapeLikeWildcards');
@@ -429,8 +442,8 @@
$freshUser = User::factory()->create();
// Test without a default workspace - should not crash
- \Livewire\Livewire::actingAs($freshUser)
- ->test(\Core\Mod\Social\View\Modal\Admin\TemplateIndex::class)
+ Livewire::actingAs($freshUser)
+ ->test(TemplateIndex::class)
->assertStatus(200);
});
@@ -502,8 +515,8 @@
'currency' => 'GBP',
]);
- $component = new \Core\Mod\Commerce\View\Modal\Web\CheckoutSuccess;
- \Illuminate\Support\Facades\Auth::login($freshUser);
+ $component = new CheckoutSuccess;
+ Auth::login($freshUser);
$reflection = new ReflectionClass($component);
$method = $reflection->getMethod('authorizeOrder');
@@ -528,8 +541,8 @@
'currency' => 'GBP',
]);
- $component = new \Core\Mod\Commerce\View\Modal\Web\CheckoutCancel;
- \Illuminate\Support\Facades\Auth::login($freshUser);
+ $component = new CheckoutCancel;
+ Auth::login($freshUser);
$reflection = new ReflectionClass($component);
$method = $reflection->getMethod('authorizeOrder');
diff --git a/src/Core/Tests/Feature/SecurityHeadersTest.php b/src/Core/Tests/Feature/SecurityHeadersTest.php
index 5ff7989..aa38e98 100644
--- a/src/Core/Tests/Feature/SecurityHeadersTest.php
+++ b/src/Core/Tests/Feature/SecurityHeadersTest.php
@@ -8,6 +8,7 @@
*/
declare(strict_types=1);
+use Core\Tenant\Models\User;
/**
* Security Headers Tests (TASK-010 Phase 4)
@@ -74,7 +75,7 @@
describe('Security Headers on Authenticated Routes', function () {
beforeEach(function () {
- $this->user = \Core\Tenant\Models\User::factory()->create();
+ $this->user = User::factory()->create();
});
it('has security headers on hub routes', function () {
@@ -98,7 +99,7 @@
describe('Security Headers on API Routes', function () {
beforeEach(function () {
- $this->user = \Core\Tenant\Models\User::factory()->create([
+ $this->user = User::factory()->create([
'account_type' => 'hades',
]);
});
diff --git a/src/Core/Tests/Feature/StorageOffloadTest.php b/src/Core/Tests/Feature/StorageOffloadTest.php
index e6bc7da..776cc29 100644
--- a/src/Core/Tests/Feature/StorageOffloadTest.php
+++ b/src/Core/Tests/Feature/StorageOffloadTest.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
/*
* Core PHP Framework
*
@@ -11,12 +13,14 @@
use Core\Cdn\Models\StorageOffload as StorageOffloadModel;
use Core\Cdn\Services\StorageOffload;
+use Illuminate\Contracts\Filesystem\Filesystem;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Config;
use Illuminate\Support\Facades\Storage;
+use PHPUnit\Framework\Attributes\Group;
use Tests\TestCase;
-#[\PHPUnit\Framework\Attributes\Group('slow')]
+#[Group('slow')]
class StorageOffloadTest extends TestCase
{
use RefreshDatabase;
@@ -406,7 +410,7 @@ public function test_can_get_disk_instance(): void
{
$disk = $this->offloadService->getDisk();
- $this->assertInstanceOf(\Illuminate\Contracts\Filesystem\Filesystem::class, $disk);
+ $this->assertInstanceOf(Filesystem::class, $disk);
}
public function test_can_get_disk_name(): void
diff --git a/src/Core/Tests/Feature/ValidationRulesTest.php b/src/Core/Tests/Feature/ValidationRulesTest.php
index 86a264f..e97a17f 100644
--- a/src/Core/Tests/Feature/ValidationRulesTest.php
+++ b/src/Core/Tests/Feature/ValidationRulesTest.php
@@ -14,10 +14,11 @@
use Core\Tenant\Models\User;
use Core\Tenant\Rules\CheckUserPasswordRule;
use Core\Tenant\Rules\ResourceStatusRule;
+use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Facades\Validator;
-uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
+uses(RefreshDatabase::class);
describe('CheckUserPasswordRule', function () {
it('passes validation when password matches', function () {
diff --git a/src/Core/Tests/Unit/CLAUDE.md b/src/Core/Tests/Unit/CLAUDE.md
new file mode 100644
index 0000000..e7da58d
--- /dev/null
+++ b/src/Core/Tests/Unit/CLAUDE.md
@@ -0,0 +1,18 @@
+# Tests/Unit/ — Core Unit Tests
+
+Pest unit tests for core framework components.
+
+## Test Files
+
+| File | Tests |
+|------|-------|
+| `ApiVersionTest.php` | API versioning logic |
+| `ComponentBuildersTest.php` | UI component builder patterns |
+| `HadesEncryptTest.php` | Hades encryption utilities |
+| `LazyModuleListenerTest.php` | Lazy module instantiation and event handling |
+| `LthnHashTest.php` | Custom hashing implementation |
+| `ModuleScannerTest.php` | Module discovery from Boot.php files |
+| `PrivacyHelperTest.php` | Privacy/GDPR helper functions |
+| `UtmHelperTest.php` | UTM parameter handling |
+
+These test the root-level Core framework components (Boot, ModuleScanner, LazyModuleListener) and shared utilities.
diff --git a/src/Core/Tests/Unit/Crypt/CLAUDE.md b/src/Core/Tests/Unit/Crypt/CLAUDE.md
new file mode 100644
index 0000000..19e86cb
--- /dev/null
+++ b/src/Core/Tests/Unit/Crypt/CLAUDE.md
@@ -0,0 +1,7 @@
+# Tests/Unit/Crypt/ — Encryption Unit Tests
+
+## Test Files
+
+| File | Purpose |
+|------|---------|
+| `EncryptArrayObjectTest.php` | Tests for encrypting and decrypting array/object data structures. Validates the Crypt subsystem's handling of complex data types. |
diff --git a/src/Core/Tests/Unit/HadesEncryptTest.php b/src/Core/Tests/Unit/HadesEncryptTest.php
index 2b92b57..73d1040 100644
--- a/src/Core/Tests/Unit/HadesEncryptTest.php
+++ b/src/Core/Tests/Unit/HadesEncryptTest.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
/*
* Core PHP Framework
*
diff --git a/src/Core/Tests/Unit/LthnHashTest.php b/src/Core/Tests/Unit/LthnHashTest.php
index 732bfb1..59d7d48 100644
--- a/src/Core/Tests/Unit/LthnHashTest.php
+++ b/src/Core/Tests/Unit/LthnHashTest.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
/*
* Core PHP Framework
*
diff --git a/src/Core/Tests/Unit/Services/BunnyCdnServiceTest.php b/src/Core/Tests/Unit/Services/BunnyCdnServiceTest.php
index 16fbe49..0165f53 100644
--- a/src/Core/Tests/Unit/Services/BunnyCdnServiceTest.php
+++ b/src/Core/Tests/Unit/Services/BunnyCdnServiceTest.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
/*
* Core PHP Framework
*
@@ -11,8 +13,9 @@
use Core\Config\ConfigService;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;
+use Tests\TestCase;
-uses(\Tests\TestCase::class);
+uses(TestCase::class);
function createMockedService(bool $configured = true): BunnyCdnService
{
diff --git a/src/Core/Tests/Unit/Services/CLAUDE.md b/src/Core/Tests/Unit/Services/CLAUDE.md
new file mode 100644
index 0000000..24cc1d3
--- /dev/null
+++ b/src/Core/Tests/Unit/Services/CLAUDE.md
@@ -0,0 +1,7 @@
+# Tests/Unit/Services/ — Service Unit Tests
+
+## Test Files
+
+| File | Purpose |
+|------|---------|
+| `BunnyCdnServiceTest.php` | Unit tests for the BunnyCDN pull zone API service. Tests cache purging, statistics retrieval, and pull zone management. |
diff --git a/src/Core/Webhook/CLAUDE.md b/src/Core/Webhook/CLAUDE.md
new file mode 100644
index 0000000..e712775
--- /dev/null
+++ b/src/Core/Webhook/CLAUDE.md
@@ -0,0 +1,54 @@
+# Core\Webhook
+
+Inbound webhook receiving, signature verification, and event dispatch.
+
+## Key Classes
+
+| Class | Purpose |
+|-------|---------|
+| `Boot` | Service provider: merges config, registers `POST /webhooks/{source}` API route via `ApiRoutesRegistering` event |
+| `WebhookController` | Receives webhooks: verifies signature (if verifier bound), stores call, dispatches `WebhookReceived` event |
+| `WebhookCall` | Eloquent model (ULID primary key): source, event_type, headers, payload, signature_valid, processed_at |
+| `WebhookReceived` | Event dispatched after a webhook is stored |
+| `WebhookVerifier` | Interface: `verify(Request $request, string $secret): bool` |
+| `CronTrigger` | Cron-based webhook triggering |
+
+## Request Flow
+
+```
+POST /api/webhooks/{source}
+ |
+ v
+WebhookController::handle()
+ |-> Look up verifier: app("webhook.verifier.{$source}")
+ |-> Verify signature against config("webhook.secrets.{$source}")
+ |-> Extract event type from payload (type/event_type/event)
+ |-> Create WebhookCall record
+ |-> Dispatch WebhookReceived event
+ |-> Return {"ok": true}
+```
+
+## Adding a New Webhook Source
+
+1. Implement `WebhookVerifier` for your source
+2. Bind it: `$this->app->bind('webhook.verifier.stripe', StripeWebhookVerifier::class)`
+3. Set secret in config: `webhook.secrets.stripe`
+4. Listen for `WebhookReceived` event and filter by source
+
+## WebhookCall Model
+
+- Uses ULIDs (not UUIDs) for sortable, unique identifiers
+- `$timestamps = false` -- has `created_at` cast but no `updated_at`
+- Scopes: `unprocessed()`, `forSource($source)`
+- `markProcessed()` sets `processed_at` to now
+
+## Configuration
+
+`config/webhook.php` (merged from `config.php` in this directory):
+- `secrets.*` -- per-source signing secrets
+
+## Integration
+
+- Route registered via `ApiRoutesRegistering` lifecycle event (event-driven module loading pattern)
+- Source parameter constrained to `[a-z0-9\-]+`
+- Pair with `Core\Rules\SafeWebhookUrl` for outbound webhook URL validation
diff --git a/src/Core/Webhook/CronTrigger.php b/src/Core/Webhook/CronTrigger.php
index ea7d111..e539fee 100644
--- a/src/Core/Webhook/CronTrigger.php
+++ b/src/Core/Webhook/CronTrigger.php
@@ -43,7 +43,7 @@ public function handle(): void
usleep($stagger * 1_000_000);
}
- $url = $baseUrl . $endpoint . '?key=' . $key;
+ $url = $baseUrl.$endpoint.'?key='.$key;
try {
Http::timeout(30)->get($url);
diff --git a/src/Mod/CLAUDE.md b/src/Mod/CLAUDE.md
new file mode 100644
index 0000000..3c0e2c6
--- /dev/null
+++ b/src/Mod/CLAUDE.md
@@ -0,0 +1,45 @@
+# Mod -- Module Aggregator
+
+`Core\Mod\Boot` is a minimal ServiceProvider that acts as the namespace root for feature modules bundled with the core-php package.
+
+## How It Works
+
+Each module lives in a subdirectory (e.g., `Mod/Trees/`) with its own `Boot.php`. Modules self-register through the lifecycle event system -- they declare a static `$listens` array and are discovered by `ModuleScanner` during `LifecycleEventProvider::register()`.
+
+`Mod\Boot` itself does nothing in `register()` or `boot()`. It exists purely as the ServiceProvider entry point listed in `Core\Boot::$providers`.
+
+## Module Structure Convention
+
+```
+Mod/
+ {ModuleName}/
+ Boot.php # $listens declaration + event handlers
+ Console/ # Artisan commands
+ Controllers/ # HTTP controllers (Api/, Web/)
+ Database/Seeders/ # Database seeders
+ Jobs/ # Queue jobs
+ Lang/ # Translation files
+ Listeners/ # Event listeners
+ Middleware/ # HTTP middleware
+ Models/ # Eloquent models
+ Notifications/ # Notification classes
+ Routes/ # Route files (api.php, web.php)
+ Tests/ # Feature and Unit tests
+ View/ # Blade templates and Livewire components
+ Blade/ # Blade view files
+ Modal/ # Livewire components (organized by frontage)
+```
+
+## Namespace
+
+`Core\Mod\{ModuleName}` -- autoloaded via PSR-4 from `src/Mod/`.
+
+## Adding a Module
+
+1. Create `Mod/{Name}/Boot.php` with `public static array $listens`
+2. Implement event handler methods referenced in `$listens`
+3. The scanner discovers it automatically -- no registration needed
+
+## Current Modules
+
+- `Trees/` -- Trees for Agents initiative (see `Trees/CLAUDE.md`)
diff --git a/src/Mod/Trees/CLAUDE.md b/src/Mod/Trees/CLAUDE.md
new file mode 100644
index 0000000..208a267
--- /dev/null
+++ b/src/Mod/Trees/CLAUDE.md
@@ -0,0 +1,87 @@
+# Trees for Agents
+
+A module implementing the "Trees for Agents" programme: when an AI agent refers a user to the platform, a tree is planted with Trees for the Future (TFTF). The module tracks plantings, manages a pre-paid reserve, provides a public leaderboard, and handles batch donations.
+
+## Namespace
+
+`Core\Mod\Trees` -- autoloaded from `src/Mod/Trees/`.
+
+## Lifecycle Events
+
+```php
+public static array $listens = [
+ ApiRoutesRegistering::class => 'onApiRoutes',
+ WebRoutesRegistering::class => 'onWebRoutes',
+ ConsoleBooting::class => 'onConsole',
+];
+```
+
+## Models
+
+| Model | Purpose |
+|-------|---------|
+| `TreePlanting` | Individual tree planting record. Workspace-scoped (`BelongsToWorkspace`). Tracks provider, model, source, status, TFTF reference. Statuses: `pending` -> `confirmed` -> `planted` (or `queued` if reserve depleted). |
+| `TreeReserve` | Singleton row managing the pre-paid tree reserve. Tracks current level, total decremented/replenished. Warning at 50, critical at 10, depleted at 0. Sends `LowTreeReserveNotification` to admins. |
+| `TreeDonation` | Batch donation record. Created when confirmed trees are batched into a monthly TFTF donation. Cost: $0.25/tree. |
+| `TreePlantingStats` | Aggregated daily stats by provider/model. Atomic upsert for concurrent safety. Powers leaderboard and provider breakdowns. |
+
+## Planting Flow
+
+```
+Agent referral visit (/ref/{provider}/{model})
+ -> User signs up
+ -> PlantTreeForAgentReferral listener fires on Registered event
+ -> Checks daily limit (1 free tree/day) and guaranteed bonus
+ -> Creates TreePlanting (pending or queued)
+ -> If pending: markConfirmed() decrements reserve + updates stats
+ -> If queued: waits for trees:process-queue command
+```
+
+## Valid Providers
+
+`anthropic`, `openai`, `google`, `meta`, `mistral`, `local`, `unknown`
+
+## Console Commands
+
+| Command | Schedule | Purpose |
+|---------|----------|---------|
+| `trees:process-queue` | Daily | Processes oldest queued tree planting. Supports `--dry-run`. |
+| `trees:donate` | Monthly (28th) | Batches confirmed trees into TFTF donation. Creates `TreeDonation`, marks plantings as `planted`, optionally replenishes reserve. Supports `--dry-run` and `--replenish=N`. |
+| `trees:reserve:add {count}` | Manual | Replenishes reserve after a TFTF donation. Supports `--force`. |
+
+## API Endpoints (public, no auth)
+
+All under `api` middleware with `throttle:60,1`:
+
+| Route | Controller Method | Returns |
+|-------|------------------|---------|
+| `GET /trees/stats` | `index()` | Global totals, monthly/yearly, queue size |
+| `GET /trees/stats/{provider}` | `provider()` | Provider totals + model breakdown |
+| `GET /trees/stats/{provider}/{model}` | `model()` | Model-specific stats |
+| `GET /trees/leaderboard` | `leaderboard()` | Top 20 providers by trees planted |
+
+## Web Routes
+
+| Route | Component | Purpose |
+|-------|-----------|---------|
+| `GET /trees` | `trees.index` Livewire | Public leaderboard page |
+| `GET /ref/{provider}/{model?}` | `ReferralController@track` | Agent referral tracking (sets cookie/session) |
+
+## Middleware
+
+`IncludeAgentContext` -- Adds `for_agents` context to 401 JSON responses when the request comes from an AI agent. Includes referral URL, impact stats, and programme links. Depends on `Core\Agentic\Services\AgentDetection`.
+
+## Key Classes
+
+| Class | Purpose |
+|-------|---------|
+| `PlantTreeForAgentReferral` | Listener on `Registered` event. Checks referral data, daily limits, bonus system. |
+| `PlantTreeWithTFTF` | Queue job for confirming plantings. 3 retries, 60s backoff. |
+| `LowTreeReserveNotification` | Mail notification at warning/critical/depleted levels. |
+| `View\Modal\Web\Index` | Livewire component for the public leaderboard page. |
+
+## Dependencies
+
+- `Core\Tenant` -- `BelongsToWorkspace` trait, `ReferralController`, `AgentReferralBonus`
+- `Core\Agentic` -- `AgentDetection`, `AgentIdentity` (for middleware)
+- `Core\Front` -- `Controller` base class
diff --git a/src/Mod/Trees/Database/Seeders/TreeSeeder.php b/src/Mod/Trees/Database/Seeders/TreeSeeder.php
index 8f538e0..5de8846 100644
--- a/src/Mod/Trees/Database/Seeders/TreeSeeder.php
+++ b/src/Mod/Trees/Database/Seeders/TreeSeeder.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
namespace Core\Mod\Trees\Database\Seeders;
use Core\Mod\Trees\Models\TreePlanting;
diff --git a/src/Mod/Trees/Routes/web.php b/src/Mod/Trees/Routes/web.php
index 3268dc0..6be60d0 100644
--- a/src/Mod/Trees/Routes/web.php
+++ b/src/Mod/Trees/Routes/web.php
@@ -1,6 +1,7 @@
<?php
use Core\Mod\Trees\View\Modal\Web\Index as TreesIndex;
+use Core\Tenant\Controllers\ReferralController;
use Illuminate\Support\Facades\Route;
/*
@@ -14,6 +15,6 @@
Route::get('/trees', TreesIndex::class)->name('trees');
// Agent referral tracking (Trees for Agents)
- Route::get('/ref/{provider}/{model?}', [\Core\Tenant\Controllers\ReferralController::class, 'track'])
+ Route::get('/ref/{provider}/{model?}', [ReferralController::class, 'track'])
->name('referral.agent');
});
diff --git a/src/Mod/Trees/Tests/Feature/DailyLimitAndBonusTest.php b/src/Mod/Trees/Tests/Feature/DailyLimitAndBonusTest.php
index 7f58c1c..4975fdd 100644
--- a/src/Mod/Trees/Tests/Feature/DailyLimitAndBonusTest.php
+++ b/src/Mod/Trees/Tests/Feature/DailyLimitAndBonusTest.php
@@ -5,8 +5,9 @@
use Core\Mod\Trees\Models\TreePlanting;
use Core\Mod\Trees\Models\TreeReserve;
use Core\Tenant\Models\AgentReferralBonus;
+use Illuminate\Foundation\Testing\RefreshDatabase;
-uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
+uses(RefreshDatabase::class);
beforeEach(function () {
// Ensure tree reserve has trees available
diff --git a/src/Mod/Trees/Tests/Feature/QueueProcessingTest.php b/src/Mod/Trees/Tests/Feature/QueueProcessingTest.php
index e0a5194..f8a6623 100644
--- a/src/Mod/Trees/Tests/Feature/QueueProcessingTest.php
+++ b/src/Mod/Trees/Tests/Feature/QueueProcessingTest.php
@@ -4,8 +4,9 @@
use Core\Mod\Trees\Models\TreePlanting;
use Core\Mod\Trees\Models\TreeReserve;
+use Illuminate\Foundation\Testing\RefreshDatabase;
-uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
+uses(RefreshDatabase::class);
beforeEach(function () {
TreeReserve::replenish(100);
diff --git a/src/Mod/Trees/Tests/Feature/ReferralRouteTest.php b/src/Mod/Trees/Tests/Feature/ReferralRouteTest.php
index a495ab9..878b2c0 100644
--- a/src/Mod/Trees/Tests/Feature/ReferralRouteTest.php
+++ b/src/Mod/Trees/Tests/Feature/ReferralRouteTest.php
@@ -1,8 +1,9 @@
<?php
declare(strict_types=1);
+use Illuminate\Foundation\Testing\RefreshDatabase;
-uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
+uses(RefreshDatabase::class);
describe('Referral Route', function () {
it('stores referral in session for valid provider', function () {
diff --git a/src/Mod/Trees/Tests/Feature/SignupReferralTest.php b/src/Mod/Trees/Tests/Feature/SignupReferralTest.php
index f095781..43351e2 100644
--- a/src/Mod/Trees/Tests/Feature/SignupReferralTest.php
+++ b/src/Mod/Trees/Tests/Feature/SignupReferralTest.php
@@ -7,8 +7,9 @@
use Core\Mod\Trees\Models\TreeReserve;
use Core\Tenant\Models\User;
use Illuminate\Auth\Events\Registered;
+use Illuminate\Foundation\Testing\RefreshDatabase;
-uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
+uses(RefreshDatabase::class);
beforeEach(function () {
// Ensure tree reserve has trees available
diff --git a/src/Mod/Trees/Tests/Feature/StatsApiTest.php b/src/Mod/Trees/Tests/Feature/StatsApiTest.php
index 9eec496..617a4dd 100644
--- a/src/Mod/Trees/Tests/Feature/StatsApiTest.php
+++ b/src/Mod/Trees/Tests/Feature/StatsApiTest.php
@@ -4,8 +4,9 @@
use Core\Mod\Trees\Models\TreePlanting;
use Core\Mod\Trees\Models\TreeReserve;
+use Illuminate\Foundation\Testing\RefreshDatabase;
-uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
+uses(RefreshDatabase::class);
beforeEach(function () {
TreeReserve::replenish(100);
diff --git a/src/Mod/Trees/Tests/Feature/SubscriberMonthlyCommandTest.php b/src/Mod/Trees/Tests/Feature/SubscriberMonthlyCommandTest.php
index bc3d729..0355bc1 100644
--- a/src/Mod/Trees/Tests/Feature/SubscriberMonthlyCommandTest.php
+++ b/src/Mod/Trees/Tests/Feature/SubscriberMonthlyCommandTest.php
@@ -9,8 +9,9 @@
use Core\Tenant\Models\User;
use Core\Tenant\Models\Workspace;
use Core\Tenant\Models\WorkspacePackage;
+use Illuminate\Foundation\Testing\RefreshDatabase;
-uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
+uses(RefreshDatabase::class);
beforeEach(function () {
TreeReserve::replenish(100);
diff --git a/src/Mod/Trees/Tests/Feature/TreePlantingTest.php b/src/Mod/Trees/Tests/Feature/TreePlantingTest.php
index 116ead9..aa98daa 100644
--- a/src/Mod/Trees/Tests/Feature/TreePlantingTest.php
+++ b/src/Mod/Trees/Tests/Feature/TreePlantingTest.php
@@ -7,8 +7,9 @@
use Core\Mod\Trees\Models\TreeReserve;
use Core\Tenant\Models\User;
use Core\Tenant\Models\Workspace;
+use Illuminate\Foundation\Testing\RefreshDatabase;
-uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
+uses(RefreshDatabase::class);
beforeEach(function () {
$this->user = User::factory()->create();
diff --git a/src/Mod/Trees/Tests/Feature/TreesPageTest.php b/src/Mod/Trees/Tests/Feature/TreesPageTest.php
index 1ee7bb2..4435888 100644
--- a/src/Mod/Trees/Tests/Feature/TreesPageTest.php
+++ b/src/Mod/Trees/Tests/Feature/TreesPageTest.php
@@ -4,8 +4,9 @@
use Core\Mod\Trees\Models\TreePlanting;
use Core\Mod\Trees\Models\TreeReserve;
+use Illuminate\Foundation\Testing\RefreshDatabase;
-uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
+uses(RefreshDatabase::class);
beforeEach(function () {
TreeReserve::replenish(100);
diff --git a/src/Mod/Trees/View/Modal/Web/Index.php b/src/Mod/Trees/View/Modal/Web/Index.php
index a1a2e92..b7c7ea3 100644
--- a/src/Mod/Trees/View/Modal/Web/Index.php
+++ b/src/Mod/Trees/View/Modal/Web/Index.php
@@ -6,6 +6,7 @@
use Core\Mod\Trees\Models\TreePlanting;
use Core\Mod\Trees\Models\TreePlantingStats;
+use Illuminate\Contracts\View\View;
use Illuminate\Support\Collection;
use Livewire\Component;
@@ -17,7 +18,7 @@
*/
class Index extends Component
{
- public function render(): \Illuminate\Contracts\View\View
+ public function render(): View
{
return view('trees::web.index', [
'stats' => $this->getGlobalStats(),
diff --git a/src/Plug/CLAUDE.md b/src/Plug/CLAUDE.md
new file mode 100644
index 0000000..e465bca
--- /dev/null
+++ b/src/Plug/CLAUDE.md
@@ -0,0 +1,107 @@
+# Plug -- Plugin System for External Service Integrations
+
+`Core\Plug` is an operation-based plugin architecture for connecting to external services (social networks, Web3, content platforms, chat, business tools). Each provider is split into discrete operation classes rather than monolithic adapters.
+
+## Namespace
+
+`Core\Plug` -- autoloaded from `src/Plug/`.
+
+## Architecture
+
+Providers are organised by category and operation:
+
+```
+Plug/
+ Social/
+ Twitter/
+ Auth.php # implements Authenticable
+ Post.php # implements Postable
+ Delete.php # implements Deletable
+ Media.php # implements MediaUploadable
+ Bluesky/
+ Auth.php
+ Post.php
+ Web3/
+ Content/
+ Chat/
+ Business/
+```
+
+Usage:
+```php
+use Core\Plug\Social\Twitter\Auth;
+use Core\Plug\Social\Twitter\Post;
+
+$auth = new Auth($clientId, $clientSecret, $redirectUrl);
+$post = (new Post())->withToken($token);
+```
+
+## Key Classes
+
+### Boot (ServiceProvider)
+
+Registers `Registry` as a singleton with alias `plug.registry`. Pure library module -- no routes, views, or migrations.
+
+### Registry
+
+Auto-discovers providers from directory structure. Scans categories: `Social`, `Web3`, `Content`, `Chat`, `Business`.
+
+**Public API:**
+
+| Method | Purpose |
+|--------|---------|
+| `discover()` | Scans category directories for provider folders. Idempotent. |
+| `register(id, category, name, namespace)` | Programmatic registration (for external packages). |
+| `identifiers()` | All registered provider identifiers (lowercase). |
+| `has(identifier)` | Check if provider exists. |
+| `get(identifier)` | Get provider metadata (category, name, namespace, path). |
+| `supports(identifier, operation)` | Check if provider has an operation class. |
+| `operation(identifier, operation)` | Get the FQCN for a provider's operation class. |
+| `all()` | All providers as Collection. |
+| `byCategory(category)` | Provider identifiers filtered by category. |
+| `withCapability(operation)` | Providers that support a specific operation. |
+| `displayName(identifier)` | Human-readable name (from Auth::name() or directory name). |
+
+### Response
+
+Standardised response for all Plug operations. Immutable value object.
+
+**Properties:** `status` (Status enum), `context` (array), `rateLimitApproaching` (bool), `retryAfter` (int).
+
+**Methods:** `isOk()`, `hasError()`, `isUnauthorized()`, `isRateLimited()`, `id()`, `get(key)`, `getMessage()`, `retryAfter()`, `toArray()`. Supports magic `__get` for context values.
+
+## Contracts (interfaces)
+
+| Contract | Methods | Purpose |
+|----------|---------|---------|
+| `Authenticable` | `identifier()`, `name()`, `getAuthUrl()`, `requestAccessToken(params)`, `getAccount()` | OAuth2/API key/credential auth flows |
+| `Postable` | `publish(text, media, params)` | Content publishing |
+| `Readable` | `get(id)`, `list(params)` | Read posts/content |
+| `Commentable` | `comment(text, postId, params)` | Reply to content |
+| `Deletable` | `delete(id)` | Delete content |
+| `MediaUploadable` | `upload(item)` | Upload media files |
+| `Listable` | `listEntities()` | List pages/boards/publications (target selection) |
+| `Refreshable` | `refresh()` | Refresh expired access tokens |
+
+## Concerns (traits)
+
+| Trait | Purpose |
+|-------|---------|
+| `BuildsResponse` | Response factory helpers: `ok()`, `error()`, `unauthorized()`, `rateLimit()`, `noContent()`, `fromHttp()`. The `fromHttp()` method auto-maps HTTP status codes (401, 429) to correct Response types. |
+| `ManagesTokens` | Token lifecycle: `withToken()`, `getToken()`, `accessToken()`, `hasRefreshToken()`, `refreshToken()`, `tokenExpiresSoon(minutes)`, `tokenExpired()`. Fluent interface via `withToken()`. |
+| `UsesHttp` | HTTP client helpers: `http()` (configured PendingRequest with 30s timeout, JSON accept, User-Agent), `buildUrl()`. Override `defaultHeaders()` for provider-specific headers. |
+
+## Enum
+
+`Status` -- string-backed: `OK`, `ERROR`, `UNAUTHORIZED`, `RATE_LIMITED`, `NO_CONTENT`.
+
+## Integration Pattern
+
+1. Create provider directory under the appropriate category
+2. Implement operation classes using contracts + concerns
+3. Registry auto-discovers on first access (or register programmatically)
+4. All operations return `Response` objects for consistent error handling
+
+## Categories
+
+`Social`, `Web3`, `Content`, `Chat`, `Business`
diff --git a/src/Website/CLAUDE.md b/src/Website/CLAUDE.md
new file mode 100644
index 0000000..1e3c79f
--- /dev/null
+++ b/src/Website/CLAUDE.md
@@ -0,0 +1,87 @@
+# Website -- Domain-Scoped Module System
+
+`Core\Website` provides lazy-loading of website modules based on the incoming HTTP domain. Only the matching provider is registered for a given request, isolating errors so one broken website does not take down others.
+
+## Namespace
+
+`Core\Website` -- autoloaded from `src/Website/`.
+
+## How It Works
+
+### Web Requests
+
+1. `Website\Boot::register()` reads `$_SERVER['HTTP_HOST']`
+2. Dispatches a `DomainResolving` event with the hostname
+3. Website modules listening for `DomainResolving` check if the host matches their `$domains` patterns
+4. The first matching provider is registered via `$app->register()`
+5. Only that one provider boots -- all others are skipped
+
+### CLI Context (artisan, tests, queues)
+
+All website providers are loaded via `registerAllProviders()`, which scans `app/Mod/*/Boot.php` for website module Boot classes. This ensures artisan commands, seeders, and queue workers can access all website modules.
+
+## Files
+
+### Boot.php (ServiceProvider)
+
+- Registers `DomainResolver` as singleton
+- Web: fires `DomainResolving` event, registers matched provider
+- CLI: loads all providers from `app/Mod/`
+- Provider load order: must come before `Front\Boot` so listeners are wired before frontage events fire
+
+### DomainResolver
+
+Utility for working with domain patterns. Website Boot classes declare domains as regex patterns:
+
+```php
+class Boot extends ServiceProvider
+{
+ public static array $domains = [
+ '/^example\.(com|test)$/',
+ ];
+}
+```
+
+**Methods:**
+
+| Method | Purpose |
+|--------|---------|
+| `extractDomains(providerClass)` | Read `$domains` static property via reflection |
+| `domainsFor(providerClass)` | Convert regex patterns to concrete domain strings. In local env, filters to `.test`/`.localhost` only. |
+
+Pattern expansion handles:
+- Fixed domains: `example.com`
+- TLD alternatives: `example\.(com|test)` -> `example.com`, `example.test`
+- Optional www prefix: `(www\.)?example\.com`
+
+## Writing a Website Module
+
+Website modules live in `app/Mod/{Name}/` (not `src/Mod/`). They use the same `$listens` pattern as regular modules:
+
+```php
+namespace Mod\MyWebsite;
+
+class Boot extends ServiceProvider
+{
+ public static array $domains = [
+ '/^mysite\.(com|test)$/',
+ ];
+
+ public static array $listens = [
+ WebRoutesRegistering::class => 'onWebRoutes',
+ ];
+
+ public function onWebRoutes(WebRoutesRegistering $event): void
+ {
+ $event->routes(fn () => require __DIR__.'/Routes/web.php');
+ $event->views('mysite', __DIR__.'/Views');
+ }
+}
+```
+
+## Key Design Decisions
+
+- **Isolation**: One broken website module cannot crash others since only the matched provider loads
+- **Lazy loading**: Website modules are not instantiated unless their domain matches
+- **Dual paths**: Framework-bundled modules in `src/Mod/`, application modules in `app/Mod/`
+- **Environment-aware**: Local dev only serves `.test`/`.localhost` domains from `domainsFor()`
diff --git a/tests/Feature/ActivityLogServiceTest.php b/tests/Feature/ActivityLogServiceTest.php
index bb89134..868e8b3 100644
--- a/tests/Feature/ActivityLogServiceTest.php
+++ b/tests/Feature/ActivityLogServiceTest.php
@@ -7,6 +7,7 @@
use Core\Activity\Services\ActivityLogService;
use Core\Tests\TestCase;
use Illuminate\Foundation\Testing\RefreshDatabase;
+use Spatie\Activitylog\ActivitylogServiceProvider;
use Spatie\Activitylog\Models\Activity;
class ActivityLogServiceTest extends TestCase
@@ -18,7 +19,7 @@ class ActivityLogServiceTest extends TestCase
protected function getPackageProviders($app): array
{
return array_merge(parent::getPackageProviders($app), [
- \Spatie\Activitylog\ActivitylogServiceProvider::class,
+ ActivitylogServiceProvider::class,
]);
}
diff --git a/tests/Feature/LazyModuleListenerTest.php b/tests/Feature/LazyModuleListenerTest.php
index f85abdb..b9787a4 100644
--- a/tests/Feature/LazyModuleListenerTest.php
+++ b/tests/Feature/LazyModuleListenerTest.php
@@ -9,6 +9,7 @@
use Core\LazyModuleListener;
use Core\Tests\TestCase;
use Illuminate\Support\ServiceProvider;
+use Mod\ServiceProviderModule\Boot;
class LazyModuleListenerTest extends TestCase
{
@@ -129,7 +130,7 @@ public function test_listener_resolves_service_providers_correctly(): void
require_once $this->getFixturePath('Mod/ServiceProviderModule/Boot.php');
$listener = new LazyModuleListener(
- \Mod\ServiceProviderModule\Boot::class,
+ Boot::class,
'onWebRoutes'
);
diff --git a/tests/Feature/LifecycleEventsTest.php b/tests/Feature/LifecycleEventsTest.php
index 7fbf14b..552ec93 100644
--- a/tests/Feature/LifecycleEventsTest.php
+++ b/tests/Feature/LifecycleEventsTest.php
@@ -15,48 +15,15 @@
use Core\Events\QueueWorkerBooting;
use Core\Events\SearchRequested;
use Core\Events\WebRoutesRegistering;
-use Core\Front\Mcp\Contracts\McpToolHandler;
use Core\Tests\TestCase;
-// Test fixture implementing McpToolHandler
-class TestMcpHandler implements McpToolHandler
-{
- public static function schema(): array
- {
- return ['name' => 'test', 'description' => 'Test', 'inputSchema' => []];
- }
+// Test fixtures — McpToolsRegistering stores class names as strings,
+// so these don't need to implement the McpToolHandler interface (lives in core-mcp).
+class TestMcpHandler {}
- public function handle(array $args, \Core\Front\Mcp\McpContext $context): array
- {
- return [];
- }
-}
+class TestMcpHandler2 {}
-class TestMcpHandler2 implements McpToolHandler
-{
- public static function schema(): array
- {
- return ['name' => 'test2', 'description' => 'Test 2', 'inputSchema' => []];
- }
-
- public function handle(array $args, \Core\Front\Mcp\McpContext $context): array
- {
- return [];
- }
-}
-
-class TestMcpHandler3 implements McpToolHandler
-{
- public static function schema(): array
- {
- return ['name' => 'test3', 'description' => 'Test 3', 'inputSchema' => []];
- }
-
- public function handle(array $args, \Core\Front\Mcp\McpContext $context): array
- {
- return [];
- }
-}
+class TestMcpHandler3 {}
class LifecycleEventsTest extends TestCase
{
diff --git a/tests/Feature/LogsActivityTraitTest.php b/tests/Feature/LogsActivityTraitTest.php
index 1ad8e75..78c9951 100644
--- a/tests/Feature/LogsActivityTraitTest.php
+++ b/tests/Feature/LogsActivityTraitTest.php
@@ -10,6 +10,7 @@
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Schema;
+use Spatie\Activitylog\ActivitylogServiceProvider;
use Spatie\Activitylog\LogOptions;
use Spatie\Activitylog\Models\Activity;
@@ -56,7 +57,7 @@ class LogsActivityTraitTest extends TestCase
protected function getPackageProviders($app): array
{
return array_merge(parent::getPackageProviders($app), [
- \Spatie\Activitylog\ActivitylogServiceProvider::class,
+ ActivitylogServiceProvider::class,
]);
}
diff --git a/tests/Feature/ModuleScannerTest.php b/tests/Feature/ModuleScannerTest.php
index 992b3dc..df446a6 100644
--- a/tests/Feature/ModuleScannerTest.php
+++ b/tests/Feature/ModuleScannerTest.php
@@ -9,6 +9,7 @@
use Core\Events\WebRoutesRegistering;
use Core\ModuleScanner;
use Core\Tests\TestCase;
+use Mod\PrivateListens\Boot;
class ModuleScannerTest extends TestCase
{
@@ -145,7 +146,7 @@ public function test_extract_listens_returns_empty_for_private_listens(): void
{
require_once $this->getFixturePath('Mod/PrivateListens/Boot.php');
- $result = $this->scanner->extractListens(\Mod\PrivateListens\Boot::class);
+ $result = $this->scanner->extractListens(Boot::class);
$this->assertIsArray($result);
$this->assertEmpty($result);
diff --git a/tests/Feature/ScheduleSyncCommandTest.php b/tests/Feature/ScheduleSyncCommandTest.php
index 8200310..66c2d07 100644
--- a/tests/Feature/ScheduleSyncCommandTest.php
+++ b/tests/Feature/ScheduleSyncCommandTest.php
@@ -6,6 +6,7 @@
use Core\Actions\ScheduledAction;
use Core\Console\Commands\ScheduleSyncCommand;
+use Illuminate\Contracts\Console\Kernel;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Orchestra\Testbench\TestCase;
@@ -36,7 +37,7 @@ protected function setUp(): void
{
parent::setUp();
- $this->app->make(\Illuminate\Contracts\Console\Kernel::class)->registerCommand(
+ $this->app->make(Kernel::class)->registerCommand(
$this->app->make(ScheduleSyncCommand::class)
);
}
diff --git a/tests/Feature/ScheduledActionScannerTest.php b/tests/Feature/ScheduledActionScannerTest.php
index b228689..68ae539 100644
--- a/tests/Feature/ScheduledActionScannerTest.php
+++ b/tests/Feature/ScheduledActionScannerTest.php
@@ -17,7 +17,7 @@ class ScheduledActionScannerTest extends TestCase
protected function setUp(): void
{
parent::setUp();
- $this->scanner = new ScheduledActionScanner();
+ $this->scanner = new ScheduledActionScanner;
}
public function test_scan_discovers_scheduled_actions(): void
diff --git a/tests/Feature/ScheduledAttributeTest.php b/tests/Feature/ScheduledAttributeTest.php
index 048512b..d769b0a 100644
--- a/tests/Feature/ScheduledAttributeTest.php
+++ b/tests/Feature/ScheduledAttributeTest.php
@@ -57,6 +57,4 @@ public function test_attribute_can_be_read_from_class(): void
}
#[Scheduled(frequency: 'everyMinute')]
-class ScheduledAttributeTest_Stub
-{
-}
+class ScheduledAttributeTest_Stub {}
diff --git a/tests/Feature/SeederDiscoveryTest.php b/tests/Feature/SeederDiscoveryTest.php
index 2b92c58..5a7663a 100644
--- a/tests/Feature/SeederDiscoveryTest.php
+++ b/tests/Feature/SeederDiscoveryTest.php
@@ -9,6 +9,12 @@
use Core\Database\Seeders\Exceptions\CircularDependencyException;
use Core\Database\Seeders\SeederDiscovery;
use Core\Tests\TestCase;
+use Mod\Alpha\Database\Seeders\AlphaSeeder;
+use Mod\Beta\Database\Seeders\BetaSeeder;
+use Mod\Circular\Database\Seeders\CircularASeeder;
+use Mod\Circular\Database\Seeders\CircularBSeeder;
+use Mod\Gamma\Database\Seeders\DeltaSeeder;
+use Mod\Gamma\Database\Seeders\GammaSeeder;
class SeederDiscoveryTest extends TestCase
{
@@ -50,30 +56,30 @@ public function test_discovers_seeders_from_paths(): void
{
// Exclude circular dependency seeders for this test
$this->discovery->exclude([
- \Mod\Circular\Database\Seeders\CircularASeeder::class,
- \Mod\Circular\Database\Seeders\CircularBSeeder::class,
+ CircularASeeder::class,
+ CircularBSeeder::class,
]);
$seeders = $this->discovery->getSeeders();
- $this->assertArrayHasKey(\Mod\Alpha\Database\Seeders\AlphaSeeder::class, $seeders);
- $this->assertArrayHasKey(\Mod\Beta\Database\Seeders\BetaSeeder::class, $seeders);
- $this->assertArrayHasKey(\Mod\Gamma\Database\Seeders\GammaSeeder::class, $seeders);
- $this->assertArrayHasKey(\Mod\Gamma\Database\Seeders\DeltaSeeder::class, $seeders);
+ $this->assertArrayHasKey(AlphaSeeder::class, $seeders);
+ $this->assertArrayHasKey(BetaSeeder::class, $seeders);
+ $this->assertArrayHasKey(GammaSeeder::class, $seeders);
+ $this->assertArrayHasKey(DeltaSeeder::class, $seeders);
}
public function test_extracts_priority_from_property(): void
{
$seeders = $this->discovery->getSeeders();
- $this->assertEquals(10, $seeders[\Mod\Alpha\Database\Seeders\AlphaSeeder::class]['priority']);
+ $this->assertEquals(10, $seeders[AlphaSeeder::class]['priority']);
}
public function test_extracts_priority_from_attribute(): void
{
$seeders = $this->discovery->getSeeders();
- $this->assertEquals(50, $seeders[\Mod\Beta\Database\Seeders\BetaSeeder::class]['priority']);
+ $this->assertEquals(50, $seeders[BetaSeeder::class]['priority']);
}
public function test_uses_default_priority_when_not_specified(): void
@@ -83,7 +89,7 @@ public function test_uses_default_priority_when_not_specified(): void
// CircularASeeder has no priority declaration
$this->assertEquals(
SeederDiscovery::DEFAULT_PRIORITY,
- $seeders[\Mod\Circular\Database\Seeders\CircularASeeder::class]['priority']
+ $seeders[CircularASeeder::class]['priority']
);
}
@@ -92,8 +98,8 @@ public function test_extracts_after_dependencies_from_property(): void
$seeders = $this->discovery->getSeeders();
$this->assertContains(
- \Mod\Beta\Database\Seeders\BetaSeeder::class,
- $seeders[\Mod\Gamma\Database\Seeders\GammaSeeder::class]['after']
+ BetaSeeder::class,
+ $seeders[GammaSeeder::class]['after']
);
}
@@ -102,8 +108,8 @@ public function test_extracts_after_dependencies_from_attribute(): void
$seeders = $this->discovery->getSeeders();
$this->assertContains(
- \Mod\Alpha\Database\Seeders\AlphaSeeder::class,
- $seeders[\Mod\Beta\Database\Seeders\BetaSeeder::class]['after']
+ AlphaSeeder::class,
+ $seeders[BetaSeeder::class]['after']
);
}
@@ -112,8 +118,8 @@ public function test_extracts_before_dependencies_from_attribute(): void
$seeders = $this->discovery->getSeeders();
$this->assertContains(
- \Mod\Beta\Database\Seeders\BetaSeeder::class,
- $seeders[\Mod\Gamma\Database\Seeders\DeltaSeeder::class]['before']
+ BetaSeeder::class,
+ $seeders[DeltaSeeder::class]['before']
);
}
@@ -123,11 +129,11 @@ public function test_sorts_seeders_by_priority(): void
$discovery = new SeederDiscovery(
[$this->getFixturePath('Mod')],
[
- \Mod\Beta\Database\Seeders\BetaSeeder::class,
- \Mod\Gamma\Database\Seeders\GammaSeeder::class,
- \Mod\Gamma\Database\Seeders\DeltaSeeder::class,
- \Mod\Circular\Database\Seeders\CircularASeeder::class,
- \Mod\Circular\Database\Seeders\CircularBSeeder::class,
+ BetaSeeder::class,
+ GammaSeeder::class,
+ DeltaSeeder::class,
+ CircularASeeder::class,
+ CircularBSeeder::class,
]
);
@@ -135,21 +141,21 @@ public function test_sorts_seeders_by_priority(): void
// Only AlphaSeeder should remain
$this->assertCount(1, $ordered);
- $this->assertEquals(\Mod\Alpha\Database\Seeders\AlphaSeeder::class, $ordered[0]);
+ $this->assertEquals(AlphaSeeder::class, $ordered[0]);
}
public function test_respects_dependency_ordering(): void
{
$this->discovery->exclude([
- \Mod\Circular\Database\Seeders\CircularASeeder::class,
- \Mod\Circular\Database\Seeders\CircularBSeeder::class,
+ CircularASeeder::class,
+ CircularBSeeder::class,
]);
$ordered = $this->discovery->discover();
- $alphaIndex = array_search(\Mod\Alpha\Database\Seeders\AlphaSeeder::class, $ordered);
- $betaIndex = array_search(\Mod\Beta\Database\Seeders\BetaSeeder::class, $ordered);
- $gammaIndex = array_search(\Mod\Gamma\Database\Seeders\GammaSeeder::class, $ordered);
+ $alphaIndex = array_search(AlphaSeeder::class, $ordered);
+ $betaIndex = array_search(BetaSeeder::class, $ordered);
+ $gammaIndex = array_search(GammaSeeder::class, $ordered);
// Alpha must come before Beta (Beta has SeederAfter(Alpha))
$this->assertLessThan($betaIndex, $alphaIndex, 'Alpha should run before Beta');
@@ -161,14 +167,14 @@ public function test_respects_dependency_ordering(): void
public function test_respects_before_dependency(): void
{
$this->discovery->exclude([
- \Mod\Circular\Database\Seeders\CircularASeeder::class,
- \Mod\Circular\Database\Seeders\CircularBSeeder::class,
+ CircularASeeder::class,
+ CircularBSeeder::class,
]);
$ordered = $this->discovery->discover();
- $deltaIndex = array_search(\Mod\Gamma\Database\Seeders\DeltaSeeder::class, $ordered);
- $betaIndex = array_search(\Mod\Beta\Database\Seeders\BetaSeeder::class, $ordered);
+ $deltaIndex = array_search(DeltaSeeder::class, $ordered);
+ $betaIndex = array_search(BetaSeeder::class, $ordered);
// Delta must come before Beta (Delta has SeederBefore(Beta))
$this->assertLessThan($betaIndex, $deltaIndex, 'Delta should run before Beta');
@@ -203,14 +209,14 @@ public function test_circular_dependency_exception_contains_cycle(): void
public function test_exclusion_filter_works(): void
{
$this->discovery->exclude([
- \Mod\Alpha\Database\Seeders\AlphaSeeder::class,
- \Mod\Circular\Database\Seeders\CircularASeeder::class,
- \Mod\Circular\Database\Seeders\CircularBSeeder::class,
+ AlphaSeeder::class,
+ CircularASeeder::class,
+ CircularBSeeder::class,
]);
$seeders = $this->discovery->getSeeders();
- $this->assertArrayNotHasKey(\Mod\Alpha\Database\Seeders\AlphaSeeder::class, $seeders);
+ $this->assertArrayNotHasKey(AlphaSeeder::class, $seeders);
}
public function test_add_paths_appends_to_existing(): void
@@ -222,8 +228,8 @@ public function test_add_paths_appends_to_existing(): void
$seeders = $discovery->getSeeders();
- $this->assertArrayHasKey(\Mod\Alpha\Database\Seeders\AlphaSeeder::class, $seeders);
- $this->assertArrayHasKey(\Mod\Beta\Database\Seeders\BetaSeeder::class, $seeders);
+ $this->assertArrayHasKey(AlphaSeeder::class, $seeders);
+ $this->assertArrayHasKey(BetaSeeder::class, $seeders);
}
public function test_set_paths_replaces_existing(): void
@@ -234,15 +240,15 @@ public function test_set_paths_replaces_existing(): void
$discovery->setPaths([$this->getFixturePath('Mod/Beta')]);
$seeders = $discovery->getSeeders();
- $this->assertArrayNotHasKey(\Mod\Alpha\Database\Seeders\AlphaSeeder::class, $seeders);
- $this->assertArrayHasKey(\Mod\Beta\Database\Seeders\BetaSeeder::class, $seeders);
+ $this->assertArrayNotHasKey(AlphaSeeder::class, $seeders);
+ $this->assertArrayHasKey(BetaSeeder::class, $seeders);
}
public function test_reset_clears_cache(): void
{
$this->discovery->exclude([
- \Mod\Circular\Database\Seeders\CircularASeeder::class,
- \Mod\Circular\Database\Seeders\CircularBSeeder::class,
+ CircularASeeder::class,
+ CircularBSeeder::class,
]);
$seeders1 = $this->discovery->getSeeders();
diff --git a/tests/Feature/WebhookControllerTest.php b/tests/Feature/WebhookControllerTest.php
index 3f68725..125e0c5 100644
--- a/tests/Feature/WebhookControllerTest.php
+++ b/tests/Feature/WebhookControllerTest.php
@@ -6,6 +6,7 @@
use Core\Tests\TestCase;
use Core\Webhook\WebhookCall;
+use Core\Webhook\WebhookController;
use Core\Webhook\WebhookReceived;
use Core\Webhook\WebhookVerifier;
use Illuminate\Foundation\Testing\RefreshDatabase;
@@ -23,7 +24,7 @@ protected function defineDatabaseMigrations(): void
protected function defineRoutes($router): void
{
- $router->post('/webhooks/{source}', [\Core\Webhook\WebhookController::class, 'handle'])
+ $router->post('/webhooks/{source}', [WebhookController::class, 'handle'])
->where('source', '[a-z0-9\-]+');
}
diff --git a/tests/Fixtures/Mod/Alpha/Database/Seeders/AlphaSeeder.php b/tests/Fixtures/Mod/Alpha/Database/Seeders/AlphaSeeder.php
index 2ae8ef7..4d59e4c 100644
--- a/tests/Fixtures/Mod/Alpha/Database/Seeders/AlphaSeeder.php
+++ b/tests/Fixtures/Mod/Alpha/Database/Seeders/AlphaSeeder.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
namespace Mod\Alpha\Database\Seeders;
use Illuminate\Database\Seeder;
diff --git a/tests/Fixtures/Mod/Beta/Database/Seeders/BetaSeeder.php b/tests/Fixtures/Mod/Beta/Database/Seeders/BetaSeeder.php
index 48b3997..b24acd7 100644
--- a/tests/Fixtures/Mod/Beta/Database/Seeders/BetaSeeder.php
+++ b/tests/Fixtures/Mod/Beta/Database/Seeders/BetaSeeder.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
namespace Mod\Beta\Database\Seeders;
use Core\Database\Seeders\Attributes\SeederAfter;
diff --git a/tests/Fixtures/Mod/Circular/Database/Seeders/CircularASeeder.php b/tests/Fixtures/Mod/Circular/Database/Seeders/CircularASeeder.php
index 8feb4a0..6d9c699 100644
--- a/tests/Fixtures/Mod/Circular/Database/Seeders/CircularASeeder.php
+++ b/tests/Fixtures/Mod/Circular/Database/Seeders/CircularASeeder.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
namespace Mod\Circular\Database\Seeders;
use Illuminate\Database\Seeder;
diff --git a/tests/Fixtures/Mod/Circular/Database/Seeders/CircularBSeeder.php b/tests/Fixtures/Mod/Circular/Database/Seeders/CircularBSeeder.php
index 957d08e..2270be4 100644
--- a/tests/Fixtures/Mod/Circular/Database/Seeders/CircularBSeeder.php
+++ b/tests/Fixtures/Mod/Circular/Database/Seeders/CircularBSeeder.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
namespace Mod\Circular\Database\Seeders;
use Illuminate\Database\Seeder;
diff --git a/tests/Fixtures/Mod/Gamma/Database/Seeders/DeltaSeeder.php b/tests/Fixtures/Mod/Gamma/Database/Seeders/DeltaSeeder.php
index 624ed09..f6bce83 100644
--- a/tests/Fixtures/Mod/Gamma/Database/Seeders/DeltaSeeder.php
+++ b/tests/Fixtures/Mod/Gamma/Database/Seeders/DeltaSeeder.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
namespace Mod\Gamma\Database\Seeders;
use Core\Database\Seeders\Attributes\SeederBefore;
diff --git a/tests/Fixtures/Mod/Gamma/Database/Seeders/GammaSeeder.php b/tests/Fixtures/Mod/Gamma/Database/Seeders/GammaSeeder.php
index 4b39141..acb106f 100644
--- a/tests/Fixtures/Mod/Gamma/Database/Seeders/GammaSeeder.php
+++ b/tests/Fixtures/Mod/Gamma/Database/Seeders/GammaSeeder.php
@@ -1,5 +1,7 @@
<?php
+declare(strict_types=1);
+
namespace Mod\Gamma\Database\Seeders;
use Illuminate\Database\Seeder;
diff --git a/tests/cli/php/Taskfile.yaml b/tests/cli/php/Taskfile.yaml
new file mode 100644
index 0000000..a3b0d27
--- /dev/null
+++ b/tests/cli/php/Taskfile.yaml
@@ -0,0 +1,26 @@
+version: "3"
+
+tasks:
+ default:
+ deps:
+ - build
+ - vet
+ - test
+
+ build:
+ desc: Compile every package in php.
+ dir: ../../..
+ cmds:
+ - GOWORK=off go build ./...
+
+ vet:
+ desc: Run go vet across the module.
+ dir: ../../..
+ cmds:
+ - GOWORK=off go vet ./...
+
+ test:
+ desc: Run unit tests.
+ dir: ../../..
+ cmds:
+ - GOWORK=off go test -count=1 ./...