Drop duplicate 'logout' route name so route:cache works

The SPA's GET /logout and Fortify's POST /logout both carried the name
'logout', which is fine at runtime (distinct verbs, same URL) but breaks
route:cache (names must be unique for serialization). The Blade auth forms
target route('logout') = Fortify's POST route, so the custom GET route — used
by the SPA via a literal /logout URL — no longer needs the name.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.claude/rules/architecture.md

@@ -1,57 +1,118 @@
 # Architecture
 
+## Shape: Vue SPA ⇄ REST API ⇄ fat Laravel Services
+
+The frontend is a **Vue 3 single-page app** (`resources/js/`). It talks to the
+backend exclusively over a **REST API** (`routes/api.php` →
+`app/Http/Controllers/Api/`). Controllers stay thin; all business logic lives in
+**Service classes** (`app/Services/`). Blade is reduced to a one-line SPA shell,
+server-rendered legal pages, transactional emails, and the Filament admin panel.
+
+```
+Browser
+  └── Vue SPA (resources/js, mounted on #app via app.blade.php)
+        └── axios (resources/js/axios.js — baseURL '/api', cookie + XSRF auth)
+              └── REST API (routes/api.php → Http/Controllers/Api/*)
+                    └── Services (app/Services/*)   ← all business logic
+                          └── Models / Jobs / Events / Notifications
+```
+
 ## Core principle: fat Services, thin everything else
 
-All business logic lives in Service classes. Controllers, Livewire components,
+All business logic lives in Service classes. API controllers, console commands,
-and console commands are thin orchestrators — they call Services and return results.
+jobs, listeners, and Filament resources are thin orchestrators — they call
-This keeps the app API-extractable later without a rewrite.
+Services and return results. Never put domain logic in a controller or a Vue
+component.
 
-## Directory structure
+## Directory structure (actual)
 
 ```
 app/
-├── Console/Commands/       # Scheduler commands (PollFuelPrices, PredictOilPrices, RunScoringEngine)
+├── Console/Commands/   # Scheduler: PollFuelPrices, FetchOilPrices, BackfillOilPrices,
-├── Http/Controllers/       # Minimal — auth + Stripe webhook only
+│                       #   RunLlmOverlay, EvaluateVolatilityRegime, ResolveForecastOutcomes,
-├── Livewire/               # Classic two-file Livewire components
+│                       #   ArchiveOldPricesCommand, ImportBeisFuelPrices, ImportPostcodes
-├── Models/                 # Eloquent models
+├── Http/
-├── Notifications/          # Laravel Notification classes (multi-channel)
+│   ├── Controllers/Api/   # AuthController, StationController, StatsController, UserController
-├── Services/               # ALL business logic lives here
+│   ├── Controllers/       # BillingController (Stripe Checkout/Portal redirects)
-│   ├── FuelPriceService.php        # Fuel Finder API polling + storage
+│   ├── Middleware/        # VerifyApiKey (API-key gate), RequiresFeature (tier gate)
-│   ├── AlertScoringService.php     # Fill-up timing recommendation engine
+│   ├── Requests/          # Form requests
-│   ├── StationTaggingService.php   # Supermarket brand detection
+│   └── Resources/Api/     # StationResource (API output shaping)
-│   ├── NotificationDispatchService.php  # Tier-aware notification routing
+├── Actions/Fortify/    # Fortify auth actions (CreateNewUser, …)
-│   ├── SubscriptionService.php    # Cashier/tier helpers
+├── Services/           # ALL business logic — see below
-│   ├── PostcodeService.php         # Resolves postcodes/outcodes/place names → lat/lng
+├── Models/             # Eloquent models
-│   ├── OilPriceService.php         # FRED fetch + EWMA/LLM Brent crude prediction
+├── Notifications/      # FuelPriceAlert + custom Channels (OneSignal, Vonage WA/SMS)
-│   ├── LocationResult.php          # DTO returned by PostcodeService
+├── Jobs/               # DispatchUserNotificationJob, PollFuelPricesJob,
-│   └── ApiLogger.php               # Wraps all outbound HTTP calls, logs to api_logs
+│                       #   SendScheduledWhatsAppJob, SendPaymentFailedReminderJob
-└── Jobs/                   # Queued jobs (dispatch notifications per user)
+├── Events/             # PricesUpdatedEvent
+├── Listeners/          # HandleStripeWebhook (Cashier WebhookReceived)
+├── Filament/           # Admin panel (Resources, Widgets) + Providers/Filament
+├── Enums/              # FuelType, PlanTier, …
+└── Livewire/Actions/   # Logout only — Livewire is otherwise vestigial
 
-resources/views/
+app/Services/
-├── livewire/               # Livewire Blade templates
+├── FuelPriceService.php       # Fuel Finder API polling + storage
-└── emails/                 # Mailable templates
+├── StationTaggingService.php  # Supermarket brand detection
+├── PostcodeService.php        # postcode/outcode/place → lat/lng (+ LocationResult DTO)
+├── PlanFeatures.php           # Single source of tier-entitlement truth (see tiers.md)
+├── HaversineQuery.php         # Distance SQL helper
+├── ApiLogger.php              # Wraps outbound HTTP, logs to api_logs
+├── StationSearch/             # StationSearchService (+ SearchCriteria, SearchResult DTOs)
+├── BrentPriceSources/         # FRED + EIA Brent sources (+ BrentPriceFetcher)
+└── Forecasting/               # Weekly forecast subsystem — WeeklyForecastService,
+                               #   LlmOverlayService, BacktestRunner, OutcomeResolver,
+                               #   VolatilityRegimeService, feature/leak tooling, …
+
+resources/
+├── js/                 # Vue 3 SPA — see .claude/rules/frontend.md
+└── views/
+    ├── app.blade.php   # SPA shell (mounts #app)
+    ├── legal/          # Server-rendered legal pages
+    ├── emails/         # Mailable templates
+    └── livewire/auth/  # Starter-kit Volt auth screens (left untouched)
 
 routes/
-├── web.php                 # All web routes (Livewire pages)
+├── web.php             # SPA shell + catch-all, legal pages, billing redirects, server logout
-└── api.php                 # Empty for now — API added later if needed
+└── api.php             # REST API consumed by the SPA (see below)
 ```
 
+> **Stale service names elsewhere.** Domain rule files (`scoring.md`,
+> `prediction.md`, `notifications.md`) still name services that have since been
+> refactored away — e.g. `AlertScoringService`, `OilPriceService`,
+> `NationalFuelPredictionService`, `NotificationDispatchService`,
+> `SubscriptionService`. Those concerns now live under `Services/Forecasting/`,
+> `Services/StationSearch/`, and `PlanFeatures`. Always verify a service name
+> against `app/Services/` before trusting it from those files.
+
 ## Service class conventions
 
 - Constructor injection only — no facade usage inside Services
-- Services are bound in AppServiceProvider if they need interfaces
 - Each Service has one responsibility — do not merge concerns
 - Return typed DTOs or Eloquent collections — never raw arrays from Services
-- Services never dispatch jobs directly — that's the controller/command's job
+- Services never dispatch jobs directly — that's the controller/command/listener's job
 
-## No API yet
+## The REST API
 
-`routes/api.php` stays empty for v1. Do not create API controllers or Sanctum
+`routes/api.php` is the SPA's backend. Three access tiers:
-token auth. The app is Livewire-only until subscriber count justifies a native app.
-When the API is added later, it will reuse the same Service classes.
 
-## Livewire components (classic only)
+- **Public** (no auth): `POST /api/auth/register`, `POST /api/auth/login`,
+  `GET /api/auth/me`, `GET /api/fuel-types`, `GET /api/stats/live`
+- **API-key** (`VerifyApiKey` + `throttle:60,1`): `GET /api/stations`,
+  `GET /api/stats/searches`
+- **Sanctum** (`auth:sanctum`): `POST /api/auth/logout`, `/api/user/*`
+  (preferences, saved stations, profile, password, delete account)
 
-Use two-file classic Livewire components. Do NOT use Volt single-file syntax.
+Conventions:
-Volt files from the starter kit (auth screens) are left as-is — do not convert them.
+
-New components go in `app/Livewire/` with corresponding Blade in `resources/views/livewire/`.
+- Shape responses with API Resources (`app/Http/Resources/Api/`), never raw arrays.
+- The fuel **prediction is embedded in the `/api/stations` response** under the
+  `prediction` key — there is no standalone prediction endpoint (see `prediction.md`).
+- Tier-gate routes with the `feature` middleware (`RequiresFeature`); never
+  inline entitlement checks (see `tiers.md`).
+- Auth is cookie/session via Sanctum SPA mode (axios sends XSRF + credentials);
+  the API-key gate protects the expensive station search from scraping.
+
+## Frontend
+
+The Vue SPA is documented in `.claude/rules/frontend.md`. Do **not** build new
+Livewire components — Livewire/Flux remain only for the starter-kit auth screens
+and the `Logout` action.

.claude/rules/frontend.md

@@ -0,0 +1,74 @@
+# Frontend — Vue 3 SPA
+
+The entire user-facing app (landing, station search, dashboard, settings) is a
+**Vue 3 single-page application** under `resources/js/`. It is served from the
+Blade shell `resources/views/app.blade.php` via the SPA catch-all in
+`routes/web.php` and consumes the REST API (`routes/api.php`). There is **no
+Livewire in the product UI** — do not add Livewire / Volt / Alpine components for
+new features. Build Vue.
+
+## Stack
+
+- Vue 3.5 with `<script setup>` (Composition API), Vue Router 4 (`createWebHistory`)
+- Vite 8 (`npm run dev` / `npm run build`), `@vitejs/plugin-vue`
+- Tailwind CSS v4 (`@tailwindcss/vite`)
+- Leaflet for maps, iconify-icon + Lucide for icons, axios for HTTP
+
+## Layout
+
+```
+resources/js/
+├── app.js              # Entry — createApp(App).use(router).mount('#app')
+├── App.vue             # Root — <RouterView/>, fetches the user on mount
+├── axios.js            # Configured axios instance (baseURL '/api', XSRF + credentials)
+├── router/index.js     # Routes + requiresAuth guard (redirects to /login)
+├── views/
+│   ├── Home.vue            # Landing + station search (mirrors state to the URL query)
+│   └── dashboard/          # Overview, SavedStations, Preferences, settings/{Profile,Security,Appearance}
+├── components/         # LeafletMap, StationCard, StationList, PredictionCard/Full,
+│                       #   PostSearchFilters, UpsellBanner, landing/*
+├── composables/        # useAuth, useStations, useSavedStations
+└── constants/          # fuelTypes.js — shared fuel-type source of truth (front + back)
+```
+
+## Conventions
+
+- **Composition API + `<script setup>` only.** No Options API.
+- **All server state goes through composables** that call the configured `api`
+  axios instance (`axios.js`) — never `fetch()` or a bare `axios` call inside a
+  component.
+- **Auth is cookie/session (Sanctum SPA mode).** axios is configured with
+  `withCredentials` + `withXSRFToken`; don't add bearer-token handling.
+- Route guards live in `router/index.js` (`meta.requiresAuth`). Hard navigations
+  (`/login`, `/logout`) use `window.location.href`, not the router.
+- Keep business logic in the API / Services. Vue components render and orchestrate.
+
+## Search & the shareable URL
+
+`Home.vue` is the search surface. Search params (postcode **or** lat/lng,
+`fuel_type`, `radius`, `sort`) are mirrored into the **URL query** via
+`router.push` (`queryFromParams`) so searches are shareable and bookmarkable, and
+restored on load (`paramsFromQuery`). Because the URL is shareable, **any
+coordinates written to it must be coarsened** — a precise GPS pair from "Use my
+location" (`HeroSearch.vue` → browser Geolocation) would otherwise broadcast the
+sharer's exact position to everyone they send the link to.
+
+## Maps (Leaflet)
+
+`components/LeafletMap.vue` wraps Leaflet directly (Leaflet is a plain JS library,
+not a Vue plugin). Station and user markers and the Google-Maps directions links
+are built from `station.lat` / `station.lng`; the user marker comes from the
+browser Geolocation API.
+
+## Prediction
+
+The fuel prediction ships **inside** the `/api/stations` response under the
+`prediction` key and is rendered by `PredictionCard.vue` / `PredictionFull.vue`
+(`useStations` reads `response.data.prediction`). See `prediction.md` for the
+payload shape and the tier gate.
+
+---
+paths:
+  - "resources/js/**/*.vue"
+  - "resources/js/**/*.js"
+---

.claude/rules/livewire.md

@@ -1,61 +0,0 @@
-# Livewire Components
-
-## Classic two-file components only
-
-Do NOT use Volt single-file syntax for new components.
-Volt files created by the Livewire starter kit (auth screens) are left untouched.
-
-## Component locations
-
-```
-app/Livewire/
-├── Dashboard/
-│   ├── FuelRecommendation.php    # Main fill-up/wait card
-│   ├── NearbyStations.php        # Map + station list
-│   └── PriceHistory.php          # 14-day trend chart
-├── Account/
-│   ├── NotificationSettings.php  # Channel prefs + WhatsApp OTP
-│   ├── SubscriptionManager.php   # Upgrade/downgrade UI
-│   └── FuelPreferences.php       # Fuel type, postcode
-└── Public/
-    └── PriceWatchdog.php         # Public-facing local price watchdog
-```
-
-## Component conventions
-
-- Component properties that are shown in the view must be `public`
-- Use `#[Computed]` attribute for derived values — not re-computed on every render
-- Validate with `#[Validate]` attribute on properties, not in separate rules array
-- Never put Service instantiation in the component — inject via method parameter or mount()
-- Dispatch browser events with `$this->dispatch()` not `$this->emit()` (Livewire 3 syntax)
-- Use `wire:loading` on all buttons that trigger server actions
-
-## Alpine.js usage
-
-Alpine.js handles local UI state only: dropdowns, modals, tab switching, copy-to-clipboard.
-Do not replicate server state in Alpine — use Livewire for anything that needs PHP.
-Alpine components stay inline in Blade (`x-data="{}"`), not in separate JS files unless reused 3+ times.
-
-## Map (Leaflet.js)
-
-Leaflet is a plain JS drop-in, not a Livewire component.
-Station data is fetched from a dedicated Livewire endpoint and passed to Leaflet via Alpine:
-```blade
-<div
-    x-data="stationMap(@entangle('stations'))"
-    id="map"
-    style="height: 400px"
-></div>
-```
-Map initialisation lives in `resources/js/maps/station-map.js`.
-
-## Page routing
-
-Livewire full-page components are mounted in `routes/web.php` using `Route::get()->component()`.
-No separate view files for pages — the Livewire component IS the page.
-
----
-paths:
-  - "app/Livewire/**/*.php"
-  - "resources/views/livewire/**/*.blade.php"
----

.claude/rules/notifications.md

@@ -6,7 +6,7 @@
 |------------|--------|-------|------------|----------|-----------|
 | Free       | £0     | ✓ weekly digest | ✗ | ✗ | ✗ |
 | Basic      | £0.99  | ✓ daily | ✓ daily | ✓ daily | ✗ |
-| Plus       | £2.49  | ✓     | ✓         | ✓        | ✓ max 1/day triggered |
+| Plus       | £2.49  | ✓     | ✓         | ✓        | ✓ max 3/day triggered |
 | Pro        | £3.99  | ✓     | ✓         | ✓        | ✓ max 3/day triggered |
 
 ## NotificationDispatchService
@@ -41,8 +41,8 @@ Subject line / message copy adapts based on `recommendation` and `confidence`.
 
 - Same Vonage client, SMS channel
 - Triggered only (not daily) — fires when signal strength ≥ 2 AND price event warrants it
-- Plus: max 8 SMS/month (enforced via alerts table count)
+- Plus (Smart): max 3 SMS/day (enforced via notification_log count)
-- Pro: max 30 SMS/month
+- Pro: deferred from launch — see `tiers.md`
 - Cost: ~3.5p per message UK
 
 ## Email

.claude/rules/tiers.md

@@ -50,7 +50,7 @@ All six are available to all tiers. The restriction is quantity only:
 | email     | weekly digest | daily        | ✓ triggered  | ✓ triggered  |
 | push      | ✗             | ✓ daily      | ✓ triggered  | ✓ triggered  |
 | whatsapp  | ✗             | ✓ daily      | ✓ triggered  | ✓ triggered  |
-| sms       | ✗             | ✗            | ✓ max 1/day  | ✓ max 3/day  |
+| sms       | ✗             | ✗            | ✓ max 3/day  | ✓ max 3/day  |
 
 WhatsApp also supports scheduled updates (morning + evening) independent of
 price triggers — available to any tier that has WhatsApp enabled.

.claude/settings.json

@@ -18,7 +18,13 @@
             "Bash(rg * .env)",
             "Bash(rg * ./.env)",
             "Bash(awk * .env)",
-            "Bash(awk * ./.env)"
+            "Bash(awk * ./.env)",
+            "Bash(php artisan migrate:fresh)",
+            "Bash(php artisan migrate:fresh *)",
+            "Bash(php artisan migrate:reset)",
+            "Bash(php artisan migrate:reset *)",
+            "Bash(php artisan db:wipe)",
+            "Bash(php artisan db:wipe *)"
         ]
     }
 }

.continue/skills/antfu

@@ -1 +0,0 @@
-../../.agents/skills/antfu

.continue/skills/nuxt

@@ -1 +0,0 @@
-../../.agents/skills/nuxt

.continue/skills/pinia

@@ -1 +0,0 @@
-../../.agents/skills/pinia

.continue/skills/pnpm

@@ -1 +0,0 @@
-../../.agents/skills/pnpm

.continue/skills/slidev

@@ -1 +0,0 @@
-../../.agents/skills/slidev

.continue/skills/tsdown

@@ -1 +0,0 @@
-../../.agents/skills/tsdown

.continue/skills/turborepo

@@ -1 +0,0 @@
-../../.agents/skills/turborepo

.continue/skills/unocss

@@ -1 +0,0 @@
-../../.agents/skills/unocss

.continue/skills/vite

@@ -1 +0,0 @@
-../../.agents/skills/vite

.continue/skills/vitepress

@@ -1 +0,0 @@
-../../.agents/skills/vitepress

.continue/skills/vitest

@@ -1 +0,0 @@
-../../.agents/skills/vitest

.continue/skills/vue

@@ -1 +0,0 @@
-../../.agents/skills/vue

.continue/skills/vue-best-practices

@@ -1 +0,0 @@
-../../.agents/skills/vue-best-practices

.continue/skills/vue-router-best-practices

@@ -1 +0,0 @@
-../../.agents/skills/vue-router-best-practices

.continue/skills/vue-testing-best-practices

@@ -1 +0,0 @@
-../../.agents/skills/vue-testing-best-practices

.continue/skills/vueuse-functions

@@ -1 +0,0 @@
-../../.agents/skills/vueuse-functions

.continue/skills/web-design-guidelines

@@ -1 +0,0 @@
-../../.agents/skills/web-design-guidelines

.env.example

@@ -1,8 +1,8 @@
-APP_NAME="Fuel Finder"
+APP_NAME="Fuel Alert"
 APP_ENV=local
 APP_KEY=
 APP_DEBUG=true
-APP_URL=http://fuel-price.test
+APP_URL=http://fuel-alert.test
 
 APP_LOCALE=en
 APP_FALLBACK_LOCALE=en
@@ -31,7 +31,7 @@ SESSION_DRIVER=database
 SESSION_LIFETIME=120
 SESSION_ENCRYPT=false
 SESSION_PATH=/
-SESSION_DOMAIN=.fuel-price.test
+SESSION_DOMAIN=.fuel-alert.test
 
 BROADCAST_CONNECTION=log
 FILESYSTEM_DISK=local
@@ -97,4 +97,4 @@ STRIPE_PRICE_PLUS_ANNUAL=price_1TM3pXJuhjW3IKHlfQenHsf1
 STRIPE_PRICE_PRO_MONTHLY=
 STRIPE_PRICE_PRO_ANNUAL=
 
-SANCTUM_STATEFUL_DOMAINS=fuel-price.test
+SANCTUM_STATEFUL_DOMAINS=fuel-alert.test

.github/workflows/lint.yml

@@ -1,50 +0,0 @@
-name: linter
-
-on:
-  push:
-    branches:
-      - develop
-      - main
-      - master
-      - workos
-  pull_request:
-    branches:
-      - develop
-      - main
-      - master
-      - workos
-
-permissions:
-  contents: write
-
-jobs:
-  quality:
-    runs-on: ubuntu-latest
-    environment: Testing
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: '8.4'
-
-      - name: Add Flux Credentials Loaded From ENV
-        run: composer config http-basic.composer.fluxui.dev "${{ secrets.FLUX_USERNAME }}" "${{ secrets.FLUX_LICENSE_KEY }}"
-
-      - name: Install Dependencies
-        run: |
-          composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
-          npm install
-
-      - name: Run Pint
-        run: composer lint
-
-      # - name: Commit Changes
-      #   uses: stefanzweifel/git-auto-commit-action@v7
-      #   with:
-      #     commit_message: fix code style
-      #     commit_options: '--no-verify'
-      #     file_pattern: |
-      #       **/*
-      #       !.github/workflows/*

.github/workflows/tests.yml

