Bump version to 0.21.0

This commit introduces a RecommendationService that is used when indexing products.

The service is utilizing a recommendation rules interface, so many rules can be created and applied during indexing the products

README.md

@@ -1,6 +1,9 @@
 # Core Module
 
-A Laravel module providing authentication, notifications, activity logging, CLI tooling, and functional types on top of the [Lunar](https://lunarphp.io) admin panel. Designed to be consumed as a standalone Composer package.
+A Laravel module providing authentication, localization, product search/catalog, privacy/GDPR
+tooling, notifications, activity logging, CLI tooling, and functional types on top of the
+[Lunar](https://lunarphp.io) e-commerce package. Designed to be consumed as a standalone Composer
+package by any Lunar-based e-shop.
 
 ---
 
@@ -8,13 +11,83 @@ A Laravel module providing authentication, notifications, activity logging, CLI
 
 ### OTP Authentication
 
-Passwordless login for both staff (Lunar panel) and customers via 6-digit codes delivered by email. Codes expire after 10 minutes. The Lunar panel login page is a two-step flow: email → OTP. Rate-limited to 5 attempts.
+Passwordless login for both staff (Lunar panel) and customers via 6-digit codes delivered by
+email. Codes expire after 10 minutes, rate-limited to 5 attempts. The Lunar panel login page is a
+two-step flow (email → OTP) with a back button to return from the code step to the email step.
 
 See [`docs/otp-auth.md`](docs/otp-auth.md).
 
+### Localization
+
+Locale-prefixed routing (`Modules\Core\Localization\LocaleMiddleware`) — a `locale` route
+middleware, opt-in per shop, that resolves and redirects to the correct language segment
+(`/el/...`, `/en/...`) based on Lunar's own language list, with caching and rename-safe
+translation migration. Also brings in storefront UI label translations
+(`spatie/laravel-translation-loader`) with an admin-editable `LanguageLine` resource.
+
+See [`docs/localization.md`](docs/localization.md).
+
+### Product Search & Catalog
+
+Two complementary services on top of Meilisearch:
+
+- **`Modules\Core\Search\ProductSearchService`** — locale-aware full-text product search.
+- **`Modules\Core\Catalog\ProductService`** — listing/filtering (by collection, brand, price
+  range) and single-product lookup by id or slug, reading directly from the Meilisearch index
+  rather than the database.
+
+Both are backed by `Modules\Core\Search\ProductIndexer`, which extends Lunar's own indexer with
+collections, price, variants, media, tags, and reviews — everything needed for both a listing
+page and a full product detail page from one index.
+
+See [`docs/product-search.md`](docs/product-search.md) and
+[`docs/product-listing.md`](docs/product-listing.md).
+
+### Product Reviews
+
+`Modules\Core\Review\ProductReview` — ratings/reviews with staff replies, a Filament sub-navigation
+page on the product edit screen, and automatic re-indexing (via `ReviewServiceProvider`) whenever
+a review is created, updated, or deleted, so a product's Meilisearch document never goes stale.
+
+### Privacy / GDPR Data-Subject Requests
+
+Right of access (export) and right of erasure, built as an extensible contract
+(`Modules\Core\Privacy\Contracts\PersonalDataProvider`) rather than a fixed table list — any
+module can register its own data without core knowing it exists.
+
+- **Two independent scopes**: erasing/exporting a Lunar `Customer` (business account) is never
+  the same operation as erasing/exporting a `User` (individual login) — a `Customer` erasure
+  never touches any linked `User`'s login, and a `User` erasure never touches a `Customer`
+  account's own data. See `docs/privacy.md` "User-scope vs Customer-scope".
+- **Cancellable grace period** (default 30 days, configurable) before anything is actually
+  erased — logging back in during the window automatically reverts the request, mirroring
+  Shopify's own account-deletion flow. Immediate erasure exists but is staff-only by type, never
+  reachable from a self-service flow.
+- **Sole-owner cascade**: erasing the last remaining `User` on a `Customer` also opens a (grace
+  period) erasure request for that now-orphaned `Customer`, so its PII doesn't sit unreachable
+  forever — traced back to the triggering request so login-reactivation can revert exactly that
+  cascade.
+- **Queued export**: gathering data and writing a CSV-per-provider zip (via the generic,
+  reusable `Modules\Core\Export\CsvWriter`) runs as a background job; a consuming app hooks its
+  own notification onto the completion event via the Notification Registry (below).
+
+See [`docs/privacy.md`](docs/privacy.md).
+
+### Shopify Migration
+
+`Modules\Core\MigrateImport\Shopify\ShopifyExportImporter` — imports a Shopify CSV product export
+(products, variants, images, collections, tags, prices) into Lunar, idempotently re-runnable via
+an `import_mappings` table. Part of a source-agnostic import framework
+(`boboko:migrate:import`) designed to support additional sources later.
+
+See [`docs/shopify-import.md`](docs/shopify-import.md).
+
 ### Notification Registry
 
-An event-driven notification system. Each notification class declares which event it listens to and who to notify — the registry wires up the listener automatically. All notifications extend `BaseNotification` which implements `ShouldQueue`, so delivery is async. Supports optional delays.
+An event-driven notification system. Each notification class declares which event it listens to
+and who to notify — the registry wires up the listener automatically. All notifications extend
+`BaseNotification`, which implements `ShouldQueue`, so delivery is async. Supports optional
+delays.
 
 **Creating a notification:**
 
@@ -33,9 +106,13 @@ class MyNotification extends BaseNotification
 NotificationRegistry::get()->register([MyNotification::class]);
 ```
 
+See [`docs/notifications.md`](docs/notifications.md).
+
 ### Activity Logging
 
-Thin wrapper around [Spatie Laravel Activity Log](https://github.com/spatie/laravel-activitylog). Four standardized methods: `created()`, `updated()`, `failed()`, `deleted()`. Logs to the `lunar` channel and auto-resolves the actor from the staff session.
+Thin wrapper around [Spatie Laravel Activity Log](https://github.com/spatie/laravel-activitylog).
+Four standardized methods: `created()`, `updated()`, `failed()`, `deleted()`. Logs to the `lunar`
+channel and auto-resolves the actor from the staff session.
 
 See [`docs/activity-log.md`](docs/activity-log.md).
 
@@ -43,8 +120,11 @@ See [`docs/activity-log.md`](docs/activity-log.md).
 
 - Custom OTP login page replacing the default Lunar panel login
 - `StaffResourceExtension` — removes password field from Lunar's staff resource
-- `CustomerResourceExtension` — replaces default address relation manager with a custom implementation
-- `CorePlugin` — configures panel path, branding, logos, navigation items, and activity log field exclusions for staff
+- `CustomerResourceExtension` — replaces default address relation manager with a custom
+  implementation
+- Table-rate shipping (`ShippingPlugin`) registered by default
+- `CorePlugin` — configures panel path, branding, logos, navigation items, and activity log
+  field exclusions for staff
 
 Register the plugin in your Lunar panel provider:
 
@@ -52,30 +132,36 @@ Register the plugin in your Lunar panel provider:
 ->plugin(\Modules\Core\CorePlugin::make())
 ```
 
+See [`docs/lunar.md`](docs/lunar.md) for the full Lunar reference and non-obvious gotchas hit
+while building against it.
+
 ### CLI Commands
 
 | Command | Description |
 |---|---|
-| `core:create-admin` | Create a Lunar admin user |
-| `core:anonymize` | GDPR anonymization of users and customers (local only) |
-| `core:export` | Dump database + storage files to a timestamped zip |
-| `core:import` | Restore from a zip export (runs anonymize automatically, local only) |
-| `core:export-cleanup` | Delete old export zips, keep N most recent |
+| `boboko:anonymize` | Dummy-scrub personal data in `users`/`lunar_customers` for local dev safety (local environment only — **not** the GDPR erasure tool; see Privacy above for that) |
+| `boboko:export` | Dump database + storage files to a timestamped zip |
+| `boboko:import` | Restore from a `boboko:export` zip archive |
+| `boboko:export:cleanup` | Delete old export zips, keep N most recent |
+| `boboko:migrate:import` | Import a vendor product catalog (Shopify, etc.) into Lunar |
+| `boboko:privacy:process-erasure-requests` | Dispatch an erasure job for every due GDPR erasure request (wire into your own scheduler) |
+| `lunar:create-admin` | Create a Lunar admin user (overrides Lunar's own command) |
+| `lunar:install` | Seed default Lunar store data — countries, channel, currency, tax zone, attributes, product type (overrides Lunar's own command) |
 
 ### Functional Types
 
-Result and Option monads for explicit error handling without exceptions.
+Result and Option types for explicit error handling without exceptions.
 
 ```php
 // Result<T, E>
-$result = Success::of($value);
-$result = Error::of('something went wrong');
+$result = Success::create($value);
+$result = Error::create('something went wrong');
 $result->map(fn($v) => ...)->flatMap(fn($v) => ...);
 
 // Option<T>
-$option = Option::fromValue($nullableValue);
-$option->getOrElse('default');
-$option->map(fn($v) => ...)->filter(fn($v) => $v > 0);
+$option = Some::create($value);
+$option = None::create();
+$option->map(fn($v) => ...);
 ```
 
 ---
@@ -102,17 +188,22 @@ Then run:
 
 ```bash
 composer require boboko/core
+php artisan vendor:publish --tag=core-config
 php artisan vendor:publish --tag=core-assets
 php artisan migrate
 ```
 
+For local core development alongside a consuming app (path-repo symlink + Docker mount), see
+[`docs/modules.md`](docs/modules.md) "Docker Compose: the local-core mount".
+
 ---
 
 ## Requirements
 
-- PHP 8.2+
-- Laravel 11+
-- Lunar (lunarphp/lunar + lunarphp/admin)
+- PHP 8.5+
+- Laravel 12+
+- Lunar 1.3 (`lunarphp/lunar`)
+- Meilisearch (for product search/listing/catalog)
 - Spatie Laravel Activity Log
 
 ---
@@ -120,7 +211,12 @@ php artisan migrate
 ## Documentation
 
 - [`docs/otp-auth.md`](docs/otp-auth.md) — OTP authentication flow
+- [`docs/localization.md`](docs/localization.md) — Locale-prefixed routing and storefront translations
+- [`docs/product-search.md`](docs/product-search.md) — Full-text product search
+- [`docs/product-listing.md`](docs/product-listing.md) — Product listing/filtering/detail catalog service
+- [`docs/privacy.md`](docs/privacy.md) — GDPR right of access/erasure, User-scope vs Customer-scope
+- [`docs/shopify-import.md`](docs/shopify-import.md) — Shopify CSV → Lunar field mapping and import design
 - [`docs/activity-log.md`](docs/activity-log.md) — Activity logging
-- [`docs/lunar.md`](docs/lunar.md) — Lunar framework reference
 - [`docs/notifications.md`](docs/notifications.md) — Notification registry
+- [`docs/lunar.md`](docs/lunar.md) — Lunar framework reference and gotchas
 - [`docs/modules.md`](docs/modules.md) — Module architecture, Customer/User pairing, provider registration pitfalls

composer.json

@@ -2,7 +2,7 @@
   "name": "boboko/core",
   "description": "Core module — authentication and shared panel behaviour",
   "type": "library",
-  "version": "0.6.0",
+  "version": "0.21.0",
   "autoload": {
     "psr-4": {
       "Modules\\Core\\": "src/"
@@ -10,14 +10,15 @@
   },
   "require": {
     "php": "^8.5",
-    "lunarphp/lunar": "1.3.0",
+    "lunarphp/lunar": "1.5.0",
     "laravel/framework": "^12.0",
     "laravel/tinker": "^3.0",
     "symfony/yaml": "^7.0",
-    "lunarphp/table-rate-shipping": "^1.3",
+    "lunarphp/table-rate-shipping": "1.5.0",
     "lunarphp/search": "*",
     "lunarphp/meilisearch": "*",
-    "spatie/laravel-translation-loader": "^2.8"
+    "spatie/laravel-translation-loader": "^2.8",
+    "stripe/stripe-php": "^16.6"
   },
   "require-dev": {
     "fakerphp/faker": "^1.23",
@@ -27,7 +28,8 @@
     "mockery/mockery": "^1.6",
     "nunomaduro/collision": "^8.6",
     "pestphp/pest": "^4.6",
-    "pestphp/pest-plugin-laravel": "^4.1"
+    "pestphp/pest-plugin-laravel": "^4.1",
+    "filament/upgrade": "^4.0"
   },
   "extra": {
     "laravel": {
@@ -35,9 +37,16 @@
         "Modules\\Core\\Providers\\CoreServiceProvider",
         "Modules\\Core\\Providers\\AuthServiceProvider",
         "Modules\\Core\\Providers\\CustomerServiceProvider",
+        "Modules\\Core\\Providers\\CheckoutServiceProvider",
+        "Modules\\Core\\Providers\\PaymentServiceProvider",
         "Modules\\Core\\Providers\\LocalizationServiceProvider",
-        "Modules\\Core\\Providers\\ProductServiceProvider",
-        "Modules\\Core\\Providers\\ReviewServiceProvider"
+        "Modules\\Core\\Providers\\CatalogServiceProvider",
+        "Modules\\Core\\Providers\\CartServiceProvider",
+        "Modules\\Core\\Providers\\ReviewServiceProvider",
+        "Modules\\Core\\Providers\\FileServiceProvider",
+        "Modules\\Core\\Providers\\ShippingServiceProvider",
+        "Modules\\Core\\Providers\\OrderServiceProvider",
+        "Modules\\Core\\Providers\\PrivacyServiceProvider"
       ]
     }
   },

config/catalog.php

@@ -0,0 +1,25 @@
+<?php
+
+use Modules\Core\Catalog\Recommendations\RandomRule;
+use Modules\Core\Catalog\Recommendations\SameCategoryRule;
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Product recommendation rules
+    |--------------------------------------------------------------------------
+    |
+    | Tried in order by Modules\Core\Catalog\Services\RecommendationService —
+    | the first rule that returns at least one product wins. The order here IS
+    | the fallback chain: SameCategoryRule first, then RandomRule as a
+    | last-resort so a product page is never left with zero recommendations
+    | (as long as the store has more than one product). A consuming app can
+    | reorder, add, or remove rules freely — nothing about the chain shape is
+    | hardcoded in the service itself.
+    |
+    */
+    'recommendation_rules' => [
+        SameCategoryRule::class,
+        RandomRule::class,
+    ],
+];

config/core.php

@@ -18,21 +18,113 @@ return [
 
     /*
     |--------------------------------------------------------------------------
-    | Product Option Types
+    | Privacy / GDPR data-subject requests
     |--------------------------------------------------------------------------
     |
-    | Enabled `Modules\Core\Product\Contracts\ProductOptionTypeInterface`
-    | implementations, describing what structured data a ProductOption's
-    | values carry in their `meta` jsonb column, and how an admin edits it.
-    | An admin picks one per ProductOption from a dropdown built from this
-    | list (stored in ProductOption::meta, not tied to the option's handle) —
-    | a ProductOption with none selected has no described meta behavior,
-    | plain name/position only.
+    | 'providers' lists every Modules\Core\Privacy\Contracts\PersonalDataProvider
+    | that should be consulted for right-of-access/right-of-erasure requests. A
+    | module never needs to be known to core in advance — it just adds its own
+    | provider class here, the same way config('lunar.search.indexers') maps a
+    | model to its indexer. See docs/privacy.md.
     |
-    | \App\ProductOptions\ColorOptionType::class,
+    | 'grace_period_days' is how long an erasure request stays cancellable
+    | (account deactivated, not yet erased) before it's actually processed by
+    | the privacy:process-erasure-requests scheduled command.
     |
     */
 
-    'product_option_types' => [],
+    'privacy' => [
+        'providers' => [
+            // ActivityLogDataProvider MUST run before AddressDataProvider —
+            // it resolves which activity_log rows belong to this customer
+            // (including ones keyed by an Address id) before
+            // AddressDataProvider hard-deletes those Address rows. See that
+            // provider's own class docblock.
+            \Modules\Core\Logging\Privacy\ActivityLogDataProvider::class,
+            \Modules\Core\Customer\Privacy\CustomerDataProvider::class,
+            \Modules\Core\Customer\Privacy\AddressDataProvider::class,
+            \Modules\Core\Order\Privacy\OrderDataProvider::class,
+            \Modules\Core\Cart\Privacy\CartDataProvider::class,
+            \Modules\Core\Review\Privacy\ReviewDataProvider::class,
+            \Modules\Core\Payment\Privacy\PaymentDataProvider::class,
+            \Modules\Core\Auth\Privacy\UserSessionDataProvider::class,
+        ],
+
+        'grace_period_days' => 30,
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Cart Abandonment Threshold
+    |--------------------------------------------------------------------------
+    |
+    | How long a cart (that hasn't converted to a placed order) can go without
+    | activity before Modules\Core\Cart\Filament\Resources\CartResource treats
+    | it as "Abandoned" rather than "Ongoing". Anything DateInterval::createFromDateString()
+    | accepts works, e.g. '1 hour', '30 minutes', '2 days'.
+    |
+    */
+
+    'cart' => [
+        'abandoned_after' => '1 hour',
+
+        /*
+        |----------------------------------------------------------------------
+        | Unrecoverable Cap
+        |----------------------------------------------------------------------
+        |
+        | Beyond this age, a stale cart stops being treated as an active
+        | "Abandoned Cart"/"Abandoned Checkout" (Modules\Core\Cart\Services\
+        | CartLifecycleService) — too old to be a realistic recovery target
+        | (pricing/stock/tax likely stale by then). This is about the
+        | abandoned-cart pipeline only, not data retention — no rows are
+        | deleted or pruned based on this value.
+        |
+        */
+
+        'unrecoverable_after' => '90 days',
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Order Return Window
+    |--------------------------------------------------------------------------
+    |
+    | How many days after a carrier order is delivered (Order::fulfillment_status
+    | becomes 'return_window_open') before Modules\Core\Order\Commands\
+    | CloseExpiredReturnWindows auto-completes it, if no return was requested.
+    | Store-pickup orders have no return-window step and are unaffected by
+    | this value (see Modules\Core\Order\Listeners\CompleteOrderOnPickedUp).
+    |
+    */
+
+    'order' => [
+        'return_window_days' => 14,
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Storefront OTP Login
+    |--------------------------------------------------------------------------
+    |
+    | Modules\Core\Auth\Services\UserOtpService's passwordless login.
+    | max_attempts caps how many wrong codes a shopper can guess against ONE
+    | generated code before it's invalidated outright. generation_limit/
+    | generation_decay_minutes cap how often a NEW code can be requested for
+    | the same email — independent of max_attempts, since generating a fresh
+    | code also resets the guess count, so an attempt cap alone doesn't stop
+    | an attacker from just requesting a new code every few tries. This same
+    | limit is also what stands between a malicious/careless caller and
+    | mail-bombing one inbox.
+    |
+    */
+
+    'auth' => [
+        'otp' => [
+            'max_attempts' => 5,
+            'generation_limit' => 3,
+            'generation_decay_minutes' => 10,
+        ],
+    ],
 
 ];

config/legal.php

@@ -0,0 +1,21 @@
+<?php
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Policy versions
+    |--------------------------------------------------------------------------
+    |
+    | Plain version strings, bumped by whoever edits the corresponding legal
+    | page — recorded alongside every consent/acceptance so a later dispute
+    | ("what did the shopper actually agree to?") can be answered from the
+    | order/cart itself rather than a live lookup against whatever the pages
+    | say TODAY. Not tied to any CMS/database row on purpose — this stays a
+    | plain config value the same way payment.php's cart_pipeline is a plain
+    | cross-cutting setting, not a per-instance one.
+    |
+    */
+    'privacy_policy_version' => env('LEGAL_PRIVACY_POLICY_VERSION', '2026-01-01'),
+
+    'terms_version' => env('LEGAL_TERMS_VERSION', '2026-01-01'),
+];

config/payment.php

@@ -0,0 +1,28 @@
+<?php
+
+use Modules\Core\Payment\Pipelines\Cart\ApplyPaymentMethodFee;
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Lunar cart pipeline additions
+    |--------------------------------------------------------------------------
+    |
+    | Appended to config('lunar.cart.pipelines.cart') after ApplyShipping so
+    | the selected payment method's own fee (if any) is added to the
+    | shipping total before the final Calculate step sums everything up.
+    |
+    | This is the one thing left in this file — everything about WHICH
+    | payment methods exist (driver mapping, capture_mode, statuses) moved
+    | onto Modules\Core\Payment\Models\PaymentMethod's own row (see
+    | docs/payments.md): that's a per-instance, merchant decision, not a
+    | store-wide-singular setting, so it never belonged in config at all.
+    | This pipeline registration IS genuinely cross-cutting — every store
+    | using this driver gets the same cart-pipeline wiring, regardless of
+    | how many payment methods it configures.
+    |
+    */
+    'cart_pipeline' => [
+        ApplyPaymentMethodFee::class,
+    ],
+];

config/shippingCarriers/acs.php

@@ -0,0 +1,50 @@
+<?php
+
+/*
+|--------------------------------------------------------------------------
+| ACS Courier credentials
+|--------------------------------------------------------------------------
+|
+| ACS requires two credential mechanisms simultaneously: an AcsApiKey
+| HTTP header (gates the REST gateway itself) and four account fields
+| (Company_ID/Company_Password/User_ID/User_Password) sent in every
+| request body. Both are supplied by ACS when your account is set up.
+|
+| Set these via environment variables — never commit real values.
+|
+| ACS_BASE_URL           Root REST endpoint (unversioned, single URL for
+|                        every ACSAlias call).
+| ACS_API_KEY            The AcsApiKey header value.
+| ACS_COMPANY_ID         Company_ID body field.
+| ACS_COMPANY_PASSWORD   Company_Password body field.
+| ACS_USER_ID            User_ID body field.
+| ACS_USER_PASSWORD      User_Password body field.
+| ACS_BILLING_CODE       Your ACS credit/billing code, used for price
+|                        calculation and voucher creation.
+| ACS_SENDER_*           Static sender details reused on every voucher.
+|
+*/
+
+return [
+
+    'base_url' => env('ACS_BASE_URL', 'https://webservices.acscourier.net/ACSRestServices/api/ACSAutoRest'),
+
+    'api_key' => env('ACS_API_KEY'),
+
+    'company_id' => env('ACS_COMPANY_ID'),
+    'company_password' => env('ACS_COMPANY_PASSWORD'),
+    'user_id' => env('ACS_USER_ID'),
+    'user_password' => env('ACS_USER_PASSWORD'),
+
+    'billing_code' => env('ACS_BILLING_CODE'),
+
+    'sender' => [
+        'name' => env('ACS_SENDER_NAME'),
+        'address' => env('ACS_SENDER_ADDRESS'),
+        'zip_code' => env('ACS_SENDER_ZIP'),
+        'phone' => env('ACS_SENDER_PHONE'),
+    ],
+
+    'timeout' => env('ACS_HTTP_TIMEOUT', 10),
+
+];

config/shippingCarriers/boxnow.php

@@ -0,0 +1,61 @@
+<?php
+
+/*
+|--------------------------------------------------------------------------
+| Box Now credentials
+|--------------------------------------------------------------------------
+|
+| Box Now uses OAuth2 client-credentials: exchange BOXNOW_CLIENT_ID /
+| BOXNOW_CLIENT_SECRET for a Bearer access token (POST /auth-sessions,
+| ~1hr expiry), then attach it as an Authorization header on every call.
+| Unlike ACS, there is no separate per-request credential body — the
+| token alone authorizes all calls once obtained.
+|
+| Set these via environment variables — never commit real values.
+|
+| Box Now has two environments (see their Partner API manual, section 2):
+| Stage/Sandbox for testing, Production once live. Each has its own
+| client_id/client_secret pair and its own base_url/location_api_url —
+| there is no shared "switch an env var" flag, since stage credentials
+| don't work against the production host or vice versa.
+|
+| BOXNOW_BASE_URL         Root REST endpoint for delivery-requests/parcels.
+| BOXNOW_LOCATION_API_URL Separate, faster endpoint for origins/destinations
+|                         lookups (Box Now recommends this over the main
+|                         base URL for those two calls specifically).
+| BOXNOW_CLIENT_ID        OAuth2 client id.
+| BOXNOW_CLIENT_SECRET    OAuth2 client secret.
+| BOXNOW_PARTNER_ID       Numeric partnerId Box Now issues alongside your
+|                         credentials. NOT used for REST API authentication
+|                         (BoxNowClient authenticates with client_id/
+|                         client_secret alone) — this is only consumed by
+|                         the client-side Destination Map widget config
+|                         (_bn_map_widget_config.partnerId), confirmed
+|                         against Box Now's own WooCommerce plugin source.
+| BOXNOW_ORIGIN_LOCATION_ID  Your warehouse's Box Now locationId, used as
+|                            the pickup origin on every delivery request.
+| BOXNOW_SENDER_*         Static sender contact details reused on every
+|                         delivery request.
+|
+*/
+
+return [
+
+    'base_url' => env('BOXNOW_BASE_URL', 'https://api-production.boxnow.gr/api/v1'),
+    'location_api_url' => env('BOXNOW_LOCATION_API_URL', 'https://locationapi-production.boxnow.gr/api/v1'),
+
+    'client_id' => env('BOXNOW_CLIENT_ID'),
+    'client_secret' => env('BOXNOW_CLIENT_SECRET'),
+    'partner_id' => env('BOXNOW_PARTNER_ID'),
+
+    'origin_location_id' => env('BOXNOW_ORIGIN_LOCATION_ID'),
+
+    'sender' => [
+        'name' => env('BOXNOW_SENDER_NAME'),
+        'email' => env('BOXNOW_SENDER_EMAIL'),
+        'phone' => env('BOXNOW_SENDER_PHONE'),
+    ],
+
+    'timeout' => env('BOXNOW_HTTP_TIMEOUT', 10),
+
+];

database/migrations/2026_07_16_000001_create_shipments_table.php

@@ -0,0 +1,29 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('shipments', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('order_id')->constrained(config('lunar.database.table_prefix').'orders');
+            $table->string('carrier');
+            $table->string('tracking_reference')->unique();
+            $table->string('parent_reference')->nullable();
+            $table->timestamp('label_printed_at')->nullable();
+            $table->string('manifest_reference')->nullable();
+            $table->timestamp('cancelled_at')->nullable();
+            $table->json('meta')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('shipments');
+    }
+};

database/migrations/2026_07_21_000001_create_shipment_info_table.php

@@ -0,0 +1,28 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('shipment_info', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('shipment_id')->constrained('shipments')->cascadeOnDelete();
+            $table->string('status');
+            $table->string('carrier_status')->nullable();
+            $table->text('message')->nullable();
+            $table->string('location')->nullable();
+            $table->timestamp('occurred_at');
+            $table->json('meta')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('shipment_info');
+    }
+};

database/migrations/2026_08_24_000001_add_deactivated_at_to_users_table.php

@@ -0,0 +1,22 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('users', function (Blueprint $table) {
+            $table->timestamp('deactivated_at')->nullable()->after('otp_expires_at');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('users', function (Blueprint $table) {
+            $table->dropColumn('deactivated_at');
+        });
+    }
+};

database/migrations/2026_08_24_000002_create_data_erasure_requests_table.php

@@ -0,0 +1,56 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('data_erasure_requests', function (Blueprint $table) {
+            $table->id();
+            // Polymorphic, not a fixed customer_id — a request targets either a
+            // Lunar Customer (business account) or a User (individual), never
+            // both at once. See docs/privacy.md "User-scope vs Customer-scope".
+            $table->string('subject_type');
+            $table->unsignedBigInteger('subject_id');
+            // Snapshot, not a live-looked-up value — the subject's email may
+            // change or the record may be gone by the time this is read.
+            $table->string('email')->nullable();
+            // Who asked for this: the subject themselves (self-service deletion)
+            // or a staff member acting on their behalf. Plain nullable type+id
+            // columns rather than morphs() — only ever one of two concrete actor
+            // types, not an open-ended polymorphic set.
+            $table->string('requested_by_type');
+            $table->unsignedBigInteger('requested_by_id');
+            $table->string('status')->default('pending');
+            // Set only on a Customer-scoped request that was auto-created because
+            // erasing a User left them as the sole remaining user on that Customer
+            // (see Modules\Core\Privacy\Listeners\CascadeCustomerErasureListener).
+            // Null for every normal, directly-requested erasure. Lets login-
+            // reactivation find and revert exactly the Customer request THIS
+            // User's cancellation caused, without touching an unrelated,
+            // independently-requested Customer erasure the User happens to be
+            // linked to.
+            $table->foreignId('caused_by_request_id')->nullable()->constrained('data_erasure_requests')->nullOnDelete();
+            // now() + config('core.privacy.grace_period_days') at creation time —
+            // when privacy:process-erasure-requests will actually run this.
+            $table->timestamp('scheduled_for');
+            $table->timestamp('cancelled_at')->nullable();
+            $table->timestamp('completed_at')->nullable();
+            // Every provider's outcome, written once the request completes —
+            // see Modules\Core\Privacy\ErasureReport. Null until then.
+            $table->json('report')->nullable();
+            $table->timestamps();
+
+            $table->index(['status', 'scheduled_for']);
+            $table->index(['subject_type', 'subject_id']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('data_erasure_requests');
+    }
+};

database/migrations/2026_08_24_000003_create_data_export_requests_table.php

@@ -0,0 +1,36 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('data_export_requests', function (Blueprint $table) {
+            $table->id();
+            // Polymorphic, not a fixed customer_id — see data_erasure_requests
+            // for the same shape and reasoning.
+            $table->string('subject_type');
+            $table->unsignedBigInteger('subject_id');
+            // Snapshot, not a live lookup — same reasoning as
+            // data_erasure_requests.email (see that migration).
+            $table->string('email')->nullable();
+            $table->string('status')->default('pending');
+            // Storage path of the assembled export .zip, set once the queued job
+            // finishes. Null while pending.
+            $table->string('file_path')->nullable();
+            $table->timestamp('completed_at')->nullable();
+            $table->timestamps();
+
+            $table->index('status');
+            $table->index(['subject_type', 'subject_id']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('data_export_requests');
+    }
+};

database/migrations/2026_08_31_000001_create_payment_methods_table.php

@@ -0,0 +1,24 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('payment_methods', function (Blueprint $table) {
+            $table->id();
+            $table->string('type')->unique();
+            $table->boolean('enabled')->default(true);
+            $table->json('data')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('payment_methods');
+    }
+};

database/migrations/2026_09_03_000001_add_cascade_delete_to_product_reviews_product_id.php

@@ -0,0 +1,43 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * product_reviews.product_id's original foreign key (2026_07_10_000001) had
+ * no ON DELETE clause, so deleting a Product with reviews throws a
+ * constraint violation instead of the review rows going with it — unlike
+ * every other Product-dependent table (variants, media, etc.), which does
+ * cascade. A review is dependent, disposable data, not something worth
+ * blocking a product deletion over.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('product_reviews', function (Blueprint $table) {
+            $table->dropForeign(['product_id']);
+        });
+
+        Schema::table('product_reviews', function (Blueprint $table) {
+            $table->foreign('product_id')
+                ->references('id')
+                ->on(config('lunar.database.table_prefix').'products')
+                ->cascadeOnDelete();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('product_reviews', function (Blueprint $table) {
+            $table->dropForeign(['product_id']);
+        });
+
+        Schema::table('product_reviews', function (Blueprint $table) {
+            $table->foreign('product_id')
+                ->references('id')
+                ->on(config('lunar.database.table_prefix').'products');
+        });
+    }
+};

database/migrations/2026_09_03_000001_create_stripe_payment_intents_table.php

@@ -0,0 +1,46 @@
+<?php
+
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+use Lunar\Base\Migration;
+
+/**
+ * First-party copy of lunarphp/stripe's own create_stripe_payment_intents_table
+ * migration (package removed in favour of depending on stripe/stripe-php
+ * directly — see Modules\Core\Payment\Support\StripeManager and
+ * Modules\Core\Payment\Models\StripePaymentIntent, which replace the
+ * package's own classes over this same table). Timestamped to run just
+ * before this app's own add_context_to_stripe_payment_intents migration,
+ * which already alters this table.
+ *
+ * Guarded with hasTable(): on any environment that already ran
+ * lunarphp/stripe's own copy of this migration before the package was
+ * removed, the table already exists — this migration is only the one that
+ * actually creates it on a fresh install/database from now on.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        if (Schema::hasTable($this->prefix.'stripe_payment_intents')) {
+            return;
+        }
+
+        Schema::create($this->prefix.'stripe_payment_intents', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('cart_id')->constrained($this->prefix.'carts');
+            $table->foreignId('order_id')->nullable()->constrained($this->prefix.'orders');
+            $table->string('intent_id')->index();
+            $table->string('status')->nullable();
+            $table->string('event_id')->index()->nullable();
+            $table->timestamp('processing_at')->nullable();
+            $table->timestamp('processed_at')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists($this->prefix.'stripe_payment_intents');
+    }
+};

database/migrations/2026_09_03_000002_add_context_to_stripe_payment_intents.php

@@ -0,0 +1,47 @@
+<?php
+
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+use Lunar\Base\Migration;
+
+/**
+ * lunarphp/stripe's own stripe_payment_intents table already correlates a
+ * Stripe intent back to a cart/order via cart_id/order_id — exactly what
+ * Modules\Core\Payment\Drivers\StripePaymentDriver needs to recover
+ * $context in handleCallback(), a separate request (a webhook) from the
+ * pay()/authorize() call that originated it. Two columns this driver
+ * needs that the vendor table doesn't have:
+ *   - context: the full opaque $context bag pay()/authorize() received,
+ *     stored so handleCallback() can dispatch the SAME context the
+ *     original call would have, without Payment inventing its own
+ *     correlation table — see docs/payments.md "Async resolution".
+ *   - payment_type: the payment type key (e.g. 'stripe') pay()/authorize()
+ *     were called with — needed to dispatch Payment events with the
+ *     correct $type in handleCallback(), which otherwise has no way to
+ *     know it (a webhook payload doesn't carry it).
+ *
+ * Extends Lunar\Base\Migration (not the plain base Migration) so $this->prefix
+ * resolves the SAME table-prefix config every Lunar-owned table uses
+ * (config('lunar.database.table_prefix')) — the vendor migration that
+ * creates this table (lunarphp/stripe's create_stripe_payment_intents_table)
+ * already does this, so a store running with a non-default prefix (this
+ * one runs with 'lunar_') would otherwise have this migration fail against
+ * a table name that doesn't exist.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table($this->prefix.'stripe_payment_intents', function (Blueprint $table) {
+            $table->json('context')->nullable()->after('status');
+            $table->string('payment_type')->nullable()->after('context');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table($this->prefix.'stripe_payment_intents', function (Blueprint $table) {
+            $table->dropColumn(['context', 'payment_type']);
+        });
+    }
+};

database/migrations/2026_09_05_000001_add_driver_columns_to_payment_methods.php

@@ -0,0 +1,52 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Moves the driver mapping and per-type behavior that used to live in
+ * config('lunar.payments.types.{type}.*') onto the PaymentMethod row
+ * itself — same DB-instance-vs-config split Modules\Core\Shipping's own
+ * shipping_methods table already has (code/driver/name/enabled columns,
+ * no driver mapping in any config file). See docs/payments.md.
+ *
+ *   - driver: the Modules\Core\Payment\Services\PaymentDriverRegistry key
+ *     (NOT the same as `type` — two rows can share one driver).
+ *   - name: admin-facing label. Nothing played this role before; `type`
+ *     was always the machine slug.
+ *   - capture_mode / captured_status / authorized_status: per-instance
+ *     behavior — fails the "would a store ever want two different answers
+ *     to this" cross-cutting-config test, so these move off config.
+ *   - position: admin-controlled display/checkout order.
+ *   - driver_missing_at: set by the payment:sync-drivers command when
+ *     `driver` no longer resolves via the registry — deliberately
+ *     separate from `enabled`, so a driver vanishing (a deploy removed
+ *     it) is never confused with an admin's own manual toggle, and a
+ *     driver that comes back later auto-clears this with no admin action.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('payment_methods', function (Blueprint $table) {
+            $table->string('name')->nullable()->after('type');
+            $table->string('driver')->nullable()->after('name');
+            $table->string('capture_mode')->nullable()->after('driver');
+            $table->string('captured_status')->nullable()->after('capture_mode');
+            $table->string('authorized_status')->nullable()->after('captured_status');
+            $table->unsignedInteger('position')->default(0)->after('authorized_status');
+            $table->timestamp('driver_missing_at')->nullable()->after('position');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('payment_methods', function (Blueprint $table) {
+            $table->dropColumn([
+                'name', 'driver', 'capture_mode', 'captured_status',
+                'authorized_status', 'position', 'driver_missing_at',
+            ]);
+        });
+    }
+};

database/migrations/2026_09_08_000001_add_refunded_status_to_payment_methods.php

@@ -0,0 +1,38 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * captured_status/authorized_status (added in 2026_09_05_000001) cover a
+ * payment being taken, but nothing wrote Order.status on a REFUND —
+ * Order::paymentStatus() (Order\Support\OrderStatus::payment(), derived
+ * live from transactions) already reflects a refund correctly, but the
+ * stored status column — the one admin filtering, customer emails, etc.
+ * actually key off — never moved. Same reasoning as captured_status/
+ * authorized_status: a store could plausibly want a different resulting
+ * status per payment method (e.g. a "Refunded" vs. a "Refund Pending"
+ * variant), so this is a PaymentMethod column, not cross-cutting config.
+ *
+ * Deliberately no separate void_status — void never moved money (it
+ * releases an authorization hold before any capture), so it doesn't carry
+ * the same "the customer needs to see this changed" weight a refund does;
+ * add one later if a real need for it shows up.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('payment_methods', function (Blueprint $table) {
+            $table->string('refunded_status')->nullable()->after('authorized_status');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('payment_methods', function (Blueprint $table) {
+            $table->dropColumn('refunded_status');
+        });
+    }
+};

database/migrations/2026_09_11_000001_add_status_axes_to_orders_table.php

@@ -0,0 +1,43 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Splits Lunar's single flat `status` column into three independently
+ * tracked axes — payment, fulfillment, return — so a payment refund and a
+ * fulfillment dispatch stop racing to write the same field, and each axis
+ * can be filtered/queried directly instead of overloading one string for
+ * three unrelated concerns. See Modules\Core\Order\Enums\OrderPaymentStatus/
+ * OrderFulfillmentStatus/OrderReturnStatus for the value vocabularies, and
+ * Modules\Core\Order\Listeners\ApplyResolvedPaymentStatus and friends for
+ * where these columns actually get written. `status` itself is left in
+ * place, unchanged — Lunar core still reads/writes it in places this
+ * package doesn't own — but nothing in this package's business logic keys
+ * off it anymore after this migration's consumers land.
+ *
+ * lunar_customers already has a direct precedent for a boboko-core
+ * migration altering a Lunar-owned table (see
+ * 2026_07_02_000002_drop_otp_from_lunar_customers_table.php) — this is not
+ * a new pattern for this codebase, just the first time it's applied to
+ * lunar_orders.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('lunar_orders', function (Blueprint $table) {
+            $table->string('payment_status')->default('awaiting_payment')->after('status')->index();
+            $table->string('fulfillment_status')->default('unfulfilled')->after('payment_status')->index();
+            $table->string('return_status')->default('none')->after('fulfillment_status')->index();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('lunar_orders', function (Blueprint $table) {
+            $table->dropColumn(['payment_status', 'fulfillment_status', 'return_status']);
+        });
+    }
+};

database/migrations/2026_09_11_000002_create_order_status_transitions_table.php

@@ -0,0 +1,42 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Append-only audit trail for Order's three status axes (see
+ * 2026_09_11_000001_add_status_axes_to_orders_table.php) — the thing
+ * `Lunar\Models\Order::getDefaultLogExcept()` explicitly denies (`status`
+ * is excluded from Lunar's own Spatie activity log), so this is a
+ * from-scratch mechanism, not a gap in an existing one.
+ *
+ * No `updated_at` — a row is never edited after it's written, only ever
+ * inserted. `event_class` is the FQCN of whatever business event/action
+ * caused the write (e.g. Modules\Core\Order\Events\OrderDispatched, or a
+ * plain string like 'Modules\Core\Shipping\Extensions\OrderViewExtension::
+ * markDispatchedAction' for a manual Filament action that has no backing
+ * event class of its own) — see Modules\Core\Order\Services\
+ * OrderStatusTransitionRecorder.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('order_status_transitions', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('order_id')->constrained('lunar_orders')->cascadeOnDelete();
+            $table->string('axis');
+            $table->string('from_status')->nullable();
+            $table->string('to_status');
+            $table->string('event_class');
+            $table->timestamp('created_at')->useCurrent();
+            $table->index(['order_id', 'axis']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('order_status_transitions');
+    }
+};

database/migrations/2026_09_11_000003_backfill_order_status_axes.php

@@ -0,0 +1,79 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Lunar\Models\Order;
+use Modules\Core\Order\Enums\PaymentStatus;
+use Modules\Core\Order\Support\OrderStatus;
+
+/**
+ * Maps every existing order's flat `status` (as it stood before
+ * 2026_09_11_000001_add_status_axes_to_orders_table.php) onto the new
+ * payment_status/fulfillment_status/return_status columns. A separate
+ * migration from the schema change so the schema migration stays simply
+ * reversible via down(), and this data pass can be independently re-run.
+ *
+ * The flat status never captured refunds at all (no 'refunded' value was
+ * ever added to config('lunar.orders.statuses')), so the table-driven
+ * mapping below is corrected per-order by re-deriving
+ * Modules\Core\Order\Support\OrderStatus::payment() — the existing,
+ * unchanged derived-enum logic — and overriding payment_status to
+ * refunded/partially_refunded wherever it disagrees with the flat-status
+ * mapping. This is the one place the "keep the old derived enums" design
+ * decision earns its keep: refund-fraction math isn't reimplemented here,
+ * just reused.
+ */
+return new class extends Migration
+{
+    private const MAP = [
+        'awaiting-payment' => ['payment_status' => 'awaiting_payment', 'fulfillment_status' => 'unfulfilled'],
+        'payment-offline' => ['payment_status' => 'awaiting_payment', 'fulfillment_status' => 'unfulfilled'],
+        'payment-received' => ['payment_status' => 'paid', 'fulfillment_status' => 'unfulfilled'],
+        'ready-for-dispatch' => ['payment_status' => 'paid', 'fulfillment_status' => 'ready'],
+        'ready-for-pickup' => ['payment_status' => 'paid', 'fulfillment_status' => 'ready'],
+        'dispatched' => ['payment_status' => 'paid', 'fulfillment_status' => 'in_transit'],
+        'completed' => ['payment_status' => 'paid', 'fulfillment_status' => 'completed'],
+    ];
+
+    public function up(): void
+    {
+        Order::query()->with('transactions')->chunkById(200, function ($orders) {
+            foreach ($orders as $order) {
+                $mapped = self::MAP[$order->status] ?? null;
+
+                if ($mapped === null) {
+                    Log::warning('Order status axis backfill: unmapped status, leaving column defaults', [
+                        'order_id' => $order->id,
+                        'status' => $order->status,
+                    ]);
+
+                    continue;
+                }
+
+                $paymentStatus = $mapped['payment_status'];
+
+                $derived = OrderStatus::payment($order);
+
+                if ($derived === PaymentStatus::Refunded) {
+                    $paymentStatus = 'refunded';
+                } elseif ($derived === PaymentStatus::PartialRefund) {
+                    $paymentStatus = 'partially_refunded';
+                }
+
+                DB::table('lunar_orders')->where('id', $order->id)->update([
+                    'payment_status' => $paymentStatus,
+                    'fulfillment_status' => $mapped['fulfillment_status'],
+                    'return_status' => 'none',
+                ]);
+            }
+        });
+    }
+
+    public function down(): void
+    {
+        // Column defaults (set in the schema migration) are the correct
+        // "undo" — no need to reverse-map back to the flat status, since
+        // `status` itself was never touched by this migration.
+    }
+};

database/migrations/2026_09_11_000004_drop_status_columns_from_payment_methods_table.php

@@ -0,0 +1,36 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * captured_status/authorized_status/refunded_status let a merchant pick
+ * which per-method Order::status label a payment outcome resulted in — a
+ * mechanism that only made sense while Order.status was the single field
+ * carrying that meaning. Modules\Core\Order\Listeners\
+ * ApplyResolvedPaymentStatus now writes a fixed 3-value payment_status
+ * column instead (see 2026_09_11_000001_add_status_axes_to_orders_table.php);
+ * there is no longer any per-method flexibility to preserve — "paid" is
+ * "paid" regardless of which method captured it. Dropped rather than left
+ * vestigial: keeping them visible in the admin would let a merchant
+ * configure something that silently does nothing.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('payment_methods', function (Blueprint $table) {
+            $table->dropColumn(['captured_status', 'authorized_status', 'refunded_status']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('payment_methods', function (Blueprint $table) {
+            $table->string('captured_status')->nullable();
+            $table->string('authorized_status')->nullable();
+            $table->string('refunded_status')->nullable();
+        });
+    }
+};

database/migrations/2026_09_12_000001_add_paid_to_orders_table.php

@@ -0,0 +1,30 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Order::paid/paid_at — entirely independent of the `status` column (see
+ * Modules\Core\Order\Services\OrderStatusFlow's own docblock for why
+ * payment timing, especially for cash-on-delivery, cannot be modeled as a
+ * status-sequence step). `paid` is the fast-filter boolean; `paid_at` is
+ * when it actually happened.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('lunar_orders', function (Blueprint $table) {
+            $table->boolean('paid')->default(false)->after('status')->index();
+            $table->timestamp('paid_at')->nullable()->after('paid');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('lunar_orders', function (Blueprint $table) {
+            $table->dropColumn(['paid', 'paid_at']);
+        });
+    }
+};

database/migrations/2026_09_12_000002_backfill_single_order_status_and_paid.php

@@ -0,0 +1,116 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Lunar\Models\Order;
+use Modules\Core\Order\Enums\PaymentStatus;
+use Modules\Core\Order\Support\OrderStatus;
+
+/**
+ * Collapses the 3-axis (payment_status/fulfillment_status/return_status)
+ * model this session briefly built — abandoned before shipping — back
+ * onto a single `status` column plus the new independent `paid`/`paid_at`
+ * fields. Must run after 2026_09_12_000001 (adds paid/paid_at) and before
+ * 2026_09_12_000003 (drops the axis columns this migration still reads).
+ *
+ * Priority rule: axis data where it's genuinely non-default (this order
+ * was really moved through the axis system during this session's manual
+ * testing); the legacy `status` column (which may still hold pre-session
+ * hyphenated values) as fallback everywhere else.
+ */
+return new class extends Migration
+{
+    private const LEGACY_MAP = [
+        'awaiting-payment' => 'awaiting_payment',
+        'payment-offline' => 'awaiting_payment',
+        'payment-received' => 'processing',
+        'ready-for-dispatch' => 'ready_for_dispatch',
+        'ready-for-pickup' => 'ready_for_pickup',
+        'dispatched' => 'dispatched',
+        'completed' => 'completed',
+    ];
+
+    /**
+     * Axis fulfillment_status -> new single status, given branch. Axis
+     * 'delivered' folds into 'return_window_open' (same combined-value
+     * decision the going-forward design makes). Axis payment_status is
+     * used only to decide whether a fully-unfulfilled order should read
+     * as 'awaiting_payment' or 'processing'.
+     */
+    private function mapFromAxes(string $payment, string $fulfillment, string $return, bool $isPickup): ?string
+    {
+        if ($return === 'returned') {
+            return 'returned';
+        }
+        if ($return === 'requested') {
+            return 'return_requested';
+        }
+
+        return match ($fulfillment) {
+            'unfulfilled' => $payment === 'paid' ? 'processing' : 'awaiting_payment',
+            'processing' => 'processing',
+            'ready' => $isPickup ? 'ready_for_pickup' : 'ready_for_dispatch',
+            'in_transit' => 'dispatched',
+            'delivered', 'return_window_open' => 'return_window_open',
+            'picked_up' => 'picked_up',
+            'completed' => 'completed',
+            default => null,
+        };
+    }
+
+    public function up(): void
+    {
+        Order::query()->with('transactions')->chunkById(200, function ($orders) {
+            foreach ($orders as $order) {
+                $isPickup = $order->isStorePickupOrder();
+
+                $axisIsDefault = $order->payment_status === 'awaiting_payment'
+                    && $order->fulfillment_status === 'unfulfilled'
+                    && $order->return_status === 'none';
+
+                $status = $axisIsDefault
+                    ? (self::LEGACY_MAP[$order->status] ?? null)
+                    : $this->mapFromAxes($order->payment_status, $order->fulfillment_status, $order->return_status, $isPickup);
+
+                if ($status === null) {
+                    Log::warning('Single-status backfill: unmapped order, defaulting to awaiting_payment', [
+                        'order_id' => $order->id,
+                        'status' => $order->status,
+                        'payment_status' => $order->payment_status,
+                        'fulfillment_status' => $order->fulfillment_status,
+                        'return_status' => $order->return_status,
+                    ]);
+                    $status = 'awaiting_payment';
+                }
+
+                $derived = OrderStatus::payment($order);
+                $paid = $order->payment_status === 'paid'
+                    || in_array($derived, [PaymentStatus::Captured, PaymentStatus::Refunded, PaymentStatus::PartialRefund], true);
+
+                // A refund implies the order concluded via a return —
+                // even one backfilled to an early status (e.g. an order
+                // refunded before fulfillment ever started) is corrected
+                // to refunded/partially_refunded here, not left stuck
+                // pre-fulfillment with no sign a refund ever happened.
+                if ($derived === PaymentStatus::Refunded) {
+                    $status = 'refunded';
+                } elseif ($derived === PaymentStatus::PartialRefund) {
+                    $status = 'partially_refunded';
+                }
+
+                DB::table('lunar_orders')->where('id', $order->id)->update([
+                    'status' => $status,
+                    'paid' => $paid,
+                    'paid_at' => $paid ? ($order->placed_at ?? now()) : null,
+                ]);
+            }
+        });
+    }
+
+    public function down(): void
+    {
+        // No reverse mapping — column defaults (post-rollback of the
+        // schema migrations) are the correct "undo".
+    }
+};

database/migrations/2026_09_12_000003_drop_status_axes_from_orders_table.php

@@ -0,0 +1,34 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Reverses 2026_09_11_000001_add_status_axes_to_orders_table.php — the
+ * 3-axis model was abandoned before shipping in favor of a single
+ * `status` column plus independent `paid`/`paid_at` (see
+ * 2026_09_12_000001/000002). Must run after 2026_09_12_000002, which
+ * still reads these columns for the backfill.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('lunar_orders', function (Blueprint $table) {
+            $table->dropColumn(['payment_status', 'fulfillment_status', 'return_status']);
+        });
+    }
+
+    public function down(): void
+    {
+        // Mirrors 2026_09_11_000001's own down() — restores columns
+        // empty/defaulted, does not attempt to resurrect real per-order
+        // values.
+        Schema::table('lunar_orders', function (Blueprint $table) {
+            $table->string('payment_status')->default('awaiting_payment')->after('paid_at')->index();
+            $table->string('fulfillment_status')->default('unfulfilled')->after('payment_status')->index();
+            $table->string('return_status')->default('none')->after('fulfillment_status')->index();
+        });
+    }
+};

database/migrations/2026_09_12_000004_drop_axis_from_order_status_transitions_table.php

@@ -0,0 +1,33 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * There is only one status column left to audit (plus the synthetic
+ * 'paid' entry — see Modules\Core\Order\Listeners\RecordStatusTransition),
+ * so the `axis` column this table was created with
+ * (2026_09_11_000002_create_order_status_transitions_table.php) no longer
+ * means anything.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('order_status_transitions', function (Blueprint $table) {
+            $table->dropIndex(['order_id', 'axis']);
+            $table->dropColumn('axis');
+            $table->index('order_id');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('order_status_transitions', function (Blueprint $table) {
+            $table->dropIndex(['order_id']);
+            $table->string('axis')->default('status')->after('order_id');
+            $table->index(['order_id', 'axis']);
+        });
+    }
+};

database/migrations/2026_09_12_000005_correct_cash_on_delivery_payment_method_driver.php

@@ -0,0 +1,27 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * The seeded 'cash-on-delivery' PaymentMethod row
+ * (Modules\Core\Command\InstallLunarCommand::seedPaymentMethods()) was
+ * wired to driver => 'offline' — the same immediate-capture driver as
+ * cash-in-hand. That's the bug that made COD "pay immediately" instead of
+ * waiting for staff to confirm cash was actually received. Repoints
+ * already-seeded environments to the new dedicated
+ * Modules\Core\Payment\Drivers\CashOnDeliveryPaymentDriver; the seeder
+ * itself is fixed separately for fresh installs.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        DB::table('payment_methods')->where('type', 'cash-on-delivery')->update(['driver' => 'cash-on-delivery']);
+    }
+
+    public function down(): void
+    {
+        DB::table('payment_methods')->where('type', 'cash-on-delivery')->update(['driver' => 'offline']);
+    }
+};

database/migrations/2026_09_13_000001_rename_return_window_open_status_to_delivered.php

@@ -0,0 +1,30 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * 'return_window_open' is renamed to 'delivered' — same status value,
+ * same meaning (the parcel arrived AND the return window is now open,
+ * still one combined moment — see Modules\Core\Order\Listeners\
+ * AdvanceFulfillmentOnDelivered), just a name a merchant expects to read
+ * on the order page rather than an internal mechanic. Also renames it in
+ * order_status_transitions' audit rows so the history stays consistent
+ * with `status` going forward.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        DB::table('lunar_orders')->where('status', 'return_window_open')->update(['status' => 'delivered']);
+        DB::table('order_status_transitions')->where('from_status', 'return_window_open')->update(['from_status' => 'delivered']);
+        DB::table('order_status_transitions')->where('to_status', 'return_window_open')->update(['to_status' => 'delivered']);
+    }
+
+    public function down(): void
+    {
+        DB::table('lunar_orders')->where('status', 'delivered')->update(['status' => 'return_window_open']);
+        DB::table('order_status_transitions')->where('from_status', 'delivered')->update(['from_status' => 'return_window_open']);
+        DB::table('order_status_transitions')->where('to_status', 'delivered')->update(['to_status' => 'return_window_open']);
+    }
+};

database/migrations/2026_09_13_000002_create_manifests_table.php

@@ -0,0 +1,43 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * A real record of "a manifest was issued", not just a loose
+ * manifest_reference string stamped onto each Shipment row — ACS's own
+ * ACS_Issue_Pickup_List call returns nothing beyond a PickupList_No (see
+ * Modules\Core\Shipping\Carriers\Acs\AcsFulfillmentService::issueManifest()),
+ * so this table is entirely our own bookkeeping: when the manifest was
+ * issued and how many shipments it included, not something re-derivable
+ * from the carrier later. `shipment_count` is denormalized (also
+ * countable via shipments()->count()) purely so the manifests list can
+ * render without an extra query per row.
+ *
+ * carrier-agnostic by design — see Modules\Core\Shipping\Contracts\
+ * SupportsManifestBatching, the same contract any future carrier
+ * (Speedex, etc.) implements to get manifest batching at all; this table
+ * has no ACS-specific columns.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('manifests', function (Blueprint $table) {
+            $table->id();
+            $table->string('carrier');
+            $table->string('reference');
+            $table->unsignedInteger('shipment_count')->default(0);
+            $table->timestamp('issued_at');
+            $table->timestamps();
+
+            $table->unique(['carrier', 'reference']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('manifests');
+    }
+};

database/migrations/2026_09_13_000003_add_manifest_id_to_shipments_table.php

@@ -0,0 +1,82 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Replaces the loose manifest_reference string with a real manifests
+ * relation — see 2026_09_13_000002_create_manifests_table.php. Backfills
+ * one Manifest row per distinct (carrier, manifest_reference) pair
+ * already present in shipments, using the earliest label_printed_at (or
+ * updated_at as a fallback) among that group as a best-effort issued_at,
+ * since the exact original issue time was never recorded anywhere.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('shipments', function (Blueprint $table) {
+            $table->foreignId('manifest_id')->nullable()->after('manifest_reference')->constrained()->nullOnDelete();
+        });
+
+        $groups = DB::table('shipments')
+            ->select('carrier', 'manifest_reference')
+            ->whereNotNull('manifest_reference')
+            ->distinct()
+            ->get();
+
+        foreach ($groups as $group) {
+            $shipments = DB::table('shipments')
+                ->where('carrier', $group->carrier)
+                ->where('manifest_reference', $group->manifest_reference)
+                ->get();
+
+            $issuedAt = $shipments->pluck('label_printed_at')->filter()->min()
+                ?? $shipments->pluck('updated_at')->min();
+
+            $manifestId = DB::table('manifests')->insertGetId([
+                'carrier' => $group->carrier,
+                'reference' => $group->manifest_reference,
+                'shipment_count' => $shipments->count(),
+                'issued_at' => $issuedAt,
+                'created_at' => $issuedAt,
+                'updated_at' => $issuedAt,
+            ]);
+
+            DB::table('shipments')
+                ->where('carrier', $group->carrier)
+                ->where('manifest_reference', $group->manifest_reference)
+                ->update(['manifest_id' => $manifestId]);
+        }
+
+        Schema::table('shipments', function (Blueprint $table) {
+            $table->dropColumn('manifest_reference');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('shipments', function (Blueprint $table) {
+            $table->string('manifest_reference')->nullable()->after('parent_reference');
+        });
+
+        DB::table('shipments')
+            ->whereNotNull('manifest_id')
+            ->orderBy('id')
+            ->each(function ($shipment) {
+                $manifest = DB::table('manifests')->find($shipment->manifest_id);
+
+                if ($manifest) {
+                    DB::table('shipments')->where('id', $shipment->id)->update([
+                        'manifest_reference' => $manifest->reference,
+                    ]);
+                }
+            });
+
+        Schema::table('shipments', function (Blueprint $table) {
+            $table->dropConstrainedForeignId('manifest_id');
+        });
+    }
+};

database/migrations/2026_09_14_000001_add_otp_attempts_to_users_table.php

@@ -0,0 +1,30 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Caps brute-forcing a 6-digit OTP code (1M combinations, 10-minute
+ * window, previously uncapped) — see Modules\Core\Auth\Services\
+ * UserOtpService::validate(), which now invalidates the code entirely
+ * (forcing a fresh generateAndSend()) once otp_attempts reaches its max,
+ * rather than leaving a live code guessable indefinitely within its
+ * expiry window.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('users', function (Blueprint $table) {
+            $table->unsignedTinyInteger('otp_attempts')->default(0)->after('otp_expires_at');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('users', function (Blueprint $table) {
+            $table->dropColumn('otp_attempts');
+        });
+    }
+};

database/migrations/2026_09_15_000001_create_user_sessions_table.php

@@ -0,0 +1,41 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * A per-login session registry, independent of the actual session store
+ * driver (SESSION_DRIVER=redis in this app — no "sessions" table to
+ * purge by user_id the way the database driver would allow). Each
+ * successful OTP login (Modules\Core\Auth\Services\UserOtpService::
+ * validate()) records one row here and stamps the token into the
+ * Laravel session payload; Modules\Core\Auth\Http\Middleware\
+ * EnsureSessionNotRevoked checks it on every request. "Logout
+ * everywhere" (Modules\Core\Auth\Services\UserSessionService::
+ * revokeOtherSessions()) is then just marking every OTHER row
+ * revoked_at, no session-store-specific logic anywhere.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('user_sessions', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
+            $table->string('token', 64)->unique();
+            $table->string('user_agent')->nullable();
+            $table->string('ip_address', 45)->nullable();
+            $table->timestamp('last_used_at');
+            $table->timestamp('revoked_at')->nullable();
+            $table->timestamps();
+
+            $table->index(['user_id', 'revoked_at']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('user_sessions');
+    }
+};

database/migrations/2026_09_15_000001_make_payment_methods_name_translatable.php

@@ -0,0 +1,65 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+use Lunar\Models\Language;
+
+/**
+ * PaymentMethod.name becomes a locale-keyed JSON array (e.g.
+ * {"en": "Cash On Delivery", "el": "Αντικαταβολή"}), rendered in Filament
+ * via Lunar's own Lunar\Admin\Support\Forms\Components\TranslatedText —
+ * the same reusable component/data-shape Product/Collection names already
+ * use (Lunar\Base\Traits\HasTranslations), just applied directly to a
+ * plain column here rather than through attribute_data, since
+ * PaymentMethod is a merchant-configured settings row, not a translatable
+ * catalog attribute.
+ *
+ * Existing plain-string rows are preserved under the store's default
+ * Language code (falls back to 'en' if no Language row exists yet — this
+ * migration can run before lunar:install seeds one) rather than dropped,
+ * so an already-configured payment method's name isn't blanked out.
+ *
+ * Uses a raw `ALTER COLUMN ... TYPE` rather than Blueprint::change()
+ * (which requires doctrine/dbal — not installed in this project) —
+ * Postgres-specific (this project runs on `pgsql`, per its own docker
+ * setup), with an explicit USING clause since json isn't implicitly
+ * castable from varchar.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        $defaultLocale = Language::where('default', true)->value('code') ?? 'en';
+
+        $existing = DB::table('payment_methods')->pluck('name', 'id');
+
+        DB::statement('ALTER TABLE payment_methods ALTER COLUMN name DROP DEFAULT');
+        DB::statement("ALTER TABLE payment_methods ALTER COLUMN name TYPE json USING NULL");
+
+        foreach ($existing as $id => $name) {
+            if ($name === null) {
+                continue;
+            }
+
+            DB::table('payment_methods')
+                ->where('id', $id)
+                ->update(['name' => json_encode([$defaultLocale => $name])]);
+        }
+    }
+
+    public function down(): void
+    {
+        $defaultLocale = Language::where('default', true)->value('code') ?? 'en';
+
+        $existing = DB::table('payment_methods')->pluck('name', 'id');
+
+        DB::statement('ALTER TABLE payment_methods ALTER COLUMN name TYPE varchar(255) USING NULL');
+
+        foreach ($existing as $id => $name) {
+            $decoded = json_decode((string) $name, true);
+            $flat = is_array($decoded) ? ($decoded[$defaultLocale] ?? reset($decoded) ?: null) : $name;
+
+            DB::table('payment_methods')->where('id', $id)->update(['name' => $flat]);
+        }
+    }
+};

database/migrations/2026_09_15_000002_make_shipping_methods_name_translatable.php

@@ -0,0 +1,74 @@
+<?php
+
+use Illuminate\Support\Facades\DB;
+use Lunar\Base\Migration;
+use Lunar\Models\Language;
+
+/**
+ * ShippingMethod.name becomes a locale-keyed JSON array (e.g.
+ * {"en": "Standard Delivery", "el": "Κανονική Παράδοση"}), rendered in
+ * Filament via Lunar's own Lunar\Admin\Support\Forms\Components\
+ * TranslatedText (Modules\Core\Shipping\Extensions\
+ * ShippingMethodResourceExtension::replaceNameField()) — same shape/
+ * resolution as PaymentMethod.name (see its own migration,
+ * 2026_09_15_000001_make_payment_methods_name_translatable.php) and
+ * Product/Collection names (Lunar\Base\Traits\HasTranslations).
+ *
+ * ShippingMethod is a vendor (lunarphp/table-rate-shipping) table, but
+ * converting a vendor column's type via a migration is no different from
+ * any other schema change this project already makes against a vendor
+ * table (see database/migrations/2026_08_31_000001_create_payment_methods_table.php's
+ * sibling migrations for the same pattern against PaymentMethod) — there
+ * was no good reason to route this through `data.name` instead, unlike
+ * `data.fulfillment_type` which is a genuinely NEW field the vendor table
+ * never had at all.
+ *
+ * Existing plain-string rows are preserved under the store's default
+ * Language code (falls back to 'en' if no Language row exists yet)
+ * rather than dropped.
+ *
+ * Uses a raw `ALTER COLUMN ... TYPE` rather than Blueprint::change()
+ * (requires doctrine/dbal — not installed in this project) — Postgres-
+ * specific (this project runs on `pgsql`), with an explicit USING clause
+ * since json isn't implicitly castable from varchar.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        $table = $this->prefix.'shipping_methods';
+        $defaultLocale = Language::where('default', true)->value('code') ?? 'en';
+
+        // The column is NOT NULL (vendor migration never marked it
+        // nullable) — converting via `USING NULL` first, then
+        // backfilling with a second UPDATE, violates that constraint
+        // before the backfill ever runs. json_build_object() converts
+        // each existing string in place, in the same statement, so the
+        // column is never transiently NULL. $defaultLocale is inlined
+        // (not bound) — parameter binding inside an ALTER TABLE ... USING
+        // expression isn't reliable across drivers; it's a Language::code
+        // value we control, not user input, so quote_literal-safe
+        // interpolation here is fine.
+        $quotedLocale = DB::getPdo()->quote($defaultLocale);
+
+        DB::statement("ALTER TABLE {$table} ALTER COLUMN name TYPE json USING json_build_object({$quotedLocale}, name)");
+    }
+
+    public function down(): void
+    {
+        $table = $this->prefix.'shipping_methods';
+        $defaultLocale = Language::where('default', true)->value('code') ?? 'en';
+
+        // Same NOT NULL constraint applies going back — ->>'{locale}'
+        // extracts the default locale's text value directly in the
+        // USING clause, falling back to the first key present via
+        // COALESCE for any row missing that locale (e.g. one only ever
+        // filled in via a non-default language).
+        $quotedLocale = DB::getPdo()->quote($defaultLocale);
+
+        DB::statement(
+            "ALTER TABLE {$table} ALTER COLUMN name TYPE varchar(255) ".
+            "USING COALESCE(name->>{$quotedLocale}, (SELECT value FROM json_each_text(name) LIMIT 1))"
+        );
+    }
+};

database/migrations/2026_09_22_000001_add_custom_fields_to_products_table.php

@@ -0,0 +1,40 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Per-product, customer-authored input fields — a personalized-statue
+ * product needing a reference photo upload and an optional engraving
+ * textarea, for example. Deliberately NOT modeled as a Lunar ProductOption
+ * (see Modules\Core\Catalog\Contracts\ProductOptionTypeInterface's own
+ * docblock): an option's values are a fixed, admin-authored list that
+ * define variants (Red/Green/Blue) — a photo upload has no such list, it's
+ * unique per order, and creates no variant at all. This is a genuinely
+ * different concept that happens to configure on the same product page.
+ *
+ * Array of {key, type: 'text'|'textarea'|'file', label, required} — `key`
+ * is what a submitted answer is keyed by in CartLine/OrderLine.meta (both
+ * already have a `meta` json column — see Modules\Core\Cart\Services\
+ * CartService::addLine()'s own $meta parameter), not a new table, since
+ * this is small, rarely-queried per-product config, the same reasoning
+ * ShippingMethod.data/PaymentMethod.data already follow for their own
+ * per-row settings.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table(config('lunar.database.table_prefix').'products', function (Blueprint $table) {
+            $table->json('custom_fields')->nullable()->after('attribute_data');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table(config('lunar.database.table_prefix').'products', function (Blueprint $table) {
+            $table->dropColumn('custom_fields');
+        });
+    }
+};

database/migrations/2026_09_25_000001_create_files_table.php

@@ -0,0 +1,50 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * A generic, storage-backend-agnostic file registry — Modules\Core\File\
+ * Services\FileService's own backing table. `disk`/`path` are whatever
+ * Laravel's Storage facade already understands (local, s3, ...); this
+ * table adds what Flysystem itself has no concept of: who a file
+ * belongs to, why it was uploaded, and whether anything still needs it.
+ *
+ * `owner_type`/`owner_id` are nullable — a file can (and, for a product
+ * custom-field photo, always does) exist before anything owns it yet: a
+ * shopper picks a photo on the product page and it's uploaded immediately
+ * (see 3dealer's CustomFieldUploadController), well before add-to-cart
+ * gives it a CartLine to belong to. FileService::attachOwner() re-points
+ * these columns once an owner exists, rather than creating a second row
+ * for the same physical file.
+ *
+ * `purpose` (e.g. 'custom-field-upload') lets one table serve unrelated
+ * future features without collision — FileService itself has no
+ * knowledge of what a purpose means, callers scope their own queries by
+ * it.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('files', function (Blueprint $table) {
+            $table->id();
+            $table->string('disk');
+            $table->string('path');
+            $table->string('original_name')->nullable();
+            $table->string('mime')->nullable();
+            $table->unsignedBigInteger('size')->nullable();
+            $table->string('purpose');
+            $table->nullableMorphs('owner');
+            $table->timestamps();
+
+            $table->index(['purpose', 'owner_type', 'owner_id']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('files');
+    }
+};

docs/cart.md

@@ -0,0 +1,280 @@
+# Cart Admin Visibility
+
+`Modules\Core\Cart\Filament\Resources\CartResource` gives staff read-only visibility into
+every cart in the Filament admin panel, guest carts included. Lunar itself ships no cart
+admin view at all — no Filament resource for `Cart`/`CartLine` exists anywhere in
+`lunarphp/lunar` or `lunarphp/core` — this is a from-scratch addition, not an extension of
+something Lunar half-built. See `docs/lunar.md`'s "Cart and Checkout" section for the
+underlying Lunar cart mechanics this resource reads from.
+
+---
+
+## Scope: every cart, identified or not
+
+`CartResource` lists every cart the four lifecycle states (below) cover, with no
+`user_id`/`customer_id` filter — an anonymous guest's session cart is included.
+
+This was a reversal of an earlier, deliberate call to exclude guest carts entirely (on the
+reasoning that an anonymous cart carries no identity a staff member could act on — no name, no
+email, nothing to follow up with — so listing every guest session cart would be noise, not a
+real admin capability). That reasoning holds for "can I click through to a Customer record,"
+but not for the resource's other real use — seeing how many carts are ongoing/abandoned right
+now regardless of who's shopping. Most real storefront traffic never reaches an identified
+user/customer, so excluding it silently undercounts exactly the thing `ListCarts`'s tabs (and
+`CartLifecycleService`, which they and `DetectAbandonedCarts` both build on) exist to report
+on. The `Customer`/`User` columns on a guest row just render "—" (Filament's `placeholder()`)
+instead of a link — nothing to click into, but the row and its contents are still visible via
+`ViewCart`.
+
+This does **not** mirror Shopify's admin (Shopify has no "all carts" view at all — only
+"Abandoned checkouts," gated on a shopper reaching checkout and entering contact info, a
+later/narrower stage than Lunar's `Cart`).
+
+---
+
+## Four states, not two — and not `Cart::completed_at`
+
+`Lunar\Models\Cart::completed_at` is declared and cast (`'completed_at' => 'datetime'`) but
+**never actually written anywhere in Lunar core** — grep `vendor/lunarphp/core/src` for it;
+the only hits are the property declaration and the cast. It is not a real signal. `Cart` has
+no `status` column at all — every state below is derived from relations/timestamps, not a
+single field.
+
+`Cart::scopeActive()` (Lunar's own "not yet converted to an order" scope) actually mixes two
+distinct states together: no order ever started, vs. a draft order exists
+(`placed_at IS NULL`) but was never placed — checkout was started, not finished. Those are
+different purchase-intent signals (see "Abandoned Cart vs Abandoned Checkout" below) and
+different reachability (checkout usually captures an email even for a guest), so
+`ListCarts::getTabs()` splits them into four tabs instead of `scopeActive()`'s two-state
+split.
+
+`Modules\Core\Cart\Services\CartLifecycleService` is the single source of truth for these four
+query shapes — both `ListCarts::getTabs()` (staff browsing) and `DetectAbandonedCarts`
+(abandonment-event dispatch) build on it, rather than each reimplementing the same split
+independently (which is what happened before this service existed, and is exactly the kind of
+drift that lets the admin panel and the recovery-email pipeline quietly disagree about what
+"abandoned" means):
+
+- **Ongoing** (`ongoing()`) — `scopeActive()` and recent `updated_at` (within
+  `abandonedCutoff()`). Default active tab on page load.
+- **Abandoned Cart** (`abandonedCarts()`) — `whereDoesntHave('orders')` and stale
+  `updated_at`.
+- **Abandoned Checkout** (`abandonedCheckouts()`) — has an order with `placed_at IS NULL`,
+  and stale `updated_at`.
+- **Completed** (`completed()`) — has an order with `placed_at IS NOT NULL`.
+
+Each method takes a `Builder` and returns it further scoped, so callers compose it onto
+whatever base query they already have (`CartResource::getEloquentQuery()` for the Filament
+tabs, a bare `Cart::query()` for the command). Deliberately query-shape-only: consent
+(`meta->recovery_consent`) and non-empty-lines filtering stay in `DetectAbandonedCarts`, not on
+the service — those gate whether a recovery *event* should fire, not what "abandoned" means to
+a staff member browsing the list.
+
+There is deliberately **no "All" tab.** Every row shown is always scoped to one of the four
+states above — the list never runs an unfiltered `Cart::query()->get()` over the whole
+(potentially large) table.
+
+### Abandoned Cart vs Abandoned Checkout — why they're not one bucket
+
+Different purchase intent, different reachability, and different recovery strategy — see
+`docs/recovery-strategies.md` for the full marketing-strategy discussion. In short:
+
+- **Abandoned Cart** (no order started) is a weak intent signal — often window-shopping, not
+  a near-purchase. Frequently unreachable (no email/identity at all for a true guest).
+  Recovery leans on on-site retargeting and ad remarketing rather than email.
+- **Abandoned Checkout** (draft order, never placed) is a strong intent signal — the shopper
+  committed to buying and something blocked completion. Checkout typically captures contact
+  info even for a guest, so this state is usually reachable. This is the state the
+  researched 1h/24h/72h recovery-email cadence targets specifically.
+
+`Modules\Core\Cart\Events\CartAbandoned` and `Modules\Core\Checkout\Events\CheckoutAbandoned`
+mirror this same split (see "Events" below) rather than one combined event.
+
+---
+
+## Why this scales fine at a large cart count
+
+Two things keep this cheap regardless of how many carts exist (10,000+):
+
+- **The list is always paginated.** Filament applies `LIMIT`/`OFFSET` to whichever tab's
+  query is active — a page only ever fetches one page's worth of rows, never the whole
+  table, "All" tab or not (and there is no "All" tab — see above).
+- **No per-row queries.** `lines_count`/`lines_sum_quantity` use Filament's built-in
+  `->counts('lines')`/`->sum('lines', 'quantity')`, which fold into the same query as the
+  rest of the list (one `LEFT JOIN`-based aggregate, not N separate lookups). There's no
+  per-record `getStateUsing()` closure anywhere in this table doing its own query — that's
+  the pattern to avoid if a future column needs derived data (see `Modules\Core\Catalog\
+  Services\ProductIndexer` for the general "compute once at index time / one aggregate
+  query, never per-row" principle this project follows elsewhere).
+
+The one thing that **does** scan more rows as the cart count grows is
+`CartResource::getNavigationBadge()` (see below) — but it's a `COUNT(*)`, not a fetch, and
+runs once per admin page load, not once per cart row.
+
+---
+
+## Navigation badge — abandoned cart count
+
+```php
+public static function getNavigationBadge(): ?string
+{
+    return (string) static::getEloquentQuery()->active()->where('updated_at', '<=', static::abandonedCutoff())->count();
+}
+```
+
+Shows the number of abandoned carts (not all carts — a converted cart isn't something a
+staff member needs to keep noticing) next to "Carts" in the sidebar. `->count()` compiles to
+a single `SELECT COUNT(*) ...` — confirmed via query log — no rows are ever loaded just to
+render the badge.
+
+---
+
+## The view page runs the cart's full calculate pipeline — once
+
+`ViewCart::resolveRecord()` calls `$cart->calculate()` before rendering, since `CartLine`'s
+computed properties (`unitPrice`, `total`, etc.) and `Cart`'s own totals (`subTotal`, `total`,
+...) are plain public properties populated as a side effect of that pipeline — never
+persisted, so a plain Eloquent-fetched `Cart` has them all `null`/unset (see `docs/lunar.md`
+Gotchas). This only runs on the single-record view page, not per row in the list table —
+running the full 5-step pipeline for every row of a paginated list would be needless cost for
+data the list doesn't display.
+
+---
+
+## Not built: staff editing a cart
+
+The resource is deliberately read-only (`canCreate()` returns `false`, no edit page
+registered). A cart is owned by the storefront's own add/update/remove flow
+(`CartSession`/`Cart::add()`/etc.) — hand-editing cart contents from the admin panel isn't a
+supported use case here.
+
+---
+
+## `CartService` — the storefront-facing API
+
+`Modules\Core\Cart\Services\CartService` mirrors `Modules\Core\Catalog\Services\
+ProductService`/`CollectionService`'s shape — one boboko-owned API a storefront calls, so
+Lunar's own `CartSession`/`Cart` stay an implementation detail rather than something a
+consuming app depends on directly.
+
+- `current()` / `currentOrCreate()` — the latter force-creates a cart (`CartSession::manager()`),
+  the former doesn't (`CartSession::current()`, returns `null` for a fresh visitor — see
+  `docs/lunar.md`'s Cart gotchas).
+- `addLine()` / `updateLine()` / `removeLine()` / `clear()` — thin wrappers over
+  `Cart::add()`/`updateLine()`/`remove()`/`clear()`. No boboko-owned exception types wrap
+  Lunar's own cart exceptions (`InvalidCartLineQuantityException`, `CartLineIdMismatchException`,
+  etc.) — they propagate as-is; a wrapper would add indirection with identical semantics.
+- `applyCoupon()` / `removeCoupon()` — sets/clears `Cart::coupon_code` (there's no dedicated
+  Lunar action for this, unlike add/update/remove). `applyCoupon()` validates via
+  `Discounts::validateCoupon()` first and throws `Modules\Core\Cart\Exceptions\
+  InvalidCouponException` on a bad code — `CouponString`'s cast only normalizes casing, it
+  doesn't validate anything, so setting `coupon_code` directly would silently accept a bogus
+  code and just not discount anything once calculated.
+- `saveForLater()` / `moveToCart()` / `activeLines()` / `savedLines()` — see "Save for later"
+  below.
+
+Every mutating method returns the recalculated `Cart` (matching Lunar's own `Cart::add()`
+etc., which already return `$this` after `refresh()->recalculate()`) and dispatches a
+matching domain event.
+
+### Events — Lunar dispatches none of its own
+
+`Lunar` dispatches zero cart events — no "item added," no "cart created" (see
+`docs/lunar.md`'s Cart gotchas). `CartService` fills that gap with its own, dispatched after
+the underlying Lunar operation completes:
+
+`CartLineAdded`, `CartLineUpdated`, `CartLineRemoved`, `CartCleared`, `CartCouponApplied`,
+`CartCouponRemoved`, `CartLineSaved`, `CartLineMovedToCart` — all under
+`Modules\Core\Cart\Events`. `CartAbandoned`/`CheckoutAbandoned` live under
+`Modules\Core\Recovery\Events` instead, not `Cart`/`Checkout` — see "Abandonment detection"
+below for why.
+
+**None of these currently have a listener.** They're dispatched-but-unconsumed by design —
+built so something downstream (reindexing, notifications, a future read-side reporting
+service) has a hook to attach to, not because a concrete consumer exists today. This was a
+deliberate decision, not an oversight — see the "don't build speculative infrastructure"
+calls made elsewhere in this project (e.g. not wrapping Lunar's cart exceptions).
+
+**Why not wired to Spatie's Activity Log:** `Cart`/`CartLine` already use Lunar's own
+`LogsActivity` trait (Spatie's package, Lunar's defaults) — confirmed from source, this logs
+model saves/deletes automatically, independent of actor. `Modules\Core\Logging\
+ActivityLogService` (this project's own wrapper, used by e.g. `LogTranslationActivity`) is
+hardcoded to the `staff` guard — correctly scoped for staff-driven writes (Filament admin
+actions), but wrong for customer-driven cart activity, which would resolve `causedBy()` to
+`null` every time. Both `ActivityLogService` and `Cart`/`CartLine`'s native `LogsActivity`
+write to the **same** `log_name = 'lunar'` / `activity_log` table, with no built-in
+separation beyond reading `causer_type` per row — a real limitation worth knowing about, but
+not one this project is fixing by giving Cart a distinct `log_name`, since every other Lunar
+model logs to `'lunar'` too and a Cart-only carve-out would just be inconsistent. The
+intended fix, if this becomes a real need, is a read-side service that queries `activity_log`
+and classifies by `causer_type`/`log_name` — not touching every write site.
+
+### Save for later
+
+A `CartLine` can be moved out of the purchasable cart without being deleted — flagged via
+`meta.saved_for_later`, not a new column (matches the free-form-JSON pattern already used
+elsewhere, e.g. `ProductOptionValue::meta`). `Modules\Core\Cart\Pipelines\
+ZeroSavedForLaterPrice` (registered in `config('lunar.cart.pipelines.cart_lines')`, after the
+stock `GetUnitPrice`) zeroes `unitPrice`/`unitPriceInclTax` for flagged lines **before**
+Lunar's own `CalculateLines` pipeline step sums the cart — `CalculateLines` sums every
+`CartLine` unconditionally with no meta-based exclusion of its own, so zeroing the price
+upstream is what makes `Cart::subTotal`/`total` naturally correct without a second pass or
+callers needing a different totals accessor.
+
+`Lunar\Actions\Carts\UpdateCartLine` **replaces** the whole `meta` column on write (plain
+`update(['meta' => $meta])`, not a merge) — `saveForLater()`/`moveToCart()` read the line's
+existing meta and merge in the flag change before calling `Cart::updateLine()`, or an
+unrelated meta key set by something else would be silently wiped.
+
+### Coupons
+
+See `CartService::applyCoupon()`/`removeCoupon()` above. `Lunar\Base\Casts\CouponString`
+just upper-cases the code; `Lunar\Managers\DiscountManager::validateCoupon()` (via the
+`Discounts` facade) is the actual check — does a matching `Discount` (type `AmountOff` or
+`BuyXGetY`) exist, `active()`, with `max_uses` not exhausted.
+
+---
+
+## Abandonment detection
+
+"Abandoned" is a **derived** state (`Cart::updated_at` older than
+`config('core.cart.abandoned_after')`, default `1 hour`) — nothing transitions a cart into it
+via a normal Eloquent write, so there's no model-event hook to dispatch from directly.
+`Modules\Core\Cart\Commands\DetectAbandonedCarts` (registered on an hourly schedule by
+`Modules\Core\Providers\CartServiceProvider`) is the only place that moment gets detected: it
+builds on the same `CartLifecycleService::abandonedCarts()`/`abandonedCheckouts()` queries
+`ListCarts::getTabs()` uses (no order at all vs. draft order never placed) and dispatches
+`Modules\Core\Recovery\Events\CartAbandoned`/`CheckoutAbandoned` for anything currently stale
+that also has `meta->recovery_consent = true`.
+
+### Cart/Checkout have zero abandonment-related writes — by design
+
+`DetectAbandonedCarts` **only dispatches** — it never writes to `Cart`/`Order` at all. An
+earlier version recorded an "already notified" marker on `Cart::meta`/`Order::meta` to avoid
+refiring the same event every run, but that `->save()` call bumped `Cart::updated_at` as an
+Eloquent side effect — since `updated_at` is also the field abandonment staleness is computed
+from, the write **un-staled the very cart it had just marked abandoned**: confirmed live, a
+cart that correctly fired `CartAbandoned` showed back up as "Ongoing," not "Abandoned Cart,"
+on the very next tab-count check.
+
+The fix wasn't to write the marker more carefully — it was to stop `Cart`/`Checkout` from
+having any way to write abandonment state at all. Deduplication ("has this cart already been
+notified") is deliberately **not** this command's job; it belongs to `Recovery` (not yet
+built — see `docs/recovery-strategies.md`), which will own its own tracking table, keeping
+`Cart`/`Order` permanently free of abandonment-related columns or `meta` keys.
+
+**Current tradeoff, accepted deliberately**: until `Recovery` exists, every cart still
+matching the "abandoned" query refires its event on every hourly run — there is no dedup at
+all right now. That's fine today only because nothing consumes these events yet (see
+"Events" above); it would need addressing before anything real listens for them.
+
+---
+
+## Recovery Sequences — design only, not built
+
+See `docs/recovery-strategies.md` — a full marketing-strategy discussion and a first-pass
+feature design for an admin-configurable sequence of "touches" (delay + optional discount +
+label) per abandonment type. Explicitly parked as an open design question, not scoped for
+implementation yet — whether this belongs under `Cart`, a new `Recovery`/`Marketing` concern,
+and how far the touch model needs to flex (channel choice, value-based branching, segment
+targeting) are all still undecided.

docs/checkout.md

@@ -0,0 +1,155 @@
+# Checkout — Design Notes
+
+**Status: design finalized, not yet built.** This is the design spec for
+`Modules\Core\Checkout\Services\CheckoutService`, plus the three-stage lifecycle model it's
+part of. Nothing in this document is implemented yet.
+
+---
+
+## Three-stage lifecycle: Cart → Checkout → Order
+
+Each stage is its own concern, not a phase inside a shared one — matching the pattern already
+established this session (`Recovery` was split out from `Cart` specifically because
+abandonment detection is a different lifecycle stage than line-item mutation, even though it
+reads `Cart` state).
+
+- **`Cart`** — line items, coupons, save-for-later (`docs/cart.md`). Ends the moment
+  `Cart::createOrder()` is called.
+- **`Checkout`** — the placement moment itself: setting addresses, selecting a shipping
+  option, placing the order. Starts where Cart ends, ends the instant an `Order` exists.
+  This document.
+- **`Order`** — everything after an order exists: status transitions (`Order::status`,
+  changed via the Filament admin `EditOrder` page — always staff-driven, never part of
+  checkout itself), fulfillment/shipment tracking. **Named and scoped here, not yet built** —
+  same status as `Recovery` before it existed as real code.
+
+`Modules\Core\Checkout\Events\OrderPlaced` (see below) is the handoff point: `Checkout`
+dispatches it the moment an order exists; `Order`'s own listeners (not built yet) would be
+what reacts to it — e.g. sending a confirmation email, initializing whatever `Order` needs to
+initialize. `Checkout` itself has no opinion about what happens after `OrderPlaced` fires.
+
+### Where `Order` would likely absorb work that currently lives under `Shipping`
+
+`Modules\Core\Shipping`'s `Shipment`/`ShipmentInfo` models are already order-scoped
+(`Shipment::order(): BelongsTo`), and `PollShipmentTrackingJob`/
+`ShipmentStatusUpdatedByCarrier` are fulfillment/tracking concerns that happen entirely after
+an order exists — conceptually closer to `Order` than to `Shipping`'s actual job (carrier
+rate quoting, `ShippingRateInterface` drivers, `ShippingManifest`). Not decided whether/when
+this gets moved; noted here so the boundary is visible when `Order` is actually scoped.
+
+---
+
+## `CheckoutService`
+
+Mirrors `Modules\Core\Cart\Services\CartService`'s shape (see `docs/cart.md`) — one
+boboko-owned API a storefront calls, keeping Lunar's own `Cart`/`ShippingManifest` primitives
+an implementation detail.
+
+| Method | Wraps | Dispatches |
+|---|---|---|
+| `setShippingAddress(array\|Addressable $address)` | `Cart::setShippingAddress()` | `ShippingAddressSet($cart, $address)` |
+| `setBillingAddress(array\|Addressable $address)` | `Cart::setBillingAddress()` | `BillingAddressSet($cart, $address)` |
+| `getShippingOptions()` | `ShippingManifest::getOptions($cart)` | — (read-only) |
+| `selectShippingOption(string $identifier)` | `Cart::setShippingOption()` | `ShippingOptionSelected($cart, $option)` — throws `InvalidShippingOptionException` if `$identifier` doesn't resolve |
+| `placeOrder(string $fingerprint)` | `Cart::checkFingerprint()` then `Cart::createOrder()` | `OrderPlaced($order)` |
+
+### `getShippingOptions()` — already fully backed by the merged Shipping-Carriers work
+
+`ShippingManifest::getOptions($cart)` runs every registered `ShippingRateInterface` driver
+through a pipeline — this already includes ACS/Box Now live-rate quoting
+(`Modules\Core\Shipping\Carriers\Acs\AcsRateDriver`/`BoxNowRateDriver`, merged from the
+`Shipping-Carriers` branch) alongside `table-rate-shipping`'s own flat-rate/free-shipping/
+collection drivers. `CheckoutService` doesn't need to build any rate-resolution logic — it's
+a thin pass-through to what already exists and works.
+
+### `placeOrder()` — fingerprint check is mandatory, not optional
+
+`placeOrder(string $fingerprint): Order` requires the fingerprint the shopper's last-seen
+cart total was built from (`Cart::fingerprint()`) as a parameter — not an optional
+after-the-fact check a caller might forget. `Cart::checkFingerprint()` throws Lunar's own
+`FingerprintMismatchException` if the cart's contents/total changed since that fingerprint
+was generated (a line's price changed, stock adjusted the total, another tab modified the
+cart), forcing re-confirmation instead of silently placing an order at a different total than
+what the shopper approved.
+
+### No exception wrapping — same reasoning as `CartService`
+
+Confirmed from source: `Lunar\Validation\Cart\ValidateCartForOrderCreation` (the validator
+`Cart::createOrder()` runs via `config('lunar.cart.validators.order_create')`) already throws
+`Lunar\Exceptions\Carts\CartException` with a field-keyed `MessageBag`
+(`$exception->errors()`) — billing/shipping address completeness, missing shipping option,
+duplicate-order guard. This is already the right shape for a storefront to catch and render
+as form errors directly; wrapping it in a boboko-owned exception type would add indirection
+with identical semantics, the same call made for `CartService`'s cart-line exceptions.
+
+`FingerprintMismatchException` (from the mandatory fingerprint check above) propagates
+as-is for the same reason.
+
+**One genuine exception to this rule**: `selectShippingOption()` throws
+`Modules\Core\Checkout\Exceptions\InvalidShippingOptionException` when `$identifier` doesn't
+resolve to a real option (`ShippingManifest::getOption()` just returns `null` — Lunar has no
+matching exception type here to propagate, unlike `CartException`/`FingerprintMismatchException`
+above). Same reasoning as `Modules\Core\Cart\Exceptions\InvalidCouponException` for
+`Discounts::validateCoupon()`, which also just returns a bool with nothing to reuse. Confirmed
+live: an invalid identifier previously returned the cart unchanged with no signal at all —
+fixed to throw instead, verified via a real container test.
+
+### Validated from source: the real precondition chain
+
+`ValidateCartForOrderCreation::validate()`, read directly from `vendor/lunarphp/core`:
+
+1. No completed order already exists on this cart (duplicate-order guard).
+2. A billing address is set and passes `country_id`/`first_name`/`line_one`/`city`/`postcode`
+   required-field validation.
+3. If the cart `isShippable()` (has at least one non-digital line):
+   - A shipping option must already be selected (`Cart::getShippingOption()` — which only
+     resolves anything once `shippingAddress->shipping_option` has been persisted via
+     `selectShippingOption()`, confirmed from `Lunar\Base\ShippingManifest::getShippingOption()`).
+   - Unless that option is collect/pickup (`$shippingOption->collect`), a shipping address is
+     also required and validated the same way as billing.
+
+This is why `CheckoutService`'s methods exist in the order they're listed above — a
+storefront checkout flow has to drive them roughly in that sequence for `placeOrder()` to
+ever succeed.
+
+---
+
+## Events — richer payload than `CartService`'s, deliberately
+
+`Modules\Core\Checkout\Events`: `ShippingAddressSet`, `BillingAddressSet`,
+`ShippingOptionSelected`, `OrderPlaced`.
+
+Unlike `CartService`'s events (which carry a plain `Cart`/`CartLine` model reference — see
+`docs/cart.md`), these carry richer, already-resolved payload — e.g. `ShippingOptionSelected`
+includes the resolved `ShippingOption` (name, price, carrier identifier), not just the
+string identifier a listener would have to re-resolve. Deliberate divergence from
+`CartService`'s convention: a live-priced shipping quote or a submitted address is
+meaningfully more expensive/awkward for a listener to re-derive later than a `CartLine`
+model reference is.
+
+**Why this matters beyond `Checkout` itself:** the Analytics survey (`docs/scratch/
+analytics-feature-survey.html`) found conversion-funnel tracking (product view → add to cart
+→ checkout → purchase) entirely missing, with zero underlying data captured anywhere. The
+Checkout survey separately flagged "abandoned-checkout stage tracking (email captured vs.
+shipping selected vs. payment started)" as missing. One event per real state transition here
+— not just a single `OrderPlaced` at the end — is what gives a future analytics/reporting
+listener (not built) the funnel-stage data neither gap currently has anything to build on.
+
+**None of these have a listener yet.** Same status as `CartService`'s events — dispatched,
+unconsumed, built so something downstream has a hook to attach to.
+
+---
+
+## Explicitly out of scope for `CheckoutService`
+
+- **Order-status-changed events** — post-placement, staff-driven (`Order::status` changes via
+  the Filament admin `EditOrder` page, never through checkout). Belongs to `Order` (see
+  above), not `Checkout`.
+- **Order confirmation email** — needs `OrderPlaced` as a trigger, but actual sending is
+  separate infrastructure, same "detection/signal only, sending is a later concern" deferral
+  already applied to `Recovery` (`docs/recovery-strategies.md`).
+- **Guest order tracking/lookup** — a separate storefront feature, not part of the placement
+  flow itself.
+- **Payment** — authorizing/capturing a transaction against the placed order. Genuinely
+  separate from `Checkout` as scoped here; `CheckoutService::placeOrder()` produces an
+  `Order`, what happens to pay for it is out of this document's scope.

docs/collections.md

@@ -0,0 +1,116 @@
+# Collections
+
+`Modules\Core\Catalog\Services\CollectionService` provides category browsing/nav AND
+single-collection lookup for a storefront — `list()`, `getById()`, `getBySlug()` —
+all reading directly from the Meilisearch index, mirroring
+`Modules\Core\Catalog\Services\ProductService` (see `product-listing.md`) exactly.
+
+---
+
+## Why it reads from the index, not the database
+
+Lunar's own `Lunar\Search\CollectionIndexer` only carries `id`/`name`/`created_at` —
+nowhere near enough for a storefront category page or a nav tree.
+`Modules\Core\Catalog\Services\CollectionIndexer` extends it to add everything
+`CollectionService` needs:
+
+| Field | Source | Notes |
+|---|---|---|
+| `parent_id` | `$model->parent_id` | Filterable. The nested-set tree's parent pointer — `null` for a top-level collection. |
+| `_lft` | `$model->_lft` | Filterable and sortable. The nested-set tree position — lets `CollectionService` resolve tree order without a database read. |
+| `collection_group_id` | `$model->collection_group_id` | Filterable. Mirrors `Collection::scopeInGroup()`. |
+| `slugs` | `$model->urls->pluck('slug')` | Filterable. Every locale's `Url::slug`, so `getBySlug()` resolves purely from the index. |
+| `thumbnail` | `$model->getThumbnailImage()` | Display only. `null` if the collection has no thumbnail image. |
+| `ancestors` | `$model->ancestors` | Display only. Array of `{id, name}`, ordered root-first — a breadcrumb (`Home > Apparel > Keychains`) can render directly from a single `getById()`/`getBySlug()` call, no extra queries. Empty array for a top-level collection. |
+| `product_count` | Queried from the *product* Meilisearch index at collection-index time | Display only. How many products are in this collection **or any of its descendants** — matches what `ProductService::list(ProductFilters(collectionId: ...))` would return, not just direct assignment. Computed via `Product::search('')->options(['filter' => "collection_ids = \"{id}\""])`, so it depends on the product index already being current — reindex products *before* collections (see "Gotchas" below). |
+
+`name`/`description` (and any other `TranslatedText` attribute) are indexed per-locale
+by Lunar's base indexer and resolved by `CollectionService` exactly like
+`ProductService` does — see `product-listing.md`'s "Locale resolution" section, same
+logic, same `LanguageCache::defaultLocale()` fallback.
+
+---
+
+## Usage
+
+```php
+use Modules\Core\Catalog\DTOs\CollectionFilters;
+use Modules\Core\Catalog\Enums\CollectionSort;
+use Modules\Core\Catalog\Services\CollectionService;
+
+$service = app(CollectionService::class);
+
+// Top-level collections only (parent_id IS NULL) — for building a nav tree
+$roots = $service->list(
+    filters: new CollectionFilters(rootOnly: true),
+    sort: CollectionSort::Position,
+);
+
+// Children of a specific collection
+$children = $service->list(
+    filters: new CollectionFilters(parentId: 222),
+    sort: CollectionSort::Position,
+);
+
+// Filter by collection group
+$collections = $service->list(filters: new CollectionFilters(groupId: 4));
+
+// Single collection, by primary key or slug
+$collection = $service->getById(223);
+$collection = $service->getBySlug('keychains');
+```
+
+`CollectionFilters(parentId: ..., rootOnly: ...)` are mutually exclusive — if both are
+set, `parentId` wins. There's no `parentId: null` shorthand for "root only", since
+that would be ambiguous with "don't filter by parent at all" (the DTO's actual
+default); `rootOnly` names the root-collections case explicitly instead.
+
+`CollectionSort::Position` (`_lft:asc`) is the recommended default for any nav/tree
+UI — it matches the order an admin arranges collections in Lunar's own Filament UI.
+`Name` and `Newest` are also available, mirroring `ProductSort`'s shape.
+
+---
+
+## Registration
+
+Like `ProductIndexer`, `CollectionIndexer` must be registered in the consuming app's
+own `config/lunar/search.php`:
+
+```php
+'indexers' => [
+    Lunar\Models\Collection::class => Modules\Core\Catalog\Services\CollectionIndexer::class,
+    // ...
+],
+```
+
+New/changed fields aren't filterable/sortable in Meilisearch until `php artisan
+lunar:meilisearch:setup` re-syncs index settings, and existing documents need
+`lunar:search:index --refresh` to pick up the new shape. If `SCOUT_QUEUE` is enabled,
+the queue worker also needs restarting after deploying changes to the indexer class —
+see `docs/lunar.md` "Gotchas".
+
+**`product_count` needs the product index reindexed first.** `config/lunar/search.php`'s
+`indexers` array is typically ordered `Collection` before `Product`, so a plain
+`lunar:search:index --refresh` computes `product_count` against whatever the product
+index held *before* this run — stale if products changed too. `lunar:search:index`
+takes an explicit model list as its argument (`--ignore` restricts it to only those),
+so reindex products first, then collections, when both need a fresh `--refresh` in the
+same deploy:
+
+```
+php artisan lunar:search:index "Lunar\Models\Product" --ignore --refresh
+php artisan lunar:search:index "Lunar\Models\Collection" --ignore --refresh
+```
+
+---
+
+## When to still use Eloquent directly
+
+A single collection's full detail page (breadcrumb via `$collection->breadcrumb`,
+tree ancestors/descendants, route-model-bound `Collection $collection` in a
+controller signature) should keep reading Eloquent directly rather than going through
+`CollectionService` — the indexed document doesn't carry ancestor chains or the full
+nested-set relations, and route-model binding already gives a controller the full
+model for free. `CollectionService` is for browsing/listing and lightweight
+by-id/by-slug lookups where a full Eloquent hydration would be wasteful, the same
+tradeoff `ProductService` makes for products.

docs/localization.md

@@ -199,9 +199,20 @@ registered.
 ### Seeding
 
 A starter set of common e-shop labels (`nav.*`, `cart.*`, `product.*`, `auth.*`, `search.*`,
-English + Greek) is seeded by `Modules\Core\Command\InstallLunarCommand` (overrides Lunar's own
-`lunar:install`), guarded by `LanguageLine::where('group', 'storefront')->exists()` — same
-idempotent pattern as the rest of that command, safe to run unattended on every boot.
+`review.*`, `shop.*`, `pagination.*`, English + Greek) lives in
+`Modules\Core\Localization\Services\StorefrontLabels::all()` — kept as its own class, separate
+from the seeding logic, so the label list can be scanned/diffed without wading through the
+seeding mechanics.
+
+`Modules\Core\Command\InstallLunarCommand` (overrides Lunar's own `lunar:install`) seeds them via
+a **per-key upsert**, not an all-or-nothing "only seed if the group is empty" guard: a key already
+present in the database — including one an admin has since edited via the Filament **Language
+Lines** resource — is left untouched; only keys missing entirely are created. This is what makes
+it safe to add new keys to `StorefrontLabels::all()` later and re-run `lunar:install` on an
+already-installed store, without either silently skipping the new keys (the old guard's behavior)
+or reverting an admin's edits back to the hardcoded default (what a naive `updateOrCreate` would
+do). New writes go through `TranslationService::create()`, so the usual cache-invalidation and
+activity-log events fire for them too.
 
 ### Admin UI
 

docs/lunar.md

@@ -554,7 +554,11 @@ Customer resolution order: session → `$user->latestCustomer()`.
 ```php
 use Lunar\Facades\CartSession;
 
-$cart = CartSession::current();       // calculates totals; returns null if no cart
+$cart = CartSession::current();       // returns null unless a cart already exists in
+                                       // session — does NOT auto-create one (see Gotchas)
+$cart = CartSession::manager();       // force-creates a cart if none exists yet — use
+                                       // this (or __call forwarding, see Gotchas) for
+                                       // "give me a cart to add to" flows
 $cart->recalculate();                 // force recalculation
 
 CartSession::createOrder();           // creates order, removes cart from session
@@ -563,6 +567,39 @@ CartSession::forget();                // clear session (soft deletes cart by def
 CartSession::forget(delete: false);   // clear session, keep cart in DB
 ```
 
+Session/identity: the active cart's id is stored under session key `lunar.cart_session.session_key`
+(default `lunar_cart`). `CartSession`'s underlying manager (`Lunar\Managers\CartSessionManager`) —
+not `Lunar\Base\CartSessionInterface`, which is stale/incomplete, see Gotchas — resolves the current
+cart from that session key, falling back to the authenticated user's active cart
+(`$user->carts()->active()->first()`) if the session has none.
+
+### `config/lunar/cart_session.php`
+
+| Key | Default | Meaning |
+|---|---|---|
+| `session_key` | `'lunar_cart'` | Laravel session key storing the active cart id. |
+| `auto_create` | `false` | Whether `CartSession::current()` auto-creates a cart when none exists — it does **not**, by default (see Gotchas). |
+| `allow_multiple_orders_per_cart` | `false` | If false, a cart with a completed order is abandoned in favor of a fresh cart on next fetch. |
+| `delete_on_forget` | `true` | Whether `forget()` (called on logout) soft-deletes the cart — see the auth-policy note above. |
+
+### `config/lunar/cart.php` (cart-line-relevant keys)
+
+| Key | Default | Meaning |
+|---|---|---|
+| `auth_policy` | `'merge'` | Guest→user cart reconciliation on login: `merge` or `override`. |
+| `pipelines.cart` | `CalculateLines, ApplyShipping, ApplyDiscounts, CalculateTax, Calculate` | Steps run on `$cart->calculate()`. |
+| `pipelines.cart_lines` | `[GetUnitPrice::class]` | Steps run per-line before cart-level calc. |
+| `actions.add_to_cart` | `AddOrUpdatePurchasable::class` | Swappable action behind `Cart::add()`. |
+| `actions.get_existing_cart_line` | `GetExistingCartLine::class` | Line-matching logic for add-or-merge (see "Adding items" above). |
+| `actions.update_cart_line` | `UpdateCartLine::class` | Behind `Cart::updateLine()`. |
+| `actions.remove_from_cart` | `RemovePurchasable::class` | Behind `Cart::remove()`. |
+| `validators.add_to_cart` | `[CartLineQuantity, CartLineStock]` | Run before add. |
+| `validators.update_cart_line` | `[CartLineQuantity, CartLineStock]` | Run before update. |
+| `validators.remove_from_cart` | `[]` | None by default. |
+| `eager_load` | 7 relation paths (currency, `lines.purchasable.*`, `lines.cart.currency`) | Auto-eager-loaded whenever the session manager fetches a cart by id. Does **not** include `addresses`/`shippingAddress`/`billingAddress`, `discounts`, or `customer` — add these yourself if needed, to avoid N+1s. |
+| `prune_tables.enabled` | `false` | Whether scheduled cart pruning runs. |
+| `prune_tables.prune_interval` | `90` (days) | Age threshold for pruning. |
+
 ### Adding items
 
 ```php
@@ -573,6 +610,11 @@ $cart->addLines([
 ]);
 ```
 
+`add()` matches an existing line by purchasable **and exact `meta` equality** (config
+`lunar.cart.actions.get_existing_cart_line`, default `GetExistingCartLine`) — if it matches, the
+existing line's quantity is incremented instead of a new line being created; any difference in
+`meta` (e.g. a different chosen option) makes it a separate line for the same purchasable.
+
 ### Updating and removing
 
 ```php
@@ -664,6 +706,14 @@ class MyPipeline
 `merge` — guest cart items combine with user's existing cart on login.
 `override` — guest cart replaces user's cart.
 
+This is wired via `Lunar\Listeners\CartSessionAuthListener`, listening on Laravel's own
+`Illuminate\Auth\Events\Login`/`Logout`. On login, if the session already has a cart with no
+`user_id` yet, it associates that cart to the user (running the policy above); if the session has
+no cart at all, it looks up and resumes the user's own active cart instead. **On logout, it calls
+`CartSession::forget()`** — which, per `cart_session.delete_on_forget` (default `true`), **soft-
+deletes the cart**. A logged-in customer's cart is gone on logout unless that config is set to
+`false`.
+
 ### Shipping options
 
 ```php
@@ -1206,6 +1256,13 @@ Real bugs/traps hit while building against Lunar in this package — not obvious
 - **`ProductOption.handle` must be unique and non-null if a product has more than one option.** Lunar's Filament variant-switcher widget does `SelectFilter::make($option->handle)` per option — two options with a `null`/matching handle throws "Filter must have a unique name" as a 500 when opening that product's variant pricing page. Always derive a slug and check uniqueness.
 - **`Attribute.position` is per-group, and the panel sorts by it.** Hardcoding `position => 1` for multiple new attributes in the same group makes their order undefined/collide with existing attributes at position 1. Compute `max('position') + 1` per group instead.
 - **Currency `decimal_places` isn't always 2.** A seeded/demo currency can have the wrong value (seen: EUR seeded with `decimal_places = 1`), which silently corrupts every price display (`€16.50` renders as `165`). If prices look wrong by a factor of 10, check the currency row before assuming the price-writing code is broken.
-- **`Builder::paginateRaw()`'s `items()` is not a hit list on the Meilisearch driver.** It contains the *entire* raw response (`hits`, `query`, `processingTimeMs`, `hitsPerPage`, `page`, `totalPages`, `totalHits`) as one associative array. Treating `$paginator->items()` as a plain list (e.g. `collect($paginator->items())->values()`) silently produces 7 elements — the real hits array happens to land first, the rest are stray scalars from the other response keys — no error, just corrupted data. Pull `$paginator->items()['hits']` explicitly. `total()`/`perPage()`/`currentPage()`/`lastPage()` on the paginator are unaffected. See `Modules\Core\Product\Services\ProductService` / `docs/product-listing.md`.
-- **`ProductOption`/`ProductOptionValue::$name` is not `attribute_data` — `translateAttribute('name')` silently returns null for them.** Unlike `Product`/`Collection`/`Brand`, their translated `name` is a plain locale-keyed array cast (`AsArrayObject`) directly on the column, not stored in `attribute_data`. `HasTranslations::translateAttribute()` only reads `attribute_data`, so calling it on these two models compiles fine and returns `null` with no error — read the array directly instead (`$value->name[$locale] ?? ...`). See `Modules\Core\Product\Services\ProductIndexer::translatedName()`.
+- **`Builder::paginateRaw()`'s `items()` is not a hit list on the Meilisearch driver.** It contains the *entire* raw response (`hits`, `query`, `processingTimeMs`, `hitsPerPage`, `page`, `totalPages`, `totalHits`) as one associative array. Treating `$paginator->items()` as a plain list (e.g. `collect($paginator->items())->values()`) silently produces 7 elements — the real hits array happens to land first, the rest are stray scalars from the other response keys — no error, just corrupted data. Pull `$paginator->items()['hits']` explicitly. `total()`/`perPage()`/`currentPage()`/`lastPage()` on the paginator are unaffected. See `Modules\Core\Catalog\Services\ProductService` / `docs/product-listing.md`.
+- **`ProductOption`/`ProductOptionValue::$name` is not `attribute_data` — `translateAttribute('name')` silently returns null for them.** Unlike `Product`/`Collection`/`Brand`, their translated `name` is a plain locale-keyed array cast (`AsArrayObject`) directly on the column, not stored in `attribute_data`. `HasTranslations::translateAttribute()` only reads `attribute_data`, so calling it on these two models compiles fine and returns `null` with no error — read the array directly instead (`$value->name[$locale] ?? ...`). See `Modules\Core\Catalog\Services\ProductIndexer::translatedName()`.
 - **A running `queue:work` process does not pick up an edited/newly-added Scout indexer class.** It loads PHP classes once at boot and keeps them for the process's lifetime. Symptoms: reindexing commands succeed with no errors, calling `toSearchableArray()` directly (e.g. via `artisan tinker`, which always boots fresh) returns the new fields correctly, but documents written via `$model->searchable()` through the live queue are still missing them. Restart the queue worker after deploying an indexer change — no code fix needed.
+- **`CartSession::current()` returns `null` for a fresh visitor by default.** `cart_session.auto_create` defaults to `false`, so nothing auto-creates a cart just from checking `current()`. Use `CartSession::manager()` (force-creates) for an "add to cart" flow, or rely on the fact that `add()`/`remove()`/etc. auto-create via `__call` forwarding (next entry) — don't gate an add-to-cart button on `current() !== null`, it will be null for every guest who hasn't added anything yet.
+- **`CartSession`'s facade/interface don't declare `add()`, `remove()`, `updateLine()`, `clear()`, etc. at all — they work anyway, via `__call` magic.** `CartSessionManager::__call()` forwards any undeclared method call straight to the underlying `Cart` model (auto-creating one first if needed). So `CartSession::add($variant, 2)` genuinely works, but neither the facade's `@method` docblock nor `Lunar\Base\CartSessionInterface` mention it — reading either in isolation makes it look unsupported. Trust the manager's source (`Lunar\Managers\CartSessionManager`), not the interface, which is also missing several real methods (`manager()`, `createOrder()`, the shipping-estimate methods) and has a stale signature for `current()`.
+- **`Cart::calculate()` is a no-op if totals already look populated — even right after you mutated lines with raw Eloquent.** It's memoized via `isCalculated()` (true when `total` and every line's `total` are non-blank). Every built-in mutator (`add`, `remove`, `updateLine`, `clear`, `associate`, …) already calls `$this->refresh()->recalculate()` to force past this memo — but custom code that touches `CartLine` rows directly (raw `update()`, a queued job, a migration) must call `$cart->recalculate()` itself, or `total`/`subTotal`/etc. silently stay stale.
+- **`CartLine`'s computed properties (`unitPrice`, `subTotal`, `total`, `taxAmount`, …) are plain public properties, not DB columns or Eloquent attributes.** A raw `CartLine::find($id)` (no `calculate()` having run on its owning cart) has all of these as `null`/unset — they only populate as a side effect of the owning `Cart`'s pipeline running. Don't read them off a line fetched outside of `CartSession`/`Cart::add()` etc. without calling `$cart->calculate()` first.
+- **Logging out deletes the cart by default.** `CartSessionAuthListener::logout()` calls `CartSession::forget()`, and `cart_session.delete_on_forget` defaults to `true` — so a logged-in customer's cart is soft-deleted the moment they log out, guest or not. Set `delete_on_forget` to `false` in `config/lunar/cart_session.php` if carts should survive a logout.
+- **Lunar dispatches no cart events at all** — no "item added," "cart created," "line removed," nothing under `Lunar\Events\Cart*`/`CartLine*` exists (unlike products/collections, which have their own Scout indexing hooks). The only reactive surface is `CartLineObserver` (`creating`/`updating`, and it only validates the purchasable type — doesn't dispatch anything). If a feature needs to react to cart changes (reindexing, abandoned-cart notifications, analytics), it has to be built from scratch on plain Eloquent model events (`CartLine::created`, etc.) — there's no Lunar-native pattern to hook into.
+- **No Filament admin resource exists for `Cart`/`CartLine`.** Carts aren't visible anywhere in the admin panel except indirectly through an order's `cart` relationship once that cart has become an order. Don't assume there's an admin cart-viewer to check against when debugging — there isn't one.

docs/modules.md

@@ -49,7 +49,8 @@ boboko-test/
   app/
     Models/
       Customer.php      ← app-level model, extends Modules\Core\Customer\Models\Customer
-      User.php           ← app-level model, dispatches Modules\Core\Auth\Events\UserCreated
+      User.php           ← app-level model, no $dispatchesEvents needed — core dispatches
+                            UserCreated itself (Modules\Core\Auth\Services\UserOtpService)
       Staff.php          ← app-level model, extends Modules\Core\Auth\Models\Staff
     Lunar/
       Extensions/        ← app's own Filament resource extensions (source of truth, wired in PanelServiceProvider)
@@ -264,7 +265,14 @@ php artisan vendor:publish --tag=core-config
 'auto_create_customer_for_user' => false,
 ```
 
-Both listeners guard against the other direction re-triggering: they call `User::withoutEvents(...)` around `firstOrCreate`/save, so pairing a `Customer` never spuriously fires `UserCreated` (and vice versa) even if both directions are somehow active at once.
+A guard against the other direction re-triggering is only needed where a real risk exists:
+`App\Listeners\CreateUserForCustomerListener` (`boboko-test`, app-level) wraps its
+`firstOrCreate` in `User::withoutEvents(...)`, since finding-or-creating a `User` there could
+itself fire `UserCreated` and loop back into `CreateCustomerForUser`. `Modules\Core\Customer\
+Listeners\CreateCustomerForUser` (core) needs no such guard — it calls a plain
+`$model::create([])` on `Customer`, which has no `$dispatchesEvents`/model hooks of its own in
+core that could re-trigger anything; the guard belongs only on the side that actually creates a
+`User`.
 
 ---
 

docs/payments.md

@@ -0,0 +1,228 @@
+# Payment — Design Notes
+
+**Status: abstraction layer built, drivers/wiring in progress.** `Payment` is designed as a
+standalone module: it never calls into `Checkout` or `Order`, never touches their Eloquent
+models, and communicates only via events. This document is the design spec for that
+abstraction — contracts, DTOs, events — independent of how `Checkout`/`Order` end up consuming
+it (that wiring is a separate, later pass).
+
+---
+
+## Operations, not gateways
+
+The driver contracts model the actual operations a payment gateway can perform, not vendor
+terminology. Every real gateway checked while designing this converges on the same small set
+under different names:
+
+| Operation | Mastercard | Stripe | Nexi |
+|---|---|---|---|
+| Atomic charge (authorize+capture in one call) | `Pay` | `capture_method: automatic` | `ActionType::PAY()` |
+| Hold only, settle/release later | `Authorize` | `capture_method: manual` | `ActionType::PREAUTH()` |
+| Settle a prior hold | `Capture` | `PaymentIntent::capture()` | `CaptureRequest`/`CaptureResponse` |
+| Release a prior hold without settling | `Void`/`Cancel` | `PaymentIntent::cancel()` | `CancelRequest`/`CancelResponse` |
+| Reverse settled funds | `Refund` | `Refund::create()` | (refund endpoint) |
+
+A driver implements only the interfaces its gateway actually supports:
+
+- An offline/cash type (`cash-on-delivery`, `cash-in-hand`) only ever settles atomically —
+  implements `SupportsPay` alone.
+- A card gateway capable of either mode per-transaction (Stripe, most card processors)
+  implements `SupportsPay`, `SupportsAuthorization`, `SupportsCaptures`, `SupportsVoids`, and
+  `SupportsRefunds` all at once — which one gets *called* for a given attempt is the caller's
+  policy choice (e.g. `config('lunar.stripe.policy')`), not something baked into the driver's
+  shape.
+- A redirect/wallet gateway with no separate hold step (Viva/Klarna in typical flows)
+  implements `SupportsPay` and `SupportsRefunds`, never `SupportsCaptures`/`SupportsVoids`.
+
+### `pay()` and `authorize()` stay separate methods even when a gateway implements both as "the same call with a flag"
+
+Stripe has no separate `authorize`/`pay` API endpoints — one `PaymentIntent`, confirmed with
+either `capture_method: automatic` or `manual`. Mastercard and Nexi *do* have genuinely
+separate operations. The contract abstracts over both shapes uniformly: every driver capable
+of both exposes two distinct methods, `pay()` and `authorize()`. A Mastercard-style driver
+calls two different endpoints under the hood; a Stripe-style driver calls the same endpoint
+twice with a different flag each time. Neither difference is visible to a caller.
+
+### `capture()`/`void()` are only ever valid against a prior `authorize()`
+
+They are not standalone operations — `capture()` settles a specific hold identified by the
+`reference` `authorize()` returned; `void()` releases that same hold instead. A driver that
+never implements `SupportsAuthorization` never produces a reference either of these methods
+could act on.
+
+---
+
+## `PaymentResult` — the one return shape, every operation, every driver
+
+```php
+enum PaymentResultStatus { case Succeeded; case Failed; case Pending; }
+
+final class PaymentResult {
+    public function __construct(
+        public readonly PaymentResultStatus $status,
+        public readonly string $reference,
+        public readonly int $amount,
+        public readonly ?string $failureReason = null,
+        public readonly bool $retriable = false,
+        public readonly array $raw = [],
+        public readonly array $meta = [],
+    ) {}
+}
+```
+
+Real gateway responses vary wildly in richness — confirmed by reading three SDKs directly:
+
+- **Stripe's `PaymentIntent`** is rich: `status`, `amount`, `amount_capturable`,
+  `amount_received`, `last_payment_error`, a full `getLastResponse()`.
+- **Nexi's `CaptureResponse`/`CancelResponse`** are minimal: just `operationId` +
+  `operationTime` — no echoed amount or status at all. Success is inferred from getting a
+  response rather than an SDK exception.
+- **Mastercard's** gateway sits in between, with `gatewayCode`/`acquirerCode`/
+  `merchantAdviceCode`.
+
+`PaymentResult` only requires what every driver can always know: `status`, `reference`,
+`amount` (the amount **we** requested — not necessarily echoed back by a sparse gateway like
+Nexi's capture). Everything else is best-effort: `failureReason`/`retriable` are normalized
+only when the gateway has something to normalize from; `raw` is the unconditional escape
+hatch — the untouched gateway response body, always populated, for genuine audit fidelity
+regardless of how sparse the normalized fields ended up.
+
+### `retriable` — real on some gateways, absent on others
+
+Stripe classifies declines as soft (`do_not_honor`, `insufficient_funds` — worth retrying,
+after a delay) vs. hard (`stolen_card`, `expired_card` — never retry the same method).
+Mastercard has the equivalent via `authorizationResponse.merchantAdviceCode` and card-scheme
+soft-decline codes. **Nexi has no such signal at all** — `OperationResult` is just
+`DECLINED`/`DENIED_BY_RISK`/`FAILED`/etc. with no retriability classification. `retriable`
+therefore defaults to `false` (assume not safely retriable) rather than guessing when a
+driver's gateway has nothing to base it on.
+
+---
+
+## Events — one terminal pair per operation, keyed to the business fact, not the call path
+
+`Modules\Core\Payment\Events`:
+
+| Event pair | Dispatched by |
+|---|---|
+| `PaymentAuthorized` / `PaymentAuthorizationFailed` | `SupportsAuthorization::authorize()`, or a later `HandlesPaymentCallback::handleCallback()` resolving it |
+| `PaymentCaptured` / `PaymentCaptureFailed` | `SupportsPay::pay()` **or** `SupportsCaptures::capture()` |
+| `PaymentVoided` / `PaymentVoidFailed` | `SupportsVoids::void()` |
+| `PaymentRefunded` / `PaymentRefundFailed` | `SupportsRefunds::refund()` |
+
+`PaymentCaptured` is deliberately the *same* event whether money was taken via `pay()` (one
+gateway call) or `authorize()` → `capture()` (two calls) — "a payment has been captured" is
+the same business fact either way, and a listener reacting to it never needs to know which
+path produced it. There is no separate "payment succeeded" wrapper event distinct from
+`PaymentCaptured`.
+
+Every event carries `{type: string, result: PaymentResult, context: array}`. `Payment` has no
+concept of a `Cart`, an `Order`, or a checkout fingerprint — `$context` is an opaque bag the
+caller hands in on the way down (`pay($type, $data, $context)`) and gets back untouched on
+whichever event that call (or a later `handleCallback()`) produces. Each listener interprets
+`$context` on its own terms, or ignores the event if the keys it needs aren't present —
+`Checkout` is only one possible consumer of these events, not the only one.
+
+---
+
+## Async resolution — `HandlesPaymentCallback`
+
+Only implemented by a driver whose `pay()`/`authorize()` can return `PaymentResultStatus::Pending`
+— a redirect the shopper completes elsewhere, a webhook that arrives later. A driver whose
+gateway always resolves synchronously never implements this.
+
+```php
+public function handleCallback(string $reference, array $data, array $context = []): PaymentResult;
+```
+
+Resolves into the *same* event pair the original `pay()`/`authorize()` call would have
+produced had it resolved synchronously.
+
+### The correlation problem: `handleCallback()` runs in a different request
+
+`$context` passed into the original `pay()`/`authorize()` call does not survive to
+`handleCallback()` on its own — that call is typically a separate HTTP request (a webhook)
+with no memory of the request that started the payment. Something has to persist enough to
+answer "which order/cart does gateway reference X belong to?" between the two calls.
+
+The precedent for this originally came from reading `lunarphp/stripe`'s own source
+(`StripePaymentType::authorize()`, `ProcessStripeWebhook`, `WebhookController`) — that package
+solved this the same way, writing the correlating ids as real, typed columns on its own
+`StripePaymentIntent` model rather than a generic opaque blob. **`lunarphp/stripe` has since
+been removed from this project** in favour of depending on `stripe/stripe-php` directly (see
+CHANGELOG.md) — `Modules\Core\Payment\Models\StripePaymentIntent` is now a first-party model
+over the same table shape, kept for exactly the same reason.
+
+**`StripePaymentDriver` follows this pattern**: it reads `cart_id`/`order_id` out of `$context`
+at `pay()`/`authorize()` time and writes them onto its own `StripePaymentIntent` row (`src/
+Payment/Models/StripePaymentIntent.php`, table `stripe_payment_intents`), then reads them back
+the same way in `handleCallback()`. No generic `context` json column beyond what that table
+already carries (`context`, added for a different purpose — see that migration's own
+docblock), no new table.
+
+### This pattern is per-driver, not a shared table
+
+`stripe_payment_intents` is Stripe-specific — keyed on `intent_id`, typed around
+`Stripe\PaymentIntent`'s own status values. It cannot be reused as-is for a future non-Stripe
+async driver (Nexi, Viva): that driver's own gateway reference has a different shape entirely,
+and shoehorning it into Stripe-named columns would make the table misleading. The **pattern**
+generalizes — *any* driver needing async callback resolution owns a small table keyed by its
+own gateway's reference, storing whatever correlation data that driver specifically needs —
+but each driver gets its own table, matching what it actually needs to correlate, rather than
+a shared generic one.
+
+---
+
+## Reconciliation — a charge that succeeds on Stripe but is never written locally
+
+This app never creates or reuses a Stripe **Customer** object — every PaymentIntent is a
+one-off (`StripePaymentDriver::createAndConfirm()`'s own `$params` never includes a `customer`
+key), and nothing calls Stripe's Customer API anywhere in this codebase. That's a deliberate
+choice, not an oversight: a Customer object only earns its keep if something actually needs it
+(saved/reusable payment methods, subscriptions, Stripe-side lifetime-value grouping across
+orders) — none of which exist in this checkout flow today. Creating one anyway would just be
+more PII sitting on a third party's servers for no functional benefit, and it would become
+another cross-reference a future Payment privacy provider has to account for (detaching/
+deleting the Customer on erasure, not just the local PaymentIntent row). If a real feature
+needs it later (e.g. "save my card"), add it then, scoped to that feature.
+
+The gap this creates: with no Customer object and no other identifying field previously sent
+to Stripe, a PaymentIntent that succeeds on Stripe's side but is never written to our own DB
+(e.g. a database outage at exactly the wrong moment, between Stripe confirming the charge and
+`rememberIntent()`'s insert) would be **untraceable** back to a cart or order — nothing to
+search Stripe's dashboard by except amount, timestamp, and card last-4.
+
+**Fix**: `createAndConfirm()` now sets `metadata: ['cart_id' => ..., 'order_id' => ...]`
+(`array_filter()`-ed, since `order_id` isn't known yet at initial `pay()`/`authorize()` time —
+same null-coalesce `rememberIntent()` already does) on every PaymentIntent. This is metadata
+only, visible on Stripe's own dashboard/API for manual reconciliation — it does not create a
+Customer object and does not change anything about how `handleCallback()`/webhook correlation
+works (that still goes through `stripe_payment_intents`, per "Async resolution" above). It's
+purely a recovery aid for the case where our own write never happened at all.
+
+---
+
+## GDPR erasure/export
+
+`Modules\Core\Payment\Privacy\PaymentDataProvider` covers `lunar_transactions`
+(`card_type`/`last_four`) and `stripe_payment_intents` — see `docs/privacy.md` for the full
+right-of-erasure/right-of-access design. Pseudonymizes card metadata on erasure (same
+tax/accounting retention reasoning `Order`'s own provider uses) and deletes the Stripe
+correlation rows outright, since their only purpose — resolving an async webhook callback, see
+"Async resolution" above — has already been served by the time an erasure request runs. No
+Stripe Customer object exists anywhere in this app (see "Reconciliation" above) for this
+provider to also request deletion of.
+
+---
+
+## Explicitly out of scope for this pass
+
+- **`Checkout`/`Order` wiring** — how `Checkout` calls into `Payment`, how `Order`/`Checkout`
+  react to `Payment`'s events, where a draft `Order` gets created relative to when `Payment` is
+  called. Deliberately designed and built separately, after `Payment` itself was complete —
+  `Payment` must stand on its own regardless of what ends up consuming it.
+- **`Transaction` persistence** — Lunar's own `transactions` table (`type`: `intent`/`capture`/
+  `refund`, `parent_transaction_id` chaining) already models the audit trail these events
+  would feed, once a listener is built to write to it. `Payment` itself does not write
+  `Transaction` rows — see the events table above; that is a listener's job, in whichever
+  module ends up owning the write (likely `Order`, since `Transaction.order_id` is required).

docs/privacy.md

@@ -0,0 +1,417 @@
+# Privacy / GDPR Data-Subject Requests
+
+`Modules\Core\Privacy` implements the right of access (export) and right of erasure for
+customers, as an extensible contract rather than a fixed list of tables — any module (core,
+or a future ERP/banking/etc. module) can register its own data without core knowing it exists.
+
+---
+
+## User-scope vs Customer-scope — two genuinely different operations
+
+A Lunar `Customer` (business account: orders, addresses, buyer record) and a `User` (individual
+login identity) are linked many-to-many via the `customer_user` pivot (see `docs/modules.md`
+"Customer/User Pairing") — **one User can belong to many Customer accounts, and one Customer
+account can have many linked Users.** This is the real shape of B2B multi-seat access: a person
+can have login access to several separate business accounts, and a business account can have
+several employees each with their own login.
+
+That means "delete my personal data" and "delete this business account" are not the same request,
+and conflating them is actively wrong:
+
+- **Erasing a Customer must never touch any linked User's login or identity.** Erasing "Acme
+  Corp" must not deactivate or destroy access for the employees who work there — and must not
+  touch any *other* Customer account, even one sharing some of the same Users.
+- **Erasing a User must never touch any Customer account's own data.** John asking to delete
+  *his* account must clear his name/email/login wherever it appears — and correctly end his
+  membership on every Customer he's linked to (detach the pivot) — but must not erase Acme Corp's
+  orders or addresses, and must not affect any other employee still linked to Acme Corp.
+
+Every part of this module is split along that line — a `PersonalDataProvider`, a `PrivacyService`
+method, a request record — is always explicitly **for a Customer** or **for a User**, never both
+at once, and never one with an implicit cascade into the other.
+
+---
+
+## Why an extensible contract, not a hardcoded script
+
+A GDPR erasure/export request has to touch every module that holds personal data, but core can't
+know in advance what future modules will exist or what data they'll hold — and different data
+needs fundamentally different handling (freely erasable PII vs. financial records that must be
+pseudonymized-not-deleted for legal retention vs. data that must be retained outright). There's
+deliberately no central taxonomy for this in the contract — each module owns its own retention
+judgment, since only the module that owns a table actually knows its legal requirements.
+
+`Modules\Core\Privacy\Contracts\PersonalDataProvider` is the whole contract:
+
+```php
+interface PersonalDataProvider
+{
+    public function name(): string;
+
+    public function exportForUser(UserSubject $subject): ProviderExportResult;
+    public function exportForCustomer(CustomerSubject $subject): ProviderExportResult;
+
+    public function eraseForUser(UserSubject $subject): ProviderErasureResult;
+    public function eraseForCustomer(CustomerSubject $subject): ProviderErasureResult;
+}
+```
+
+Every provider implements all four methods. A provider with nothing relevant to one scope
+implements that method as a no-op — `ErasureOutcome::Skipped` with a reason for erase, an empty
+payload for export (e.g. `AddressDataProvider::eraseForUser()`, since addresses belong to a
+Customer, not an individual).
+
+A provider implementation lives inside the module that owns the data it erases/exports, under
+that module's own `Privacy/` subdirectory (e.g. `Modules\Core\Order\Privacy\OrderDataProvider`,
+`Modules\Core\Customer\Privacy\CustomerDataProvider`) — never inside `Modules\Core\Privacy`
+itself, which only owns the shared contract (`Contracts\PersonalDataProvider`), the request
+lifecycle (`Services\PrivacyManager`/`PrivacyService`), and the DTOs/enums every provider
+returns. This mirrors how this codebase already handles other cross-cutting-but-domain-specific
+code (e.g. a resource's own `Filament/Extensions/` subdirectory) — and matters concretely if a
+module is ever extracted into its own composer package (see `docs/modules.md`): the provider
+that knows how to erase that module's data must travel with it, not get stranded in `Privacy`
+depending on a package that no longer ships in this repo.
+
+A module registers by adding its provider class to `config('core.privacy.providers')` — the
+same shape as Lunar's own `config('lunar.search.indexers')` model→indexer map:
+
+```php
+// config/core.php
+'privacy' => [
+    'providers' => [
+        \Modules\Core\Customer\Privacy\CustomerDataProvider::class,
+        \Modules\Core\Customer\Privacy\AddressDataProvider::class,
+        \Modules\Core\Order\Privacy\OrderDataProvider::class,
+        \Modules\Core\Cart\Privacy\CartDataProvider::class,
+        \Modules\Core\Review\Privacy\ReviewDataProvider::class,
+        // A future module just adds its own provider here.
+    ],
+],
+```
+
+`PrivacyManager` resolves each class via the container and asserts every `name()` is unique —
+two providers registering the same name throws, so a naming collision fails loudly at
+resolution time rather than silently overwriting one provider's data in an export/report.
+
+---
+
+## `UserSubject` and `CustomerSubject` — identifying "the person" vs "the account"
+
+Two separate value objects, not one — each deliberately carries only what its own scope needs, so
+a provider can't accidentally reach across the boundary:
+
+```php
+class CustomerSubject
+{
+    public readonly int $customerId;
+    // No userIds, no email — Customer-scope has no business knowing about logins.
+}
+
+class UserSubject
+{
+    public readonly int $userId;
+    public readonly ?string $email;
+    // No customerId — one User can be linked to many Customers; a provider that
+    // needs to know which ones looks that up itself (e.g. to detach the pivot),
+    // rather than this value object assuming or privileging any single one.
+}
+```
+
+`CustomerSubject::forCustomer(Customer $customer)` and `UserSubject::forUser($user)` build one
+from the record staff (or the person themselves) look up.
+
+---
+
+## Providers shipped in core
+
+| Provider | `name()` | Lives in | Covers | Customer-scope | User-scope |
+|---|---|---|---|---|---|
+| `ActivityLogDataProvider` | `activity_log` | `Modules\Core\Logging\Privacy` | `activity_log` (Spatie) for subject types `Customer`/`Address`/`CartAddress`/`OrderAddress`/`Transaction` | **Pseudonymized** — `properties` redacted, who/what/when metadata kept | Skipped — `causer_id` is an actor reference, not PII content; see below |
+| `CustomerDataProvider` | `customer` | `Modules\Core\Customer\Privacy` | `lunar_customers`, and separately the `User`'s own name/email/OTP fields | Erases the account's own fields only | Erases that User's name/email/OTP fields only, and detaches them from every linked Customer |
+| `AddressDataProvider` | `addresses` | `Modules\Core\Customer\Privacy` | `lunar_addresses` | Erased (deleted outright) | Skipped — belongs to a Customer, not an individual |
+| `OrderDataProvider` | `orders` | `Modules\Core\Order\Privacy` | `lunar_orders`, `lunar_order_addresses`, and their `meta` (`terms_accepted*`, `payment_method`, `box_now_locker`) | **Pseudonymized, not erased** — see below | Skipped — belongs to a Customer, not an individual |
+| `CartDataProvider` | `carts` | `Modules\Core\Cart\Privacy` | `lunar_cart_addresses`, and `lunar_carts.meta` (`recovery_consent*`, `payment_method`, `checkout_fingerprint`) | Erased | Skipped — belongs to a Customer, not an individual |
+| `ReviewDataProvider` | `reviews` | `Modules\Core\Review\Privacy` | `product_reviews` | Skipped — authored by an individual, not a business account | Pseudonymized by matching `reviewer_email`; rating/title/body text kept |
+| `PaymentDataProvider` | `payments` | `Modules\Core\Payment\Privacy` | `lunar_transactions` (`card_type`/`last_four`), `stripe_payment_intents` | **Pseudonymized** — card metadata cleared, correlation rows deleted, amounts/statuses kept | Skipped — belongs to Customer-owned orders, not individual users |
+| `UserSessionDataProvider` | `sessions` | `Modules\Core\Auth\Privacy` | `user_sessions` (`ip_address`, `user_agent`) | Skipped — belongs to an individual User, not a business account | Erased (deleted outright) |
+
+`CustomerDataProvider` is the one provider that implements both scopes meaningfully, and keeps
+them from touching each other — see the class docblock for the full reasoning.
+
+### `activity_log` is redacted by subject, never by causer
+
+`Modules\Core\Logging\ActivityLogService` (plus several Lunar models' own native `use
+LogsActivity` — `Customer`, `CartAddress`, `OrderAddress`, `Transaction`) durably retains a full
+snapshot of whatever it logged in `properties`, completely independent of the real row it
+describes — erasing/pseudonymizing a `Customer`/`Address`/`Order`/etc. elsewhere does nothing to
+this table on its own. `ActivityLogDataProvider::eraseForCustomer()` redacts `properties` on
+every row whose **subject** (not causer) resolves back to that customer, across all five
+PII-bearing subject types.
+
+It deliberately never touches `causer_id` — the causer is "who performed this action," not PII
+content, and erasing it would defeat the audit trail's own purpose. `eraseForUser()` is
+therefore a no-op: a `User` appears in this table only as a causer, never as subject content, so
+there's nothing to redact from the User side alone.
+
+**Ordering dependency**: `ActivityLogDataProvider` must run *before* `AddressDataProvider` in
+`config('core.privacy.providers')` — it resolves which `activity_log` rows are keyed by an
+`Address` id while those Address rows still exist; `AddressDataProvider` then hard-deletes them.
+Reversing the order would make matching those rows impossible once the addresses are gone.
+
+**`ReviewDataProvider` needs review.** It moved from Customer-scope to User-scope on the
+reasoning that authorship is a personal attribute, not a business-account attribute — but this
+hasn't been fully validated against how reviews are actually attributed in this codebase. The
+class carries a `NEEDS REVIEW` note; revisit before relying on it for a real request.
+
+### Orders are pseudonymized, not deleted
+
+GDPR Art. 17(3)(b) explicitly allows retaining data an erasure request would otherwise cover,
+when a legal obligation requires it — tax/accounting law generally requires invoices be kept for
+several years. `OrderDataProvider::eraseForCustomer()` clears the free-text PII fields on `Order`/
+`OrderAddress` (`customer_reference`, `notes`, name/address/contact fields) but leaves the order
+row, totals, line items, and tax data fully intact. Its `ProviderErasureResult` reports
+`ErasureOutcome::Pseudonymized`, not `Erased` — a compliance report or admin UI can see exactly
+why an order wasn't deleted without reading `OrderDataProvider`'s source.
+
+### Reviews are matched by email — a real, documented limitation
+
+`ProductReview` has no FK to Customer/User at all (see `docs/product-listing.md` "Reviews") —
+it's deliberately anonymous, just free-text `reviewer_name`/`reviewer_email`. `ReviewDataProvider`
+matches by `reviewer_email` against `UserSubject::$email`; a review submitted under a different
+email than the one on file simply won't be found. There's no stronger signal available without
+changing `ProductReview`'s schema.
+
+### Staff/employee data is out of scope
+
+`Staff` (admin/panel employees) is never a `UserSubject`/`CustomerSubject` at all — this feature
+is scoped to customer-initiated and staff-initiated-on-a-customer's-behalf requests. An employee's
+own data (a different HR/access-management concern) isn't reachable through this flow.
+
+---
+
+## Erasure isn't immediate — a cancellable grace period
+
+`PrivacyService` has parallel methods for each scope: `requestErasureForCustomer()` /
+`requestErasureForUser()`. Neither erases anything immediately. Each opens a `DataErasureRequest`
+(`pending`, `scheduled_for` = now + `config('core.privacy.grace_period_days')`, default 30). This
+mirrors Shopify's own account-deletion flow: a window where the subject can change their mind
+before anything is actually erased.
+
+**Only the User-scoped request deactivates a login.** `requestErasureForCustomer()` deactivates
+no one — a business-account erasure must never block anyone's access.
+`requestErasureForUser()` deactivates that one User's login (blocks it — see
+`Modules\Core\Auth\Services\UserOtpService` — nothing else changes).
+
+```php
+use Modules\Core\Privacy\Services\PrivacyService;
+
+$service = app(PrivacyService::class);
+
+// Customer-scoped: either the Customer itself (self-service) or a Staff member.
+$request = $service->requestErasureForCustomer($customer, $requestedBy);
+
+// User-scoped: either the User itself (self-service) or a Staff member.
+$request = $service->requestErasureForUser($user, $requestedBy);
+
+// Cancel before scheduled_for — for a User-scoped request, reactivates the
+// account. A Customer-scoped request never deactivated anything, so there's
+// nothing to reactivate for it.
+$service->cancelErasure($request);
+```
+
+### Logging back in during the grace period cancels the request automatically
+
+Authentication is never blocked by deactivation — `UserOtpService::validate()` still requires
+the correct OTP code. Once validated, it dispatches `Modules\Core\Auth\Events\UserAuthenticated`;
+`Modules\Core\Privacy\Listeners\CancelErasureOnLoginListener` (registered in
+`PrivacyServiceProvider`, **queued** — see below) looks for a pending request keyed on *that
+User's own id* — never a Customer-scoped one, since Customer-scope never deactivates a login in
+the first place — and calls `cancelErasure()` on it, then reverts every Customer erasure request
+it caused (see "The sole-owner cascade" below). Logging back in **is** the "I changed my mind"
+action — no separate UI/flow needed for reactivation.
+
+This listener is queued rather than synchronous, so login returns to the browser without waiting
+on the bookkeeping. Nothing else in this codebase currently reads `deactivated_at` besides this
+listener and `PrivacyService` itself — `UserOtpService::validate()` never gates the login on it —
+so the brief window between the login response and the job actually running has no other consumer
+to observe it as stale.
+
+### The sole-owner cascade — erasing the last User on a Customer also erases the Customer
+
+If a User is erased and they were the **only** User linked to a given Customer, that Customer's
+data (orders, addresses, buyer record) becomes permanently unreachable through any login the
+moment the User's identity is gone — nobody could ever again log in to exercise a data-subject
+right over it. GDPR's data minimization principle (Art. 5(1)(c)) means it shouldn't just sit
+there indefinitely with no legitimate purpose.
+
+`requestErasureForUser()` and `requestImmediateErasureForUser()` both fire
+`Modules\Core\Privacy\Events\UserErasureRequested` right after the request is created (and, for
+the immediate path, before `completeErasure()` runs — see below).
+`Modules\Core\Privacy\Listeners\CascadeCustomerErasureListener` (**queued**, registered in
+`PrivacyServiceProvider`) handles it: for every Customer the User is linked to, if that User is
+currently the *sole* linked User (count is 1, and that one User is this one — not just count ===
+1, to be explicit rather than relying on an assumption), it opens a second, independent
+grace-period request via `requestErasureForCustomer($customer, $user, causedByRequestId: ...)`.
+Both requests then run through their own separate 30-day windows.
+
+```
+User erasure requested
+   │
+   ▼
+UserErasureRequested event ──▶ CascadeCustomerErasureListener (queued)
+                                    │
+                                    ▼
+                    for each linked Customer: sole owner?
+                                    │ yes
+                                    ▼
+                    requestErasureForCustomer(..., causedByRequestId: <user request id>)
+```
+
+**Tracing the cascade — `caused_by_request_id`.** A cascade-created Customer request's
+`caused_by_request_id` points back at the User request that triggered it. This is what lets
+`CancelErasureOnLoginListener` revert *exactly* the cascade a User's own cancellation should
+undo (via `DataErasureRequest::caused()`) without ever touching an unrelated, independently
+staff-requested Customer erasure the User happens to still be linked to.
+
+**Why this is queued, not synchronous.** `CascadeCustomerErasureListener` runs as an independent,
+separately-retryable job rather than inline inside `requestErasureForUser()` — a failure in the
+cascade check never rolls back or blocks the User's own request, and there's no
+`DB::transaction()` wrapping needed, since the two writes (the User's request, and any cascaded
+Customer request) aren't required to be atomic with each other.
+
+**A known, accepted race on the immediate-erasure path only.** Because the listener is queued,
+Eloquent re-fetches its models fresh when the job actually runs (see
+`Illuminate\Queue\SerializesModels`) — so `$event->request->subject->customers` reflects the
+*real* state at execution time, not a stale snapshot from dispatch time. For
+`requestImmediateErasureForUser()`, that job may run before or after `completeErasure()` detaches
+the User's memberships in the same call. If the detach happens first, the User is simply no
+longer linked to anything by the time the cascade job runs, and nothing cascades — an accepted
+race for that rare, staff-only path (see "Immediate erasure" below), not a concern for the
+everyday `requestErasureForUser()` grace-period path, where nothing detaches until its own later,
+separate `completeErasure()` run — well after the cascade job has had time to fire.
+
+### Processing due requests — one job per request
+
+`php artisan boboko:privacy:process-erasure-requests` finds every `pending` request whose
+`scheduled_for` has passed and dispatches one `Modules\Core\Privacy\Jobs\EraseDataSubjectJob` per
+request — it does not run `completeErasure()` inline itself. Each job independently calls
+`PrivacyService::completeErasure()`, which checks the request's polymorphic `subject` and calls
+either every registered provider's `eraseForCustomer()` or `eraseForUser()`, writing the full
+per-provider outcome onto the request's `report` column and marking it `completed`. One job per
+request means one request's failure (a provider throwing, a DB error) doesn't block or crash
+processing of the others, and Laravel's normal per-job retry/failure handling applies to each
+request independently. This package doesn't register a schedule itself; each consuming app wires
+the command into its own scheduler (daily is reasonable), the same way it owns any other
+scheduled task.
+
+### Immediate erasure — staff-only, not self-service
+
+`requestImmediateErasureForCustomer(Customer $customer, Staff $requestedBy): ErasureReport` and
+`requestImmediateErasureForUser($user, Staff $requestedBy): ErasureReport` bypass the grace
+period entirely and erase right away. Both are `Staff`-only **by type**, not just by convention —
+their signatures take `Staff $requestedBy` specifically (not the union type the grace-period
+methods accept), so a self-service/customer-facing code path can't reach either one even by
+accident; calling with a `Customer`/`User` actor is a compile-time type error, not a runtime
+check to remember.
+
+This exists for a formal legal request or regulator inquiry that genuinely requires immediate
+action, not as a convenience for an impatient customer. GDPR Art. 17 requires erasure "without
+undue delay," but doesn't set a maximum number of days for a grace period, and a short, disclosed,
+cancellable hold before executing a self-service request is a widely-used, generally accepted
+pattern (the same one Shopify and most major platforms use) — it is **not** offered as a
+same-click alternative on the self-service deletion flow, since doing so would mostly defeat the
+grace period's purpose (protecting an impulsive requester from themselves). If a subject
+explicitly insists on immediate deletion, that's a staff/support decision to make on the record
+via one of these methods, not a checkbox exposed to every customer.
+
+```php
+$report = $service->requestImmediateErasureForCustomer($customer, $staffMember);
+$report = $service->requestImmediateErasureForUser($user, $staffMember);
+// Both run synchronously — no queueing, no grace period. $report is the same
+// ErasureReport completeErasure() would produce.
+```
+
+---
+
+## Export — queued, not synchronous
+
+Export gathers real data across every registered provider — potentially slow, and there's no
+reason to block whatever request triggered it (a customer clicking "export my data," an API
+call). `requestExportForCustomer()`/`requestExportForUser()` are fast synchronous calls that only
+create a `DataExportRequest` row and dispatch the actual work:
+
+```php
+$request = $service->requestExportForCustomer($customer);
+$request = $service->requestExportForUser($user);
+// $request->status is 'pending'; nothing has been gathered yet.
+```
+
+### The event chain
+
+1. **`ExportDataSubjectJob`** (queued) checks the request's polymorphic `subject` and calls every
+   registered provider's `exportForCustomer()` or `exportForUser()` — all sequentially, in this
+   one job, not fanned out into one job per provider. Per-subject export work is small (a handful
+   of indexed queries per provider), so there's no real parallelism win, and one job means
+   "finished" is just "`handle()` returned," with no `Bus::batch()`/completion-counting needed. If
+   a future provider ever does something genuinely slow (an external API call, a generated PDF),
+   that's the point to reconsider a per-provider batch — not before.
+2. Once every provider's data is gathered, the job fires **`PersonalDataGathered`**
+   (carries the request and the assembled `ExportReport`) — no file exists yet.
+3. **`Modules\Core\Privacy\Listeners\WriteExportToCsvListener`** (registered in
+   `PrivacyServiceProvider`) handles that event: turns each provider's data into its own CSV (via
+   the generic `Modules\Core\Export\CsvWriter` — see below), zips them together, writes the zip to
+   `storage/app/exports/privacy/`, and updates the request (`status: completed`, `file_path`).
+   This is its own listener — not inline in the job — so the export *format* is swappable (an app
+   could unregister this and register a JSON-only listener instead) without touching how data is
+   gathered.
+4. Once the file exists, that listener fires **`PersonalDataExportFileWritten`**.
+5. Core has no opinion on how the subject is told. A consuming app registers its own notification
+   against `PersonalDataExportFileWritten` via `Modules\Core\Notification\NotificationRegistry` —
+   the same pattern as `App\Notifications\QuestionnaireResultsSentNotification` listening on
+   `App\Events\QuestionnaireResultsSent` (see `boboko-test` for a working example). Core
+   deliberately does not send an email itself.
+
+### CSV shape
+
+Every provider's `data` is either a list of associative arrays (addresses, orders, reviews — each
+item becomes a row) or a single associative array (customer — becomes one row). Any nested array
+value within a row (e.g. an order's `addresses` sub-array) is JSON-encoded into that one cell
+rather than exploded into further columns — a generic, provider-agnostic rule in
+`WriteExportToCsvListener`, not something each provider has to think about.
+
+### `Modules\Core\Export\CsvWriter` — a generic, reusable piece
+
+`CsvWriter::write(array $columns, iterable $rows, string $path)` has no knowledge of GDPR,
+customers, or Lunar at all — a caller supplies a schema (`CsvColumn[]`, each just a header plus a
+closure that pulls that column's value out of one record) and any iterable data source. It's used
+here by `WriteExportToCsvListener`, but is equally usable for an unrelated future need — an admin
+bulk catalog export, an accounting handoff — by supplying a different schema and row source;
+nothing about it is GDPR-specific.
+
+---
+
+## Audit trail
+
+`DataErasureRequest` (`data_erasure_requests`) and `DataExportRequest` (`data_export_requests`)
+are the audit records for erasure and export respectively. Both have a polymorphic `subject`
+(`subject_type`/`subject_id`, pointing at either a Lunar `Customer` or a `User` — never both) —
+`subject_type`/`subject_id`/`email` are stored as a **snapshot**, not looked up live, since the
+whole point is for these tables to remain readable after the record they're about has been
+erased. `DataErasureRequest::isForCustomer()` tells you which scope a given request is.
+
+`DataErasureRequest.requested_by_type`/`requested_by_id` capture who asked for it (the subject
+themselves, self-service; `Staff` acting on their behalf; or, for a cascade-created Customer
+request, the User whose erasure caused it — see "The sole-owner cascade") at request time.
+`DataErasureRequest.caused_by_request_id` is set only on a cascade-created Customer request,
+pointing back at the User request that triggered it; null on every normal, directly-requested
+erasure — see `DataErasureRequest::causedBy()`/`::caused()`.
+`DataErasureRequest.report` holds the full per-provider outcome once `completeErasure()` runs;
+`DataExportRequest.file_path` points at the generated zip once `WriteExportToCsvListener`
+finishes.
+
+**Not yet built**: a standalone "leave/remove from a Customer account" action — unlinking a User
+from a Customer without any erasure involved (e.g. a teammate leaving a project, or an account
+admin removing someone) — is a related but separate, smaller feature, deliberately out of scope
+for this module so far. It shares the same pivot-detach primitive `CustomerDataProvider::
+eraseForUser()` already uses as part of a full erasure, but as a standalone action it doesn't
+exist yet.

docs/product-listing.md

@@ -1,10 +1,11 @@
 # Product Listing
 
-`Modules\Core\Product\Services\ProductService` provides catalog browsing/filtering AND single-product
-lookup for a storefront — `list()`, `getById()`, `getBySlug()` — all reading directly from the
-Meilisearch index rather than the database. One data source for everything this service does.
+`Modules\Core\Catalog\Services\ProductService` provides catalog browsing/filtering AND single-product
+lookup for a storefront — `list()`, `getById()`, `getBySlug()`, `random()`, `variantSummaries()` —
+all reading directly from the Meilisearch index rather than the database. One data source for
+everything this service does.
 
-This is separate from `Modules\Core\Product\Services\ProductSearchService` (see `product-search.md`), which
+This is separate from `Modules\Core\Catalog\Services\ProductSearchService` (see `product-search.md`), which
 handles free-text query search. `ProductService` is for browsing/lookup without a search term.
 
 ---
@@ -14,7 +15,7 @@ handles free-text query search. `ProductService` is for browsing/lookup without
 Every method here reads Meilisearch documents directly and returns plain arrays — never Scout's
 `->get()`, which would re-hydrate Eloquent models from the database. This means the index has to
 carry everything a detail page needs (variants, prices, options, media, reviews — see below), not
-just the trimmed fields a listing page needs. `Modules\Core\Product\Services\ProductIndexer` is built to
+just the trimmed fields a listing page needs. `Modules\Core\Catalog\Services\ProductIndexer` is built to
 carry that full shape.
 
 ---
@@ -22,28 +23,34 @@ carry that full shape.
 ## Usage
 
 ```php
-use Modules\Core\Product\DTOs\ProductFilters;
-use Modules\Core\Product\Services\ProductService;
-use Modules\Core\Product\Enums\ProductSort;
+use Modules\Core\Catalog\DTOs\ProductFilters;
+use Modules\Core\Catalog\Services\ProductService;
+use Modules\Core\Catalog\Enums\ProductSort;
 
 $service = app(ProductService::class);
 
-// List everything, paginated — returns a real Illuminate\Pagination\LengthAwarePaginator,
-// built from the localized Meilisearch hits (not Scout's own paginateRaw() result — see
-// "Meilisearch driver quirk" below), so it behaves like any other Laravel paginator.
-$products = $service->list(perPage: 24, page: 1);
+// One call for everything a listing page needs — products AND the price slider's
+// bounds together, as a Modules\Core\Catalog\DTOs\ProductListingResult. A caller
+// used to have to call list() and priceSliderBounds() (or the older priceRange())
+// separately and glue the results together itself; that's now list()'s own job.
+$listing = $service->list(perPage: 24, page: 1);
 
-// Filter by collection, brand, and/or price range
-$products = $service->list(
-    filters: new ProductFilters(collectionId: 17, minPrice: 10.0, maxPrice: 50.0),
+// Filter by collection, brand, price range, and/or stock
+$listing = $service->list(
+    filters: new ProductFilters(collectionId: 17, minPrice: 10.0, maxPrice: 50.0, inStockOnly: true),
     perPage: 24,
     page: 1,
 );
 
 // Sort — cheapest/priciest first, or newest first. Omit for Meilisearch's default
 // relevance ordering (irrelevant here since the query is always empty).
-$products = $service->list(perPage: 24, page: 1, sort: ProductSort::PriceAsc);
+$listing = $service->list(perPage: 24, page: 1, sort: ProductSort::PriceAsc);
 
+$products = $listing->products;  // a real Illuminate\Pagination\LengthAwarePaginator,
+                                  // built from the localized Meilisearch hits (not Scout's
+                                  // own paginateRaw() result — see "Meilisearch driver
+                                  // quirk" below), so it behaves like any other Laravel
+                                  // paginator.
 $products->items();            // array of Meilisearch documents (plain arrays, not models)
 $products->total();
 $products->perPage();
@@ -51,36 +58,91 @@ $products->currentPage();
 $products->lastPage();
 $products->links();            // in a Blade view — renders pagination links as usual
 
+$bounds = $listing->priceBounds;  // Modules\Core\Catalog\DTOs\PriceSliderBounds
+$bounds->floor;    // ?int — floor() of the matching range's minimum, in whole currency units
+$bounds->ceil;     // ?int — ceil() of the matching range's maximum
+$bounds->filtered; // bool — whether the applied filters' minPrice/maxPrice actually
+                   // narrow the slider below/above these bounds (drives whether a
+                   // "clear filter" control should show)
+
 // Single product, by primary key
 $product = $service->getById(367);   // array, or null if not found
 
 // Single product, by URL slug (any locale — slugs are indexed across all languages)
 $product = $service->getBySlug('erotika-mprelok');   // array, or null if not found
+
+// $limit random products — still scoped to the index's own default channel/status
+// visibility, unlike Eloquent's Product::inRandomOrder() (which has no notion of
+// that filtering at all). Meilisearch has no ORDER BY RANDOM() equivalent, so this
+// pulls every matching id only, shuffles in PHP, then fetches the full localized
+// documents for just the ids picked — see random()'s own docblock.
+$randomProducts = $service->random(13);   // array of documents, same shape as list()'s items
+
+// The id/price/image of every variant on a product document — the base price and
+// thumbnail a variant picker/swatch list needs, without reaching into
+// $product['variants'][n]['prices'][0]/['media'][0] yourself.
+$variants = $service->variantSummaries($product);
+// [['id' => 1204, 'price' => 19.99, 'image' => 'https://.../thumb.jpg'], ...]
+
+// Facet counts for a sidebar — value => matching product count, scoped to whatever
+// $filters is passed. Does NOT exclude the faceted field itself from $filters — see
+// facets()'s docblock for why, and how to build a standard "every option's count,
+// unaffected by that option's own currently-selected value" sidebar.
+$brandCounts = $service->facets('brand', filters: new ProductFilters(collectionId: 17));
+// ['3Dealer.gr - 3D printed creations' => 48, 'Kraniou Topos - 3D printed creations' => 135]
+
+// Min/max price across matching products — the raw, unrounded values list() itself
+// uses to build priceBounds above. minPrice/maxPrice are ALWAYS excluded from the
+// filter driving this (unlike facets(), which doesn't auto-exclude) — the slider's
+// own bounds shouldn't shrink to whatever range is currently selected on it. Other
+// filters (collectionId, brand, inStockOnly) still apply normally. Pass $query too
+// to scope the range to a text search's own matches (see product-search.md) rather
+// than the whole catalog.
+$range = $service->priceRange(new ProductFilters(collectionId: 17));
+// ['min' => 0.0, 'max' => 120.0]
 ```
 
 All `ProductFilters` fields are optional; only the ones set are added to the Meilisearch query.
 
+`facets()` only makes sense on discrete-value filterable fields (`brand`, `in_stock`) — a numeric
+field like `price` would return one "facet" per exact price, not a usable range bucket. Use
+`priceRange()` (or `list()`'s own `priceBounds`) for `price` instead, which reads Meilisearch's
+`facetStats` (min/max), a different feature from `facetDistribution`.
+
 ---
 
-## Fields this depends on: `Modules\Core\Product\Services\ProductIndexer`
+## Stock goes stale between orders
+
+`in_stock` reflects `ProductVariant::stock`/`purchasable` as of the **last reindex**, not live
+inventory. Nothing in this codebase currently reindexes a product when an order decrements its
+stock — that's a cart/checkout concern, not something `ProductIndexer` can solve on its own (see
+`Modules\Core\Catalog\Observers\ProductOptionReindexObserver` for the equivalent pattern once an
+order → stock → reindex pipeline exists to hook into). Until then, `in_stock`/`product_count` can
+drift from the database the same way every other indexed field already can between writes.
+
+---
+
+## Fields this depends on: `Modules\Core\Catalog\Services\ProductIndexer`
 
 Lunar's own `Lunar\Search\ProductIndexer` only carries listing-grade fields (name, description,
 status, brand, a single thumbnail, skus) and marks just `__soft_deleted`, `skus`, `status` as
-filterable. `Modules\Core\Product\Services\ProductIndexer` extends it to add everything `ProductService`
+filterable. `Modules\Core\Catalog\Services\ProductIndexer` extends it to add everything `ProductService`
 needs, listing and detail alike:
 
 | Field | Source | Notes |
 |---|---|---|
 | `id` | — | Newly marked **filterable** — needed for `getById()`'s `id = "..."` filter; Meilisearch doesn't filter on the primary key by default. |
-| `collections` | `$product->collections->pluck('id')` | Filterable. Array of collection IDs (as strings) — filtering matches by ID, not slug. |
-| `collection_names` | `$product->collections` | Display only, not filterable — translated collection names. |
+| `collections` | `$product->collections` | Array of `{id, name}` — directly assigned collections only, `name` is the translated collection name. Not filterable — see `collection_ids`. |
+| `collection_ids` | `$product->collections` + `->ancestors` | Filterable. Flat array of every directly-assigned collection's id, unioned with all of its ancestors' ids. `ProductFilters(collectionId: ...)` filters against this field, not `collections`, since products are typically attached only to leaf collections — a plain direct-match filter would never return anything for a parent/root category page. |
 | `slugs` | `$product->urls->pluck('slug')` | Filterable. Every locale's `Url::slug` for the product, so `getBySlug()` resolves purely from the index — no database read. |
+| `skus` | `$product->variants->pluck('sku')` | Filterable. Every variant's `sku`, deduplicated, empty ones dropped. Same "resolve from the index alone" reasoning as `slugs`, for a future SKU-based lookup/filter. |
 | `price` | Cheapest variant's base price | Filterable. Float in major units (e.g. `19.99`, not `1999`). Base price only — no customer group, default currency (`Currency::getDefault()`) only. `null` if the product has no priced variant yet, so it's excluded from range filters rather than treated as free. |
 | `brand` | Already indexed by Lunar's base indexer | Newly marked **filterable** — it existed in the document already, just wasn't usable in a `filter` clause. |
 | `tags` | `$product->tags->pluck('value')` | Display only. |
 | `media` | `$product->media` | Full gallery (id/url/thumb per image), not just the single thumbnail Lunar's base indexer sends. |
-| `variants` | `$product->variants` | Per variant: `id`, `sku`, `stock`, `purchasable`, `options` (option/value names, in the current locale), `prices` (per currency/customer group), `media` (variant-specific images). |
-| `reviews`, `review_count`, `average_rating` | `Modules\Core\Review\Models\ProductReview` | See "Reviews" below. |
+| `variants` | `$product->variants` | Per variant: `id`, `sku`, `gtin`, `mpn`, `ean`, `stock`, `backorder`, `unit_quantity`, `purchasable`, `shippable`, `tax_ref`, `dimensions` (`length`/`width`/`height`/`weight`/`volume`, each `{value, unit}`), `options` (option/value names, in the current locale), `prices` (per currency/customer group), `media` (the variant's own images — `ProductVariant::images()`, a separate pivot from the product's own gallery above, populated by `ShopifyExportImporter` from Shopify's `Variant Image` CSV column). |
+| `reviews` | `Modules\Core\Review\Models\ProductReview` | `{items, count, average_rating}` — see "Reviews" below. |
+| `in_stock` | `$model->variants` | Filterable boolean. `true` if ANY variant currently passes `ProductVariant::canBeFulfilledAtQuantity(1)` — Lunar's own purchasability rule (`purchasable === 'always'` ignores stock entirely; `in_stock` checks `stock` alone; anything else checks `stock + backorder`). Only as fresh as the last reindex — see "Stock goes stale" below. |
 
 `name`/`description` (and any other `TranslatedText` attribute) are indexed per-locale — see
 "Locale resolution" below for how `ProductService` resolves them down to one value per request.
@@ -121,11 +183,12 @@ description sourced from `ProductService`'s results must treat it as trusted HTM
 
 ## Reviews
 
-`Modules\Core\Review\Models\ProductReview` (`product_reviews` table) is indexed per-product as
-`reviews` (array), plus `review_count` and `average_rating` (rounded to 1 decimal, `null` if the
-product has no reviews). Only public-safe fields are included — **`reviewer_email` is deliberately
-excluded**, it's PII with no storefront use. `reply`/`replied_at` (the staff response) are
-included, since they're meant to be shown alongside the review.
+`Modules\Core\Review\Models\ProductReview` (`product_reviews` table) is indexed per-product under
+a single `reviews` key: `{items, count, average_rating}` — `items` is the array of reviews,
+`average_rating` is rounded to 1 decimal (`null` if the product has no reviews). Only public-safe
+fields are included on each item — **`reviewer_email` is deliberately excluded**, it's PII with no
+storefront use. `reply`/`replied_at` (the staff response) are included, since they're meant to be
+shown alongside the review.
 
 A review is created/edited independently of its product (a customer submission, a staff reply)
 — its own save doesn't touch the `Product` row, so the product's own model events never fire.
@@ -149,9 +212,9 @@ variants don't.
 
 ## Sorting
 
-`ProductSort` (`Modules\Core\Product\Enums\ProductSort`) is a fixed enum of supported sort orders —
+`ProductSort` (`Modules\Core\Catalog\Enums\ProductSort`) is a fixed enum of supported sort orders —
 `PriceAsc`, `PriceDesc`, `Newest` — each mapping to a Meilisearch `sort` clause against a field
-`Modules\Core\Product\Services\ProductIndexer::getSortableFields()` marks sortable (`price`, plus
+`Modules\Core\Catalog\Services\ProductIndexer::getSortableFields()` marks sortable (`price`, plus
 `created_at`/`updated_at`/`skus`/`status` inherited from Lunar's base indexer). Adding a new
 `ProductSort` case requires adding the matching field to `getSortableFields()` and re-syncing (see
 below) — sortable attributes are index settings, not computed per-query, same as filterable ones.
@@ -168,7 +231,7 @@ Not automatic — an app opts in via its own `config/lunar/search.php`:
 
 ```php
 'indexers' => [
-    Lunar\Models\Product::class => Modules\Core\Product\Services\ProductIndexer::class,
+    Lunar\Models\Product::class => Modules\Core\Catalog\Services\ProductIndexer::class,
     // ...other model indexers unchanged
 ],
 ```

docs/product-options.md

@@ -6,7 +6,7 @@ Each `ProductOptionValue` carries a free-form `meta` jsonb column, but nothing i
 Lunar's own admin UI exposes it — there's no way for an admin to, say, attach a hex
 code to a "Red" value without editing the database directly.
 
-`Modules\Core\Product\Contracts\ProductOptionTypeInterface` describes how a category
+`Modules\Core\Catalog\Contracts\ProductOptionTypeInterface` describes how a category
 of option behaves — what structured data its values carry in `meta`, and how an
 admin edits that data — without introducing a new model. `ProductOption`/
 `ProductOptionValue` stay exactly as Lunar defines them.
@@ -15,21 +15,23 @@ admin edits that data — without introducing a new model. `ProductOption`/
 
 ## Registering a type
 
-A shop enables a type class in `config/core.php`:
+A shop registers a type class from its own service provider's `boot()`, the same
+shape as `Modules\Core\Notification\NotificationRegistry`:
 
 ```php
-// config/core.php
-'product_option_types' => [
+use Modules\Core\Catalog\Services\ProductOptionTypeManager;
+
+ProductOptionTypeManager::get()->register([
     \App\ProductOptions\ColorOptionType::class,
-],
+]);
 ```
 
-This is a plain list, **not** keyed by `ProductOption::handle` — a shop's own handle
-naming (transliterated Greek, legacy import slugs, whatever an admin happened to type
-when creating the option) shouldn't have to match a type's key. Instead, an admin
-picks a type per-option from a dropdown on the `ProductOption` edit form itself (see
-below); the choice is stored in `ProductOption::meta['option_type']`, not inferred
-from anything else.
+Not a published config array — the mapping isn't per-`ProductOption`, so there's
+nothing for a shop to *key* by. Instead, an admin picks a type per-option from a
+dropdown on the `ProductOption` edit form itself (see below); the choice is stored
+in `ProductOption::meta['option_type']`, deliberately **not** tied to the option's
+`handle` (a shop's own handle naming — transliterated Greek, legacy import slugs —
+shouldn't have to match a type's key).
 
 A `ProductOption` with no type selected behaves exactly as stock Lunar does — plain
 name/position, no extra meta form.
@@ -42,7 +44,7 @@ name/position, no extra meta form.
 namespace App\ProductOptions;
 
 use Filament\Forms\Components\ColorPicker;
-use Modules\Core\Product\Contracts\ProductOptionTypeInterface;
+use Modules\Core\Catalog\Contracts\ProductOptionTypeInterface;
 
 class ColorOptionType implements ProductOptionTypeInterface
 {
@@ -68,28 +70,34 @@ plain jsonb column). `getKey()` is the identifier used in the admin's "Option Ty
 dropdown and in `ProductOption::meta['option_type']` — it has no relationship to the
 `ProductOption::handle`.
 
-A reference implementation ships at `Modules\Core\Product\OptionTypes\ColorOptionType`
-— not auto-registered, since registration is always an explicit shop decision.
+A reference implementation ships at `Modules\Core\Catalog\OptionTypes\ColorOptionType`,
+registered automatically by `Modules\Core\Providers\CatalogServiceProvider` — no shop
+setup needed for it to appear in the "Option Type" dropdown, though an admin still
+has to pick it per-`ProductOption` for it to take effect.
 
 ---
 
 ## How it's wired into the admin UI
 
-`Modules\Core\Product\Services\ProductOptionTypeManager`:
-- `all(): Collection<string, ProductOptionTypeInterface>` — every enabled type,
-  keyed by `getKey()`.
-- `resolve(?string $key): ?ProductOptionTypeInterface` — looks up one by key (or
-  `null` if no key / not found).
+`Modules\Core\Catalog\Services\ProductOptionTypeManager` is a singleton registry:
+- `get(): static` — the shared instance.
+- `register(array $types): void` — registers one or more type classes, keyed
+  internally by `getKey()`.
+- `unregister(string $key): void`
+- `resolve(?string $key): ?ProductOptionTypeInterface` — looks up a registered type
+  by key (or `null` if no key / not found).
+- `all(): array<string, class-string>` — every registered type's class, keyed by
+  `getKey()`.
 
 Two extensions hook into Lunar's admin via its extension system
 (`LunarPanel::extensions([...])`, registered in `CorePlugin`) — no forking of Lunar's
 classes needed:
 
-- `Modules\Core\Product\Filament\Extensions\ProductOptionResourceExtension` extends
+- `Modules\Core\Catalog\Filament\Extensions\ProductOptionResourceExtension` extends
   `Lunar\Admin\Filament\Resources\ProductOptionResource`'s own form with a `Select`
   (`meta.option_type`) listing every enabled type's key. Shown only when at least one
   type is enabled.
-- `Modules\Core\Product\Filament\Extensions\ValuesRelationManagerExtension` extends
+- `Modules\Core\Catalog\Filament\Extensions\ValuesRelationManagerExtension` extends
   the "Values" tab's form. Its `extendForm()` reads
   `$option->meta['option_type']` off the owning `ProductOption`, resolves it via
   `ProductOptionTypeManager`, and appends `getMetaForm()`'s fields to the stock name

docs/product-recommendations.md

@@ -0,0 +1,155 @@
+# Product Recommendations
+
+`Modules\Core\Catalog\Services\RecommendationService` computes "related products" for a given
+product — a same-category pick today, with a random fallback, but built as a configurable chain of
+strategies rather than one hardcoded rule. `Modules\Core\Catalog\Services\ProductIndexer` embeds
+the result directly into each product's own Meilisearch document, so a product detail page renders
+its recommendations with zero extra queries — same reasoning as `collections` (see
+`docs/product-listing.md`).
+
+---
+
+## The rule chain
+
+```php
+use Modules\Core\Catalog\Services\RecommendationService;
+
+$recommendations = app(RecommendationService::class)->recommend($product, limit: 4);
+// Illuminate\Support\Collection<int, Lunar\Models\Product>
+```
+
+`recommend()` walks `config('catalog.recommendation_rules')` in order, **topping up** from each
+successive rule until `$limit` distinct products are collected or every rule is exhausted — it does
+not stop at the first rule that returns *something*. If a product's category only has 3 other
+products, `SameCategoryRule` contributes those 3 and `RandomRule` fills the last slot. A rule is
+handed the ids already collected (`$exclude`, always including the source product's own id) so it
+never wastes its own `$limit` budget re-suggesting something already picked, and the same product
+is never returned twice even if two rules would both suggest it.
+
+Default chain (`config/catalog.php`):
+
+```php
+'recommendation_rules' => [
+    SameCategoryRule::class,   // other products sharing $product's first collection
+    RandomRule::class,          // universal fallback — always returns something as
+                                 // long as the store has more than one product
+],
+```
+
+A consuming app publishes and edits this config to reorder, add, or remove rules — nothing about
+the chain shape is hardcoded in `RecommendationService` itself. A new rule (same tag, best sellers,
+"frequently bought together", ...) is a class implementing `Modules\Core\Catalog\Contracts\
+RecommendationRule`, added to the array:
+
+```php
+interface RecommendationRule
+{
+    /**
+     * @param  array<int>  $exclude  ids to never return — the source product's own
+     *   id, plus every id an earlier rule in the chain already picked
+     * @return Collection<int, Product>  at most $limit products
+     */
+    public function recommend(Product $product, int $limit, array $exclude): Collection;
+}
+```
+
+Rules query Eloquent directly (`$product->collections->first()->products()`, `Product::query()`),
+not `Modules\Core\Catalog\Services\ProductService` — see "Why not `ProductService`" below.
+
+---
+
+## Why not `ProductService`
+
+Every other read path in `Modules\Core\Catalog` goes through `ProductService`, which reads
+Meilisearch and resolves translated fields to whatever locale the *current request* is in (see
+`docs/product-listing.md`, "Locale resolution"). Recommendation rules deliberately don't use it:
+they run inside `ProductIndexer::toSearchableArray()`, at **index time** — there is no request, no
+meaningful "current locale" to resolve against, and Meilisearch itself may be mid-write for the very
+product being indexed. Rules return raw `Lunar\Models\Product` models instead; `ProductIndexer`
+resolves what it embeds (`name` via `translateAttribute()`, `price` via the indexer's own
+`cheapestPrice()`, `image` via its own `mapMedia()`) the same way it already does for the embedded
+`collections` field — including that field's same accepted index-time-locale tradeoff (a
+recommendation's embedded `name` reflects whatever locale was active when *that* product was last
+indexed, not the viewer's current locale).
+
+---
+
+## What's embedded, and why not just an id
+
+`ProductIndexer` embeds full card data per recommendation, not just an id:
+
+```php
+$data['recommendations'] = [
+    ['id' => 42, 'name' => 'Espresso Cup', 'price' => 12.5, 'image' => 'https://.../thumb.jpg'],
+    // ...
+];
+```
+
+This shape is deliberately exactly what `x-ui.product-card`/`x-product-grid` (3dealer's storefront
+components) need — `name`, `price`, `image`, and an `id` the view resolves to a URL itself via
+`route('product.show', ['id' => $rec['id']])`. A resolved `href` is **not** embedded: `product.show`
+is locale-prefixed (`{locale}/products/{id}`), so a URL baked in at index time would be correct only
+for whichever locale happened to be active during that index run — wrong for every other locale.
+Building the URL is left to the view, which knows the current request's locale.
+
+`recommendations.id` is marked **filterable** — not for the storefront, but for the reverse-lookup
+reindexing below.
+
+---
+
+## Keeping it fresh: `ProductSaved` / `ProductDeleted`
+
+A recommendation is computed once, at index time, and embedded — it does not update itself when the
+recommended product later changes name, price, or image, or is deleted. Unlike `Modules\Core\Catalog\
+Observers\ProductOptionReindexObserver`'s equivalent problem (which product option value is used by),
+there is no Postgres relation for "which products currently recommend product X" — a recommendation
+only exists inside Meilisearch. The fix is a reverse Meilisearch filter query, not a database join,
+wired through a real event → listener pair (`Modules\Core\Providers\CatalogServiceProvider`):
+
+- `Product::saved()` dispatches `Modules\Core\Catalog\Events\ProductSaved`.
+- `Product::deleted()` dispatches `Modules\Core\Catalog\Events\ProductDeleted` — fires for both a
+  soft delete and a force delete (`Lunar\Models\Product` uses `SoftDeletes`), the same model event
+  Laravel Scout's own `ModelObserver` hooks to make a deleted product `unsearchable()`.
+- `Modules\Core\Catalog\Listeners\ReindexProductsRecommendingProduct` handles both: it searches the
+  product index for `recommendations.id = "{id}"`, finds every referencing product, and calls
+  `->searchable()` on each — which recomputes their `recommendations` field fresh, picking up the
+  changed name/price/image, or (for a delete) dropping the now-gone product and topping back up to
+  the configured limit via the rule chain, same as any other reindex.
+
+`->searchable()` dispatches Scout's own reindex job, queued if `SCOUT_QUEUE` is configured — this
+listener does no synchronous Meilisearch writing itself.
+
+**Product creation is deliberately not hooked into this.** A brand-new product has no
+`recommendations` of its own until Scout's existing create-triggered indexing runs (already correct
+— nothing to add). What's *not* immediate is other products picking the new one up as a fresh
+recommendation candidate — that happens on their own next natural reindex (a save, or the nightly
+full reindex below), the same accepted staleness window `docs/product-listing.md` already documents
+for `in_stock`/`price`. A full proactive "who could now recommend this new product" pass was
+considered and rejected as unnecessary cost for a cosmetic delay.
+
+---
+
+## Nightly full reindex
+
+`Modules\Core\Providers\CatalogServiceProvider` schedules `lunar:search:index "Lunar\Models\Product"
+--refresh` daily at 03:00 — a safety net on top of the event-driven reindexing above, not a
+replacement for it. Catches what event-driven reindexing deliberately doesn't cover: a newly-created
+product not yet appearing as a recommendation elsewhere, and any other drift already accepted
+between reindexes (see `docs/product-listing.md`, "Stock goes stale between orders"). `--refresh`
+also re-syncs filterable/sortable index *settings*, not just documents, so a deploy that changed
+`ProductIndexer`'s field list self-heals overnight even if `lunar:meilisearch:setup` wasn't run
+manually right after that deploy.
+
+---
+
+## Re-syncing after this change
+
+Same as any other `ProductIndexer` field change (see `docs/product-listing.md`):
+
+```bash
+php artisan lunar:meilisearch:setup
+php artisan lunar:search:index "Lunar\Models\Product" --refresh
+```
+
+Restart the queue worker if `SCOUT_QUEUE=true` — see `docs/product-listing.md`'s "Re-syncing after
+this change" for why a running worker won't otherwise pick up the new indexer code.

docs/product-search.md

@@ -1,6 +1,6 @@
 # Product Search
 
-`Modules\Core\Product\Services\ProductSearchService` provides locale-aware full-text product search on
+`Modules\Core\Catalog\Services\ProductSearchService` provides locale-aware full-text product search on
 top of Laravel Scout + Meilisearch.
 
 ---
@@ -24,36 +24,62 @@ merges `$builder->options` directly into the search request).
 ## Usage
 
 ```php
-use Modules\Core\Product\Services\ProductSearchService;
+use Modules\Core\Catalog\DTOs\ProductFilters;
+use Modules\Core\Catalog\Enums\ProductSort;
+use Modules\Core\Catalog\Services\ProductSearchService;
 
 $results = app(ProductSearchService::class)->search('running shoes');
-// or an explicit locale, bypassing App::getLocale():
-$results = app(ProductSearchService::class)->search('running shoes', 'el');
+
+// Filters/sort apply the exact same semantics ProductService::list() uses for
+// collection browsing (same ProductFilterBuilder, same ProductSort) — a shopper
+// narrowing a text search by price/brand/stock gets identical filter behavior
+// to narrowing a category listing.
+$results = app(ProductSearchService::class)->search(
+    'running shoes',
+    filters: new ProductFilters(brand: 'Acme', minPrice: 20.0, inStockOnly: true),
+    sort: ProductSort::PriceAsc,
+);
 ```
 
 Returns an `Illuminate\Database\Eloquent\Collection` of `Lunar\Models\Product` — Scout's
 `->get()` hydrates real models from the database after the Meilisearch query, so relations
 (`variants`, `brand`, `media`, etc.) are available on the results as normal.
 
-`$locale` defaults to `App::getLocale()` — already set correctly on every storefront request by
-`Modules\Core\Localization\Middleware\LocaleMiddleware` (see `localization.md`), so callers in controllers
-don't need to pass it explicitly.
+There is no `$locale` parameter — see "Field list is dynamic, not hardcoded" below for why
+every configured store language is always searched, regardless of the current request locale.
 
 ---
 
-## Missing-translation fallback
+## Missing-translation fallback, in both directions
 
 If a product was only ever given an English name, `name_el` doesn't exist on that document at
 all (Lunar's indexer only writes a `{handle}_{locale}` field for locales actually present in the
 attribute's stored data — see `ScoutIndexer::mapSearchableAttributes()`). Searching strictly
-against `name_el` would make that product invisible to Greek-locale search, even though it's a
-real catalog item.
+against the current request's locale field would make that product invisible whenever a shopper's
+locale doesn't match the language it happens to be translated into.
 
-To avoid silently hiding incompletely-translated products, `ProductSearchService` targets **both**
-the resolved locale's fields **and** the default language's fields
-(`Lunar\Models\Language::getDefault()->code`) — e.g. searching in `el` targets `name_el`,
-`name_en`, `description_el`, `description_en` together (assuming `en` is the default language).
-A product missing an `el` translation still matches via its `en` fields.
+`ProductSearchService` avoids this by targeting **every configured store language's fields**
+(`Lunar\Models\Language::all()`) on every search, not just the current request locale plus the
+store default — e.g. with `el`/`en` configured, every search targets `name_el`, `name_en`,
+`description_el`, `description_en` together, regardless of which locale the shopper is browsing
+in. This is deliberately not scoped to "current locale + default locale": if the current locale
+already equals the default (a single-language store, or a shopper browsing in the default
+language), that pairing collapses to one locale and stops catching anything else — always
+searching every configured language avoids that gap in both directions, at the cost of a larger
+`attributesToSearchOn` list as the store's language count grows.
+
+---
+
+## Variant option values are searched too
+
+Alongside the locale-suffixed attribute fields, every search also targets
+`variants.options.value` directly — e.g. a variant named "Κάπτεν Γαμέρικα" on a "Name" option
+matches a search for that text, even though it never appears in the product's own name or
+description. This isn't one of Lunar's own attributes (`AttributeManifest` has no entry for it),
+so it can't be discovered the way `name`/`description` are — it's a structural field of
+`Modules\Core\Catalog\Services\ProductIndexer`'s own document shape (see `ProductIndexer::mapVariant()`),
+added here directly. Not locale-suffixed — each option value is stored as one already-resolved
+string per variant.
 
 ---
 

docs/recovery-strategies.md

@@ -0,0 +1,128 @@
+# Cart/Checkout Recovery Strategies — Design Notes
+
+**Status: open design discussion, not scoped or built.** This is a record of the
+reasoning behind an eventual "Recovery Sequences" feature, kept so the discussion doesn't
+have to be re-derived from scratch later. Nothing in this document is implemented.
+
+See `docs/cart.md` for what's actually built today (the four-state cart classification,
+`CartAbandoned`/`CheckoutAbandoned` events, `DetectAbandonedCarts`).
+
+---
+
+## Why Abandoned Cart and Abandoned Checkout need different strategies
+
+Established in `docs/cart.md`: Abandoned Cart (no order ever started) is a weak purchase-intent
+signal and often unreachable (no identity for a true guest). Abandoned Checkout (a draft order
+exists, `placed_at IS NULL`) is a strong intent signal and usually reachable, since checkout
+typically captures an email/address even for a guest.
+
+That difference in intent and reachability drives genuinely different marketing strategy, not
+just a different admin filter:
+
+### Abandoned Cart strategy — re-engagement, not completion
+
+- **On-site retargeting first** (exit-intent popups, "still thinking it over?" banners on
+  return visits) — often the only viable channel, since email may not exist yet.
+- **Ad platform retargeting** (Meta/Google dynamic remarketing) is the dominant channel here
+  specifically because it works off a browser/device signal, not an email address — the one
+  thing reliably available for an anonymous cart.
+- **Soft messaging** ("did you forget something?") rather than urgency-driven — intent is
+  weak, so aggressive discounting is often poor ROI: it trains browsers who were never close
+  to buying to expect a coupon.
+- **Longer, gentler cadence** — a single reminder around 24h, maybe a second a few days out,
+  sometimes trigger-based (a price drop, back-in-stock) rather than a fixed schedule.
+
+### Abandoned Checkout strategy — completion, not re-engagement
+
+- **Speed matters most.** This is where the classic 1h/24h/72h recovery-email cadence lives —
+  conversion drops sharply with delay, since the shopper is often still in a "was about to
+  buy" mental state within the first hour.
+- **Direct, urgency-framed messaging** ("complete your order"), sometimes showing cart
+  contents/total, occasionally a countdown or limited-time incentive on later touches.
+- **Discount escalation pays off here** — a small incentive (free shipping, 10% off) on the
+  2nd/3rd touch is standard, because it's nudging someone who already decided to buy past
+  whatever blocked them (price shock, a broken payment step, indecision on shipping cost) —
+  not manufacturing demand from nothing.
+- **SMS is more viable** — checkout often captures a phone number, and the higher intent
+  justifies a more direct channel than for cart-stage.
+
+---
+
+## The broader strategy space (beyond cadence + discount)
+
+Raised as context for how far a "Recovery Sequence" feature might eventually need to flex,
+without committing to building any of it yet:
+
+**Message-content strategies**
+- Social proof ("X people have this in their cart," reviews shown in the reminder)
+- Scarcity/urgency framing (low-stock count, countdown timer on an offer)
+- Personalized alternatives — a cheaper or complementary item instead of just re-showing the
+  abandoned one, useful when the likely blocker was price
+
+**Channel strategies**
+- Email (the baseline; nothing built yet — see `docs/cart.md`'s "Recovery Sequences" section)
+- SMS — checkout-stage specifically, opt-in required
+- Push notifications — not relevant yet given this project's storefront maturity, noted for
+  completeness
+- On-site remarketing (banner/modal on the shopper's next visit) — doesn't require email at
+  all, arguably the highest-value channel for Abandoned Cart specifically
+- Ad platform sync (pushing abandoned-cart product data to a custom audience for paid retargeting)
+
+**Escalation/segmentation strategies**
+- Value-based branching — a high-value abandoned checkout might skip straight to a bigger
+  incentive rather than waiting through a full ladder
+- Repeat-abandoner suppression — a customer who's abandoned 3+ times without ever completing
+  either stops receiving emails (fatigue/spam risk) or gets a different tactic (e.g. a "what
+  stopped you?" survey) instead of another discount
+- New vs. returning customer branching — a first-time visitor's abandoned cart might warrant
+  "welcome discount" framing instead of a generic recovery email, since the blocker was
+  likely trust/unfamiliarity rather than price
+
+**Timing refinement**
+- Time-of-day/timezone-aware sending (don't fire a touch at 3am local time even if the delay
+  technically elapsed)
+- Cart-content-triggered timing — a fast-moving/low-stock item might warrant an earlier, more
+  urgent first touch than a cart of always-in-stock staples
+
+---
+
+## First-pass feature shape (discussed, not finalized)
+
+An admin defines, independently per abandonment type (Abandoned Cart, Abandoned Checkout), an
+ordered sequence of **touches**. Each touch is three ideas:
+
+1. **How long to wait** since the abandonment began
+2. **What offer to attach**, optional — reusing whatever `Discount` already exists in the
+   system rather than inventing a new pricing concept
+3. **A label**, so staff can see what a touch represents in the admin UI
+
+The system continuously re-evaluates every abandoned cart/checkout against its sequence, and
+when a cart becomes due for the next touch it hasn't had yet, that becomes a signal — this
+feature's responsibility ends there. Actually sending anything (email, SMS, on-site banner) is
+explicitly out of scope for this feature; something else, not yet designed, would consume that
+signal.
+
+### What this requires that isn't built yet
+
+- **A fixed "abandonment began at" timestamp**, captured once and never re-derived — a
+  sequence needs to schedule touches from a stable starting point, not from `Cart::updated_at`,
+  which keeps moving every time the cart (or its own bookkeeping) is written to. This is the
+  same underlying issue as the known bug in `docs/cart.md`'s "Abandonment detection" section —
+  fixing that bug properly (freezing the abandonment moment) is very likely a prerequisite for
+  this feature, not a separate concern.
+- **Re-evaluation, not one-shot detection** — `DetectAbandonedCarts` today marks a cart
+  abandoned once and stops; a sequence needs a cart to be revisited on every scheduler run to
+  check "which touch, if any, is now due," for as long as it stays unrecovered.
+
+### Still undecided
+
+- **Which concern this belongs under.** Not `Cart` (it's not a cart-mechanics concern) —
+  candidates raised: a new `Recovery` concern, or `Marketing`. Not decided.
+- **How far the touch model needs to flex.** The three-idea shape above (delay, discount,
+  label) covers cadence + discount escalation cleanly, but doesn't yet accommodate channel
+  choice, value-based branching, or segment targeting from the broader strategy list above.
+  Whether those get folded into the touch model, layered on top some other way, or deliberately
+  left out of v1 is unresolved.
+- **Whether "recovery" is cart/checkout-specific at all**, or a more general "scheduled
+  customer touch based on a triggering condition" mechanism that cart/checkout abandonment
+  happens to be the first use case for.

docs/scratch/analytics-feature-survey.html

@@ -0,0 +1,449 @@
+<title>Analytics Feature Survey</title>
+<style>
+  :root {
+    --paper: #FAFAF7;
+    --ink: #1C1C1A;
+    --muted: #6B6B63;
+    --accent: #2F5D50;
+    --accent-soft: #E4EDE9;
+    --good: #3F7A5C;
+    --good-soft: #E6F0EA;
+    --warn: #B8863B;
+    --warn-soft: #F5ECDC;
+    --miss: #A14B3B;
+    --miss-soft: #F5E5E0;
+    --hairline: #E4E2DB;
+    --card: #FFFFFF;
+  }
+
+  :root:not([data-theme="light"]) {
+    @media (prefers-color-scheme: dark) {
+      --paper: #17181A;
+      --ink: #EDEBE4;
+      --muted: #9B9A90;
+      --accent: #7FBFA8;
+      --accent-soft: #1E2C27;
+      --good: #6FBF97;
+      --good-soft: #1B2A22;
+      --warn: #D9A85C;
+      --warn-soft: #2C2418;
+      --miss: #D97C68;
+      --miss-soft: #2E1E1A;
+      --hairline: #2C2D2E;
+      --card: #1E1F21;
+    }
+  }
+
+  :root[data-theme="dark"] {
+    --paper: #17181A;
+    --ink: #EDEBE4;
+    --muted: #9B9A90;
+    --accent: #7FBFA8;
+    --accent-soft: #1E2C27;
+    --good: #6FBF97;
+    --good-soft: #1B2A22;
+    --warn: #D9A85C;
+    --warn-soft: #2C2418;
+    --miss: #D97C68;
+    --miss-soft: #2E1E1A;
+    --hairline: #2C2D2E;
+    --card: #1E1F21;
+  }
+
+  * { box-sizing: border-box; }
+
+  body {
+    background: var(--paper);
+    color: var(--ink);
+    font-family: "IBM Plex Sans", ui-sans-serif, system-ui, sans-serif;
+    font-size: 15.5px;
+    line-height: 1.55;
+    margin: 0;
+    padding: 4.5rem 1.5rem 6rem;
+  }
+
+  .wrap {
+    max-width: 780px;
+    margin: 0 auto;
+  }
+
+  header.page {
+    margin-bottom: 3.25rem;
+  }
+
+  .eyebrow {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: var(--accent);
+    margin-bottom: 0.9rem;
+  }
+
+  h1 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 560;
+    font-size: clamp(2.1rem, 4.5vw, 2.65rem);
+    line-height: 1.08;
+    letter-spacing: -0.01em;
+    margin: 0 0 0.9rem;
+    text-wrap: balance;
+  }
+
+  .dek {
+    color: var(--muted);
+    max-width: 60ch;
+    font-size: 1.02rem;
+  }
+
+  .dek strong {
+    color: var(--ink);
+    font-weight: 600;
+  }
+
+  .legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.6rem;
+    margin-top: 1.6rem;
+  }
+
+  .chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.04em;
+    padding: 0.28rem 0.6rem;
+    border-radius: 3px;
+  }
+
+  .chip.have { background: var(--good-soft); color: var(--good); }
+  .chip.partial { background: var(--warn-soft); color: var(--warn); }
+  .chip.missing { background: var(--miss-soft); color: var(--miss); }
+
+  section.category {
+    margin-top: 3rem;
+  }
+
+  .cat-head {
+    display: flex;
+    align-items: baseline;
+    gap: 0.85rem;
+    border-bottom: 1px solid var(--hairline);
+    padding-bottom: 0.7rem;
+    margin-bottom: 1.1rem;
+  }
+
+  .cat-num {
+    font-family: "Fraunces", Georgia, serif;
+    font-size: 1.05rem;
+    color: var(--accent);
+    font-variant-numeric: tabular-nums;
+    min-width: 1.6rem;
+  }
+
+  .cat-head h2 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 500;
+    font-size: 1.28rem;
+    margin: 0;
+    letter-spacing: -0.005em;
+  }
+
+  .cat-note {
+    color: var(--muted);
+    font-size: 0.86rem;
+    margin: 0 0 1.2rem;
+    max-width: 62ch;
+  }
+
+  .feature {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    gap: 0.3rem 1rem;
+    padding: 1.05rem 0;
+    border-bottom: 1px solid var(--hairline);
+    align-items: start;
+  }
+
+  .feature:last-child { border-bottom: none; }
+
+  .f-name {
+    font-weight: 600;
+    font-size: 0.98rem;
+  }
+
+  .f-status {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.68rem;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    padding: 0.22rem 0.55rem;
+    border-radius: 3px;
+    white-space: nowrap;
+    height: fit-content;
+  }
+
+  .f-status.have { background: var(--good-soft); color: var(--good); }
+  .f-status.partial { background: var(--warn-soft); color: var(--warn); }
+  .f-status.missing { background: var(--miss-soft); color: var(--miss); }
+
+  .f-note {
+    grid-column: 1 / -1;
+    color: var(--muted);
+    font-size: 0.87rem;
+    margin-top: 0.15rem;
+    max-width: 66ch;
+  }
+
+  .f-note code {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.82em;
+    background: var(--accent-soft);
+    color: var(--accent);
+    padding: 0.08em 0.35em;
+    border-radius: 3px;
+  }
+
+  footer.page {
+    margin-top: 4rem;
+    padding-top: 1.5rem;
+    border-top: 1px solid var(--hairline);
+    color: var(--muted);
+    font-size: 0.82rem;
+    display: flex;
+    justify-content: space-between;
+    gap: 1rem;
+    flex-wrap: wrap;
+  }
+
+  footer.page a { color: var(--accent); }
+
+  @media (max-width: 560px) {
+    body { padding: 3rem 1.1rem 4rem; }
+    .feature { grid-template-columns: 1fr; }
+    .f-status { justify-self: start; }
+  }
+</style>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400..600&family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap">
+
+<div class="wrap">
+
+  <header class="page">
+    <div class="eyebrow">boboko / analytics · competitive survey</div>
+    <h1>What analytics elsewhere can do that boboko can't yet</h1>
+    <p class="dek">
+      A feature-by-feature pass across Shopify, WooCommerce Analytics, and PrestaShop's
+      stats modules — sourced, not recalled from memory — checked against what
+      <strong>Lunar's admin <code>Dashboard</code></strong> actually ships today and what
+      raw data already sits in <code>lunar_orders</code>/<code>lunar_carts</code> unused.
+      This is genuinely new territory for boboko — most rows below land on partial or
+      missing, and that's an honest read, not an undersell.
+    </p>
+    <div class="legend">
+      <span class="chip have">● have</span>
+      <span class="chip partial">◐ partial</span>
+      <span class="chip missing">○ missing</span>
+    </div>
+  </header>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">01</span>
+      <h2>Sales &amp; revenue dashboard</h2>
+    </div>
+    <p class="cat-note">What loads the moment staff open the admin panel — this is the one area where Lunar ships more than expected.</p>
+
+    <div class="feature">
+      <div class="f-name">Revenue / order-count stat cards with period-over-period trend</div>
+      <span class="f-status have">have</span>
+      <div class="f-note">Verified from source: <code>OrderStatsOverview</code> widget — today vs. yesterday, last 7 vs. prior 7, last 30 vs. prior 30 days, both order count and sub-total, with up/down trend icons. Registered by default on Lunar's <code>Dashboard</code> page, and boboko's panel (<code>3dealer/app/Providers/PanelServiceProvider.php</code>) registers the stock panel with no <code>pages()</code>/<code>Dashboard</code> override — this ships as-is.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Sales-over-time chart (revenue + order count, 12-month trend)</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>OrdersSalesChart</code> — ApexCharts area chart, monthly buckets over the trailing year, dual y-axis (order count / sub-total). Same "no override" reasoning as above applies to every widget on this page.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Average order value (AOV) trend, segmented by customer group</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>AverageOrderValueChart</code> — one series per <code>CustomerGroup</code> plus a synthetic guest series, monthly average of <code>sub_total</code> over the trailing year.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">New vs. returning customer split</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>NewVsReturningCustomersChart</code> reads <code>Order::new_customer</code>, a real boolean column set by <code>Lunar\Jobs\Orders\MarkAsNewCustomer</code> (true when no prior order existed for that customer at placement time) — not a cosmetic flag.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Live/latest-orders feed on the dashboard</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>LatestOrdersTable</code> — last 10 placed orders, 60s polling, reuses <code>OrderResource</code>'s own table columns.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Real-time dashboard vs. scheduled email reports</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">The dashboard widgets above poll every 60s (near-real-time, pull-based) — there is no scheduled/emailed report anywhere in Lunar or boboko-core. Industry pattern researched: real-time suits operational checks, scheduled digest suits weekly/monthly strategic review — boboko only has the first half.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">02</span>
+      <h2>Product &amp; catalog performance</h2>
+    </div>
+    <p class="cat-note">Which products are actually selling, and what's about to run out.</p>
+
+    <div class="feature">
+      <div class="f-name">Best-sellers / top-products report</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>PopularProductsTable</code> — groups <code>lunar_order_lines</code> by product identifier over the trailing 12 months, ranked by quantity sold, with revenue (<code>sub_total</code>) alongside. Physical products only (<code>whereType('physical')</code>).</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Per-product detail stats (views, conversion, revenue for one SKU)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">PrestaShop's <code>statsproduct</code> module was researched as the comparison point (per-product page-view + sales detail) — boboko has no page-view capture at all (see 04), so even the sales half of this can't be built without the traffic half.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Catalog-wide statistics (active/inactive counts, category breakdown)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">PrestaShop's <code>statscatalog</code> module researched as the reference. No equivalent surface in Lunar or boboko-core — would be a straightforward aggregate over <code>lunar_products</code>/<code>lunar_collections</code>, just not built.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Inventory / stock-turnover report</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note"><code>ProductVariant::$stock</code> is a plain point-in-time integer column — no stock-movement ledger or history table exists in <code>lunarphp/core</code> (grepped the models and migrations directories). Turnover reporting needs a time series of stock levels or receipts/sales deltas; today's schema only has "current stock," so there's nothing to compute turnover from yet, not just a missing report.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Low-stock / reorder alerting surfaced in a report</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">The Cart survey already noted <code>ProductIndexer</code>'s <code>in_stock</code> field exists for search/listing purposes — nothing aggregates it into a "low stock" admin view or report.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">03</span>
+      <h2>Customer analytics</h2>
+    </div>
+    <p class="cat-note">Value and behavior at the level of one shopper, or a group of them.</p>
+
+    <div class="feature">
+      <div class="f-name">Per-customer order count / average spend / lifetime spend</div>
+      <span class="f-status have">have</span>
+      <div class="f-note">Verified from source: <code>CustomerStatsOverviewWidget</code> on the customer view page — total orders, average spend, and total spend, computed live from <code>orders()->sum()/average()</code>. This is per-customer lookup, not an aggregate report across all customers.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Customer Lifetime Value (CLV) as a store-wide metric/segment</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">The per-customer total-spend figure above is the raw ingredient, but there's no store-wide CLV report, no ranking of customers by CLV, and no predictive/forward-looking CLV — WooCommerce Analytics' Customer Analytics extension (researched) computes this plus churn and RFM segments, none of which exist here.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Cohort retention analysis</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Researched as a WooCommerce/Metorik feature (retention rate by signup-month cohort). No cohort concept, table, or query exists anywhere in Lunar or boboko-core.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">04</span>
+      <h2>Behavioral &amp; funnel tracking</h2>
+    </div>
+    <p class="cat-note">What happens before an order exists — the storefront side neither repo instruments at all.</p>
+
+    <div class="feature">
+      <div class="f-name">Page-view / product-view event capture</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Grepped both repos for <code>gtag</code>/<code>dataLayer</code>/GA4/any client-side event tracker — zero hits. No storefront event of any kind is dispatched, captured, or stored anywhere.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Conversion funnel (view → add to cart → checkout → purchase)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Shopify's funnel report (researched) needs a session-scoped event stream across all four stages. boboko has only the last stage as durable data (a placed <code>Order</code>) — no view or add-to-cart events exist to build the earlier steps from, consistent with the Cart survey's finding that Lunar dispatches zero cart events.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Abandoned-cart aggregate value/rate reporting</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">Distinct from the Cart survey's per-cart admin lookup (<code>CartResource</code>, already shipped) — this is a rolled-up metric: total abandoned value this week, abandonment rate as a percentage of carts started. The underlying rows exist in <code>lunar_carts</code>/<code>lunar_cart_lines</code> (same query <code>CartResource</code>'s Abandoned tab already runs), but nothing aggregates them into a rate or a trend — it's list-only today.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Traffic-source / campaign attribution (UTM-based)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No UTM capture, no marketing/session table anywhere in either repo. Researched as the backbone of Shopify's/GA4's acquisition reporting — would need a session table capturing <code>utm_source</code>/<code>medium</code>/<code>campaign</code> at first touch, tied forward to the eventual order.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">05</span>
+      <h2>Tax, accounting &amp; export</h2>
+    </div>
+    <p class="cat-note">Getting numbers out of boboko and into someone else's books.</p>
+
+    <div class="feature">
+      <div class="f-name">Tax / VAT breakdown captured per order</div>
+      <span class="f-status have">have</span>
+      <div class="f-note">Verified from source: <code>lunar_orders</code> migration stores both <code>tax_breakdown</code> (JSON, per-rate detail) and <code>tax_total</code> as real columns on every placed order — this is genuine underlying data, not inferred.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Tax / VAT report for accounting (e.g. by tax zone, by period)</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">The per-order data above is complete enough to build this from, but nothing aggregates <code>tax_breakdown</code>/<code>tax_total</code> across orders into a filing-ready report by <code>TaxZone</code> or period — no such widget, page, or query exists in Lunar or boboko-core.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">CSV / accounting-software export of orders or sales data</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Grepped for <code>Exporter</code>/<code>ExportAction</code>/<code>Excel::</code> across <code>lunarphp/lunar</code> and boboko-core's <code>src</code> — no hits. Filament ships export actions as a first-party feature elsewhere in the ecosystem; nothing here wires one up for orders.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Sales by channel</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note"><code>Order::channel_id</code> is a real, always-populated foreign key (verified in the <code>lunar_orders</code> migration) — every order already knows its channel. No report groups by it; the dashboard's charts are all channel-blind.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">06</span>
+      <h2>Audit trail vs. analytics</h2>
+    </div>
+    <p class="cat-note">A distinction worth being explicit about, since it's easy to mistake one for the other.</p>
+
+    <div class="feature">
+      <div class="f-name">Activity log (Spatie activitylog) on core models</div>
+      <span class="f-status have">have</span>
+      <div class="f-note">Verified from source and <code>docs/lunar.md</code>'s Activity Logging section: <code>Lunar\Base\Traits\LogsActivity</code> covers Order, Cart, Product, Customer, and 15 other models, recording only dirty attributes per change under the <code>lunar</code> log name.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">This counts as analytics</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">It doesn't, and isn't listed as "have" anywhere above for that reason — activity log is a per-record change history for compliance/support ("who edited this order's shipping address"), not aggregate reporting ("how much revenue this month"). No row in this survey is satisfied by activity-log data.</div>
+    </div>
+  </section>
+
+  <footer class="page">
+    <span>Compiled 2026-08-28 — sources cited inline: <code>docs/lunar.md</code> §Filament Panel Integration and §Activity Logging plus direct reads of <code>vendor/lunarphp/lunar/src/Filament/Widgets/Dashboard</code>, <code>vendor/lunarphp/core</code> models/migrations, and <code>3dealer/app/Providers/PanelServiceProvider.php</code> are repo-verified; Shopify/WooCommerce/PrestaShop feature claims are from web research, not repo reads.</span>
+    <span>boboko-core / docs</span>
+  </footer>
+
+</div>

docs/scratch/checkout-feature-survey.html

@@ -0,0 +1,429 @@
+<title>Checkout Feature Survey</title>
+<style>
+  :root {
+    --paper: #FAFAF7;
+    --ink: #1C1C1A;
+    --muted: #6B6B63;
+    --accent: #2F5D50;
+    --accent-soft: #E4EDE9;
+    --good: #3F7A5C;
+    --good-soft: #E6F0EA;
+    --warn: #B8863B;
+    --warn-soft: #F5ECDC;
+    --miss: #A14B3B;
+    --miss-soft: #F5E5E0;
+    --hairline: #E4E2DB;
+    --card: #FFFFFF;
+  }
+
+  :root:not([data-theme="light"]) {
+    @media (prefers-color-scheme: dark) {
+      --paper: #17181A;
+      --ink: #EDEBE4;
+      --muted: #9B9A90;
+      --accent: #7FBFA8;
+      --accent-soft: #1E2C27;
+      --good: #6FBF97;
+      --good-soft: #1B2A22;
+      --warn: #D9A85C;
+      --warn-soft: #2C2418;
+      --miss: #D97C68;
+      --miss-soft: #2E1E1A;
+      --hairline: #2C2D2E;
+      --card: #1E1F21;
+    }
+  }
+
+  :root[data-theme="dark"] {
+    --paper: #17181A;
+    --ink: #EDEBE4;
+    --muted: #9B9A90;
+    --accent: #7FBFA8;
+    --accent-soft: #1E2C27;
+    --good: #6FBF97;
+    --good-soft: #1B2A22;
+    --warn: #D9A85C;
+    --warn-soft: #2C2418;
+    --miss: #D97C68;
+    --miss-soft: #2E1E1A;
+    --hairline: #2C2D2E;
+    --card: #1E1F21;
+  }
+
+  * { box-sizing: border-box; }
+
+  body {
+    background: var(--paper);
+    color: var(--ink);
+    font-family: "IBM Plex Sans", ui-sans-serif, system-ui, sans-serif;
+    font-size: 15.5px;
+    line-height: 1.55;
+    margin: 0;
+    padding: 4.5rem 1.5rem 6rem;
+  }
+
+  .wrap {
+    max-width: 780px;
+    margin: 0 auto;
+  }
+
+  header.page {
+    margin-bottom: 3.25rem;
+  }
+
+  .eyebrow {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: var(--accent);
+    margin-bottom: 0.9rem;
+  }
+
+  h1 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 560;
+    font-size: clamp(2.1rem, 4.5vw, 2.65rem);
+    line-height: 1.08;
+    letter-spacing: -0.01em;
+    margin: 0 0 0.9rem;
+    text-wrap: balance;
+  }
+
+  .dek {
+    color: var(--muted);
+    max-width: 60ch;
+    font-size: 1.02rem;
+  }
+
+  .dek strong {
+    color: var(--ink);
+    font-weight: 600;
+  }
+
+  .legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.6rem;
+    margin-top: 1.6rem;
+  }
+
+  .chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.04em;
+    padding: 0.28rem 0.6rem;
+    border-radius: 3px;
+  }
+
+  .chip.have { background: var(--good-soft); color: var(--good); }
+  .chip.partial { background: var(--warn-soft); color: var(--warn); }
+  .chip.missing { background: var(--miss-soft); color: var(--miss); }
+
+  section.category {
+    margin-top: 3rem;
+  }
+
+  .cat-head {
+    display: flex;
+    align-items: baseline;
+    gap: 0.85rem;
+    border-bottom: 1px solid var(--hairline);
+    padding-bottom: 0.7rem;
+    margin-bottom: 1.1rem;
+  }
+
+  .cat-num {
+    font-family: "Fraunces", Georgia, serif;
+    font-size: 1.05rem;
+    color: var(--accent);
+    font-variant-numeric: tabular-nums;
+    min-width: 1.6rem;
+  }
+
+  .cat-head h2 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 500;
+    font-size: 1.28rem;
+    margin: 0;
+    letter-spacing: -0.005em;
+  }
+
+  .cat-note {
+    color: var(--muted);
+    font-size: 0.86rem;
+    margin: 0 0 1.2rem;
+    max-width: 62ch;
+  }
+
+  .feature {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    gap: 0.3rem 1rem;
+    padding: 1.05rem 0;
+    border-bottom: 1px solid var(--hairline);
+    align-items: start;
+  }
+
+  .feature:last-child { border-bottom: none; }
+
+  .f-name {
+    font-weight: 600;
+    font-size: 0.98rem;
+  }
+
+  .f-status {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.68rem;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    padding: 0.22rem 0.55rem;
+    border-radius: 3px;
+    white-space: nowrap;
+    height: fit-content;
+  }
+
+  .f-status.have { background: var(--good-soft); color: var(--good); }
+  .f-status.partial { background: var(--warn-soft); color: var(--warn); }
+  .f-status.missing { background: var(--miss-soft); color: var(--miss); }
+
+  .f-note {
+    grid-column: 1 / -1;
+    color: var(--muted);
+    font-size: 0.87rem;
+    margin-top: 0.15rem;
+    max-width: 66ch;
+  }
+
+  .f-note code {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.82em;
+    background: var(--accent-soft);
+    color: var(--accent);
+    padding: 0.08em 0.35em;
+    border-radius: 3px;
+  }
+
+  footer.page {
+    margin-top: 4rem;
+    padding-top: 1.5rem;
+    border-top: 1px solid var(--hairline);
+    color: var(--muted);
+    font-size: 0.82rem;
+    display: flex;
+    justify-content: space-between;
+    gap: 1rem;
+    flex-wrap: wrap;
+  }
+
+  footer.page a { color: var(--accent); }
+
+  @media (max-width: 560px) {
+    body { padding: 3rem 1.1rem 4rem; }
+    .feature { grid-template-columns: 1fr; }
+    .f-status { justify-self: start; }
+  }
+</style>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400..600&family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap">
+
+<div class="wrap">
+
+  <header class="page">
+    <div class="eyebrow">boboko / checkout · competitive survey</div>
+    <h1>What checkout elsewhere can do that boboko can't yet</h1>
+    <p class="dek">
+      A feature-by-feature pass across Shopify, WooCommerce, and PrestaShop's checkout
+      layer — sourced, not recalled from memory — checked against what
+      <strong>Lunar's <code>Cart::createOrder()</code> / order-creation pipeline</strong>
+      actually supports today. Companion to the Cart survey: this starts where that one
+      left off — address and shipping-option capture through to a placed order. For
+      deciding what to design next, not a build order.
+    </p>
+    <div class="legend">
+      <span class="chip have">● have</span>
+      <span class="chip partial">◐ partial</span>
+      <span class="chip missing">○ missing</span>
+    </div>
+  </header>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">01</span>
+      <h2>Getting to checkout</h2>
+    </div>
+    <p class="cat-note">Who's allowed to check out, and in how many steps.</p>
+
+    <div class="feature">
+      <div class="f-name">Guest checkout (no account required)</div>
+      <span class="f-status have">have</span>
+      <div class="f-note">Structural, not bolted-on: <code>Order.user_id</code> and <code>customer_id</code> are both nullable, and <code>ValidateCartForOrderCreation</code> never checks for either — it only requires a billing address and, if shippable, a shipping address + option. A cart with no <code>user_id</code> creates an order fine.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">One-page vs. multi-step checkout</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Pure storefront-UI concern — Lunar has no opinion here, it just exposes <code>setShippingAddress()</code>/<code>setBillingAddress()</code>/<code>setShippingOption()</code> as independent calls that a UI can sequence however it likes. WooCommerce and PrestaShop both ship one-page as a plugin/theme layer, not core, so this isn't a Lunar gap so much as storefront work still to do.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Address autocomplete (type-ahead, from Google Places / Loqate)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Research: cuts address-entry keystrokes by 70%+ and is a proven abandonment-reduction tactic (Google Maps Platform, Loqate). No Lunar hook for it either way — it's a storefront form concern layered on top of the same <code>setShippingAddress()</code> call.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Express/accelerated checkout (Shop Pay, Apple Pay, Google Pay equivalents)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Research: Shopify reports Shop Pay can lift conversion up to 50% over guest checkout, mobile especially. Lunar's <code>Payments</code> facade is driver-based (<code>Payments::driver('card')</code>) so a wallet driver is architecturally pluggable, but none ships, and there's no one-tap "skip the address form" path since address capture still runs through the standard cart-address flow first.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Terms &amp; conditions acceptance at checkout</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note"><code>Order.meta</code> and <code>Cart.meta</code> are both free-form JSON columns carried straight through <code>FillOrderFromCart</code> (<code>'meta' => $cart->meta</code>) — technically able to record a timestamp/version of accepted terms today, but no dedicated field, checkbox validation, or admin display exists.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">02</span>
+      <h2>Order creation mechanics</h2>
+    </div>
+    <p class="cat-note">What actually happens inside <code>createOrder()</code>, verified from source.</p>
+
+    <div class="feature">
+      <div class="f-name">Duplicate-order prevention on repeat submits</div>
+      <span class="f-status have">have</span>
+      <div class="f-note">Two layers, both real: <code>Cart::draftOrder()</code> matches on <code>fingerprint()</code> + <code>total</code>, so re-running <code>createOrder()</code> on an unchanged cart reuses the same draft order instead of duplicating it (<code>CreateOrder::execute()</code>); once an order is placed, <code>hasCompletedOrders()</code> throws <code>DisallowMultipleCartOrdersException</code> unless <code>allowMultipleOrders</code> is explicitly passed.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Draft order created before payment, finalized after</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Order::isDraft()</code>/<code>isPlaced()</code> gate on <code>placed_at</code>; <code>orders.draft_status</code> config (default <code>awaiting-payment</code>) sets the initial status. The order exists — and can be re-run through the pipeline idempotently via the fingerprint match above — before a payment driver ever authorizes anything.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Order address, line, and shipping-line snapshotting from cart</div>
+      <span class="f-status have">have</span>
+      <div class="f-note">The whole <code>orders.pipelines.creation</code> chain does this explicitly — <code>FillOrderFromCart</code>, <code>CreateOrderLines</code>, <code>CreateOrderAddresses</code>, <code>CreateShippingLine</code>, <code>CleanUpOrderLines</code>, <code>MapDiscountBreakdown</code> — each copying cart state into immutable order rows rather than referencing the cart live.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Address validation before order creation</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ValidateCartForOrderCreation</code> requires <code>country_id</code>, <code>first_name</code>, <code>line_one</code>, <code>city</code>, <code>postcode</code> on billing always, and on shipping too unless the chosen <code>ShippingOption-&gt;collect</code> is true (in-store pickup skips a shipping address).</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Exchange rate and currency locked at order time</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>FillOrderFromCart</code> copies <code>currency_code</code> and <code>exchange_rate</code> from the cart's currency onto the order at creation — later currency-config changes don't retroactively alter placed orders.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">03</span>
+      <h2>Confirmation &amp; communication</h2>
+    </div>
+    <p class="cat-note">What tells the customer (and staff) an order happened.</p>
+
+    <div class="feature">
+      <div class="f-name">Order confirmation email on placement</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Surprising given how close it looks to shipping: every status in <code>config/lunar/orders.php</code> carries a <code>mailers</code> and <code>notifications</code> array, but grep across core turns up exactly one reader of that config (<code>Order::getStatusLabelAttribute()</code>, and it only reads <code>label</code>). Nothing in core ever dispatches a mailer or notification from a status change — those keys are unwired placeholders, not a working feature.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Order-status-changed events</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Same gap as Cart's event survey found — <code>src/Events/</code> in core contains only <code>PaymentAttemptEvent</code>. No <code>OrderCreated</code>, no <code>OrderStatusUpdated</code>. Confirmation email, staff Slack ping, or customer SMS on status change all have to be built from scratch on plain Eloquent model events (<code>Order::updated()</code>), same pattern as the cart-event gap.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Order tracking / status lookup for guests</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Research: PrestaShop's order-tracking extensions explicitly cover "non-logged-in customers track their orders." Lunar has the data (<code>Order.reference</code>, <code>status</code>, <code>OrderAddress.contact_email</code>) but no lookup mechanism — a guest with no account has no route back to their order without the confirmation email that also doesn't exist yet.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">New-customer detection on first order</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>CreateOrder::execute()</code> dispatches <code>MarkAsNewCustomer::dispatch($order->id)</code> as a queued job after every order creation — genuinely wired, unlike the mail/notification config above.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">04</span>
+      <h2>Abandoned checkout recovery</h2>
+    </div>
+    <p class="cat-note">Distinct from abandoned <em>cart</em> recovery (covered in the Cart survey) — this is someone who reached address/email capture and still left.</p>
+
+    <div class="feature">
+      <div class="f-name">Draft orders are queryable and staff-visible</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">The data exists — <code>Order::isDraft()</code> plus the address already captured on it — but per the Cart survey's finding, there's no Filament resource for <code>Cart</code> and (unverified here, likely the same gap) no dedicated "abandoned checkout" view distinguishing a draft order with a captured address from one that never got that far.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Automated recovery email (post-address-capture)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Research: Shopify's built-in template fires after a shopper enters details and leaves, with editable wait time and an optional discount. boboko has strictly better raw material for this than the cart-abandonment case — a draft order after address capture always has <code>OrderAddress.contact_email</code>, where an abandoned guest cart usually has none — but nothing sends on it.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Abandoned-checkout stage tracking (email captured vs. shipping selected vs. payment started)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No event dispatch anywhere in the checkout pipeline (see 03) means no timestamped record of which step a checkout got to — only the current state of the draft order, not its history.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">05</span>
+      <h2>Pricing, tax &amp; locale at checkout</h2>
+    </div>
+    <p class="cat-note">What the customer sees the moment money is on screen.</p>
+
+    <div class="feature">
+      <div class="f-name">Tax-inclusive vs. tax-exclusive price display</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>TaxZone.price_display</code> is a first-class enum (<code>tax_inclusive</code>/<code>tax_exclusive</code>), and <code>Price::priceExTax()</code>/<code>priceIncTax()</code> both exist on the model — more complete than PrestaShop, where dual-price display is a separately-sold addon module, not core.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Full tax breakdown shown at checkout (per-line, per-rate)</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Cart.taxBreakdown</code> and <code>OrderLine.tax_breakdown</code> are both populated structured objects (iterate <code>.amounts</code>), not just a lump-sum total — the data supports a itemized tax display, a storefront just has to render it.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Multi-currency checkout (pay in shopper's own currency)</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Currency.exchange_rate</code> plus <code>sync_prices</code> per non-default currency, and the rate is snapshotted onto the order at creation (see 02) — the same mechanics PrestaShop needs an addon for.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Multi-language checkout copy</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">Product/collection/attribute copy is fully translatable via <code>attribute_data</code> + <code>Language</code>, but checkout itself — form labels, validation errors, status labels — is storefront-owned Laravel localization, not something Lunar's order pipeline touches either way.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Click-and-collect / in-store pickup as a checkout option</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ShippingOption.collect</code> is a real boolean the validator checks directly — when true, <code>ValidateCartForOrderCreation</code> skips the shipping-address requirement entirely. Modeled at the same level as the <code>collection</code> driver in the Table Rate Shipping add-on.</div>
+    </div>
+  </section>
+
+  <footer class="page">
+    <span>Compiled 2026-08-28 — sources cited inline; <code>vendor/lunarphp/core/src</code> reads are marked by file/class name, Shopify/WooCommerce/PrestaShop claims are marked "Research."</span>
+    <span>boboko-core / docs</span>
+  </footer>
+
+</div>

docs/scratch/customer-accounts-feature-survey.html

@@ -0,0 +1,476 @@
+<title>Customer Accounts Feature Survey</title>
+<style>
+  :root {
+    --paper: #FAFAF7;
+    --ink: #1C1C1A;
+    --muted: #6B6B63;
+    --accent: #2F5D50;
+    --accent-soft: #E4EDE9;
+    --good: #3F7A5C;
+    --good-soft: #E6F0EA;
+    --warn: #B8863B;
+    --warn-soft: #F5ECDC;
+    --miss: #A14B3B;
+    --miss-soft: #F5E5E0;
+    --hairline: #E4E2DB;
+    --card: #FFFFFF;
+  }
+
+  :root:not([data-theme="light"]) {
+    @media (prefers-color-scheme: dark) {
+      --paper: #17181A;
+      --ink: #EDEBE4;
+      --muted: #9B9A90;
+      --accent: #7FBFA8;
+      --accent-soft: #1E2C27;
+      --good: #6FBF97;
+      --good-soft: #1B2A22;
+      --warn: #D9A85C;
+      --warn-soft: #2C2418;
+      --miss: #D97C68;
+      --miss-soft: #2E1E1A;
+      --hairline: #2C2D2E;
+      --card: #1E1F21;
+    }
+  }
+
+  :root[data-theme="dark"] {
+    --paper: #17181A;
+    --ink: #EDEBE4;
+    --muted: #9B9A90;
+    --accent: #7FBFA8;
+    --accent-soft: #1E2C27;
+    --good: #6FBF97;
+    --good-soft: #1B2A22;
+    --warn: #D9A85C;
+    --warn-soft: #2C2418;
+    --miss: #D97C68;
+    --miss-soft: #2E1E1A;
+    --hairline: #2C2D2E;
+    --card: #1E1F21;
+  }
+
+  * { box-sizing: border-box; }
+
+  body {
+    background: var(--paper);
+    color: var(--ink);
+    font-family: "IBM Plex Sans", ui-sans-serif, system-ui, sans-serif;
+    font-size: 15.5px;
+    line-height: 1.55;
+    margin: 0;
+    padding: 4.5rem 1.5rem 6rem;
+  }
+
+  .wrap {
+    max-width: 780px;
+    margin: 0 auto;
+  }
+
+  header.page {
+    margin-bottom: 3.25rem;
+  }
+
+  .eyebrow {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: var(--accent);
+    margin-bottom: 0.9rem;
+  }
+
+  h1 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 560;
+    font-size: clamp(2.1rem, 4.5vw, 2.65rem);
+    line-height: 1.08;
+    letter-spacing: -0.01em;
+    margin: 0 0 0.9rem;
+    text-wrap: balance;
+  }
+
+  .dek {
+    color: var(--muted);
+    max-width: 60ch;
+    font-size: 1.02rem;
+  }
+
+  .dek strong {
+    color: var(--ink);
+    font-weight: 600;
+  }
+
+  .legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.6rem;
+    margin-top: 1.6rem;
+  }
+
+  .chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.04em;
+    padding: 0.28rem 0.6rem;
+    border-radius: 3px;
+  }
+
+  .chip.have { background: var(--good-soft); color: var(--good); }
+  .chip.partial { background: var(--warn-soft); color: var(--warn); }
+  .chip.missing { background: var(--miss-soft); color: var(--miss); }
+
+  section.category {
+    margin-top: 3rem;
+  }
+
+  .cat-head {
+    display: flex;
+    align-items: baseline;
+    gap: 0.85rem;
+    border-bottom: 1px solid var(--hairline);
+    padding-bottom: 0.7rem;
+    margin-bottom: 1.1rem;
+  }
+
+  .cat-num {
+    font-family: "Fraunces", Georgia, serif;
+    font-size: 1.05rem;
+    color: var(--accent);
+    font-variant-numeric: tabular-nums;
+    min-width: 1.6rem;
+  }
+
+  .cat-head h2 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 500;
+    font-size: 1.28rem;
+    margin: 0;
+    letter-spacing: -0.005em;
+  }
+
+  .cat-note {
+    color: var(--muted);
+    font-size: 0.86rem;
+    margin: 0 0 1.2rem;
+    max-width: 62ch;
+  }
+
+  .feature {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    gap: 0.3rem 1rem;
+    padding: 1.05rem 0;
+    border-bottom: 1px solid var(--hairline);
+    align-items: start;
+  }
+
+  .feature:last-child { border-bottom: none; }
+
+  .f-name {
+    font-weight: 600;
+    font-size: 0.98rem;
+  }
+
+  .f-status {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.68rem;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    padding: 0.22rem 0.55rem;
+    border-radius: 3px;
+    white-space: nowrap;
+    height: fit-content;
+  }
+
+  .f-status.have { background: var(--good-soft); color: var(--good); }
+  .f-status.partial { background: var(--warn-soft); color: var(--warn); }
+  .f-status.missing { background: var(--miss-soft); color: var(--miss); }
+
+  .f-note {
+    grid-column: 1 / -1;
+    color: var(--muted);
+    font-size: 0.87rem;
+    margin-top: 0.15rem;
+    max-width: 66ch;
+  }
+
+  .f-note code {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.82em;
+    background: var(--accent-soft);
+    color: var(--accent);
+    padding: 0.08em 0.35em;
+    border-radius: 3px;
+  }
+
+  footer.page {
+    margin-top: 4rem;
+    padding-top: 1.5rem;
+    border-top: 1px solid var(--hairline);
+    color: var(--muted);
+    font-size: 0.82rem;
+    display: flex;
+    justify-content: space-between;
+    gap: 1rem;
+    flex-wrap: wrap;
+  }
+
+  footer.page a { color: var(--accent); }
+
+  @media (max-width: 560px) {
+    body { padding: 3rem 1.1rem 4rem; }
+    .feature { grid-template-columns: 1fr; }
+    .f-status { justify-self: start; }
+  }
+</style>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400..600&family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap">
+
+<div class="wrap">
+
+  <header class="page">
+    <div class="eyebrow">boboko / customer accounts · competitive survey</div>
+    <h1>What customer accounts elsewhere can do that boboko can't yet</h1>
+    <p class="dek">
+      A feature-by-feature pass across Shopify, WooCommerce, and PrestaShop's
+      account layer — sourced, not recalled from memory — checked against what
+      <strong>Lunar's <code>Customer</code>/<code>Address</code>/<code>CustomerGroup</code></strong>
+      models actually support today and what exists (or doesn't) in boboko-core
+      and 3dealer right now. For deciding what to design next, not a build order.
+    </p>
+    <div class="legend">
+      <span class="chip have">● have</span>
+      <span class="chip partial">◐ partial</span>
+      <span class="chip missing">○ missing</span>
+    </div>
+  </header>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">01</span>
+      <h2>Whether an account exists at all</h2>
+    </div>
+    <p class="cat-note">The storefront-facing account experience, as distinct from staff/admin auth in <code>Modules\Core\Auth</code>.</p>
+
+    <div class="feature">
+      <div class="f-name">Customer↔User linking (data model)</div>
+      <span class="f-status have">have</span>
+      <div class="f-note">Fully modeled by Lunar core — <code>Customer::users()</code> / <code>User::customers()</code> via <code>customer_user</code> pivot (<code>LunarUser</code> trait), plus <code>User::latestCustomer()</code>.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Customer record auto-created on signup</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Modules\Core\Customer\Listeners\CreateCustomerForUser</code> attaches a new <code>Customer</code> to every <code>User</code> on <code>UserCreated</code>, gated by <code>config('core.auto_create_customer_for_user')</code>.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Storefront login / registration UI</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">3dealer has no auth scaffolding at all — no Breeze/Fortify/Sanctum in <code>composer.json</code>, no <code>login</code>/<code>register</code> views, nothing in <code>routes/web.php</code>. Only <code>Modules\Core\Auth</code>'s Filament staff panel login exists.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Account/profile page (name, addresses, orders)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No <code>AccountController</code>, no <code>account</code>/<code>profile</code> route, no matching Blade views anywhere in 3dealer's <code>app/</code> or <code>resources/views</code> — confirmed by exhaustive grep.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Account nav link in header</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note"><code>resources/views/components/header.blade.php</code> has a cart icon and a search button but no account/login link at all — not even a dead one. The cart icon itself links to <code>/cart</code>, which also has no matching route, matching this codebase's known stubbed-UI pattern.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">02</span>
+      <h2>Order history &amp; tracking</h2>
+    </div>
+    <p class="cat-note">Letting a customer see and follow their own orders without contacting support.</p>
+
+    <div class="feature">
+      <div class="f-name">Order history data (per customer)</div>
+      <span class="f-status have">have</span>
+      <div class="f-note">Fully modeled — <code>Customer::orders()</code> and <code>User::orders()</code> both exist (<code>Lunar\Models\Order</code>), with <code>status</code>, line items, addresses, and transactions already relational.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Self-service order history / status page</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No storefront route or controller reads <code>Order</code> for a logged-in customer — the data exists, nothing surfaces it. Shopify's rebuilt (2026) customer-accounts UI and PrestaShop's order-detail tracking page are both native; WooCommerce ships this in My Account by default.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Shipment tracking numbers surfaced to customer</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No tracking-number field found on <code>Order</code>/<code>OrderLine</code>/shipping models in <code>vendor/lunarphp/core</code>; PrestaShop's tracking module patches this same gap with a third-party add-on, so it isn't a "native everywhere" bar either.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Reorder / buy-again from order history</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Needs an order-history UI to exist first (see above) plus a "re-add these lines to cart" action — Lunar's <code>Cart::add()</code> already supports the mechanics, nothing wires an <code>Order</code> line back into a new cart.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">03</span>
+      <h2>Saved addresses</h2>
+    </div>
+    <p class="cat-note">What a returning customer doesn't have to retype.</p>
+
+    <div class="feature">
+      <div class="f-name">Multiple saved addresses per customer</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Customer::addresses()</code> (<code>HasMany</code>) — <code>Lunar\Models\Address</code> has no cap on count.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Separate default shipping / billing address</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Address::shipping_default</code> and <code>billing_default</code> booleans; <code>AddressObserver</code> auto-unsets the previous default when a new one is flagged, so only one of each can be true at a time.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Self-service address book (add/edit/delete UI)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Only Filament's staff-facing <code>AddressRelationManager</code> (<code>src/Customer/RelationManagers/AddressRelationManager.php</code>) touches addresses today — that's an admin back-office view, not a storefront one. No customer-facing CRUD exists.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Address autocomplete / validation at entry</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Nothing in <code>lunarphp/core</code> or boboko-core wires a geocoding/validation service — this is a storefront-only concern layered on top of the plain <code>line_one</code>…<code>postcode</code> fields.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">04</span>
+      <h2>Login &amp; identity</h2>
+    </div>
+    <p class="cat-note">How a customer gets in, and how forgiving that path is.</p>
+
+    <div class="feature">
+      <div class="f-name">Email + password login</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No storefront auth guard/routes configured — see 01. <code>Modules\Core\Auth\Services\OtpService</code>/<code>UserOtpService</code> exist but are wired to staff/Filament login, not a customer-facing flow.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Passwordless / magic-link / OTP login</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note"><code>UserOtpService</code> and <code>UserOtpMail</code> already implement an OTP-by-email mechanism for the staff panel — the building block for a customer-facing passwordless flow exists, just not exposed to a storefront route. Shopify ships this as sign-in links (6-digit email code) by default in its 2026 customer accounts.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Social login (Google / Apple / Facebook)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No <code>laravel/socialite</code> in either <code>composer.json</code>. Shopify offers Google/Facebook sign-in and "Sign in with Shop" natively; this would be a from-scratch integration here.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Guest checkout → account conversion</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No storefront checkout flow exists yet in 3dealer to convert from — this depends on checkout being built before it's meaningful. Lunar's <code>Cart::user_id</code>/<code>customer_id</code> nullable-until-claimed design would support it once a checkout and account UI exist.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">05</span>
+      <h2>Payments &amp; saved methods</h2>
+    </div>
+    <p class="cat-note">Whether a returning customer can skip re-entering card details.</p>
+
+    <div class="feature">
+      <div class="f-name">Saved payment methods on account</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No tokenized-card storage model found in <code>lunarphp/core</code> or boboko-core's payment integration. Even Shopify gates this behind Enterprise; WooCommerce's version depends entirely on gateway-level tokenization (e.g. Stripe), not a core feature.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">06</span>
+      <h2>Wishlist &amp; saved items</h2>
+    </div>
+    <p class="cat-note">Keeping track of products outside the cart.</p>
+
+    <div class="feature">
+      <div class="f-name">Wishlist / saved-for-later products</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No <code>wishlist</code> model, table, or reference anywhere in <code>src/</code> or <code>vendor/lunarphp</code> — grep confirms zero hits. Shopify also has no native wishlist (third-party apps like Flits fill the gap); WooCommerce/PrestaShop are the same story via plugins, so this is a genuinely common gap, not a boboko-specific one.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">07</span>
+      <h2>Groups, pricing &amp; B2B</h2>
+    </div>
+    <p class="cat-note">Where boboko is already ahead of a typical single-tenant storefront — Lunar's <code>CustomerGroup</code> does real work here.</p>
+
+    <div class="feature">
+      <div class="f-name">Customer groups for differentiated pricing/visibility</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>CustomerGroup</code> model plus <code>HasCustomerGroups</code> trait — <code>Product::customerGroup()</code> scope and <code>Price</code>'s polymorphic customer-group awareness are both real, shipped behavior, not scaffolding.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Scheduled group availability (time-boxed access)</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>HasCustomerGroups::scheduleCustomerGroup()</code> / <code>unscheduleCustomerGroup()</code>, backed by <code>CanScheduleAvailability</code> — supports a <code>starts_at</code>/<code>ends_at</code> window per group, e.g. early access for wholesale.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Multi-user company / B2B accounts</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note"><code>Customer::users()->sync([...])</code> already supports attaching several <code>User</code>s to one <code>Customer</code> record — the data model allows a shared company account today, but nothing (invite flow, role/permission split between company users, storefront switch-account UI) is built on top of it. PrestaShop's "Multi-User Customer Account" add-on is the closest native comparison, and it's a paid third-party module there too.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Self-service customer-group selection at registration</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Groups exist and are assignable (<code>HasCustomerGroups::bootHasCustomerGroups()</code> auto-syncs default groups on creation), but nothing lets a customer request/select a group like "wholesale" at signup — that's currently a staff-only Filament action via <code>CustomerResourceExtension</code>.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">08</span>
+      <h2>Loyalty, retention &amp; data rights</h2>
+    </div>
+    <p class="cat-note">Longer-tail account features — noted for completeness, not depth (data rights specifically overlaps a separate Privacy survey).</p>
+
+    <div class="feature">
+      <div class="f-name">Loyalty / rewards points program</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No points/loyalty model anywhere in <code>lunarphp/core</code> or boboko-core — <code>Discount</code>'s <code>BuyXGetY</code> type is the closest primitive, but it's a promo mechanic, not an accruing balance. PrestaShop and WooCommerce both rely on third-party modules for this too (Knowband, Webkul, Yith).</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Self-service data export / account deletion</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">The only related tool is <code>boboko:anonymize</code> — a local-environment-only dev command that scrubs <code>users</code>/<code>lunar_customers</code> for testing, not a customer-facing GDPR flow. WooCommerce's closest native equivalent is also a paid add-on (Data Privacy Manager); flagged briefly here, full treatment belongs to the separate Privacy survey.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Subscription / recurring-order management</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No subscription model, billing-cycle field, or recurring-cart concept found in <code>lunarphp/core</code>. This is WooCommerce Subscriptions/Shopify-app territory on the platforms researched too — not a core-package feature anywhere.</div>
+    </div>
+  </section>
+
+  <footer class="page">
+    <span>Compiled 2026-08-28 — chips backed by web research (Shopify/WooCommerce/PrestaShop feature claims) are noted inline by platform name; all other claims are direct reads of <code>vendor/lunarphp/core/src</code>, boboko-core's <code>src/</code>, and 3dealer's <code>app/</code>/<code>resources/views</code>/<code>routes</code>.</span>
+    <span>boboko-core / docs</span>
+  </footer>
+
+</div>

docs/scratch/discounts-feature-survey.html

@@ -0,0 +1,527 @@
+<title>Discounts Feature Survey</title>
+<style>
+  @import url('https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400;9..144,500;9..144,600&family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap');
+
+  :root {
+    --paper: #FAFAF7;
+    --ink: #1C1C1A;
+    --muted: #6B6B63;
+    --accent: #2F5D50;
+    --accent-soft: #E4EDE9;
+    --good: #3F7A5C;
+    --good-soft: #E6F0EA;
+    --warn: #B8863B;
+    --warn-soft: #F5ECDC;
+    --miss: #A14B3B;
+    --miss-soft: #F5E5E0;
+    --hairline: #E4E2DB;
+    --card: #FFFFFF;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) {
+      --paper: #17181A;
+      --ink: #EDEBE4;
+      --muted: #9C9A90;
+      --accent: #6FAE97;
+      --accent-soft: #1E2D28;
+      --good: #6FAE97;
+      --good-soft: #1C2B22;
+      --warn: #D9AD6B;
+      --warn-soft: #2E2618;
+      --miss: #DE8A76;
+      --miss-soft: #2E1F1B;
+      --hairline: #302F2B;
+      --card: #1D1E20;
+    }
+  }
+
+  :root[data-theme="dark"] {
+    --paper: #17181A;
+    --ink: #EDEBE4;
+    --muted: #9C9A90;
+    --accent: #6FAE97;
+    --accent-soft: #1E2D28;
+    --good: #6FAE97;
+    --good-soft: #1C2B22;
+    --warn: #D9AD6B;
+    --warn-soft: #2E2618;
+    --miss: #DE8A76;
+    --miss-soft: #2E1F1B;
+    --hairline: #302F2B;
+    --card: #1D1E20;
+  }
+
+  * { box-sizing: border-box; }
+
+  body {
+    background: var(--paper);
+    color: var(--ink);
+    font-family: "IBM Plex Sans", ui-sans-serif, system-ui, sans-serif;
+    font-size: 16px;
+    line-height: 1.6;
+    margin: 0;
+    padding: 0;
+  }
+
+  .sheet {
+    max-width: 780px;
+    margin: 0 auto;
+    padding: 72px 24px 56px;
+  }
+
+  header.title-block {
+    margin-bottom: 56px;
+    padding-bottom: 32px;
+    border-bottom: 1px solid var(--hairline);
+  }
+
+  .eyebrow {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 12px;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--accent);
+    margin: 0 0 16px;
+  }
+
+  h1 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 500;
+    font-size: 2.15rem;
+    line-height: 1.18;
+    letter-spacing: -0.01em;
+    text-wrap: balance;
+    margin: 0 0 18px;
+    color: var(--ink);
+  }
+
+  .lede {
+    font-size: 1rem;
+    color: var(--muted);
+    max-width: 62ch;
+    margin: 0 0 20px;
+  }
+
+  .legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 10px;
+    margin-top: 8px;
+  }
+
+  .chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 11.5px;
+    letter-spacing: 0.03em;
+    padding: 3px 9px;
+    border-radius: 3px;
+    text-transform: uppercase;
+    white-space: nowrap;
+  }
+
+  .chip.have { background: var(--good-soft); color: var(--good); }
+  .chip.partial { background: var(--warn-soft); color: var(--warn); }
+  .chip.missing { background: var(--miss-soft); color: var(--miss); }
+
+  section.category {
+    margin-bottom: 48px;
+  }
+
+  .cat-head {
+    display: flex;
+    align-items: baseline;
+    gap: 14px;
+    margin-bottom: 6px;
+  }
+
+  .cat-num {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 500;
+    font-size: 1rem;
+    color: var(--accent);
+    min-width: 26px;
+  }
+
+  .cat-title {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 500;
+    font-size: 1.3rem;
+    letter-spacing: -0.005em;
+    margin: 0;
+  }
+
+  .cat-note {
+    font-size: 0.92rem;
+    color: var(--muted);
+    margin: 0 0 22px 40px;
+    max-width: 58ch;
+  }
+
+  .rows {
+    display: flex;
+    flex-direction: column;
+    border-top: 1px solid var(--hairline);
+    margin-left: 40px;
+  }
+
+  .row {
+    padding: 15px 0;
+    border-bottom: 1px solid var(--hairline);
+  }
+
+  .row-head {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: 16px;
+    margin-bottom: 6px;
+  }
+
+  .feat-name {
+    font-weight: 600;
+    font-size: 0.98rem;
+    color: var(--ink);
+  }
+
+  .ground {
+    font-size: 0.87rem;
+    color: var(--muted);
+    max-width: 66ch;
+  }
+
+  .ground code {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.83em;
+    background: var(--accent-soft);
+    color: var(--accent);
+    padding: 1px 5px;
+    border-radius: 3px;
+  }
+
+  .callout {
+    background: var(--card);
+    border: 1px solid var(--hairline);
+    border-left: 3px solid var(--accent);
+    border-radius: 4px;
+    padding: 16px 18px;
+    margin: 0 0 22px 40px;
+    font-size: 0.9rem;
+    color: var(--ink);
+  }
+
+  .callout strong {
+    color: var(--accent);
+  }
+
+  footer {
+    margin-top: 64px;
+    padding-top: 24px;
+    border-top: 1px solid var(--hairline);
+    font-size: 0.82rem;
+    color: var(--muted);
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+  }
+
+  footer p {
+    margin: 0 0 8px;
+    line-height: 1.6;
+  }
+
+  footer p:last-child { margin-bottom: 0; }
+
+  @media (max-width: 560px) {
+    .cat-note, .rows, .callout { margin-left: 0; }
+    .row-head { flex-direction: column; gap: 4px; }
+  }
+</style>
+
+<div class="sheet">
+
+  <header class="title-block">
+    <p class="eyebrow">boboko-core &middot; competitive spec sheet</p>
+    <h1>What discounts &amp; promotions elsewhere can do that boboko can&rsquo;t yet</h1>
+    <p class="lede">A feature-by-feature audit of Lunar's <code style="font-family:'IBM Plex Mono',monospace;background:var(--accent-soft);color:var(--accent);padding:1px 5px;border-radius:3px;font-size:0.85em;">Discount</code> engine against promotion tooling in Shopify, WooCommerce, and PrestaShop. Each row is graded against the underlying Lunar source, not the docs.</p>
+    <div class="legend">
+      <span class="chip have">have</span>
+      <span class="chip partial">partial</span>
+      <span class="chip missing">missing</span>
+    </div>
+  </header>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">01</span>
+      <h2 class="cat-title">Core discount mechanics</h2>
+    </div>
+    <p class="cat-note">The two shipped discount types and the machinery that decides whether they fire.</p>
+
+    <div class="rows">
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Percentage / fixed-amount off cart or line items</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground">Built in as <code>Lunar\DiscountTypes\AmountOff</code>. <code>applyPercentage()</code> and <code>applyFixedValue()</code> distribute the discount across eligible lines, tracking per-currency fixed values (<code>data.fixed_values.{code}</code>) so the amount is currency-aware, not a single converted number.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Buy X get Y (free or discounted)</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground">Built in as <code>Lunar\DiscountTypes\BuyXGetY</code>. Condition lines and reward lines are configured separately via <code>discountableConditions</code>/<code>discountableRewards</code>; <code>getRewardQuantity()</code> computes how many reward units a given condition quantity earns, with an optional <code>max_reward_qty</code> cap.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Coupon-code discounts</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground"><code>checkDiscountConditions()</code> compares <code>strtoupper($cart-&gt;coupon_code)</code> against <code>$discount-&gt;coupon</code>; <code>Discounts::validateCoupon()</code> exposes a standalone check. Coupon is cast via <code>CouponString</code> on the model.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Automatic (no-code) discounts</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground">A blank <code>coupon</code> column makes a discount apply to every eligible cart with no code entered &mdash; <code>DiscountManager::getDiscounts()</code> queries <code>whereNull('coupon')-&gt;orWhere('coupon', '')</code> when the cart carries no coupon code.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Minimum cart spend condition</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground"><code>checkDiscountConditions()</code> reads <code>data.min_prices.{currency}</code> and compares it against <code>$lines-&gt;sum('subTotal.value')</code>. Configurable per-currency in the admin form's "Minimum cart amount" fieldset &mdash; but only enforced by <code>AmountOff</code>, see row below.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Scoping to products, variants, collections, brands (incl. exclusions)</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground"><code>AmountOff::getEligibleLines()</code> filters/rejects cart lines against <code>discountableLimitations</code>/<code>discountableExclusions</code> plus <code>collections()</code>/<code>brands()</code> pivot rows typed <code>limitation</code> or <code>exclusion</code>. Configured through five separate Filament relation managers on the discount record.</p>
+      </div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">02</span>
+      <h2 class="cat-title">Timing, status, and usage limits</h2>
+    </div>
+    <p class="cat-note">Whether a discount is currently live, and how hard its usage caps are enforced.</p>
+
+    <div class="rows">
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Scheduled / expiring discount windows</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground"><code>Discount::getStatusAttribute()</code> derives <code>active</code>/<code>pending</code>/<code>expired</code>/<code>scheduled</code> from <code>starts_at</code>/<code>ends_at</code>; the Filament table badges this status column directly (green/gray/red/blue via <code>DiscountResource::getTableColumns()</code>).</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Global max-uses cap</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground"><code>Discount::scopeUsable()</code> filters query-side (<code>uses &lt; max_uses OR max_uses IS NULL</code>) before a discount is even fetched; <code>checkDiscountConditions()</code> re-checks it in <code>AmountOff</code>. <code>markAsUsed()</code> increments <code>uses</code> and attaches the user via <code>discount_user</code>.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Per-user max-uses cap</span>
+          <span class="chip partial">partial</span>
+        </div>
+        <p class="ground"><code>checkDiscountConditions()</code> calls <code>usesByUser()</code> only when <code>$cart-&gt;user</code> exists &mdash; a guest checkout cannot be capped per-customer since there's no <code>user_id</code> to key against, only <code>customer_id</code>. Wholesale/B2B carts often complete without a Laravel <code>User</code> attached, so the cap silently no-ops for them.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Usage/eligibility checks on Buy X Get Y</span>
+          <span class="chip missing">missing</span>
+        </div>
+        <p class="ground"><code>BuyXGetY::apply()</code> never calls <code>checkDiscountConditions()</code> &mdash; grep the method body, it's absent. A coupon-gated, min-spend-gated, or max-uses-capped BOGO discount ignores all three conditions; only the min-quantity/reward math runs. <code>AmountOff::apply()</code> calls it correctly by contrast.</p>
+      </div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">03</span>
+      <h2 class="cat-title">Multiple discounts, priority, and stacking</h2>
+    </div>
+    <p class="cat-note">What happens when more than one discount could legally apply to the same cart.</p>
+
+    <div class="callout">
+      <strong>The <code>stop</code> field is dead code.</strong> It's a real column, cast as boolean on the model, and it's a live toggle in the Filament admin form (<code>DiscountResource::getStopFormComponent()</code>) &mdash; but a repo-wide grep of both <code>lunarphp/core</code> and <code>lunarphp/lunar</code> for reads of <code>$discount-&gt;stop</code> outside the model and the form turns up nothing. <code>DiscountManager::apply()</code> is a plain unconditional <code>foreach</code> over every fetched discount; nothing ever breaks the loop. Staff can toggle a setting that has zero runtime effect.
+    </div>
+
+    <div class="rows">
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Priority ordering between discounts</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground"><code>DiscountManager::getDiscounts()</code> ends with <code>orderBy('priority', 'desc')-&gt;orderBy('id')</code>, and the admin form exposes low/medium/high (1/5/10) presets. This genuinely controls apply order.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Stopping further discounts once one applies ("exclusive" discount)</span>
+          <span class="chip missing">missing</span>
+        </div>
+        <p class="ground">See callout above &mdash; <code>stop</code> is unread at runtime. Every active, eligible discount is applied every time; there is no way to make one discount exclusive of the rest short of writing a custom <code>AbstractDiscountType</code> that inspects <code>$cart-&gt;discounts</code> itself.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Per-class combination rules (product vs. order vs. shipping discounts)</span>
+          <span class="chip missing">missing</span>
+        </div>
+        <p class="ground">Shopify models discounts as Product/Order/Shipping classes with an explicit "Combines with" toggle per pair. Lunar has no discount class concept at all &mdash; <code>AmountOff</code> and <code>BuyXGetY</code> are the only two types and neither declares a class or combination policy.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Customer-facing stacking transparency (which discounts combined, and why)</span>
+          <span class="chip partial">partial</span>
+        </div>
+        <p class="ground"><code>$cart-&gt;discountBreakdown</code> (a collection of <code>DiscountBreakdown</code> value objects, one per applied discount with its affected lines) gives a storefront the raw data to render "2 promotions applied," but no UI ships to render it &mdash; it's a data structure a storefront app must build its own component against.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">"Best deal wins" line-level conflict resolution</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground">Both <code>AmountOff::applyFixedValue()</code> and <code>applyPercentage()</code> explicitly skip a line when <code>$line-&gt;discountTotal-&gt;value &gt; $amount</code> &mdash; "if this line already has a greater discount value, don't add this one as they already have a better deal." This is a real per-line max-discount guard, just not a whole-cart exclusivity rule.</p>
+      </div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">04</span>
+      <h2 class="cat-title">Volume, tiers, and bundles</h2>
+    </div>
+    <p class="cat-note">"Buy more, save more" mechanics &mdash; and the separate pricing layer that actually implements some of them in Lunar.</p>
+
+    <div class="callout">
+      <strong>Tiered/volume pricing exists &mdash; but it's not a <code>Discount</code>.</strong> <code>PricingManager::get()</code> filters a purchasable's <code>Price</code> rows for <code>min_quantity &gt; 1 AND $this-&gt;qty &gt;= $price-&gt;min_quantity</code> and picks the cheapest matching price break. This is quantity-break pricing baked into the price table itself, resolved at <code>Pricing::for($variant)-&gt;qty($n)-&gt;get()</code> time &mdash; it never touches the <code>Discount</code> model, coupon system, or discount breakdown at all. A storefront gets the discounted unit price with no visible "discount applied" line.
+    </div>
+
+    <div class="rows">
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Per-SKU quantity price breaks</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground">Via the <code>Price</code> model's <code>min_quantity</code>/pricing pipeline described above, not <code>Discount</code>. Configured directly on product variant pricing in the admin, no separate promotion object needed.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Cart-wide tiered discount ("spend $100, save 10%; spend $200, save 20%")</span>
+          <span class="chip missing">missing</span>
+        </div>
+        <p class="ground"><code>AmountOff</code> takes one flat percentage or fixed value per discount record; there is no multi-tier threshold structure in <code>data</code>. Reaching this today means creating several separate <code>Discount</code> rows, each with its own <code>min_prices</code> floor, and hoping only the intended one wins (compounded by the <code>stop</code> gap in section 03).</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Bundle / kit discount (buy this set, get a fixed bundle price)</span>
+          <span class="chip missing">missing</span>
+        </div>
+        <p class="ground">No bundle or kit concept anywhere in <code>lunarphp/core</code>'s catalog or discount models. Shopify/WooCommerce/PrestaShop all support this via dedicated bundle apps or plugins layered on the same primitive Lunar lacks &mdash; a discount keyed to a co-purchased product set rather than any single line.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Free-gift-with-purchase (a distinct SKU added free, not a percentage off an existing line)</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground"><code>BuyXGetY</code>'s <code>automatically_add_rewards</code> flag drives <code>processAutomaticRewards()</code>, which inserts a brand-new <code>CartLine</code> for a randomly selected reward product and zeroes its price via <code>discountTotal</code>. <code>$cart-&gt;freeItems</code> tracks which purchasables were added this way.</p>
+      </div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">05</span>
+      <h2 class="cat-title">Customer targeting</h2>
+    </div>
+    <p class="cat-note">Lunar has two genuinely different mechanisms here that solve overlapping-looking problems &mdash; conflating them is the easiest mistake to make.</p>
+
+    <div class="callout">
+      <strong><code>CustomerGroup</code> pricing and <code>Discount</code> customer-group scoping are not the same feature.</strong> <code>Pricing::for($variant)-&gt;customerGroups($groups)-&gt;get()</code> resolves a <em>different base price</em> per customer group directly from the <code>Price</code> table (wholesale sees $8, retail sees $10 &mdash; two rows, no discount object, no coupon, nothing to "apply"). <code>Discount::customerGroups()</code> is a separate pivot (<code>customer_group_discount</code>, via the <code>HasCustomerGroups</code> trait) that scopes whether a <em>promotion</em> is visible/enabled to a group at all, with its own <code>starts_at</code>/<code>ends_at</code>/<code>enabled</code>/<code>visible</code> per-pivot-row scheduling. One is differential pricing; the other is promotion eligibility. Both exist and both work, but they're wired into completely separate code paths.
+    </div>
+
+    <div class="rows">
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Differential pricing per customer group (wholesale/VIP base price)</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground"><code>PricingManager::get()</code>: <code>$potentialGroupPrice</code> filters <code>Price</code> rows with a matching <code>customer_group_id</code> and picks the cheapest; falls back to <code>$basePrice</code> when no group price exists.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Restricting a discount/coupon to specific customer groups</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground"><code>DiscountManager::getDiscounts()</code> applies <code>-&gt;customerGroup($this-&gt;customerGroups)</code> via the shared <code>HasCustomerGroups</code> trait's <code>scopeCustomerGroup()</code>, configured on the discount's own "Availability" sub-page (<code>ManageDiscountAvailability</code>) alongside channel restriction.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Restricting a discount to specific named customers</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground"><code>Discount::customers()</code> pivot (<code>customer_discount</code>), checked in <code>checkDiscountConditions()</code>: if the discount has any tied customers, a cart without a matching <code>customer_id</code> fails eligibility outright. Managed via <code>CustomerLimitationRelationManager</code> in the admin.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">First-purchase / welcome discount</span>
+          <span class="chip missing">missing</span>
+        </div>
+        <p class="ground">Lunar does compute an order-level <code>new_customer</code> boolean (<code>Jobs\Orders\MarkAsNewCustomer</code>, <code>! $previousOrder</code>) &mdash; but it's a post-order reporting flag surfaced only in the Filament order table/dashboard chart. Nothing reads it during <code>ApplyDiscounts</code>; there's no "is this customer's first order" condition available to a <code>Discount</code> at checkout time.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Referral discounts (reward both referrer and referee)</span>
+          <span class="chip missing">missing</span>
+        </div>
+        <p class="ground">No referral concept anywhere in <code>lunarphp/core</code> or <code>lunarphp/lunar</code> &mdash; not a model, job, or config key. Common as a bolt-on in WooCommerce/Shopify via loyalty apps (e.g. WPLoyalty's referral-points module); would need to be built from scratch on top of <code>Discount::customers()</code> at best.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Loyalty points redeemable as a discount</span>
+          <span class="chip missing">missing</span>
+        </div>
+        <p class="ground">No points ledger, balance, or redemption model exists in Lunar core. A loyalty program (points-to-discount conversion, VIP-tier multipliers) is a third-party plugin layer in every researched competitor, not core commerce logic &mdash; same gap here, but Lunar offers no <code>AbstractDiscountType</code> hook obviously suited to "redeem N points" either, since discount eligibility has no notion of a spendable balance.</p>
+      </div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">06</span>
+      <h2 class="cat-title">Extensibility</h2>
+    </div>
+    <p class="cat-note">What it takes to reach a feature Lunar doesn't ship, without forking the package.</p>
+
+    <div class="rows">
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Registering a custom discount type</span>
+          <span class="chip have">have</span>
+        </div>
+        <p class="ground"><code>Discounts::addType(MyType::class)</code> appends to <code>DiscountManager::$types</code> (seeded with just <code>AmountOff::class, BuyXGetY::class</code>). A new type extends <code>AbstractDiscountType</code> and implements <code>apply(CartContract $cart)</code> &mdash; the same contract the two built-ins use, so it participates in the same unconditional-foreach loop from section 03.</p>
+      </div>
+      <div class="row">
+        <div class="row-head">
+          <span class="feat-name">Admin UI for a custom discount type</span>
+          <span class="chip partial">partial</span>
+        </div>
+        <p class="ground">Requires additionally implementing <code>Lunar\Admin\Base\LunarPanelDiscountInterface</code> (<code>lunarPanelSchema()</code>/<code>lunarPanelOnFill()</code>/<code>lunarPanelOnSave()</code>) for <code>DiscountResource::getDefaultForm()</code> to render a config section for it. The interface exists and is wired in, but there is no shipped example implementation to copy from beyond <code>AmountOff</code>/<code>BuyXGetY</code>, which are hard-coded into the form rather than using the interface themselves.</p>
+      </div>
+    </div>
+  </section>
+
+  <footer>
+    <p>Compiled 2026-08-28 &middot; boboko-core / docs</p>
+    <p>Section 01&ndash;03 and 05&ndash;06 rows are grounded directly in <code>vendor/lunarphp/core/src</code> and <code>vendor/lunarphp/lunar/src</code> source reads (file/method citations inline). Section 02's per-user cap and section 04's pricing-vs-discount distinction are likewise direct source reads. Comparative claims about Shopify, WooCommerce, and PrestaShop feature sets and terminology (discount classes, cart-rule compatibility, loyalty/referral plugins) are sourced from current public documentation and app-store listings via web research, not from reading those platforms' source.</p>
+  </footer>
+
+</div>

docs/scratch/orders-feature-survey.html

@@ -0,0 +1,450 @@
+<title>Order Feature Survey</title>
+<style>
+  :root {
+    --paper: #FAFAF7;
+    --ink: #1C1C1A;
+    --muted: #6B6B63;
+    --accent: #2F5D50;
+    --accent-soft: #E4EDE9;
+    --good: #3F7A5C;
+    --good-soft: #E6F0EA;
+    --warn: #B8863B;
+    --warn-soft: #F5ECDC;
+    --miss: #A14B3B;
+    --miss-soft: #F5E5E0;
+    --hairline: #E4E2DB;
+    --card: #FFFFFF;
+  }
+
+  :root:not([data-theme="light"]) {
+    @media (prefers-color-scheme: dark) {
+      --paper: #17181A;
+      --ink: #EDEBE4;
+      --muted: #9B9A90;
+      --accent: #7FBFA8;
+      --accent-soft: #1E2C27;
+      --good: #6FBF97;
+      --good-soft: #1B2A22;
+      --warn: #D9A85C;
+      --warn-soft: #2C2418;
+      --miss: #D97C68;
+      --miss-soft: #2E1E1A;
+      --hairline: #2C2D2E;
+      --card: #1E1F21;
+    }
+  }
+
+  :root[data-theme="dark"] {
+    --paper: #17181A;
+    --ink: #EDEBE4;
+    --muted: #9B9A90;
+    --accent: #7FBFA8;
+    --accent-soft: #1E2C27;
+    --good: #6FBF97;
+    --good-soft: #1B2A22;
+    --warn: #D9A85C;
+    --warn-soft: #2C2418;
+    --miss: #D97C68;
+    --miss-soft: #2E1E1A;
+    --hairline: #2C2D2E;
+    --card: #1E1F21;
+  }
+
+  * { box-sizing: border-box; }
+
+  body {
+    background: var(--paper);
+    color: var(--ink);
+    font-family: "IBM Plex Sans", ui-sans-serif, system-ui, sans-serif;
+    font-size: 15.5px;
+    line-height: 1.55;
+    margin: 0;
+    padding: 4.5rem 1.5rem 6rem;
+  }
+
+  .wrap {
+    max-width: 780px;
+    margin: 0 auto;
+  }
+
+  header.page {
+    margin-bottom: 3.25rem;
+  }
+
+  .eyebrow {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: var(--accent);
+    margin-bottom: 0.9rem;
+  }
+
+  h1 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 560;
+    font-size: clamp(2.1rem, 4.5vw, 2.65rem);
+    line-height: 1.08;
+    letter-spacing: -0.01em;
+    margin: 0 0 0.9rem;
+    text-wrap: balance;
+  }
+
+  .dek {
+    color: var(--muted);
+    max-width: 60ch;
+    font-size: 1.02rem;
+  }
+
+  .dek strong {
+    color: var(--ink);
+    font-weight: 600;
+  }
+
+  .legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.6rem;
+    margin-top: 1.6rem;
+  }
+
+  .chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.04em;
+    padding: 0.28rem 0.6rem;
+    border-radius: 3px;
+  }
+
+  .chip.have { background: var(--good-soft); color: var(--good); }
+  .chip.partial { background: var(--warn-soft); color: var(--warn); }
+  .chip.missing { background: var(--miss-soft); color: var(--miss); }
+
+  section.category {
+    margin-top: 3rem;
+  }
+
+  .cat-head {
+    display: flex;
+    align-items: baseline;
+    gap: 0.85rem;
+    border-bottom: 1px solid var(--hairline);
+    padding-bottom: 0.7rem;
+    margin-bottom: 1.1rem;
+  }
+
+  .cat-num {
+    font-family: "Fraunces", Georgia, serif;
+    font-size: 1.05rem;
+    color: var(--accent);
+    font-variant-numeric: tabular-nums;
+    min-width: 1.6rem;
+  }
+
+  .cat-head h2 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 500;
+    font-size: 1.28rem;
+    margin: 0;
+    letter-spacing: -0.005em;
+  }
+
+  .cat-note {
+    color: var(--muted);
+    font-size: 0.86rem;
+    margin: 0 0 1.2rem;
+    max-width: 62ch;
+  }
+
+  .feature {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    gap: 0.3rem 1rem;
+    padding: 1.05rem 0;
+    border-bottom: 1px solid var(--hairline);
+    align-items: start;
+  }
+
+  .feature:last-child { border-bottom: none; }
+
+  .f-name {
+    font-weight: 600;
+    font-size: 0.98rem;
+  }
+
+  .f-status {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.68rem;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    padding: 0.22rem 0.55rem;
+    border-radius: 3px;
+    white-space: nowrap;
+    height: fit-content;
+  }
+
+  .f-status.have { background: var(--good-soft); color: var(--good); }
+  .f-status.partial { background: var(--warn-soft); color: var(--warn); }
+  .f-status.missing { background: var(--miss-soft); color: var(--miss); }
+
+  .f-note {
+    grid-column: 1 / -1;
+    color: var(--muted);
+    font-size: 0.87rem;
+    margin-top: 0.15rem;
+    max-width: 66ch;
+  }
+
+  .f-note code {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.82em;
+    background: var(--accent-soft);
+    color: var(--accent);
+    padding: 0.08em 0.35em;
+    border-radius: 3px;
+  }
+
+  footer.page {
+    margin-top: 4rem;
+    padding-top: 1.5rem;
+    border-top: 1px solid var(--hairline);
+    color: var(--muted);
+    font-size: 0.82rem;
+    display: flex;
+    justify-content: space-between;
+    gap: 1rem;
+    flex-wrap: wrap;
+  }
+
+  footer.page a { color: var(--accent); }
+
+  @media (max-width: 560px) {
+    body { padding: 3rem 1.1rem 4rem; }
+    .feature { grid-template-columns: 1fr; }
+    .f-status { justify-self: start; }
+  }
+</style>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400..600&family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap">
+
+<div class="wrap">
+
+  <header class="page">
+    <div class="eyebrow">boboko / order · competitive survey</div>
+    <h1>What order management elsewhere can do that boboko can't yet</h1>
+    <p class="dek">
+      Where the Checkout survey stopped — the instant <code>Order</code> exists — this
+      one starts. A feature-by-feature pass across Shopify, WooCommerce, PrestaShop, and
+      (briefly) Magento's post-placement order layer — sourced, not recalled from memory —
+      checked against what <strong>Lunar's <code>Order</code> model and the
+      already-shipped Filament <code>ManageOrder</code> page</strong> actually support
+      today. For deciding what the new <code>Order</code> module needs to own, not a
+      build order.
+    </p>
+    <div class="legend">
+      <span class="chip have">● have</span>
+      <span class="chip partial">◐ partial</span>
+      <span class="chip missing">○ missing</span>
+    </div>
+  </header>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">01</span>
+      <h2>Status model</h2>
+    </div>
+    <p class="cat-note">One field, or several axes — and who's allowed to move it.</p>
+
+    <div class="feature">
+      <div class="f-name">Payment status independent of a single overall status</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">The data exists — <code>ManageOrder::paymentStatus()</code> derives a real value from <code>transactions()</code>/<code>captureTotal()</code>/<code>refundTotal()</code>/<code>intentTotal()</code> — but it's a computed display value on the admin page, not a stored column or something the rest of the system (mailers, automations) can key off. Shopify and Magento both make payment status a first-class, independently-queryable dimension; here it's derived on the fly, once, in one Filament page.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Fulfillment status independent of overall status</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No equivalent of <code>paymentStatus()</code> exists for shipment/fulfillment state — <code>Order</code> has no <code>shipments()</code> relation of its own at all; it's added dynamically by <code>Modules\Core\Shipping\Providers\ShippingServiceProvider::resolveRelationUsing()</code>, outside Order's own boundary (see docs/checkout.md, "Where Order would likely absorb work"). Every platform researched (Shopify, Woo, PrestaShop, Magento) treats "has this shipped" as derivable from child records, not a manually-set field — Lunar has the child records (<code>Shipment</code>) but no derived status method reading them.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Staff-editable order status with a picker/action</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ManageOrder</code> ships a working <code>UpdateStatusAction</code> out of the box, backed by <code>config('lunar.orders.statuses')</code> — a flat, merchant-configured list, each entry carrying a <code>label</code>/<code>color</code>/<code>favourite</code> flag. Closer to WooCommerce's single linear field than Shopify's multi-axis split.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Status rows carry behavior (auto-send email, generate invoice, restock)</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">Each status entry in <code>config('lunar.orders.statuses')</code> already declares <code>mailers</code> and <code>notifications</code> arrays — the PrestaShop-style shape is there in config — but per the Checkout survey's finding, nothing in core actually reads and dispatches from those keys on a transition. The data model for "status carries behavior" exists; the behavior doesn't.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Order-status-changed event other code can react to</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Same gap the Checkout survey flagged for order creation: no <code>OrderStatusUpdated</code>/equivalent exists anywhere in core. <code>UpdateStatusAction</code> just writes the column. Anything wanting to react to a status change — a confirmation email, a webhook, re-deriving payment/fulfillment status — has to hook the raw Eloquent <code>Order::updated()</code> event and diff <code>status</code> itself.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">02</span>
+      <h2>Fulfillment &amp; shipment tracking</h2>
+    </div>
+    <p class="cat-note">Turning a placed order into a package that moves.</p>
+
+    <div class="feature">
+      <div class="f-name">Shipment as its own record, separate from the order</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Modules\Core\Shipping\Models\Shipment</code> (carrier, tracking reference, label-printed timestamp, manifest reference) already exists and belongs to <code>Order</code>. Built this session, ahead of most gaps in this survey — the record shape is closer to Magento's per-shipment entity than Woo's "no shipment entity at all."</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Multiple shipments per order (partial/split fulfillment)</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note"><code>Shipment</code> has no <code>quantity</code>-per-line or <code>order_line_id</code> concept — it's one shipment record per carrier voucher, with a <code>parent_reference</code> for ACS's own multipart-voucher case (one physical order split into multiple packages by the carrier), not a per-line-item fulfillment split decided by staff. Closer to "multiple packages for one shipment" than Magento's true per-line partial-shipment model.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Create-shipment action from the order admin screen</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Modules\Core\Shipping\Extensions\OrderViewExtension</code> adds a working "Create Shipment" header action to <code>ManageOrder</code>, resolving a <code>CarrierFulfillmentInterface</code> by the order's chosen shipping method and calling <code>createShipment()</code> — genuinely wired, not a stub. Currently lives under <code>Shipping</code>, flagged in docs/checkout.md as conceptually an <code>Order</code> concern.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Tracking number + carrier surfaced on the order itself</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Shipment.tracking_reference</code>/<code>carrier</code> exist and are populated by <code>createShipment()</code>; <code>PollShipmentTrackingJob</code> (scheduled every 30 minutes) keeps <code>ShipmentInfo</code> checkpoints current via <code>CarrierFulfillmentInterface::trackShipment()</code>. Genuinely ahead of PrestaShop's thin <code>order_carrier.tracking_number</code> field — this has a real checkpoint history, not just one string.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">"Shipped"/"delivered" status auto-derived from tracking</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">The tracking checkpoints exist (<code>ShipmentInfo</code>, <code>TrackingStatus</code> enum including <code>Delivered</code>) but nothing writes them back onto <code>Order.status</code> — a delivered shipment doesn't move the order out of whatever status it was already in. Every platform researched treats "delivered" as a status a customer/staff can see on the order, not something buried one relation away.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Shipping/delivery notification emails (shipped, out-for-delivery, delivered)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Research: Shopify fires four separate templated notifications across this window alone (shipping confirmation, out-for-delivery, delivered, plus edited-order). None of the pieces exist here — no order-status-changed event (01) to trigger from, and no mailer wired to <code>PollShipmentTrackingJob</code>'s own status updates either.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">03</span>
+      <h2>Payments: capture, refund, cancellation</h2>
+    </div>
+    <p class="cat-note">Money moving back out, and orders that never should have been placed.</p>
+
+    <div class="feature">
+      <div class="f-name">Refund action from the order screen, amount-scoped</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ManageOrder</code>'s <code>refund</code> action already exists — picks a transaction, an amount (validated against <code>availableToRefund()</code>), and notes, then calls the driver's own <code>Transaction::refund()</code>. This is genuinely native, matching Woo/Magento's line-item-adjacent (if not line-item-exact) refund UX.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Capture action for auth-then-capture payment flows</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ManageOrder</code>'s <code>capture</code> action + <code>requiresCapture()</code>/<code>canBeRefunded()</code> guard methods already exist, delegating to <code>Transaction::capture()</code> — this is the Stripe "authorize now, capture later" flow's admin-side half, already built ahead of most gaps here.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Refund tied to specific line items (not just a dollar amount)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">The refund action takes a transaction + amount, with no line-item selection or restock decision — WooCommerce and Magento both make "which items, how many, restock or not" the primary refund UI; here it's one number against one transaction, closer to a manual adjustment than a structured partial return.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Order cancellation as a distinct action (vs. just changing status)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No dedicated "cancel" action exists on <code>ManageOrder</code> — a cancellation today would just be picking a "cancelled"-labeled entry from the generic status dropdown (01), with no automatic refund trigger, no stock-release logic, and no distinction from any other manual status edit.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Refund/capture reflected back into an order-level payment status</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">Same gap as 01's payment-status finding — <code>paymentStatus()</code> recomputes correctly from transactions when the admin page loads, but a refund doesn't push the order into a <code>refunded</code>/<code>partially-refunded</code> overall status the way Shopify's <code>displayFinancialStatus</code> does automatically.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">04</span>
+      <h2>Returns (RMA)</h2>
+    </div>
+    <p class="cat-note">The one area every researched platform treats as optional, not core.</p>
+
+    <div class="feature">
+      <div class="f-name">Return-merchandise-authorization flow (customer requests, staff approves)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No <code>Return</code>/RMA model, status set, or request flow exists anywhere in this codebase. Consistent with the research: Shopify is the only platform of the four with this genuinely native; PrestaShop ships it off-by-default; Magento gates it behind the paid Adobe Commerce tier; WooCommerce lacks it entirely. Safe to treat as a real gap, not an urgent one.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Return shipping label generation</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Depends entirely on the RMA flow above existing first — <code>CarrierFulfillmentInterface</code> already has the label-printing primitive (<code>printLabel()</code>) a return label would reuse, so the carrier-side plumbing isn't the blocker, the RMA request/approval model is.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">05</span>
+      <h2>Order editing</h2>
+    </div>
+    <p class="cat-note">Changing a placed order — and where every platform draws the line.</p>
+
+    <div class="feature">
+      <div class="f-name">Editing guardrails keyed to fulfillment state</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No line-item add/remove exists on a placed order at all today (unlike Shopify/Woo/PrestaShop, which all allow it up to some fulfillment-keyed cutoff, then force a return instead) — so there's no guardrail to speak of yet because there's no editing to guard. Whatever gets built here should key the cutoff to <code>Shipment</code> existing, per the pattern all four researched platforms converge on.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Editable shipping/billing address after placement</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note"><code>OrderAddress</code> rows are snapshotted at creation (see Checkout survey, 02) and nothing in <code>ManageOrder</code> exposes editing them afterward — every platform researched treats address edits as lower-risk than line-item edits and allows them more freely; this codebase currently allows neither.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Tag editing on a placed order</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ManageOrder</code>'s <code>edit_tags</code> action already works — the one piece of native post-placement editing that exists today, via <code>HasTags</code> on the <code>Order</code> model.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">06</span>
+      <h2>Notes &amp; audit trail</h2>
+    </div>
+    <p class="cat-note">The one thing every researched platform treats as non-negotiable.</p>
+
+    <div class="feature">
+      <div class="f-name">Append-only change history (who changed what, when)</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Order</code> already uses Spatie's <code>LogsActivity</code> trait — every save is recorded with a diff, same underlying mechanism already relied on elsewhere in this codebase (staff activity log, translation history). Structurally equivalent to PrestaShop's <code>order_history</code> table, just via a different package.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Internal staff notes, separate from system-generated log entries</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">The activity log above captures field changes automatically, but there's no free-text "leave a note for the next person" field — every platform researched has this as a distinct feed from the automatic history (Woo's Order Notes, Shopify's Timeline comments, Magento's Comments History), usually with a private-vs-customer-visible toggle. Nothing here yet.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Customer-visible note-to-customer, sent as a message</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Depends on both the internal-notes feature above and a working mailer (01/02) — genuinely blocked on more foundational gaps, not just unbuilt on its own.</div>
+    </div>
+  </section>
+
+  <footer class="page">
+    <span>Compiled 2026-09-01 — sources cited inline; <code>vendor/lunarphp/lunar</code> and this codebase's own <code>src/</code> reads are marked by file/class name, Shopify/WooCommerce/PrestaShop/Magento claims are marked "Research."</span>
+    <span>boboko-core / docs</span>
+  </footer>
+
+</div>

docs/scratch/payments-feature-survey.html

@@ -0,0 +1,448 @@
+<title>Payments Feature Survey</title>
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400;9..144,500;9..144,600;9..144,700&family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap" rel="stylesheet" />
+
+<style>
+  :root {
+    --paper: #FAFAF7;
+    --ink: #1C1C1A;
+    --muted: #6B6B63;
+    --accent: #2F5D50;
+    --accent-soft: #E4EDE9;
+    --good: #3F7A5C;
+    --good-soft: #E6F0EA;
+    --warn: #B8863B;
+    --warn-soft: #F5ECDC;
+    --miss: #A14B3B;
+    --miss-soft: #F5E5E0;
+    --hairline: #E4E2DB;
+    --card: #FFFFFF;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) {
+      --paper: #17181A;
+      --ink: #EDEBE4;
+      --muted: #9B9A91;
+      --accent: #6FAE97;
+      --accent-soft: #1E2C27;
+      --good: #6FAE97;
+      --good-soft: #1C2B22;
+      --warn: #D8A85C;
+      --warn-soft: #2E2718;
+      --miss: #D97F68;
+      --miss-soft: #2E1F1A;
+      --hairline: #2C2D2E;
+      --card: #1D1F20;
+    }
+  }
+
+  :root[data-theme="dark"] {
+    --paper: #17181A;
+    --ink: #EDEBE4;
+    --muted: #9B9A91;
+    --accent: #6FAE97;
+    --accent-soft: #1E2C27;
+    --good: #6FAE97;
+    --good-soft: #1C2B22;
+    --warn: #D8A85C;
+    --warn-soft: #2E2718;
+    --miss: #D97F68;
+    --miss-soft: #2E1F1A;
+    --hairline: #2C2D2E;
+    --card: #1D1F20;
+  }
+
+  * { box-sizing: border-box; }
+
+  body {
+    background: var(--paper);
+    color: var(--ink);
+    font-family: "IBM Plex Sans", ui-sans-serif, system-ui, sans-serif;
+    font-size: 16px;
+    line-height: 1.55;
+    -webkit-font-smoothing: antialiased;
+  }
+
+  .page {
+    max-width: 780px;
+    margin: 0 auto;
+    padding: 72px 24px 96px;
+  }
+
+  header.masthead {
+    margin-bottom: 56px;
+  }
+
+  .eyebrow {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 12.5px;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--accent);
+    margin: 0 0 18px;
+  }
+
+  h1 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 600;
+    font-size: clamp(30px, 5vw, 40px);
+    line-height: 1.18;
+    letter-spacing: -0.01em;
+    margin: 0 0 18px;
+    text-wrap: balance;
+    max-width: 22ch;
+  }
+
+  .dek {
+    color: var(--muted);
+    font-size: 16.5px;
+    max-width: 62ch;
+    margin: 0 0 28px;
+  }
+
+  .summary-strip {
+    display: flex;
+    gap: 10px;
+    flex-wrap: wrap;
+    padding-top: 22px;
+    border-top: 1px solid var(--hairline);
+  }
+
+  .summary-pill {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 12.5px;
+    padding: 6px 12px;
+    border-radius: 999px;
+    display: flex;
+    align-items: baseline;
+    gap: 6px;
+  }
+  .summary-pill b { font-size: 13.5px; }
+  .summary-pill.have { background: var(--good-soft); color: var(--good); }
+  .summary-pill.partial { background: var(--warn-soft); color: var(--warn); }
+  .summary-pill.missing { background: var(--miss-soft); color: var(--miss); }
+
+  section.category {
+    margin-bottom: 52px;
+  }
+
+  .category-head {
+    display: flex;
+    gap: 16px;
+    align-items: baseline;
+    margin-bottom: 6px;
+  }
+
+  .numeral {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 500;
+    font-size: 15px;
+    color: var(--accent);
+    font-variant-numeric: tabular-nums;
+    flex: none;
+    width: 2ch;
+  }
+
+  h2 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 600;
+    font-size: 22px;
+    margin: 0;
+    letter-spacing: -0.01em;
+  }
+
+  .category-note {
+    color: var(--muted);
+    font-size: 14.5px;
+    margin: 0 0 22px 34px;
+    max-width: 58ch;
+  }
+
+  .rows {
+    margin-left: 34px;
+    border-top: 1px solid var(--hairline);
+  }
+
+  .row {
+    padding: 16px 0;
+    border-bottom: 1px solid var(--hairline);
+  }
+
+  .row-head {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    gap: 16px;
+  }
+
+  .feature-name {
+    font-weight: 500;
+    font-size: 15.5px;
+  }
+
+  .chip {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 11.5px;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    padding: 3px 10px;
+    border-radius: 999px;
+    flex: none;
+    white-space: nowrap;
+  }
+  .chip.have { background: var(--good-soft); color: var(--good); }
+  .chip.partial { background: var(--warn-soft); color: var(--warn); }
+  .chip.missing { background: var(--miss-soft); color: var(--miss); }
+
+  .grounding {
+    color: var(--muted);
+    font-size: 13.5px;
+    margin-top: 6px;
+    line-height: 1.5;
+    max-width: 64ch;
+  }
+
+  code {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 12.5px;
+    background: var(--accent-soft);
+    color: var(--accent);
+    padding: 1px 5px;
+    border-radius: 4px;
+  }
+
+  footer {
+    margin-top: 64px;
+    padding-top: 24px;
+    border-top: 1px solid var(--hairline);
+    color: var(--muted);
+    font-size: 13px;
+  }
+
+  footer .compiled {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 12px;
+    margin-bottom: 10px;
+  }
+
+  footer p {
+    margin: 0 0 8px;
+    max-width: 62ch;
+  }
+
+  footer p:last-child { margin-bottom: 0; }
+
+  @media (max-width: 560px) {
+    .category-note, .rows { margin-left: 0; }
+    .category-head { gap: 10px; }
+  }
+</style>
+
+<div class="page">
+
+  <header class="masthead">
+    <p class="eyebrow">boboko-core &middot; competitive gap survey &middot; 03</p>
+    <h1>What payments elsewhere can do that boboko can't yet</h1>
+    <p class="dek">
+      Lunar's payment layer (<code>Lunar\Facades\Payments</code>, <code>Transaction</code>, the offline
+      driver) is wired for a single "pay on delivery / bank transfer" flow. Everything downstream of
+      that — cards, wallets, saved methods, self-service refunds, retries — is either scaffolded in
+      Lunar core and unused here, or absent from the stack entirely. This is a research survey, not a
+      build plan.
+    </p>
+    <div class="summary-strip">
+      <span class="summary-pill have"><b>4</b> have</span>
+      <span class="summary-pill partial"><b>9</b> partial</span>
+      <span class="summary-pill missing"><b>14</b> missing</span>
+    </div>
+  </header>
+
+  <section class="category">
+    <div class="category-head">
+      <span class="numeral">01</span>
+      <h2>Payment method breadth</h2>
+    </div>
+    <p class="category-note">boboko currently ships one payment type: cash-in-hand via the offline driver. Every card/wallet/BNPL path below is theoretically pluggable but has zero live implementation.</p>
+    <div class="rows">
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Offline / pay-on-account</span><span class="chip have">have</span></div>
+        <div class="grounding">The only configured type in <code>config/lunar/payments.php</code> (3dealer's published copy): <code>'cash-in-hand' => ['driver' => 'offline', 'authorized' => 'payment-offline']</code>, backed by <code>Lunar\PaymentTypes\OfflinePayment</code>.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Card payments (Stripe/other gateway)</span><span class="chip missing">missing</span></div>
+        <div class="grounding"><code>lunarphp/stripe</code> is not present in either <code>boboko-core/vendor/lunarphp</code> or <code>3dealer/vendor/lunarphp</code>, and not listed in either <code>composer.json</code>. <code>docs/lunar.md</code>'s Stripe section documents Lunar's general capability, not something wired into this project.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Digital wallets (Apple Pay, Google Pay, Shop Pay)</span><span class="chip missing">missing</span></div>
+        <div class="grounding">Depends entirely on a card gateway (Stripe Payment Request Button or similar) that isn't installed. Shopify bundles Apple Pay, Google Pay, and Shop Pay as one-tap checkout by default.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Buy-now-pay-later (Klarna, Afterpay, Affirm)</span><span class="chip missing">missing</span></div>
+        <div class="grounding">No BNPL driver or config entry anywhere in the repo. Shopify bundles Klarna natively in eligible regions with Pay-in-4, Pay-Later, and financing tiers; WooCommerce and PrestaShop both offer it as installable gateway plugins.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Bank transfer / open banking (SEPA, Pay by Bank)</span><span class="chip missing">missing</span></div>
+        <div class="grounding">Not represented as a distinct payment type; only the generic cash-in-hand offline flow exists, which is manual reconciliation rather than an automated bank-transfer rail.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Crypto / stablecoin checkout</span><span class="chip missing">missing</span></div>
+        <div class="grounding">No driver, no research finding of it being used in this stack. Industry-wide it's still marginal — stablecoin payment volume is roughly 0.02% of global payments in 2026 per Nuvei's trend report — so this is low-priority even elsewhere.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Pluggable driver architecture for adding methods</span><span class="chip have">have</span></div>
+        <div class="grounding"><code>Lunar\Managers\PaymentManager</code> extends Laravel's <code>Manager</code>; <code>Payments::extend('custom', fn ($app) => ...)</code> registers a new driver, and any class extending <code>Lunar\PaymentTypes\AbstractPayment</code> implementing <code>authorize()</code>/<code>capture()</code>/<code>refund()</code> plugs in. The scaffolding is solid — nothing beyond offline is plugged into it yet.</div>
+      </div>
+
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="category-head">
+      <span class="numeral">02</span>
+      <h2>Capture, refund &amp; transaction lifecycle</h2>
+    </div>
+    <p class="category-note">The core primitives (intent/capture/refund, partial amounts, transaction chaining) exist in Lunar and are exposed in the Filament admin — but nothing calls them outside cash-in-hand, and none of it is customer-facing.</p>
+    <div class="rows">
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Authorize / capture / refund contract</span><span class="chip have">have</span></div>
+        <div class="grounding"><code>Lunar\Base\PaymentTypeInterface</code> defines <code>authorize()</code>, <code>capture(Transaction $t, $amount)</code>, <code>refund(Transaction $t, int $amount, $notes)</code>; <code>Transaction::capture()</code>/<code>refund()</code> forward to the transaction's own <code>driver()</code> via <code>Payments::driver($this->driver)</code>.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Manual vs. automatic capture policy</span><span class="chip partial">partial</span></div>
+        <div class="grounding">The interface supports separate authorize/capture steps (intent vs. capture transaction types), but <code>OfflinePayment::capture()</code> just returns <code>new PaymentCapture(true)</code> unconditionally — there's no real deferred-capture gateway wired up to exercise the distinction.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Partial capture</span><span class="chip partial">partial</span></div>
+        <div class="grounding">Admin Filament action passes an arbitrary <code>$data['amount']</code> to <code>$transaction->capture(bcmul($data['amount'], $record->currency->factor))</code> in <code>ManageOrder.php</code> — the plumbing supports partial amounts, but only staff can trigger it, and only against a real (non-offline) driver would it mean anything.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Partial / staged refunds</span><span class="chip have">have</span></div>
+        <div class="grounding">Same file: the "refund" Filament action computes <code>$response = $transaction->refund(bcmul($data['amount'], ...), $data['notes'])</code>, and <code>isPartiallyRefunded()</code> / order status logic (<code>partial-refund</code>, <code>refunded</code>) compares <code>refundTotal</code> against <code>captureTotal</code>/<code>intentTotal</code>. This genuinely works today through the offline driver's no-op <code>refund()</code>.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Multiple payment attempts per order</span><span class="chip partial">partial</span></div>
+        <div class="grounding"><code>Transaction.parent_transaction_id</code> chains captures to intents and refunds to captures, and nothing in the model stops multiple transaction rows per order — but no code path in this repo actually retries a failed attempt with a second transaction; it's schema support, not a driven flow.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Transaction audit trail</span><span class="chip have">have</span></div>
+        <div class="grounding"><code>Lunar\Observers\TransactionObserver::created()</code> logs every transaction (amount, type, status, card_type, last_four, reference, notes) via Spatie activity log automatically — this is real and unconditional, independent of driver.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Webhook handling for async payment events</span><span class="chip missing">missing</span></div>
+        <div class="grounding">Lunar's Stripe package registers a <code>stripe/webhook</code> route, but that package isn't installed here, so there is no webhook endpoint of any kind in this project today.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Payment attempt events for downstream hooks</span><span class="chip have">have</span></div>
+        <div class="grounding"><code>Lunar\Events\PaymentAttemptEvent</code> is dispatched from <code>OfflinePayment::authorize()</code> with the resulting <code>PaymentAuthorize</code> DTO — a real, listenable event, though only one driver currently fires it.</div>
+      </div>
+
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="category-head">
+      <span class="numeral">03</span>
+      <h2>Customer-facing payment experience</h2>
+    </div>
+    <p class="category-note">Everything a shopper would touch directly — saved cards, one-click repeat purchase, self-service refunds — is absent. Lunar's payment layer is staff/checkout-oriented, not account-oriented.</p>
+    <div class="rows">
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Saved payment methods on customer account</span><span class="chip missing">missing</span></div>
+        <div class="grounding">No vault/tokenization model exists anywhere in <code>Lunar\Models</code> — no <code>PaymentMethod</code>/<code>Card</code> model, no field on <code>Customer</code>. 2026 trend research (Nuvei, Checkout.com) treats network-tokenized saved cards as baseline for one-click checkout.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">One-click repeat purchase</span><span class="chip missing">missing</span></div>
+        <div class="grounding">Depends on saved payment methods, which don't exist. No "reorder" or "buy again" affordance found in boboko-core or 3dealer.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Customer self-service refund requests</span><span class="chip missing">missing</span></div>
+        <div class="grounding">The only refund entry point is the Filament staff action in <code>ManageOrder.php</code> (<code>Actions\Action::make('refund')</code>), gated behind admin auth. WooCommerce/PrestaShop ecosystems commonly expose a customer-initiated return/refund request flow; nothing equivalent exists here.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Split / partial payment plans (pay-in-installments at checkout)</span><span class="chip missing">missing</span></div>
+        <div class="grounding">Distinct from BNPL-as-a-gateway: this is a native "split into N charges" checkout option, seen as marketplace split-payment modules in the PrestaShop ecosystem. No equivalent concept in Lunar's cart/order/payment pipeline.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">3D Secure / SCA authentication</span><span class="chip missing">missing</span></div>
+        <div class="grounding">3DS is a property of the card gateway integration (e.g. Stripe PaymentIntents), which isn't installed. WooPayments explicitly advertises 3DS/SCA compatibility with visible card-brand + last-four confirmation as a baseline expectation in 2026.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Fraud detection / risk scoring</span><span class="chip missing">missing</span></div>
+        <div class="grounding">No fraud-scoring hook in <code>PaymentTypeInterface</code> or the offline driver. <code>getPaymentChecks()</code> exists as an extension point (<code>Lunar\Base\DataTransferObjects\PaymentChecks</code>, an iterable of pass/fail <code>PaymentCheck</code> DTOs) but <code>AbstractPayment::getPaymentChecks()</code> just returns an empty collection — real fraud tooling (Stripe Radar-style) isn't behind it.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Payment check / validation extension point</span><span class="chip partial">partial</span></div>
+        <div class="grounding"><code>Transaction::paymentChecks()</code> → driver's <code>getPaymentChecks($transaction)</code> is real, typed infrastructure for surfacing checks (e.g. "AVS matched") in the admin UI — but the default implementation is a no-op, so nothing populates it today.</div>
+      </div>
+
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="category-head">
+      <span class="numeral">04</span>
+      <h2>Currency, subscriptions &amp; recurring billing</h2>
+    </div>
+    <p class="category-note">Lunar's multi-currency model covers pricing display, not multi-currency payment settlement; recurring billing/dunning has no representation at all.</p>
+    <div class="rows">
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Multi-currency pricing display</span><span class="chip have">have</span></div>
+        <div class="grounding"><code>Lunar\Models\Currency</code> (code, exchange_rate, decimal_places, default) with <code>sync_prices</code>-gated conversion, documented in <code>docs/lunar.md</code> "Channels and Currencies" — this is genuinely wired, cart/pricing layer already uses it.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Multi-currency payment processing (charge in customer's currency)</span><span class="chip partial">partial</span></div>
+        <div class="grounding">Pricing can display and calculate in any configured currency, but no payment driver in this project actually settles a charge — so whether a real gateway would charge in-currency is untested; the pricing half is there, the processing half isn't proven.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Recurring billing / subscriptions</span><span class="chip missing">missing</span></div>
+        <div class="grounding">No subscription model, no recurring-charge scheduler anywhere in <code>Lunar\Models</code> or boboko-core. This is a one-time-purchase order/cart model end to end.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">Failed-payment retry / dunning</span><span class="chip missing">missing</span></div>
+        <div class="grounding">No retry scheduling, no dunning email sequence, no soft-decline handling anywhere in the payment layer — there's nothing to retry against since there's no recurring billing and no live gateway. WooPayments' dunning (1-3 day delayed retry on soft declines) is the comparison point.</div>
+      </div>
+
+      <div class="row">
+        <div class="row-head"><span class="feature-name">PCI compliance / tokenized card storage</span><span class="chip missing">missing</span></div>
+        <div class="grounding">No card data is collected or stored anywhere in this codebase (offline driver never touches card fields), so there's no PCI-scope exposure today — but also no tokenized-vault capability to build saved cards or 3DS on top of when a real gateway is added.</div>
+      </div>
+
+    </div>
+  </section>
+
+  <footer>
+    <p class="compiled">Compiled 2026-08-28 &middot; boboko-core / docs</p>
+    <p>Section 01 (driver architecture) and section 02 (transaction lifecycle, refund/capture, observer, events) are grounded in direct reads of <code>vendor/lunarphp/core/src/{Managers,PaymentTypes,Models,Observers,Events,Base}</code> and <code>vendor/lunarphp/lunar/src/Filament/Resources/OrderResource/Pages/ManageOrder.php</code>, plus the published <code>config/lunar/payments.php</code> in 3dealer — not from <code>docs/lunar.md</code> alone, which was cross-checked and found to describe Lunar's general Stripe capability rather than anything installed in this project.</p>
+    <p>Sections 03 and 04, and the competitive framing throughout, draw on 2026 web research covering Shopify, WooCommerce/WooPayments, and PrestaShop payment modules, plus general industry trend reporting (Nuvei, Checkout.com, Mastercard). Those claims are marked by comparison language ("Shopify bundles...", "WooPayments advertises...") rather than citation to this repo.</p>
+  </footer>
+
+</div>

docs/scratch/privacy-feature-survey.html

@@ -0,0 +1,492 @@
+<title>Privacy Feature Survey</title>
+<style>
+  :root {
+    --paper: #FAFAF7;
+    --ink: #1C1C1A;
+    --muted: #6B6B63;
+    --accent: #2F5D50;
+    --accent-soft: #E4EDE9;
+    --good: #3F7A5C;
+    --good-soft: #E6F0EA;
+    --warn: #B8863B;
+    --warn-soft: #F5ECDC;
+    --miss: #A14B3B;
+    --miss-soft: #F5E5E0;
+    --hairline: #E4E2DB;
+    --card: #FFFFFF;
+  }
+
+  :root:not([data-theme="light"]) {
+    @media (prefers-color-scheme: dark) {
+      --paper: #17181A;
+      --ink: #EDEBE4;
+      --muted: #9B9A90;
+      --accent: #7FBFA8;
+      --accent-soft: #1E2C27;
+      --good: #6FBF97;
+      --good-soft: #1B2A22;
+      --warn: #D9A85C;
+      --warn-soft: #2C2418;
+      --miss: #D97C68;
+      --miss-soft: #2E1E1A;
+      --hairline: #2C2D2E;
+      --card: #1E1F21;
+    }
+  }
+
+  :root[data-theme="dark"] {
+    --paper: #17181A;
+    --ink: #EDEBE4;
+    --muted: #9B9A90;
+    --accent: #7FBFA8;
+    --accent-soft: #1E2C27;
+    --good: #6FBF97;
+    --good-soft: #1B2A22;
+    --warn: #D9A85C;
+    --warn-soft: #2C2418;
+    --miss: #D97C68;
+    --miss-soft: #2E1E1A;
+    --hairline: #2C2D2E;
+    --card: #1E1F21;
+  }
+
+  * { box-sizing: border-box; }
+
+  body {
+    background: var(--paper);
+    color: var(--ink);
+    font-family: "IBM Plex Sans", ui-sans-serif, system-ui, sans-serif;
+    font-size: 15.5px;
+    line-height: 1.55;
+    margin: 0;
+    padding: 4.5rem 1.5rem 6rem;
+  }
+
+  .wrap {
+    max-width: 780px;
+    margin: 0 auto;
+  }
+
+  header.page {
+    margin-bottom: 3.25rem;
+  }
+
+  .eyebrow {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: var(--accent);
+    margin-bottom: 0.9rem;
+  }
+
+  h1 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 560;
+    font-size: clamp(2.1rem, 4.5vw, 2.65rem);
+    line-height: 1.08;
+    letter-spacing: -0.01em;
+    margin: 0 0 0.9rem;
+    text-wrap: balance;
+  }
+
+  .dek {
+    color: var(--muted);
+    max-width: 60ch;
+    font-size: 1.02rem;
+  }
+
+  .dek strong {
+    color: var(--ink);
+    font-weight: 600;
+  }
+
+  .legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.6rem;
+    margin-top: 1.6rem;
+  }
+
+  .chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.04em;
+    padding: 0.28rem 0.6rem;
+    border-radius: 3px;
+  }
+
+  .chip.have { background: var(--good-soft); color: var(--good); }
+  .chip.partial { background: var(--warn-soft); color: var(--warn); }
+  .chip.missing { background: var(--miss-soft); color: var(--miss); }
+
+  .branch-note {
+    margin-top: 1.4rem;
+    padding: 0.85rem 1rem;
+    background: var(--accent-soft);
+    border-radius: 4px;
+    font-size: 0.86rem;
+    color: var(--ink);
+    max-width: 66ch;
+  }
+
+  .branch-note code {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.85em;
+    color: var(--accent);
+  }
+
+  section.category {
+    margin-top: 3rem;
+  }
+
+  .cat-head {
+    display: flex;
+    align-items: baseline;
+    gap: 0.85rem;
+    border-bottom: 1px solid var(--hairline);
+    padding-bottom: 0.7rem;
+    margin-bottom: 1.1rem;
+  }
+
+  .cat-num {
+    font-family: "Fraunces", Georgia, serif;
+    font-size: 1.05rem;
+    color: var(--accent);
+    font-variant-numeric: tabular-nums;
+    min-width: 1.6rem;
+  }
+
+  .cat-head h2 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 500;
+    font-size: 1.28rem;
+    margin: 0;
+    letter-spacing: -0.005em;
+  }
+
+  .cat-note {
+    color: var(--muted);
+    font-size: 0.86rem;
+    margin: 0 0 1.2rem;
+    max-width: 62ch;
+  }
+
+  .feature {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    gap: 0.3rem 1rem;
+    padding: 1.05rem 0;
+    border-bottom: 1px solid var(--hairline);
+    align-items: start;
+  }
+
+  .feature:last-child { border-bottom: none; }
+
+  .f-name {
+    font-weight: 600;
+    font-size: 0.98rem;
+  }
+
+  .f-status {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.68rem;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    padding: 0.22rem 0.55rem;
+    border-radius: 3px;
+    white-space: nowrap;
+    height: fit-content;
+  }
+
+  .f-status.have { background: var(--good-soft); color: var(--good); }
+  .f-status.partial { background: var(--warn-soft); color: var(--warn); }
+  .f-status.missing { background: var(--miss-soft); color: var(--miss); }
+
+  .f-note {
+    grid-column: 1 / -1;
+    color: var(--muted);
+    font-size: 0.87rem;
+    margin-top: 0.15rem;
+    max-width: 66ch;
+  }
+
+  .f-note code {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.82em;
+    background: var(--accent-soft);
+    color: var(--accent);
+    padding: 0.08em 0.35em;
+    border-radius: 3px;
+  }
+
+  footer.page {
+    margin-top: 4rem;
+    padding-top: 1.5rem;
+    border-top: 1px solid var(--hairline);
+    color: var(--muted);
+    font-size: 0.82rem;
+    display: flex;
+    justify-content: space-between;
+    gap: 1rem;
+    flex-wrap: wrap;
+  }
+
+  footer.page a { color: var(--accent); }
+
+  @media (max-width: 560px) {
+    body { padding: 3rem 1.1rem 4rem; }
+    .feature { grid-template-columns: 1fr; }
+    .f-status { justify-self: start; }
+  }
+</style>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400..600&family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap">
+
+<div class="wrap">
+
+  <header class="page">
+    <div class="eyebrow">boboko / privacy &amp; compliance · competitive survey</div>
+    <h1>What privacy &amp; compliance elsewhere can do that boboko can't yet</h1>
+    <p class="dek">
+      A feature-by-feature pass across GDPR/CCPA compliance tooling used by Shopify,
+      WooCommerce, and dedicated consent-management platforms — sourced, not recalled
+      from memory — checked against <strong>master</strong> and the substantial,
+      unmerged <strong><code>Privacy</code> branch</strong> ("Feature: Creating Privacy
+      Basics") already built in this repo. For deciding what to finish and merge
+      next, not a build order.
+    </p>
+    <div class="legend">
+      <span class="chip have">● have</span>
+      <span class="chip partial">◐ partial</span>
+      <span class="chip missing">○ missing</span>
+    </div>
+    <div class="branch-note">
+      Most "partial" rows below are fully coded on the unmerged <code>Privacy</code>
+      branch (53 files, +3127/&#8209;24 across two commits: <code>9f540cb</code>,
+      <code>59303cf</code>) but not on <code>master</code> — treated as partial, not
+      have, until it merges. <code>boboko:anonymize</code> is the one privacy-adjacent
+      command that already lives on <code>master</code> today.
+    </div>
+  </header>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">01</span>
+      <h2>Right of access &amp; erasure</h2>
+    </div>
+    <p class="cat-note">GDPR Art. 15 (access) and Art. 17 (erasure) — the two rights every DSAR tool is built around.</p>
+
+    <div class="feature">
+      <div class="f-name">Data export request (right of access)</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">On <code>Privacy</code> branch only: <code>PrivacyService::requestExportForCustomer()/requestExportForUser()</code> queue <code>ExportDataSubjectJob</code>, which gathers every registered provider's data and writes a CSV-per-provider zip via <code>WriteExportToCsvListener</code>. Not on <code>master</code>.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Data erasure request (right to be forgotten)</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">On <code>Privacy</code> branch only: <code>PrivacyService::requestErasureForCustomer()/requestErasureForUser()</code>, extensible via <code>config('core.privacy.providers')</code> — the same config-array-registration pattern as <code>NotificationRegistry</code>, keyed off <code>Modules\Core\Privacy\Contracts\PersonalDataProvider</code>.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Cancellable grace period before erasure</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">On <code>Privacy</code> branch only: 30-day default (<code>core.privacy.grace_period_days</code>), reverted automatically on login via <code>CancelErasureOnLoginListener</code> — same pattern Shopify's own account-deletion flow uses. No native platform documents this as a first-party primitive; it's usually left to a third-party app.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Immediate erasure for regulator/legal requests</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">On <code>Privacy</code> branch only: <code>requestImmediateErasureForCustomer()/ForUser()</code>, typed to accept only <code>Staff $requestedBy</code> so a self-service path cannot reach it even by accident.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Multi-tenant erasure scoping (business account vs. individual login)</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">On <code>Privacy</code> branch only, and a genuinely uncommon feature: <code>PrivacyService</code> splits every operation into Customer-scope vs. User-scope, plus a sole-owner cascade (<code>CascadeCustomerErasureListener</code>) when erasing the last linked User orphans a Customer. No researched competitor product handles B2B multi-seat erasure this explicitly.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Right to rectification (self-service data correction)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No dedicated flow found on either branch — Art. 16 is generally satisfied today only incidentally, by a customer editing their own profile/address through existing account forms, not a tracked rectification request.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Dummy data anonymization for local dev</div>
+      <span class="f-status have">have</span>
+      <div class="f-note">On <code>master</code>: <code>src/Command/AnonymizeCommand.php</code> (<code>boboko:anonymize</code>) — scrubs <code>users</code>/<code>lunar_customers</code>, environment-guarded to <code>local</code> only. Distinct from GDPR erasure; the <code>Privacy</code> branch README diff explicitly flags this is <strong>not</strong> the compliance tool.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">02</span>
+      <h2>Anonymization, pseudonymization &amp; retention</h2>
+    </div>
+    <p class="cat-note">Deletion isn't the only lawful outcome — these are three different operations, often confused with each other.</p>
+
+    <div class="feature">
+      <div class="f-name">Legal-retention pseudonymization (orders/invoices)</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">On <code>Privacy</code> branch only: <code>OrderDataProvider::eraseForCustomer()</code> clears PII fields but keeps order rows/totals/tax data intact, citing GDPR Art. 17(3)(b)'s legal-obligation exception — reports <code>ErasureOutcome::Pseudonymized</code>, not <code>Erased</code>, distinctly.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Per-provider retention policy, owned by the data's own module</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">On <code>Privacy</code> branch only: <code>PersonalDataProvider</code> deliberately has no central taxonomy — each provider (<code>CustomerDataProvider</code>, <code>AddressDataProvider</code>, <code>OrderDataProvider</code>, <code>CartDataProvider</code>, <code>ReviewDataProvider</code>) decides erase vs. pseudonymize vs. skip for its own table. <code>docs/privacy.md</code> flags <code>ReviewDataProvider</code>'s scope choice as needing review before relying on it.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Automatic data retention / auto-deletion after N days</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Neither branch has a scheduled sweep that erases stale data on its own — every erasure on the <code>Privacy</code> branch is triggered by an explicit request, not a retention-policy timer (e.g. "delete guest carts after 2 years," "purge OTP logs after 90 days").</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Audit trail of what was erased/exported and why</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">On <code>Privacy</code> branch only: <code>DataErasureRequest.report</code> stores the full per-provider outcome as a snapshot (not a live lookup), specifically so the audit record stays readable after the underlying data is gone.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">03</span>
+      <h2>Consent &amp; cookies</h2>
+    </div>
+    <p class="cat-note">What a visitor is asked before tracking starts, and whether that choice is recorded anywhere.</p>
+
+    <div class="feature">
+      <div class="f-name">Cookie consent banner (categorized: essential/analytics/marketing)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No code on either branch. Shopify ships a first-party <code>Customer Privacy API</code> recognizing four consent signals (analytics, marketing, preferences, sale-of-data); WooCommerce relies entirely on third-party plugins for this.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Granular marketing-consent tracking (email/SMS opt-in, per channel)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Not modeled anywhere in <code>Modules\Core</code> — no consent flag found on the <code>Customer</code>/<code>User</code> models on either branch.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Timestamped, versioned consent log (audit trail per visitor)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Standard feature of dedicated CMPs (OneTrust, Enzuzo, Consentmo) — a logged record of which policy version a visitor consented to and when. Nothing comparable exists in this codebase; the <code>Privacy</code> branch's audit trail covers erasure/export requests only, not consent events.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Google Consent Mode v2 / IAB TCF v2.3 integration</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Storefront/analytics-layer concern, not present in boboko-core at all — would live in the 3dealer storefront, not this package.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">04</span>
+      <h2>Policy &amp; agreement management</h2>
+    </div>
+    <p class="cat-note">Terms of service and privacy policy as tracked, versioned documents — not just static pages.</p>
+
+    <div class="feature">
+      <div class="f-name">Terms-of-service / privacy-policy versioning</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No version-tracked policy document model on either branch — best practice researched: store version hashes or dated text alongside each acceptance record, review at least annually.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Per-user acceptance tracking (clickwrap audit trail)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No record of "which policy version did this customer accept, and when" anywhere in <code>Modules\Core</code>. Researched as a standard requirement for surviving a legal dispute or regulatory inquiry.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Re-acceptance prompt on material policy change</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Depends on the versioning row above existing first — nothing to gate a re-prompt on today.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">05</span>
+      <h2>Payment data &amp; PCI-DSS scope</h2>
+    </div>
+    <p class="cat-note">Whether cardholder data ever actually reaches boboko's own infrastructure.</p>
+
+    <div class="feature">
+      <div class="f-name">Card data never touches application servers (tokenization)</div>
+      <span class="f-status have">have</span>
+      <div class="f-note">Verified from source: <code>docs/lunar.md</code> "Stripe integration" — payment flows through Lunar's Stripe driver (<code>Lunar\Stripe\Facades\Stripe</code>, <code>fetchOrCreateIntent()</code>/PaymentIntents), so PAN never lands in a boboko/Lunar database. Researched: this pattern alone can cut PCI-DSS scope by roughly 90% per industry sources.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Self-attested SAQ-A eligibility documentation</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">The technical precondition (no card data touching the server) is met, but nothing in <code>docs/</code> documents or asserts SAQ-A eligibility for a consuming app's own compliance paperwork.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">06</span>
+      <h2>Regional &amp; regulatory coverage</h2>
+    </div>
+    <p class="cat-note">Beyond GDPR — the other regimes a storefront selling outside the EU may need.</p>
+
+    <div class="feature">
+      <div class="f-name">CCPA "Do Not Sell/Share My Info" opt-out</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No opt-out flag or page found on either branch. Shopify's Customer Privacy API models this as a distinct fourth consent signal ("sale of data") alongside analytics/marketing/preferences — boboko has no equivalent signal at all yet.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Geo-targeted regulatory detection (GDPR vs. CCPA vs. LGPD banner)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Third-party CMPs (Consentmo, UniConsent) auto-detect visitor region to show the applicable banner/rights. No geo-based privacy-regime logic anywhere in this codebase.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Age verification / minor-data restrictions (COPPA-adjacent)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No age gate or minor-specific data handling found on either branch.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">07</span>
+      <h2>Incident &amp; vendor accountability</h2>
+    </div>
+    <p class="cat-note">What happens when something goes wrong, or when a third party is handling data on the shop's behalf.</p>
+
+    <div class="feature">
+      <div class="f-name">Data breach notification workflow</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No incident-tracking model or notification path found on either branch — GDPR Art. 33/34's 72-hour authority-notification and affected-subject-notification duties have no tooling here today.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Subprocessor / third-party vendor disclosure list</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No subprocessor registry in code — Stripe is the one third-party data processor identifiable from <code>docs/lunar.md</code>, but nothing formally tracks or discloses it as a subprocessor.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Data processing agreement (DPA) tracking per vendor</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Not applicable to application code directly, but no config or doc references a DPA registry either — purely a legal/ops artifact today, not represented in boboko-core at all.</div>
+    </div>
+  </section>
+
+  <footer class="page">
+    <span>Compiled 2026-08-28 — <code>have</code>/<code>partial</code> statuses sourced from direct reads of <code>master</code> and the unmerged <code>Privacy</code> branch (commits <code>9f540cb</code>, <code>59303cf</code>) via <code>git show</code>; competitor/regulatory claims sourced from web research, cited inline.</span>
+    <span>boboko-core / docs</span>
+  </footer>
+
+</div>

docs/scratch/products-collections-feature-survey.html

@@ -0,0 +1,508 @@
+<title>Products &amp; Collections Feature Survey</title>
+<style>
+  :root {
+    --paper: #FAFAF7;
+    --ink: #1C1C1A;
+    --muted: #6B6B63;
+    --accent: #2F5D50;
+    --accent-soft: #E4EDE9;
+    --good: #3F7A5C;
+    --good-soft: #E6F0EA;
+    --warn: #B8863B;
+    --warn-soft: #F5ECDC;
+    --miss: #A14B3B;
+    --miss-soft: #F5E5E0;
+    --hairline: #E4E2DB;
+    --card: #FFFFFF;
+  }
+
+  :root:not([data-theme="light"]) {
+    @media (prefers-color-scheme: dark) {
+      --paper: #17181A;
+      --ink: #EDEBE4;
+      --muted: #9B9A90;
+      --accent: #7FBFA8;
+      --accent-soft: #1E2C27;
+      --good: #6FBF97;
+      --good-soft: #1B2A22;
+      --warn: #D9A85C;
+      --warn-soft: #2C2418;
+      --miss: #D97C68;
+      --miss-soft: #2E1E1A;
+      --hairline: #2C2D2E;
+      --card: #1E1F21;
+    }
+  }
+
+  :root[data-theme="dark"] {
+    --paper: #17181A;
+    --ink: #EDEBE4;
+    --muted: #9B9A90;
+    --accent: #7FBFA8;
+    --accent-soft: #1E2C27;
+    --good: #6FBF97;
+    --good-soft: #1B2A22;
+    --warn: #D9A85C;
+    --warn-soft: #2C2418;
+    --miss: #D97C68;
+    --miss-soft: #2E1E1A;
+    --hairline: #2C2D2E;
+    --card: #1E1F21;
+  }
+
+  * { box-sizing: border-box; }
+
+  body {
+    background: var(--paper);
+    color: var(--ink);
+    font-family: "IBM Plex Sans", ui-sans-serif, system-ui, sans-serif;
+    font-size: 15.5px;
+    line-height: 1.55;
+    margin: 0;
+    padding: 4.5rem 1.5rem 6rem;
+  }
+
+  .wrap {
+    max-width: 780px;
+    margin: 0 auto;
+  }
+
+  header.page {
+    margin-bottom: 3.25rem;
+  }
+
+  .eyebrow {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: var(--accent);
+    margin-bottom: 0.9rem;
+  }
+
+  h1 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 560;
+    font-size: clamp(2.1rem, 4.5vw, 2.65rem);
+    line-height: 1.08;
+    letter-spacing: -0.01em;
+    margin: 0 0 0.9rem;
+    text-wrap: balance;
+  }
+
+  .dek {
+    color: var(--muted);
+    max-width: 60ch;
+    font-size: 1.02rem;
+  }
+
+  .dek strong {
+    color: var(--ink);
+    font-weight: 600;
+  }
+
+  .callout {
+    margin-top: 1.4rem;
+    padding: 0.9rem 1.1rem;
+    background: var(--accent-soft);
+    border-radius: 4px;
+    color: var(--ink);
+    font-size: 0.88rem;
+    max-width: 62ch;
+  }
+
+  .callout strong { color: var(--accent); }
+
+  .legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.6rem;
+    margin-top: 1.6rem;
+  }
+
+  .chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.04em;
+    padding: 0.28rem 0.6rem;
+    border-radius: 3px;
+  }
+
+  .chip.have { background: var(--good-soft); color: var(--good); }
+  .chip.partial { background: var(--warn-soft); color: var(--warn); }
+  .chip.missing { background: var(--miss-soft); color: var(--miss); }
+
+  .tally {
+    margin-top: 1rem;
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.78rem;
+    color: var(--muted);
+    letter-spacing: 0.02em;
+  }
+
+  .tally b { color: var(--ink); }
+
+  section.category {
+    margin-top: 3rem;
+  }
+
+  .cat-head {
+    display: flex;
+    align-items: baseline;
+    gap: 0.85rem;
+    border-bottom: 1px solid var(--hairline);
+    padding-bottom: 0.7rem;
+    margin-bottom: 1.1rem;
+  }
+
+  .cat-num {
+    font-family: "Fraunces", Georgia, serif;
+    font-size: 1.05rem;
+    color: var(--accent);
+    font-variant-numeric: tabular-nums;
+    min-width: 1.6rem;
+  }
+
+  .cat-head h2 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 500;
+    font-size: 1.28rem;
+    margin: 0;
+    letter-spacing: -0.005em;
+  }
+
+  .cat-note {
+    color: var(--muted);
+    font-size: 0.86rem;
+    margin: 0 0 1.2rem;
+    max-width: 62ch;
+  }
+
+  .feature {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    gap: 0.3rem 1rem;
+    padding: 1.05rem 0;
+    border-bottom: 1px solid var(--hairline);
+    align-items: start;
+  }
+
+  .feature:last-child { border-bottom: none; }
+
+  .f-name {
+    font-weight: 600;
+    font-size: 0.98rem;
+  }
+
+  .f-status {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.68rem;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    padding: 0.22rem 0.55rem;
+    border-radius: 3px;
+    white-space: nowrap;
+    height: fit-content;
+  }
+
+  .f-status.have { background: var(--good-soft); color: var(--good); }
+  .f-status.partial { background: var(--warn-soft); color: var(--warn); }
+  .f-status.missing { background: var(--miss-soft); color: var(--miss); }
+
+  .f-note {
+    grid-column: 1 / -1;
+    color: var(--muted);
+    font-size: 0.87rem;
+    margin-top: 0.15rem;
+    max-width: 66ch;
+  }
+
+  .f-note code {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.82em;
+    background: var(--accent-soft);
+    color: var(--accent);
+    padding: 0.08em 0.35em;
+    border-radius: 3px;
+  }
+
+  footer.page {
+    margin-top: 4rem;
+    padding-top: 1.5rem;
+    border-top: 1px solid var(--hairline);
+    color: var(--muted);
+    font-size: 0.82rem;
+    display: flex;
+    justify-content: space-between;
+    gap: 1rem;
+    flex-wrap: wrap;
+  }
+
+  footer.page a { color: var(--accent); }
+
+  @media (max-width: 560px) {
+    body { padding: 3rem 1.1rem 4rem; }
+    .feature { grid-template-columns: 1fr; }
+    .f-status { justify-self: start; }
+  }
+</style>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400..600&family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap">
+
+<div class="wrap">
+
+  <header class="page">
+    <div class="eyebrow">boboko / products &amp; collections · competitive survey</div>
+    <h1>What products &amp; collections elsewhere can do that boboko can't yet</h1>
+    <p class="dek">
+      A feature-by-feature pass across Shopify, WooCommerce, PrestaShop, and general
+      2026 storefront UX trends — checked against what
+      <strong><code>Modules\Core\Catalog</code></strong> actually ships in boboko-core
+      and what 3dealer's storefront actually calls. Unlike the rest of this survey
+      series, this concern is not a blank slate: a real Meilisearch-backed catalog
+      layer (listing, filtering, facets, search, collections, a product-option-type
+      system) was built this session. The gaps here are mostly about storefront wiring
+      and discovery/merchandising UX, not backend plumbing.
+    </p>
+    <div class="callout">
+      <strong>Read this first:</strong> the category page's sort dropdown, price
+      slider, in-stock checkbox, and sidebar search box are all visually present but
+      functionally dead — none of them submit a request or call a filter. The backend
+      methods they'd need (<code>ProductService::facets()</code>,
+      <code>priceRange()</code>, <code>list()</code>'s sort param) already exist and
+      work; nothing in <code>CategoryController</code> passes them through yet.
+    </div>
+    <div class="legend">
+      <span class="chip have">● have</span>
+      <span class="chip partial">◐ partial</span>
+      <span class="chip missing">○ missing</span>
+    </div>
+    <div class="tally">31 features surveyed — <b>8 have</b> · <b>10 partial</b> · <b>13 missing</b></div>
+  </header>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">01</span>
+      <h2>Core listing &amp; filtering plumbing</h2>
+    </div>
+    <p class="cat-note">The Meilisearch-backed layer everything else in this survey sits on top of — this is where most of this session's real build lives.</p>
+
+    <div class="feature">
+      <div class="f-name">Paginated product listing, index-backed (not DB reads)</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ProductService::list()</code> reads <code>Product::search('')</code> via Meilisearch and returns a real <code>LengthAwarePaginator</code> — used end-to-end by <code>CategoryController::show()</code> and rendered by <code>x-product-grid</code>.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Filter by collection (including descendant collections)</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ProductFilters::collectionId</code> matches <code>ProductIndexer</code>'s <code>collection_ids</code> field, which unions a product's direct collections with all ancestors — so a parent-category page picks up products attached only to a leaf subcategory. Wired in <code>CategoryController</code>.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Filter by brand, price range, stock status</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note"><code>ProductFilters</code> supports <code>brand</code>, <code>minPrice</code>/<code>maxPrice</code>, <code>inStockOnly</code>, fully implemented in <code>ProductService::buildFilter()</code> — but <code>category/show.blade.php</code>'s price slider and in-stock checkbox are hardcoded markup with no form submission; <code>CategoryController</code> never constructs a <code>ProductFilters</code> with any of these three.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Faceted counts for a filter sidebar (brand, stock, etc.)</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note"><code>ProductService::facets()</code> returns value→count via Meilisearch <code>facetDistribution</code>, correctly scoped to co-applied filters — but nothing storefront-side calls it. No brand/attribute facet list renders anywhere in <code>category/show.blade.php</code>.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Price-range slider backed by real min/max</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note"><code>ProductService::priceRange()</code> reads Meilisearch <code>facetStats</code> for a correct, filter-scoped min/max — the sidebar instead shows a static "€10 - €50" label with a non-functional apply button.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Sort (price asc/desc, newest)</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note"><code>ProductSort</code> enum + <code>ProductIndexer::getSortableFields()</code> (price, created_at) work end-to-end in <code>ProductService::list(sort: ...)</code> — the storefront's sort <code>&lt;select&gt;</code> is explicitly commented <code>{{-- Dummy — not wired to real sorting yet --}}</code> and includes a "popularity" option with no backing signal at all.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Free-text product search</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note"><code>ProductSearchService::search()</code> is a complete, locale-aware, fallback-safe implementation (<code>attributesToSearchOn</code> targeting current + default locale) — but no search route exists in 3dealer (<code>routes/web.php</code> only has <code>product.show</code>/<code>category.show</code>), and both the header search icon and the sidebar search box are inert buttons/inputs.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Single-product lookup by slug or id, index-only</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ProductService::getById()</code>/<code>getBySlug()</code>, both zero-database-read lookups against the <code>slugs</code>/<code>id</code> filterable fields. <code>ProductController::show()</code> uses <code>getById()</code> directly.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">02</span>
+      <h2>Collections &amp; navigation</h2>
+    </div>
+    <p class="cat-note">Category tree browsing, breadcrumbs, and merchandising — what turns a flat product list into a navigable store.</p>
+
+    <div class="feature">
+      <div class="f-name">Category tree browsing (root / children / by group)</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>CollectionService::list()</code> with <code>CollectionFilters(rootOnly</code>/<code>parentId</code>/<code>groupId)</code>, backed by <code>CollectionIndexer</code>'s nested-set <code>parent_id</code>/<code>_lft</code> fields — no database read needed to build a nav tree.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Top-nav category dropdown</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>components/header.blade.php</code> renders a CSS-only hover dropdown from a <code>$categories</code> list passed into the layout, linking to <code>category.show</code>.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Breadcrumb navigation</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note"><code>CollectionIndexer</code> indexes a full root-first <code>ancestors</code> array ({id, name}) specifically so a breadcrumb needs zero extra queries — but <code>category/show.blade.php</code> and <code>product/show.blade.php</code> both build a flat two-level <code>x-breadcrumb</code> (Home → this category/product) by hand, never reading <code>ancestors</code>. A product under a three-deep category shows no intermediate levels.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Category landing page merchandising (banner, pinned/featured products)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note"><code>category/show.blade.php</code> renders only the collection name/description above a plain product grid — no banner image field, no "featured in this category" pinning above organic results. <code>CollectionIndexer</code>'s <code>thumbnail</code> field exists but isn't read on the category page at all (only used, if anywhere, for nav-level imagery).</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Sub-category faceting (filter by attribute within a category)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No attribute-value facet (size, material, etc.) is indexed as filterable on <code>ProductIndexer</code> beyond <code>brand</code> and <code>in_stock</code> — a category page can't offer "filter dresses by size" the way Shopify/WooCommerce faceted nav does; would need new filterable fields on custom product attributes plus sidebar UI.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Product count shown per category</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note"><code>CollectionIndexer</code> computes <code>product_count</code> (including descendant collections) at index time by querying the product index directly — correct and cheap, but nothing in <code>category/show.blade.php</code> or the nav dropdown displays it.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">03</span>
+      <h2>Product detail page</h2>
+    </div>
+    <p class="cat-note">What a shopper sees once they land on a single product — media, variants, reviews, cross-sell.</p>
+
+    <div class="feature">
+      <div class="f-name">Multi-image gallery with lightbox</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>product/show.blade.php</code>'s <code>product-gallery</code> Stimulus controller — thumbnail rail, main image, full popover lightbox with prev/next/counter — fed from <code>ProductIndexer</code>'s full <code>media</code> array (not just a single thumbnail).</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Variant selection via color swatches</div>
+      <span class="f-status have">have</span>
+      <div class="f-note">End-to-end: <code>ColorOptionType</code> lets an admin attach a hex code to an option value → <code>ProductIndexer::mapVariant()</code> embeds <code>meta.hex</code> per variant → <code>x-ui.color-swatch</code> renders real swatch buttons wired to a <code>product-form</code> Stimulus controller that swaps price/image on selection.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Swatches for non-color attributes (pattern, texture, material)</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">The <code>ProductOptionTypeInterface</code> system is explicitly built to be extensible — a <code>PatternOptionType</code> or <code>MaterialOptionType</code> is a new class plus a Filament form, no core change needed — but only <code>ColorOptionType</code> is registered, and <code>x-ui.color-swatch</code> itself hardcodes a background-color swatch, not a generic swatch renderer.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Customer reviews with ratings, photos, staff replies</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ProductReview</code> model, fully indexed (<code>items</code>/<code>count</code>/<code>average_rating</code>, PII-safe), live-reindexed on review create/update/delete via <code>ReviewServiceProvider</code>, and rendered in <code>product/show.blade.php</code>'s Reviews tab with <code>x-review-card</code>/<code>x-review-form</code>.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Structured data / schema.org Product markup</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No <code>application/ld+json</code> or <code>itemscope</code> markup anywhere in 3dealer's views. Rich results (price/rating/availability in Google Shopping) are a significant organic-CTR lever per 2026 SEO guidance — the product page already has every field (price, rating, stock) a Product schema block would need, just not emitted.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Related products / "customers also bought" / cross-sell</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Raw Lunar already models this (<code>Lunar\Base\Enums\ProductAssociation::CROSS_SELL</code>/<code>UP_SELL</code>/<code>ALTERNATE</code>, <code>$product-&gt;associate()</code>/<code>associations()</code> — see <code>docs/lunar.md</code> "Products and Variants") but nothing in <code>Modules\Core\Catalog</code> surfaces it, and the "Σχετικά προϊόντα" block at the bottom of <code>product/show.blade.php</code> is four fully hardcoded fake products with <code>href =&gt; '#'</code>.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Recently-viewed products</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No session/cookie tracking of viewed products anywhere in 3dealer or core — a standard discovery module on both Shopify and WooCommerce storefronts per current UX research.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Product badges (new / sale / bestseller)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No badge concept on <code>ProductIndexer</code>'s document and no badge markup on <code>x-ui.product-card</code> — would need either a computed signal (e.g. "new" from <code>created_at</code>, "sale" from <code>compare_price</code> already indexed per-variant) or an admin-set tag, neither wired to a visual badge today.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Size chart / fit guide</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No size-chart content field on <code>Product</code>/<code>ProductType</code> and no UI for it on the product page. Not especially relevant to 3dealer's current catalog (3D-printed goods), but a real gap for any apparel-leaning store built on this core.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Stock notification ("notify me when back in stock")</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note"><code>in_stock</code> is indexed and known per-product (<code>ProductIndexer::toSearchableArray()</code>), but there's no subscription model, email trigger, or UI for a shopper to ask to be notified — the signal exists, nothing acts on it.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Product Q&amp;A section</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No question/answer model anywhere in core — only the separate review system (<code>ProductReview</code>) exists, which is a distinct concept (post-purchase rating, not pre-purchase Q&amp;A).</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">04</span>
+      <h2>Emerging discovery &amp; merchandising UX</h2>
+    </div>
+    <p class="cat-note">2026 trend-adjacent features, mostly backed on other platforms by paid apps/plugins rather than core — useful for calibrating how unusual these gaps are.</p>
+
+    <div class="feature">
+      <div class="f-name">Quick-view modal (preview from listing grid, no page load)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note"><code>x-ui.product-card</code> links straight to <code>product.show</code> with a hover-revealed "add to cart" button only — no modal/preview interaction. Current UX research flags quick-view modals as a common INP (responsiveness) failure point, so the absence isn't purely a gap to close blindly.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Infinite scroll as an alternative to pagination</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note"><code>category/show.blade.php</code> uses classic <code>x-ui.pagination</code> against the real paginator from <code>ProductService::list()</code> — works correctly, just page-based rather than scroll-based. Research is genuinely mixed on whether infinite scroll is even preferable for conversion/SEO, so this is a parity note, not a clear gap.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Product comparison tool (side-by-side spec table)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Not in boboko-core, and notably not native on Shopify or WooCommerce either — both rely on third-party apps (Bear Specs &amp; Compare, Equate, WooCommerce's own paid "Advanced Product Comparison" extension). A real gap, but not one competitors solve in-platform for free.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Product bundles / kits</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No bundle/kit concept (a purchasable grouping of several variants as one line item) anywhere in <code>Lunar\Models\Product</code>/<code>ProductVariant</code> or <code>Modules\Core\Catalog</code>.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">360°/video product media, AR try-on</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note"><code>ProductIndexer</code>'s <code>media</code> array is just Spatie media-library images (<code>url</code>/<code>thumb</code>) — no video or 360° asset type modeled, and no AR integration. The gallery component (<code>product-gallery</code> Stimulus controller) is generic enough to extend to a video slide without a rewrite, but nothing does today.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Variant-specific SEO URLs (distinct slug per color/size)</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note">Lunar's <code>HasUrls</code>/<code>Url</code> model supports per-locale slugs per <em>product</em> (indexed in <code>ProductIndexer</code>'s <code>slugs</code> field), but there's no per-<em>variant</em> URL — selecting a color swatch changes displayed price/image via <code>product-form</code> client-side state, not the URL, so a specific variant can't be linked or indexed separately.</div>
+    </div>
+  </section>
+
+  <footer class="page">
+    <span>Compiled 2026-08-28 — <code>Modules\Core\Catalog</code> source, docs, and 3dealer storefront claims are direct reads; 2026 UX-trend, quick-view/infinite-scroll, and product-comparison-tooling claims are sourced from web research and marked accordingly in context.</span>
+    <span>boboko-core / docs</span>
+  </footer>
+
+</div>

docs/scratch/shipping-feature-survey.html

@@ -0,0 +1,465 @@
+<title>Shipping Feature Survey</title>
+<style>
+  :root {
+    --paper: #FAFAF7;
+    --ink: #1C1C1A;
+    --muted: #6B6B63;
+    --accent: #2F5D50;
+    --accent-soft: #E4EDE9;
+    --good: #3F7A5C;
+    --good-soft: #E6F0EA;
+    --warn: #B8863B;
+    --warn-soft: #F5ECDC;
+    --miss: #A14B3B;
+    --miss-soft: #F5E5E0;
+    --hairline: #E4E2DB;
+    --card: #FFFFFF;
+  }
+
+  :root:not([data-theme="light"]) {
+    @media (prefers-color-scheme: dark) {
+      --paper: #17181A;
+      --ink: #EDEBE4;
+      --muted: #9B9A90;
+      --accent: #7FBFA8;
+      --accent-soft: #1E2C27;
+      --good: #6FBF97;
+      --good-soft: #1B2A22;
+      --warn: #D9A85C;
+      --warn-soft: #2C2418;
+      --miss: #D97C68;
+      --miss-soft: #2E1E1A;
+      --hairline: #2C2D2E;
+      --card: #1E1F21;
+    }
+  }
+
+  :root[data-theme="dark"] {
+    --paper: #17181A;
+    --ink: #EDEBE4;
+    --muted: #9B9A90;
+    --accent: #7FBFA8;
+    --accent-soft: #1E2C27;
+    --good: #6FBF97;
+    --good-soft: #1B2A22;
+    --warn: #D9A85C;
+    --warn-soft: #2C2418;
+    --miss: #D97C68;
+    --miss-soft: #2E1E1A;
+    --hairline: #2C2D2E;
+    --card: #1E1F21;
+  }
+
+  * { box-sizing: border-box; }
+
+  body {
+    background: var(--paper);
+    color: var(--ink);
+    font-family: "IBM Plex Sans", ui-sans-serif, system-ui, sans-serif;
+    font-size: 15.5px;
+    line-height: 1.55;
+    margin: 0;
+    padding: 4.5rem 1.5rem 6rem;
+  }
+
+  .wrap {
+    max-width: 780px;
+    margin: 0 auto;
+  }
+
+  header.page {
+    margin-bottom: 3.25rem;
+  }
+
+  .eyebrow {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: var(--accent);
+    margin-bottom: 0.9rem;
+  }
+
+  h1 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 560;
+    font-size: clamp(2.1rem, 4.5vw, 2.65rem);
+    line-height: 1.08;
+    letter-spacing: -0.01em;
+    margin: 0 0 0.9rem;
+    text-wrap: balance;
+  }
+
+  .dek {
+    color: var(--muted);
+    max-width: 60ch;
+    font-size: 1.02rem;
+  }
+
+  .dek strong {
+    color: var(--ink);
+    font-weight: 600;
+  }
+
+  .legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.6rem;
+    margin-top: 1.6rem;
+  }
+
+  .chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.04em;
+    padding: 0.28rem 0.6rem;
+    border-radius: 3px;
+  }
+
+  .chip.have { background: var(--good-soft); color: var(--good); }
+  .chip.partial { background: var(--warn-soft); color: var(--warn); }
+  .chip.missing { background: var(--miss-soft); color: var(--miss); }
+
+  section.category {
+    margin-top: 3rem;
+  }
+
+  .cat-head {
+    display: flex;
+    align-items: baseline;
+    gap: 0.85rem;
+    border-bottom: 1px solid var(--hairline);
+    padding-bottom: 0.7rem;
+    margin-bottom: 1.1rem;
+  }
+
+  .cat-num {
+    font-family: "Fraunces", Georgia, serif;
+    font-size: 1.05rem;
+    color: var(--accent);
+    font-variant-numeric: tabular-nums;
+    min-width: 1.6rem;
+  }
+
+  .cat-head h2 {
+    font-family: "Fraunces", Georgia, serif;
+    font-weight: 500;
+    font-size: 1.28rem;
+    margin: 0;
+    letter-spacing: -0.005em;
+  }
+
+  .cat-note {
+    color: var(--muted);
+    font-size: 0.86rem;
+    margin: 0 0 1.2rem;
+    max-width: 62ch;
+  }
+
+  .feature {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    gap: 0.3rem 1rem;
+    padding: 1.05rem 0;
+    border-bottom: 1px solid var(--hairline);
+    align-items: start;
+  }
+
+  .feature:last-child { border-bottom: none; }
+
+  .f-name {
+    font-weight: 600;
+    font-size: 0.98rem;
+  }
+
+  .f-status {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.68rem;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    padding: 0.22rem 0.55rem;
+    border-radius: 3px;
+    white-space: nowrap;
+    height: fit-content;
+  }
+
+  .f-status.have { background: var(--good-soft); color: var(--good); }
+  .f-status.partial { background: var(--warn-soft); color: var(--warn); }
+  .f-status.missing { background: var(--miss-soft); color: var(--miss); }
+
+  .f-note {
+    grid-column: 1 / -1;
+    color: var(--muted);
+    font-size: 0.87rem;
+    margin-top: 0.15rem;
+    max-width: 66ch;
+  }
+
+  .f-note code {
+    font-family: "IBM Plex Mono", ui-monospace, monospace;
+    font-size: 0.82em;
+    background: var(--accent-soft);
+    color: var(--accent);
+    padding: 0.08em 0.35em;
+    border-radius: 3px;
+  }
+
+  footer.page {
+    margin-top: 4rem;
+    padding-top: 1.5rem;
+    border-top: 1px solid var(--hairline);
+    color: var(--muted);
+    font-size: 0.82rem;
+    display: flex;
+    justify-content: space-between;
+    gap: 1rem;
+    flex-wrap: wrap;
+  }
+
+  footer.page a { color: var(--accent); }
+
+  @media (max-width: 560px) {
+    body { padding: 3rem 1.1rem 4rem; }
+    .feature { grid-template-columns: 1fr; }
+    .f-status { justify-self: start; }
+  }
+</style>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400..600&family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap">
+
+<div class="wrap">
+
+  <header class="page">
+    <div class="eyebrow">boboko / shipping · competitive survey</div>
+    <h1>What shipping elsewhere can do that boboko can't yet</h1>
+    <p class="dek">
+      A feature-by-feature pass across Shopify, WooCommerce, and PrestaShop's shipping
+      layer — sourced, not recalled from memory — checked against what
+      <strong>Lunar core's <code>ShippingManifest</code></strong> and the
+      <strong><code>lunarphp/table-rate-shipping</code></strong> add-on actually support
+      today, and what's actually wired up in boboko-core and 3dealer right now.
+      For deciding what to design next, not a build order.
+    </p>
+    <div class="legend">
+      <span class="chip have">● have</span>
+      <span class="chip partial">◐ partial</span>
+      <span class="chip missing">○ missing</span>
+    </div>
+  </header>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">01</span>
+      <h2>Core plumbing</h2>
+    </div>
+    <p class="cat-note">The mechanism Lunar core provides for offering and applying a shipping charge — everything else in this survey is built on top of it.</p>
+
+    <div class="feature">
+      <div class="f-name">Pluggable shipping option providers</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Lunar\Base\ShippingModifier</code> abstract class + <code>ShippingManifest::addOption()</code> — any package can register options onto the manifest via a pipeline of modifiers (<code>ShippingModifiers::getModifiers()</code>).</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Shipping applied to cart totals during calculate()</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Lunar\Pipelines\Cart\ApplyShipping</code> — reads <code>ShippingManifest::getShippingOption($cart)</code> or a manual <code>shippingOptionOverride</code>, writes a <code>ShippingBreakdown</code> and <code>shippingSubTotal</code> onto the cart before <code>CalculateTax</code> runs.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Cart-level shippable check</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Cart::isShippable()</code> — true if any line's <code>purchasable</code> (e.g. <code>ProductVariant::isShippable()</code>) is shippable; a digital-only cart skips the shipping-address requirement entirely.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Selecting a shipping option on the cart</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Cart::setShippingOption()</code> → <code>SetShippingOption</code> action, validated by <code>ShippingOptionValidator</code>, triggers a recalculate. Nothing in 3dealer's storefront calls it yet — no shipping step exists in the UI.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Order-time shipping line snapshot</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Lunar\Pipelines\Order\Creation\CreateShippingLine</code> writes an immutable <code>shipping</code>-type order line from the cart's shipping breakdown at checkout — survives later rate changes.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">02</span>
+      <h2>Rate configuration (table-rate-shipping add-on)</h2>
+    </div>
+    <p class="cat-note"><code>lunarphp/table-rate-shipping</code> is installed (<code>composer.json</code>, pinned <code>^1.3</code>) and its <code>ShippingPlugin</code> is registered in <code>CorePlugin::boot()</code> — so 3dealer inherits it automatically, it doesn't need its own registration.</p>
+
+    <div class="feature">
+      <div class="f-name">Geographic shipping zones (country / state / postcode)</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ShippingZone</code> model, type <code>unrestricted|countries|states|postcodes</code>; <code>ShippingZoneResolver::get()</code> matches a cart's address against zone scope, falling back to any <code>unrestricted</code> zone.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Flat-rate shipping</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Drivers\ShippingMethods\FlatRate::resolve()</code> — one price per cart subtotal via <code>Pricing::for($shippingRate)</code>.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Weight- or total-tiered rates ("ship by")</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Drivers\ShippingMethods\ShipBy::resolve()</code> — <code>data['charge_by']</code> is <code>cart_total</code> or <code>weight</code>, tiered via <code>priceBreaks</code>, with customer-group price overrides taking priority.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Free-shipping threshold</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Drivers\ShippingMethods\FreeShipping::resolve()</code> — <code>data['minimum_spend']</code> (per-currency array supported), optional <code>use_discount_amount</code> to check against post-discount subtotal.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">In-store pickup / collection</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>Drivers\ShippingMethods\Collection::resolve()</code> — zero-price option, flagged <code>collect: true</code> on the <code>ShippingOption</code>. Single implicit "store" — no concept of which location, no per-location stock or hours.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Per-product shipping exclusions by zone</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ShippingExclusionList</code> + <code>ShippingZone::shippingExclusions()</code> — every driver checks it before resolving and returns <code>null</code> if any cart line's product is excluded from that zone.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Per-customer-group rate visibility</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ShippingMethod::customerGroups()</code> pivot carries <code>visible</code>, <code>enabled</code>, <code>starts_at</code>, <code>ends_at</code> — scheduling and audience-gating a rate is already modeled.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Filament admin UI for zones/methods/rates</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ShippingZoneResource</code>, <code>ShippingMethodResource</code>, <code>ShippingExclusionListResource</code> ship with the add-on — usable as soon as the Filament plugin is registered, which it is via <code>CorePlugin</code>.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Storefront checkout step to pick a rate</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No shipping views exist in 3dealer's <code>resources/views</code> beyond a passing mention in <code>components/footer.blade.php</code> — the whole backend above is unwired to any customer-facing UI.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">03</span>
+      <h2>Carrier integration</h2>
+    </div>
+    <p class="cat-note">Real carriers quoting and printing on Lunar's behalf, rather than merchant-defined flat/tiered rates.</p>
+
+    <div class="feature">
+      <div class="f-name">Real-time carrier rate shopping (USPS/UPS/FedEx/DHL)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No driver in <code>table-rate-shipping</code> calls an external carrier API — all four shipped drivers (<code>FlatRate</code>, <code>ShipBy</code>, <code>FreeShipping</code>, <code>Collection</code>) compute from local data. Shopify's <code>CarrierService</code> API is the model for this: shop sends weight/dims/destination, carrier returns live rates at checkout.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Product/variant weight &amp; dimensions for rating</div>
+      <span class="f-status partial">partial</span>
+      <div class="f-note"><code>ProductVariant</code> has <code>weight_value</code>/<code>weight_unit</code> (referenced in <code>ShipBy</code>'s weight tier and <code>docs/lunar.md</code>) but no length/width/height fields exist in core migrations — enough for weight-tier rating, not enough for carrier-grade dimensional/volumetric quotes.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Shipping label generation &amp; printing (staff-facing)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No label concept anywhere in core or the add-on. Shopify has this built in for US merchants (USPS/UPS labels from admin or mobile); WooCommerce/PrestaShop lean on Shippo/EasyPost-style apps.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Return / exchange label generation</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No returns concept exists in Lunar core at all — this sits behind both "labels" and "returns," neither of which exists yet.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Shipment tracking numbers on orders</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note"><code>OrderShippingZone</code> pivot table records which zone an order matched, but no field anywhere stores a carrier tracking number or shipment status.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">04</span>
+      <h2>Fulfillment logistics</h2>
+    </div>
+    <p class="cat-note">Where an order physically ships from, and whether it can ship from more than one place.</p>
+
+    <div class="feature">
+      <div class="f-name">Multi-warehouse / multi-location inventory</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No warehouse, location, or fulfillment-center model anywhere in <code>vendor/lunarphp/core</code> or <code>lunar</code> — stock is a flat quantity on the variant. WooCommerce needs Calcurates or WooCommerce Warehouses add-ons for this; it's genuinely not a Lunar concept at all.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Split shipment (one order, multiple packages/warehouses)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Downstream of multi-warehouse — with a single implicit stock pool, there's nothing to split by. <code>CreateShippingLine</code> writes exactly one shipping line per order.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Multiple pickup locations (choose a specific store)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">The <code>Collection</code> driver models pickup as a single yes/no rate per zone — no location entity to pick from, no per-location hours/capacity.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Local delivery (distinct from carrier shipping or pickup)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No radius/zone-based "we deliver it ourselves" driver — only <code>ShipBy</code>/<code>FlatRate</code> (carrier-agnostic priced shipping) and <code>Collection</code> (pickup) exist as concepts.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Delivery date / time-slot selection at checkout</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No date/time field on <code>ShippingOption</code>, <code>CartAddress</code>, or the order shipping line. WooCommerce needs a dedicated delivery-date-picker plugin for this too — not a gap unique to Lunar, but still open here.</div>
+    </div>
+  </section>
+
+  <section class="category">
+    <div class="cat-head">
+      <span class="cat-num">05</span>
+      <h2>International &amp; risk</h2>
+    </div>
+    <p class="cat-note">What happens when a shipment crosses a border, or something goes wrong in transit.</p>
+
+    <div class="feature">
+      <div class="f-name">Customs documentation / HS codes per product</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No HS-code or customs-description field found on <code>Product</code>/<code>ProductVariant</code> migrations. Every international shipment needs one per line item to clear customs — researched requirement, not yet modeled anywhere in Lunar.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Duties/taxes collected at checkout (DDP)</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">Lunar's <code>CalculateTax</code> pipeline step handles sales tax/VAT on the cart itself, not import duty estimation for cross-border orders. DDP vs. DDU is the standard framing (seller-collects-upfront vs. customer-pays-on-delivery) — neither is modeled.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Country/zone-restricted shipping</div>
+      <span class="f-status have">have</span>
+      <div class="f-note"><code>ShippingZone</code> type <code>countries</code>/<code>states</code>/<code>postcodes</code> already scopes which rates apply where — the building block international shipping would sit on top of.</div>
+    </div>
+
+    <div class="feature">
+      <div class="f-name">Shipping insurance / package protection at checkout</div>
+      <span class="f-status missing">missing</span>
+      <div class="f-note">No insurance line-item concept in core. On Shopify this is exclusively third-party (ShipInsure, Route, Simply Shipping Protection) — not a platform-native feature there either, so the gap is normal, not distinctive.</div>
+    </div>
+  </section>
+
+  <footer class="page">
+    <span>Compiled 2026-08-28 — inline citations from <code>vendor/lunarphp/core</code> and <code>vendor/lunarphp/table-rate-shipping</code> source are direct reads; DDP/DDU, carrier-API, label, and warehouse claims are sourced from web research on Shopify/WooCommerce/PrestaShop, marked accordingly by context.</span>
+    <span>boboko-core / docs</span>
+  </footer>
+
+</div>

docs/shopify-import.md

@@ -2,6 +2,9 @@
 
 Findings from comparing a real Shopify product export CSV against Lunar's schema (`vendor/lunarphp/core`), plus the resulting implementation plan for `MigrateImport\Shopify\ShopifyExportImporter`.
 
+Need to discard everything and re-import from scratch (e.g. after a schema/indexer change that
+only applies to newly-created rows)? See `docs/shopify-reimport.md`.
+
 ## Idempotency problem
 
 Nothing in Lunar tracks "this record came from external system X, ID Y." Re-running an import with no external-ID tracking would duplicate every product on each run.

docs/shopify-reimport.md

@@ -0,0 +1,149 @@
+# Wiping products before a clean Shopify re-import
+
+A runbook for discarding every imported product (and everything that hangs off one —
+variants, prices, media, reviews, options/values, the Meilisearch documents) and re-running
+`ShopifyExportImporter` from scratch. Useful after a schema/indexer change that only applies to
+newly-created rows (see "Why a wipe, not an update" below), or when the export CSV itself changed
+enough that stale products need to go, not just be updated in place.
+
+Every command below is a `tinker --execute=` one-liner run inside the app container — adjust the
+exec prefix (`./bin/dc-core.sh exec app ...`, `docker compose exec app ...`, etc.) for your setup.
+
+---
+
+## Why a wipe, not an update
+
+`ShopifyExportImporter`'s resolvers are mostly `firstOrCreate` — re-running the importer against
+an *existing* database updates matched rows but leaves already-created ones exactly as they were.
+That's the right behavior for routine re-imports (an updated price, a new variant), but it means a
+change to what gets set **at creation time only** — e.g. `ProductOptionResolver` now also setting
+`label`, not just `name`, on a `ProductOption` — never reaches a `ProductOption` row that already
+exists. A wipe forces every row to go through creation again, picking up such fixes.
+
+---
+
+## 1. Delete every product
+
+Cascades to `ProductVariant`, prices, and Spatie media rows — verified live (see
+`shopify-import.md`'s own history/commit log for context). Also removes each product's Meilisearch
+document automatically, via Scout's own delete hook fired on `forceDelete()` — no separate
+`scout:flush` needed.
+
+```php
+\Lunar\Models\Product::withTrashed()->get()->each->forceDelete();
+```
+
+**Let this run to completion.** Interrupting it mid-loop (e.g. Ctrl+C on the tinker session) stops
+after whichever product it was on, leaving the rest undeleted — safe to just re-run the same
+command again afterward, since already-deleted products are simply skipped.
+
+Verify:
+
+```php
+\Lunar\Models\Product::withTrashed()->count(); // 0
+```
+
+### Requires: `product_reviews.product_id` cascades on delete
+
+`product_reviews` (boboko-core's own table, not Lunar's) originally had no `ON DELETE` clause on
+its `product_id` foreign key — deleting a reviewed product threw a constraint violation instead of
+the review going with it. Fixed by
+`database/migrations/2026_09_03_000001_add_cascade_delete_to_product_reviews_product_id.php`. Make
+sure this migration has actually run (`php artisan migrate`) before step 1, or a product with
+reviews will fail to delete.
+
+---
+
+## 2. Delete product options and values
+
+Not touched by step 1 (`ProductOption`/`ProductOptionValue` aren't scoped to one product — they're
+shared across the catalog, per `ProductOptionResolver::resolveOption()`'s `shared: true`). Safe to
+delete in full once every product (and therefore every variant referencing an option value via the
+`product_option_value_product_variant` pivot) is gone — deleting values while variants still
+reference them throws the same kind of FK violation step 1 guards against.
+
+```php
+\Lunar\Models\ProductOptionValue::query()->delete();
+\Lunar\Models\ProductOption::query()->delete();
+```
+
+Verify:
+
+```php
+\Lunar\Models\ProductOption::count();      // 0
+\Lunar\Models\ProductOptionValue::count(); // 0
+```
+
+---
+
+## 3. Clear the import mappings
+
+Without this, the importer's `ImportMapping::resolve(...)` calls still find the (now-deleted)
+mappings' rows absent, so this step is really about not leaving stale mapping rows pointing at
+nothing — `ImportMapping` rows aren't foreign-keyed to the models they map (`morphTo`, no
+constraint), so leaving them wouldn't break the re-import, but a stale mapping for a product that
+no longer exists is dead weight.
+
+```php
+\Modules\Core\MigrateImport\Models\ImportMapping::where('source', 'shopify')->delete();
+```
+
+Verify:
+
+```php
+\Modules\Core\MigrateImport\Models\ImportMapping::where('source', 'shopify')->count(); // 0
+```
+
+---
+
+## 4. Re-run the importer
+
+`boboko:migrate:import` dispatches `RunMigrateImportJob` onto the queue — **not synchronous** —
+so a queue worker must actually be running (`php artisan queue:work`, or your dev queue container)
+or the job just sits queued.
+
+```bash
+php artisan boboko:migrate:import --source=shopify --type=export --file=<absolute path to the CSV>
+```
+
+The `--file` value must be an **absolute path** inside the container (e.g.
+`/var/www/html/storage/app/private/imports/shopify/products_export.csv`) when running
+non-interactively — a path relative to `storage/app/private/imports` only resolves correctly when
+the command can fall back to its interactive prompt, which isn't available in a scripted/non-TTY
+run.
+
+Watch the queue worker's own log output for `FAIL` entries (see `docs/lunar.md` or your compose
+setup for how logs are routed to `docker compose logs`) — a clean run shows every
+`Laravel\Scout\Jobs\MakeSearchable` / `Spatie\MediaLibrary\Conversions\Jobs\PerformConversionsJob`
+line ending `DONE`, never `FAIL`.
+
+---
+
+## 5. Re-sync Meilisearch and reindex
+
+```bash
+php artisan lunar:meilisearch:setup
+php artisan lunar:meilisearch:tune-product-search
+php artisan lunar:search:index "Lunar\Models\Product" --refresh
+```
+
+`--refresh` re-syncs filterable/sortable index settings *and* reindexes every document — it does
+not reset `typoTolerance`/`prefixSearch` (confirmed live: both survived a `--refresh` run
+unchanged), so `tune-product-search` only needs re-running here for completeness/if it hadn't
+already been applied, not because `--refresh` would have clobbered it.
+
+---
+
+## Verifying the result
+
+```php
+// Product count should match the CSV's actual unique `Handle` count, not
+// whatever the database held before the wipe — those aren't the same number
+// if stale/manually-added products existed alongside the CSV-sourced ones.
+\Lunar\Models\Product::count();
+
+// Spot-check that at least one variant picked up its own image (see
+// shopify-import.md's "Images" section) — 0 is only correct if the CSV
+// genuinely has no `Variant Image` values populated.
+\Lunar\Models\ProductVariant::has('images')->count();
+```

lang/el/countries.php

@@ -0,0 +1,21 @@
+<?php
+
+/**
+ * Greek translations for Lunar\Models\Country::name, keyed by the exact
+ * English spelling Lunar's own installer seeds (`lunar:import:address-data`
+ * fetches http://data.lunarphp.io/countries+states.json — see
+ * vendor/lunarphp/core/src/Console/Commands/Import/AddressData.php).
+ * `Country`/`State` have no i18n support of their own (plain string
+ * columns, no translatable trait) — this is a plain Laravel lang file, not
+ * Modules\Core\Localization's DB-backed TranslationService, since these
+ * names are fixed reference data seeded once, not editable UI copy (see
+ * docs/localization.md). A consuming app's storefront looks this up
+ * itself, e.g. __('core::countries.'.$country->name) — core has no
+ * storefront UI of its own to wire this into (see docs/lunar.md).
+ *
+ * Only Greece is covered — this store operates within Greece; add further
+ * countries here as needed.
+ */
+return [
+    'Greece' => 'Ελλάδα',
+];

lang/el/states.php

@@ -0,0 +1,52 @@
+<?php
+
+/**
+ * Greek translations for Lunar\Models\State::name, keyed by the exact
+ * English spelling Lunar's own installer seeds for Greece
+ * (`lunar:import:address-data` — see lang/el/countries.php's own docblock
+ * for the full explanation of why this is a plain lang file, not
+ * Modules\Core\Localization's TranslationService).
+ *
+ * Covers every Greek state/regional-unit row in Lunar's seed dataset —
+ * scoped to Greece only, matching this store's operating country.
+ */
+return [
+    'Achaea Regional Unit' => 'Περιφερειακή Ενότητα Αχαΐας',
+    'Aetolia-Acarnania Regional Unit' => 'Περιφερειακή Ενότητα Αιτωλοακαρνανίας',
+    'Arcadia Prefecture' => 'Νομός Αρκαδίας',
+    'Argolis Regional Unit' => 'Περιφερειακή Ενότητα Αργολίδας',
+    'Attica Region' => 'Περιφέρεια Αττικής',
+    'Boeotia Regional Unit' => 'Περιφερειακή Ενότητα Βοιωτίας',
+    'Central Greece Region' => 'Περιφέρεια Στερεάς Ελλάδας',
+    'Central Macedonia' => 'Κεντρική Μακεδονία',
+    'Chania Regional Unit' => 'Περιφερειακή Ενότητα Χανίων',
+    'Corfu Prefecture' => 'Νομός Κέρκυρας',
+    'Corinthia Regional Unit' => 'Περιφερειακή Ενότητα Κορινθίας',
+    'Crete Region' => 'Περιφέρεια Κρήτης',
+    'Drama Regional Unit' => 'Περιφερειακή Ενότητα Δράμας',
+    'East Attica Regional Unit' => 'Περιφερειακή Ενότητα Ανατολικής Αττικής',
+    'East Macedonia and Thrace' => 'Ανατολική Μακεδονία και Θράκη',
+    'Epirus Region' => 'Περιφέρεια Ηπείρου',
+    'Euboea' => 'Εύβοια',
+    'Grevena Prefecture' => 'Νομός Γρεβενών',
+    'Imathia Regional Unit' => 'Περιφερειακή Ενότητα Ημαθίας',
+    'Ioannina Regional Unit' => 'Περιφερειακή Ενότητα Ιωαννίνων',
+    'Ionian Islands Region' => 'Περιφέρεια Ιονίων Νήσων',
+    'Karditsa Regional Unit' => 'Περιφερειακή Ενότητα Καρδίτσας',
+    'Kastoria Regional Unit' => 'Περιφερειακή Ενότητα Καστοριάς',
+    'Kefalonia Prefecture' => 'Νομός Κεφαλληνίας',
+    'Kilkis Regional Unit' => 'Περιφερειακή Ενότητα Κιλκίς',
+    'Kozani Prefecture' => 'Νομός Κοζάνης',
+    'Laconia' => 'Λακωνία',
+    'Larissa Prefecture' => 'Νομός Λάρισας',
+    'Lefkada Regional Unit' => 'Περιφερειακή Ενότητα Λευκάδας',
+    'Pella Regional Unit' => 'Περιφερειακή Ενότητα Πέλλας',
+    'Peloponnese Region' => 'Περιφέρεια Πελοποννήσου',
+    'Phthiotis Prefecture' => 'Νομός Φθιώτιδας',
+    'Preveza Prefecture' => 'Νομός Πρέβεζας',
+    'Serres Prefecture' => 'Νομός Σερρών',
+    'South Aegean' => 'Νότιο Αιγαίο',
+    'Thessaloniki Regional Unit' => 'Περιφερειακή Ενότητα Θεσσαλονίκης',
+    'West Greece Region' => 'Περιφέρεια Δυτικής Ελλάδας',
+    'West Macedonia Region' => 'Περιφέρεια Δυτικής Μακεδονίας',
+];

resources/views/auth/filament/pages/login.blade.php

@@ -2,7 +2,7 @@
 
     @if (! $otpSent)
         <form wire:submit="requestOtp">
-            <div class="grid gap-y-4">
+            <div style="display: flex; flex-direction: column; row-gap: 1rem;">
                 <x-filament::input.wrapper>
                     <x-filament::input
                         type="email"
@@ -24,7 +24,7 @@
         </form>
     @else
         <form wire:submit="authenticate">
-            <div class="grid gap-y-4">
+            <div style="display: flex; flex-direction: column; row-gap: 1rem;">
                 <p class="text-sm text-gray-500">
                     A login code was sent to <strong>{{ $email }}</strong>.
                 </p>

resources/views/auth/mail/otp.blade.php

@@ -1,5 +1,5 @@
 <p>Hi {{ $name }},</p>
 
-<p>Your login code is:</p>
+<p>{{ $intro }}</p>
 
 <p style="font-size: 2rem; font-weight: bold; letter-spacing: 0.25rem;">{{ $code }}</p>

resources/views/order/infolists/transaction.blade.php

@@ -0,0 +1,127 @@
+@php
+    $transaction = $getRecord();
+    $notes = $transaction->notes ?: ($transaction->meta['notes'] ?? null);
+@endphp
+
+@once
+    @php
+        $renderPaymentIcons();
+    @endphp
+@endonce
+<div
+    @class([
+        'text-sm rounded-lg shadow-md border dark:bg-gray-900',
+        'text-gray-950 dark:text-white',
+        match($transaction->type){
+            'refund' => 'border-orange-300',
+            'intent' => 'border-sky-300',
+            'capture' => 'border-green-300',
+            default => 'border-gray-300',
+        },
+        '!border-red-500 bg-red-50' => !$transaction->success,
+        'bg-gray-50' => $transaction->success,
+    ])
+>
+    <div class="p-2 space-y-2">
+        <div class="px-4 py-2 rounded text-xs bg-white dark:bg-gray-800 shadow text-gray-600 dark:text-gray-400 ring-1 ring-gray-100 dark:ring-gray-700">
+            <span>{{ $transaction->driver }}</span> //
+            <span>{{ $transaction->reference }}</span>
+        </div>
+
+        <div class="flex items-center justify-between p-4 bg-white dark:bg-gray-800 rounded shadow ring-1 ring-gray-100 dark:ring-gray-700">
+            <div class="flex items-center gap-6">
+                <div>
+                    <strong class="text-xs">
+                        {{ $transaction->status }}
+                    </strong>
+                </div>
+
+                <div>
+                    <svg viewBox="0 0 50 50" class="w-10">
+                        <use xlink:href="#{{ strtolower($transaction->card_type) }}"></use>
+                    </svg>
+                </div>
+
+                @if($transaction->last_four)
+                    <p class="text-sm">
+                        <span class="inline-block -translate-y-px">
+                            &lowast;&lowast;&lowast;&lowast; &lowast;&lowast;&lowast;&lowast; &lowast;&lowast;&lowast;&lowast;
+                        </span>
+
+                        <span class="font-medium">
+                            {{ (string) $transaction->last_four }}
+                        </span>
+                    </p>
+                @endif
+            </div>
+
+            <strong
+                @class([
+                    "text-sm",
+                    'text-red-500' => !$transaction->success,
+                    match($transaction->type){
+                        'refund' => "text-orange-500",
+                        default => "text-gray-900 dark:text-gray-100",
+                    },
+                ])
+            >
+                @if($transaction->type == 'refund')-@endif{{ $transaction->amount->formatted }}
+            </strong>
+        </div>
+
+        <div class="px-4 py-2 bg-white dark:bg-gray-800 shadow rounded flex items-center justify-between text-gray-600 dark:text-gray-400 ring-1 ring-gray-100 dark:ring-gray-700">
+            <div class="text-xs flex items-center gap-2">
+                <div>
+                    <x-filament::icon
+                        icon="heroicon-o-clock"
+                        class="w-4"
+                    />
+                </div>
+                <span>{{ $transaction->created_at->format('jS F Y h:ia') }}</span>
+            </div>
+
+            <div class="flex space-x-2">
+            @foreach($transaction->paymentChecks() as $check)
+                    <x-filament::badge
+                        :icon="$check->successful ? 'heroicon-m-check' : 'heroicon-m-x-mark'"
+                        :color="$check->successful ?  \Filament\Support\Colors\Color::Sky : 'gray'"
+                    >
+                        {{ $check->label }}: {{ $check->message }}
+                    </x-filament::badge>
+            @endforeach
+            </div>
+        </div>
+
+        @if($notes)
+            <div class="px-4 py-2 bg-white dark:bg-gray-800 shadow flex items-center rounded gap-2 ring-1 ring-gray-100 dark:ring-gray-700">
+                <div>
+                    <x-filament::icon
+                        icon="heroicon-o-chat-bubble-oval-left-ellipsis"
+                        class="w-4"
+                    />
+                </div>
+
+                <p class="text-sm">{{ $notes }}</p>
+            </div>
+        @endif
+    </div>
+
+    <div
+        @class([
+            "bottom-0 left-0 block w-full text-center rounded-b-lg border-t text-xs py-1",
+            "!bg-red-50 !dark:bg-red-400/10 !border-red-300 !text-red-600 !dark:text-red-400" => !$transaction->success,
+            match($transaction->type){
+                'refund' => "bg-orange-50 dark:bg-orange-400/10 border-orange-300 text-orange-600 dark:text-orange-400",
+                'intent' => "bg-sky-50 dark:bg-sky-400/10 border-sky-300 text-sky-600 dark:text-sky-400",
+                'capture' => "bg-green-50 dark:bg-green-400/10 border-green-300 text-green-600 dark:text-green-400",
+                default => "bg-gray-50 dark:bg-gray-400/10 border-gray-300 text-gray-600 dark:text-gray-400",
+            },
+        ])
+    >
+        @if(!$transaction->success)
+            {{ __('lunarpanel::order.transactions.failed') }}
+        @else
+            {{ __('lunarpanel::order.transactions.'.$transaction->type) }}
+        @endif
+    </div>
+</div>

resources/views/order/notifications/captured.blade.php

@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>Payment of <strong>{{ $amount }}</strong> for your order <strong>{{ $reference }}</strong> has been captured.</p>

resources/views/order/notifications/completed.blade.php

@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>Your order <strong>{{ $reference }}</strong> is complete. Thanks for shopping with us!</p>

resources/views/order/notifications/delivered.blade.php

@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>Good news — your order <strong>{{ $reference }}</strong> has been delivered.</p>

resources/views/order/notifications/dispatched.blade.php

@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>Your order <strong>{{ $reference }}</strong> is on its way.</p>

resources/views/order/notifications/pickup-ready.blade.php

@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>Your order <strong>{{ $reference }}</strong> is ready for pickup in store.</p>

resources/views/order/notifications/placed.blade.php

@@ -0,0 +1,11 @@
+<p>Hi,</p>
+
+<p>Thanks for your order! Your order <strong>{{ $reference }}</strong> is confirmed.</p>
+
+<ul>
+    @foreach ($lines as $line)
+        <li>{{ $line->quantity }} &times; {{ $line->description }} — {{ $line->total?->formatted }}</li>
+    @endforeach
+</ul>
+
+<p>Total: <strong>{{ $total }}</strong></p>

resources/views/order/notifications/refunded.blade.php

@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>A refund of <strong>{{ $amount }}</strong> has been issued for your order <strong>{{ $reference }}</strong>.</p>

resources/views/order/notifications/status-updated.blade.php

@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>Your order <strong>{{ $reference }}</strong> is now: <strong>{{ $statusLabel }}</strong></p>

src/Auth/Events/UserAuthenticated.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Modules\Core\Auth\Events;
+
+use Illuminate\Contracts\Auth\Authenticatable;
+use Lunar\Base\LunarUser;
+
+/**
+ * Dispatched by UserOtpService::validate() on every successful OTP login, not just
+ * a first-time one. Modules\Core\Privacy listens on this to auto-cancel a pending
+ * DataErasureRequest — logging back in during the grace period is the "I changed
+ * my mind" action (see Modules\Core\Privacy\Listeners\CancelErasureOnLoginListener),
+ * which needs $user->customers to resolve any pending request. Typed as
+ * Authenticatable&LunarUser rather than plain Authenticatable (unlike the sibling
+ * UserCreated event) specifically because that listener depends on it — every real
+ * User in this codebase implements LunarUser (see docs/lunar.md "LunarUser trait"),
+ * and User is the only Authenticatable entity in this project (Customer is not —
+ * see docs/modules.md "Customer/User Pairing").
+ */
+class UserAuthenticated
+{
+    public function __construct(
+        public readonly Authenticatable&LunarUser $user,
+    ) {}
+}

src/Auth/Exceptions/OtpThrottledException.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Modules\Core\Auth\Exceptions;
+
+use RuntimeException;
+
+/**
+ * Thrown by Modules\Core\Auth\Services\UserOtpService::generateAndSend()
+ * when an email has requested too many codes too quickly — caps both
+ * mail-bombing one inbox and the "just request a fresh code to reset my
+ * guess count" loophole a per-code attempt cap alone doesn't close.
+ */
+class OtpThrottledException extends RuntimeException
+{
+    public function __construct(
+        public readonly int $availableInSeconds,
+    ) {
+        parent::__construct("Too many code requests. Try again in {$availableInSeconds} second(s).");
+    }
+}

src/Auth/Extensions/StaffResourceExtension.php

@@ -2,18 +2,18 @@
 
 namespace Modules\Core\Auth\Extensions;
 
-use Filament\Forms\Form;
+use Filament\Schemas\Schema;
 use Lunar\Admin\Support\Extending\ResourceExtension;
 
 class StaffResourceExtension extends ResourceExtension
 {
-    public function extendForm(Form $form): Form
+    public function extendForm(Schema $form): Schema
     {
         $schema = collect($form->getComponents())
             ->reject(fn ($component) => method_exists($component, 'getName') && $component->getName() == 'password')
             ->values()
             ->all();
 
-        return $form->schema($schema);
+        return $form->components($schema);
     }
 }

src/Auth/Filament/Pages/Login.php

@@ -15,7 +15,7 @@ class Login extends SimplePage
 {
     use WithRateLimiting;
 
-    protected static string $view = 'core::auth.filament.pages.login';
+    protected string $view = 'core::auth.filament.pages.login';
 
     public ?string $email = '';
     public ?string $otp = '';
@@ -78,7 +78,7 @@ class Login extends SimplePage
             ]);
         }
 
-        if ($staff instanceof FilamentUser && !$staff->canAccessPanel(Filament::getCurrentPanel())) {
+        if ($staff instanceof FilamentUser && !$staff->canAccessPanel(Filament::getCurrentOrDefaultPanel())) {
             throw ValidationException::withMessages([
                 'email' => 'You do not have access to this panel.',
             ]);

src/Auth/Http/Middleware/EnsureSessionNotRevoked.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Modules\Core\Auth\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+use Modules\Core\Auth\Services\UserSessionService;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * The enforcement half of the session registry — see
+ * Modules\Core\Auth\Services\UserSessionService's own docblock. Not
+ * auto-registered anywhere (no routes/kernel wiring exist in this
+ * package — see Modules\Core\Customer\Services\CustomerAccountService's
+ * own docblock for why this branch stops at services); a consuming app
+ * adds this to its `web` middleware group (after `auth`) to actually get
+ * "logout everywhere" enforcement.
+ *
+ * A request with no recorded UserSession at all (see
+ * UserSessionService::currentSession()'s own docblock) is let through —
+ * only an EXPLICITLY revoked session is rejected.
+ */
+class EnsureSessionNotRevoked
+{
+    public function __construct(
+        private readonly UserSessionService $sessions,
+    ) {}
+
+    public function handle(Request $request, Closure $next): Response
+    {
+        if (! Auth::check()) {
+            return $next($request);
+        }
+
+        $session = $this->sessions->currentSession();
+
+        if ($session && $session->isRevoked()) {
+            Auth::logout();
+            $request->session()->invalidate();
+            $request->session()->regenerateToken();
+
+            abort(401, 'Your session has been revoked. Please log in again.');
+        }
+
+        $session?->update(['last_used_at' => now()]);
+
+        return $next($request);
+    }
+}

src/Auth/Mail/OtpMail.php

@@ -6,20 +6,47 @@ use Illuminate\Mail\Mailable;
 use Illuminate\Mail\Mailables\Content;
 use Illuminate\Mail\Mailables\Envelope;
 
+/**
+ * The one OTP email template for every use of Auth\Services\OtpService —
+ * not just admin login. A code confirming a destructive Artisan command
+ * (e.g. Command\WipeCatalogCommand) reuses the exact same generation/
+ * validation mechanism as login, but "Your login code" as the subject
+ * would be actively misleading for that — the recipient never initiated a
+ * login. $purpose is a small, fixed set of known keys (see
+ * COPY_BY_PURPOSE), not free text — a typo'd/unknown purpose falls back
+ * to 'login' rather than rendering a blank subject/intro.
+ */
 class OtpMail extends Mailable
 {
+    private const COPY_BY_PURPOSE = [
+        'login' => [
+            'subject' => 'Your login code',
+            'intro' => 'Your login code is:',
+        ],
+        'wipe-catalog' => [
+            'subject' => 'Confirm: Wipe Catalog',
+            'intro' => 'Someone requested to permanently delete every product in the catalog. If this was you, enter this code to confirm:',
+        ],
+    ];
+
     public function __construct(
         public readonly string $name,
         public readonly string $code,
+        public readonly string $purpose = 'login',
     ) {}
 
     public function envelope(): Envelope
     {
-        return new Envelope(subject: 'Your login code');
+        return new Envelope(subject: $this->copy()['subject']);
     }
 
     public function content(): Content
     {
-        return new Content(view: 'core::auth.mail.otp');
+        return new Content(view: 'core::auth.mail.otp', with: ['intro' => $this->copy()['intro']]);
+    }
+
+    private function copy(): array
+    {
+        return self::COPY_BY_PURPOSE[$this->purpose] ?? self::COPY_BY_PURPOSE['login'];
     }
 }

src/Auth/Models/UserSession.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Modules\Core\Auth\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * One row per login (see Modules\Core\Auth\Services\UserOtpService::
+ * validate()) — see that table's own migration docblock for why this
+ * exists independent of the actual session-store driver.
+ */
+class UserSession extends Model
+{
+    protected $guarded = [];
+
+    protected $casts = [
+        'last_used_at' => 'datetime',
+        'revoked_at' => 'datetime',
+    ];
+
+    public function user(): BelongsTo
+    {
+        $model = config('auth.providers.users.model');
+
+        return $this->belongsTo($model);
+    }
+
+    public function isRevoked(): bool
+    {
+        return $this->revoked_at !== null;
+    }
+}

src/Auth/Privacy/UserSessionDataProvider.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Modules\Core\Auth\Privacy;
+
+use Modules\Core\Auth\Models\UserSession;
+use Modules\Core\Privacy\Contracts\PersonalDataProvider;
+use Modules\Core\Privacy\DTOs\CustomerSubject;
+use Modules\Core\Privacy\Enums\ErasureOutcome;
+use Modules\Core\Privacy\DTOs\ProviderErasureResult;
+use Modules\Core\Privacy\DTOs\ProviderExportResult;
+use Modules\Core\Privacy\DTOs\UserSubject;
+
+/**
+ * Login-session device/location metadata (user_sessions) — ip_address and
+ * user_agent are device/location fingerprinting data tied 1:1 to a User via
+ * user_id, never to a Customer (business account), so this is User-scope
+ * only. No legal retention requirement applies to session metadata the way
+ * it does to Order (there's no tax/accounting reason to keep old login IPs
+ * around), so rows are deleted outright rather than pseudonymized.
+ *
+ * A hard delete here is safe regardless of whether the User row itself has
+ * already been erased — CustomerDataProvider::eraseForUser() nulls the
+ * User's own name/email but never touches user_sessions, and the table's
+ * own user_id FK is cascadeOnDelete() only if the User row itself were
+ * hard-deleted, which it never is (erasure here means "identity nulled,"
+ * not "row removed" — see docs/modules.md "Customer/User Pairing").
+ */
+class UserSessionDataProvider implements PersonalDataProvider
+{
+    public function name(): string
+    {
+        return 'sessions';
+    }
+
+    public function exportForCustomer(CustomerSubject $subject): ProviderExportResult
+    {
+        return new ProviderExportResult('sessions', []);
+    }
+
+    public function exportForUser(UserSubject $subject): ProviderExportResult
+    {
+        $sessions = UserSession::where('user_id', $subject->userId)->get();
+
+        return new ProviderExportResult('sessions', $sessions->map(fn (UserSession $session) => [
+            'id' => $session->id,
+            'ip_address' => $session->ip_address,
+            'user_agent' => $session->user_agent,
+            'last_used_at' => $session->last_used_at?->toIso8601String(),
+            'revoked_at' => $session->revoked_at?->toIso8601String(),
+        ])->all());
+    }
+
+    public function eraseForCustomer(CustomerSubject $subject): ProviderErasureResult
+    {
+        return new ProviderErasureResult('sessions', ErasureOutcome::Skipped, 'Login sessions belong to individual Users, not Customer accounts.');
+    }
+
+    public function eraseForUser(UserSubject $subject): ProviderErasureResult
+    {
+        $deleted = UserSession::where('user_id', $subject->userId)->delete();
+
+        if ($deleted === 0) {
+            return new ProviderErasureResult('sessions', ErasureOutcome::Skipped, 'No login sessions for this user.');
+        }
+
+        return new ProviderErasureResult('sessions', ErasureOutcome::Erased);
+    }
+}

src/Auth/Services/OtpService.php

@@ -11,7 +11,13 @@ class OtpService
     private const EXPIRY_MINUTES = 10;
     private const CODE_LENGTH = 6;
 
-    public function generateAndSend(string $email): bool
+    /**
+     * $purpose is forwarded as-is to OtpMail, which only recognizes a
+     * fixed set of keys (see its own COPY_BY_PURPOSE) — an unrecognized
+     * value there just falls back to 'login' rather than failing here, so
+     * this method has nothing of its own to validate.
+     */
+    public function generateAndSend(string $email, string $purpose = 'login'): bool
     {
         $staff = Staff::where('email', $email)->first();
 
@@ -25,7 +31,7 @@ class OtpService
         $staff->otp_expires_at = now()->addMinutes(self::EXPIRY_MINUTES);
         $staff->save();
 
-        Mail::to($staff->email)->send(new OtpMail($staff->first_name, $code));
+        Mail::to($staff->email)->send(new OtpMail($staff->first_name, $code, $purpose));
 
         return true;
     }

src/Auth/Services/UserOtpService.php

@@ -2,23 +2,97 @@
 
 namespace Modules\Core\Auth\Services;
 
+use Illuminate\Contracts\Auth\Authenticatable;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Event;
 use Illuminate\Support\Facades\Mail;
+use Illuminate\Support\Facades\RateLimiter;
+use Modules\Core\Auth\Events\UserAuthenticated;
+use Modules\Core\Auth\Events\UserCreated;
+use Modules\Core\Auth\Exceptions\OtpThrottledException;
 use Modules\Core\Auth\Mail\UserOtpMail;
 
+/**
+ * The storefront's passwordless login — a shopper supplies only an email
+ * (Shopify-style), gets a 6-digit code, and validate() authenticates the
+ * `web` guard via Auth::login().
+ *
+ * That alone is enough to merge/associate any active guest cart into the
+ * now-known customer — Auth::login() fires Illuminate\Auth\Events\Login,
+ * which Lunar's own Lunar\Listeners\CartSessionAuthListener (registered
+ * unconditionally in LunarServiceProvider::boot(), no opt-in needed)
+ * already listens to, calling CartSession::associate() with
+ * config('lunar.cart.auth_policy') — 'merge' by default, 'override' if a
+ * consumer changes that config. Deliberately no cart-association call
+ * here: doing our own on top would run a SECOND merge attempt with a
+ * hardcoded policy that ignores whatever the consumer configured.
+ *
+ * generateAndSend()'s find-or-create already triggers the full
+ * Customer/User pairing cascade for a genuinely new email — see
+ * Modules\Core\Auth\Events\UserCreated's own docblock and
+ * Modules\Core\Customer\Listeners\CreateCustomerForUser.
+ *
+ * Two independent throttles, both configured under core.auth.otp — see
+ * config/core.php's own comment for why they're separate: max_attempts
+ * caps wrong guesses against ONE code; generation_limit caps how often a
+ * NEW code can be requested for the same email at all (closes both the
+ * "regenerate to reset my guess count" loophole and mail-bombing one
+ * inbox).
+ *
+ * validate() also records a UserSessionService entry for the new login —
+ * see that class's own docblock for the "logout everywhere" registry
+ * this feeds (Modules\Core\Auth\Http\Middleware\EnsureSessionNotRevoked
+ * is the enforcement half; a consuming app must add it to its own
+ * middleware stack). $request is optional purely so this service stays
+ * callable from a context with no HTTP request at all (a console
+ * command, a test) — user-agent/ip are simply not recorded when omitted.
+ */
 class UserOtpService
 {
     private const EXPIRY_MINUTES = 10;
     private const CODE_LENGTH = 6;
 
+    public function __construct(
+        private readonly UserSessionService $sessions,
+    ) {}
+
+    /**
+     * @throws OtpThrottledException if this email has requested too many
+     *   codes within core.auth.otp.generation_decay_minutes
+     */
     public function generateAndSend(string $email): bool
     {
+        $limiterKey = $this->generationLimiterKey($email);
+        $maxGenerations = (int) config('core.auth.otp.generation_limit', 3);
+
+        if (RateLimiter::tooManyAttempts($limiterKey, $maxGenerations)) {
+            throw new OtpThrottledException(RateLimiter::availableIn($limiterKey));
+        }
+
+        RateLimiter::hit($limiterKey, (int) config('core.auth.otp.generation_decay_minutes', 10) * 60);
+
         $model = config('auth.providers.users.model');
         $user = $model::firstOrCreate(['email' => $email]);
 
+        // wasRecentlyCreated is Eloquent's own "did firstOrCreate() just
+        // INSERT, or did it find an existing row" flag — the only reliable
+        // way to tell them apart from firstOrCreate()'s return value alone.
+        // Without this check, a genuinely new signup never fired
+        // UserCreated at all (this class's own docblock claimed the
+        // Customer/User pairing cascade "already triggers" here, which was
+        // false as written — see Modules\Core\Customer\Listeners\
+        // CreateCustomerForUser, which depends entirely on this event).
+        if ($user->wasRecentlyCreated) {
+            Event::dispatch(new UserCreated($user));
+        }
+
         $code = str_pad((string) random_int(0, 999999), self::CODE_LENGTH, '0', STR_PAD_LEFT);
 
         $user->otp_code = $code;
         $user->otp_expires_at = now()->addMinutes(self::EXPIRY_MINUTES);
+        $user->otp_attempts = 0;
         $user->save();
 
         Mail::to($user->email)->send(new UserOtpMail($user->name ?? $user->email, $code));
@@ -26,23 +100,70 @@ class UserOtpService
         return true;
     }
 
-    public function validate(string $email, string $code)
+    /**
+     * A wrong code counts against core.auth.otp.max_attempts and, once
+     * reached, invalidates the code entirely — the shopper must request
+     * a fresh one via generateAndSend() (itself throttled independently
+     * — see this class's own docblock) rather than being able to keep
+     * guessing against a still-live code for the rest of its 10-minute
+     * expiry window.
+     */
+    public function validate(string $email, string $code, ?Request $request = null): ?Authenticatable
     {
         $model = config('auth.providers.users.model');
-        $user = $model::where('email', $email)->first();
 
-        if (! $user) {
+        // lockForUpdate() + a transaction make the read-check-increment-save
+        // below atomic across concurrent requests for the same user — without
+        // it, two guesses fired in parallel can each read the same
+        // pre-increment otp_attempts value and both save past
+        // max_attempts, letting an attacker exceed the lockout by
+        // parallelizing requests instead of sending them serially.
+        $result = DB::transaction(function () use ($model, $email, $code) {
+            $user = $model::where('email', $email)->lockForUpdate()->first();
+
+            if (! $user || ! $user->otp_expires_at || now()->isAfter($user->otp_expires_at)) {
+                return null;
+            }
+
+            if (! hash_equals((string) $user->otp_code, $code)) {
+                $user->otp_attempts++;
+
+                if ($user->otp_attempts >= (int) config('core.auth.otp.max_attempts', 5)) {
+                    $user->otp_code = null;
+                    $user->otp_expires_at = null;
+                    $user->otp_attempts = 0;
+                }
+
+                $user->save();
+
+                return null;
+            }
+
+            $user->otp_code = null;
+            $user->otp_expires_at = null;
+            $user->otp_attempts = 0;
+            $user->save();
+
+            return $user;
+        });
+
+        if (! $result) {
             return null;
         }
 
-        if (! $user->otp_expires_at || $user->otp_code != $code || now()->isAfter($user->otp_expires_at)) {
-            return null;
-        }
+        RateLimiter::clear($this->generationLimiterKey($email));
 
-        $user->otp_code = null;
-        $user->otp_expires_at = null;
-        $user->save();
+        Auth::login($result);
 
-        return $user;
+        $this->sessions->record($result, $request);
+
+        Event::dispatch(new UserAuthenticated($result));
+
+        return $result;
+    }
+
+    private function generationLimiterKey(string $email): string
+    {
+        return 'otp-generate:'.strtolower($email);
     }
 }

src/Auth/Services/UserSessionService.php

@@ -0,0 +1,105 @@
+<?php
+
+namespace Modules\Core\Auth\Services;
+
+use Illuminate\Contracts\Auth\Authenticatable;
+use Illuminate\Http\Request;
+use Illuminate\Support\Str;
+use Modules\Core\Auth\Models\UserSession;
+
+/**
+ * The record/revoke half of the session registry — see
+ * database/migrations/2026_09_15_000001_create_user_sessions_table.php's
+ * own docblock for why this exists (SESSION_DRIVER=redis in this app has
+ * no "sessions" table to purge by user_id). The enforcement half is
+ * Modules\Core\Auth\Http\Middleware\EnsureSessionNotRevoked, which reads
+ * the token this class stamps into the session payload.
+ */
+class UserSessionService
+{
+    private const SESSION_TOKEN_KEY = 'user_session_token';
+
+    /**
+     * Called once, right after Auth::login() succeeds (see
+     * UserOtpService::validate()) — generates a fresh token, records it,
+     * and stamps it into the CURRENT session payload so
+     * EnsureSessionNotRevoked can look it up on later requests.
+     */
+    public function record(Authenticatable $user, ?Request $request = null): UserSession
+    {
+        $token = Str::random(64);
+
+        $session = UserSession::create([
+            'user_id' => $user->getAuthIdentifier(),
+            'token' => $token,
+            'user_agent' => $request?->userAgent(),
+            'ip_address' => $request?->ip(),
+            'last_used_at' => now(),
+        ]);
+
+        session([self::SESSION_TOKEN_KEY => $token]);
+
+        return $session;
+    }
+
+    /**
+     * Revokes every OTHER active session for $user — the current one
+     * (matched by the token in the CURRENT session payload) is left
+     * alone, matching Laravel's own logoutOtherDevices() semantics
+     * (there just isn't a password to re-verify against here — this is a
+     * passwordless account, so revocation is simply "every row that
+     * isn't the one making this request").
+     *
+     * Known, deliberately accepted gap: this requires only a currently
+     * valid session, not a freshly-completed login — so anyone holding
+     * an already-authenticated session (e.g. someone who sits down at an
+     * account left logged in on a shared/public PC) can use this to
+     * evict the real owner's OTHER sessions just as easily as the real
+     * owner could use it to evict an intruder's. A stricter version would
+     * require a fresh OTP re-verification (e.g. within the last few
+     * minutes) before allowing this call. Left as-is for now — revisit if
+     * this turns out to matter in practice, rather than building
+     * abuse-resistance against a threat model nobody's confirmed is real
+     * for this storefront.
+     */
+    public function revokeOtherSessions(Authenticatable $user): int
+    {
+        $currentToken = session(self::SESSION_TOKEN_KEY);
+
+        return UserSession::query()
+            ->where('user_id', $user->getAuthIdentifier())
+            ->whereNull('revoked_at')
+            ->when($currentToken, fn ($query) => $query->where('token', '!=', $currentToken))
+            ->update(['revoked_at' => now()]);
+    }
+
+    /**
+     * Revokes EVERY session for $user, current one included — for a
+     * "this account may be compromised" response, not a routine logout.
+     */
+    public function revokeAllSessions(Authenticatable $user): int
+    {
+        return UserSession::query()
+            ->where('user_id', $user->getAuthIdentifier())
+            ->whereNull('revoked_at')
+            ->update(['revoked_at' => now()]);
+    }
+
+    /**
+     * @return UserSession|null null if the CURRENT session has no
+     *   recorded token at all (e.g. a session predating this feature, or
+     *   one Auth::login() established outside UserOtpService) — treated
+     *   as valid by EnsureSessionNotRevoked rather than rejected, since
+     *   there's nothing to have been revoked.
+     */
+    public function currentSession(): ?UserSession
+    {
+        $token = session(self::SESSION_TOKEN_KEY);
+
+        if (! $token) {
+            return null;
+        }
+
+        return UserSession::where('token', $token)->first();
+    }
+}

src/Cart/Commands/DetectAbandonedCarts.php

@@ -0,0 +1,89 @@
+<?php
+
+namespace Modules\Core\Cart\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Event;
+use Lunar\Models\Cart;
+use Modules\Core\Cart\Services\CartLifecycleService;
+use Modules\Core\Recovery\Events\CartAbandoned;
+use Modules\Core\Recovery\Events\CheckoutAbandoned;
+
+/**
+ * "Abandoned" is a derived state (Cart::updated_at older than
+ * config('core.cart.abandoned_after')) — nothing transitions a cart into it
+ * via a normal Eloquent write, so there's no model-event hook to dispatch
+ * CartAbandoned/CheckoutAbandoned from directly. This command is the only
+ * place that moment gets detected; run it on a schedule (see docs/cart.md).
+ *
+ * Splits Cart::scopeActive()'s two branches into their own events —
+ * see CartAbandoned/CheckoutAbandoned's docblocks for why they're distinct,
+ * not one combined "abandoned" state: a cart with no order at all is a much
+ * weaker purchase-intent signal than one with a draft order that was never
+ * placed.
+ *
+ * Deliberately does NOT write anything to Cart/Order — dispatch only. An
+ * earlier version recorded an "already notified" marker on Cart::meta/
+ * Order::meta, but that write bumped updated_at as an Eloquent side effect,
+ * which un-staled the very cart being marked abandoned (the same field
+ * abandonment staleness is computed from) — see docs/cart.md's former
+ * "Known bug" note. Cart/Checkout must have no way of writing abandonment
+ * state at all; every cart still matching the query below refires its event
+ * on every run until Recovery (not yet built — see
+ * docs/recovery-strategies.md) owns its own dedup/tracking table.
+ *
+ * Both queries require meta->recovery_consent = true — CartAbandoned/
+ * CheckoutAbandoned exist specifically to drive future recovery-email
+ * sends (Checkout\Services\CheckoutService::setRecoveryConsent() is where
+ * that consent is actually recorded), and a non-consenting cart's
+ * abandonment must never be dispatched at all, not merely filtered later
+ * at send time — see docs referenced above for the legal reasoning. This
+ * consent filter stays here rather than on Modules\Core\Cart\Services\
+ * CartLifecycleService, whose two "abandoned" queries this command builds
+ * on — dispatch eligibility is this command's own concern, not part of
+ * what "abandoned" means to a staff member browsing the admin panel. (The
+ * non-empty-lines requirement, by contrast, IS part of what "abandoned"
+ * means either way, so it lives on CartLifecycleService::abandonedCarts()
+ * itself, not here.)
+ */
+class DetectAbandonedCarts extends Command
+{
+    protected $signature = 'boboko:cart:detect-abandoned';
+
+    protected $description = 'Dispatch CartAbandoned/CheckoutAbandoned for carts that just crossed the abandonment threshold.';
+
+    public function handle(CartLifecycleService $lifecycle): void
+    {
+        $cartsAbandoned = 0;
+        $checkoutsAbandoned = 0;
+
+        $lifecycle->abandonedCarts(Cart::query())
+            ->where('meta->recovery_consent', true)
+            ->chunkById(200, function ($carts) use (&$cartsAbandoned) {
+                foreach ($carts as $cart) {
+                    Event::dispatch(new CartAbandoned($cart));
+
+                    $cartsAbandoned++;
+                }
+            });
+
+        $lifecycle->abandonedCheckouts(Cart::query())
+            ->where('meta->recovery_consent', true)
+            ->with(['orders' => fn ($query) => $query->whereNull('placed_at')])
+            ->chunkById(200, function ($carts) use (&$checkoutsAbandoned) {
+                foreach ($carts as $cart) {
+                    $order = $cart->orders->first();
+
+                    if ($order === null) {
+                        continue;
+                    }
+
+                    Event::dispatch(new CheckoutAbandoned($cart, $order));
+
+                    $checkoutsAbandoned++;
+                }
+            });
+
+        $this->components->info("Dispatched CartAbandoned for {$cartsAbandoned} cart(s), CheckoutAbandoned for {$checkoutsAbandoned} checkout(s).");
+    }
+}

src/Cart/Events/CartCleared.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Modules\Core\Cart\Events;
+
+use Lunar\Models\Cart;
+
+class CartCleared
+{
+    /**
+     * @param  array<int, array{id: int, purchasable_type: string, purchasable_id: int, quantity: int, meta: array}>  $lines
+     *   Snapshot of every line that was in the cart before clearing — Cart::clear()
+     *   deletes all rows directly, so nothing here can be fresh CartLine instances.
+     */
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly array $lines,
+    ) {}
+}

src/Cart/Events/CartCouponApplied.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Modules\Core\Cart\Events;
+
+use Lunar\Models\Cart;
+
+class CartCouponApplied
+{
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly string $code,
+    ) {}
+}

src/Cart/Events/CartCouponRemoved.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Modules\Core\Cart\Events;
+
+use Lunar\Models\Cart;
+
+class CartCouponRemoved
+{
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly string $code,
+    ) {}
+}

src/Cart/Events/CartLineAdded.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Modules\Core\Cart\Events;
+
+use Lunar\Models\Cart;
+use Lunar\Models\CartLine;
+
+class CartLineAdded
+{
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly CartLine $line,
+    ) {}
+}

src/Cart/Events/CartLineMovedToCart.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Modules\Core\Cart\Events;
+
+use Lunar\Models\Cart;
+use Lunar\Models\CartLine;
+
+/**
+ * The reverse of CartLineSaved — a previously saved-for-later line moved back
+ * into the purchasable cart (now counted in totals again).
+ */
+class CartLineMovedToCart
+{
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly CartLine $line,
+    ) {}
+}

src/Cart/Events/CartLineRemoved.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Modules\Core\Cart\Events;
+
+use Lunar\Models\Cart;
+
+class CartLineRemoved
+{
+    /**
+     * @param  array{id: int, purchasable_type: string, purchasable_id: int, quantity: int, meta: array}  $line
+     *   Snapshot of the removed line — the row is already deleted by the time this
+     *   event dispatches, so nothing here can be a fresh CartLine model instance.
+     */
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly array $line,
+    ) {}
+}

src/Cart/Events/CartLineSaved.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Modules\Core\Cart\Events;
+
+use Lunar\Models\Cart;
+use Lunar\Models\CartLine;
+
+/**
+ * A line was moved OUT of the purchasable cart and into "saved for later" —
+ * not a removal (the row still exists), but distinct from CartLineUpdated
+ * since it's a state transition worth its own hook (e.g. abandoned-cart
+ * recovery treating a saved line very differently from a deleted one).
+ */
+class CartLineSaved
+{
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly CartLine $line,
+    ) {}
+}

src/Cart/Events/CartLineUpdated.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Modules\Core\Cart\Events;
+
+use Lunar\Models\Cart;
+use Lunar\Models\CartLine;
+
+class CartLineUpdated
+{
+    /**
+     * @param  array{quantity: int, meta: array}  $old  Snapshot before the update.
+     */
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly CartLine $line,
+        public readonly array $old,
+    ) {}
+}

src/Cart/Exceptions/InvalidCouponException.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Modules\Core\Cart\Exceptions;
+
+use RuntimeException;
+
+/**
+ * Thrown by CartService::applyCoupon() when the given code doesn't match any
+ * currently-active, non-exhausted Discount — Lunar's own
+ * Discounts::validateCoupon() only returns a bool, it has no matching
+ * exception type of its own to reuse here.
+ */
+class InvalidCouponException extends RuntimeException
+{
+    public function __construct(public readonly string $couponCode)
+    {
+        parent::__construct("The coupon code \"{$couponCode}\" is not valid.");
+    }
+}

src/Cart/Filament/Resources/CartResource.php

@@ -0,0 +1,125 @@
+<?php
+
+namespace Modules\Core\Cart\Filament\Resources;
+
+use Filament\Tables\Columns\TextColumn;
+use Filament\Actions\ViewAction;
+use Modules\Core\Cart\Filament\Resources\CartResource\Pages\ListCarts;
+use Modules\Core\Cart\Filament\Resources\CartResource\Pages\ViewCart;
+use Filament\Resources\Resource;
+use Filament\Tables;
+use Filament\Tables\Table;
+use Illuminate\Support\Carbon;
+use Lunar\Admin\Filament\Resources\CustomerResource;
+use Lunar\Models\Cart;
+use Modules\Core\Cart\Filament\Resources\CartResource\Pages;
+use Modules\Core\Cart\Services\CartLifecycleService;
+
+/**
+ * Read-only — a cart is managed entirely through the storefront (add/update/remove
+ * line, checkout), never hand-edited by staff. Lists every cart, guest carts
+ * included — see docs/cart.md ("Scope: every cart, identified or not"). An
+ * anonymous cart's Customer/User columns just render "—" (see table() below)
+ * rather than the row being hidden outright: most real traffic never reaches
+ * an identified user/customer, and "how many carts are ongoing/abandoned
+ * right now" is a real reporting need regardless of identity — excluding
+ * anonymous carts would silently undercount it. Lunar itself ships no cart
+ * admin view at all to follow a precedent from.
+ */
+class CartResource extends Resource
+{
+    protected static ?string $model = Cart::class;
+
+    protected static string | \BackedEnum | null $navigationIcon = 'heroicon-o-shopping-cart';
+
+    protected static string | \UnitEnum | null $navigationGroup = 'Sales';
+
+    protected static ?string $modelLabel = 'Cart';
+
+    protected static ?string $pluralModelLabel = 'Carts';
+
+    /**
+     * Count only, not a fetch — no rows are loaded. Combines BOTH abandoned
+     * states (`active()` already covers "no order at all" and "draft order,
+     * never placed" together — see ListCarts::getTabs()'s "Abandoned Cart" /
+     * "Abandoned Checkout" tabs for where they're split apart), not "Ongoing"
+     * — the badge is meant to answer "how many carts might need following up
+     * on," not the total including ones someone is actively shopping in right
+     * now.
+     */
+    public static function getNavigationBadge(): ?string
+    {
+        return (string) static::getEloquentQuery()->active()->where('updated_at', '<=', static::abandonedCutoff())->count();
+    }
+
+    public static function lifecycle(): CartLifecycleService
+    {
+        return app(CartLifecycleService::class);
+    }
+
+    /**
+     * `Cart::scopeActive()` (not-yet-converted-to-an-order carts) mixes two very
+     * different things together: a cart someone is actively shopping in right now,
+     * and one that's genuinely been left behind. Lunar tracks no time-based
+     * staleness signal of its own — `Cart::updated_at` plus a configurable
+     * threshold (`config('core.cart.abandoned_after')`, default 1 hour) is what
+     * this resource uses to tell them apart. A cart with no recent activity is
+     * "Abandoned"; anything more recent is "Ongoing".
+     */
+    public static function abandonedCutoff(): Carbon
+    {
+        return static::lifecycle()->abandonedCutoff();
+    }
+
+    public static function table(Table $table): Table
+    {
+        return $table
+            ->columns([
+                TextColumn::make('id')
+                    ->label('Cart')
+                    ->sortable(),
+                TextColumn::make('customer.full_name')
+                    ->label('Customer')
+                    ->placeholder('—')
+                    ->searchable()
+                    ->url(fn (Cart $record) => $record->customer_id !== null
+                        ? CustomerResource::getUrl('view', ['record' => $record->customer_id])
+                        : null),
+                TextColumn::make('user.email')
+                    ->label('User')
+                    ->placeholder('—')
+                    ->searchable(),
+                TextColumn::make('lines_count')
+                    ->label('Lines')
+                    ->counts('lines')
+                    ->sortable(),
+                TextColumn::make('lines_sum_quantity')
+                    ->label('Items')
+                    ->sum('lines', 'quantity')
+                    ->sortable(),
+                TextColumn::make('currency.code')
+                    ->label('Currency'),
+                TextColumn::make('updated_at')
+                    ->label('Last activity')
+                    ->dateTime()
+                    ->sortable(),
+            ])
+            ->recordActions([
+                ViewAction::make(),
+            ])
+            ->defaultSort('updated_at', 'desc');
+    }
+
+    public static function getPages(): array
+    {
+        return [
+            'index' => ListCarts::route('/'),
+            'view' => ViewCart::route('/{record}'),
+        ];
+    }
+
+    public static function canCreate(): bool
+    {
+        return false;
+    }
+}

src/Cart/Filament/Resources/CartResource/Pages/ListCarts.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Modules\Core\Cart\Filament\Resources\CartResource\Pages;
+
+use Filament\Schemas\Components\Tabs\Tab;
+use Filament\Resources\Pages\ListRecords;
+use Illuminate\Database\Eloquent\Builder;
+use Modules\Core\Cart\Filament\Resources\CartResource;
+use Modules\Core\Cart\Services\CartLifecycleService;
+
+class ListCarts extends ListRecords
+{
+    protected static string $resource = CartResource::class;
+
+    /**
+     * `Cart::completed_at` is declared/cast on the model but never actually written
+     * anywhere in Lunar core — it's dead, not a real "did this convert" signal.
+     * "Completed" instead means the cart has an order with `placed_at` set (a
+     * placed, not just drafted, order).
+     *
+     * `Cart::scopeActive()` (not yet converted to an order) actually mixes two
+     * distinct states: no order started at all, vs. a draft order exists
+     * (`placed_at IS NULL`) but was never placed — checkout was started, not
+     * finished. That's a real difference in purchase intent (a cart with a
+     * draft order is a much stronger signal than one with no order at all) and
+     * in reachability (checkout usually captures an email even for a guest),
+     * so they get separate tabs rather than one combined "no order yet"
+     * bucket — same distinction Modules\Core\Recovery\Events\CartAbandoned /
+     * Modules\Core\Recovery\Events\CheckoutAbandoned draw.
+     *
+     * The four query shapes below live on Modules\Core\Cart\Services\
+     * CartLifecycleService, shared with Modules\Core\Cart\Commands\
+     * DetectAbandonedCarts — see that service's docblock for why duplicating
+     * them independently in both places was worth centralizing.
+     */
+    public function getTabs(): array
+    {
+        $lifecycle = app(CartLifecycleService::class);
+
+        return [
+            'abandoned_cart' => Tab::make('Abandoned Cart')
+                ->modifyQueryUsing(fn (Builder $query) => $lifecycle->abandonedCarts($query)),
+            'abandoned_checkout' => Tab::make('Abandoned Checkout')
+                ->modifyQueryUsing(fn (Builder $query) => $lifecycle->abandonedCheckouts($query)),
+            'ongoing' => Tab::make('Ongoing')
+                ->modifyQueryUsing(fn (Builder $query) => $lifecycle->ongoing($query)),
+            'completed' => Tab::make('Completed')
+                ->modifyQueryUsing(fn (Builder $query) => $lifecycle->completed($query)),
+        ];
+    }
+}

src/Cart/Filament/Resources/CartResource/Pages/ViewCart.php

@@ -0,0 +1,223 @@
+<?php
+
+namespace Modules\Core\Cart\Filament\Resources\CartResource\Pages;
+
+use Filament\Schemas\Schema;
+use Filament\Schemas\Components\Section;
+use Filament\Actions\Action;
+use Filament\Infolists\Components\ImageEntry;
+use Filament\Infolists\Components\RepeatableEntry;
+use Filament\Infolists\Components\TextEntry;
+use Filament\Resources\Pages\ViewRecord;
+use Filament\Support\Colors\Color;
+use Illuminate\Database\Eloquent\Collection as EloquentCollection;
+use Illuminate\Support\Facades\Blade;
+use Lunar\Admin\Filament\Resources\CustomerResource;
+use Lunar\Admin\Filament\Resources\ProductResource\Pages\EditProduct;
+use Lunar\Exceptions\MissingCurrencyPriceException;
+use Lunar\Models\Cart;
+use Lunar\Models\CartLine;
+use Lunar\Models\ProductVariant;
+use Modules\Core\Cart\Filament\Resources\CartResource;
+
+class ViewCart extends ViewRecord
+{
+    protected static string $resource = CartResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [
+            Action::make('viewCustomer')
+                ->label('View Customer')
+                ->icon('heroicon-o-user')
+                ->url(fn (Cart $record) => CustomerResource::getUrl('view', ['record' => $record->customer_id]))
+                ->visible(fn (Cart $record) => $record->customer_id !== null),
+        ];
+    }
+
+    /**
+     * Cart's computed properties (subTotal/total/etc.) are plain public properties
+     * populated as a side effect of the pipeline calculate() runs — never persisted,
+     * so they don't exist on a plain Eloquent-fetched record. Calculated once here
+     * (a single view page load), not per-row in the list table, since running the
+     * full pipeline for every row of a paginated table would be expensive for no
+     * real benefit — see docs/lunar.md's Cart gotchas.
+     *
+     * Eager-loads what the Lines section (below) reads off each line's
+     * purchasable — name, thumbnail, options — the same relations Lunar's
+     * own OrderItemsTable loads for an order's line items (`with(['purchasable'])`,
+     * see vendor/lunarphp/lunar/.../OrderItemsTable::getDefaultTable()) — so
+     * rendering the product grid doesn't N+1 per line.
+     *
+     * calculate() throws Lunar\Exceptions\MissingCurrencyPriceException
+     * (vendor PricingManager) the moment ANY line's purchasable has no
+     * price row for the cart's currency — including a line whose
+     * purchasable no longer exists at all (a deleted ProductVariant still
+     * referenced by cart_lines.purchasable_id), which 500'd this whole
+     * page rather than just leaving that one line unpriced. The Lines
+     * section below already guards every purchasable-derived field with
+     * `instanceof ProductVariant` and renders fine with $cart left
+     * uncalculated — subTotal/total/etc. simply won't be populated, which
+     * reads as a stale/pending state rather than a broken page.
+     */
+    protected function resolveRecord(int|string $key): Cart
+    {
+        /** @var Cart $cart */
+        $cart = parent::resolveRecord($key);
+
+        $cart->load('lines.purchasable', 'shippingAddress.country');
+
+        EloquentCollection::make($cart->lines->pluck('purchasable')->filter(fn ($p) => $p instanceof ProductVariant))
+            ->loadMissing(['product.thumbnail', 'images', 'values']);
+
+        try {
+            return $cart->calculate();
+        } catch (MissingCurrencyPriceException) {
+            return $cart;
+        }
+    }
+
+    public function infolist(Schema $schema): Schema
+    {
+        return $schema
+            ->components([
+                Section::make('Cart')
+                    ->columns(3)
+                    ->schema([
+                        TextEntry::make('id'),
+                        TextEntry::make('customer.full_name')
+                            ->label('Customer')
+                            ->placeholder('—')
+                            ->url(fn (Cart $record) => $record->customer_id !== null
+                                ? CustomerResource::getUrl('view', ['record' => $record->customer_id])
+                                : null),
+                        TextEntry::make('user.email')
+                            ->label('User')
+                            ->placeholder('—'),
+                        TextEntry::make('currency.code')
+                            ->label('Currency'),
+                        TextEntry::make('completedOrderPlacedAt')
+                            ->label('Ordered at')
+                            ->state(fn (Cart $record) => $record->orders()->whereNotNull('placed_at')->value('placed_at'))
+                            ->dateTime()
+                            ->placeholder('Not ordered'),
+                        TextEntry::make('updated_at')
+                            ->label('Last activity')
+                            ->dateTime(),
+                    ]),
+                Section::make('Lines')
+                    ->schema([
+                        RepeatableEntry::make('lines')
+                            ->hiddenLabel()
+                            ->schema([
+                                ImageEntry::make('image')
+                                    ->hiddenLabel()
+                                    ->state(fn (CartLine $record) => $record->purchasable instanceof ProductVariant
+                                        ? $record->purchasable->getThumbnail()?->getUrl('small')
+                                        : null)
+                                    ->defaultImageUrl(fn () => 'data:image/svg+xml;base64,'.base64_encode(
+                                        Blade::render('<x-filament::icon icon="heroicon-o-photo" style="color:rgb('.Color::Gray[400].');"/>')
+                                    ))
+                                    ->imageSize(48),
+                                TextEntry::make('description')
+                                    ->label('Product')
+                                    // ProductVariant::getDescription()/getOption() are typed
+                                    // string but internally read translateAttribute()/
+                                    // translate(), which return null for a product/option
+                                    // with no attribute data set for the active locale —
+                                    // reading the underlying relations directly here avoids
+                                    // that TypeError rather than calling through them.
+                                    ->state(fn (CartLine $record) => $record->purchasable instanceof ProductVariant
+                                        ? ($record->purchasable->product?->translateAttribute('name') ?? '—')
+                                        : '—')
+                                    ->url(fn (CartLine $record) => $record->purchasable instanceof ProductVariant
+                                        ? EditProduct::getUrl(['record' => $record->purchasable->product_id])
+                                        : null)
+                                    ->weight('bold'),
+                                TextEntry::make('options')
+                                    ->label('Options')
+                                    ->state(fn (CartLine $record) => $record->purchasable instanceof ProductVariant
+                                        ? ($record->purchasable->values->map(fn ($value) => $value->translate('name'))->filter()->join(', ') ?: null)
+                                        : null)
+                                    ->placeholder('—')
+                                    ->badge(),
+                                TextEntry::make('purchasable.sku')
+                                    ->label('SKU')
+                                    ->placeholder('—'),
+                                TextEntry::make('quantity'),
+                                TextEntry::make('unitPrice')
+                                    ->label('Unit price')
+                                    ->formatStateUsing(fn (CartLine $record) => $record->unitPrice?->formatted() ?? '—'),
+                                TextEntry::make('total')
+                                    ->label('Line total')
+                                    ->formatStateUsing(fn (CartLine $record) => $record->total?->formatted() ?? '—'),
+                            ])
+                            ->columns(4),
+                    ]),
+                Section::make('Shipping')
+                    ->columns(3)
+                    ->schema([
+                        TextEntry::make('shippingAddress.shipping_option')
+                            ->label('Shipping method')
+                            // The raw identifier (e.g. "acs") is all a
+                            // CartAddress row stores — the human-readable
+                            // name only exists on the resolved
+                            // Lunar\DataTypes\ShippingOption, which is what
+                            // shippingBreakdown's items are keyed/named
+                            // from below, so fall back to that name rather
+                            // than showing the bare identifier.
+                            ->formatStateUsing(fn (Cart $record, ?string $state) => $state
+                                ? ($record->shippingBreakdown?->items->get($state)?->name ?? $state)
+                                : null)
+                            ->placeholder('Not selected'),
+                        TextEntry::make('shippingAddress.country.name')
+                            ->label('Shipping to')
+                            ->placeholder('—'),
+                        TextEntry::make('shippingTotal')
+                            ->label('Shipping total')
+                            ->formatStateUsing(fn (Cart $record) => $record->shippingTotal?->formatted() ?? '—')
+                            ->weight('bold'),
+                        RepeatableEntry::make('shippingBreakdownItems')
+                            ->label('Breakdown')
+                            ->columnSpanFull()
+                            // shippingBreakdown->items is a plain (non-Eloquent)
+                            // Collection of Lunar\Base\ValueObjects\Cart\
+                            // ShippingBreakdownItem — e.g. the carrier rate and,
+                            // separately, Modules\Core\Payment\Pipelines\Cart\
+                            // ApplyPaymentMethodFee's own line item when the
+                            // selected payment method carries a fee (see
+                            // CHANGELOG 0.16.3) — both show up here individually
+                            // rather than only as the summed shippingTotal above.
+                            ->state(fn (Cart $record) => $record->shippingBreakdown?->items->values() ?? [])
+                            ->schema([
+                                TextEntry::make('name')
+                                    ->hiddenLabel(),
+                                TextEntry::make('price')
+                                    ->hiddenLabel()
+                                    ->formatStateUsing(fn ($state) => $state?->formatted() ?? '—')
+                                    ->alignEnd(),
+                            ])
+                            ->columns(2)
+                            ->visible(fn (Cart $record) => (bool) $record->shippingBreakdown?->items->isNotEmpty()),
+                    ])
+                    ->visible(fn (Cart $record) => $record->shippingAddress !== null),
+                Section::make('Totals')
+                    ->columns(3)
+                    ->schema([
+                        TextEntry::make('subTotal')
+                            ->label('Subtotal')
+                            ->formatStateUsing(fn (Cart $record) => $record->subTotal?->formatted() ?? '—'),
+                        TextEntry::make('discountTotal')
+                            ->label('Discount')
+                            ->formatStateUsing(fn (Cart $record) => $record->discountTotal?->formatted() ?? '—'),
+                        TextEntry::make('taxTotal')
+                            ->label('Tax')
+                            ->formatStateUsing(fn (Cart $record) => $record->taxTotal?->formatted() ?? '—'),
+                        TextEntry::make('total')
+                            ->label('Total')
+                            ->formatStateUsing(fn (Cart $record) => $record->total?->formatted() ?? '—')
+                            ->weight('bold'),
+                    ]),
+            ]);
+    }
+}

src/Cart/Pipelines/ZeroSavedForLaterPrice.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Modules\Core\Cart\Pipelines;
+
+use Closure;
+use Lunar\DataTypes\Price;
+use Lunar\Models\Contracts\CartLine as CartLineContract;
+
+/**
+ * Runs in config('lunar.cart.pipelines.cart_lines'), after GetUnitPrice —
+ * zeroes out unitPrice/unitPriceInclTax for any line flagged
+ * meta.saved_for_later, BEFORE Lunar's own CalculateLines pipeline step reads
+ * unitPrice to compute subTotal/total. A saved-for-later item is deliberately
+ * parked, not pending purchase, so it shouldn't inflate Cart::total — and
+ * since CalculateLines sums every CartLine unconditionally with no meta-based
+ * exclusion of its own, zeroing the price here (rather than patching subTotal
+ * after the fact) is what makes every downstream total naturally correct
+ * without a second pass.
+ */
+class ZeroSavedForLaterPrice
+{
+    public function handle(CartLineContract $cartLine, Closure $next): mixed
+    {
+        if ($cartLine->meta['saved_for_later'] ?? false) {
+            $currency = $cartLine->cart->currency;
+
+            $cartLine->unitPrice = new Price(0, $currency, 1);
+            $cartLine->unitPriceInclTax = new Price(0, $currency, 1);
+        }
+
+        return $next($cartLine);
+    }
+}