@@ -1,60 +0,0 @@
-name: tests
-
-on:
-  push:
-    branches:
-      - develop
-      - main
-      - master
-      - workos
-  pull_request:
-    branches:
-      - develop
-      - main
-      - master
-      - workos
-
-jobs:
-  ci:
-    runs-on: ubuntu-latest
-    environment: Testing
-    strategy:
-      matrix:
-        php-version: ['8.3', '8.4', '8.5']
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v6
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: ${{ matrix.php-version }}
-          tools: composer:v2
-          coverage: xdebug
-
-      - name: Setup Node
-        uses: actions/setup-node@v6
-        with:
-          node-version: '22'
-
-      - name: Install Node Dependencies
-        run: npm i
-
-      - name: Add Flux Credentials Loaded From ENV
-        run: composer config http-basic.composer.fluxui.dev "${{ secrets.FLUX_USERNAME }}" "${{ secrets.FLUX_LICENSE_KEY }}"
-
-      - name: Install Dependencies
-        run: composer install --no-interaction --prefer-dist --optimize-autoloader
-
-      - name: Copy Environment File
-        run: cp .env.example .env
-
-      - name: Generate Application Key
-        run: php artisan key:generate
-
-      - name: Build Assets
-        run: npm run build
-
-      - name: Run Tests
-        run: ./vendor/bin/pest

.gitignore

@@ -1,3 +1,4 @@
+.DS_Store
 /.phpunit.cache
 /node_modules
 /public/build

.kiro/skills/antfu

@@ -1 +0,0 @@
-../../.agents/skills/antfu

.kiro/skills/nuxt

@@ -1 +0,0 @@
-../../.agents/skills/nuxt

.kiro/skills/pinia

@@ -1 +0,0 @@
-../../.agents/skills/pinia

.kiro/skills/pnpm

@@ -1 +0,0 @@
-../../.agents/skills/pnpm

.kiro/skills/slidev

@@ -1 +0,0 @@
-../../.agents/skills/slidev

.kiro/skills/tsdown

@@ -1 +0,0 @@
-../../.agents/skills/tsdown

.kiro/skills/turborepo

@@ -1 +0,0 @@
-../../.agents/skills/turborepo

.kiro/skills/unocss

@@ -1 +0,0 @@
-../../.agents/skills/unocss

.kiro/skills/vite

@@ -1 +0,0 @@
-../../.agents/skills/vite

.kiro/skills/vitepress

@@ -1 +0,0 @@
-../../.agents/skills/vitepress

.kiro/skills/vitest

@@ -1 +0,0 @@
-../../.agents/skills/vitest

.kiro/skills/vue

@@ -1 +0,0 @@
-../../.agents/skills/vue

.kiro/skills/vue-best-practices

@@ -1 +0,0 @@
-../../.agents/skills/vue-best-practices

.kiro/skills/vue-router-best-practices

@@ -1 +0,0 @@
-../../.agents/skills/vue-router-best-practices

.kiro/skills/vue-testing-best-practices

@@ -1 +0,0 @@
-../../.agents/skills/vue-testing-best-practices

.kiro/skills/vueuse-functions

@@ -1 +0,0 @@
-../../.agents/skills/vueuse-functions

.kiro/skills/web-design-guidelines

@@ -1 +0,0 @@
-../../.agents/skills/web-design-guidelines

.superdesign/README.md

@@ -1,138 +0,0 @@
-# SuperDesign Context Files for Fuel Price Application
-
-This directory contains comprehensive design system documentation for the Fuel Price (Laravel Starter Kit) application.
-
-## Generated Files
-
-### 1. `init/components.md` (274 lines)
-**Shared UI Primitives & Components**
-
-Lists all reusable Blade components (7 total) with full source code:
-- x-action-message: Temporary status messages
-- x-app-logo: Branding component
-- x-app-logo-icon: SVG logo icon
-- x-auth-header: Centered auth page header
-- x-auth-session-status: Session status display
-- x-desktop-user-menu: User profile dropdown
-- x-placeholder-pattern: Loading state pattern
-
-Also documents Flux v2 components used throughout the application.
-
-### 2. `init/layouts.md` (347 lines)
-**Complete Layout Hierarchy**
-
-Full content of 7 layout files:
-- layouts/app.blade.php: Main app wrapper
-- layouts/app/sidebar.blade.php: Authenticated layout with header/sidebar
-- layouts/auth.blade.php: Auth wrapper
-- layouts/auth/simple.blade.php: Centered auth layout
-- layouts/auth/card.blade.php: Card-based auth layout
-- layouts/auth/split.blade.php: Split-screen auth layout
-- partials/head.blade.php: Shared head section
-
-Includes usage patterns and color scheme documentation.
-
-### 3. `init/routes.md` (120 lines)
-**Route Configuration & Summary**
-
-Complete files:
-- routes/web.php: Public and authenticated routes
-- routes/settings.php: Settings page routes
-
-Plus detailed route summary table covering:
-- 19 total routes (web + Fortify)
-- Route grouping by protection level
-- Livewire component routes mapping
-
-### 4. `init/theme.md` (298 lines)
-**Design Tokens & Configuration**
-
-Complete content:
-- resources/css/app.css: Tailwind imports and custom theme
-- Color palette: Zinc neutral scale + semantic colors
-- Typography: Instrument Sans font configuration
-- Spacing system: 4px base unit scale
-- Dark mode implementation
-- Vite build configuration
-- Flux theme setup
-
-### 5. `init/pages.md` (291 lines)
-**Page Dependency Trees**
-
-Full-page component documentation with dependency trees:
-1. StationSearch Livewire component (public)
-2. Dashboard
-3. Welcome/Home page
-4. Settings pages (Profile, Security, Appearance)
-5. Authentication pages (Login, Register, Password Reset, Email Verification, 2FA)
-
-Includes data flow documentation and page transition patterns.
-
-### 6. `init/extractable-components.md` (386 lines)
-**Reusable Component Analysis**
-
-16 components identified by category:
-- 3 Form components (Search, Select, Loading Button)
-- 6 Data Display components (Card, Stats, Legend)
-- 2 Navigation components (Sidebar Nav, User Menu)
-- 3 Layout components (Auth layouts)
-- 2 Feedback components (Messages)
-- 1 Map/Visualization component
-- 2 Typography components
-
-Includes reusability scoring table and extraction recommendations.
-
-### 7. `init/design-system.md` (494 lines)
-**Complete Design System**
-
-Comprehensive design documentation:
-- Brand identity & philosophy
-- Color system: Zinc palette + semantic colors
-- Typography: Typeface, hierarchy, weights
-- Spacing & layout: Grid system, breakpoints
-- Borders & radius: Border weight, color, radius scales
-- Component patterns: Forms, Buttons, Cards, Navigation
-- Data visualization: Map colors, marker styles
-- Animations & transitions: Page transitions, component effects
-- Accessibility: Contrast, interactive elements, typography
-- Dark mode: Colors, images, implementation
-- Responsive behavior: Breakpoints, layout adjustments
-
-## Project Stack
-
-- **Framework:** Laravel 11
-- **UI Library:** Livewire 3 (classic components)
-- **Styling:** Tailwind CSS v4
-- **UI Components:** Flux UI v2
-- **JavaScript:** Alpine.js
-- **Font:** Instrument Sans (400, 500, 600 weights)
-- **Map Library:** Leaflet
-- **Map Tiles:** OpenStreetMap
-
-## Key Features
-
-- Dark-mode-first design with light mode support
-- Responsive mobile-first architecture
-- Comprehensive authentication UI (Fortify-based)
-- Interactive fuel station search with Leaflet maps
-- Settings/profile management
-- Accessibility-focused component design
-
-## Color Palette
-
-### Primary
-- Zinc neutral scale (50-950)
-
-### Semantic
-- Success: Green-500 (#22c55e)
-- Warning: Amber-500 (#f59e0b)
-- Error: Red-500 (#ef4444)
-- Info: Slate-500 (#64748b)
-
-## File Organization
-
-All context files are in `init/` subdirectory for SuperDesign import.
-
-Total: ~2,210 lines of comprehensive design documentation
-
-Generated: April 6, 2026

.superdesign/init/components.md

@@ -1,274 +0,0 @@
-# Shared UI Components
-
-## Blade Components (Reusable)
-
-### 1. `x-action-message`
-**Path:** `resources/views/components/action-message.blade.php`
-
-Displays a temporary status message that auto-hides after 2 seconds using Alpine.js.
-
-**Props:**
-- `on`: Event name to listen for (Livewire event)
-
-**Features:**
-- Transition animation with fade-out
-- Auto-hide timeout (2000ms)
-- Default text: "Saved."
-
-```blade
-@props([
-    'on',
-])
-
-<div
-    x-data="{ shown: false, timeout: null }"
-    x-init="@this.on('{{ $on }}', () => { clearTimeout(timeout); shown = true; timeout = setTimeout(() => { shown = false }, 2000); })"
-    x-show.transition.out.opacity.duration.1500ms="shown"
-    x-transition:leave.opacity.duration.1500ms
-    style="display: none"
-    {{ $attributes->merge(['class' => 'text-sm']) }}
->
-    {{ $slot->isEmpty() ? __('Saved.') : $slot }}
-</div>
-```
-
----
-
-### 2. `x-app-logo`
-**Path:** `resources/views/components/app-logo.blade.php`
-
-Main app branding component. Renders as `flux:brand` (header) or `flux:sidebar.brand` (sidebar variant).
-
-**Props:**
-- `sidebar` (bool): If true, renders sidebar variant
-- Inherits Flux component attributes
-
-**Features:**
-- Dynamic logo rendering based on context (header vs sidebar)
-- Uses `x-app-logo-icon` for icon
-- Passes through attributes to Flux components
-
-```blade
-@props([
-    'sidebar' => false,
-])
-
-@if($sidebar)
-    <flux:sidebar.brand name="Laravel Starter Kit" {{ $attributes }}>
-        <x-slot name="logo" class="flex aspect-square size-8 items-center justify-center rounded-md bg-accent-content text-accent-foreground">
-            <x-app-logo-icon class="size-5 fill-current text-white dark:text-black" />
-        </x-slot>
-    </flux:sidebar.brand>
-@else
-    <flux:brand name="Laravel Starter Kit" {{ $attributes }}>
-        <x-slot name="logo" class="flex aspect-square size-8 items-center justify-center rounded-md bg-accent-content text-accent-foreground">
-            <x-app-logo-icon class="size-5 fill-current text-white dark:text-black" />
-        </x-slot>
-    </flux:brand>
-@endif
-```
-
----
-
-### 3. `x-app-logo-icon`
-**Path:** `resources/views/components/app-logo-icon.blade.php`
-
-SVG icon for the application logo. Geometric design with fills.
-
-**Features:**
-- Scalable SVG
-- Uses `currentColor` for dynamic styling
-- Can be sized with Tailwind classes
-
-```blade
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 42" {{ $attributes }}>
-    <path 
-        fill="currentColor" 
-        fill-rule="evenodd" 
-        clip-rule="evenodd"
-        d="M17.2 5.633 8.6.855 0 5.633v26.51l16.2 9 16.2-9v-8.442l7.6-4.223V9.856l-8.6-4.777-8.6 4.777V18.3l-5.6 3.111V5.633ZM38 18.301l-5.6 3.11v-6.157l5.6-3.11V18.3Zm-1.06-7.856-5.54 3.078-5.54-3.079 5.54-3.078 5.54 3.079ZM24.8 18.3v-6.157l5.6 3.111v6.158L24.8 18.3Zm-1 1.732 5.54 3.078-13.14 7.302-5.54-3.078 13.14-7.3v-.002Zm-16.2 7.89 7.6 4.222V38.3L2 30.966V7.92l5.6 3.111v16.892ZM8.6 9.3 3.06 6.222 8.6 3.143l5.54 3.08L8.6 9.3Zm21.8 15.51-13.2 7.334V38.3l13.2-7.334v-6.156ZM9.6 11.034l5.6-3.11v14.6l-5.6 3.11v-14.6Z"
-    />
-</svg>
-```
-
----
-
-### 4. `x-auth-header`
-**Path:** `resources/views/components/auth-header.blade.php`
-
-Centered header for authentication pages with title and description.
-
-**Props:**
-- `title`: Main heading text
-- `description`: Subheading/description text
-
-**Features:**
-- Centered layout
-- Uses Flux typography components
-
-```blade
-@props([
-    'title',
-    'description',
-])
-
-<div class="flex w-full flex-col text-center">
-    <flux:heading size="xl">{{ $title }}</flux:heading>
-    <flux:subheading>{{ $description }}</flux:subheading>
-</div>
-```
-
----
-
-### 5. `x-auth-session-status`
-**Path:** `resources/views/components/auth-session-status.blade.php`
-
-Displays session status messages (typically success messages after redirect).
-
-**Props:**
-- `status`: Status message text (if present)
-- Passes through attributes
-
-**Features:**
-- Conditional rendering (only shows if status exists)
-- Green success styling
-
-```blade
-@props([
-    'status',
-])
-
-@if ($status)
-    <div {{ $attributes->merge(['class' => 'font-medium text-sm text-green-600']) }}>
-        {{ $status }}
-    </div>
-@endif
-```
-
----
-
-### 6. `x-desktop-user-menu`
-**Path:** `resources/views/components/desktop-user-menu.blade.php`
-
-User profile dropdown menu with settings and logout options. Uses Flux components.
-
-**Features:**
-- Sidebar profile with dropdown
-- Shows user avatar, name, and email
-- Menu items: Settings (cog icon), Logout (arrow icon)
-- Logout form with CSRF protection
-- Data test attributes for testing
-
-```blade
-<flux:dropdown position="bottom" align="start">
-    <flux:sidebar.profile
-        :name="auth()->user()->name"
-        :initials="auth()->user()->initials()"
-        icon:trailing="chevrons-up-down"
-        data-test="sidebar-menu-button"
-    />
-
-    <flux:menu>
-        <div class="flex items-center gap-2 px-1 py-1.5 text-start text-sm">
-            <flux:avatar
-                :name="auth()->user()->name"
-                :initials="auth()->user()->initials()"
-            />
-            <div class="grid flex-1 text-start text-sm leading-tight">
-                <flux:heading class="truncate">{{ auth()->user()->name }}</flux:heading>
-                <flux:text class="truncate">{{ auth()->user()->email }}</flux:text>
-            </div>
-        </div>
-        <flux:menu.separator />
-        <flux:menu.radio.group>
-            <flux:menu.item :href="route('profile.edit')" icon="cog" wire:navigate>
-                {{ __('Settings') }}
-            </flux:menu.item>
-            <form method="POST" action="{{ route('logout') }}" class="w-full">
-                @csrf
-                <flux:menu.item
-                    as="button"
-                    type="submit"
-                    icon="arrow-right-start-on-rectangle"
-                    class="w-full cursor-pointer"
-                    data-test="logout-button"
-                >
-                    {{ __('Log out') }}
-                </flux:menu.item>
-            </form>
-        </flux:menu.radio.group>
-    </flux:menu>
-</flux:dropdown>
-```
-
----
-
-### 7. `x-placeholder-pattern`
-**Path:** `resources/views/components/placeholder-pattern.blade.php`
-
-SVG placeholder pattern for skeleton/loading states. Diagonal line pattern.
-
-**Props:**
-- `id`: Unique pattern ID (auto-generated)
-
-**Features:**
-- Reusable SVG pattern definition
-- Can be styled with Tailwind stroke classes
-- Used in dashboard placeholder cards
-
-```blade
-@props([
-    'id' => uniqid(),
-])
-
-<svg {{ $attributes }} fill="none">
-    <defs>
-        <pattern id="pattern-{{ $id }}" x="0" y="0" width="8" height="8" patternUnits="userSpaceOnUse">
-            <path d="M-1 5L5 -1M3 9L8.5 3.5" stroke-width="0.5"></path>
-        </pattern>
-    </defs>
-    <rect stroke="none" fill="url(#pattern-{{ $id }})" width="100%" height="100%"></rect>
-</svg>
-```
-
----
-
-## Flux UI Components Used
-
-Flux v2 components extensively used throughout the application:
-
-- **Layout:** `flux:header`, `flux:sidebar`, `flux:main`, `flux:spacer`
-- **Navigation:** `flux:navbar`, `flux:navbar.item`, `flux:sidebar.nav`, `flux:sidebar.item`, `flux:sidebar.group`
-- **Forms:** `flux:input`, `flux:select`, `flux:checkbox`, `flux:button`
-- **Typography:** `flux:heading`, `flux:subheading`, `flux:text`
-- **Dropdowns/Menus:** `flux:dropdown`, `flux:menu`, `flux:menu.item`, `flux:menu.separator`
-- **UI Elements:** `flux:badge`, `flux:avatar`, `flux:brand`, `flux:profile`
-- **Other:** `flux:tooltip`, `flux:separator`, `flux:link`
-
----
-
-## Flux Custom Icons
-
-Located in `resources/views/flux/icon/`:
-- `layout-grid.blade.php`
-- `folder-git-2.blade.php`
-- `chevrons-up-down.blade.php`
-- `book-open-text.blade.php`
-
-These extend Flux's default icon library.
-
----
-
-## Alpine.js Data Objects
-
-### `stationMap`
-**Path:** `resources/js/maps/station-map.js`
-
-Leaflet map integration for displaying fuel stations:
-- Initializes map centered on UK
-- Plots colored circle markers for stations
-- Color coding: green (current), slate (recent), amber (stale), red (outdated)
-- Popup display with station details
-- Responsive bounds fitting
-- Watches for data changes via Alpine
-

.superdesign/init/design-system.md

@@ -1,494 +0,0 @@
-# Design System
-
-Comprehensive documentation of the design system, visual language, and brand identity for the Fuel Price application.
-
----
-
-## Brand Identity
-
-### App Name
-"Fuel Price" (Laravel Starter Kit internally)
-
-### Logo
-- **Style:** Geometric, modern
-- **Colors:** Adapts to light/dark mode
-- **Variants:** Header logo (wider), Sidebar logo (square icon)
-- **Usage:** All pages in navigation
-
-### Design Philosophy
-- Clean, minimal aesthetic
-- Dark-first design (dark mode as primary)
-- Accessibility-focused
-- Data visualization emphasis (maps, charts)
-- Utility-oriented interface
-
----
-
-## Color System
-
-### Primary Palette - Zinc (Neutral)
-
-Used as base colors for UI, text, and borders.
-
-```
-Zinc-50:   #fafafa  (Lightest backgrounds)
-Zinc-100:  #f5f5f5  (Light backgrounds)
-Zinc-200:  #e5e5e5  (Light borders, dividers)
-Zinc-300:  #d4d4d4  (Subtle borders)
-Zinc-400:  #a3a3a3  (Placeholder text)
-Zinc-500:  #737373  (Secondary text)
-Zinc-600:  #525252  (Body text)
-Zinc-700:  #404040  (Dark text)
-Zinc-800:  #262626  (Page backgrounds dark)
-Zinc-900:  #171717  (Header/sidebar backgrounds)
-Zinc-950:  #0a0a0a  (Darkest)
-```
-
-### Semantic Colors
-
-#### Success
-- **Primary:** `#22c55e` (Green-500)
-- **Dark:** `#16a34a` (Green-600)
-- **Light:** `#86efac` (Green-300)
-- **Usage:** Success messages, positive indicators, current/fresh data
-
-#### Warning
-- **Primary:** `#f59e0b` (Amber-500)
-- **Light:** `#fbbf24` (Amber-400)
-- **Usage:** Stale data, deprecation notices
-
-#### Error/Danger
-- **Primary:** `#ef4444` (Red-500)
-- **Dark:** `#dc2626` (Red-600)
-- **Light:** `#fca5a5` (Red-300)
-- **Usage:** Outdated data, error messages, destructive actions
-
-#### Info
-- **Primary:** `#64748b` (Slate-500)
-- **Usage:** Neutral information, recent data
-
-### Accent Colors
-
-**Light Mode:**
-- Accent: `--color-neutral-800` (dark gray)
-- Accent Content: `--color-neutral-800`
-- Accent Foreground: `--color-white`
-
-**Dark Mode:**
-- Accent: `--color-white`
-- Accent Content: `--color-white`
-- Accent Foreground: `--color-neutral-800`
-
-Used for:
-- Primary buttons
-- Active navigation items
-- Focus states
-- Primary CTAs
-
----
-
-## Typography System
-
-### Typeface
-
-**Primary Font:** Instrument Sans
-- **Source:** Google Fonts (fonts.bunny.net)
-- **Weights Available:** 400 (Regular), 500 (Medium), 600 (Semibold)
-- **Category:** Sans-serif, Humanist
-- **Use Case:** All body text, headings, UI labels
-
-**Fallback Stack:**
-```
-'Instrument Sans', 
-ui-sans-serif, 
-system-ui, 
-sans-serif,
-'Apple Color Emoji',
-'Segoe UI Emoji',
-'Segoe UI Symbol',
-'Noto Color Emoji'
-```
-
-### Font Sizes & Hierarchy
-
-Via Flux components (sizes managed by Flux):
-
-- **flux:heading size="xl":** Page titles (largest)
-- **flux:heading size="lg":** Section titles
-- **flux:heading:** Standard headings
-- **flux:subheading:** Secondary headings, descriptions
-- **flux:text:** Body text
-- **flux:label:** Form labels, captions
-- **flux:badge:** Small labels, tags
-
-### Line Heights
-
-- **Tight:** Labels, badges (`leading-tight`)
-- **Normal:** Body text, headings (default)
-- **Relaxed:** Long-form content (when needed)
-
-### Weight Distribution
-
-- **400 (Regular):** Body text, regular content
-- **500 (Medium):** Secondary headings, strong emphasis, labels
-- **600 (Semibold):** Primary headings, buttons, strong emphasis
-
----
-
-## Spacing & Layout
-
-### Spacing Scale
-
-Based on 4px base unit:
-
-```
-0:    0px
-0.5:  2px
-1:    4px
-1.5:  6px
-2:    8px
-2.5:  10px
-3:    12px
-3.5:  14px
-4:    16px
-5:    20px
-6:    24px
-7:    28px
-8:    32px
-9:    36px
-10:   40px
-11:   44px
-12:   48px
-...
-```
-
-### Common Spacing Patterns
-
-- **Gap between elements:** `gap-3` (12px), `gap-4` (16px), `gap-6` (24px)
-- **Form field spacing:** `gap-2` (8px) for label + input
-- **Card padding:** `p-4` (16px) for compact, `p-6` (24px) for default, `p-10` (40px) for large
-- **Horizontal padding:** `px-4` (16px) standard
-- **Vertical padding:** `py-3` (12px) standard
-
-### Grid System
-
-- Flex-based layouts (no CSS Grid for most components)
-- Default gap: `gap-4` (16px)
-- Settings page: 2-column on desktop (220px sidebar + flex content)
-- Station results: 1-column list, single-level nesting
-
-### Responsive Breakpoints
-
-```
-Default (mobile):     0px
-sm:                   640px   (@media max-width: 639px = mobile)
-md:                   768px   (tablet)
-lg:                   1024px  (desktop)
-xl:                   1280px  (large desktop)
-2xl:                  1536px  (extra large)
-```
-
-**Breakpoint Patterns:**
-- `max-lg:` - Mobile and tablet
-- `lg:` - Desktop and larger
-- `max-md:` - Mobile only
-- `md:` - Tablet and larger
-
----
-
-## Border & Radius
-
-### Border Weight
-
-- **Default:** 1px (all borders)
-- **Emphasis:** None (single weight used)
-
-### Border Radius
-
-- **Small:** `rounded-md` (6-8px) - Icons, small buttons, badges
-- **Medium:** `rounded-lg` (8-10px) - Inputs, dropdowns
-- **Large:** `rounded-xl` (12-16px) - Cards, modals, large components
-- **None:** `rounded-none` - Rarely used
-
-### Border Colors
-
-**Light Mode:**
-- Default border: `border-zinc-200`
-- Focus ring: `ring-accent` (accent color)
-
-**Dark Mode:**
-- Default border: `border-zinc-700`
-- Card/modal: `border-stone-800` or `border-neutral-800`
-- Focus ring: `ring-accent` with `ring-offset-2` and `ring-offset-accent-foreground`
-
-### Focus States
-
-All interactive elements have:
-- `ring-2 ring-accent` (focus ring)
-- `ring-offset-2` (space between element and ring)
-- `ring-offset-accent-foreground` (offset background color)
-
----
-
-## Component Patterns
-
-### Form Patterns
-
-All form elements follow consistent structure:
-1. Label (top)
-2. Input/Select/Textarea
-3. Error message (bottom, conditional)
-4. Helper text (optional)
-
-**Spacing:** `gap-2` between label and input
-
-**States:**
-- Normal: default appearance
-- Focus: ring around element
-- Disabled: opacity/pointer-events disabled
-- Error: red text below
-
-### Button Patterns
-
-**Variants:**
-- `variant="primary"` - Primary action (accent color background)
-- `variant="secondary"` - Secondary action
-- `variant="danger"` - Destructive action (red)
-
-**States:**
-- Normal: clickable
-- Hover: slight opacity increase
-- Disabled: `disabled` attribute via `wire:loading.attr="disabled"`
-- Loading: show spinner or text change
-
-### Card Patterns
-
-Standard card styling:
-- Border: `border border-zinc-200 dark:border-zinc-700`
-- Radius: `rounded-xl`
-- Background: white (light) / dark (dark mode)
-- Padding: `p-4` to `p-10` depending on content density
-- Shadow: `shadow-xs` for subtle lift (optional)
-
-### Navigation Patterns
-
-**Sidebar Navigation:**
-- `flux:sidebar.nav` wrapper
-- `flux:sidebar.group` for sections (with heading)
-- `flux:sidebar.item` for links
-- Active state: current attribute
-- Icon on left, text on right
-
-**Navbar Navigation:**
-- `flux:navbar` wrapper
-- `flux:navbar.item` for links
-- Icons only or icon + text
-- Horizontal layout
-- Tooltip support
-
----
-
-## Data Visualization
-
-### Station Search Map Colors (Leaflet)
-
-Classification-based color coding for fuel price data freshness:
-
-- **Current (< 24h):** `#22c55e` (Green-500)
-- **Recent (24-48h):** `#64748b` (Slate-500)
-- **Stale (2-5 days):** `#f59e0b` (Amber-500)
-- **Outdated (5+ days):** `#ef4444` (Red-500)
-
-### Map Markers
-
-- **Shape:** Circle
-- **Radius:** 9px
-- **Stroke:** White, 2px weight
-- **Fill:** Classification color
-- **Opacity:** 85% (0.85)
-- **Click:** Shows popup with station details
-
-### Data Table Patterns
-
-(No explicit tables in current design, but pattern would be):
-- Striped rows (alternate bg)
-- Hover states for interactivity
-- Clear column alignment
-- Sortable headers
-
----
-
-## Animations & Transitions
-
-### Page Transitions
-
-All navigation via `wire:navigate` (no full page reload):
-- Seamless SPA-like experience
-- Preserves scroll position
-- No loading screen between pages
-
-### Component Transitions
-
-**Alpine.js Transitions:**
-- Fade on message dismiss: `x-show.transition.out.opacity.duration.1500ms`
-- Duration: 1500ms (1.5 seconds)
-- Effect: Opacity fade
-
-**Flux Built-in:**
-- Dropdown/menu opens: instant or quick fade
-- Sidebar collapse: smooth width transition
-- Modal appears: fade + scale (typical Flux defaults)
-
-### Hover & Active States
-
-- Links: `hover:underline` (default Flux)
-- Buttons: Opacity change on hover
-- Navigation items: Background highlight on hover/active
-- Interactive elements: Subtle color shift
-
----
-
-## Accessibility
-
-### Color Contrast
-
-- Text on backgrounds meets WCAG AA standards (4.5:1 for normal text)
-- Semantic colors (green/red) supplemented with icons/patterns
-- No color-only indicators
-
-### Interactive Elements
-
-- Keyboard navigable (all Flux components)
-- Focus indicators visible (`ring-2 ring-accent`)
-- Touch-friendly sizing (minimum 44x44px recommended)
-- ARIA labels where needed
-
-### Typography
-
-- Font sizes readable at standard distances
-- Line height adequate for readability
-- High contrast between text and background
-
----
-
-## Dark Mode
-
-### Implementation
-
-- **Method:** `class="dark"` on HTML root
-- **Toggle:** Managed by `@fluxAppearance` directive
-- **Detection:** Optional prefers-color-scheme integration
-
-### Dark Mode Colors
-
-**Text:**
-- Primary: `text-zinc-100` (light gray)
-- Secondary: `text-zinc-400` (medium gray)
-- Disabled: `text-zinc-500` (darker gray)
-
-**Backgrounds:**
-- Page: `bg-zinc-800`
-- Header/Sidebar: `bg-zinc-900`
-- Cards: `bg-stone-950` (darker variant)
-- Inputs: `bg-zinc-900`
-
-**Borders:**
-- Primary: `border-zinc-700`
-- Secondary: `border-stone-800`
-- Subtle: `border-neutral-800`
-
-**Accents:**
-- Primary accent inverts: white (instead of dark gray)
-
-### Image/SVG Handling in Dark
-
-- Logo icon color inverts via `fill-current` and `text-*` classes
-- Patterns use opacity: `stroke-neutral-100/20` (dark) vs `stroke-gray-900/20` (light)
-- Leaflet map: Default OSM colors (already dark-friendly)
-
----
-
-## Responsive Behavior
-
-### Mobile-First Approach
-
-Design starts at mobile (smallest), enhances at larger breakpoints.
-
-### Key Breakpoints
-
-**Mobile (0-639px):**
-- Single column layouts
-- Hamburger menu (sidebar collapses)
-- Stacked form fields
-- Full-width cards
-
-**Tablet (640-1023px):**
-- Narrower multi-column (if applicable)
-- Touch-friendly spacing
-- Condensed headers
-
-**Desktop (1024px+):**
-- Multi-column layouts
-- Horizontal navigation
-- Sidebar persistent
-- Full feature set visible
-
-### Layout Adjustments
-
-- Header: Hidden navbar items on mobile (`max-lg:hidden`)
-- Sidebar: Becomes mobile hamburger at lg breakpoint
-- Forms: Stack vertically on mobile, horizontal on desktop
-- Grids: 1 column mobile, 2-3 columns desktop
-
----
-
-## Consistency Patterns
-
-### Consistent Component Usage
-
-- All buttons: `flux:button` (never raw `<button>`)
-- All inputs: `flux:input` (with validation/errors)
-- All selects: `flux:select`
-- All headings: `flux:heading` (sizes: xl, lg, etc.)
-
-### Consistent Spacing
-
-- Inter-element gaps: multiples of 4px
-- Card padding: consistent with gap sizes
-- Consistent use of flexbox for alignment
-
-### Consistent States
-
-- Forms show errors below input in red
-- Success messages fade out after 2 seconds
-- Disabled states use opacity + pointer-events
-- Loading states shown via spinner or text change
-
----
-
-## Implementation Notes
-
-### CSS Custom Properties
-
-```css
---font-sans: 'Instrument Sans', ...
---color-accent: (theme-dependent)
---color-accent-content: (theme-dependent)
---color-accent-foreground: (theme-dependent)
---color-zinc-{50-950}: (full palette)
-```
-
-### Tailwind Integration
-
-- Uses Tailwind CSS v4 with `@tailwindcss/vite`
-- `@theme` block defines custom colors and fonts
-- `@custom-variant` for dark mode
-- `@layer` for CSS overrides
-
-### Flux Integration
-
-- Heavy reliance on Flux v2 components
-- Flux provides theming, dark mode, layout components
-- Custom CSS only overrides specific Flux defaults
-- No Flux config file needed (uses defaults + CSS)
-

.superdesign/init/extractable-components.md

@@ -1,386 +0,0 @@
-# Extractable UI Components
-
-This document identifies reusable UI components that could be extracted, packaged, and reused across other projects.
-
----
-
-## Form Components
-
-### 1. Search Input with Debounce
-**Source:** `resources/views/livewire/public/station-search.blade.php` (lines 8-16)  
-**Category:** Forms  
-**Complexity:** Low
-
-**Props:**
-- `name`: Input field name
-- `wire:model`: Livewire property binding
-- `label`: Display label
-- `placeholder`: Placeholder text
-
-**Features:**
-- Flux form styling
-- Wire model binding support
-- Error message display
-
-**Extractable:** Yes - Generic search input wrapper
-
----
-
-### 2. Multi-Option Select Dropdown
-**Source:** `resources/views/livewire/public/station-search.blade.php` (lines 20-28, 34-42, 44-52)  
-**Category:** Forms  
-**Complexity:** Low
-
-**Props:**
-- `wire:model.live` or `wire:model`: Binding
-- `name`: Field name
-- `label`: Label text
-- Options as slot
-
-**Features:**
-- Reactive updates via `wire:model.live`
-- Error display
-- Multiple select options
-
-**Variants:**
-- Fuel type selector (6 options)
-- Radius selector (5 options)
-- Sort selector (5 options)
-
-**Extractable:** Yes - Reusable select component wrapper
-
----
-
-### 3. Form Submission Button with Loading State
-**Source:** `resources/views/livewire/public/station-search.blade.php` (lines 54-59)  
-**Category:** Forms  
-**Complexity:** Low
-
-**Props:**
-- `type`: button type
-- `variant`: "primary", etc.
-- `wire:loading.attr`: Disabled state during loading
-- `wire:target`: Target action
-
-**Features:**
-- Dynamic text based on loading state
-- Wire loading indicators
-- Primary variant styling
-
-**Extractable:** Yes - Generic loading button component
-
----
-
-## Data Display Components
-
-### 4. Station Result Card
-**Source:** `resources/views/livewire/public/station-search.blade.php` (lines 94-128)  
-**Category:** Data Display  
-**Complexity:** Medium
-
-**Props:**
-- `station`: Object with station data
-  - `name`: Station name
-  - `address`: Street address
-  - `postcode`: Postcode
-  - `distance_km`: Distance in kilometers
-  - `price`: Fuel price in pence
-  - `price_classification`: One of (current, recent, stale, outdated)
-  - `price_classification_label`: Human label
-  - `price_updated_at`: ISO date string
-  - `is_supermarket`: Boolean
-
-**Features:**
-- Responsive layout (flex items-center justify-between)
-- Color-coded price based on freshness
-- Supermarket badge display
-- Distance/address display
-- Time-ago formatting
-
-**Extractable:** Yes - Could be standalone component for displaying station data
-
----
-
-### 5. Results Count Summary
-**Source:** `resources/views/livewire/public/station-search.blade.php` (lines 72-76)  
-**Category:** Data Display  
-**Complexity:** Low
-
-**Props:**
-- `count`: Total stations found
-- `lowest_pence`: Lowest price in pence
-- `avg_pence`: Average price in pence
-
-**Features:**
-- Formatted currency display
-- Singular/plural handling
-- Stats display on one line
-
-**Extractable:** Yes - Generic stats summary component
-
----
-
-### 6. Classification Legend/Color Code Guide
-**Source:** `resources/views/livewire/public/station-search.blade.php` (lines 84-90)  
-**Category:** Data Display  
-**Complexity:** Low
-
-**Props:**
-- Array of classification items with colors and labels
-
-**Features:**
-- Inline color swatches
-- Legend item labels
-- Responsive flex layout
-
-**Extractable:** Yes - Reusable legend component
-
----
-
-## Navigation Components
-
-### 7. Settings Sidebar Navigation
-**Source:** `resources/views/pages/settings/layout.blade.php` (lines 3-7)  
-**Category:** Navigation  
-**Complexity:** Low
-
-**Props:**
-- Navigation items array with:
-  - `label`: Display text
-  - `route`: Route name
-  - `icon`: Optional icon name
-
-**Features:**
-- flux:navlist component
-- wire:navigate support
-- Active state detection
-- Mobile/desktop responsive
-
-**Extractable:** Yes - Generic sidebar nav for multi-section pages
-
----
-
-### 8. User Profile Dropdown Menu
-**Source:** `resources/views/components/desktop-user-menu.blade.php`  
-**Category:** Navigation  
-**Complexity:** Medium
-
-**Props:**
-- User object with:
-  - `name`: User name
-  - `email`: User email
-  - `initials()`: Method to get initials
-
-**Features:**
-- Flux dropdown + menu
-- Avatar display with initials
-- Settings link
-- Logout form with CSRF
-- Test attributes for QA
-
-**Extractable:** Yes - Standalone user menu component for authenticated apps
-
----
-
-## Layout Components
-
-### 9. Centered Authentication Layout Container
-**Source:** `resources/views/layouts/auth/simple.blade.php`  
-**Category:** Layouts  
-**Complexity:** Low
-
-**Props:**
-- None (slot-based)
-
-**Features:**
-- Centered flex layout
-- Max-width constraint (sm)
-- Dark gradient background
-- Logo link at top
-- Responsive padding
-
-**Extractable:** Yes - Generic centered auth layout
-
----
-
-### 10. Card-Based Form Container
-**Source:** `resources/views/layouts/auth/card.blade.php`  
-**Category:** Layouts  
-**Complexity:** Low
-
-**Props:**
-- None (slot-based)
-
-**Features:**
-- White card on dark background
-- Rounded borders with shadow
-- Dark mode support
-- Centered with max-width
-- Padding inside card
-
-**Extractable:** Yes - Modal/card wrapper component
-
----
-
-### 11. Split-Screen Auth Layout
-**Source:** `resources/views/layouts/auth/split.blade.php`  
-**Category:** Layouts  
-**Complexity:** Medium
-
-**Props:**
-- Quote display (generated from Inspiring::quotes)
-
-**Features:**
-- Two-column grid (desktop only)
-- Dark sidebar with quote/branding
-- Form content on right
-- Mobile-friendly (single column)
-- Absolute background fill
-
-**Extractable:** Yes - Premium auth layout component
-
----
-
-## Status/Feedback Components
-
-### 12. Temporary Action Message
-**Source:** `resources/views/components/action-message.blade.php`  
-**Category:** Feedback  
-**Complexity:** Low
-
-**Props:**
-- `on`: Livewire event to listen to
-- Slot for custom message (defaults to "Saved.")
-
-**Features:**
-- Alpine.js event listener
-- Auto-hide after 2 seconds
-- Fade transition
-- Livewire integration
-
-**Extractable:** Yes - Generic toast/message component
-
----
-
-### 13. Session Status Message
-**Source:** `resources/views/components/auth-session-status.blade.php`  
-**Category:** Feedback  
-**Complexity:** Low
-
-**Props:**
-- `status`: Status message text
-
-**Features:**
-- Conditional rendering
-- Green success styling
-- Used in auth forms
-
-**Extractable:** Yes - Simple status display component
-
----
-
-## Map/Visualization Components
-
-### 14. Leaflet Map Integration
-**Source:** `resources/js/maps/station-map.js`  
-**Category:** Map/Visualization  
-**Complexity:** High
-
-**Props:**
-- `results`: Array of station data with lat/lng/classifications
-
-**Features:**
-- Leaflet map initialization
-- OpenStreetMap tiles
-- Custom circle markers with colors
-- Popup on marker click
-- Auto-fit bounds
-- Reactive to data changes
-
-**Extractable:** Yes - Could be abstracted into reusable Leaflet component
-
-**Note:** Currently tightly coupled to Alpine.js and station data structure. Would require prop mapping for reuse.
-
----
-
-## Typography/Header Components
-
-### 15. Auth Page Header
-**Source:** `resources/views/components/auth-header.blade.php`  
-**Category:** Typography  
-**Complexity:** Low
-
-**Props:**
-- `title`: Main heading
-- `description`: Subheading
-
-**Features:**
-- Centered text
-- Flux typography (heading + subheading)
-- Used on all auth pages
-
-**Extractable:** Yes - Generic header for centered pages
-
----
-
-### 16. Settings Page Header
-**Source:** `resources/views/partials/settings-heading.blade.php`  
-**Category:** Typography  
-**Complexity:** Low
-
-**Props:**
-- None (hardcoded for settings)
-
-**Features:**
-- Page title "Settings"
-- Subheading text
-- Separator line
-
-**Extractable:** Maybe - Specific to settings but pattern is reusable
-
----
-
-## Reusability Summary Table
-
-| Component | Type | Complexity | Reusable | Dependencies | Extraction Cost |
-|-----------|------|-----------|----------|---|---|
-| Search Input | Form | Low | High | Flux | Very Low |
-| Select Dropdown | Form | Low | High | Flux | Very Low |
-| Loading Button | Form | Low | High | Flux, Livewire | Very Low |
-| Station Card | Display | Medium | High | Flux | Low |
-| Stats Summary | Display | Low | High | None | Very Low |
-| Legend | Display | Low | High | Tailwind | Very Low |
-| Settings Nav | Nav | Low | High | Flux | Very Low |
-| User Menu | Nav | Medium | High | Flux, Auth | Low |
-| Simple Auth Layout | Layout | Low | High | Tailwind | Very Low |
-| Card Container | Layout | Low | High | Tailwind | Very Low |
-| Split Layout | Layout | Medium | High | Tailwind | Low |
-| Action Message | Feedback | Low | High | Alpine, Livewire | Very Low |
-| Status Message | Feedback | Low | High | None | Very Low |
-| Leaflet Map | Visualization | High | Medium | Leaflet, Alpine | Medium |
-| Auth Header | Typography | Low | High | Flux | Very Low |
-| Settings Header | Typography | Low | Medium | Flux | Very Low |
-
----
-
-## Top Candidates for Extraction
-
-1. **Search Input Component** - Generic, simple, widely useful
-2. **Station Card Component** - Good showcase of complex data display
-3. **User Menu Component** - Authentication pattern, widely needed
-4. **Loading Button Component** - Form UX pattern, commonly needed
-5. **Simple Auth Layout** - Authentication flows are common
-
----
-
-## Framework Package Recommendations
-
-If extracting these components into a package:
-
-1. Make them framework-agnostic (or have adapters)
-2. Ensure Flux/Livewire are peer dependencies
-3. Document required Alpine.js versions
-4. Provide TypeScript declarations for props
-5. Include Storybook examples
-6. Consider CSS-in-JS vs Tailwind integration
-

.superdesign/init/layouts.md

@@ -1,347 +0,0 @@
-# Layout Files
-
-## App Layouts (For Authenticated Users)
-
-### 1. `layouts/app.blade.php` (Main App Layout)
-**Path:** `resources/views/layouts/app.blade.php`
-
-Wrapper layout that delegates to sidebar layout. Used by authenticated routes.
-
-```blade
-<x-layouts::app.sidebar :title="$title ?? null">
-    <flux:main>
-        {{ $slot }}
-    </flux:main>
-</x-layouts::app.sidebar>
-```
-
----
-
-### 2. `layouts/app/sidebar.blade.php` (Sidebar Layout with Header/Navigation)
-**Path:** `resources/views/layouts/app/sidebar.blade.php`
-
-Core authenticated layout with sidebar navigation and header. Renders app header on desktop, mobile sidebar.
-
-**Key Features:**
-- Dark mode support (HTML class="dark")
-- Responsive: Sidebar on desktop, hamburger on mobile
-- Desktop navbar with Dashboard link
-- Mobile header with sidebar toggle
-- Search, Repository, and Documentation links
-- User menu in header (desktop) and mobile sidebar
-- Uses Flux components extensively
-
-**Structure:**
-- HTML/head with partials.head include
-- Body with min-h-screen, dark mode bg colors
-- flux:header (desktop) with:
-  - Sidebar toggle (mobile only)
-  - App logo
-  - Desktop navbar with links
-  - Spacer
-  - Secondary navbar (Search, Repo, Docs icons)
-  - Desktop user menu
-- flux:sidebar (mobile) with:
-  - App logo
-  - Sidebar collapse button
-  - Navigation group (Platform section)
-  - External links (Repo, Docs)
-- flux:main slot for page content
-- @fluxScripts directive at end
-
-```blade
-<!DOCTYPE html>
-<html lang="{{ str_replace('_', '-', app()->getLocale()) }}" class="dark">
-    <head>
-        @include('partials.head')
-    </head>
-    <body class="min-h-screen bg-white dark:bg-zinc-800">
-        <flux:header container class="border-b border-zinc-200 bg-zinc-50 dark:border-zinc-700 dark:bg-zinc-900">
-            <flux:sidebar.toggle class="lg:hidden mr-2" icon="bars-2" inset="left" />
-
-            <x-app-logo href="{{ route('dashboard') }}" wire:navigate />
-
-            <flux:navbar class="-mb-px max-lg:hidden">
-                <flux:navbar.item icon="layout-grid" :href="route('dashboard')" :current="request()->routeIs('dashboard')" wire:navigate>
-                    {{ __('Dashboard') }}
-                </flux:navbar.item>
-            </flux:navbar>
-
-            <flux:spacer />
-
-            <flux:navbar class="me-1.5 space-x-0.5 rtl:space-x-reverse py-0!">
-                <flux:tooltip :content="__('Search')" position="bottom">
-                    <flux:navbar.item class="!h-10 [&>div>svg]:size-5" icon="magnifying-glass" href="#" :label="__('Search')" />
-                </flux:tooltip>
-                <flux:tooltip :content="__('Repository')" position="bottom">
-                    <flux:navbar.item
-                        class="h-10 max-lg:hidden [&>div>svg]:size-5"
-                        icon="folder-git-2"
-                        href="https://github.com/laravel/livewire-starter-kit"
-                        target="_blank"
-                        :label="__('Repository')"
-                    />
-                </flux:tooltip>
-                <flux:tooltip :content="__('Documentation')" position="bottom">
-                    <flux:navbar.item
-                        class="h-10 max-lg:hidden [&>div>svg]:size-5"
-                        icon="book-open-text"
-                        href="https://laravel.com/docs/starter-kits#livewire"
-                        target="_blank"
-                        :label="__('Documentation')"
-                    />
-                </flux:tooltip>
-            </flux:navbar>
-
-            <x-desktop-user-menu />
-        </flux:header>
-
-        <!-- Mobile Menu -->
-        <flux:sidebar collapsible="mobile" sticky class="lg:hidden border-e border-zinc-200 bg-zinc-50 dark:border-zinc-700 dark:bg-zinc-900">
-            <flux:sidebar.header>
-                <x-app-logo :sidebar="true" href="{{ route('dashboard') }}" wire:navigate />
-                <flux:sidebar.collapse class="in-data-flux-sidebar-on-desktop:not-in-data-flux-sidebar-collapsed-desktop:-mr-2" />
-            </flux:sidebar.header>
-
-            <flux:sidebar.nav>
-                <flux:sidebar.group :heading="__('Platform')">
-                    <flux:sidebar.item icon="layout-grid" :href="route('dashboard')" :current="request()->routeIs('dashboard')" wire:navigate>
-                        {{ __('Dashboard')  }}
-                    </flux:sidebar.item>
-                </flux:sidebar.group>
-            </flux:sidebar.nav>
-
-            <flux:spacer />
-
-            <flux:sidebar.nav>
-                <flux:sidebar.item icon="folder-git-2" href="https://github.com/laravel/livewire-starter-kit" target="_blank">
-                    {{ __('Repository') }}
-                </flux:sidebar.item>
-                <flux:sidebar.item icon="book-open-text" href="https://laravel.com/docs/starter-kits#livewire" target="_blank">
-                    {{ __('Documentation') }}
-                </flux:sidebar.item>
-            </flux:sidebar.nav>
-        </flux:sidebar>
-
-        {{ $slot }}
-
-        @fluxScripts
-    </body>
-</html>
-```
-
----
-
-## Auth Layouts (For Unauthenticated Users)
-
-### 3. `layouts/auth.blade.php` (Auth Wrapper)
-**Path:** `resources/views/layouts/auth.blade.php`
-
-Simple wrapper that delegates to simple layout. Used for auth pages (login, register, password reset, etc.).
-
-```blade
-<x-layouts::auth.simple :title="$title ?? null">
-    {{ $slot }}
-</x-layouts::auth.simple>
-```
-
----
-
-### 4. `layouts/auth/simple.blade.php` (Simple Auth Layout - Centered)
-**Path:** `resources/views/layouts/auth/simple.blade.php`
-
-Minimalist centered layout for authentication. Used for login, register, etc.
-
-**Key Features:**
-- Dark mode with gradient background (dark:from-neutral-950 to-neutral-900)
-- Centered content with max-width constraint
-- App logo centered with link to home
-- Dark mode gradient background
-- Flex column centered layout
-
-```blade
-<!DOCTYPE html>
-<html lang="{{ str_replace('_', '-', app()->getLocale()) }}" class="dark">
-    <head>
-        @include('partials.head')
-    </head>
-    <body class="min-h-screen bg-white antialiased dark:bg-linear-to-b dark:from-neutral-950 dark:to-neutral-900">
-        <div class="bg-background flex min-h-svh flex-col items-center justify-center gap-6 p-6 md:p-10">
-            <div class="flex w-full max-w-sm flex-col gap-2">
-                <a href="{{ route('home') }}" class="flex flex-col items-center gap-2 font-medium" wire:navigate>
-                    <span class="flex h-9 w-9 mb-1 items-center justify-center rounded-md">
-                        <x-app-logo-icon class="size-9 fill-current text-black dark:text-white" />
-                    </span>
-                    <span class="sr-only">{{ config('app.name', 'Laravel') }}</span>
-                </a>
-                <div class="flex flex-col gap-6">
-                    {{ $slot }}
-                </div>
-            </div>
-        </div>
-        @fluxScripts
-    </body>
-</html>
-```
-
----
-
-### 5. `layouts/auth/card.blade.php` (Card-based Auth Layout)
-**Path:** `resources/views/layouts/auth/card.blade.php`
-
-Card-based authentication layout with rounded borders and shadow. Alternative to simple layout.
-
-**Key Features:**
-- Centered card with white background and dark border
-- Max-width constraint
-- Padding inside card (px-10 py-8)
-- Light neutral-100 background
-- Dark mode: stone-950 card bg with stone-800 border
-
-```blade
-<!DOCTYPE html>
-<html lang="{{ str_replace('_', '-', app()->getLocale()) }}" class="dark">
-    <head>
-        @include('partials.head')
-    </head>
-    <body class="min-h-screen bg-neutral-100 antialiased dark:bg-linear-to-b dark:from-neutral-950 dark:to-neutral-900">
-        <div class="bg-muted flex min-h-svh flex-col items-center justify-center gap-6 p-6 md:p-10">
-            <div class="flex w-full max-w-md flex-col gap-6">
-                <a href="{{ route('home') }}" class="flex flex-col items-center gap-2 font-medium" wire:navigate>
-                    <span class="flex h-9 w-9 items-center justify-center rounded-md">
-                        <x-app-logo-icon class="size-9 fill-current text-black dark:text-white" />
-                    </span>
-
-                    <span class="sr-only">{{ config('app.name', 'Laravel') }}</span>
-                </a>
-
-                <div class="flex flex-col gap-6">
-                    <div class="rounded-xl border bg-white dark:bg-stone-950 dark:border-stone-800 text-stone-800 shadow-xs">
-                        <div class="px-10 py-8">{{ $slot }}</div>
-                    </div>
-                </div>
-            </div>
-        </div>
-        @fluxScripts
-    </body>
-</html>
-```
-
----
-
-### 6. `layouts/auth/split.blade.php` (Split-screen Auth Layout)
-**Path:** `resources/views/layouts/auth/split.blade.php`
-
-Split-screen layout with marketing content on left (desktop only) and form on right.
-
-**Key Features:**
-- Two-column layout on desktop (lg:grid-cols-2)
-- Left side: Dark background (neutral-900) with motivational quote (hidden on mobile)
-- Right side: Form content
-- Logo centered on mobile, top-left on desktop (left side)
-- Quote display with blockquote
-- Uses Flux heading component
-- Full viewport height (h-dvh)
-
-```blade
-<!DOCTYPE html>
-<html lang="{{ str_replace('_', '-', app()->getLocale()) }}" class="dark">
-    <head>
-        @include('partials.head')
-    </head>
-    <body class="min-h-screen bg-white antialiased dark:bg-linear-to-b dark:from-neutral-950 dark:to-neutral-900">
-        <div class="relative grid h-dvh flex-col items-center justify-center px-8 sm:px-0 lg:max-w-none lg:grid-cols-2 lg:px-0">
-            <div class="bg-muted relative hidden h-full flex-col p-10 text-white lg:flex dark:border-e dark:border-neutral-800">
-                <div class="absolute inset-0 bg-neutral-900"></div>
-                <a href="{{ route('home') }}" class="relative z-20 flex items-center text-lg font-medium" wire:navigate>
-                    <span class="flex h-10 w-10 items-center justify-center rounded-md">
-                        <x-app-logo-icon class="me-2 h-7 fill-current text-white" />
-                    </span>
-                    {{ config('app.name', 'Laravel') }}
-                </a>
-
-                @php
-                    [$message, $author] = str(Illuminate\Foundation\Inspiring::quotes()->random())->explode('-');
-                @endphp
-
-                <div class="relative z-20 mt-auto">
-                    <blockquote class="space-y-2">
-                        <flux:heading size="lg">&ldquo;{{ trim($message) }}&rdquo;</flux:heading>
-                        <footer><flux:heading>{{ trim($author) }}</flux:heading></footer>
-                    </blockquote>
-                </div>
-            </div>
-            <div class="w-full lg:p-8">
-                <div class="mx-auto flex w-full flex-col justify-center space-y-6 sm:w-[350px]">
-                    <a href="{{ route('home') }}" class="z-20 flex flex-col items-center gap-2 font-medium lg:hidden" wire:navigate>
-                        <span class="flex h-9 w-9 items-center justify-center rounded-md">
-                            <x-app-logo-icon class="size-9 fill-current text-black dark:text-white" />
-                        </span>
-
-                        <span class="sr-only">{{ config('app.name', 'Laravel') }}</span>
-                    </a>
-                    {{ $slot }}
-                </div>
-            </div>
-        </div>
-        @fluxScripts
-    </body>
-</html>
-```
-
----
-
-## Head/Partial Layouts
-
-### 7. `partials/head.blade.php`
-**Path:** `resources/views/partials/head.blade.php`
-
-Shared head section included in all layouts.
-
-**Content:**
-- Meta charset and viewport
-- Dynamic title generation
-- Favicon setup (ico, svg, apple-touch-icon)
-- Fonts: Instrument Sans from fonts.bunny.net (weights 400, 500, 600)
-- Vite asset loading (CSS and JS)
-- Flux appearance directive (dark mode toggle support)
-
-```blade
-<meta charset="utf-8" />
-<meta name="viewport" content="width=device-width, initial-scale=1.0" />
-
-<title>
-    {{ filled($title ?? null) ? $title.' - '.config('app.name', 'Laravel') : config('app.name', 'Laravel') }}
-</title>
-
-<link rel="icon" href="/favicon.ico" sizes="any">
-<link rel="icon" href="/favicon.svg" type="image/svg+xml">
-<link rel="apple-touch-icon" href="/apple-touch-icon.png">
-
-<link rel="preconnect" href="https://fonts.bunny.net">
-<link href="https://fonts.bunny.net/css?family=instrument-sans:400,500,600" rel="stylesheet" />
-
-@vite(['resources/css/app.css', 'resources/js/app.js'])
-@fluxAppearance
-```
-
----
-
-## Usage Pattern
-
-| Route | Layout Chain | Use Case |
-|-------|-----------|----------|
-| `/` (home) | Custom (not using these layouts) | Landing page |
-| `/dashboard` | `layouts/app` → `layouts/app/sidebar` | Authenticated user dashboard |
-| `/login`, `/register` | `layouts/auth` → `layouts/auth/simple` | Simple auth forms |
-| `/stations` | StationSearch Livewire component (no layout wrapper) | Public search page |
-| `/settings/*` | `layouts/app` → `layouts/app/sidebar` | Settings pages |
-
----
-
-## Color Scheme in Layouts
-
-- **Light Mode:** white background, zinc borders
-- **Dark Mode:** zinc-800 body, zinc-900 header/sidebar, zinc-700 borders
-- **Auth Pages (Dark):** linear gradient from neutral-950 to neutral-900
-

.superdesign/init/pages.md

@@ -1,291 +0,0 @@
-# Pages & Full-Page Components
-
-## Page Dependency Trees
-
-Pages are organized by their view location and dependencies. Livewire components with full-page routes are documented here.
-
----
-
-## 1. StationSearch (Public Livewire Component)
-**Route:** `/stations`  
-**Component:** `App\Livewire\Public\StationSearch`  
-**View:** `resources/views/livewire/public/station-search.blade.php`
-
-### Dependency Tree
-
-```
-StationSearch (Livewire Component)
-├── resources/views/livewire/public/station-search.blade.php
-│   ├── flux:heading (component)
-│   ├── flux:subheading (component)
-│   ├── form > flux:input (Fuel location input)
-│   ├── form > flux:select (Fuel type selector)
-│   │   └── Options: Petrol, E5, Diesel, Premium Diesel, B10, HVO
-│   ├── form > flux:select (Radius selector)
-│   │   └── Options: 1, 2, 5, 10, 20 miles
-│   ├── form > flux:select (Sort selector)
-│   │   └── Options: Price, Distance, Updated, Brand, Reliable
-│   ├── form > flux:button (Search button)
-│   ├── Error display (conditional)
-│   ├── Results meta (count, cheapest, average)
-│   ├── x-data="stationMap(...)" (Alpine.js map)
-│   │   └── resources/js/maps/station-map.js
-│   │       ├── Leaflet map initialization
-│   │       ├── OpenStreetMap tiles
-│   │       └── Circle markers (station data)
-│   ├── Legend (color codes for data age)
-│   └── Results list
-│       └── Station cards (name, address, price, distance, age classification)
-│           └── flux:badge (Supermarket tag, conditional)
-```
-
-### Data Flow
-
-1. **PHP Class** (`App\Livewire\Public\StationSearch`):
-   - Properties: `$search`, `$fuelType`, `$radius`, `$sort`
-   - Properties: `$results[]`, `$meta[]`, `$apiError`
-   - Methods:
-     - `updatedFuelType()`: Refetch on fuel type change
-     - `updatedRadius()`: Refetch on radius change
-     - `updatedSort()`: Refetch on sort change
-     - `findStations()`: HTTP request to `/api/stations`
-     - `render()`: Returns view
-
-2. **View Interactions**:
-   - `wire:model` on search input (two-way binding)
-   - `wire:model.live` on selectors (reactive updates)
-   - `wire:submit="findStations"` on form submit
-   - `wire:loading` for button state
-   - `wire:target="findStations"` for loading indicator
-   - `@entangle('results')` for Alpine.js map data
-
-3. **JavaScript**:
-   - `stationMap(results)` Alpine data object
-   - Watches for `results` property changes
-   - Renders/updates Leaflet markers dynamically
-
----
-
-## 2. Dashboard
-**Route:** `/dashboard`  
-**View:** `resources/views/dashboard.blade.php`  
-**Middleware:** `auth`, `verified`
-
-### Dependency Tree
-
-```
-dashboard.blade.php
-├── Layout: x-layouts::app (authenticated layout)
-│   └── layouts/app.blade.php
-│       └── x-layouts::app.sidebar (sidebar layout)
-│           └── layouts/app/sidebar.blade.php
-│               ├── partials/head.blade.php
-│               ├── flux:header (navigation)
-│               │   ├── x-app-logo
-│               │   ├── flux:navbar with Dashboard link
-│               │   ├── Secondary icons (Search, Repo, Docs)
-│               │   └── x-desktop-user-menu
-│               └── flux:sidebar (mobile navigation)
-│
-├── flux:main (page content wrapper)
-│
-└── Content: Grid of placeholder cards
-    └── x-placeholder-pattern (diagonal line SVG pattern)
-        └── 3 aspect-video cards (top row)
-        └── 1 flex-1 card (bottom, full height)
-```
-
-### Features
-
-- Placeholder cards for future dashboard widgets
-- Responsive grid: 3 columns on desktop, stacked on mobile
-- Dark mode support with adjusted stroke colors
-
----
-
-## 3. Welcome/Home Page
-**Route:** `/`  
-**View:** `resources/views/welcome.blade.php`
-
-### Note
-
-The welcome view is large (>15KB) and contains:
-- Full HTML with embedded Tailwind CSS
-- Hero section with Fuel Price branding
-- CTA buttons (Search Stations, View Source)
-- Feature cards
-- Dark mode support
-- No layout wrapper (standalone)
-
-(Full content available in actual file due to size)
-
----
-
-## 4. Settings Pages
-**Route:** `/settings/*`  
-**Layout:** `x-layouts::app` → `layouts/app/sidebar.blade.php`
-
-### 4.1 Profile Settings
-**Route:** `/settings/profile`  
-**Livewire Component:** `pages::settings.profile`
-
-### Dependency Tree
-
-```
-settings/profile (Livewire Component)
-├── Layout: x-layouts::app
-│   └── layouts/app/sidebar.blade.php
-│
-├── partials/settings-heading.blade.php
-│   ├── flux:heading ("Settings")
-│   ├── flux:subheading ("Manage your profile...")
-│   └── flux:separator
-│
-├── pages/settings/layout.blade.php (settings sidebar layout)
-│   ├── flux:navlist (navigation)
-│   │   ├── flux:navlist.item (Profile - current)
-│   │   ├── flux:navlist.item (Security)
-│   │   └── flux:navlist.item (Appearance)
-│   │
-│   └── Slot content (form fields)
-│       └── Profile edit form (Livewire form)
-│           ├── flux:input (Name)
-│           ├── flux:input (Email)
-│           ├── flux:button (Save)
-│           └── Action messages on update
-```
-
-### 4.2 Security Settings
-**Route:** `/settings/security`  
-**Livewire Component:** `pages::settings.security`
-
-- Two-factor authentication setup/management
-- Recovery codes display
-- Password confirmation (optional middleware)
-
-### 4.3 Appearance Settings
-**Route:** `/settings/appearance`  
-**Livewire Component:** `pages::settings.appearance`
-
-- Theme selection (light/dark mode)
-- Preference persistence
-
----
-
-## 5. Authentication Pages
-**Layout:** `x-layouts::auth` → Various auth layouts
-
-### 5.1 Login
-**Route:** `/login`  
-**View:** `resources/views/pages/auth/login.blade.php`  
-**Layout:** `layouts/auth/simple.blade.php`
-
-### Dependency Tree
-
-```
-login.blade.php
-├── Layout: x-layouts::auth
-│   └── layouts/auth/simple.blade.php
-│       ├── partials/head.blade.php
-│       └── Centered login form
-│
-├── x-auth-header (title + description)
-├── x-auth-session-status (success message display)
-├── form (POST to login.store)
-│   ├── csrf token
-│   ├── flux:input (Email)
-│   ├── flux:input (Password, viewable)
-│   │   └── flux:link to password.request (forgot password)
-│   ├── flux:checkbox (Remember me)
-│   └── flux:button (Log in, primary)
-│
-└── Sign up link (flux:link to register)
-```
-
-### 5.2 Register
-**Route:** `/register`  
-**View:** `resources/views/pages/auth/register.blade.php`  
-**Layout:** `layouts/auth/simple.blade.php`
-
-```
-register.blade.php
-├── Layout: layouts/auth/simple.blade.php
-├── x-auth-header
-├── x-auth-session-status
-├── form (POST to register.store)
-│   ├── flux:input (Name)
-│   ├── flux:input (Email)
-│   ├── flux:input (Password, viewable)
-│   ├── flux:input (Password Confirmation, viewable)
-│   └── flux:button (Create account, primary)
-└── Log in link
-```
-
-### 5.3 Password Reset
-**Route:** `/forgot-password` and `/reset-password/{token}`  
-**Views:** `pages/auth/forgot-password.blade.php`, `pages/auth/reset-password.blade.php`  
-**Layout:** `layouts/auth/simple.blade.php`
-
-### 5.4 Email Verification
-**Route:** `/verify-email`  
-**View:** `pages/auth/verify-email.blade.php`  
-**Layout:** `layouts/auth/simple.blade.php`
-
-### 5.5 Two-Factor Challenge
-**Route:** `/two-factor-challenge`  
-**View:** `pages/auth/two-factor-challenge.blade.php`  
-**Layout:** `layouts/auth/simple.blade.php`
-
----
-
-## Component Include Hierarchy
-
-### Layout Chain (All Authenticated Pages)
-
-```
-Page View
-└── x-layouts::app (wrapper)
-    └── x-layouts::app.sidebar (main layout)
-        ├── partials/head (in <head>)
-        │   ├── CSS imports (Vite)
-        │   ├── @fluxAppearance
-        │   └── Font preload
-        │
-        ├── flux:header (desktop navigation)
-        │   ├── x-app-logo
-        │   ├── x-desktop-user-menu
-        │   └── flux:navbar / flux:tooltip components
-        │
-        ├── flux:sidebar (mobile navigation)
-        │   ├── x-app-logo (:sidebar="true")
-        │   └── Navigation items
-        │
-        └── flux:main (page content slot)
-            └── Page-specific content
-```
-
-### Layout Chain (Auth Pages)
-
-```
-Auth Page View
-└── x-layouts::auth (wrapper)
-    └── x-layouts::auth.simple (centered layout)
-        ├── partials/head (in <head>)
-        └── Centered card with form
-            ├── x-app-logo-icon
-            └── x-auth-header or form content
-```
-
----
-
-## Page Transitions
-
-All pages use `wire:navigate` for Livewire navigation (no full page reload).
-
-Example:
-- `wire:navigate` on `<flux:brand>` links
-- `wire:navigate` on `<flux:link>` components
-- `wire:navigate` on navigation items
-
-This enables seamless SPA-like experience.
-

.superdesign/init/routes.md

@@ -1,120 +0,0 @@
-# Routes
-
-## Public Routes
-
-### `routes/web.php`
-
-```php
-<?php
-
-use App\Livewire\Public\StationSearch;
-use Illuminate\Support\Facades\Route;
-
-Route::view('/', 'homepage')->name('home');
-
-Route::get('/stations', StationSearch::class)->name('stations.search');
-
-Route::middleware(['auth', 'verified'])->group(function () {
-    Route::view('dashboard', 'dashboard')->name('dashboard');
-});
-
-require __DIR__.'/settings.php';
-```
-
----
-
-## Settings Routes
-
-### `routes/settings.php`
-
-```php
-<?php
-
-use Illuminate\Support\Facades\Route;
-use Laravel\Fortify\Features;
-
-Route::middleware(['auth'])->group(function () {
-    Route::redirect('settings', 'settings/profile');
-
-    Route::livewire('settings/profile', 'pages::settings.profile')->name('profile.edit');
-});
-
-Route::middleware(['auth', 'verified'])->group(function () {
-    Route::livewire('settings/appearance', 'pages::settings.appearance')->name('appearance.edit');
-
-    Route::livewire('settings/security', 'pages::settings.security')
-        ->middleware(
-            when(
-                Features::canManageTwoFactorAuthentication()
-                    && Features::optionEnabled(Features::twoFactorAuthentication(), 'confirmPassword'),
-                ['password.confirm'],
-                [],
-            ),
-        )
-        ->name('security.edit');
-});
-```
-
-**Note:** Auth routes (login, register, password reset, etc.) are provided by Laravel Fortify. See `config/fortify.php` for route definitions.
-
----
-
-## Route Summary Table
-
-| Method | Path | Name | Component/View | Middleware | Purpose |
-|--------|------|------|---|---|---|
-| GET | `/` | `home` | `welcome` view | public | Landing page |
-| GET | `/stations` | `stations.search` | `StationSearch` Livewire | public | Fuel station search page |
-| GET | `/dashboard` | `dashboard` | `dashboard` view | `auth`, `verified` | Authenticated user dashboard |
-| GET/POST | `/login` | `login` | Fortify auth | public | User login |
-| GET/POST | `/register` | `register` | Fortify auth | public | User registration |
-| POST | `/logout` | `logout` | Fortify action | `auth` | Logout action |
-| GET/POST | `/forgot-password` | `password.request` | Fortify auth | public | Password reset request |
-| GET/POST | `/reset-password/{token}` | `password.reset` | Fortify auth | public | Password reset form |
-| GET/POST | `/confirm-password` | `password.confirm` | Fortify auth | `auth` | Confirm password (before sensitive actions) |
-| GET/POST | `/verify-email` | `verification.notice` | Fortify auth | `auth` | Email verification |
-| GET | `/verify-email/{id}/{hash}` | `verification.verify` | Fortify action | `auth`, `signed` | Verify email action |
-| GET/POST | `/two-factor-challenge` | `two-factor.login` | Fortify auth | `guest` | Two-factor challenge |
-| GET | `/settings` | (redirect) | → `settings.profile` | `auth` | Redirect to profile |
-| GET | `/settings/profile` | `profile.edit` | Livewire `pages::settings.profile` | `auth` | Edit user profile |
-| GET | `/settings/appearance` | `appearance.edit` | Livewire `pages::settings.appearance` | `auth`, `verified` | Edit appearance preferences |
-| GET | `/settings/security` | `security.edit` | Livewire `pages::settings.security` | `auth`, `verified`, (optional) `password.confirm` | Edit security settings |
-
----
-
-## Route Grouping
-
-### Public Routes
-- Landing page (`/`)
-- Station search (`/stations`)
-- Fortify auth routes (login, register, password reset, etc.)
-
-### Authenticated Routes
-- Dashboard (`/dashboard`)
-- Settings pages (`/settings/*`)
-
-### Settings Routes (Special Handling)
-- Profile editing: `auth` only
-- Appearance: `auth`, `verified`
-- Security: `auth`, `verified`, optional password confirmation
-
----
-
-## Livewire Component Routes
-
-| Route | Livewire Component | View | Purpose |
-|-------|---|---|---|
-| `/stations` | `App\Livewire\Public\StationSearch` | `livewire.public.station-search` | Interactive fuel station search with map |
-| `/settings/profile` | `pages::settings.profile` | `pages.settings.profile` | User profile management |
-| `/settings/appearance` | `pages::settings.appearance` | `pages.settings.appearance` | Theme/appearance preferences |
-| `/settings/security` | `pages::settings.security` | `pages.settings.security` | Security and 2FA settings |
-
----
-
-## Notes
-
-- **Fortify**: The application uses Laravel Fortify for authentication scaffolding. Auth routes are auto-registered by Fortify package.
-- **Livewire Routes**: Routes using `Route::livewire()` expect corresponding Livewire components in `app/Livewire/`.
-- **Middleware Chain**: Routes are protected with `auth` and/or `verified` middleware as appropriate.
-- **Settings Redirect**: Accessing `/settings` redirects to `/settings/profile` (first settings tab).
-

.superdesign/init/theme.md

@@ -1,298 +0,0 @@
-# Design System & Theme
-
-## Tailwind Configuration
-
-### `tailwind.config.js`
-
-File doesn't exist. The project uses Tailwind CSS v4 with `@tailwindcss/vite` plugin for compilation.
-
----
-
-## CSS Configuration
-
-### `resources/css/app.css`
-
-```css
-@import 'leaflet/dist/leaflet.css';
-@import 'tailwindcss';
-@import '../../vendor/livewire/flux/dist/flux.css';
-
-@source '../views';
-@source '../../vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php';
-@source '../../vendor/livewire/flux-pro/stubs/**/*.blade.php';
-@source '../../vendor/livewire/flux/stubs/**/*.blade.php';
-
-@custom-variant dark (&:where(.dark, .dark *));
-
-@theme {
-    --font-sans: 'Instrument Sans', ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
-
-    --color-zinc-50: #fafafa;
-    --color-zinc-100: #f5f5f5;
-    --color-zinc-200: #e5e5e5;
-    --color-zinc-300: #d4d4d4;
-    --color-zinc-400: #a3a3a3;
-    --color-zinc-500: #737373;
-    --color-zinc-600: #525252;
-    --color-zinc-700: #404040;
-    --color-zinc-800: #262626;
-    --color-zinc-900: #171717;
-    --color-zinc-950: #0a0a0a;
-
-    --color-accent: var(--color-neutral-800);
-    --color-accent-content: var(--color-neutral-800);
-    --color-accent-foreground: var(--color-white);
-}
-
-@layer theme {
-    .dark {
-        --color-accent: var(--color-white);
-        --color-accent-content: var(--color-white);
-        --color-accent-foreground: var(--color-neutral-800);
-    }
-}
-
-@layer base {
-
-    *,
-    ::after,
-    ::before,
-    ::backdrop,
-    ::file-selector-button {
-        border-color: var(--color-gray-200, currentColor);
-    }
-}
-
-[data-flux-field]:not(ui-radio, ui-checkbox) {
-    @apply grid gap-2;
-}
-
-[data-flux-label] {
-    @apply  !mb-0 !leading-tight;
-}
-
-input:focus[data-flux-control],
-textarea:focus[data-flux-control],
-select:focus[data-flux-control] {
-    @apply outline-hidden ring-2 ring-accent ring-offset-2 ring-offset-accent-foreground;
-}
-```
-
----
-
-## Color Palette
-
-### Primary Colors
-- **Zinc Palette** (grays): 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950
-  - Used for backgrounds, borders, text
-
-### Accent Colors
-- **Dark Mode:** White/neutral-800 depending on context
-- **Light Mode:** neutral-800
-- **Accent Foreground:** White (light mode), neutral-800 (dark mode)
-- **Accent Content:** neutral-800 (light), white (dark)
-
-### Status Colors
-- **Success:** green-500, green-600
-- **Warning:** amber-500, amber-400
-- **Error:** red-500, red-400, red-600
-- **Info:** slate-500
-
-### Semantic Colors (from Station Search)
-- **Current Price (fresh):** green-500 (#22c55e)
-- **Recent (24-48h):** slate-500 (#64748b)
-- **Stale (2-5 days):** amber-500 (#f59e0b)
-- **Outdated (5+ days):** red-500 (#ef4444)
-
----
-
-## Typography
-
-### Font Family
-- **Primary:** 'Instrument Sans' (Weights: 400, 500, 600)
-- **Fallback:** ui-sans-serif, system-ui, sans-serif
-- **Emoji:** Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji
-
-### Font Sizes & Weights (via Flux)
-- **Heading (XL):** Used for page titles
-- **Heading (LG):** Used for section titles
-- **Subheading:** Used for descriptions
-- **Text:** Standard body text
-- **Label:** Form labels
-- **Badge:** Small text labels
-
----
-
-## Spacing System
-
-Based on Tailwind default scale:
-- **Base Unit:** 4px (1 = 4px)
-- **Common Spacing:**
-  - `gap-2`: 8px (0.5rem)
-  - `gap-3`: 12px (0.75rem)
-  - `gap-4`: 16px (1rem)
-  - `gap-6`: 24px (1.5rem)
-  - `px-4`: 16px horizontal padding
-  - `py-3`: 12px vertical padding
-  - `p-6`: 24px all sides padding
-  - `p-10`: 40px all sides padding
-
----
-
-## Border & Radius
-
-### Border Colors
-- **Light:** `border-zinc-200`
-- **Dark:** `border-zinc-700` (primary), `border-stone-800` (cards), `border-neutral-800` (split layout)
-
-### Border Radius
-- **Input/buttons:** Default Flux radius
-- **Cards:** `rounded-xl` (larger radius)
-- **Icons/small:** `rounded-md`
-
----
-
-## Dark Mode
-
-### Implementation
-- Uses `class="dark"` on `<html>` root
-- Custom variant: `@custom-variant dark (&:where(.dark, .dark *))`
-- Flux `@fluxAppearance` directive manages theme toggle
-
-### Dark Mode Colors
-- **Body BG:** `dark:bg-zinc-800`
-- **Header/Sidebar BG:** `dark:bg-zinc-900`
-- **Borders:** `dark:border-zinc-700`
-- **Text:** `dark:text-zinc-100` (headings), `dark:text-zinc-400` (secondary)
-
-### Accent in Dark Mode
-- `--color-accent: var(--color-white)`
-- `--color-accent-foreground: var(--color-neutral-800)`
-
----
-
-## Responsive Design
-
-### Breakpoints (Tailwind defaults)
-- **sm:** 640px
-- **md:** 768px
-- **lg:** 1024px
-- **xl:** 1280px
-- **2xl:** 1536px
-
-### Usage Patterns
-- `max-lg:hidden` - Hide on mobile/tablet
-- `lg:hidden` - Hide on desktop
-- `max-md:flex-col` - Stack on small screens
-- `sm:flex-row` - Row layout on small+ screens
-- `md:w-[220px]` - Fixed width on medium+
-
----
-
-## Component-Specific Theming
-
-### Forms (Flux)
-- `[data-flux-field]`: grid gap-2 layout
-- `[data-flux-label]`: No margin-bottom, tight line-height
-- Focus states: ring-2 ring-accent with ring-offset
-
-### Flux Appearance
-- Automatically applied via `@fluxAppearance` directive
-- Manages light/dark mode toggle
-- Integrates with browser's prefers-color-scheme
-
-### Leaflet Map
-- Uses default OSM tiles
-- Custom marker colors: green (current), slate (recent), amber (stale), red (outdated)
-- Markers: 9px radius, white stroke, 2px weight, 85% fill opacity
-
----
-
-## Brand Identity
-
-### Logo
-- **Primary Icon:** Custom SVG (geometric design)
-- **Color:** Adapts to theme (black light mode, white dark mode)
-- **Name:** "Laravel Starter Kit"
-- **Contexts:**
-  - Header/nav: `flux:brand`
-  - Sidebar: `flux:sidebar.brand`
-
-### Loading/Placeholder States
-- Pattern SVG with diagonal lines
-- Color: `stroke-gray-900/20` (light) or `stroke-neutral-100/20` (dark)
-
----
-
-## Animations & Transitions
-
-### Alpine.js Transitions
-- **Message Dismiss:** `x-show.transition.out.opacity.duration.1500ms`
-- **Fade effects:** opacity transitions over 1500ms
-
-### Flux Components
-- Built-in animations for:
-  - Dropdown menus
-  - Sidebar collapse/expand
-  - Modal opens/closes
-
----
-
-## CSS Custom Properties (Tokens)
-
-```css
---font-sans: 'Instrument Sans', ...
---color-zinc-50 through --color-zinc-950
---color-accent
---color-accent-content
---color-accent-foreground
-```
-
----
-
-## Vite Build Configuration
-
-**File:** `vite.config.js`
-
-```javascript
-import {
-    defineConfig
-} from 'vite';
-import laravel from 'laravel-vite-plugin';
-import tailwindcss from "@tailwindcss/vite";
-
-export default defineConfig({
-    plugins: [
-        laravel({
-            input: ['resources/css/app.css', 'resources/js/app.js'],
-            refresh: true,
-        }),
-        tailwindcss(),
-    ],
-    server: {
-        cors: true,
-        watch: {
-            ignored: ['**/storage/framework/views/**'],
-        },
-    },
-});
-```
-
-**Features:**
-- Tailwind CSS v4 via @tailwindcss/vite plugin
-- Automatic CSS/JS refresh
-- CORS enabled for dev server
-- Ignores Laravel view cache files
-
----
-
-## Flux UI Theme Configuration
-
-Flux v2 is configured via:
-- CSS import: `@import '../../vendor/livewire/flux/dist/flux.css'`
-- Content sources point to Flux stubs for autocomplete
-- `@fluxAppearance` handles dark mode toggling
-- `@fluxScripts` loads JavaScript enhancements
-
-No custom Flux config file exists; uses defaults with CSS customizations.
-

CLAUDE.md

@@ -1,15 +1,51 @@
-# Fuel Price — Claude Code Instructions
+# Fuel Alert — Claude Code Instructions
 
 UK fuel price intelligence app. Subscribers receive fill-up timing recommendations
 based on local price trends. Built solo by a PHP/Laravel developer.
 
+> **Stack reality check (read first).** The frontend is a **Vue 3 SPA**
+> (`resources/js/`, see `frontend.md`), not Livewire. Station data is served by a
+> **REST API** under `routes/api.php` (see `architecture.md`). Some domain rule
+> files (`scoring.md`, `prediction.md`, `notifications.md`) still name services
+> that were since refactored into `Services/Forecasting/`,
+> `Services/StationSearch/`, and `PlanFeatures` — verify names against
+> `app/Services/`. When docs and code disagree, the code wins.
+
+## Destructive DB operations — HARD STOP
+
+**Never run** the following commands. If one of them is the right step, stop, tell the user the exact command, and ask them to run it themselves:
+
+- `php artisan migrate:fresh` (with any flags, including `--seed`)
+- `php artisan migrate:reset`
+- `php artisan db:wipe`
+- Raw `DROP TABLE`, `DROP DATABASE`, or `TRUNCATE` via tinker, `database-query`, or any MCP tool
+- Any sequence that effectively rebuilds the schema or drops tables
+
+These are also blocked at the harness level via `.claude/settings.json` deny rules, but the prose rule applies everywhere the block doesn't reach (compound shell commands, MCP tools, etc.).
+
+A user saying "trust me", "do the refactor", "clean up the mess", or "I want it in db" is **not** authorisation for these — the architectural decision is separate from the operational step. If a migration is awkward to apply in-place, propose the in-place version (read JSON → populate new columns → drop the old column) instead of suggesting a rebuild. Asking once at the start of a task does not authorise repeat wipes later in the session.
+
 ## Project overview
 
 - **Product**: "Fill up now or wait?" — local fuel price trend scoring for UK drivers
 - **Monetisation**: £0/mo free, £0.99/mo Basic, £2.49/mo Plus, £3.99/mo Pro
-- **Stack**: Laravel 11 + Livewire 3 (Volt disabled — use classic components) + Alpine.js + Tailwind CSS
+- **Backend**: Laravel 13 + PHP 8.4. MySQL (Eloquent, migrations only — no raw DDL)
-- **Database**: MySQL — Eloquent ORM, migrations only (no raw DDL)
+- **Frontend**: **Vue 3 SPA** — Vue 3.5 + Vue Router 4, Vite 8, Tailwind CSS v4.
-- **Payments**: Stripe via Laravel Cashier
+  Entry `resources/js/app.js` mounts `App.vue`; views/components under
+  `resources/js/`. Served from the Blade shell `resources/views/app.blade.php`
+  via the SPA catch-all in `web.php`. Maps: Leaflet
+  (`components/LeafletMap.vue`). Icons: iconify-icon + Lucide. HTTP: axios
+  (`resources/js/axios.js`).
+- **API**: REST API in `routes/api.php` → `app/Http/Controllers/Api/*`
+  (Auth, Station, Stats, User). Public station data is gated by an API key
+  (`VerifyApiKey` middleware); user/dashboard endpoints use Sanctum. The SPA is
+  the primary consumer.
+- **Auth**: Laravel Fortify (backend auth) + Sanctum (API tokens)
+- **Admin**: Filament v5 panel
+- **Livewire**: v4 / Flux v2 are installed but **vestigial** — only starter-kit
+  Volt auth screens (`resources/views/livewire/auth`) and `app/Livewire/Actions`
+  remain. Do **not** build new Livewire components; build Vue.
+- **Payments**: Stripe via Laravel Cashier (v16)
 - **Notifications**: Laravel Notification channels — email, WhatsApp (Vonage), SMS (Vonage), push (OneSignal)
 - **Queue**: Laravel queues with Redis driver (notifications and polling jobs)
 - **Scheduler**: Laravel scheduler for Fuel Finder API polling and scoring
@@ -22,7 +58,8 @@ php artisan queue:work     # Process notification jobs
 php artisan schedule:run   # Run scheduled commands (cron every minute)
 php artisan migrate        # Run migrations
 php artisan test           # Run Pest test suite
-npm run dev                # Vite asset watcher
+npm run dev                # Vite dev server (Vue SPA + HMR)
+npm run build              # Production build — run if SPA changes don't show up
 ```
 
 ## Imports
@@ -34,7 +71,7 @@ npm run dev                # Vite asset watcher
 @.claude/rules/prediction.md
 @.claude/rules/payments.md
 @.claude/rules/tiers.md
-@.claude/rules/livewire.md
+@.claude/rules/frontend.md
 @.claude/rules/api-data.md
 @.claude/rules/testing.md
 @.claude/rules/code-style.md

app/Console/Commands/BackfillOilPrices.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\BrentPriceFetcher;
+use App\Services\BrentPriceSources\BrentPriceFetchException;
+use Illuminate\Console\Attributes\Description;
+use Illuminate\Console\Attributes\Signature;
+use Illuminate\Console\Command;
+
+#[Signature('oil:backfill {--from=2018-01-01 : ISO start date (inclusive)} {--to= : ISO end date (defaults to today, inclusive)}')]
+#[Description('One-shot backfill of historical Brent crude prices from FRED into brent_prices.')]
+class BackfillOilPrices extends Command
+{
+    public function handle(BrentPriceFetcher $fetcher): int
+    {
+        $from = (string) $this->option('from');
+        $to = (string) ($this->option('to') ?: now()->toDateString());
+
+        $this->info("Backfilling Brent ({$from} → {$to}) from FRED...");
+
+        try {
+            $count = $fetcher->backfillFromFred($from, $to);
+            $this->info(sprintf('Upserted %d Brent rows.', $count));
+
+            return self::SUCCESS;
+        } catch (BrentPriceFetchException $e) {
+            $this->error('FRED backfill failed: '.$e->getMessage());
+
+            return self::FAILURE;
+        }
+    }
+}

app/Console/Commands/EvaluateVolatilityRegime.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\Forecasting\VolatilityRegimeService;
+use Illuminate\Console\Attributes\Description;
+use Illuminate\Console\Attributes\Signature;
+use Illuminate\Console\Command;
+
+#[Signature('forecast:evaluate-volatility')]
+#[Description('Evaluate the volatility regime triggers and update volatility_regimes accordingly. Hourly cron.')]
+class EvaluateVolatilityRegime extends Command
+{
+    public function handle(VolatilityRegimeService $service): int
+    {
+        $regime = $service->evaluate();
+
+        if ($regime === null) {
+            $this->info('Volatility regime: OFF');
+        } else {
+            $this->info(sprintf(
+                'Volatility regime: ON (trigger=%s, since %s)',
+                $regime->trigger,
+                $regime->flipped_on_at->toIso8601String(),
+            ));
+        }
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/ImportBeisFuelPrices.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\Forecasting\BeisImporter;
+use Illuminate\Console\Attributes\Description;
+use Illuminate\Console\Attributes\Signature;
+use Illuminate\Console\Command;
+use Throwable;
+
+#[Signature('beis:import')]
+#[Description('Pull the latest gov.uk Weekly road fuel prices CSV and upsert into weekly_pump_prices.')]
+class ImportBeisFuelPrices extends Command
+{
+    public function handle(BeisImporter $importer): int
+    {
+        try {
+            $result = $importer->import();
+        } catch (Throwable $e) {
+            $this->error('BEIS import failed: '.$e->getMessage());
+
+            return self::FAILURE;
+        }
+
+        $this->info(sprintf(
+            'Imported %d rows from %s — latest date: %s.',
+            $result['parsed'],
+            $result['csv_url'],
+            $result['latest_date'],
+        ));
+        $this->info('Forecast cache flushed; next API hit will retrain on the new row.');
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/PredictOilPrices.php

@@ -1,58 +0,0 @@
-<?php
-
-namespace App\Console\Commands;
-
-use App\Services\BrentPricePredictor;
-use Illuminate\Console\Command;
-use Throwable;
-
-class PredictOilPrices extends Command
-{
-    protected $signature = 'oil:predict {--force : Generate even if the latest price already has a prediction}';
-
-    protected $description = 'Generate a Brent crude oil price direction prediction';
-
-    public function handle(BrentPricePredictor $predictor): int
-    {
-        try {
-            $latest = $predictor->latestPrice();
-
-            if ($latest?->prediction_generated_at !== null && ! $this->option('force')) {
-                $message = sprintf(
-                    'Prediction already generated for %s at %s.',
-                    $latest->date->toDateString(),
-                    $latest->prediction_generated_at->toDateTimeString(),
-                );
-
-                if (! $this->confirm($message.' Run again anyway?', default: false)) {
-                    $this->info('Skipped.');
-
-                    return self::SUCCESS;
-                }
-            }
-
-            $this->info('Generating prediction...');
-            $prediction = $predictor->generatePrediction();
-
-            if ($prediction === null) {
-                $this->error('Could not generate a prediction — not enough price data.');
-
-                return self::FAILURE;
-            }
-
-            $this->info(sprintf(
-                'Done. [%s] direction=%s confidence=%d%% — %s',
-                strtoupper($prediction->source->value),
-                $prediction->direction->value,
-                $prediction->confidence,
-                $prediction->reasoning,
-            ));
-        } catch (Throwable $e) {
-            $this->error("Prediction failed: {$e->getMessage()}");
-
-            return self::FAILURE;
-        }
-
-        return self::SUCCESS;
-    }
-}

app/Console/Commands/ResolveForecastOutcomes.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\Forecasting\OutcomeResolver;
+use Illuminate\Console\Attributes\Description;
+use Illuminate\Console\Attributes\Signature;
+use Illuminate\Console\Command;
+
+#[Signature('forecast:resolve-outcomes')]
+#[Description('Pair past weekly forecasts with the actual ULSP from BEIS data and write rows to forecast_outcomes.')]
+class ResolveForecastOutcomes extends Command
+{
+    public function handle(OutcomeResolver $resolver): int
+    {
+        $count = $resolver->resolvePending();
+        $this->info(sprintf('Resolved %d outstanding forecast(s).', $count));
+
+        return self::SUCCESS;
+    }
+}

app/Console/Commands/RunLlmOverlay.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\Forecasting\LlmOverlayService;
+use Illuminate\Console\Attributes\Description;
+use Illuminate\Console\Attributes\Signature;
+use Illuminate\Console\Command;
+
+#[Signature('forecast:llm-overlay {--event-driven : Honor the 4h cooldown (default: false; daily 07:00 cron always runs)}')]
+#[Description('Run the daily Anthropic web-search overlay on the current weekly forecast.')]
+class RunLlmOverlay extends Command
+{
+    public function handle(LlmOverlayService $service): int
+    {
+        $row = $service->run(eventDriven: (bool) $this->option('event-driven'));
+
+        if ($row === null) {
+            $this->warn('LLM overlay skipped (no API key, on cooldown, or rejected for empty citations).');
+
+            return self::SUCCESS;
+        }
+
+        $this->info(sprintf(
+            'Stored llm_overlays #%d — direction=%s confidence=%d major_impact=%s.',
+            $row->id,
+            $row->direction,
+            $row->confidence,
+            $row->major_impact_event ? 'YES' : 'no',
+        ));
+
+        return self::SUCCESS;
+    }
+}

app/Filament/NavigationGroup.php

@@ -13,6 +13,8 @@ enum NavigationGroup implements HasIcon, HasLabel
 
     case Data;
 
+    case Forecasting;
+
     case System;
 
     public function getLabel(): string
@@ -20,6 +22,7 @@ enum NavigationGroup implements HasIcon, HasLabel
         return match ($this) {
             self::Users => 'Users',
             self::Data => 'Data',
+            self::Forecasting => 'Forecasting',
             self::System => 'System',
         };
     }
@@ -29,6 +32,7 @@ enum NavigationGroup implements HasIcon, HasLabel
         return match ($this) {
             self::Users => 'heroicon-o-users',
             self::Data => 'heroicon-o-circle-stack',
+            self::Forecasting => null,
             self::System => 'heroicon-o-cog-6-tooth',
         };
     }

app/Filament/Resources/Backtests/BacktestResource.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Filament\Resources\Backtests;
+
+use App\Filament\NavigationGroup;
+use App\Filament\Resources\Backtests\Pages\ListBacktests;
+use App\Filament\Resources\Backtests\Pages\ViewBacktest;
+use App\Filament\Resources\Backtests\Schemas\BacktestInfolist;
+use App\Filament\Resources\Backtests\Tables\BacktestsTable;
+use App\Models\Backtest;
+use BackedEnum;
+use Filament\Resources\Resource;
+use Filament\Schemas\Schema;
+use Filament\Support\Icons\Heroicon;
+use Filament\Tables\Table;
+use Illuminate\Database\Eloquent\Model;
+
+class BacktestResource extends Resource
+{
+    protected static ?string $model = Backtest::class;
+
+    protected static string|BackedEnum|null $navigationIcon = Heroicon::OutlinedBeaker;
+
+    protected static string|\UnitEnum|null $navigationGroup = NavigationGroup::Forecasting;
+
+    protected static ?string $navigationLabel = 'Backtests';
+
+    protected static ?int $navigationSort = 3;
+
+    public static function infolist(Schema $schema): Schema
+    {
+        return BacktestInfolist::configure($schema);
+    }
+
+    public static function table(Table $table): Table
+    {
+        return BacktestsTable::configure($table);
+    }
+
+    public static function canCreate(): bool
+    {
+        return false;
+    }
+
+    public static function canEdit(Model $record): bool
+    {
+        return false;
+    }
+
+    public static function canDelete(Model $record): bool
+    {
+        return false;
+    }
+
+    public static function getPages(): array
+    {
+        return [
+            'index' => ListBacktests::route('/'),
+            'view' => ViewBacktest::route('/{record}'),
+        ];
+    }
+}

app/Filament/Resources/Backtests/Pages/ListBacktests.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Filament\Resources\Backtests\Pages;
+
+use App\Filament\Resources\Backtests\BacktestResource;
+use Filament\Resources\Pages\ListRecords;
+
+class ListBacktests extends ListRecords
+{
+    protected static string $resource = BacktestResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [];
+    }
+}

app/Filament/Resources/Backtests/Pages/ViewBacktest.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Filament\Resources\Backtests\Pages;
+
+use App\Filament\Resources\Backtests\BacktestResource;
+use Filament\Resources\Pages\ViewRecord;
+
+class ViewBacktest extends ViewRecord
+{
+    protected static string $resource = BacktestResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [];
+    }
+}

app/Filament/Resources/Backtests/Schemas/BacktestInfolist.php

@@ -0,0 +1,89 @@
+<?php
+
+namespace App\Filament\Resources\Backtests\Schemas;
+
+use App\Models\Backtest;
+use Filament\Infolists\Components\IconEntry;
+use Filament\Infolists\Components\KeyValueEntry;
+use Filament\Infolists\Components\TextEntry;
+use Filament\Schemas\Components\Section;
+use Filament\Schemas\Schema;
+
+class BacktestInfolist
+{
+    public static function configure(Schema $schema): Schema
+    {
+        return $schema->components([
+            Section::make('Run')->columns(3)->schema([
+                TextEntry::make('model_version')->columnSpanFull(),
+                TextEntry::make('directional_accuracy')
+                    ->label('Accuracy')
+                    ->state(fn (Backtest $record): string => $record->directional_accuracy === null
+                        ? '—'
+                        : round((float) $record->directional_accuracy, 1).'%'),
+                TextEntry::make('mae_pence')
+                    ->label('MAE')
+                    ->state(fn (Backtest $record): string => $record->mae_pence === null
+                        ? '—'
+                        : number_format((float) $record->mae_pence, 2).'p'),
+                IconEntry::make('leak_suspected')
+                    ->label('Leak suspected')
+                    ->boolean()
+                    ->trueColor('danger'),
+                TextEntry::make('train_start')->date('d M Y'),
+                TextEntry::make('train_end')->date('d M Y'),
+                TextEntry::make('eval_start')->date('d M Y'),
+                TextEntry::make('eval_end')->date('d M Y'),
+                TextEntry::make('ran_at')->dateTime('d M Y H:i'),
+            ]),
+            Section::make('Calibration table')
+                ->description('Empirical hit rate per magnitude bin from the eval window.')
+                ->schema([
+                    KeyValueEntry::make('calibration_table')
+                        ->hiddenLabel()
+                        ->keyLabel('Magnitude bin')
+                        ->valueLabel('Empirical hit rate')
+                        ->state(fn (Backtest $record): array => collect($record->calibration_table ?? [])
+                            ->mapWithKeys(fn ($value, $key) => [$key => round((float) $value * 100, 1).'%'])
+                            ->all())
+                        ->columnSpanFull(),
+                ]),
+            Section::make('Feature spec')->schema([
+                KeyValueEntry::make('features_json')
+                    ->hiddenLabel()
+                    ->state(fn (Backtest $record): array => self::flattenForKeyValue($record->features_json))
+                    ->columnSpanFull(),
+            ]),
+            Section::make('Coefficients')
+                ->visible(fn (Backtest $record) => $record->coefficients_json !== null)
+                ->collapsed()
+                ->schema([
+                    TextEntry::make('coefficients_json')
+                        ->hiddenLabel()
+                        ->state(fn (Backtest $record): string => json_encode(
+                            $record->coefficients_json,
+                            JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES
+                        ) ?: '')
+                        ->columnSpanFull(),
+                ]),
+        ]);
+    }
+
+    /**
+     * KeyValueEntry expects a flat string-keyed map, so collapse nested arrays
+     * into JSON strings rather than dropping them.
+     *
+     * @param  array<string, mixed>|null  $features
+     * @return array<string, string>
+     */
+    protected static function flattenForKeyValue(?array $features): array
+    {
+        return collect($features ?? [])
+            ->mapWithKeys(fn ($value, $key) => [
+                (string) $key => is_scalar($value)
+                    ? (string) $value
+                    : (json_encode($value, JSON_UNESCAPED_SLASHES) ?: ''),
+            ])
+            ->all();
+    }
+}

app/Filament/Resources/Backtests/Tables/BacktestsTable.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace App\Filament\Resources\Backtests\Tables;
+
+use App\Models\Backtest;
+use Filament\Actions\ViewAction;
+use Filament\Tables\Columns\IconColumn;
+use Filament\Tables\Columns\TextColumn;
+use Filament\Tables\Filters\Filter;
+use Filament\Tables\Table;
+use Illuminate\Database\Eloquent\Builder;
+
+class BacktestsTable
+{
+    public static function configure(Table $table): Table
+    {
+        return $table
+            ->columns([
+                TextColumn::make('model_version')
+                    ->searchable()
+                    ->limit(32)
+                    ->tooltip(fn (Backtest $record) => strlen($record->model_version) > 32 ? $record->model_version : null),
+                TextColumn::make('directional_accuracy')
+                    ->label('Accuracy')
+                    ->state(fn (Backtest $record): string => $record->directional_accuracy === null
+                        ? '—'
+                        : round((float) $record->directional_accuracy, 1).'%')
+                    ->color(fn (Backtest $record) => self::accuracyColor($record))
+                    ->sortable(),
+                TextColumn::make('mae_pence')
+                    ->label('MAE')
+                    ->state(fn (Backtest $record): string => $record->mae_pence === null
+                        ? '—'
+                        : number_format((float) $record->mae_pence, 2).'p')
+                    ->sortable(),
+                IconColumn::make('leak_suspected')
+                    ->label('Leak?')
+                    ->boolean()
+                    ->trueColor('danger'),
+                TextColumn::make('eval_start')
+                    ->date('d M Y')
+                    ->sortable()
+                    ->toggleable(isToggledHiddenByDefault: true),
+                TextColumn::make('eval_end')
+                    ->date('d M Y')
+                    ->sortable()
+                    ->toggleable(isToggledHiddenByDefault: true),
+                TextColumn::make('ran_at')
+                    ->dateTime('d M Y H:i')
+                    ->sortable(),
+            ])
+            ->defaultSort('ran_at', 'desc')
+            ->filters([
+                Filter::make('leak_suspected')
+                    ->label('Suspicious accuracy (leak suspected)')
+                    ->toggle()
+                    ->query(fn (Builder $query) => $query->where('leak_suspected', true)),
+                Filter::make('below_ship_gate')
+                    ->label('Below ship gate')
+                    ->toggle()
+                    ->query(fn (Builder $query) => $query->where('directional_accuracy', '<', 62)),
+            ])
+            ->recordActions([
+                ViewAction::make(),
+            ]);
+    }
+
+    protected static function accuracyColor(Backtest $record): ?string
+    {
+        if ($record->directional_accuracy === null) {
+            return null;
+        }
+
+        $accuracy = (float) $record->directional_accuracy;
+
+        if ($accuracy > 75 && $record->leak_suspected) {
+            return 'danger';
+        }
+
+        if ($accuracy < 60) {
+            return 'danger';
+        }
+
+        if ($accuracy < 62) {
+            return 'warning';
+        }
+
+        if ($accuracy <= 75) {
+            return 'success';
+        }
+
+        return null;
+    }
+}

app/Filament/Resources/OilPredictionResource.php

@@ -1,141 +0,0 @@
-<?php
-
-namespace App\Filament\Resources;
-
-use App\Enums\PredictionSource;
-use App\Enums\TrendDirection;
-use App\Filament\NavigationGroup;
-use App\Filament\Resources\OilPredictionResource\Pages\ListOilPredictions;
-use App\Filament\Resources\OilPredictionResource\Pages\ViewOilPrediction;
-use App\Models\PricePrediction;
-use Filament\Actions\ViewAction;
-use Filament\Forms\Components\DatePicker;
-use Filament\Infolists\Components\TextEntry;
-use Filament\Resources\Resource;
-use Filament\Schemas\Components\Section;
-use Filament\Schemas\Schema;
-use Filament\Tables\Columns\TextColumn;
-use Filament\Tables\Filters\Filter;
-use Filament\Tables\Filters\SelectFilter;
-use Filament\Tables\Table;
-use Illuminate\Database\Eloquent\Builder;
-
-class OilPredictionResource extends Resource
-{
-    protected static ?string $model = PricePrediction::class;
-
-    protected static string|\UnitEnum|null $navigationGroup = NavigationGroup::Data;
-
-    protected static ?string $navigationLabel = 'Oil Predictions';
-
-    protected static ?int $navigationSort = 3;
-
-    public static function table(Table $table): Table
-    {
-        return $table
-            ->columns([
-                TextColumn::make('predicted_for')
-                    ->date('d M Y')
-                    ->sortable(),
-                TextColumn::make('source')
-                    ->badge()
-                    ->formatStateUsing(fn (PredictionSource $state) => match ($state) {
-                        PredictionSource::Llm => 'LLM',
-                        PredictionSource::LlmWithContext => 'LLM + Context',
-                        PredictionSource::Ewma => 'EWMA',
-                    })
-                    ->color(fn (PredictionSource $state) => match ($state) {
-                        PredictionSource::Llm => 'success',
-                        PredictionSource::LlmWithContext => 'warning',
-                        PredictionSource::Ewma => 'info',
-                    }),
-                TextColumn::make('direction')
-                    ->badge()
-                    ->color(fn (TrendDirection $state) => match ($state) {
-                        TrendDirection::Rising => 'danger',
-                        TrendDirection::Falling => 'success',
-                        TrendDirection::Flat => 'gray',
-                    }),
-                TextColumn::make('confidence')
-                    ->suffix('%')
-                    ->sortable(),
-                TextColumn::make('reasoning')
-                    ->limit(60)
-                    ->placeholder('—'),
-                TextColumn::make('generated_at')
-                    ->dateTime('d M Y H:i')
-                    ->sortable(),
-            ])
-            ->defaultSort('predicted_for', 'desc')
-            ->filters([
-                SelectFilter::make('source')
-                    ->options([
-                        PredictionSource::Llm->value => 'LLM',
-                        PredictionSource::LlmWithContext->value => 'LLM + Context',
-                        PredictionSource::Ewma->value => 'EWMA',
-                    ]),
-                SelectFilter::make('direction')
-                    ->options([
-                        TrendDirection::Rising->value => 'Rising',
-                        TrendDirection::Falling->value => 'Falling',
-                        TrendDirection::Flat->value => 'Flat',
-                    ]),
-                Filter::make('predicted_for')
-                    ->schema([
-                        DatePicker::make('from')->label('From'),
-                        DatePicker::make('until')->label('Until'),
-                    ])
-                    ->query(function (Builder $query, array $data) {
-                        $query
-                            ->when($data['from'], fn ($q, $d) => $q->whereDate('predicted_for', '>=', $d))
-                            ->when($data['until'], fn ($q, $d) => $q->whereDate('predicted_for', '<=', $d));
-                    }),
-            ])
-            ->recordActions([
-                ViewAction::make(),
-            ]);
-    }
-
-    public static function infolist(Schema $schema): Schema
-    {
-        return $schema->components([
-            Section::make('Prediction')->schema([
-                TextEntry::make('predicted_for')->date('d M Y'),
-                TextEntry::make('source')
-                    ->badge()
-                    ->formatStateUsing(fn (PredictionSource $state) => match ($state) {
-                        PredictionSource::Llm => 'LLM',
-                        PredictionSource::LlmWithContext => 'LLM + Context',
-                        PredictionSource::Ewma => 'EWMA',
-                    })
-                    ->color(fn (PredictionSource $state) => match ($state) {
-                        PredictionSource::Llm => 'success',
-                        PredictionSource::LlmWithContext => 'warning',
-                        PredictionSource::Ewma => 'info',
-                    }),
-                TextEntry::make('direction')
-                    ->badge()
-                    ->color(fn (TrendDirection $state) => match ($state) {
-                        TrendDirection::Rising => 'danger',
-                        TrendDirection::Falling => 'success',
-                        TrendDirection::Flat => 'gray',
-                    }),
-                TextEntry::make('confidence')->suffix('%'),
-                TextEntry::make('generated_at')->dateTime('d M Y H:i:s'),
-            ])->columns(3),
-            Section::make('Reasoning')->schema([
-                TextEntry::make('reasoning')
-                    ->columnSpanFull()
-                    ->placeholder('No reasoning recorded'),
-            ]),
-        ]);
-    }
-
-    public static function getPages(): array
-    {
-        return [
-            'index' => ListOilPredictions::route('/'),
-            'view' => ViewOilPrediction::route('/{record}'),
-        ];
-    }
-}

app/Filament/Resources/OilPredictionResource/Pages/ListOilPredictions.php

@@ -1,42 +0,0 @@
-<?php
-
-namespace App\Filament\Resources\OilPredictionResource\Pages;
-
-use App\Filament\Resources\OilPredictionResource;
-use Filament\Actions\Action;
-use Filament\Notifications\Notification;
-use Filament\Resources\Pages\ListRecords;
-use Illuminate\Support\Facades\Artisan;
-
-class ListOilPredictions extends ListRecords
-{
-    protected static string $resource = OilPredictionResource::class;
-
-    protected function getHeaderActions(): array
-    {
-        return [
-            Action::make('runPrediction')
-                ->label('Run Prediction Now')
-                ->icon('heroicon-o-cpu-chip')
-                ->requiresConfirmation()
-                ->modalHeading('Run oil price prediction?')
-                ->modalDescription('Generates a new prediction from the stored Brent prices. Runs even if a prediction already exists for the latest price.')
-                ->action(function () {
-                    $result = Artisan::call('oil:predict', ['--force' => true]);
-
-                    if ($result === 0) {
-                        Notification::make()
-                            ->title('Prediction generated successfully')
-                            ->success()
-                            ->send();
-                    } else {
-                        Notification::make()
-                            ->title('Prediction failed')
-                            ->body('Check API Logs for details.')
-                            ->danger()
-                            ->send();
-                    }
-                }),
-        ];
-    }
-}

app/Filament/Resources/OilPredictionResource/Pages/ViewOilPrediction.php

@@ -1,16 +0,0 @@
-<?php
-
-namespace App\Filament\Resources\OilPredictionResource\Pages;
-
-use App\Filament\Resources\OilPredictionResource;
-use Filament\Resources\Pages\ViewRecord;
-
-class ViewOilPrediction extends ViewRecord
-{
-    protected static string $resource = OilPredictionResource::class;
-
-    protected function getHeaderActions(): array
-    {
-        return [];
-    }
-}

app/Filament/Resources/WatchedEvents/Pages/CreateWatchedEvent.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace App\Filament\Resources\WatchedEvents\Pages;
+
+use App\Filament\Resources\WatchedEvents\WatchedEventResource;
+use Filament\Resources\Pages\CreateRecord;
+
+class CreateWatchedEvent extends CreateRecord
+{
+    protected static string $resource = WatchedEventResource::class;
+}

app/Filament/Resources/WatchedEvents/Pages/EditWatchedEvent.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace App\Filament\Resources\WatchedEvents\Pages;
+
+use App\Filament\Resources\WatchedEvents\WatchedEventResource;
+use Filament\Actions\DeleteAction;
+use Filament\Resources\Pages\EditRecord;
+
+class EditWatchedEvent extends EditRecord
+{
+    protected static string $resource = WatchedEventResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [
+            DeleteAction::make(),
+        ];
+    }
+}

app/Filament/Resources/WatchedEvents/Pages/ListWatchedEvents.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace App\Filament\Resources\WatchedEvents\Pages;
+
+use App\Filament\Resources\WatchedEvents\WatchedEventResource;
+use Filament\Actions\CreateAction;
+use Filament\Resources\Pages\ListRecords;
+
+class ListWatchedEvents extends ListRecords
+{
+    protected static string $resource = WatchedEventResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [
+            CreateAction::make(),
+        ];
+    }
+}

app/Filament/Resources/WatchedEvents/Schemas/WatchedEventForm.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Filament\Resources\WatchedEvents\Schemas;
+
+use Filament\Forms\Components\DateTimePicker;
+use Filament\Forms\Components\Textarea;
+use Filament\Forms\Components\TextInput;
+use Filament\Schemas\Schema;
+
+class WatchedEventForm
+{
+    public static function configure(Schema $schema): Schema
+    {
+        return $schema->components([
+            TextInput::make('label')
+                ->required()
+                ->maxLength(128)
+                ->helperText('Short geopolitical event label, e.g. "Iran tensions Apr–May 2026".'),
+            DateTimePicker::make('starts_at')
+                ->label('Starts at')
+                ->required(),
+            DateTimePicker::make('ends_at')
+                ->label('Ends at')
+                ->required()
+                ->after('starts_at'),
+            Textarea::make('notes')
+                ->maxLength(2000)
+                ->rows(4)
+                ->columnSpanFull(),
+        ]);
+    }
+}

app/Filament/Resources/WatchedEvents/Tables/WatchedEventsTable.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace App\Filament\Resources\WatchedEvents\Tables;
+
+use App\Models\WatchedEvent;
+use Filament\Actions\BulkActionGroup;
+use Filament\Actions\DeleteAction;
+use Filament\Actions\DeleteBulkAction;
+use Filament\Actions\EditAction;
+use Filament\Tables\Columns\TextColumn;
+use Filament\Tables\Filters\Filter;
+use Filament\Tables\Table;
+use Illuminate\Database\Eloquent\Builder;
+
+class WatchedEventsTable
+{
+    public static function configure(Table $table): Table
+    {
+        return $table
+            ->columns([
+                TextColumn::make('label')
+                    ->searchable()
+                    ->sortable()
+                    ->limit(60)
+                    ->tooltip(fn (WatchedEvent $record) => strlen($record->label) > 60 ? $record->label : null),
+                TextColumn::make('starts_at')
+                    ->dateTime('d M Y H:i')
+                    ->sortable(),
+                TextColumn::make('ends_at')
+                    ->dateTime('d M Y H:i')
+                    ->sortable(),
+                TextColumn::make('status')
+                    ->label('Status')
+                    ->badge()
+                    ->state(fn (WatchedEvent $record): string => self::isActive($record) ? 'Active' : 'Inactive')
+                    ->color(fn (string $state) => $state === 'Active' ? 'success' : 'gray'),
+                TextColumn::make('notes')
+                    ->limit(50)
+                    ->placeholder('—')
+                    ->toggleable(isToggledHiddenByDefault: true),
+            ])
+            ->defaultSort('starts_at', 'desc')
+            ->filters([
+                Filter::make('currently_active')
+                    ->label('Currently active')
+                    ->toggle()
+                    ->query(fn (Builder $query) => $query
+                        ->where('starts_at', '<=', now())
+                        ->where('ends_at', '>=', now())),
+            ])
+            ->recordActions([
+                EditAction::make(),
+                DeleteAction::make(),
+            ])
+            ->toolbarActions([
+                BulkActionGroup::make([
+                    DeleteBulkAction::make(),
+                ]),
+            ]);
+    }
+
+    protected static function isActive(WatchedEvent $record): bool
+    {
+        $now = now();
+
+        return $record->starts_at !== null
+            && $record->ends_at !== null
+            && $record->starts_at->lessThanOrEqualTo($now)
+            && $record->ends_at->greaterThanOrEqualTo($now);
+    }
+}

app/Filament/Resources/WatchedEvents/WatchedEventResource.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace App\Filament\Resources\WatchedEvents;
+
+use App\Filament\NavigationGroup;
+use App\Filament\Resources\WatchedEvents\Pages\CreateWatchedEvent;
+use App\Filament\Resources\WatchedEvents\Pages\EditWatchedEvent;
+use App\Filament\Resources\WatchedEvents\Pages\ListWatchedEvents;
+use App\Filament\Resources\WatchedEvents\Schemas\WatchedEventForm;
+use App\Filament\Resources\WatchedEvents\Tables\WatchedEventsTable;
+use App\Models\WatchedEvent;
+use BackedEnum;
+use Filament\Resources\Resource;
+use Filament\Schemas\Schema;
+use Filament\Support\Icons\Heroicon;
+use Filament\Tables\Table;
+
+class WatchedEventResource extends Resource
+{
+    protected static ?string $model = WatchedEvent::class;
+
+    protected static string|BackedEnum|null $navigationIcon = Heroicon::OutlinedFlag;
+
+    protected static string|\UnitEnum|null $navigationGroup = NavigationGroup::Forecasting;
+
+    protected static ?string $navigationLabel = 'Watched Events';
+
+    protected static ?int $navigationSort = 1;
+
+    public static function form(Schema $schema): Schema
+    {
+        return WatchedEventForm::configure($schema);
+    }
+
+    public static function table(Table $table): Table
+    {
+        return WatchedEventsTable::configure($table);
+    }
+
+    public static function getPages(): array
+    {
+        return [
+            'index' => ListWatchedEvents::route('/'),
+            'create' => CreateWatchedEvent::route('/create'),
+            'edit' => EditWatchedEvent::route('/{record}/edit'),
+        ];
+    }
+}

app/Filament/Resources/WeeklyForecasts/Pages/ListWeeklyForecasts.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Filament\Resources\WeeklyForecasts\Pages;
+
+use App\Filament\Resources\WeeklyForecasts\WeeklyForecastResource;
+use Filament\Resources\Pages\ListRecords;
+
+class ListWeeklyForecasts extends ListRecords
+{
+    protected static string $resource = WeeklyForecastResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [];
+    }
+}

app/Filament/Resources/WeeklyForecasts/Pages/ViewWeeklyForecast.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Filament\Resources\WeeklyForecasts\Pages;
+
+use App\Filament\Resources\WeeklyForecasts\WeeklyForecastResource;
+use Filament\Resources\Pages\ViewRecord;
+
+class ViewWeeklyForecast extends ViewRecord
+{
+    protected static string $resource = WeeklyForecastResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [];
+    }
+}

app/Filament/Resources/WeeklyForecasts/Schemas/WeeklyForecastInfolist.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Filament\Resources\WeeklyForecasts\Schemas;
+
+use App\Models\WeeklyForecast;
+use Filament\Infolists\Components\IconEntry;
+use Filament\Infolists\Components\TextEntry;
+use Filament\Schemas\Components\Section;
+use Filament\Schemas\Schema;
+
+class WeeklyForecastInfolist
+{
+    public static function configure(Schema $schema): Schema
+    {
+        return $schema->components([
+            Section::make('Forecast')->columns(3)->schema([
+                TextEntry::make('forecast_for')->date('d M Y'),
+                TextEntry::make('direction')
+                    ->badge()
+                    ->color(fn (string $state) => match ($state) {
+                        'rising' => 'warning',
+                        'falling' => 'success',
+                        default => 'gray',
+                    }),
+                TextEntry::make('magnitude_pence')
+                    ->label('Magnitude')
+                    ->state(fn (WeeklyForecast $record): string => self::formatMagnitude($record->magnitude_pence)),
+                TextEntry::make('ridge_confidence')
+                    ->label('Confidence')
+                    ->state(fn (WeeklyForecast $record): string => $record->ridge_confidence.'%')
+                    ->color(fn (WeeklyForecast $record) => $record->ridge_confidence < 40 ? 'warning' : null),
+                IconEntry::make('flagged_duty_change')
+                    ->label('Duty change adjacent')
+                    ->boolean()
+                    ->trueColor('warning'),
+                TextEntry::make('generated_at')->dateTime('d M Y H:i'),
+            ]),
+            Section::make('Reasoning')->schema([
+                TextEntry::make('reasoning')
+                    ->columnSpanFull()
+                    ->placeholder('No reasoning recorded.'),
+            ]),
+            Section::make('Model')
+                ->description('Calibration table from the matching backtest determines the displayed confidence.')
+                ->schema([
+                    TextEntry::make('model_version')->columnSpanFull(),
+                ]),
+        ]);
+    }
+
+    protected static function formatMagnitude(?int $magnitudePence): string
+    {
+        if ($magnitudePence === null) {
+            return '—';
+        }
+
+        $pence = round($magnitudePence / 100, 1);
+        $sign = $pence > 0 ? '+' : '';
+
+        return $sign.$pence.'p';
+    }
+}

app/Filament/Resources/WeeklyForecasts/Tables/WeeklyForecastsTable.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace App\Filament\Resources\WeeklyForecasts\Tables;
+
+use App\Models\WeeklyForecast;
+use Filament\Actions\ViewAction;
+use Filament\Tables\Columns\IconColumn;
+use Filament\Tables\Columns\TextColumn;
+use Filament\Tables\Filters\Filter;
+use Filament\Tables\Filters\SelectFilter;
+use Filament\Tables\Table;
+use Illuminate\Database\Eloquent\Builder;
+
+class WeeklyForecastsTable
+{
+    public static function configure(Table $table): Table
+    {
+        return $table
+            ->columns([
+                TextColumn::make('forecast_for')
+                    ->label('Forecast for')
+                    ->date('d M Y')
+                    ->sortable(),
+                TextColumn::make('direction')
+                    ->badge()
+                    ->color(fn (string $state) => match ($state) {
+                        'rising' => 'warning',
+                        'falling' => 'success',
+                        default => 'gray',
+                    }),
+                TextColumn::make('magnitude_pence')
+                    ->label('Magnitude')
+                    ->state(fn (WeeklyForecast $record): string => self::formatMagnitude($record->magnitude_pence))
+                    ->sortable(),
+                TextColumn::make('ridge_confidence')
+                    ->label('Confidence')
+                    ->state(fn (WeeklyForecast $record): string => $record->ridge_confidence.'%')
+                    ->color(fn (WeeklyForecast $record) => $record->ridge_confidence < 40 ? 'warning' : null)
+                    ->sortable(),
+                IconColumn::make('flagged_duty_change')
+                    ->label('Duty change')
+                    ->boolean()
+                    ->trueColor('warning'),
+                TextColumn::make('model_version')
+                    ->searchable()
+                    ->limit(32)
+                    ->toggleable(isToggledHiddenByDefault: true),
+                TextColumn::make('generated_at')
+                    ->dateTime('d M Y H:i')
+                    ->sortable()
+                    ->toggleable(isToggledHiddenByDefault: true),
+            ])
+            ->defaultSort('forecast_for', 'desc')
+            ->filters([
+                SelectFilter::make('direction')
+                    ->multiple()
+                    ->options([
+                        'rising' => 'Rising',
+                        'falling' => 'Falling',
+                        'flat' => 'Flat',
+                    ]),
+                Filter::make('high_confidence')
+                    ->label('High confidence')
+                    ->toggle()
+                    ->query(fn (Builder $query) => $query->where('ridge_confidence', '>=', 70)),
+                Filter::make('flagged_duty_change')
+                    ->label('Duty-change-adjacent')
+                    ->toggle()
+                    ->query(fn (Builder $query) => $query->where('flagged_duty_change', true)),
+            ])
+            ->recordActions([
+                ViewAction::make(),
+            ]);
+    }
+
+    protected static function formatMagnitude(?int $magnitudePence): string
+    {
+        if ($magnitudePence === null) {
+            return '—';
+        }
+
+        $pence = round($magnitudePence / 100, 1);
+        $sign = $pence > 0 ? '+' : '';
+
+        return $sign.$pence.'p';
+    }
+}

app/Filament/Resources/WeeklyForecasts/WeeklyForecastResource.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Filament\Resources\WeeklyForecasts;
+
+use App\Filament\NavigationGroup;
+use App\Filament\Resources\WeeklyForecasts\Pages\ListWeeklyForecasts;
+use App\Filament\Resources\WeeklyForecasts\Pages\ViewWeeklyForecast;
+use App\Filament\Resources\WeeklyForecasts\Schemas\WeeklyForecastInfolist;
+use App\Filament\Resources\WeeklyForecasts\Tables\WeeklyForecastsTable;
+use App\Models\WeeklyForecast;
+use BackedEnum;
+use Filament\Resources\Resource;
+use Filament\Schemas\Schema;
+use Filament\Support\Icons\Heroicon;
+use Filament\Tables\Table;
+use Illuminate\Database\Eloquent\Model;
+
+class WeeklyForecastResource extends Resource
+{
+    protected static ?string $model = WeeklyForecast::class;
+
+    protected static string|BackedEnum|null $navigationIcon = Heroicon::OutlinedChartBar;
+
+    protected static string|\UnitEnum|null $navigationGroup = NavigationGroup::Forecasting;
+
+    protected static ?string $navigationLabel = 'Weekly Forecasts';
+
+    protected static ?int $navigationSort = 2;
+
+    public static function infolist(Schema $schema): Schema
+    {
+        return WeeklyForecastInfolist::configure($schema);
+    }
+
+    public static function table(Table $table): Table
+    {
+        return WeeklyForecastsTable::configure($table);
+    }
+
+    public static function canCreate(): bool
+    {
+        return false;
+    }
+
+    public static function canEdit(Model $record): bool
+    {
+        return false;
+    }
+
+    public static function canDelete(Model $record): bool
+    {
+        return false;
+    }
+
+    public static function getPages(): array
+    {
+        return [
+            'index' => ListWeeklyForecasts::route('/'),
+            'view' => ViewWeeklyForecast::route('/{record}'),
+        ];
+    }
+}

app/Filament/Widgets/StatsOverviewWidget.php

@@ -3,10 +3,10 @@
 namespace App\Filament\Widgets;
 
 use App\Models\ApiLog;
-use App\Models\PricePrediction;
 use App\Models\Search;
 use App\Models\Station;
 use App\Models\User;
+use App\Models\WeeklyForecast;
 use Carbon\Carbon;
 use Filament\Widgets\StatsOverviewWidget as BaseWidget;
 use Filament\Widgets\StatsOverviewWidget\Stat;
@@ -21,7 +21,7 @@ class StatsOverviewWidget extends BaseWidget
             $this->usersStat(),
             $this->searchesStat(),
             $this->stationsStat(),
-            $this->oilPredictionStat(),
+            $this->weeklyForecastStat(),
             $this->apiErrorsStat(),
         ];
     }
@@ -56,23 +56,23 @@ class StatsOverviewWidget extends BaseWidget
             ->color('success');
     }
 
-    private function oilPredictionStat(): Stat
+    private function weeklyForecastStat(): Stat
     {
-        $prediction = PricePrediction::bestFirst()->latest('generated_at')->first();
+        $forecast = WeeklyForecast::query()->latest('generated_at')->first();
 
-        if ($prediction === null) {
+        if ($forecast === null) {
-            return Stat::make('Latest oil prediction', 'None')
+            return Stat::make('Latest weekly forecast', 'None')
                 ->icon('heroicon-o-beaker')
                 ->color('gray');
         }
 
-        $ageHours = $prediction->generated_at->diffInHours(now());
+        $ageHours = $forecast->generated_at->diffInHours(now());
-        $color = $ageHours > 24 ? 'warning' : 'success';
+        $color = $ageHours > 168 ? 'warning' : 'success'; // weekly forecast → stale after a week
-        $value = $prediction->direction->label().' · '.$prediction->confidence.'%';
+        $directionLabel = ucfirst($forecast->direction);
+        $value = $directionLabel.' · '.$forecast->ridge_confidence.'%';
 
-        return Stat::make('Latest oil prediction', $value)
+        return Stat::make('Latest weekly forecast', $value)
-            ->description('Generated '.$prediction->generated_at->diffForHumans())
+            ->description('For week of '.$forecast->forecast_for->toDateString())
-            ->url(route('filament.admin.resources.oil-predictions.index'))
             ->icon('heroicon-o-beaker')
             ->color($color);
     }

app/Http/Controllers/Api/AuthController.php

@@ -64,19 +64,24 @@ class AuthController extends Controller
     public function me(Request $request): JsonResponse
     {
         $user = $request->user();
+
+        if ($user === null) {
+            return new JsonResponse('null', json: true);
+        }
+
         $subscription = $user->subscription();
 
         $expiresAt = $subscription?->ends_at ?? $subscription?->current_period_end;
 
-        return response()->json(array_merge(
+        return response()->json([
-            $user->toArray(),
+            'name' => $user->name,
-            [
+            'email' => $user->email,
-                'tier' => PlanFeatures::for($user)->tier(),
+            'two_factor_confirmed_at' => $user->two_factor_confirmed_at?->toIso8601String(),
-                'subscription_cancelled' => $subscription?->canceled() ?? false,
+            'tier' => PlanFeatures::for($user)->tier(),
-                'subscription_cadence' => Plan::resolveCadenceForUser($user),
+            'subscription_cancelled' => $subscription?->canceled() ?? false,
-                'subscribed_at' => $subscription?->created_at?->toIso8601String(),
+            'subscription_cadence' => Plan::resolveCadenceForUser($user),
-                'subscription_expires_at' => $expiresAt?->toIso8601String(),
+            'subscribed_at' => $subscription?->created_at?->toIso8601String(),
-            ],
+            'subscription_expires_at' => $expiresAt?->toIso8601String(),
-        ));
+        ]);
     }
 }

app/Listeners/HandleStripeWebhook.php

@@ -129,8 +129,9 @@ final class HandleStripeWebhook
 
     private function bustPlanCache(User $user): void
     {
-        $tag = Cache::tags(['plans']);
+        $cache = Cache::supportsTags() ? Cache::tags(['plans']) : Cache::store();
-        $tag->forget("plan_for_user_{$user->id}");
+
-        $tag->forget("plan_cadence_for_user_{$user->id}");
+        $cache->forget("plan_for_user_{$user->id}");
+        $cache->forget("plan_cadence_for_user_{$user->id}");
     }
 }

app/Models/ApiLog.php

@@ -7,7 +7,21 @@ use Illuminate\Database\Eloquent\Attributes\Fillable;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 
-#[Fillable(['service', 'method', 'url', 'status_code', 'duration_ms', 'error'])]
+#[Fillable([
+    'service',
+    'method',
+    'url',
+    'status_code',
+    'duration_ms',
+    'error',
+    'response_body',
+    'input_tokens',
+    'output_tokens',
+    'cache_read_tokens',
+    'cache_write_tokens',
+    'ratelimit_remaining',
+    'ratelimit_reset_at',
+])]
 class ApiLog extends Model
 {
     /** @use HasFactory<ApiLogFactory> */
@@ -19,6 +33,7 @@ class ApiLog extends Model
     {
         return [
             'created_at' => 'datetime',
+            'ratelimit_reset_at' => 'datetime',
         ];
     }
 }

app/Models/Backtest.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace App\Models;
+
+use Database\Factories\BacktestFactory;
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+#[Fillable([
+    'model_version',
+    'features_json',
+    'coefficients_json',
+    'train_start',
+    'train_end',
+    'eval_start',
+    'eval_end',
+    'directional_accuracy',
+    'mae_pence',
+    'calibration_table',
+    'leak_suspected',
+    'ran_at',
+])]
+class Backtest extends Model
+{
+    /** @use HasFactory<BacktestFactory> */
+    use HasFactory;
+
+    protected function casts(): array
+    {
+        return [
+            'features_json' => 'array',
+            'coefficients_json' => 'array',
+            'calibration_table' => 'array',
+            'train_start' => 'date',
+            'train_end' => 'date',
+            'eval_start' => 'date',
+            'eval_end' => 'date',
+            'directional_accuracy' => 'decimal:2',
+            'mae_pence' => 'decimal:2',
+            'leak_suspected' => 'boolean',
+            'ran_at' => 'datetime',
+        ];
+    }
+}

app/Models/ForecastOutcome.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Model;
+
+#[Fillable([
+    'forecast_for',
+    'model_version',
+    'predicted_class',
+    'actual_class',
+    'correct',
+    'abs_error_pence',
+    'resolved_at',
+])]
+class ForecastOutcome extends Model
+{
+    public $timestamps = false;
+
+    public $incrementing = false;
+
+    protected $primaryKey = 'forecast_for';
+
+    protected $keyType = 'string';
+
+    protected function casts(): array
+    {
+        return [
+            'forecast_for' => 'date',
+            'correct' => 'boolean',
+            'abs_error_pence' => 'integer',
+            'resolved_at' => 'datetime',
+        ];
+    }
+}

app/Models/LlmOverlay.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Model;
+
+#[Fillable([
+    'ran_at',
+    'forecast_for_week',
+    'direction',
+    'confidence',
+    'reasoning',
+    'events_json',
+    'agrees_with_ridge',
+    'major_impact_event',
+    'volatility_flag_on',
+    'search_used',
+])]
+class LlmOverlay extends Model
+{
+    protected function casts(): array
+    {
+        return [
+            'ran_at' => 'datetime',
+            'forecast_for_week' => 'date',
+            'confidence' => 'integer',
+            'events_json' => 'array',
+            'agrees_with_ridge' => 'boolean',
+            'major_impact_event' => 'boolean',
+            'volatility_flag_on' => 'boolean',
+            'search_used' => 'boolean',
+        ];
+    }
+}

app/Models/PricePrediction.php

@@ -1,54 +0,0 @@
-<?php
-
-namespace App\Models;
-
-use App\Enums\PredictionSource;
-use App\Enums\TrendDirection;
-use Database\Factories\PricePredictionFactory;
-use Illuminate\Database\Eloquent\Attributes\Fillable;
-use Illuminate\Database\Eloquent\Builder;
-use Illuminate\Database\Eloquent\Factories\HasFactory;
-use Illuminate\Database\Eloquent\Model;
-
-#[Fillable(['predicted_for', 'source', 'direction', 'confidence', 'reasoning', 'generated_at'])]
-class PricePrediction extends Model
-{
-    /** @use HasFactory<PricePredictionFactory> */
-    use HasFactory;
-
-    public $timestamps = false;
-
-    protected function casts(): array
-    {
-        return [
-            'predicted_for' => 'date',
-            'source' => PredictionSource::class,
-            'direction' => TrendDirection::class,
-            'confidence' => 'integer',
-            'generated_at' => 'datetime',
-        ];
-    }
-
-    /**
-     * Order by source quality: llm_with_context → llm → ewma.
-     * Use this whenever reading the "best" prediction for a given date.
-     *
-     * @param  Builder<PricePrediction>  $query
-     * @return Builder<PricePrediction>
-     */
-    public function scopeBestFirst(Builder $query): Builder
-    {
-        $priority = [
-            PredictionSource::LlmWithContext->value,
-            PredictionSource::Llm->value,
-            PredictionSource::Ewma->value,
-        ];
-
-        $cases = '';
-        foreach ($priority as $rank => $source) {
-            $cases .= " WHEN '$source' THEN $rank";
-        }
-
-        return $query->orderByRaw("CASE source$cases ELSE ".count($priority).' END');
-    }
-}

app/Models/VolatilityRegime.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Model;
+
+#[Fillable([
+    'flipped_on_at',
+    'flipped_off_at',
+    'trigger',
+    'trigger_detail',
+    'active',
+])]
+class VolatilityRegime extends Model
+{
+    protected function casts(): array
+    {
+        return [
+            'flipped_on_at' => 'datetime',
+            'flipped_off_at' => 'datetime',
+            'active' => 'boolean',
+        ];
+    }
+
+    public static function currentlyActive(): ?self
+    {
+        return static::query()->where('active', true)->orderByDesc('flipped_on_at')->first();
+    }
+}

app/Models/WatchedEvent.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Models;
+
+use Database\Factories\WatchedEventFactory;
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+#[Fillable([
+    'label',
+    'starts_at',
+    'ends_at',
+    'notes',
+])]
+class WatchedEvent extends Model
+{
+    /** @use HasFactory<WatchedEventFactory> */
+    use HasFactory;
+
+    protected function casts(): array
+    {
+        return [
+            'starts_at' => 'datetime',
+            'ends_at' => 'datetime',
+        ];
+    }
+}

app/Models/WeeklyForecast.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace App\Models;
+
+use Database\Factories\WeeklyForecastFactory;
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+#[Fillable([
+    'forecast_for',
+    'model_version',
+    'direction',
+    'magnitude_pence',
+    'ridge_confidence',
+    'flagged_duty_change',
+    'reasoning',
+    'generated_at',
+])]
+class WeeklyForecast extends Model
+{
+    /** @use HasFactory<WeeklyForecastFactory> */
+    use HasFactory;
+
+    protected function casts(): array
+    {
+        return [
+            'forecast_for' => 'date',
+            'magnitude_pence' => 'integer',
+            'ridge_confidence' => 'integer',
+            'flagged_duty_change' => 'boolean',
+            'generated_at' => 'datetime',
+        ];
+    }
+}

app/Providers/AppServiceProvider.php

@@ -4,11 +4,6 @@ namespace App\Providers;
 
 use App\Listeners\HandleStripeWebhook;
 use App\Models\Subscription;
-use App\Services\ApiLogger;
-use App\Services\LlmPrediction\AnthropicPredictionProvider;
-use App\Services\LlmPrediction\GeminiPredictionProvider;
-use App\Services\LlmPrediction\OilPredictionProvider;
-use App\Services\LlmPrediction\OpenAiPredictionProvider;
 use Carbon\CarbonImmutable;
 use Illuminate\Support\Facades\Date;
 use Illuminate\Support\Facades\DB;
@@ -25,15 +20,9 @@ class AppServiceProvider extends ServiceProvider
      */
     public function register(): void
     {
-        $this->app->bind(OilPredictionProvider::class, function ($app) {
+        // No bindings here. The legacy LLM prediction provider binding
-            $logger = $app->make(ApiLogger::class);
+        // was removed when the Phase 4 ridge model + Phase 8
-
+        // LlmOverlayService replaced the old daily oil prediction.
-            return match (config('services.llm.provider')) {
-                'openai' => new OpenAiPredictionProvider($logger),
-                'gemini' => new GeminiPredictionProvider($logger),
-                default => new AnthropicPredictionProvider($logger),
-            };
-        });
     }
 
     /**

app/Services/ApiLogger.php

@@ -3,18 +3,29 @@
 namespace App\Services;
 
 use App\Models\ApiLog;
+use Illuminate\Http\Client\RequestException;
 use Illuminate\Http\Client\Response;
 use Illuminate\Support\Str;
 use Throwable;
 
 class ApiLogger
 {
+    /**
+     * Cap the stored response body. MEDIUMTEXT can hold ~16MB, but
+     * persisting more than 64KB is rarely useful for debugging and
+     * blows up the row size on busy services.
+     */
+    private const int RESPONSE_BODY_CAP = 65_536;
+
     /**
      * Execute an HTTP request and log it to api_logs.
      *
      * The callable must return an Illuminate\Http\Client\Response.
      * Exceptions are logged and re-thrown so the caller handles them.
      *
+     * Persists the response body to `api_logs.response_body` ONLY when
+     * the call failed (non-2xx) or threw. Truncates to RESPONSE_BODY_CAP.
+     *
      * @param  callable(): Response  $request
      */
     public function send(string $service, string $method, string $url, callable $request): Response
@@ -22,19 +33,31 @@ class ApiLogger
         $start = microtime(true);
         $statusCode = null;
         $error = null;
+        $responseBody = null;
+        $usage = [];
 
         try {
             $response = $request();
             $statusCode = $response->status();
+            $usage = $this->extractUsage($response);
 
             if ($response->failed()) {
-                $error = Str::limit($response->body(), 1000);
+                $body = $response->body();
+                $error = Str::limit($body, 1000);
+                $responseBody = $this->truncate($body);
             }
 
             return $response;
         } catch (Throwable $e) {
             $error = $e->getMessage();
 
+            // RequestException carries the response, ConnectionException
+            // doesn't. Pull the body when it's available.
+            if ($e instanceof RequestException) {
+                $responseBody = $this->truncate($e->response->body());
+                $usage = $this->extractUsage($e->response);
+            }
+
             throw $e;
         } finally {
             ApiLog::create([
@@ -44,7 +67,51 @@ class ApiLogger
                 'status_code' => $statusCode,
                 'duration_ms' => (int) round((microtime(true) - $start) * 1000),
                 'error' => $error,
+                'response_body' => $responseBody,
+                ...$usage,
             ]);
         }
     }
+
+    private function truncate(string $body): string
+    {
+        return strlen($body) > self::RESPONSE_BODY_CAP
+            ? substr($body, 0, self::RESPONSE_BODY_CAP)
+            : $body;
+    }
+
+    /**
+     * Pull token-usage and rate-limit telemetry from a provider response.
+     *
+     * Today only Anthropic exposes both. Other providers return mostly
+     * NULLs — callers don't need to know which is which.
+     *
+     * @return array<string, int|string|null>
+     */
+    private function extractUsage(?Response $response): array
+    {
+        if ($response === null) {
+            return [];
+        }
+
+        $usage = $response->json('usage');
+        $tokens = is_array($usage) ? $usage : [];
+
+        $reset = $response->header('anthropic-ratelimit-input-tokens-reset');
+        $remaining = $response->header('anthropic-ratelimit-input-tokens-remaining');
+
+        return [
+            'input_tokens' => $this->intOrNull($tokens['input_tokens'] ?? null),
+            'output_tokens' => $this->intOrNull($tokens['output_tokens'] ?? null),
+            'cache_read_tokens' => $this->intOrNull($tokens['cache_read_input_tokens'] ?? null),
+            'cache_write_tokens' => $this->intOrNull($tokens['cache_creation_input_tokens'] ?? null),
+            'ratelimit_remaining' => $this->intOrNull($remaining !== '' ? $remaining : null),
+            'ratelimit_reset_at' => $reset !== '' ? $reset : null,
+        ];
+    }
+
+    private function intOrNull(mixed $value): ?int
+    {
+        return is_numeric($value) ? (int) $value : null;
+    }
 }

app/Services/BrentPriceFetcher.php

@@ -41,4 +41,24 @@ final readonly class BrentPriceFetcher
 
         BrentPrice::upsert($rows, ['date'], ['price_usd']);
     }
+
+    /**
+     * One-shot Brent backfill via FRED's observation_start/end. Used to
+     * seed `brent_prices` going back to 2018 so Phase 9's volatility
+     * detector and Phase 8's LLM overlay have proper context.
+     *
+     * @return int rows inserted/updated
+     */
+    public function backfillFromFred(string $from, string $to): int
+    {
+        $rows = $this->fred->fetchRange($from, $to);
+
+        if ($rows === null) {
+            throw new BrentPriceFetchException("FRED backfill ({$from} → {$to}) returned no data");
+        }
+
+        BrentPrice::upsert($rows, ['date'], ['price_usd']);
+
+        return count($rows);
+    }
 }

app/Services/BrentPricePredictor.php

@@ -1,119 +0,0 @@
-<?php
-
-namespace App\Services;
-
-use App\Enums\PredictionSource;
-use App\Enums\TrendDirection;
-use App\Models\BrentPrice;
-use App\Models\PricePrediction;
-use App\Services\LlmPrediction\OilPredictionProvider;
-use Illuminate\Support\Collection;
-use Illuminate\Support\Facades\Log;
-
-final class BrentPricePredictor
-{
-    private const float EWMA_THRESHOLD_PCT = 1.5;
-
-    private const int EWMA_MAX_CONFIDENCE = 65;
-
-    private const int EWMA_MIN_ROWS = 14;
-
-    public function __construct(
-        private readonly OilPredictionProvider $provider,
-    ) {}
-
-    /**
-     * Return the latest BrentPrice row, or null if none exists.
-     */
-    public function latestPrice(): ?BrentPrice
-    {
-        return BrentPrice::orderBy('date', 'desc')->first();
-    }
-
-    /**
-     * Try LLM first; persist EWMA only as a fallback when the LLM provider
-     * returns null. The downstream OilSignal already prefers LLM
-     * (llm_with_context > llm > ewma), so writing both rows on every run is
-     * dead weight 95% of the time. EWMA still acts as the safety net.
-     */
-    public function generatePrediction(): ?PricePrediction
-    {
-        $prices = BrentPrice::orderBy('date', 'desc')->limit(30)->get();
-
-        if ($prices->count() < self::EWMA_MIN_ROWS) {
-            Log::warning('BrentPricePredictor: not enough price data', [
-                'rows' => $prices->count(),
-            ]);
-
-            return null;
-        }
-
-        $llm = $this->provider->predict($prices);
-
-        if ($llm !== null) {
-            PricePrediction::create($llm->toArray());
-            $prices->first()->forceFill(['prediction_generated_at' => now()])->save();
-
-            return $llm;
-        }
-
-        $ewma = $this->generateEwmaPrediction($prices);
-
-        if ($ewma !== null) {
-            PricePrediction::create($ewma->toArray());
-            $prices->first()->forceFill(['prediction_generated_at' => now()])->save();
-        }
-
-        return $ewma;
-    }
-
-    public function generateEwmaPrediction(Collection $prices): ?PricePrediction
-    {
-        $chronological = $prices->sortBy('date')->pluck('price_usd')->values()->all();
-
-        if (count($chronological) < self::EWMA_MIN_ROWS) {
-            return null;
-        }
-
-        $ewma3 = Ewma::compute(array_slice($chronological, -3));
-        $ewma7 = Ewma::compute(array_slice($chronological, -7));
-
-        $changePct = (($ewma3 - $ewma7) / $ewma7) * 100;
-
-        [$direction, $confidence] = match (true) {
-            $changePct >= self::EWMA_THRESHOLD_PCT => [
-                TrendDirection::Rising,
-                $this->ewmaConfidence($changePct),
-            ],
-            $changePct <= -self::EWMA_THRESHOLD_PCT => [
-                TrendDirection::Falling,
-                $this->ewmaConfidence(abs($changePct)),
-            ],
-            default => [TrendDirection::Flat, 50],
-        };
-
-        $reasoning = sprintf(
-            '3-day EWMA ($%.2f) vs 7-day EWMA ($%.2f): %.2f%% %s.',
-            $ewma3,
-            $ewma7,
-            abs($changePct),
-            $direction === TrendDirection::Flat ? 'difference (flat)' : $direction->value,
-        );
-
-        return new PricePrediction([
-            'predicted_for' => now()->toDateString(),
-            'source' => PredictionSource::Ewma,
-            'direction' => $direction,
-            'confidence' => $confidence,
-            'reasoning' => $reasoning,
-            'generated_at' => now(),
-        ]);
-    }
-
-    private function ewmaConfidence(float $changePct): int
-    {
-        $scaled = min($changePct / 5.0, 1.0) * self::EWMA_MAX_CONFIDENCE;
-
-        return (int) round(max(30, $scaled));
-    }
-}

app/Services/BrentPriceSources/EiaBrentPriceSource.php

@@ -3,8 +3,9 @@
 namespace App\Services\BrentPriceSources;
 
 use App\Services\ApiLogger;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Http\Client\RequestException;
 use Illuminate\Support\Facades\Http;
-use Illuminate\Support\Facades\Log;
 use Throwable;
 
 final class EiaBrentPriceSource
@@ -14,12 +15,16 @@ final class EiaBrentPriceSource
     public function __construct(private readonly ApiLogger $apiLogger) {}
 
     /**
-     * @return array{date: string, price_usd: float}[]|null
+     * @return array{date: string, price_usd: float}[]|null null only when the response carried no usable rows
+     *
+     * @throws BrentPriceFetchException on network failure or non-2xx response after retries
      */
     public function fetch(): ?array
     {
         try {
-            $response = $this->apiLogger->send('eia', 'GET', self::URL, fn () => Http::timeout(10)
+            $response = $this->apiLogger->send('eia', 'GET', self::URL, fn () => Http::timeout(30)
+                ->retry(3, 200, fn (Throwable $e) => $this->shouldRetry($e))
+                ->throw()
                 ->get(self::URL, [
                     'api_key' => config('services.eia.api_key'),
                     'frequency' => 'daily',
@@ -29,32 +34,26 @@ final class EiaBrentPriceSource
                     'sort[0][direction]' => 'desc',
                     'length' => 30,
                 ]));
-
+        } catch (ConnectionException $e) {
-            if (! $response->successful()) {
+            throw new BrentPriceFetchException("EIA connection failed: {$e->getMessage()}", previous: $e);
-                Log::error('EiaBrentPriceSource: request failed', ['status' => $response->status()]);
+        } catch (RequestException $e) {
-
+            throw new BrentPriceFetchException("EIA returned HTTP {$e->response->status()}", previous: $e);
-                return null;
-            }
-
-            $rows = collect($response->json('response.data') ?? [])
-                ->filter(fn (array $row) => ($row['value'] ?? '.') !== '.')
-                ->map(fn (array $row) => [
-                    'date' => $row['period'],
-                    'price_usd' => (float) $row['value'],
-                ])
-                ->all();
-
-            if ($rows === []) {
-                Log::warning('EiaBrentPriceSource: no valid observations returned');
-
-                return null;
-            }
-
-            return $rows;
-        } catch (Throwable $e) {
-            Log::error('EiaBrentPriceSource: fetch failed', ['error' => $e->getMessage()]);
-
-            return null;
         }
+
+        $rows = collect($response->json('response.data') ?? [])
+            ->filter(fn (array $row) => ($row['value'] ?? '.') !== '.')
+            ->map(fn (array $row) => [
+                'date' => $row['period'],
+                'price_usd' => (float) $row['value'],
+            ])
+            ->all();
+
+        return $rows === [] ? null : $rows;
+    }
+
+    private function shouldRetry(Throwable $e): bool
+    {
+        return $e instanceof ConnectionException
+            || ($e instanceof RequestException && $e->response->serverError());
     }
 }

app/Services/BrentPriceSources/FredBrentPriceSource.php

@@ -3,8 +3,9 @@
 namespace App\Services\BrentPriceSources;
 
 use App\Services\ApiLogger;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Http\Client\RequestException;
 use Illuminate\Support\Facades\Http;
-use Illuminate\Support\Facades\Log;
 use Throwable;
 
 final class FredBrentPriceSource
@@ -14,45 +15,76 @@ final class FredBrentPriceSource
     public function __construct(private readonly ApiLogger $apiLogger) {}
 
     /**
-     * @return array{date: string, price_usd: float}[]|null
+     * @return array{date: string, price_usd: float}[]|null null only when the response carried no usable rows
+     *
+     * @throws BrentPriceFetchException on network failure or non-2xx response after retries
      */
     public function fetch(): ?array
     {
+        return $this->call([
+            'sort_order' => 'desc',
+            'limit' => 30,
+        ]);
+    }
+
+    /**
+     * Backfill range (inclusive). FRED's `observation_start` /
+     * `observation_end` parameters expect ISO dates (YYYY-MM-DD).
+     * Returns null when the range is empty (e.g. all weekends/holidays).
+     *
+     * @return array{date: string, price_usd: float}[]|null
+     *
+     * @throws BrentPriceFetchException
+     */
+    public function fetchRange(string $from, string $to): ?array
+    {
+        return $this->call([
+            'observation_start' => $from,
+            'observation_end' => $to,
+            'sort_order' => 'asc',
+            'limit' => 100000,
+        ]);
+    }
+
+    /**
+     * @param  array<string, scalar>  $extraParams
+     * @return array{date: string, price_usd: float}[]|null
+     *
+     * @throws BrentPriceFetchException
+     */
+    private function call(array $extraParams): ?array
+    {
+        $params = array_merge([
+            'series_id' => 'DCOILBRENTEU',
+            'api_key' => config('services.fred.api_key'),
+            'file_type' => 'json',
+        ], $extraParams);
+
         try {
-            $response = $this->apiLogger->send('fred', 'GET', self::URL, fn () => Http::timeout(10)
+            $response = $this->apiLogger->send('fred', 'GET', self::URL, fn () => Http::timeout(60)
-                ->get(self::URL, [
+                ->retry(3, 200, fn (Throwable $e) => $this->shouldRetry($e))
-                    'series_id' => 'DCOILBRENTEU',
+                ->throw()
-                    'api_key' => config('services.fred.api_key'),
+                ->get(self::URL, $params));
-                    'sort_order' => 'desc',
+        } catch (ConnectionException $e) {
-                    'limit' => 30,
+            throw new BrentPriceFetchException("FRED connection failed: {$e->getMessage()}", previous: $e);
-                    'file_type' => 'json',
+        } catch (RequestException $e) {
-                ]));
+            throw new BrentPriceFetchException("FRED returned HTTP {$e->response->status()}", previous: $e);
-
-            if (! $response->successful()) {
-                Log::error('FredBrentPriceSource: request failed', ['status' => $response->status()]);
-
-                return null;
-            }
-
-            $rows = collect($response->json('observations') ?? [])
-                ->filter(fn (array $obs) => $obs['value'] !== '.')
-                ->map(fn (array $obs) => [
-                    'date' => $obs['date'],
-                    'price_usd' => (float) $obs['value'],
-                ])
-                ->all();
-
-            if ($rows === []) {
-                Log::warning('FredBrentPriceSource: no valid observations returned');
-
-                return null;
-            }
-
-            return $rows;
-        } catch (Throwable $e) {
-            Log::error('FredBrentPriceSource: fetch failed', ['error' => $e->getMessage()]);
-
-            return null;
         }
+
+        $rows = collect($response->json('observations') ?? [])
+            ->filter(fn (array $obs) => $obs['value'] !== '.')
+            ->map(fn (array $obs) => [
+                'date' => $obs['date'],
+                'price_usd' => (float) $obs['value'],
+            ])
+            ->all();
+
+        return $rows === [] ? null : $rows;
+    }
+
+    private function shouldRetry(Throwable $e): bool
+    {
+        return $e instanceof ConnectionException
+            || ($e instanceof RequestException && $e->response->serverError());
     }
 }

app/Services/Ewma.php

@@ -1,25 +0,0 @@
-<?php
-
-namespace App\Services;
-
-/**
- * Exponentially-weighted moving average. Pure function — used by
- * BrentPricePredictor for the EWMA fallback prediction and by
- * AnthropicPredictionProvider to enrich the basic-flow prompt.
- */
-final class Ewma
-{
-    public const float DEFAULT_ALPHA = 0.3;
-
-    /** @param  float[]  $prices  Chronological order (oldest first). */
-    public static function compute(array $prices, float $alpha = self::DEFAULT_ALPHA): float
-    {
-        $ema = $prices[0];
-
-        foreach (array_slice($prices, 1) as $price) {
-            $ema = $alpha * $price + (1 - $alpha) * $ema;
-        }
-
-        return round($ema, 4);
-    }
-}

app/Services/Forecasting/AccuracyHistory.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Services\Forecasting;
+
+use Carbon\Carbon;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Trailing-13-week hit rate for a model_version. Read from
+ * `forecast_outcomes`. Returns null when fewer than 4 outcomes are
+ * available (a single bad week would otherwise dominate the ratio).
+ */
+final class AccuracyHistory
+{
+    private const int WEEKS = 13;
+
+    private const int MIN_OUTCOMES = 4;
+
+    public function trailingHitRate(string $modelVersion): ?float
+    {
+        $cutoff = Carbon::now()->subWeeks(self::WEEKS)->toDateString();
+
+        $row = DB::table('forecast_outcomes')
+            ->where('model_version', $modelVersion)
+            ->where('forecast_for', '>=', $cutoff)
+            ->selectRaw('COUNT(*) as total, SUM(CASE WHEN correct THEN 1 ELSE 0 END) as correct')
+            ->first();
+
+        $total = (int) ($row->total ?? 0);
+        if ($total < self::MIN_OUTCOMES) {
+            return null;
+        }
+
+        return (int) ($row->correct ?? 0) / $total;
+    }
+}