Bump Version to 0.10.1

This commit introduces a Product service to Lunar. This product service calls Meilisearch to fetch an indexed product. The indexer has been updated to also include the collection and the price of the product.

A product search service has also been created to be used by the frontend's search

CHANGELOG.md

@@ -4,6 +4,173 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.10.1] - 2026-09-01
+
+### Added
+- `Modules\Core\Localization\Services\StorefrontLabels::all()` gains three keys found missing from `3dealer`'s actual `storefront.*` translation usage: `shop.price_min`, `shop.price_max`, `shop.reset` (the price-filter sidebar's min/max labels and its reset link). Picked up by `InstallLunarCommand`'s existing per-key upsert — re-running `lunar:install` on an already-installed store adds only these three rows, leaving everything already seeded or admin-edited untouched.
+
+## [0.10.0] - 2026-08-31
+
+### Changed
+- **Breaking:** Upgraded `lunarphp/lunar`, `lunarphp/core`, `lunarphp/stripe`, `lunarphp/table-rate-shipping`, and `lunarphp/search` to `1.5.0`, and `filament/filament` to `v4.12.6` — the first Filament v4 admin panel on this codebase. `lunarphp/filament3-2fa` and `kalnoy/nestedset` are gone, replaced by Filament v4's native two-factor auth and `lunarphp/nestedset`. Ran Filament's automated `filament-v4` migration tool across `src/`, then hand-fixed three bugs it introduced or left behind: a stale `$infolist` variable reference in `CartResource`'s `ViewCart` page (the parameter had been renamed to `$schema` but the body wasn't updated), `ShippingMethodResourceExtension` rewritten to call `getDefaultChildComponents()` (returns `array|Schema`) instead of the type-safe `getChildComponents()` (always `array<Component>`), and — unrelated to the tool, but surfaced by the same PHP version bump — `InvalidCouponException`'s `readonly $code` property illegally shadowing the built-in `Exception::$code`, renamed to `$couponCode`. `LunarStaff::addActivitylogExcept()` updated for the renamed `two_factor_secret`/`two_factor_recovery_codes` staff columns (now `app_authentication_secret`/`app_authentication_recovery_codes`; `two_factor_confirmed_at` removed). Consuming apps must run `composer update boboko/core --with-all-dependencies` and `php artisan migrate`.
+
+### Added
+- `Modules\Core\Checkout\Contracts\PaymentDriver` — the abstraction every payment provider implements: `confirm(Cart $cart, string $type, string $fingerprint, array $data): Order` and `isConfigured(): bool`. A driver only ever calls `CheckoutService::placeOrder()` once it has, by whatever mechanism is native to that gateway, independently confirmed payment — never Lunar's raw `Cart::createOrder()`. This is what lets the storefront checkout sequence stay uniform regardless of which provider is active: set addresses, select shipping, hand off to whichever driver is configured, and the driver decides when (or whether) the order gets created.
+- `Modules\Core\Payment\Drivers\OfflinePaymentDriver` — shared by every payment type with no real gateway to confirm against (`cash-in-hand`, `cash-on-delivery`): places the order immediately via `CheckoutService::placeOrder()`, then sets the order status from `config("lunar.payments.types.{$type}.authorized")` using the type actually confirmed, not a hardcoded key, since one driver instance serves multiple types.
+- `Modules\Core\Payment\Drivers\StripePaymentDriver` — a fork, not a decoration, of `lunarphp/stripe`'s `StripePaymentType::authorize()`: that method is `final` and calls `Cart::createOrder()` directly with no seam to redirect into our fingerprint-checked `placeOrder()`, so this class reimplements its logic (intent retrieval, capture-on-policy, status mapping via `UpdateOrderFromIntent`) with that one substitution. Throws the new `Modules\Core\Payment\Exceptions\PaymentNotConfirmedException` on anything short of a genuinely confirmed payment intent — never falls through to placing an order on ambiguity.
+- `CheckoutService::getPaymentMethods(): array` — every payment type currently offered to the storefront: every key in `config('lunar.payments.types')` that is both administratively enabled (`Modules\Core\Payment\Models\PaymentMethod::enabled`) and whose driver reports `isConfigured()` (e.g. Stripe with no API key set is never offered, regardless of the enabled toggle). `selectPaymentMethod(string $type)` and `confirmPayment(string $type, array $data)` both validate against this list, throwing the new `UnknownPaymentTypeException` for a type that isn't currently offered — re-checked in `confirmPayment()` too, since a type could be disabled between selection and confirmation.
+- `CheckoutService::selectPaymentMethod()` snapshots `Cart::fingerprint()` into `cart->meta['checkout_fingerprint']` *after* saving the chosen type and recalculating — the fingerprint has to reflect the final total including any payment-type-specific adjustment (e.g. a COD surcharge), which only exists once `payment_method` is set. `confirmPayment()` reads this stored fingerprint internally rather than taking one as a parameter: a storefront should never need to know `Cart::fingerprint()` exists or capture it at exactly the right moment itself.
+- `Modules\Core\Payment\Models\PaymentMethod` — one DB row per payment type key (matching `config('lunar.payments.types')`), `enabled` boolean plus a `data` jsonb column (starting with `fee`, the flat cash-on-delivery surcharge) — mirrors Lunar's own `Discount` model (a single jsonb column of keyed settings, not a fixed column per setting or a separate conditions table). Seeded idempotently by `InstallLunarCommand` (skip-if-exists per type, safe to re-run after installing a new payment-provider package), always `enabled: false` — a newly-seeded type shouldn't go live for shoppers before staff have configured and reviewed it. Admin-editable via the new `PaymentMethodResource` (inline enabled toggle, modal fee editor) under Settings.
+- `ApplyCashOnDeliveryFee` now reads its surcharge from `PaymentMethod` instead of static config, so it's admin-editable without a deploy.
+
+### Fixed
+- `CashOnDeliveryPaymentDriver` renamed to `OfflinePaymentDriver` and generalized to work for any offline-style type — it previously hardcoded `'cash-on-delivery'` when reading the post-placement order status from config, which would have silently read the wrong type's status the moment a second offline type (`cash-in-hand`) used it.
+
+## [0.9.0] - 2026-08-29
+
+### Added
+- `Modules\Core\Cart\Services\CartService` — the boboko-owned API for all cart mutation, wrapping Lunar's `CartSession`/`Cart` primitives: `addLine()`, `updateLine()`, `removeLine()`, `clear()`, `applyCoupon()`/`removeCoupon()` (throws `InvalidCouponException` on an invalid code), and save-for-later (`saveForLater()`/`moveToCart()`/`activeLines()`/`savedLines()`, backed by a `meta.saved_for_later` flag and a new `Modules\Core\Cart\Pipelines\ZeroSavedForLaterPrice` cart-line pipeline step that zeroes a saved line's price so it's excluded from cart totals without being removed). Dispatches 8 real domain events (`CartLineAdded`/`Updated`/`Removed`/`Saved`/`MovedToCart`, `CartCleared`, `CartCouponApplied`/`Removed`) — none have a listener yet, built so a future concern (analytics, recovery) has something to attach to. Documented in `docs/cart.md`.
+- `Modules\Core\Checkout\Services\CheckoutService` — the boboko-owned API for the checkout stage (address → shipping selection → order placement), sitting between `CartService` and `Order`: `setShippingAddress()`/`setBillingAddress()`, `getShippingOptions()`/`selectShippingOption()` (throws the new `InvalidShippingOptionException` on an identifier that doesn't resolve — previously a silent no-op), and `placeOrder(string $fingerprint)` (the fingerprint is mandatory, not optional — forces re-confirmation via Lunar's own `FingerprintMismatchException` if the cart changed since the shopper last saw its total). Dispatches `ShippingAddressSet`/`BillingAddressSet`/`ShippingOptionSelected`/`OrderPlaced`, each carrying richer, already-resolved payload (e.g. the resolved `ShippingOption`, not just its identifier) than `CartService`'s events. No exception wrapping otherwise — Lunar's own `CartException`/`FingerprintMismatchException` are already the right shape for a storefront to render as form errors. Documented in `docs/checkout.md`.
+- `Modules\Core\Cart\Filament\Resources\CartResource`'s list view now classifies every cart into one of four states — **Ongoing**, **Abandoned Cart**, **Abandoned Checkout**, **Completed** — instead of the previous two-tab Abandoned/Completed split, distinguishing a cart that never reached checkout from one that has a started-but-unplaced order (mirrors the real distinction in Lunar's own `Cart::scopeActive()`). Abandonment threshold is a fixed, configurable cutoff (`config('core.cart.abandoned_after')`, default 1 hour). Added a customer hyperlink (list column + a "View Customer" header action on the view page, both pointing straight at `customers/{id}` via the plain `customer_id` column, no extra query via the `customer` relation).
+- `Modules\Core\Cart\Commands\DetectAbandonedCarts` (`boboko:cart:detect-abandoned`, scheduled hourly) dispatches `Modules\Core\Recovery\Events\CartAbandoned`/`CheckoutAbandoned` for carts/checkouts past the abandonment cutoff — detection only, no persistence; a real tracking table is left for when `Recovery` is built as its own concern. Fixed a self-defeating bug from an earlier draft: marking a cart as notified by writing to it bumped `updated_at`, which immediately un-staled it for the next run's own cutoff check.
+- Merged the `Shipping-Carriers` branch: live carrier rate quoting and fulfillment for **ACS Courier** and **Box Now** (`Modules\Core\Shipping\Carriers\{Acs,BoxNow}`) on top of `lunarphp/table-rate-shipping` — `AcsRateDriver`/`BoxNowRateDriver` (live + static price-break resolution), `AcsFulfillmentService`/`BoxNowFulfillmentService` (shipment creation, label printing, cancellation via the new `Modules\Core\Shipping\Contracts\CarrierFulfillmentInterface`, resolved per-carrier via contextual container binding), `Modules\Core\Shipping\Models\Shipment`/`ShipmentInfo`, `PollShipmentTrackingJob` (scheduled every 30 minutes), `ManagePickupManifests` (Filament page for carrier manifest batching), and an `OrderViewExtension` adding a "Create Shipment" header action to Lunar's order view. Carrier credentials are published config (`config/shippingCarriers/{acs,boxnow}.php`), never committed.
+- `Modules\Core\Shipping\Concerns\CachesLivePricing` caches a live-priced carrier quote per `(rate, cart)` for 30 minutes — a real, billed API call that's otherwise re-run on every `getShippingOptions()`/`selectShippingOption()` call within the same checkout attempt. `Modules\Core\Shipping\Listeners\FlushLivePricingCache` invalidates it on the only two things that can change a quote: a cart line changing or the shipping address changing (deliberately **not** on order placement — the price the shopper was quoted must still be readable afterwards). Scoped generically to any `SupportsLivePricing` driver, not hardcoded to ACS.
+- `AcsRateDriver::resolveLivePrice()` now falls back to the rate's own configured static price if the live ACS API call fails (previously: the shipping option silently disappeared from the list on any API error, including a brief outage). `ManageShippingRates` (our Filament subclass of the vendor rates page) now allows a static price to be configured and saved on a "live" rate specifically for this fallback — previously those fields were hidden and discarded on save for any live-priced rate.
+
+### Fixed
+- Fixed a crash (`Attempt to read property "price" on null`) opening/editing a live-priced shipping rate with no fallback price configured yet — the vendor `ManageShippingRates` page's `afterStateHydrated` callback for the price field had no null-guard for a rate with zero `basePrices`, which is now the routine case for an unconfigured live rate.
+- Fixed the Filament admin panel's home URL (`/boboko/home`) incorrectly resolving to the Shipping module's `ManagePickupManifests` page instead of the Dashboard — Filament falls back to the first item of the first registered navigation group when no explicit `homeUrl()` is set, and `ManagePickupManifests` had no `navigationGroup`/`navigationSort` of its own. Fixed via explicit `navigationGroup = 'Sales'` / `navigationSort = 100`, placing it after Sales in the nav instead of first overall.
+
+## [0.8.0] - 2026-08-27
+
+### Added
+- `Modules\Core\Cart\Filament\Resources\CartResource` gives staff read-only visibility into carts in the Filament admin panel — Lunar ships no cart admin view at all. Scoped to carts with a known `user_id`/`customer_id` (an anonymous guest cart carries no identity staff could act on); list table shows customer/user, line/item counts (via Filament's built-in `->counts()`/`->sum()`, no per-row queries), currency, and last activity. List page has only two tabs, **Abandoned** (default active) and **Completed** — no "All" tab, so the list never runs an unfiltered fetch over the whole table. They key off whether the cart has a **placed** order (`orders.placed_at IS NOT NULL`), not `Cart::completed_at` — that column is declared/cast on the model but never actually written anywhere in Lunar core, so it's not a real signal; "Abandoned" mirrors Lunar's own `Cart::scopeActive()`. `getNavigationBadge()` shows the abandoned-cart count in the sidebar via a single `COUNT(*)` query, no rows loaded. View page runs `$cart->calculate()` once so line/cart totals (plain public properties Lunar never persists) are populated, without paying that cost per row in the list. Documented in `docs/cart.md`.
+
+## [0.7.0] - 2026-08-27
+
+### Added
+- `Modules\Core\Catalog\Services\CollectionService` provides category browsing/nav AND single-collection lookup from Meilisearch, mirroring `ProductService` exactly (`list()`, `getById()`, `getBySlug()`, same locale-resolution logic). `Modules\Core\Catalog\Services\CollectionIndexer` extends Lunar's own `Lunar\Search\CollectionIndexer` (which only carried `id`/`name`/`created_at`) to add `parent_id`, `_lft`/`_rgt` (nested-set tree position, filterable/sortable), `collection_group_id`, `slugs`, and `thumbnail`. `Modules\Core\Catalog\DTOs\CollectionFilters` supports `parentId` (children of a specific collection), `groupId`, and `rootOnly` (top-level collections, `parent_id IS NULL` — mutually exclusive with `parentId`). `Modules\Core\Catalog\Enums\CollectionSort` adds `Position` (`_lft:asc`, the recommended default for nav/tree UIs — matches admin arrangement order), `Name`, `Newest`. Must be registered in a consuming app's `config/lunar/search.php` (`Lunar\Models\Collection::class => CollectionIndexer::class`), same as `ProductIndexer`. Documented in `docs/collections.md`.
+- `Modules\Core\Localization\Services\StorefrontLabels::all()` extracts the default storefront UI label list out of `InstallLunarCommand` into its own class, and adds every previously-missing key (`nav.contact`, `product.description`/`no_image`/`read_more`/`reviews`, `customer_reviews`, `pagination.*`, `review.*`, `shop.*`) that had already been seeded manually in some stores but was absent from the command's own list — bringing the code-side default back in sync with what a real store actually has. `InstallLunarCommand::seedStorefrontLabels()` now does a **per-key upsert** instead of 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, and only missing keys are created via `TranslationService::create()`. This 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. Documented in `docs/localization.md` ("Seeding").
+- `Modules\Core\Catalog\Services\CollectionIndexer` adds `ancestors` — `[{id, name}, ...]` ordered root-first (via the newly eager-loaded `ancestors` relation) — so a breadcrumb can render directly from `CollectionService::getById()`/`getBySlug()` with zero extra queries, and `product_count` — how many products are in a collection or any of its descendants, queried from the product Meilisearch index at collection-index time via the same `collection_ids` field `ProductFilters(collectionId:)` filters against. Documented in `docs/collections.md`, including the reindex-ordering gotcha (`product_count` needs the product index reindexed first).
+- `Modules\Core\Catalog\Services\ProductIndexer` adds a filterable `in_stock` boolean — `true` if any variant currently passes `ProductVariant::canBeFulfilledAtQuantity(1)` (Lunar's own purchasability rule, not a naive `stock > 0` check). `Modules\Core\Catalog\DTOs\ProductFilters` gets a matching `inStockOnly` flag. Reflects stock as of the last reindex only — nothing currently reindexes a product when an order decrements its stock, since that's a cart/checkout concern this doesn't attempt to solve; see `docs/product-listing.md` ("Stock goes stale between orders").
+- `Modules\Core\Catalog\Services\ProductService::facets(string $field, ?ProductFilters $filters = null): array` returns Meilisearch facet value counts (e.g. `['Brand A' => 48, 'Brand B' => 135]`) for a discrete-value filterable field, scoped to the given filters. Uses Scout's plain `->options(['facets' => [...]])`, merged directly into the raw Meilisearch query the same way `filter`/`sort` already are — no adoption of Lunar's separate `SearchManager`/`Search` facade needed. `ProductService::priceRange(?ProductFilters $filters = null): array{min, max}` covers the numeric-field case `facets()` explicitly doesn't (`price` would otherwise return one "facet" per exact price) — backed by Meilisearch's `facetStats`, not `facetDistribution`. `priceRange()` always excludes `minPrice`/`maxPrice` from the filter it builds (via a new `$exclude` parameter on the private `buildFilter()`), so a price slider's own bounds don't shrink to whatever range is already selected on it; other filters (`collectionId`, `brand`, `inStockOnly`) still apply normally. Documented in `docs/product-listing.md`.
+
+### Changed
+- **Breaking:** Renamed the `Product` module to `Catalog`, flattened. Every class under `Modules\Core\Product\*` (`Contracts`, `DTOs`, `Enums`, `Services`, `Observers`, `Filament\Extensions`, `OptionTypes`) now lives under `Modules\Core\Catalog\*` at the same sub-path — e.g. `Modules\Core\Product\Services\ProductService` is now `Modules\Core\Catalog\Services\ProductService`, `Modules\Core\Product\DTOs\ProductFilters` is now `Modules\Core\Catalog\DTOs\ProductFilters`. Class names themselves are unchanged (still `ProductService`, `ProductIndexer`, `ProductFilters`, etc.) — only the namespace/folder moved, to make room for `Collection` as a sibling concern under the same `Catalog` umbrella rather than a disconnected top-level module. Consuming apps must update every `use Modules\Core\Product\...` import and any FQCN reference (`config/lunar/search.php`'s indexer registration, service provider bindings).
+- **Breaking:** `Modules\Core\Providers\ProductServiceProvider` renamed to `Modules\Core\Providers\CatalogServiceProvider` (composer.json's provider list updated accordingly) — it now only wires `Catalog`-namespace classes (`ProductOptionTypeManager`, `ProductOptionReindexObserver`), so the name follows the same by-concern convention as `LocalizationServiceProvider`/`ReviewServiceProvider`.
+- **Breaking:** `Modules\Core\Review`'s flat `Extensions/`/`Pages/` folders now nest under `Filament/`, matching the strict per-concern subfolder convention already applied to `Product`(now `Catalog`)/`Localization`. `Modules\Core\Review\Extensions\ProductResourceExtension` is now `Modules\Core\Review\Filament\Extensions\ProductResourceExtension`; `Modules\Core\Review\Pages\ManageProductReviews` is now `Modules\Core\Review\Filament\Pages\ManageProductReviews`. `Modules\Core\Review\Models\ProductReview` is unchanged.
+- **Breaking:** `ProductFilters(collectionId: ...)` now matches a product in that collection **or any of its descendant collections**, not just direct assignment. Products in a Shopify-imported tree are typically attached only to leaf collections, so filtering strictly on direct assignment meant a parent/root category page (`CollectionFilters(rootOnly: true)`'s results, or any non-leaf collection) always returned zero products even though real products existed several levels down. `Modules\Core\Catalog\Services\ProductIndexer` adds a new filterable `collection_ids` field — every directly-assigned collection's id unioned with all of its ancestors' ids (via the newly eager-loaded `collections.ancestors`) — and `ProductService::buildFilter()` now filters `collectionId` against `collection_ids` instead of the old `collections.id`. The display-only `collections` field (`{id, name}`, direct assignments) is unchanged and no longer filterable.
+
+## [0.6.1] - 2026-08-27
+
+### Added
+- `Modules\Core\Product\Contracts\ProductOptionTypeInterface` describes how a category of `Lunar\Models\ProductOption` (e.g. "Color", "Size") behaves — what structured data its values carry in their free-form `meta` jsonb column, and how an admin edits it via Filament — without introducing a new model. Registered via `Modules\Core\Product\Services\ProductOptionTypeManager::get()->register([...])` (a singleton registry, same shape as `Modules\Core\Notification\NotificationRegistry`) from a service provider's `boot()`. An admin then picks one per `ProductOption` from an "Option Type" dropdown on the option's own edit form (added by `Modules\Core\Product\Filament\Extensions\ProductOptionResourceExtension`), stored in `ProductOption::meta['option_type']` — deliberately not tied to the option's `handle`, since a shop's own handle naming shouldn't have to match a type's key. `Modules\Core\Product\Filament\Extensions\ValuesRelationManagerExtension` hooks Lunar's own `ValuesRelationManager` (both extensions via `LunarPanel::extensions()`, registered in `CorePlugin`) to append the resolved type's meta form fields to the stock "Values" tab — no fork of Lunar's classes needed. Ships a reference implementation, `Modules\Core\Product\OptionTypes\ColorOptionType`, registered automatically by the new `Modules\Core\Providers\ProductServiceProvider`. Documented in `docs/product-options.md`.
+- `Modules\Core\Product\Services\ProductIndexer::mapVariant()` now includes each option's `handle` (alongside its translated name) in a variant's indexed `options[]` — previously only the translated `option`/`value` names and `meta` were indexed, with no stable, locale-independent identifier for which option a value belongs to.
+- `Modules\Core\Product\Observers\ProductOptionReindexObserver`, wired in the new `Modules\Core\Providers\ProductServiceProvider`, keeps Meilisearch in sync when a `ProductOption` or `ProductOptionValue` is saved or deleted — e.g. picking an Option Type or editing a color's hex. `ProductIndexer::mapVariant()` embeds each option value's `meta` directly into a product's indexed document, but saving the option/value never fires the *product's* own save events, so without this a changed hex would only reach the index on that product's next unrelated reindex. The observer resolves every `Lunar\Models\Product` whose variants use the changed option (or option value) via the `product_option_value_product_variant` pivot, and calls `->searchable()` on each.
+
+### Changed
+- **Breaking:** `Modules\Core\Product\Services\ProductIndexer`'s indexed `collections` field is now an array of `{id, name}` objects instead of two parallel arrays (`collections` as bare ID strings, `collection_names` as translated names joined only by array index). `collection_names` is removed. Filtering by collection now targets the nested field `collections.id` (Meilisearch supports filtering on nested object fields), not bare `collections` — `Modules\Core\Product\Services\ProductService::buildFilter()` updated accordingly; `ProductFilters(collectionId: ...)`'s public API is unchanged. Run `php artisan lunar:meilisearch:setup` then `lunar:search:index --refresh` after upgrading (see docs/product-listing.md "Gotchas").
+- **Breaking:** `ProductIndexer`'s indexed `review_count`/`average_rating` top-level keys are folded into the existing `reviews` key: `reviews` is now `{items, count, average_rating}` instead of a bare array with `review_count`/`average_rating` as separate sibling keys. `reviews` (the array of review items) moved to `reviews.items`.
+
+## [0.6.0] - 2026-08-27
+
+### Added
+- `Modules\Core\Localization\Models\LanguageLine` extends `spatie/laravel-translation-loader`'s `LanguageLine` to fall back to the store's actual default language (`LanguageCache::defaultLocale()`, backed by Lunar's `languages.default` flag) instead of the package's stock behavior of falling back to the static `config('app.fallback_locale')` — the two were previously disconnected, so changing the default language via the Filament **Languages** resource had no effect on which locale an untranslated storefront label silently fell back to. Swapped in automatically via `config('translation-loader.model')` in `LocalizationServiceProvider::register()`; no consuming app changes needed. Documented in `docs/localization.md` ("Fallback locale follows the store's default language").
+
+### Changed
+- **Breaking:** `Modules\Core\Catalog\ProductService::list()` now returns a real `Illuminate\Pagination\LengthAwarePaginator` (built from the localized Meilisearch hits) instead of a plain `array{data, meta}` — gives callers normal Laravel pagination behaviour (`$products->links()`, standard JSON serialization) without ever touching Scout's raw `paginateRaw()` response directly. `getById()`/`getBySlug()` are unaffected (still return `?array`).
+- `ProductService::withLocalizedFields()` (used by `list()`, `getById()`, `getBySlug()`) no longer hardcodes `name`/`description` as the only translated fields — it now reads every `TranslatedText` attribute on `Product` from `Lunar\Base\AttributeManifest` (the same source Lunar's own indexer reads), so a store's own custom translated attributes (e.g. `seo_title`, `seo_description`) are resolved and locale-stripped automatically with no code change here. Raw `{handle}_{locale}` keys (e.g. `name_el`, `seo_title_en`) are now stripped from every returned product, not just `name_*`/`description_*`.
+- Extracted `Modules\Core\Localization\Services\LanguageCache` (cached read layer over Lunar's `languages` table: `all()`, `defaultLocale()`, `availableLocales()`, `forget()`) out of `LocaleMiddleware`, which previously owned this as private/static methods despite not being middleware-specific behavior. `LocaleMiddleware` now takes `LanguageCache` via constructor injection. `LocaleMiddleware::defaultLocale()`/`forgetLanguagesCache()` (static) are removed — use `app(LanguageCache::class)` or inject `LanguageCache` directly.
+
+### Fixed
+- `Modules\Core\MigrateImport\JudgeMe\Resolvers\ProductResolver::resolve()` picked whichever `lunar_urls` row matched a slug first, which can be a soft-deleted product left behind by an earlier import batch rather than the current live one — a store can easily end up with more than one `Product` row sharing the same slug across re-imports, since a soft-deleted product's URL row isn't cleaned up. This silently broke every downstream lookup for that handle (e.g. `Modules\Core\MigrateImport\JudgeMe\JudgeMeExportImporter` logging "no product found for handle, skipping review" and dropping the row, even though a live product with that exact handle existed). Rewrote as a join against `lunar_products` — via `Product::query()`, so Eloquent's `SoftDeletes` global scope excludes trashed rows — so only a URL pointing at a live product resolves.
+- `Modules\Core\Review\Models\ProductReview` had no `registerMediaConversions()` at all, unlike `Product`/`ProductVariant` which get one automatically from Lunar's own `Lunar\Base\StandardMediaDefinitions`. `Modules\Core\Search\ProductIndexer::mapMedia()` is shared across product, variant, and review media and always requests the `small` conversion — the first time a review had an attached image, indexing it threw `Spatie\MediaLibrary\MediaCollections\Exceptions\InvalidConversion`, silently failing the product's `MakeSearchable` queue job (and everything queued after it, since Scout batches). Added a matching `small` conversion (300×300, same fit/border/background as Lunar's standard one) directly on `ProductReview`.
+
+### Breaking
+- Merged `Modules\Core\Catalog` and `Modules\Core\Search` into a single `Modules\Core\Product` concern, since both existed purely to serve `Product` (browsing/filtering vs. indexing/full-text search — two services, one concern), following a stricter subfolder convention (`Contracts/`, `Enums/`, `Services/`, `DTOs/`, `Models/`, etc. per concern) going forward:
+  - `Modules\Core\Catalog\ProductService` → `Modules\Core\Product\Services\ProductService`
+  - `Modules\Core\Catalog\ProductFilters` → `Modules\Core\Product\DTOs\ProductFilters`
+  - `Modules\Core\Catalog\ProductSort` → `Modules\Core\Product\Enums\ProductSort`
+  - `Modules\Core\Search\ProductIndexer` → `Modules\Core\Product\Services\ProductIndexer`
+  - `Modules\Core\Search\ProductSearchService` → `Modules\Core\Product\Services\ProductSearchService`
+
+  Consuming apps must update any direct references — notably `config/lunar/search.php`'s `'indexers'` map, which points at `ProductIndexer` by FQCN. `Modules\Core\Catalog\ProductOptionTypeInterface` (in-progress, not yet wired to anything) was deliberately left in place rather than moved.
+- Reorganized `Modules\Core\Localization` under the same stricter per-concern subfolder convention — `Events/`, `Filament/`, `Listeners/` were already correctly categorized; four loose root files moved into typed buckets by structural role:
+  - `Modules\Core\Localization\LocaleMiddleware` → `Modules\Core\Localization\Middleware\LocaleMiddleware`
+  - `Modules\Core\Localization\LanguageCacheObserver` → `Modules\Core\Localization\Observers\LanguageCacheObserver`
+  - `Modules\Core\Localization\TranslationReader` → `Modules\Core\Localization\Services\TranslationReader`
+  - `Modules\Core\Localization\TranslationService` → `Modules\Core\Localization\Services\TranslationService`
+
+  `Modules\Core\Localization\Services\LanguageCache` (added earlier in this same unreleased version) already lived at its correct final path — unaffected. The `'locale'` route-middleware alias (registered in `LocalizationServiceProvider`) is unaffected for consuming apps using it by string alias rather than FQCN.
+
+## [0.5.4] - 2026-08-26
+
+### Added
+- `Modules\Core\Catalog\ProductService::list()` accepts a `sort` parameter (new `ProductSort` enum: `PriceAsc`, `PriceDesc`, `Newest`), translated into a Meilisearch `sort` clause — `list()` previously had no way to order results, since it always searches with an empty query string and so has no relevance score to fall back on. `Modules\Core\Search\ProductIndexer::getSortableFields()` now also marks `price` sortable (Lunar's base indexer only marks `created_at`/`updated_at`/`skus`/`status`). Requires re-syncing index settings (`php artisan lunar:meilisearch:setup`) on existing stores. Documented in `docs/product-listing.md` ("Sorting").
+
+## [0.5.3] - 2026-08-26
+
+### Fixed
+- `Modules\Core\Search\ProductIndexer::toSearchableArray()` threw `column reference "id" is ambiguous` on Postgres when computing `channel_ids` — `$model->channels()->wherePivot('enabled', true)->pluck('id')` joins `lunar_channels` and `lunar_channelables`, both of which have an `id` column, and the unqualified `pluck('id')` left Postgres unable to resolve which table's column to select (SQLite/MySQL tolerated the ambiguity). Qualified as `pluck('lunar_channels.id')`.
+
+## [0.5.2] - 2026-08-26
+
+### Fixed
+- `Modules\Core\Localization\LocaleMiddleware`'s shared view data only ever surfaced a single alternate locale (`altLocale`/`altLocaleUrl`, found via `firstWhere('code', '!=', $current)`) — correct by coincidence for a 2-language store, but silently dropped every locale past the first "other" one found for a 3+ language store, with no error. Replaced with `altLocales`, a collection of every other configured language (`code`, `name`, `url` for the current route each), so a language switcher or `hreflang` tags scale to any number of locales. Documented in `docs/localization.md` ("Shared view data — language switcher and `hreflang` tags").
+
+## [0.5.1] - 2026-08-25
+
+### Added
+- `Modules\Core\Search\ProductIndexer` now indexes `channel_ids` (filterable) — Lunar's base indexer only marks `status` as filterable, not channel assignment, so storefront search couldn't otherwise scope results to products actually assigned and enabled on the current sales channel. Computed from `$product->channels()->wherePivot('enabled', true)`. Ported from an older `Products` branch whose remote had been deleted; the branch's other, now-superseded `ProductIndexer` changes were dropped in favor of the richer indexer already on `master` (collections, price, variants, reviews — see `0.5.0`).
+
+## [0.5.0] - 2026-08-24
+
+### Added
+- **`Modules\Core\Catalog\ProductService`**: storefront product listing/filtering (`list()`) and single-product lookup (`getById()`, `getBySlug()`), reading directly from the Meilisearch index rather than the database — one data source, no `->get()` model hydration. Returns plain arrays (not Eloquent models), meant to be called directly from a consuming app's controllers.
+  - `ProductFilters` DTO: optional `collectionId`, `brand`, `minPrice`, `maxPrice`, translated into a Meilisearch `filter` expression.
+  - Listing results are locale-aware: `withLocalizedFields()` resolves `name`/`description` from the indexer's per-locale fields, falling back to the store's default language (via `LocaleMiddleware::defaultLocale()`) when the current locale has no translation yet, instead of rendering blank.
+  - `Modules\Core\Search\ProductIndexer` expanded well beyond its original collection/price additions to carry everything a detail page needs: `id`/`slugs` (filterable — `getById()`/`getBySlug()` resolve purely from the index, no database read), `collection_names`, `tags`, the full media gallery, per-variant data (`sku`, `stock`, `purchasable`, translated option/value names + `meta` for swatches, per-currency prices, variant media), and reviews (`reviews`, `review_count`, `average_rating` — public-safe fields only, `reviewer_email` deliberately excluded).
+  - `Modules\Core\Providers\ReviewServiceProvider` (newly registered): re-indexes a product whenever one of its reviews is created/updated/deleted, since a review write doesn't touch the `Product` row and so never fires the product's own model events.
+- **`Modules\Core\Search\ProductSearchService`**: locale-aware full-text product search on top of the same Meilisearch index, for use by a storefront's search bar — separate from `ProductService`, which is for browsing/filtering without a query term.
+- `docs/product-listing.md` and `docs/product-search.md` — usage, full field reference, and design notes for the two services above.
+- `docs/lunar.md` "Gotchas": three new entries hit while building this — `ProductOption`/`ProductOptionValue::name` isn't `attribute_data` (so `translateAttribute()` silently returns `null` for it), a running `queue:work` process not picking up an edited Scout indexer class, and Scout's `paginateRaw()->items()` on the Meilisearch driver returning the whole raw response rather than a hit list.
+
+### Fixed
+- The admin login form (`Modules\Core\Auth\Filament\Pages\Login`) had no way back from the OTP-entry step to the email step short of reloading the page. A `back()` method resets to the email step; a "← Back" link/button is shown on the OTP step only.
+
+## [0.4.0] - 2026-08-06
+
+### Added
+- **Locale-prefixed routing** (`Modules\Core\Localization\LocaleMiddleware`): a `locale` route-middleware alias, opt-in per shop (not pushed onto the `web` group globally, since admin/Livewire/webhook routes must not be locale-redirected). Reads the first URL segment against Lunar's own `languages` table, sets `App::setLocale()`, and redirects unprefixed/unknown-locale requests to a resolved locale (`Accept-Language` match → default language → first language). Every locale is prefixed, including the default (`/el/...`, `/en/...`), never a bare root — avoids the hreflang/duplicate-content ambiguity of a bare-root default locale.
+  - Language list cached with `Cache::rememberForever()`, invalidated via `Modules\Core\Localization\LanguageCacheObserver` dispatching `LanguageCreated`/`LanguageUpdated`/`LanguageDeleted` events (see below) rather than doing the work itself.
+  - **Language rename safety**: renaming a `Language::code` (e.g. `el` → `gr`) no longer strands existing translations. `MigrateTranslationsForRenamedLanguage` (listening on `LanguageUpdated`) migrates every affected `LanguageLine.text` key from the old code to the new one and flushes both codes' translation caches — closing a real data-loss gap where a rename would otherwise make existing `LanguageLine` translations permanently unreachable.
+- **Storefront UI label translations**: pulled in `spatie/laravel-translation-loader` (self-registers via Composer package auto-discovery; its loader *extends* Laravel's file-based `FileLoader` and merges DB translations on top — existing Filament/Lunar vendor `lang/` strings are unaffected). Labels are looked up via Laravel's native `__('storefront.nav.cart')`, kept in its own `storefront` group so nothing collides with Lunar/Filament's own translation groups.
+  - `Modules\Core\Command\InstallLunarCommand` (overriding `lunar:install`) seeds a starter set of ~15 common e-shop labels (`nav.*`, `cart.*`, `product.*`, `auth.*`, `search.*`, English + Greek), idempotently guarded so it's safe on every boot.
+  - `Modules\Core\Localization\TranslationReader::group('storefront')` returns the whole reduced/cached label array for a locale (backed by `LanguageLine`'s own forever-cache) — for sharing to a view as `$labels` or `@json()`-ing to JS, on top of `__()` for single-key Blade lookups.
+  - **Admin UI**: `Modules\Core\Localization\Filament\Resources\LanguageLineResource` (registered in `CorePlugin`) lists/searches/filters `language_lines` and edits each row's `group`, `key`, and one text input per locale currently in `lunar_languages` — locale columns/inputs are generated dynamically from the language list, so a new language needs no resource changes.
+  - **Event-driven writes**: `Modules\Core\Localization\TranslationService` (`create`/`update`/`delete`) is the single write path for `LanguageLine` — the Filament resource's Create/Edit/Delete pages route through it rather than Filament's default direct-model writes. Dispatches `TranslationCreated`/`TranslationUpdated` (carries the full pre-update `{group, key, text}` snapshot, so a bare rename is tracked the same as a text edit)/`TranslationDeleted`, each handled by two listeners:
+    - `FlushTranslationCache` — closes a real gap in `LanguageLine`'s own self-invalidation, which only flushes locales/groups present *after* a save. Flushes the union of old and new group+locale combinations, so a locale removed from `text`, or a `group`/`key` rename, can't leave a stale cached array behind.
+    - `LogTranslationActivity` — audits every write via the existing `Modules\Core\Logging\ActivityLogService` (`lunar` activity log channel), same `created`/`updated`/`deleted` shape as every other domain write in this project. Properties are flattened with `Arr::dot()` before logging (`text.en`, `text.el` instead of a nested `text` object) since Filament's Activity resource renders `properties` with a flat `KeyValue` field that can't display nested arrays.
+- `Modules\Core\Providers\LocalizationServiceProvider` — split out of the growing `CoreServiceProvider` (per this project's own "split when a provider does too much" convention) to own all locale/translation middleware, observer, and event-listener registration.
+
+## [0.3.0] - 2026-07-12
+
+### Added
+- **Meilisearch product search**: pulled in `lunarphp/search` (Lunar's driver-agnostic search abstraction — `database`/`meilisearch`/`typesense` engines, selectable via Scout's own `SCOUT_DRIVER` config) and `lunarphp/meilisearch`, wiring Meilisearch in as the search engine for products.
+  - `Search\ProductIndexer` overrides Lunar's own indexer to strip HTML tags from string fields (e.g. `name_en`, `description_en`) before they reach the search index — Lunar's default indexer sends raw attribute HTML straight through, which pollutes relevance ranking and highlighting with markup.
+  - Meilisearch itself is treated as app-level infrastructure, not a `boboko-core` concern: the actual Meilisearch container, host port, and master key live in each consuming app's own `docker-compose.yml`/`.env` (e.g. `3dealer`), the same way Postgres and Valkey do — `boboko-core` only declares the PHP package dependency and the indexing code.
+
+## [0.2.0] - 2026-07-10
+
+### Added
+- **Product reviews** (`Modules\Core\Review`): a new `ProductReview` model + `product_reviews` table (plain, unprefixed — same convention as `import_mappings`), linked to Lunar's `Product` via a `Product::reviews()` macro (registered in `CorePlugin`, since `Lunar\Models\Product` is a vendor model and can't be edited directly).
+  - **JudgeMe CSV review importer** (`MigrateImport\JudgeMe\JudgeMeExportImporter`), wired into the existing `boboko:migrate:import --source=judgeme --type=export` command: reads a Judge.me review export, resolves each row's `product_handle` to a Lunar product via `Lunar\Models\Url`, and creates/updates `ProductReview` rows idempotently via `import_mappings` (`source=judgeme`, `source_type=review`, keyed on Judge.me's `metaobject_handle`). Rows with no matching product are skipped with a logged warning rather than failing the whole import.
+  - Review images (`picture_urls` in the CSV) are downloaded and stored as real media via Spatie MediaLibrary (`ProductReview::IMAGES_COLLECTION`), not just linked by URL — consistent with how product images are handled.
+  - **Admin UI**: a new "Reviews" sub-navigation page on the product edit screen (`Review\Pages\ManageProductReviews`, wired via `Review\Extensions\ProductResourceExtension`), listing rating/title/reviewer with View, Reply, and Delete actions. The Reply action lets staff write/edit a reply directly from the table, setting `replied_at`. The View modal shows full review detail (body, reviewer email, location, source, dates, reply, downloaded images).
+
+### Fixed
+- `Shopify\ShopifyExportImporter` never wrote a Lunar `Url` (slug) row for imported products, despite `docs/shopify-import.md` specifying it should — meaning no code outside the importer itself could resolve "which Lunar product has handle X" (only the importer's own private `import_mappings` bookkeeping could). It now creates/updates a default `Url` row (`slug` = Shopify handle) per product on every import, which the new JudgeMe review importer depends on for product resolution.
+
 ## [0.1.0] - 2026-07-09
 
 ### Added

composer.json

@@ -2,7 +2,7 @@
   "name": "boboko/core",
   "description": "Core module — authentication and shared panel behaviour",
   "type": "library",
-  "version": "0.1.0",
+  "version": "0.10.1",
   "autoload": {
     "psr-4": {
       "Modules\\Core\\": "src/"
@@ -10,11 +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",
+    "lunarphp/stripe": "^1.5"
   },
   "require-dev": {
     "fakerphp/faker": "^1.23",
@@ -24,20 +28,28 @@
     "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": {
       "providers": [
         "Modules\\Core\\Providers\\CoreServiceProvider",
         "Modules\\Core\\Providers\\AuthServiceProvider",
-        "Modules\\Core\\Providers\\CustomerServiceProvider"
+        "Modules\\Core\\Providers\\CustomerServiceProvider",
+        "Modules\\Core\\Providers\\PaymentServiceProvider",
+        "Modules\\Core\\Providers\\LocalizationServiceProvider",
+        "Modules\\Core\\Providers\\CatalogServiceProvider",
+        "Modules\\Core\\Providers\\CartServiceProvider",
+        "Modules\\Core\\Providers\\ReviewServiceProvider",
+        "Modules\\Core\\Providers\\ShippingServiceProvider"
       ]
     }
   },
   "config": {
     "allow-plugins": {
-      "pestphp/pest-plugin": true
+      "pestphp/pest-plugin": true,
+      "php-http/discovery": true
     }
   }
 }

config/core.php

@@ -16,4 +16,20 @@ return [
 
     'auto_create_customer_for_user' => true,
 
+    /*
+    |--------------------------------------------------------------------------
+    | 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',
+    ],
+
 ];

config/payment.php

@@ -0,0 +1,46 @@
+<?php
+
+use Modules\Core\Payment\Drivers\OfflinePaymentDriver;
+use Modules\Core\Payment\Pipelines\Cart\ApplyCashOnDeliveryFee;
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Lunar payment types merged in by Boboko Core
+    |--------------------------------------------------------------------------
+    |
+    | These are merged into config('lunar.payments.types') so every app using
+    | boboko-core gets cash-on-delivery out of the box, without publishing
+    | Lunar's own config.
+    |
+    | 'payment_driver' is boboko-owned, alongside Lunar's own 'driver' key —
+    | it's the Modules\Core\Checkout\Contracts\PaymentDriver class
+    | CheckoutService::confirmPayment() resolves via the container and calls
+    | confirm() on. Kept on the same row as 'driver' rather than a second,
+    | separately-keyed map, so a type's full definition — Lunar's driver,
+    | its config, and its PaymentDriver — lives in one place.
+    |
+    */
+    'types' => [
+        'cash-on-delivery' => [
+            'driver' => 'offline',
+            'payment_driver' => OfflinePaymentDriver::class,
+            'authorized' => 'awaiting-payment',
+            'fee' => 0,
+        ],
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Lunar cart pipeline additions
+    |--------------------------------------------------------------------------
+    |
+    | Appended to config('lunar.cart.pipelines.cart') after ApplyShipping so
+    | the cash-on-delivery fee is added to the shipping total before the
+    | final Calculate step sums everything up.
+    |
+    */
+    'cart_pipeline' => [
+        ApplyCashOnDeliveryFee::class,
+    ],
+];

config/scout.php

@@ -0,0 +1,210 @@
+<?php
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Default Search Engine
+    |--------------------------------------------------------------------------
+    |
+    | This option controls the default search connection that gets used while
+    | using Laravel Scout. This connection is used when syncing all models
+    | to the search service. You should adjust this based on your needs.
+    |
+    | Supported: "algolia", "meilisearch", "typesense",
+    |            "database", "collection", "null"
+    |
+    */
+
+    'driver' => env('SCOUT_DRIVER', 'collection'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Index Prefix
+    |--------------------------------------------------------------------------
+    |
+    | Here you may specify a prefix that will be applied to all search index
+    | names used by Scout. This prefix may be useful if you have multiple
+    | "tenants" or applications sharing the same search infrastructure.
+    |
+    */
+
+    'prefix' => env('SCOUT_PREFIX', ''),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Queue Data Syncing
+    |--------------------------------------------------------------------------
+    |
+    | This option allows you to control if the operations that sync your data
+    | with your search engines are queued. When this is set to "true" then
+    | all automatic data syncing will get queued for better performance.
+    |
+    */
+
+    'queue' => env('SCOUT_QUEUE', false),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Database Transactions
+    |--------------------------------------------------------------------------
+    |
+    | This configuration option determines if your data will only be synced
+    | with your search indexes after every open database transaction has
+    | been committed, thus preventing any discarded data from syncing.
+    |
+    */
+
+    'after_commit' => false,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Chunk Sizes
+    |--------------------------------------------------------------------------
+    |
+    | These options allow you to control the maximum chunk size when you are
+    | mass importing data into the search engine. This allows you to fine
+    | tune each of these chunk sizes based on the power of the servers.
+    |
+    */
+
+    'chunk' => [
+        'searchable' => 500,
+        'unsearchable' => 500,
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Soft Deletes
+    |--------------------------------------------------------------------------
+    |
+    | This option allows to control whether to keep soft deleted records in
+    | the search indexes. Maintaining soft deleted records can be useful
+    | if your application still needs to search for the records later.
+    |
+    */
+
+    'soft_delete' => false,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Identify User
+    |--------------------------------------------------------------------------
+    |
+    | This option allows you to control whether to notify the search engine
+    | of the user performing the search. This is sometimes useful if the
+    | engine supports any analytics based on this application's users.
+    |
+    | Supported engines: "algolia"
+    |
+    */
+
+    'identify' => env('SCOUT_IDENTIFY', false),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Algolia Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Here you may configure your Algolia settings. Algolia is a cloud hosted
+    | search engine which works great with Scout out of the box. Just plug
+    | in your application ID and admin API key to get started searching.
+    |
+    */
+
+    'algolia' => [
+        'id' => env('ALGOLIA_APP_ID', ''),
+        'secret' => env('ALGOLIA_SECRET', ''),
+        'index-settings' => [
+            // 'users' => [
+            //     'searchableAttributes' => ['id', 'name', 'email'],
+            //     'attributesForFaceting'=> ['filterOnly(email)'],
+            // ],
+        ],
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Meilisearch Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Here you may configure your Meilisearch settings. Meilisearch is an open
+    | source search engine with minimal configuration. Below, you can state
+    | the host and key information for your own Meilisearch installation.
+    |
+    | See: https://www.meilisearch.com/docs/learn/configuration/instance_options#all-instance-options
+    |
+    */
+
+    'meilisearch' => [
+        'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
+        'key' => env('MEILISEARCH_KEY'),
+        'index-settings' => [
+            // 'users' => [
+            //     'filterableAttributes'=> ['id', 'name', 'email'],
+            // ],
+        ],
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Typesense Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Here you may configure your Typesense settings. Typesense is an open
+    | source search engine using minimal configuration. Below, you will
+    | state the host, key, and schema configuration for the instance.
+    |
+    */
+
+    'typesense' => [
+        'client-settings' => [
+            'api_key' => env('TYPESENSE_API_KEY', 'xyz'),
+            'nodes' => [
+                [
+                    'host' => env('TYPESENSE_HOST', 'localhost'),
+                    'port' => env('TYPESENSE_PORT', '8108'),
+                    'path' => env('TYPESENSE_PATH', ''),
+                    'protocol' => env('TYPESENSE_PROTOCOL', 'http'),
+                ],
+            ],
+            'nearest_node' => [
+                'host' => env('TYPESENSE_HOST', 'localhost'),
+                'port' => env('TYPESENSE_PORT', '8108'),
+                'path' => env('TYPESENSE_PATH', ''),
+                'protocol' => env('TYPESENSE_PROTOCOL', 'http'),
+            ],
+            'connection_timeout_seconds' => env('TYPESENSE_CONNECTION_TIMEOUT_SECONDS', 2),
+            'healthcheck_interval_seconds' => env('TYPESENSE_HEALTHCHECK_INTERVAL_SECONDS', 30),
+            'num_retries' => env('TYPESENSE_NUM_RETRIES', 3),
+            'retry_interval_seconds' => env('TYPESENSE_RETRY_INTERVAL_SECONDS', 1),
+        ],
+        // 'max_total_results' => env('TYPESENSE_MAX_TOTAL_RESULTS', 1000),
+        'model-settings' => [
+            // User::class => [
+            //     'collection-schema' => [
+            //         'fields' => [
+            //             [
+            //                 'name' => 'id',
+            //                 'type' => 'string',
+            //             ],
+            //             [
+            //                 'name' => 'name',
+            //                 'type' => 'string',
+            //             ],
+            //             [
+            //                 'name' => 'created_at',
+            //                 'type' => 'int64',
+            //             ],
+            //         ],
+            //         'default_sorting_field' => 'created_at',
+            //     ],
+            //     'search-parameters' => [
+            //         'query_by' => 'name'
+            //     ],
+            // ],
+        ],
+        'import_action' => env('TYPESENSE_IMPORT_ACTION', 'upsert'),
+    ],
+
+];

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,47 @@
+<?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.
+|
+| 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_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'),
+
+    '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_10_000001_create_product_reviews_table.php

@@ -0,0 +1,32 @@
+<?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('product_reviews', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('product_id')->constrained(config('lunar.database.table_prefix').'products');
+            $table->string('title')->nullable();
+            $table->text('body')->nullable();
+            $table->unsignedTinyInteger('rating');
+            $table->timestamp('reviewed_at')->nullable();
+            $table->string('reviewer_name')->nullable();
+            $table->string('reviewer_email')->nullable();
+            $table->text('reply')->nullable();
+            $table->timestamp('replied_at')->nullable();
+            $table->string('location')->nullable();
+            $table->string('source')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('product_reviews');
+    }
+};

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_05_210535_create_language_lines_table.php

@@ -0,0 +1,34 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     *
+     * @return void
+     */
+    public function up(): void
+    {
+        Schema::create('language_lines', function (Blueprint $table) {
+            $table->id();
+            $table->string('group')->index();
+            $table->string('key');
+            $table->json('text');
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     *
+     * @return void
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('language_lines');
+    }
+};

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');
+    }
+};

docs/cart.md

@@ -0,0 +1,272 @@
+# Cart Admin Visibility
+
+`Modules\Core\Cart\Filament\Resources\CartResource` gives staff read-only visibility into
+customer/user carts in the Filament admin panel. 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: only carts with a known customer or user
+
+`CartResource::getEloquentQuery()` filters to `Cart::whereNotNull('user_id')->orWhereNotNull('customer_id')`
+— an anonymous guest's session cart is excluded entirely.
+
+This was a deliberate call, not an oversight: 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. 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`). Lunar's own `Cart` model already gets `user_id`/`customer_id` set the moment a
+shopper is authenticated (via `Lunar\Listeners\CartSessionAuthListener` on login), with no
+checkout step required — so scoping to "identifiable" here is broader than Shopify's
+equivalent, not a copy of it.
+
+---
+
+## 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:
+
+- **Ongoing** — `scopeActive()` and recent `updated_at` (within `abandonedCutoff()`). Default
+  active tab on page load.
+- **Abandoned Cart** — `whereDoesntHave('orders')` and stale `updated_at`.
+- **Abandoned Checkout** — has an order with `placed_at IS NULL`, and stale `updated_at`.
+- **Completed** — has an order with `placed_at IS NOT NULL`.
+
+```php
+// Ongoing
+$query->active()->where('updated_at', '>', CartResource::abandonedCutoff());
+
+// Abandoned Cart
+$query->whereDoesntHave('orders')->where('updated_at', '<=', CartResource::abandonedCutoff());
+
+// Abandoned Checkout
+$query->whereHas('orders', fn ($q) => $q->whereNull('placed_at'))
+    ->where('updated_at', '<=', CartResource::abandonedCutoff());
+
+// Completed
+$query->whereHas('orders', fn ($q) => $q->whereNotNull('placed_at'));
+```
+
+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()->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
+queries the same two branches `ListCarts::getTabs()` uses (no order at all vs. draft order
+never placed) and dispatches `Modules\Core\Recovery\Events\CartAbandoned`/`CheckoutAbandoned`
+for anything currently stale.
+
+### 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

@@ -0,0 +1,271 @@
+# Localization
+
+Storefront routes can be locale-prefixed (`/el/proionta`, `/en/products`) using a middleware
+that reads directly from Lunar's `languages` table — the same table the Filament **Languages**
+resource manages, so there's no separate locale config to keep in sync.
+
+---
+
+## Why prefix every locale, including the default
+
+Leaving the default locale bare at the root (`/proionta` for Greek, `/en/products` for English)
+creates ambiguity: is `/` the language-neutral homepage or specifically the Greek version? It
+also complicates `hreflang` (needs a self-referencing tag on the root plus a possibly-duplicate
+`x-default`) and risks duplicate content if a bot or campaign link reaches the root without a
+language signal.
+
+Prefixing every locale avoids this: every URL unambiguously declares its language, `hreflang`
+tags are symmetrical, and adding a locale later requires no URL restructuring.
+
+---
+
+## Opt-in, not global
+
+The middleware is registered as a **named alias** (`locale`), not pushed onto the `web`
+middleware group. Apply it explicitly to the route group(s) that make up your storefront:
+
+```php
+// routes/web.php
+use Illuminate\Support\Facades\Route;
+
+Route::middleware('locale')->group(function () {
+    Route::get('/{locale}', HomeController::class);
+    Route::get('/{locale}/proionta', ProductIndexController::class);
+    Route::get('/{locale}/proionta/{slug}', ProductShowController::class);
+});
+```
+
+It is **not** applied automatically because storefront routes aren't the only routes living
+under `web` in a shop:
+
+- The Filament admin panel (`/boboko*`, see `PanelServiceProvider`) has its own routing/auth
+  concerns and must never be locale-redirected.
+- Livewire's internal update endpoint (`/livewire/update`) must resolve without a locale prefix.
+- Webhooks, health checks, and other non-storefront routes shouldn't be touched.
+
+If a shop's entire `web.php` *is* the storefront, wrapping the whole file in the group above is
+fine — just keep admin/Livewire/webhook routes registered outside of it (as they already are).
+
+---
+
+## Behavior
+
+`Modules\Core\Localization\Middleware\LocaleMiddleware`:
+
+1. Reads the first path segment (`request()->segment(1)`).
+2. Matches it against `Lunar\Models\Language::code`.
+   - **Match** — `App::setLocale($code)` is set, and `locale` / `language` request attributes
+     are populated for controllers/views to use.
+   - **No match** (missing, wrong, or unknown segment) — redirects to the same path prefixed
+     with a resolved locale:
+     - the best match from the `Accept-Language` header against available language codes, or
+     - the language flagged `default` in the `languages` table, or
+     - the first language row, as a last resort.
+
+The language list is cached with `Cache::rememberForever()` under `core.localization.languages`
+and invalidated automatically. Adding, editing, or removing a language via the Filament
+**Languages** resource clears the cache immediately — no TTL, no stale reads.
+
+### How invalidation is wired (event-driven, not the observer itself)
+
+`Modules\Core\Localization\Observers\LanguageCacheObserver` observes `Lunar\Models\Language`'s
+`created`/`updated`/`deleted` Eloquent events, but it's a thin trigger only — it doesn't do any
+invalidation work itself. It dispatches one of three events from
+`Modules\Core\Localization\Events` (`LanguageCreated`, `LanguageUpdated` — carrying the old
+`code` — or `LanguageDeleted`), and two listeners, wired in
+`Modules\Core\Providers\LocalizationServiceProvider`, react:
+
+- **`FlushLanguageCache`** — flushes `core.localization.languages` on all three events.
+- **`MigrateTranslationsForRenamedLanguage`** — `LanguageUpdated` only, and only when `code`
+  actually changed. A renamed `Language::code` (e.g. `el` → `gr`) would otherwise strand every
+  `LanguageLine`'s translated text under the old, now-unroutable key —
+  `getTranslationsForGroup('gr', ...)` would silently return nothing for that locale even though
+  the translated content still exists. This listener moves the `text.{oldCode}` key to
+  `text.{newCode}` on every affected `LanguageLine` row and flushes both the old and new code's
+  translation cache for every group touched.
+
+Deleting a `Language` only flushes the language-list cache — `LanguageLine.text` keys for the
+deleted code are left in place rather than destructively erased, in case the language is ever
+re-added under the same code.
+
+Splitting cache-flush and text-migration into separate listeners (rather than one
+`LanguageCacheObserver` method doing both) mirrors the same event → listener pattern used for
+`TranslationService`'s writes below — the observer only detects *what happened*, listeners own
+*what to do about it*.
+
+---
+
+## Reading the resolved locale/language downstream
+
+```php
+// In a controller or view composer
+$locale = $request->attributes->get('locale');      // e.g. "el"
+$language = $request->attributes->get('language');   // Lunar\Models\Language instance
+```
+
+Use `$language->id` when querying Lunar's translatable content (e.g. `Url::where('language_id', ...)`).
+
+### Shared view data — language switcher and `hreflang` tags
+
+The middleware also shares two variables with every view, via `View::share()`, so a layout's
+language switcher or `hreflang` tags don't have to recompute the language list themselves:
+
+```blade
+{{-- current locale --}}
+{{ $currentLocale }}   {{-- e.g. "el" --}}
+
+{{-- every OTHER configured language, each with its own URL for the current page --}}
+@foreach ($altLocales as $altLocale)
+    <a href="{{ $altLocale['url'] }}" hreflang="{{ $altLocale['code'] }}">{{ $altLocale['name'] }}</a>
+@endforeach
+```
+
+`$altLocales` is a **collection**, not a single value — deliberately, so it scales to any number
+of configured languages rather than assuming exactly two. Each entry is a plain array:
+
+| Key | Description |
+|---|---|
+| `code` | The language's `Lunar\Models\Language::code` (e.g. `en`) |
+| `name` | The language's display name |
+| `url` | The **current route**, re-generated with that language's code — via `route($routeName, [...])` when the current request matched a named route, or a bare `/{code}` fallback otherwise |
+
+A 3+ language store gets one `$altLocales` entry per additional language automatically — nothing
+about this shape assumes or special-cases a two-language store.
+
+---
+
+## Single-language shops
+
+If a shop has only one row in `languages`, the middleware still enforces the prefix (e.g. every
+URL under `/en/...`) rather than special-casing it away — this keeps behavior identical across
+shops and avoids a silent restructuring if a second language is added later. If a shop genuinely
+never wants locale prefixes, don't apply the `locale` middleware to its routes at all.
+
+---
+
+## Storefront UI labels (`__('storefront.*')`)
+
+The `locale` middleware resolves *which* language a request is in — routing/redirects,
+`Lunar\Models\Language`, and Lunar's own translatable product/collection content. It has nothing
+to do with static UI chrome like "Cart", "Back", "Add to Cart". Those are handled separately by
+[`spatie/laravel-translation-loader`](https://github.com/spatie/laravel-translation-loader),
+stored in the `language_lines` table.
+
+### Why a separate system, not another `languages`-table lookup
+
+Lunar's translatable fields (`TranslatedText`, `Url`, etc.) are all tied to specific *model
+records* — a product's name, a collection's description. UI labels aren't attached to any model;
+they're static strings the app itself owns. `laravel-translation-loader` is Laravel's own
+`__()`/`trans()` mechanism with a DB-backed source layered on top of the normal file-based one —
+no new helper to learn, no bespoke table shape.
+
+**Nothing existing breaks.** The package's `TranslationLoaderManager` *extends* Laravel's
+`FileLoader` and merges DB translations on top of file-based ones
+(`array_replace_recursive()`) — Filament's own vendor `lang/en/product.php`-style strings
+keep working exactly as before. The package registers itself via Laravel's standard Composer
+package auto-discovery (`extra.laravel.providers` in its own `composer.json`) — nothing needed
+in `CoreServiceProvider` to wire it up.
+
+### Usage
+
+```blade
+{{ __('storefront.nav.cart') }}
+{{ __('storefront.product.add_to_cart') }}
+```
+
+`group` is `storefront` for e-shop UI labels — kept separate from Lunar/Filament's own `lunar::`
+namespaced groups so nothing collides. `__()` resolves the translation for whatever
+`App::getLocale()` currently is, which `LocaleMiddleware` already sets per-request (see
+"Behavior" above) — no extra wiring needed between the two systems.
+
+### Fallback locale follows the store's default language, not `config('app.fallback_locale')`
+
+`spatie/laravel-translation-loader`'s stock `LanguageLine::getTranslation()` falls back to
+`config('app.fallback_locale')` — a static `.env` value — when a key has no text for the current
+locale. That's a second, disconnected "default language" concept: an admin changing the default
+language via the Filament **Languages** resource has no effect on it, so an untranslated label
+could silently fall back to the wrong language.
+
+`Modules\Core\Localization\Models\LanguageLine` overrides `getTranslation()` to fall back to
+`LanguageCache::defaultLocale()` instead — the same `languages.default` flag `LocaleMiddleware`
+already treats as the single source of truth. It's swapped in via
+`config('translation-loader.model')` (the package's own documented extension point for
+"any model that extends `LanguageLine`"), set in `LocalizationServiceProvider::register()` so it
+wins regardless of provider boot order (Laravel's `mergeConfigFrom()` only fills in config keys
+not already set, so an explicit `register()`-time set always beats the package's own default).
+No consuming app configuration needed — this is automatic once `LocalizationServiceProvider` is
+registered.
+
+### Seeding
+
+A starter set of common e-shop labels (`nav.*`, `cart.*`, `product.*`, `auth.*`, `search.*`,
+`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
+
+`Modules\Core\Localization\Filament\Resources\LanguageLineResource` (registered in
+`CorePlugin`, under the panel's Settings group) lists/searches/filters `language_lines` and
+edits each row's `group`, `key`, and one text input per row currently in `lunar_languages` —
+the locale columns are generated dynamically from `Language::query()->pluck('code')`, so adding
+a third language automatically adds a third input, no resource changes needed.
+
+### `TranslationService` — writes go through here, not the model directly
+
+`Modules\Core\Localization\Services\TranslationService` wraps create/update/delete on `LanguageLine` and
+dispatches a domain event after each write, following this project's standard event-driven
+pattern (see `modules.md`'s "Splitting Service Providers" / event-listener convention —
+the same shape as `Modules\Core\Auth\Events\UserCreated`):
+
+```php
+use Modules\Core\Localization\Services\TranslationService;
+
+app(TranslationService::class)->create('storefront', 'nav.wishlist', [
+    'en' => 'Wishlist',
+    'el' => 'Λίστα Επιθυμιών',
+]);
+
+app(TranslationService::class)->update(
+    $languageLine,
+    'storefront',
+    'nav.wishlist',
+    ['en' => 'Wishlist ♥', 'el' => 'Λίστα Επιθυμιών ♥'],
+);
+
+app(TranslationService::class)->delete($languageLine);
+```
+
+`update()` takes the full `group`/`key`/`text` state, not just `text` — a rename is a normal
+update, not a special case. `TranslationCreated`, `TranslationUpdated` (carries the full
+`{group, key, text}` snapshot from *before* the update, so a listener can tell a rename from a
+text edit), and `TranslationDeleted` are dispatched from `Modules\Core\Localization\Events`. Two
+listeners are wired in `Modules\Core\Providers\LocalizationServiceProvider` for all three events:
+
+- **`FlushTranslationCache`** — `LanguageLine::boot()` already flushes the cache for the
+  *current* group's locales present after a save, but misses two cases on update: locales a save
+  *removed* from `text` (e.g. dropping the `el` key leaves `storefront.el` stale), and a changed
+  `group`/`key` (the *old* group's cached array is never told a row left it). This listener
+  flushes every group+locale combination touched by either the old or new state, so nothing —
+  including the group a row was renamed away from — can remain stale.
+- **`LogTranslationActivity`** — records the change via `Modules\Core\Logging\ActivityLogService`
+  on the `lunar` activity log channel, same `created`/`updated`/`deleted` shape as every other
+  domain write in this project. A rename shows up in the log as an `old`/`attributes` diff across
+  `group`, `key`, and `text` together, not just a text diff.
+
+The Filament resource's Create/Edit/Delete pages route through `TranslationService` (via
+`handleRecordCreation`/`handleRecordUpdate`/the delete action's `->action()` override) rather
+than Filament's default direct-model calls, so **every** edit made in the admin UI — including a
+bare `group`/`key` rename with no `text` change — dispatches `TranslationUpdated` and is both
+cache-invalidated and audit-logged.

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,3 +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\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/product-listing.md

@@ -0,0 +1,239 @@
+# Product Listing
+
+`Modules\Core\Catalog\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.
+
+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.
+
+---
+
+## Why it reads from the index, not the database
+
+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\Catalog\Services\ProductIndexer` is built to
+carry that full shape.
+
+---
+
+## Usage
+
+```php
+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);
+
+// Filter by collection, brand, price range, and/or stock
+$products = $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);
+
+$products->items();            // array of Meilisearch documents (plain arrays, not models)
+$products->total();
+$products->perPage();
+$products->currentPage();
+$products->lastPage();
+$products->links();            // in a Blade view — renders pagination links as usual
+
+// 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
+
+// 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, for sizing a price-range slider.
+// 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.
+$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()` for `price` instead, which reads Meilisearch's `facetStats` (min/max), a different
+feature from `facetDistribution`.
+
+---
+
+## 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\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` | 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. |
+| `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` | `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.
+
+**`ProductOption`/`ProductOptionValue` names need a different translation accessor.** Unlike
+`Product`/`Collection`/`Brand`, their `name` is a plain locale-keyed array cast, not
+`attribute_data` — Lunar's `translateAttribute('name')` silently returns `null` for them. The
+indexer's `translatedName()` reads the array directly instead. See `docs/lunar.md` "Gotchas".
+
+---
+
+## Locale resolution: `name`, `description`, and any other translated attribute
+
+Lunar's base `ScoutIndexer` explodes every `TranslatedText` attribute into one `{handle}_{locale}`
+field per store language at index time (`name_el`, `name_en`, `description_el`, ... — and the same
+for any custom translated attribute a store adds, e.g. `seo_title`/`seo_description`). Every raw
+document in Meilisearch carries all of them side by side, since a document is written once but
+read across many different-locale requests.
+
+`ProductService` resolves these back down to a single value per request. For every result it
+returns (`list()`'s items, `getById()`, `getBySlug()`), it:
+
+1. Reads which `Product` attributes are `TranslatedText` from `Lunar\Base\AttributeManifest` — the
+   same source Lunar's own indexer reads — rather than a hardcoded `['name', 'description']` list,
+   so a store's own custom translated attributes are picked up automatically with no change here.
+2. For each one, resolves `{handle}_{currentLocale}`, falling back to `{handle}_{storeDefaultLocale}`
+   (`LanguageCache::defaultLocale()`) if the current locale has no translation — e.g. a product with
+   no English copy yet still shows its Greek name on `/en/` rather than rendering blank.
+3. Assigns the result to a plain `{handle}` key and **strips every raw `{handle}_{locale}` key** —
+   callers only ever see `$product['name']`/`$product['seo_title']`/etc., never the per-locale
+   fields the index actually stores.
+
+`description` and other translated attributes are otherwise indexed as-is, including any HTML
+markup (e.g. from a Shopify `Body (HTML)` import) — **not stripped**. Any view rendering a
+description sourced from `ProductService`'s results must treat it as trusted HTML.
+
+---
+
+## Reviews
+
+`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.
+`Modules\Core\Providers\ReviewServiceProvider` listens on `ProductReview`'s `created`/`updated`/
+`deleted` events and calls `$review->product->searchable()`, so the parent product's document
+stays current without waiting for the next full reindex. This provider must be registered in
+`composer.json`'s `extra.laravel.providers` (already done in this repo) — see `docs/modules.md`
+"Provider Registration Pitfalls" for what happens if a provider like this is ever added but not
+registered.
+
+---
+
+## Multi-variant products and price
+
+A product's `price` is its *cheapest* variant's price ("from €19.99" style), not every variant's
+price. A price-range filter matches based on that single minimum — a product with one cheap
+variant and several expensive ones will match a low-price-range filter even though most of its
+variants don't.
+
+---
+
+## Sorting
+
+`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\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.
+
+Omitting `sort` leaves Meilisearch's default ordering, which is meaningless here since `list()`
+always searches with an empty query string (`Product::search('')`) — there's no relevance score to
+rank by, so results come back in whatever order the index returns them absent an explicit sort.
+
+---
+
+## Registering the indexer
+
+Not automatic — an app opts in via its own `config/lunar/search.php`:
+
+```php
+'indexers' => [
+    Lunar\Models\Product::class => Modules\Core\Catalog\Services\ProductIndexer::class,
+    // ...other model indexers unchanged
+],
+```
+
+## Re-syncing after this change
+
+Filterable attributes are Meilisearch index settings, not computed per-query — changing them
+requires re-syncing settings and reindexing existing documents:
+
+```bash
+php artisan lunar:meilisearch:setup
+php artisan lunar:search:index "Lunar\Models\Product" --refresh
+```
+
+**If `SCOUT_QUEUE=true`, restart the queue worker after deploying an indexer change.** A running
+`queue:work` process loads PHP classes once at boot and keeps that code in memory for its entire
+lifetime — it does not pick up an edited/newly-deployed indexer class. Symptoms: reindexing
+commands succeed with no errors, `Product::toSearchableArray()` returns the new fields correctly
+when called directly (e.g. via `artisan tinker`, which always boots fresh), but documents written
+via `$model->searchable()` through the live queue are still missing the new fields. Restarting the
+queue worker (`docker compose restart queue`, or equivalent) resolves it — no code change needed.
+
+---
+
+## Meilisearch driver quirk: `paginateRaw()`'s `items()` is not a list of hits
+
+For the Meilisearch engine specifically, Scout's `Builder::paginateRaw()` puts the **entire raw
+response** (`hits`, `query`, `processingTimeMs`, `hitsPerPage`, `page`, `totalPages`, `totalHits`)
+into the paginator's `items()`, not a plain array of documents. Calling `$paginator->items()`
+and treating it as a list (e.g. `collect($paginator->items())->values()`) silently produces a
+7-element array whose first element happens to be the real hits and the rest are stray scalars
+from the other response keys — no error, just wrong data leaking into what looks like a normal
+list. `ProductService::list()` pulls `$paginator->items()['hits']` explicitly to avoid this;
+`$paginator->total()`/`perPage()`/`currentPage()`/`lastPage()` are unaffected and safe to use
+as-is.

docs/product-options.md

@@ -0,0 +1,113 @@
+# Product Option Types
+
+Lunar's `ProductOption`/`ProductOptionValue` are generic by design — a "Color" option
+and a "Size" option are both just a handle, a translated name, and a list of values.
+Each `ProductOptionValue` carries a free-form `meta` jsonb column, but nothing in
+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\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.
+
+---
+
+## Registering a type
+
+A shop registers a type class from its own service provider's `boot()`, the same
+shape as `Modules\Core\Notification\NotificationRegistry`:
+
+```php
+use Modules\Core\Catalog\Services\ProductOptionTypeManager;
+
+ProductOptionTypeManager::get()->register([
+    \App\ProductOptions\ColorOptionType::class,
+]);
+```
+
+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.
+
+---
+
+## Writing a type
+
+```php
+namespace App\ProductOptions;
+
+use Filament\Forms\Components\ColorPicker;
+use Modules\Core\Catalog\Contracts\ProductOptionTypeInterface;
+
+class ColorOptionType implements ProductOptionTypeInterface
+{
+    public static function getKey(): string
+    {
+        return 'color';
+    }
+
+    public function getMetaForm(): array
+    {
+        return [
+            ColorPicker::make('meta.hex')
+                ->label('Color')
+                ->required(),
+        ];
+    }
+}
+```
+
+`getMetaForm()` returns Filament form components, keyed under `meta.*` dot notation
+— the path they save to on `ProductOptionValue::meta` (cast as `AsArrayObject`, a
+plain jsonb column). `getKey()` is the identifier used in the admin's "Option Type"
+dropdown and in `ProductOption::meta['option_type']` — it has no relationship to the
+`ProductOption::handle`.
+
+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\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\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\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
+  field. A `ProductOption` with no type selected gets the stock form unchanged.
+
+---
+
+## Reading the value back
+
+Storefront code reads `ProductOptionValue::meta` like any other jsonb column — e.g.
+`$value->meta['hex']` for a color swatch. `ProductOptionTypeManager` is an admin-side
+concern only (describing *how to edit* the meta); nothing requires the storefront to
+go through it to *read* the meta.

docs/product-search.md

@@ -0,0 +1,81 @@
+# Product Search
+
+`Modules\Core\Catalog\Services\ProductSearchService` provides locale-aware full-text product search on
+top of Laravel Scout + Meilisearch.
+
+---
+
+## Why locale-aware search isn't a filter
+
+Lunar's Meilisearch indexer (`Lunar\Search\ScoutIndexer::mapSearchableAttributes()`) flattens
+every translated attribute into **locale-suffixed fields on a single document** — a product with
+a translated `name` produces `name_en`, `name_el`, etc. as separate top-level fields, not
+separate documents per locale and not a filterable `locale` field.
+
+That means "search in Greek" isn't a `->filter('locale = el')` — Meilisearch has no such field to
+filter on. It's a choice of **which fields the query targets**: `name_el`/`description_el`
+instead of `name_en`/`description_en`. This is what Meilisearch's `attributesToSearchOn` search
+parameter controls, exposed through Scout via `Builder::options()`, which passes straight through
+to the underlying Meilisearch client call (`Laravel\Scout\Engines\MeilisearchEngine::performSearch()`
+merges `$builder->options` directly into the search request).
+
+---
+
+## Usage
+
+```php
+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');
+```
+
+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.
+
+---
+
+## Missing-translation fallback
+
+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.
+
+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.
+
+---
+
+## Field list is dynamic, not hardcoded
+
+The set of attribute handles searched (`name`, `description`, or whatever else) comes from
+`Lunar\Facades\AttributeManifest::getSearchableAttributes(Product::morphName())` — the same
+source `ScoutIndexer` itself uses to decide what gets indexed. If an admin marks a new attribute
+searchable in the panel, `ProductSearchService` picks it up automatically; nothing in this class
+needs to change.
+
+---
+
+## Re-syncing after indexer changes
+
+Changing which attributes are searchable, or `ProductIndexer`'s filterable/sortable fields,
+requires re-syncing Meilisearch's index settings and re-indexing existing documents:
+
+```bash
+php artisan lunar:meilisearch:setup
+php artisan lunar:search:index "Lunar\Models\Product" --refresh
+```
+
+`ProductSearchService` itself needs no re-sync when locales change — `attributesToSearchOn` is
+computed per-query from the live language list, not baked into index settings.

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/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>

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

@@ -46,6 +46,10 @@
                 <x-filament::button type="submit" class="w-full">
                     Sign in
                 </x-filament::button>
+
+                <x-filament::link wire:click="back" tag="button" type="button" class="mx-auto">
+                    &larr; Back
+                </x-filament::link>
             </div>
         </form>
     @endif

resources/views/shipping/filament/pages/manage-pickup-manifests.blade.php

@@ -0,0 +1,3 @@
+<x-filament-panels::page>
+    {{ $this->table }}
+</x-filament-panels::page>

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 = '';
@@ -35,6 +35,12 @@ class Login extends SimplePage
         }
     }
 
+    public function back(): void
+    {
+        $this->otpSent = false;
+        $this->otp = '';
+    }
+
     public function requestOtp(): void
     {
         $this->validate(['email' => 'required|email']);
@@ -72,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/Cart/Commands/DetectAbandonedCarts.php

@@ -0,0 +1,84 @@
+<?php
+
+namespace Modules\Core\Cart\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Event;
+use Lunar\Models\Cart;
+use Modules\Core\Cart\Filament\Resources\CartResource;
+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.
+ */
+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(): void
+    {
+        $cutoff = CartResource::abandonedCutoff();
+
+        $cartsAbandoned = 0;
+        $checkoutsAbandoned = 0;
+
+        Cart::query()
+            ->whereDoesntHave('orders')
+            ->where('updated_at', '<=', $cutoff)
+            ->with('lines')
+            ->chunkById(200, function ($carts) use (&$cartsAbandoned) {
+                foreach ($carts as $cart) {
+                    if ($cart->lines->isEmpty()) {
+                        continue;
+                    }
+
+                    Event::dispatch(new CartAbandoned($cart));
+
+                    $cartsAbandoned++;
+                }
+            });
+
+        Cart::query()
+            ->whereHas('orders', fn ($query) => $query->whereNull('placed_at'))
+            ->where('updated_at', '<=', $cutoff)
+            ->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,124 @@
+<?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\Database\Eloquent\Builder;
+use Illuminate\Support\Carbon;
+use Lunar\Admin\Filament\Resources\CustomerResource;
+use Lunar\Models\Cart;
+use Modules\Core\Cart\Filament\Resources\CartResource\Pages;
+
+/**
+ * Read-only — a cart is managed entirely through the storefront (add/update/remove
+ * line, checkout), never hand-edited by staff. Scoped to carts with a known
+ * `user_id`/`customer_id` only: an anonymous guest's session cart carries no
+ * identity a staff member could act on (no name, no email, nothing to follow up
+ * with), so listing every such row would be noise, not a real admin capability —
+ * see docs/cart.md for the reasoning (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';
+
+    public static function getEloquentQuery(): Builder
+    {
+        return parent::getEloquentQuery()
+            ->where(fn (Builder $query) => $query->whereNotNull('user_id')->orWhereNotNull('customer_id'));
+    }
+
+    /**
+     * 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();
+    }
+
+    /**
+     * `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 now()->sub(config('core.cart.abandoned_after', '1 hour'));
+    }
+
+    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,56 @@
+<?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;
+
+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.
+     *
+     * "Ongoing" vs the two abandoned tabs all split on `updated_at` against
+     * `CartResource::abandonedCutoff()` — Lunar has no time-based staleness
+     * signal of its own, so recent activity is the only thing distinguishing a
+     * cart someone is shopping in right now from one genuinely left behind.
+     */
+    public function getTabs(): array
+    {
+        return [
+            'abandoned_cart' => Tab::make('Abandoned Cart')
+                ->modifyQueryUsing(fn(Builder $query) => $query
+                    ->whereDoesntHave('orders')
+                    ->where('updated_at', '<=', CartResource::abandonedCutoff())),
+            'abandoned_checkout' => Tab::make('Abandoned Checkout')
+                ->modifyQueryUsing(fn(Builder $query) => $query
+                    ->whereHas('orders', fn(Builder $query) => $query->whereNull('placed_at'))
+                    ->where('updated_at', '<=', CartResource::abandonedCutoff())),
+
+            'ongoing' => Tab::make('Ongoing')
+                ->modifyQueryUsing(fn(Builder $query) => $query->active()->where('updated_at', '>', CartResource::abandonedCutoff())),
+            'completed' => Tab::make('Completed')
+                ->modifyQueryUsing(fn(Builder $query) => $query->whereHas(
+                    'orders',
+                    fn(Builder $query) => $query->whereNotNull('placed_at'),
+                )),
+        ];
+    }
+}

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

@@ -0,0 +1,112 @@
+<?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\RepeatableEntry;
+use Filament\Infolists\Components\TextEntry;
+use Filament\Resources\Pages\ViewRecord;
+use Lunar\Admin\Filament\Resources\CustomerResource;
+use Lunar\Models\Cart;
+use Lunar\Models\CartLine;
+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.
+     */
+    protected function resolveRecord(int|string $key): Cart
+    {
+        /** @var Cart $cart */
+        $cart = parent::resolveRecord($key);
+
+        return $cart->calculate();
+    }
+
+    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([
+                                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('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);
+    }
+}

src/Cart/Services/CartService.php

@@ -0,0 +1,250 @@
+<?php
+
+namespace Modules\Core\Cart\Services;
+
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Event;
+use Lunar\Actions\Carts\GetExistingCartLine;
+use Lunar\Base\Purchasable;
+use Lunar\Facades\CartSession;
+use Lunar\Facades\Discounts;
+use Lunar\Models\Cart;
+use Lunar\Models\CartLine;
+use Modules\Core\Cart\Events\CartCleared;
+use Modules\Core\Cart\Events\CartCouponApplied;
+use Modules\Core\Cart\Events\CartCouponRemoved;
+use Modules\Core\Cart\Events\CartLineAdded;
+use Modules\Core\Cart\Events\CartLineMovedToCart;
+use Modules\Core\Cart\Events\CartLineRemoved;
+use Modules\Core\Cart\Events\CartLineSaved;
+use Modules\Core\Cart\Events\CartLineUpdated;
+use Modules\Core\Cart\Exceptions\InvalidCouponException;
+
+/**
+ * Storefront-facing cart operations, mirroring 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.
+ *
+ * Every mutating method dispatches a matching domain event
+ * (Modules\Core\Cart\Events\*) after the underlying Lunar operation completes —
+ * Lunar itself dispatches zero cart events (see docs/lunar.md's Cart gotchas),
+ * so without this, nothing in a consuming app has anything to react to when a
+ * cart actually changes (reindexing, notifications, analytics, etc.).
+ *
+ * All mutating methods return the recalculated Cart — matching Lunar's own
+ * Cart::add()/updateLine()/etc., which already return $this after
+ * refresh()->recalculate() — so a caller gets fresh totals in the same call,
+ * no second fetch needed.
+ */
+class CartService
+{
+    /**
+     * The current session's cart, or null if none exists yet. Does NOT
+     * auto-create one — see currentOrCreate() for that.
+     */
+    public function current(): ?Cart
+    {
+        return CartSession::current();
+    }
+
+    /**
+     * The current session's cart, creating one if none exists yet — the right
+     * call for "add to cart" style flows where a cart must exist by the time
+     * the method returns.
+     */
+    public function currentOrCreate(): Cart
+    {
+        return CartSession::manager();
+    }
+
+    public function addLine(Purchasable $purchasable, int $quantity = 1, array $meta = []): Cart
+    {
+        $cart = $this->currentOrCreate()->add($purchasable, $quantity, $meta);
+
+        $line = app(config('lunar.cart.actions.get_existing_cart_line', GetExistingCartLine::class))
+            ->execute($cart, $purchasable, $meta);
+
+        if ($line !== null) {
+            Event::dispatch(new CartLineAdded($cart, $line));
+        }
+
+        return $cart;
+    }
+
+    public function updateLine(int $cartLineId, int $quantity, ?array $meta = null): Cart
+    {
+        $before = CartLine::findOrFail($cartLineId);
+        $old = ['quantity' => $before->quantity, 'meta' => $before->meta->toArray()];
+
+        $cart = $this->currentOrCreate()->updateLine($cartLineId, $quantity, $meta);
+
+        $line = $cart->lines->firstWhere('id', $cartLineId);
+
+        if ($line !== null) {
+            Event::dispatch(new CartLineUpdated($cart, $line, $old));
+        }
+
+        return $cart;
+    }
+
+    public function removeLine(int $cartLineId): Cart
+    {
+        $line = CartLine::findOrFail($cartLineId);
+        $snapshot = $this->snapshotLine($line);
+
+        $cart = $this->currentOrCreate()->remove($cartLineId);
+
+        Event::dispatch(new CartLineRemoved($cart, $snapshot));
+
+        return $cart;
+    }
+
+    public function clear(): Cart
+    {
+        $cart = $this->currentOrCreate();
+        $snapshots = $cart->lines->map($this->snapshotLine(...))->all();
+
+        $cart = $cart->clear();
+
+        Event::dispatch(new CartCleared($cart, $snapshots));
+
+        return $cart;
+    }
+
+    /**
+     * Sets the cart's coupon code, which the ApplyDiscounts pipeline step picks
+     * up on the next calculate() — there's no dedicated Lunar action for this
+     * (unlike add/update/remove, coupon_code is a plain cast attribute), so
+     * this is the closest thing to one for a consuming app to call.
+     *
+     * Validated via Discounts::validateCoupon() (does a matching, currently
+     * active, non-exhausted Discount exist?) before it's set — 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.
+     *
+     * @throws InvalidCouponException if the code doesn't match a valid, active,
+     *   non-exhausted Discount
+     */
+    public function applyCoupon(string $code): Cart
+    {
+        if (! Discounts::validateCoupon($code)) {
+            throw new InvalidCouponException($code);
+        }
+
+        $cart = $this->currentOrCreate();
+        $cart->coupon_code = $code;
+        $cart->save();
+        $cart = $cart->recalculate();
+
+        Event::dispatch(new CartCouponApplied($cart, $cart->coupon_code));
+
+        return $cart;
+    }
+
+    public function removeCoupon(): Cart
+    {
+        $cart = $this->currentOrCreate();
+        $code = $cart->coupon_code;
+
+        if ($code === null) {
+            return $cart;
+        }
+
+        $cart->coupon_code = null;
+        $cart->save();
+        $cart = $cart->recalculate();
+
+        Event::dispatch(new CartCouponRemoved($cart, $code));
+
+        return $cart;
+    }
+
+    /**
+     * Lines currently counted toward the cart's totals — everything except
+     * ones flagged meta.saved_for_later (see savedLines()). This is the set a
+     * cart page's main list / checkout would iterate, since a saved line
+     * isn't pending purchase.
+     *
+     * @return Collection<int, CartLine>
+     */
+    public function activeLines(?Cart $cart = null): Collection
+    {
+        $cart ??= $this->currentOrCreate();
+
+        return $cart->lines->reject(fn (CartLine $line) => $line->meta['saved_for_later'] ?? false)->values();
+    }
+
+    /**
+     * Lines a shopper has deliberately parked rather than deleted — excluded
+     * from Cart totals (see Modules\Core\Cart\Pipelines\ZeroSavedForLaterPrice)
+     * and from activeLines(). A cart page's "Saved for later" section iterates
+     * this set.
+     *
+     * @return Collection<int, CartLine>
+     */
+    public function savedLines(?Cart $cart = null): Collection
+    {
+        $cart ??= $this->currentOrCreate();
+
+        return $cart->lines->filter(fn (CartLine $line) => $line->meta['saved_for_later'] ?? false)->values();
+    }
+
+    /**
+     * Moves a line OUT of the purchasable cart without deleting it — it stays
+     * on the cart (still visible, still re-addable) but is excluded from
+     * totals via meta.saved_for_later, zeroed by ZeroSavedForLaterPrice before
+     * Lunar's own CalculateLines sums the cart (which has no meta-based
+     * exclusion of its own).
+     */
+    public function saveForLater(int $cartLineId): Cart
+    {
+        $line = CartLine::findOrFail($cartLineId);
+        $meta = [...$line->meta->toArray(), 'saved_for_later' => true];
+
+        $cart = $this->currentOrCreate()->updateLine($cartLineId, $line->quantity, $meta);
+
+        $line = $cart->lines->firstWhere('id', $cartLineId);
+
+        if ($line !== null) {
+            Event::dispatch(new CartLineSaved($cart, $line));
+        }
+
+        return $cart;
+    }
+
+    /**
+     * The reverse of saveForLater() — moves a line back into the purchasable
+     * cart, counted in totals again.
+     */
+    public function moveToCart(int $cartLineId): Cart
+    {
+        $line = CartLine::findOrFail($cartLineId);
+        $meta = [...$line->meta->toArray(), 'saved_for_later' => false];
+
+        $cart = $this->currentOrCreate()->updateLine($cartLineId, $line->quantity, $meta);
+
+        $line = $cart->lines->firstWhere('id', $cartLineId);
+
+        if ($line !== null) {
+            Event::dispatch(new CartLineMovedToCart($cart, $line));
+        }
+
+        return $cart;
+    }
+
+    /**
+     * @return array{id: int, purchasable_type: string, purchasable_id: int, quantity: int, meta: array}
+     */
+    private function snapshotLine(CartLine $line): array
+    {
+        return [
+            'id' => $line->id,
+            'purchasable_type' => $line->purchasable_type,
+            'purchasable_id' => $line->purchasable_id,
+            'quantity' => $line->quantity,
+            'meta' => $line->meta->toArray(),
+        ];
+    }
+}

src/Catalog/Contracts/ProductOptionTypeInterface.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Modules\Core\Catalog\Contracts;
+
+use Filament\Schemas\Components\Component;
+
+/**
+ * A Product Option Type describes how a category of Lunar `ProductOption` (e.g.
+ * "Color", "Size", "Material") behaves — namely, what structured data its values
+ * carry in their free-form `meta` jsonb column, and how an admin edits that data.
+ *
+ * `ProductOption`/`ProductOptionValue` themselves stay exactly as Lunar defines
+ * them — this is not a new model. `ProductOptionTypeManager` maps a
+ * `ProductOption::handle` to the type describing it (via `config('core.product_option_types')`,
+ * typed explicitly by the admin), so adding a new kind of option is a single new
+ * class, not scattered per-option special-casing across the admin UI or storefront.
+ */
+interface ProductOptionTypeInterface
+{
+    /**
+     * Matches the ProductOption::handle this type describes (e.g. 'color', 'size').
+     */
+    public static function getKey(): string;
+
+    /**
+     * Filament form components for editing a ProductOptionValue's `meta` under this
+     * option type — e.g. Color returns a color picker for `meta.hex`, Size returns a
+     * numeric input for `meta.sort_value`. Field names should be dot-notation under
+     * `meta` (e.g. `meta.hex`), matching where ValuesRelationManagerExtension saves them.
+     *
+     * @return array<Component>
+     */
+    public function getMetaForm(): array;
+}

src/Catalog/DTOs/CollectionFilters.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Core\Catalog\DTOs;
+
+/**
+ * Filter input for CollectionService::list(). All fields are optional — omitted
+ * filters are simply not added to the Meilisearch query. Values are matched
+ * against Modules\Core\Catalog\Services\CollectionIndexer's document fields, so
+ * filtering only works on stores where that indexer is registered and the index
+ * has been re-synced (see docs/product-listing.md).
+ */
+class CollectionFilters
+{
+    /**
+     * @param $parentId children of this specific parent collection.
+     * @param $rootOnly top-level collections only (`parent_id IS NULL`) — mutually
+     *   exclusive with $parentId; if both are set, $parentId wins.
+     */
+    public function __construct(
+        public readonly ?int $parentId = null,
+        public readonly ?int $groupId = null,
+        public readonly bool $rootOnly = false,
+    ) {}
+}

src/Catalog/DTOs/ProductFilters.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Modules\Core\Catalog\DTOs;
+
+/**
+ * Filter input for ProductService::list(). All fields are optional — omitted
+ * filters are simply not added to the Meilisearch query. Values are matched
+ * against Modules\Core\Catalog\Services\ProductIndexer's document fields, so
+ * filtering only works on stores where that indexer is registered and the index
+ * has been re-synced (see docs/product-listing.md).
+ */
+class ProductFilters
+{
+    /**
+     * @param $collectionId matches a product in this collection OR any of its
+     *   descendant collections (filtered against ProductIndexer's `collection_ids`,
+     *   not a direct-assignment-only match) — the right semantics for "products on
+     *   this category page", since products are typically attached only to leaf
+     *   collections.
+     */
+    public function __construct(
+        public readonly ?int $collectionId = null,
+        public readonly ?string $brand = null,
+        public readonly ?float $minPrice = null,
+        public readonly ?float $maxPrice = null,
+        public readonly bool $inStockOnly = false,
+    ) {}
+}

src/Catalog/Enums/CollectionSort.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Core\Catalog\Enums;
+
+/**
+ * Sort options for CollectionService::list(), each mapped to a Meilisearch `sort`
+ * clause against a field indexed as sortable by Modules\Core\Catalog\Services\
+ * CollectionIndexer (see its getSortableFields()).
+ */
+enum CollectionSort: string
+{
+    case Position = 'position';
+    case Name = 'name';
+    case Newest = 'newest';
+
+    public function toMeilisearchSort(): string
+    {
+        return match ($this) {
+            self::Position => '_lft:asc',
+            self::Name => 'name:asc',
+            self::Newest => 'created_at:desc',
+        };
+    }
+}

src/Catalog/Enums/ProductSort.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Modules\Core\Catalog\Enums;
+
+/**
+ * Sort options for ProductService::list(), each mapped to a Meilisearch `sort`
+ * clause against a field indexed as sortable by Modules\Core\Catalog\Services\
+ * ProductIndexer (see its getSortableFields()). Adding a case here requires the
+ * matching field to also be sortable in the index, re-synced via
+ * `php artisan lunar:meilisearch:setup`.
+ */
+enum ProductSort: string
+{
+    case PriceAsc = 'price_asc';
+    case PriceDesc = 'price_desc';
+    case Newest = 'newest';
+
+    public function toMeilisearchSort(): string
+    {
+        return match ($this) {
+            self::PriceAsc => 'price:asc',
+            self::PriceDesc => 'price:desc',
+            self::Newest => 'created_at:desc',
+        };
+    }
+}

src/Catalog/Filament/Extensions/ProductOptionResourceExtension.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace Modules\Core\Catalog\Filament\Extensions;
+
+use Filament\Schemas\Schema;
+use Filament\Forms\Components\Select;
+use Illuminate\Support\Str;
+use Lunar\Admin\Support\Extending\ResourceExtension;
+use Modules\Core\Catalog\Services\ProductOptionTypeManager;
+
+/**
+ * Adds an "Option Type" dropdown to Lunar's own ProductOptionResource form, letting
+ * an admin pick which registered `ProductOptionTypeInterface` (if any) describes this
+ * option's values — e.g. "Color" — independent of the option's own `handle`. The
+ * selection is saved to `ProductOption::meta['option_type']`.
+ */
+class ProductOptionResourceExtension extends ResourceExtension
+{
+    public function extendForm(Schema $schema): Schema
+    {
+        $options = collect(ProductOptionTypeManager::get()->all())
+            ->keys()
+            ->mapWithKeys(fn (string $key) => [$key => Str::headline($key)])
+            ->all();
+
+        if ($options === []) {
+            return $schema;
+        }
+
+        return $schema->components([
+            ...$schema->getComponents(),
+            Select::make('meta.option_type')
+                ->label('Option Type')
+                ->options($options)
+                ->helperText('Controls which meta fields appear when editing this option\'s values.')
+                ->native(false),
+        ]);
+    }
+}

src/Catalog/Filament/Extensions/ValuesRelationManagerExtension.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Modules\Core\Catalog\Filament\Extensions;
+
+use Filament\Schemas\Schema;
+use Lunar\Admin\Support\Extending\RelationManagerExtension;
+use Lunar\Models\ProductOption;
+use Modules\Core\Catalog\Services\ProductOptionTypeManager;
+
+/**
+ * Appends the owning `ProductOption`'s registered `ProductOptionTypeInterface` meta
+ * form (if any) to Lunar's own ValuesRelationManager form, so e.g. a "color" option
+ * gets a hex-color picker for each value alongside the stock name field — without
+ * forking Lunar's relation manager.
+ */
+class ValuesRelationManagerExtension extends RelationManagerExtension
+{
+    public function extendForm(Schema $schema): Schema
+    {
+        /** @var ProductOption $option */
+        $option = $this->caller->getOwnerRecord();
+
+        $type = ProductOptionTypeManager::get()->resolve($option->meta['option_type'] ?? null);
+
+        if ($type === null) {
+            return $schema;
+        }
+
+        return $schema->components([
+            ...$schema->getComponents(),
+            ...$type->getMetaForm(),
+        ]);
+    }
+}

src/Catalog/Observers/ProductOptionReindexObserver.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Modules\Core\Catalog\Observers;
+
+use Illuminate\Support\Facades\DB;
+use Lunar\Models\Product;
+use Lunar\Models\ProductOption;
+use Lunar\Models\ProductOptionValue;
+use Lunar\Models\ProductVariant;
+
+/**
+ * Keeps every product using a ProductOption/ProductOptionValue in sync with
+ * Meilisearch. ProductIndexer::mapVariant() embeds each option value's `meta`
+ * (e.g. a color's hex) directly into the product's indexed document — but saving
+ * the option or one of its values never fires the *product's* own save/update
+ * events, so without this, a changed option_type or a changed hex would only
+ * reach the index on that product's next unrelated reindex.
+ */
+class ProductOptionReindexObserver
+{
+    public function optionSaved(ProductOption $option): void
+    {
+        $this->reindexProductsForOption($option->id);
+    }
+
+    public function optionDeleted(ProductOption $option): void
+    {
+        $this->reindexProductsForOption($option->id);
+    }
+
+    public function valueSaved(ProductOptionValue $value): void
+    {
+        $this->reindexProductsForValues([$value->id]);
+    }
+
+    public function valueDeleted(ProductOptionValue $value): void
+    {
+        $this->reindexProductsForValues([$value->id]);
+    }
+
+    private function reindexProductsForOption(int $optionId): void
+    {
+        $valueIds = ProductOptionValue::where('product_option_id', $optionId)->pluck('id');
+
+        $this->reindexProductsForValues($valueIds->all());
+    }
+
+    private function reindexProductsForValues(array $valueIds): void
+    {
+        if ($valueIds === []) {
+            return;
+        }
+
+        $prefix = config('lunar.database.table_prefix');
+
+        $variantIds = DB::table("{$prefix}product_option_value_product_variant")
+            ->whereIn('value_id', $valueIds)
+            ->pluck('variant_id');
+
+        if ($variantIds->isEmpty()) {
+            return;
+        }
+
+        $productIds = ProductVariant::whereIn('id', $variantIds)->pluck('product_id')->unique();
+
+        Product::whereIn('id', $productIds)->get()->each->searchable();
+    }
+}

src/Catalog/OptionTypes/ColorOptionType.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Modules\Core\Catalog\OptionTypes;
+
+use Filament\Forms\Components\ColorPicker;
+use Modules\Core\Catalog\Contracts\ProductOptionTypeInterface;
+
+/**
+ * Describes a 'color' ProductOption's values as carrying a hex code in
+ * `meta.hex`, editable via a Filament color picker. Registered automatically by
+ * `Modules\Core\Providers\CatalogServiceProvider` — a shop's admin still has to
+ * pick "Color" from the Option Type dropdown per-ProductOption for it to apply.
+ */
+class ColorOptionType implements ProductOptionTypeInterface
+{
+    public static function getKey(): string
+    {
+        return 'color';
+    }
+
+    public function getMetaForm(): array
+    {
+        return [
+            ColorPicker::make('meta.hex')
+                ->label('Color')
+                ->required(),
+        ];
+    }
+}

src/Catalog/Services/CollectionIndexer.php

@@ -0,0 +1,91 @@
+<?php
+
+namespace Modules\Core\Catalog\Services;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use Lunar\Models\Collection;
+use Lunar\Models\Product;
+use Lunar\Search\CollectionIndexer as BaseCollectionIndexer;
+
+/**
+ * Extends Lunar's own indexer so Modules\Core\Catalog\Services\CollectionService can
+ * serve category browsing/nav AND single-collection lookups from Meilisearch alone,
+ * the same reasoning as Modules\Core\Catalog\Services\ProductIndexer. Lunar's base
+ * indexer only carries `id`/`name`/`created_at` — nowhere near enough for a storefront
+ * category page or a nav tree. Adds:
+ *   - parent_id, _lft, _rgt (filterable/sortable) — the nested-set tree position, so
+ *     CollectionService can resolve "children of X" or build a full tree without a
+ *     database read
+ *   - collection_group_id (filterable) — mirrors Collection::scopeInGroup()
+ *   - slugs (filterable) — every locale's Url::slug, so getBySlug() resolves from the
+ *     index directly, no database read
+ *   - thumbnail (display) — the collection's thumbnail image URL
+ *   - ancestors (display) — [{id, name}, ...] ordered root-first, so a breadcrumb can
+ *     render directly from a single indexed document with zero extra queries
+ *   - product_count (display) — how many products are in this collection or any of
+ *     its descendants, read from the *product* Meilisearch index at collection-index
+ *     time (via `collection_ids`, see Modules\Core\Catalog\Services\ProductIndexer) —
+ *     matches what ProductService::list(ProductFilters(collectionId: ...)) would
+ *     return, not just direct assignment. Reflects the product index's state as of
+ *     the last collection reindex, so re-run `lunar:search:index --refresh` after a
+ *     product reindex if this needs to be current.
+ *
+ * New 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.
+ */
+class CollectionIndexer extends BaseCollectionIndexer
+{
+    public function getFilterableFields(): array
+    {
+        return [
+            ...parent::getFilterableFields(),
+            'id',
+            'parent_id',
+            '_lft',
+            'collection_group_id',
+            'slugs',
+        ];
+    }
+
+    public function getSortableFields(): array
+    {
+        return [
+            ...parent::getSortableFields(),
+            '_lft',
+        ];
+    }
+
+    public function makeAllSearchableUsing(Builder $query): Builder
+    {
+        return parent::makeAllSearchableUsing($query)->with(['urls', 'media', 'ancestors']);
+    }
+
+    public function toSearchableArray(Model $model): array
+    {
+        /** @var Collection $model */
+        $data = parent::toSearchableArray($model);
+
+        $data['parent_id'] = $model->parent_id;
+        $data['_lft'] = $model->_lft;
+        $data['_rgt'] = $model->_rgt;
+        $data['collection_group_id'] = $model->collection_group_id;
+        $data['slugs'] = $model->urls->pluck('slug')->unique()->values()->all();
+        $data['thumbnail'] = $model->getThumbnailImage() ?: null;
+        $data['ancestors'] = $model->ancestors
+            ->sortBy('_lft')
+            ->map(fn ($ancestor) => [
+                'id' => $ancestor->id,
+                'name' => $ancestor->translateAttribute('name'),
+            ])
+            ->values()
+            ->all();
+        $data['product_count'] = Product::search('')
+            ->options(['filter' => "collection_ids = \"{$model->id}\""])
+            ->paginateRaw(perPage: 1, page: 1)
+            ->total();
+
+        return $data;
+    }
+}

src/Catalog/Services/CollectionService.php

@@ -0,0 +1,147 @@
+<?php
+
+namespace Modules\Core\Catalog\Services;
+
+use Illuminate\Contracts\Pagination\LengthAwarePaginator as LengthAwarePaginatorContract;
+use Illuminate\Pagination\LengthAwarePaginator;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\App;
+use Lunar\Base\AttributeManifest;
+use Lunar\FieldTypes\TranslatedText;
+use Lunar\Models\Collection as CollectionModel;
+use Modules\Core\Catalog\DTOs\CollectionFilters;
+use Modules\Core\Catalog\Enums\CollectionSort;
+use Modules\Core\Localization\Services\LanguageCache;
+
+/**
+ * Category browsing (tree/nav) AND single-collection lookup, all reading directly
+ * from the Meilisearch index (Modules\Core\Catalog\Services\CollectionIndexer) — same
+ * shape and reasoning as Modules\Core\Catalog\Services\ProductService. Callers get
+ * plain arrays of the indexed document, not Eloquent models.
+ */
+class CollectionService
+{
+    public function __construct(
+        private readonly LanguageCache $languages,
+        private readonly AttributeManifest $attributes,
+    ) {}
+
+    /**
+     * Returns a real LengthAwarePaginator (not Scout's own paginateRaw() result — see
+     * ProductService's "Meilisearch driver quirk" note) so a controller/view gets
+     * normal pagination behaviour without ever touching the raw Meilisearch response.
+     */
+    public function list(?CollectionFilters $filters = null, int $perPage = 24, int $page = 1, ?CollectionSort $sort = null): LengthAwarePaginator
+    {
+        $options = ['filter' => $this->buildFilter($filters)];
+
+        if ($sort !== null) {
+            $options['sort'] = [$sort->toMeilisearchSort()];
+        }
+
+        $paginator = CollectionModel::search('')
+            ->options($options)
+            ->paginateRaw(perPage: $perPage, page: $page);
+
+        $data = collect($this->hitsFrom($paginator))
+            ->map(fn (array $collection) => $this->withLocalizedFields($collection))
+            ->all();
+
+        return new LengthAwarePaginator(
+            items: $data,
+            total: $paginator->total(),
+            perPage: $paginator->perPage(),
+            currentPage: $paginator->currentPage(),
+            options: ['path' => LengthAwarePaginator::resolveCurrentPath()],
+        );
+    }
+
+    /**
+     * Look up a single collection by its URL slug (any locale). Returns the full
+     * indexed collection document, or null if no collection has that slug.
+     */
+    public function getBySlug(string $slug): ?array
+    {
+        return $this->findOneWhere('slugs = "'.addcslashes($slug, '"\\').'"');
+    }
+
+    /**
+     * Look up a single collection by its primary key. Returns the full indexed
+     * collection document, or null if no collection has that id.
+     */
+    public function getById(int $id): ?array
+    {
+        return $this->findOneWhere("id = \"{$id}\"");
+    }
+
+    private function findOneWhere(string $filter): ?array
+    {
+        $paginator = CollectionModel::search('')
+            ->options(['filter' => $filter])
+            ->paginateRaw(perPage: 1, page: 1);
+
+        $collection = $this->hitsFrom($paginator)[0] ?? null;
+
+        return $collection !== null ? $this->withLocalizedFields($collection) : null;
+    }
+
+    /**
+     * Resolves every translated Collection attribute's current-locale value — same
+     * logic as ProductService::withLocalizedFields(), see there for the full
+     * reasoning (AttributeManifest-driven, store-default-locale fallback, raw
+     * per-locale keys stripped after resolving).
+     */
+    private function withLocalizedFields(array $collection): array
+    {
+        $locale = App::getLocale();
+        $fallbackLocale = $this->languages->defaultLocale();
+        $availableLocales = $this->languages->availableLocales();
+
+        foreach ($this->translatedAttributeHandles() as $handle) {
+            $collection[$handle] = $collection[$handle.'_'.$locale] ?? $collection[$handle.'_'.$fallbackLocale] ?? null;
+
+            foreach ($availableLocales as $availableLocale) {
+                unset($collection[$handle.'_'.$availableLocale]);
+            }
+        }
+
+        return $collection;
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function translatedAttributeHandles(): array
+    {
+        return $this->attributes->getSearchableAttributes((new CollectionModel)->getMorphClass())
+            ->filter(fn ($attribute) => $attribute->type === TranslatedText::class)
+            ->pluck('handle')
+            ->all();
+    }
+
+    /**
+     * For the Meilisearch driver, Scout's paginateRaw() puts the whole raw response
+     * in items(), not a plain list of hits — see ProductService's identical note.
+     */
+    private function hitsFrom(LengthAwarePaginatorContract $paginator): array
+    {
+        $rawResponse = $paginator->items();
+
+        return collect($rawResponse['hits'] ?? [])->values()->all();
+    }
+
+    private function buildFilter(?CollectionFilters $filters): ?string
+    {
+        if ($filters === null) {
+            return null;
+        }
+
+        $clauses = Collection::make([
+            $filters->parentId !== null ? "parent_id = \"{$filters->parentId}\""
+                : ($filters->rootOnly ? 'parent_id IS NULL' : null),
+            $filters->groupId !== null ? "collection_group_id = \"{$filters->groupId}\"" : null,
+        ])->filter();
+
+        return $clauses->isEmpty() ? null : $clauses->join(' AND ');
+    }
+}

src/Catalog/Services/ProductIndexer.php

@@ -0,0 +1,221 @@
+<?php
+
+namespace Modules\Core\Catalog\Services;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use Lunar\Models\Currency;
+use Lunar\Models\Price;
+use Lunar\Models\Product;
+use Lunar\Models\ProductVariant;
+use Lunar\Search\ProductIndexer as BaseProductIndexer;
+use Modules\Core\Review\Models\ProductReview;
+use Spatie\MediaLibrary\MediaCollections\Models\Media;
+
+/**
+ * Extends Lunar's own indexer so Modules\Core\Catalog\Services\ProductService can
+ * serve both listing/filtering AND single-product lookups from Meilisearch alone —
+ * one data source, no separate database read path for a product detail page. Adds:
+ *   - collections: [{id, name}, ...] — directly assigned collections only, for
+ *     display (breadcrumbs, "also in"). Not filterable — see collection_ids below.
+ *   - collection_ids (filterable): flat array of every directly-assigned collection's
+ *     id UNIONED with all of its ancestors' ids. Products are typically attached only
+ *     to leaf collections in a Shopify-imported tree, so a plain `collections.id`
+ *     filter would never match a parent/root category page — ProductService::list()
+ *     filters `collectionId` against this field instead, so "products in category X"
+ *     also picks up every product attached only to one of X's subcategories.
+ *   - slugs (every locale's Url::slug for the product, filterable) — lets
+ *     ProductService::getBySlug() resolve a product from the index directly, with
+ *     no database read at all
+ *   - price (cheapest variant, filterable) and full per-variant pricing
+ *   - variants: sku, stock, purchasable, option values, prices, media
+ *   - the full media gallery (not just the single thumbnail Lunar's base indexer sends)
+ *   - tags
+ *   - reviews: {items: [...], count, average_rating} — items are public-safe fields
+ *     only (see mapReview() — reviewer_email is deliberately excluded, it's PII with
+ *     no storefront use), including staff replies
+ *   - channel_ids (filterable) — Lunar's base indexer only indexes "status" as
+ *     filterable, not channel assignment, so search results can't otherwise be
+ *     scoped to products actually assigned+enabled on the current sales channel
+ *   - in_stock (filterable) — true if ANY variant can currently be purchased at
+ *     quantity 1, via ProductVariant::canBeFulfilledAtQuantity() (Lunar's own
+ *     purchasability rule: `purchasable === 'always'` is always true regardless of
+ *     stock, `in_stock` checks stock alone, anything else checks stock+backorder).
+ *     Reflects stock as of the last reindex only — nothing currently reindexes a
+ *     product when an order decrements its stock (see docs/product-listing.md).
+ *
+ * A review is created/edited independently of its product (Modules\Core\Providers\
+ * ReviewServiceProvider re-indexes the product on review create/update/delete), so
+ * this data doesn't go stale between full reindexes.
+ *
+ * New fields aren't filterable 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 — see docs/product-listing.md. If SCOUT_QUEUE is enabled, the
+ * queue worker also needs restarting after deploying changes to this class (see
+ * docs/lunar.md "Gotchas" — a running worker keeps stale indexer code in memory).
+ */
+class ProductIndexer extends BaseProductIndexer
+{
+    public function getFilterableFields(): array
+    {
+        return [
+            ...parent::getFilterableFields(),
+            'id',
+            'brand',
+            'collection_ids',
+            'price',
+            'slugs',
+            'channel_ids',
+            'in_stock',
+        ];
+    }
+
+    public function getSortableFields(): array
+    {
+        return [
+            ...parent::getSortableFields(),
+            'price',
+        ];
+    }
+
+    public function makeAllSearchableUsing(Builder $query): Builder
+    {
+        return parent::makeAllSearchableUsing($query)->with([
+            'collections',
+            'collections.ancestors',
+            'media',
+            'tags',
+            'urls',
+            'variants.images',
+            'variants.prices',
+            'variants.values.option',
+        ]);
+    }
+
+    public function toSearchableArray(Model $model): array
+    {
+        /** @var Product $model */
+        $data = parent::toSearchableArray($model);
+
+        $currency = Currency::getDefault();
+        $reviews = ProductReview::where('product_id', $model->id)->with('media')->get();
+
+        $data['collections'] = $model->collections->map(fn ($collection) => [
+            'id' => $collection->id,
+            'name' => $collection->translateAttribute('name'),
+        ])->all();
+        $data['collection_ids'] = $model->collections
+            ->flatMap(fn ($collection) => [$collection->id, ...$collection->ancestors->pluck('id')])
+            ->unique()
+            ->values()
+            ->all();
+        $data['slugs'] = $model->urls->pluck('slug')->unique()->values()->all();
+        $data['tags'] = $model->tags->pluck('value')->all();
+        $data['media'] = $model->media->map(fn (Media $media) => $this->mapMedia($media))->all();
+        $data['variants'] = $model->variants->map(fn (ProductVariant $variant) => $this->mapVariant($variant, $currency))->all();
+        $data['price'] = $this->cheapestPrice($model, $currency);
+        $data['reviews'] = [
+            'items' => $reviews->map(fn (ProductReview $review) => $this->mapReview($review))->all(),
+            'count' => $reviews->count(),
+            'average_rating' => $reviews->isEmpty() ? null : round($reviews->avg('rating'), 1),
+        ];
+        $data['channel_ids'] = $model->channels()
+            ->wherePivot('enabled', true)
+            ->pluck('lunar_channels.id')
+            ->toArray();
+        $data['in_stock'] = $model->variants->contains(
+            fn (ProductVariant $variant) => $variant->canBeFulfilledAtQuantity(1)
+        );
+
+        return $data;
+    }
+
+    private function mapVariant(ProductVariant $variant, Currency $currency): array
+    {
+        return [
+            'id' => $variant->id,
+            'sku' => $variant->sku,
+            'stock' => $variant->stock,
+            'purchasable' => $variant->purchasable,
+            'options' => $variant->values->map(fn ($value) => [
+                'option' => $this->translatedName($value->option->name),
+                'handle' => $value->option->handle,
+                'value' => $this->translatedName($value->name),
+                'meta' => $value->meta,
+            ])->all(),
+            'prices' => $variant->prices->map(fn (Price $price) => [
+                'currency_id' => $price->currency_id,
+                'customer_group_id' => $price->customer_group_id,
+                'price' => $price->price->decimal(),
+                'compare_price' => $price->compare_price?->decimal(),
+                'min_quantity' => $price->min_quantity,
+            ])->all(),
+            'media' => $variant->images->map(fn (Media $media) => $this->mapMedia($media))->all(),
+        ];
+    }
+
+    /**
+     * Public-safe fields only — reviewer_email is PII with no storefront use and is
+     * deliberately excluded, unlike every other column on the review. reply/replied_at
+     * (the staff response) are included since they're meant to be shown alongside the
+     * review on the storefront.
+     */
+    private function mapReview(ProductReview $review): array
+    {
+        return [
+            'id' => $review->id,
+            'title' => $review->title,
+            'body' => $review->body,
+            'rating' => $review->rating,
+            'reviewed_at' => $review->reviewed_at?->timestamp,
+            'reviewer_name' => $review->reviewer_name,
+            'reply' => $review->reply,
+            'replied_at' => $review->replied_at?->timestamp,
+            'location' => $review->location,
+            'media' => $review->media->map(fn (Media $media) => $this->mapMedia($media))->all(),
+        ];
+    }
+
+    /**
+     * ProductOption/ProductOptionValue's `name` is a plain locale-keyed array cast
+     * (AsArrayObject) directly on the column — unlike Product/Collection/Brand, it is
+     * not stored in attribute_data. Lunar's translateAttribute() only reads
+     * attribute_data, so it silently returns null for these two models; this reads
+     * the array directly instead. Falls back to the first available locale if the
+     * current one is missing. Not a general replacement for translateAttribute() —
+     * every other translated field in this indexer (product/collection name and
+     * description) genuinely is attribute_data-backed and translateAttribute() is
+     * correct for those.
+     */
+    private function translatedName(mixed $name): ?string
+    {
+        $names = is_array($name) ? $name : (array) $name;
+
+        return $names[app()->getLocale()] ?? reset($names) ?: null;
+    }
+
+    private function mapMedia(Media $media): array
+    {
+        return [
+            'id' => $media->id,
+            'url' => $media->getUrl(),
+            'thumb' => $media->getUrl('small'),
+        ];
+    }
+
+    /**
+     * The cheapest variant's base price (no customer group) in the default currency,
+     * as a float in major units — e.g. 19.99, not 1999. Null if the product has no
+     * variant with a price in that currency yet, so it's excluded from price filters
+     * rather than sorting to the bottom as if it were free.
+     */
+    private function cheapestPrice(Product $model, Currency $currency): ?float
+    {
+        $price = $model->variants
+            ->flatMap(fn ($variant) => $variant->prices)
+            ->filter(fn ($price) => $price->currency_id === $currency->id && $price->customer_group_id === null)
+            ->min(fn ($price) => $price->price->value);
+
+        return $price !== null ? $price / (10 ** $currency->decimal_places) : null;
+    }
+}

src/Catalog/Services/ProductOptionTypeManager.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Modules\Core\Catalog\Services;
+
+use Modules\Core\Catalog\Contracts\ProductOptionTypeInterface;
+
+/**
+ * Resolves an admin-selected option type key to the `ProductOptionTypeInterface`
+ * describing it. The selection (which key a given `Lunar\Models\ProductOption` uses)
+ * is stored per-option in `ProductOption::meta['option_type']` — deliberately not
+ * tied to the option's `handle`, since a shop's own handle naming (e.g. transliterated
+ * Greek, legacy imports) shouldn't have to match a type's key.
+ *
+ * A singleton registry, same shape as `Modules\Core\Notification\NotificationRegistry`
+ * — a consuming app calls `ProductOptionTypeManager::get()->register([...])` from its
+ * own service provider `boot()`, rather than listing classes in a published config
+ * file.
+ */
+class ProductOptionTypeManager
+{
+    private static ?self $instance = null;
+
+    /** @var array<string, class-string<ProductOptionTypeInterface>> */
+    private array $types = [];
+
+    private function __construct() {}
+
+    public static function get(): static
+    {
+        if (static::$instance === null) {
+            static::$instance = new static();
+        }
+
+        return static::$instance;
+    }
+
+    /**
+     * @param array<class-string<ProductOptionTypeInterface>> $types
+     */
+    public function register(array $types): void
+    {
+        foreach ($types as $class) {
+            $this->types[$class::getKey()] = $class;
+        }
+    }
+
+    public function unregister(string $key): void
+    {
+        unset($this->types[$key]);
+    }
+
+    public function resolve(?string $key): ?ProductOptionTypeInterface
+    {
+        if ($key === null || ! isset($this->types[$key])) {
+            return null;
+        }
+
+        return app($this->types[$key]);
+    }
+
+    /**
+     * @return array<string, class-string<ProductOptionTypeInterface>>
+     */
+    public function all(): array
+    {
+        return $this->types;
+    }
+}

src/Catalog/Services/ProductSearchService.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Modules\Core\Catalog\Services;
+
+use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Support\Facades\App;
+use Lunar\Facades\AttributeManifest;
+use Lunar\Models\Language;
+use Lunar\Models\Product;
+
+/**
+ * Lunar's Meilisearch indexer flattens translated attributes into locale-suffixed
+ * fields on a single document (name_en, name_el, description_en, description_el —
+ * see Lunar\Search\ScoutIndexer::mapSearchableAttributes()), not separate indexes
+ * or a filterable locale field. Locale-aware search means choosing which fields
+ * to search on, not filtering results by locale.
+ */
+class ProductSearchService
+{
+    /**
+     * @return Collection<int, Product>
+     */
+    public function search(string $query, ?string $locale = null): Collection
+    {
+        $locale ??= App::getLocale();
+        $defaultLocale = Language::getDefault()->code;
+
+        return Product::search($query)
+            ->options([
+                'attributesToSearchOn' => $this->searchableFields($locale, $defaultLocale),
+            ])
+            ->get();
+    }
+
+    /**
+     * Target the resolved locale's fields plus the default locale's fields, so a
+     * product that's only ever been translated into the default language still
+     * surfaces when searched in another locale, instead of becoming invisible
+     * until every product is fully translated.
+     *
+     * @return array<int, string>
+     */
+    private function searchableFields(string $locale, string $defaultLocale): array
+    {
+        $handles = AttributeManifest::getSearchableAttributes(Product::morphName())
+            ->pluck('handle');
+
+        $locales = array_unique([$locale, $defaultLocale]);
+
+        return $handles
+            ->crossJoin($locales)
+            ->map(fn (array $pair) => "{$pair[0]}_{$pair[1]}")
+            ->values()
+            ->all();
+    }
+}

src/Catalog/Services/ProductService.php

@@ -0,0 +1,231 @@
+<?php
+
+namespace Modules\Core\Catalog\Services;
+
+use Illuminate\Contracts\Pagination\LengthAwarePaginator as LengthAwarePaginatorContract;
+use Illuminate\Pagination\LengthAwarePaginator;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\App;
+use Lunar\Base\AttributeManifest;
+use Lunar\FieldTypes\TranslatedText;
+use Lunar\Models\Product;
+use Modules\Core\Localization\Services\LanguageCache;
+use Modules\Core\Catalog\DTOs\ProductFilters;
+use Modules\Core\Catalog\Enums\ProductSort;
+
+/**
+ * Storefront product listing/filtering AND single-product lookup, all reading directly
+ * from the Meilisearch index (Modules\Core\Catalog\Services\ProductIndexer) - one data
+ * source, no ->get() model hydration anywhere in this service. Callers get plain arrays
+ * of the indexed document, not Eloquent models.
+ *
+ * Full-text query search lives separately in Modules\Core\Catalog\Services\
+ * ProductSearchService; this service is for browsing/filtering without a search term.
+ */
+class ProductService
+{
+    public function __construct(
+        private readonly LanguageCache $languages,
+        private readonly AttributeManifest $attributes,
+    ) {}
+
+    /**
+     * Returns a real LengthAwarePaginator (not Scout's own paginateRaw() result -
+     * see "Meilisearch driver quirk" below) so a controller/view gets normal
+     * pagination behaviour ($products->links(), JSON serialization, etc.)
+     * without ever touching the raw Meilisearch response directly.
+     */
+    public function list(?ProductFilters $filters = null, int $perPage = 24, int $page = 1, ?ProductSort $sort = null): LengthAwarePaginator
+    {
+        $options = ['filter' => $this->buildFilter($filters)];
+
+        if ($sort !== null) {
+            $options['sort'] = [$sort->toMeilisearchSort()];
+        }
+
+        $paginator = Product::search('')
+            ->options($options)
+            ->paginateRaw(perPage: $perPage, page: $page);
+
+        $data = collect($this->hitsFrom($paginator))
+            ->map(fn (array $product) => $this->withLocalizedFields($product))
+            ->all();
+
+        return new LengthAwarePaginator(
+            items: $data,
+            total: $paginator->total(),
+            perPage: $paginator->perPage(),
+            currentPage: $paginator->currentPage(),
+            options: ['path' => LengthAwarePaginator::resolveCurrentPath()],
+        );
+    }
+
+    /**
+     * Facet value counts for the given filter/field, scoped to the SAME filters
+     * `list()` would apply. Note this does NOT exclude `$field` itself from
+     * `$filters` — e.g. `facets('brand', new ProductFilters(brand: 'Acme'))` would
+     * scope the counts to only "Acme" already, collapsing every other brand's count
+     * to whatever remains under that filter. For a standard "faceted sidebar" (every
+     * brand's count reflecting collection/price/stock filters but NOT the brand
+     * filter itself), build a `$filters` that omits the field being faceted on and
+     * apply that field's own filter separately in the UI/query layer.
+     *
+     * `$field` must be one of ProductIndexer's filterable fields; only discrete-value
+     * fields make sense here (`brand`, `in_stock`) — a numeric field like `price`
+     * would return one "facet" per exact price, not a usable range bucket. Use
+     * `priceRange()` for `price` instead.
+     *
+     * @return array<string, int> facet value => matching product count
+     */
+    public function facets(string $field, ?ProductFilters $filters = null): array
+    {
+        return $this->rawFacets($field, $this->buildFilter($filters))['facetDistribution'][$field] ?? [];
+    }
+
+    /**
+     * The min/max `price` across products matching the given filters (minus
+     * `minPrice`/`maxPrice` themselves, same "scoped but not self-collapsing"
+     * reasoning as `facets()` — a price slider's own bounds shouldn't shrink to
+     * whatever range is currently selected). Backed by Meilisearch's `facetStats`,
+     * not `facetDistribution` — the right feature for a numeric field's range,
+     * where `facets('price')` would otherwise return one entry per exact price.
+     *
+     * @return array{min: ?float, max: ?float} null/null if no product matches
+     */
+    public function priceRange(?ProductFilters $filters = null): array
+    {
+        $filter = $this->buildFilter($filters, exclude: ['price']);
+        $stats = $this->rawFacets('price', $filter)['facetStats']['price'] ?? null;
+
+        return [
+            'min' => $stats['min'] ?? null,
+            'max' => $stats['max'] ?? null,
+        ];
+    }
+
+    private function rawFacets(string $field, ?string $filter): array
+    {
+        return Product::search('')
+            ->options([
+                'filter' => $filter,
+                'facets' => [$field],
+                'hitsPerPage' => 0,
+            ])
+            ->raw();
+    }
+
+    /**
+     * Look up a single product by its URL slug (any locale - slugs are indexed across
+     * all languages, see Modules\Core\Catalog\Services\ProductIndexer). Returns the full
+     * indexed product document, or null if no product has that slug.
+     */
+    public function getBySlug(string $slug): ?array
+    {
+        return $this->findOneWhere('slugs = "'.addcslashes($slug, '"\\').'"');
+    }
+
+    /**
+     * Look up a single product by its primary key. Returns the full indexed product
+     * document, or null if no product has that id.
+     */
+    public function getById(int $id): ?array
+    {
+        return $this->findOneWhere("id = \"{$id}\"");
+    }
+
+    private function findOneWhere(string $filter): ?array
+    {
+        $paginator = Product::search('')
+            ->options(['filter' => $filter])
+            ->paginateRaw(perPage: 1, page: 1);
+
+        $product = $this->hitsFrom($paginator)[0] ?? null;
+
+        return $product !== null ? $this->withLocalizedFields($product) : null;
+    }
+
+    /**
+     * Resolves every translated Product attribute's current-locale value from the
+     * indexer's per-locale `{handle}_{locale}` fields (e.g. `name_el`, `name_en`,
+     * `seo_title_el`, ...) into a plain `{handle}` key, falling back to the store's
+     * default language (LanguageCache::defaultLocale()) when the current locale
+     * has no translation - e.g. a product with no English copy yet still shows its
+     * Greek name on /en/ rather than rendering blank.
+     *
+     * Which handles are translated is read from AttributeManifest - the same
+     * source Lunar's own ScoutIndexer reads when exploding a TranslatedText
+     * attribute into `{handle}_{locale}` keys at index time - rather than a fixed
+     * list, so a store's own custom translated attributes (e.g. `seo_title`) are
+     * picked up automatically with no change here. The raw per-locale keys are
+     * then stripped, since once resolved, callers only ever need the one that
+     * matched the current locale.
+     *
+     * Deliberately not config('app.locale') - App::setLocale() overwrites that
+     * config value on every request, so by request time it's just whatever the
+     * current locale already is, not a stable fallback.
+     */
+    private function withLocalizedFields(array $product): array
+    {
+        $locale = App::getLocale();
+        $fallbackLocale = $this->languages->defaultLocale();
+        $availableLocales = $this->languages->availableLocales();
+
+        foreach ($this->translatedAttributeHandles() as $handle) {
+            $product[$handle] = $product[$handle.'_'.$locale] ?? $product[$handle.'_'.$fallbackLocale] ?? null;
+
+            foreach ($availableLocales as $availableLocale) {
+                unset($product[$handle.'_'.$availableLocale]);
+            }
+        }
+
+        return $product;
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function translatedAttributeHandles(): array
+    {
+        return $this->attributes->getSearchableAttributes((new Product)->getMorphClass())
+            ->filter(fn ($attribute) => $attribute->type === TranslatedText::class)
+            ->pluck('handle')
+            ->all();
+    }
+
+    /**
+     * For the Meilisearch driver, Scout's paginateRaw() puts the whole raw response
+     * (hits, query, processingTimeMs, ...) in items(), not a plain list of hits - the
+     * actual documents are under the 'hits' key.
+     */
+    private function hitsFrom(LengthAwarePaginatorContract $paginator): array
+    {
+        $rawResponse = $paginator->items();
+
+        return collect($rawResponse['hits'] ?? [])->values()->all();
+    }
+
+    /**
+     * @param array<int, 'collectionId'|'brand'|'price'|'inStockOnly'> $exclude filter
+     *   fields to leave out even if set on $filters — e.g. priceRange() excludes
+     *   'price' so a price slider's own bounds don't shrink to whatever range is
+     *   already selected on it.
+     */
+    private function buildFilter(?ProductFilters $filters, array $exclude = []): ?string
+    {
+        if ($filters === null) {
+            return null;
+        }
+
+        $clauses = Collection::make([
+            'collectionId' => $filters->collectionId !== null ? "collection_ids = \"{$filters->collectionId}\"" : null,
+            'brand' => $filters->brand !== null ? 'brand = "'.addcslashes($filters->brand, '"\\').'"' : null,
+            'price' => Collection::make([
+                $filters->minPrice !== null ? "price >= {$filters->minPrice}" : null,
+                $filters->maxPrice !== null ? "price <= {$filters->maxPrice}" : null,
+            ])->filter()->join(' AND ') ?: null,
+            'inStockOnly' => $filters->inStockOnly ? 'in_stock = true' : null,
+        ])->except($exclude)->filter();
+
+        return $clauses->isEmpty() ? null : $clauses->join(' AND ');
+    }
+}

src/Checkout/Contracts/PaymentDriver.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace Modules\Core\Checkout\Contracts;
+
+use Lunar\Exceptions\FingerprintMismatchException;
+use Lunar\Exceptions\Carts\CartException;
+use Lunar\Models\Cart;
+use Lunar\Models\Order;
+
+/**
+ * A boboko-owned payment driver — wraps a payment gateway's own confirmation
+ * mechanics (Stripe's synchronous authorize() call, a redirect-based
+ * provider's async callback/webhook, anything else) behind one uniform
+ * moment: "payment is confirmed, place the order."
+ *
+ * confirm() is the only thing a driver is required to do: once it has,
+ * by whatever mechanism is native to that gateway, independently decided
+ * the payment succeeded, it calls Modules\Core\Checkout\Services\
+ * CheckoutService::placeOrder($fingerprint) itself — no driver ever calls
+ * Lunar\Models\Cart::createOrder() directly. This is what lets the
+ * storefront checkout sequence stay uniform regardless of which provider is
+ * active: set addresses, select shipping, hand off to whichever driver is
+ * configured, and the driver decides when (or whether) the order actually
+ * gets created. See docs/checkout.md / docs/payments.md.
+ */
+interface PaymentDriver
+{
+    /**
+     * Whether this driver can actually be used right now — e.g. Stripe
+     * checking its own API key is present, an offline-style driver always
+     * returning true since it has no external dependency. Independent of
+     * Modules\Core\Payment\Models\PaymentMethod::enabled (the admin
+     * on/off toggle) — CheckoutService::getPaymentMethods() combines both:
+     * a type is only offered to the storefront if it's administratively
+     * enabled AND its driver reports itself configured.
+     */
+    public function isConfigured(): bool;
+
+    /**
+     * $type is the payment type key being confirmed (e.g. 'cash-in-hand',
+     * 'cash-on-delivery', 'stripe') — passed through even though most
+     * drivers only ever serve one type, because a driver shared across
+     * several types (e.g. one "no real confirmation" offline driver behind
+     * both cash-in-hand and cash-on-delivery) needs it to look up that
+     * type's own config (e.g. its 'authorized' status) rather than another
+     * type's.
+     *
+     * $data carries whatever the gateway needs to confirm this specific
+     * payment (Stripe: ['payment_intent' => $id], a redirect-based
+     * provider: its callback payload) — passed explicitly by the caller
+     * (a controller, a webhook job) rather than a driver reaching into the
+     * global request(), so confirm() works the same whether it's called
+     * from a synchronous HTTP request or an async webhook/job with no
+     * active request at all.
+     *
+     * @param  array<string, mixed>  $data
+     *
+     * @throws FingerprintMismatchException
+     * @throws CartException
+     */
+    public function confirm(Cart $cart, string $type, string $fingerprint, array $data): Order;
+}

src/Checkout/Events/BillingAddressSet.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Modules\Core\Checkout\Events;
+
+use Lunar\Base\Addressable;
+use Lunar\Models\Cart;
+
+/**
+ * Dispatched by CheckoutService::setBillingAddress() — see
+ * ShippingAddressSet's docblock for the full reasoning (Lunar dispatches no
+ * checkout-lifecycle events; this feeds funnel-stage tracking, not built
+ * yet).
+ */
+class BillingAddressSet
+{
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly array|Addressable $address,
+    ) {}
+}

src/Checkout/Events/OrderPlaced.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Modules\Core\Checkout\Events;
+
+use Lunar\Models\Order;
+
+/**
+ * Dispatched by CheckoutService::placeOrder() the moment an Order exists —
+ * the handoff point between Checkout and Order (see docs/checkout.md's
+ * "Three-stage lifecycle"). Checkout has no opinion about what happens
+ * after this fires; Order's own listeners (not built yet — Order is a
+ * named-but-unscoped concern, same status Recovery had before it existed)
+ * would be what reacts to it — e.g. a confirmation email, initializing
+ * order status tracking.
+ */
+class OrderPlaced
+{
+    public function __construct(
+        public readonly Order $order,
+    ) {}
+}

src/Checkout/Events/PaymentMethodSelected.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Modules\Core\Checkout\Events;
+
+use Lunar\Models\Cart;
+
+/**
+ * Dispatched by CheckoutService::selectPaymentMethod() — carries the plain
+ * type key (e.g. 'cash-on-delivery', 'stripe'), same convention as
+ * CartService's events (a plain reference the listener resolves further
+ * itself, rather than an already-resolved object) since a payment type key
+ * has nothing further to eagerly resolve the way a ShippingOption does.
+ */
+class PaymentMethodSelected
+{
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly string $type,
+    ) {}
+}

src/Checkout/Events/ShippingAddressSet.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Modules\Core\Checkout\Events;
+
+use Lunar\Base\Addressable;
+use Lunar\Models\Cart;
+
+/**
+ * Dispatched by CheckoutService::setShippingAddress() — Lunar itself
+ * dispatches no checkout-lifecycle events at all (same gap CartService's
+ * events fill for cart mutations; see docs/cart.md). Feeds
+ * abandoned-checkout stage tracking / conversion-funnel analytics (neither
+ * built yet — see docs/checkout.md), which is why $address is carried
+ * directly rather than requiring a listener to re-read it off the cart.
+ */
+class ShippingAddressSet
+{
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly array|Addressable $address,
+    ) {}
+}

src/Checkout/Events/ShippingOptionSelected.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Core\Checkout\Events;
+
+use Lunar\DataTypes\ShippingOption;
+use Lunar\Models\Cart;
+
+/**
+ * Dispatched by CheckoutService::selectShippingOption() — carries the fully
+ * resolved ShippingOption (name, price, carrier identifier), not just the
+ * string identifier the caller passed in. Deliberate divergence from
+ * CartService's events, which carry a plain Cart/CartLine model reference —
+ * a live-priced carrier quote (see docs/checkout.md's note on
+ * ShippingManifest::getOptions() already being backed by the merged
+ * Shipping-Carriers ACS/Box Now live-rate drivers) is meaningfully more
+ * expensive for a listener to re-derive later than a CartLine reference is.
+ */
+class ShippingOptionSelected
+{
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly ShippingOption $option,
+    ) {}
+}

src/Checkout/Exceptions/InvalidShippingOptionException.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Modules\Core\Checkout\Exceptions;
+
+use RuntimeException;
+
+/**
+ * Thrown by CheckoutService::selectShippingOption() when the given
+ * identifier doesn't resolve to a real, currently-available ShippingOption
+ * for the cart — Lunar's own ShippingManifest::getOption() just returns
+ * null, it has no matching exception type of its own to reuse here (same
+ * reasoning as Modules\Core\Cart\Exceptions\InvalidCouponException for
+ * Discounts::validateCoupon()).
+ */
+class InvalidShippingOptionException extends RuntimeException
+{
+    public function __construct(public readonly string $identifier)
+    {
+        parent::__construct("The shipping option \"{$identifier}\" is not available for this cart.");
+    }
+}

src/Checkout/Exceptions/UnknownPaymentTypeException.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Modules\Core\Checkout\Exceptions;
+
+use RuntimeException;
+
+/**
+ * Thrown by CheckoutService::selectPaymentMethod()/confirmPayment() when
+ * $type doesn't resolve to a registered Modules\Core\Checkout\Contracts\
+ * PaymentDriver (config('payment.drivers')) — same reasoning as
+ * InvalidShippingOptionException: nothing here has a matching Lunar
+ * exception type to reuse, so this is the boboko-owned signal instead of a
+ * silent no-op or an opaque container-resolution error.
+ */
+class UnknownPaymentTypeException extends RuntimeException
+{
+    public function __construct(public readonly string $type)
+    {
+        parent::__construct("The payment type \"{$type}\" is not registered.");
+    }
+}

src/Checkout/Services/CheckoutService.php

@@ -0,0 +1,248 @@
+<?php
+
+namespace Modules\Core\Checkout\Services;
+
+use Lunar\Exceptions\FingerprintMismatchException;
+use Lunar\Exceptions\Carts\CartException;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Event;
+use Lunar\Base\Addressable;
+use Lunar\DataTypes\ShippingOption;
+use Lunar\Facades\ShippingManifest;
+use Lunar\Models\Cart;
+use Lunar\Models\Order;
+use Modules\Core\Cart\Services\CartService;
+use Modules\Core\Checkout\Contracts\PaymentDriver;
+use Modules\Core\Checkout\Events\BillingAddressSet;
+use Modules\Core\Checkout\Events\OrderPlaced;
+use Modules\Core\Checkout\Events\PaymentMethodSelected;
+use Modules\Core\Checkout\Events\ShippingAddressSet;
+use Modules\Core\Checkout\Events\ShippingOptionSelected;
+use Modules\Core\Checkout\Exceptions\InvalidShippingOptionException;
+use Modules\Core\Checkout\Exceptions\UnknownPaymentTypeException;
+use Modules\Core\Payment\Models\PaymentMethod;
+
+/**
+ * Storefront-facing checkout operations, mirroring
+ * Modules\Core\Cart\Services\CartService's shape — one boboko-owned API a
+ * storefront calls, keeping Lunar's own Cart/ShippingManifest primitives an
+ * implementation detail. See docs/checkout.md for the full design —
+ * Checkout is the middle of a three-stage lifecycle (Cart → Checkout →
+ * Order): it owns the placement moment itself (address, shipping selection,
+ * placeOrder()) and ends the instant an Order exists. What happens to that
+ * Order afterward (status transitions, fulfillment) is deliberately out of
+ * scope here — see OrderPlaced's docblock.
+ *
+ * Depends on CartService for cart access rather than reaching into
+ * Lunar\Facades\CartSession directly a second time, so Checkout stays
+ * layered on top of Cart's own service boundary instead of duplicating it.
+ */
+class CheckoutService
+{
+    public function __construct(
+        private readonly CartService $cart,
+    ) {}
+
+    public function setShippingAddress(array|Addressable $address): Cart
+    {
+        $cart = $this->cart->currentOrCreate()->setShippingAddress($address);
+
+        Event::dispatch(new ShippingAddressSet($cart, $address));
+
+        return $cart;
+    }
+
+    public function setBillingAddress(array|Addressable $address): Cart
+    {
+        $cart = $this->cart->currentOrCreate()->setBillingAddress($address);
+
+        Event::dispatch(new BillingAddressSet($cart, $address));
+
+        return $cart;
+    }
+
+    /**
+     * Every shipping option currently available for the cart — already
+     * fully backed by the merged Shipping-Carriers work: this runs every
+     * registered Lunar\Shipping\Interfaces\ShippingRateInterface driver
+     * (ACS/Box Now live-rate quoting alongside table-rate-shipping's own
+     * flat-rate/free-shipping/collection drivers) through
+     * ShippingManifest's pipeline. No rate-resolution logic lives here —
+     * this is a thin pass-through.
+     *
+     * @return Collection<int, ShippingOption>
+     */
+    public function getShippingOptions(): Collection
+    {
+        return ShippingManifest::getOptions($this->cart->currentOrCreate());
+    }
+
+    /**
+     * @throws InvalidShippingOptionException if $identifier doesn't resolve
+     *   to a real, currently-available option for the cart
+     */
+    public function selectShippingOption(string $identifier): Cart
+    {
+        $cartBefore = $this->cart->currentOrCreate();
+        $option = ShippingManifest::getOption($cartBefore, $identifier);
+
+        if ($option === null) {
+            throw new InvalidShippingOptionException($identifier);
+        }
+
+        $cart = $cartBefore->setShippingOption($option);
+
+        Event::dispatch(new ShippingOptionSelected($cart, $option));
+
+        return $cart;
+    }
+
+    /**
+     * $fingerprint is mandatory, not optional — the caller must prove the
+     * cart total the shopper last saw (Cart::fingerprint()) still matches
+     * before an order is placed. Cart::checkFingerprint() throws Lunar's own
+     * FingerprintMismatchException on a mismatch (a line's price changed,
+     * stock adjusted the total, another tab modified the cart) rather than
+     * silently placing an order at a different total than what was shown.
+     *
+     * Not called directly by a storefront — see confirmPayment(), which is
+     * the only caller and supplies the fingerprint captured in
+     * selectPaymentMethod(), not one the storefront has to obtain itself.
+     *
+     * No exception wrapping: Lunar\Validation\Cart\ValidateCartForOrderCreation
+     * (run inside Cart::createOrder()) already throws
+     * Lunar\Exceptions\Carts\CartException with a field-keyed MessageBag
+     * ($exception->errors()) for address/shipping-option validation and the
+     * duplicate-order guard — already the right shape for a storefront to
+     * render as form errors directly. FingerprintMismatchException
+     * propagates the same way, for the same reason.
+     *
+     * @throws FingerprintMismatchException
+     * @throws CartException
+     */
+    public function placeOrder(string $fingerprint): Order
+    {
+        $cart = $this->cart->currentOrCreate();
+        $cart->checkFingerprint($fingerprint);
+
+        $order = $cart->createOrder();
+
+        Event::dispatch(new OrderPlaced($order));
+
+        return $order;
+    }
+
+    /**
+     * Every payment type currently offered to the storefront — every key
+     * in config('lunar.payments.types') that is BOTH administratively
+     * enabled (Modules\Core\Payment\Models\PaymentMethod::enabled) AND
+     * whose registered PaymentDriver reports itself usable right now
+     * (PaymentDriver::isConfigured() — e.g. Stripe with no API key set is
+     * never offered, regardless of the enabled toggle). A type with no
+     * PaymentMethod row at all (never seeded) is treated as not offered,
+     * same as disabled — nothing here creates one; see
+     * InstallLunarCommand::seedPaymentMethods().
+     *
+     * @return array<string>
+     */
+    public function getPaymentMethods(): array
+    {
+        return PaymentMethod::where('enabled', true)
+            ->pluck('type')
+            ->filter(fn (string $type) => $this->resolvePaymentDriver($type)?->isConfigured() ?? false)
+            ->values()
+            ->all();
+    }
+
+    /**
+     * Records which payment type the shopper picked (Cart::meta
+     * ['payment_method']) — read by e.g. Modules\Core\Payment\Pipelines\
+     * Cart\ApplyCashOnDeliveryFee to add that type's own cart-total
+     * adjustments before recalculation.
+     *
+     * Also snapshots Cart::fingerprint() into meta, *after* saving the
+     * chosen type — the fingerprint has to reflect the final total
+     * including any payment-type-specific adjustment (e.g. a COD
+     * surcharge), which only exists once payment_method is set and the
+     * cart recalculates. Captured here, server-side, rather than asked of
+     * the storefront: this is the last moment before confirmPayment() that
+     * the shopper's reviewed total is known, and confirmPayment() reads it
+     * back internally instead of taking a fingerprint parameter — a
+     * storefront should never need to know Cart::fingerprint() exists.
+     *
+     * Does not itself call a PaymentDriver — selecting a method and
+     * confirming payment against it are deliberately separate steps, same
+     * as selecting a shipping option happens before placing the order.
+     *
+     * @throws UnknownPaymentTypeException if $type isn't currently offered
+     *   — see getPaymentMethods() for what that means (registered,
+     *   administratively enabled, and its driver reports itself usable)
+     */
+    public function selectPaymentMethod(string $type): Cart
+    {
+        if (! in_array($type, $this->getPaymentMethods(), true)) {
+            throw new UnknownPaymentTypeException($type);
+        }
+
+        $cart = $this->cart->currentOrCreate();
+        $cart->meta = [...$cart->meta->toArray(), 'payment_method' => $type];
+        $cart->save();
+
+        $cart = $cart->calculate();
+        $cart->meta = [...$cart->meta->toArray(), 'checkout_fingerprint' => $cart->fingerprint()];
+        $cart->save();
+
+        Event::dispatch(new PaymentMethodSelected($cart, $type));
+
+        return $cart;
+    }
+
+    /**
+     * Resolves $type's registered PaymentDriver and calls confirm() —
+     * the driver decides whether/when the order actually gets placed (see
+     * Modules\Core\Checkout\Contracts\PaymentDriver's docblock). $data
+     * carries whatever that driver needs (Stripe's payment_intent id, a
+     * future redirect-based provider's callback payload).
+     *
+     * The fingerprint passed to the driver is the one captured by
+     * selectPaymentMethod(), not supplied by the caller — see that
+     * method's docblock. Throws the same FingerprintMismatchException a
+     * caller-supplied one would if the cart's total has since changed;
+     * missing entirely (selectPaymentMethod() was never called for this
+     * cart) is treated the same as a mismatch, not a different error.
+     *
+     * @param  array<string, mixed>  $data
+     *
+     * @throws UnknownPaymentTypeException if $type isn't currently offered
+     *   (see getPaymentMethods()) — re-checked here, not just in
+     *   selectPaymentMethod(), since a type could be disabled between
+     *   selection and confirmation
+     * @throws \Lunar\Exceptions\FingerprintMismatchException
+     * @throws \Lunar\Exceptions\Carts\CartException
+     */
+    public function confirmPayment(string $type, array $data = []): Order
+    {
+        if (! in_array($type, $this->getPaymentMethods(), true)) {
+            throw new UnknownPaymentTypeException($type);
+        }
+
+        $cart = $this->cart->currentOrCreate();
+        $fingerprint = $cart->meta['checkout_fingerprint'] ?? '';
+
+        return $this->resolvePaymentDriver($type)->confirm($cart, $type, $fingerprint, $data);
+    }
+
+    /**
+     * Resolves $type's registered PaymentDriver, or null if $type has no
+     * 'payment_driver' registered in config('lunar.payments.types.<type>')
+     * at all — deliberately non-throwing so getPaymentMethods() can filter
+     * unresolvable types silently rather than treating "not registered"
+     * as an error condition when just checking availability.
+     */
+    private function resolvePaymentDriver(string $type): ?PaymentDriver
+    {
+        $driverClass = config("lunar.payments.types.{$type}.payment_driver");
+
+        return $driverClass ? app($driverClass) : null;
+    }
+}

src/Command/CreateAdminCommand.php

@@ -2,6 +2,7 @@
 
 namespace Modules\Core\Command;
 
+use Lunar\Admin\Models\Staff;
 use Lunar\Admin\Console\Commands\MakeLunarAdminCommand;
 
 use function Laravel\Prompts\text;
@@ -31,7 +32,7 @@ class CreateAdminCommand extends MakeLunarAdminCommand
                 required: true,
                 validate: fn (string $email): ?string => match (true) {
                     ! filter_var($email, FILTER_VALIDATE_EMAIL) => 'The email address must be valid.',
-                    \Lunar\Admin\Models\Staff::where('email', $email)->exists() => 'A user with this email address already exists',
+                    Staff::where('email', $email)->exists() => 'A user with this email address already exists',
                     default => null,
                 },
             ),

src/Command/ExportCommand.php

@@ -2,6 +2,9 @@
 
 namespace Modules\Core\Command;
 
+use RecursiveIteratorIterator;
+use RecursiveDirectoryIterator;
+use FilesystemIterator;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\Storage;
 use Modules\Core\ResultType\Error;
@@ -88,10 +91,10 @@ class ExportCommand extends Command
         $zip->addFile($sqlFile, basename($sqlFile));
 
         if (is_dir($filesDir)) {
-            $iterator = new \RecursiveIteratorIterator(
-                new \RecursiveDirectoryIterator(
+            $iterator = new RecursiveIteratorIterator(
+                new RecursiveDirectoryIterator(
                     $filesDir,
-                    \FilesystemIterator::SKIP_DOTS,
+                    FilesystemIterator::SKIP_DOTS,
                 ),
             );
             foreach ($iterator as $file) {

src/Command/InstallLunarCommand.php

@@ -0,0 +1,318 @@
+<?php
+
+namespace Modules\Core\Command;
+
+use Illuminate\Console\Command;
+use Lunar\Facades\DB;
+use Lunar\FieldTypes\TranslatedText;
+use Lunar\Models\Attribute;
+use Lunar\Models\AttributeGroup;
+use Lunar\Models\Channel;
+use Lunar\Models\Collection;
+use Lunar\Models\CollectionGroup;
+use Lunar\Models\Country;
+use Lunar\Models\Currency;
+use Lunar\Models\CustomerGroup;
+use Lunar\Models\Language;
+use Lunar\Models\Product;
+use Lunar\Models\ProductType;
+use Lunar\Models\TaxClass;
+use Lunar\Models\TaxZone;
+use Modules\Core\Localization\Models\LanguageLine;
+use Modules\Core\Localization\Services\StorefrontLabels;
+use Modules\Core\Localization\Services\TranslationService;
+use Modules\Core\Payment\Models\PaymentMethod;
+
+/**
+ * Overrides Lunar's own lunar:install to skip the interactive prompts (migrate
+ * confirmation, admin creation, GitHub star), so it's safe to run unattended from
+ * the entrypoint on every boot. Migrations already run as a separate, earlier
+ * entrypoint step; the admin user is created manually.
+ */
+class InstallLunarCommand extends Command
+{
+    protected $signature = 'lunar:install';
+
+    protected $description = 'Seed the default Lunar store data (countries, channel, currency, tax zone, attributes, product type)';
+
+    public function handle(TranslationService $translations): void
+    {
+        $this->components->info('Seeding default Lunar store data...');
+
+        if (! Country::count()) {
+            $this->components->info('Importing countries');
+            $this->call('lunar:import:address-data');
+        }
+
+        DB::transaction(function () {
+            if (! Channel::whereDefault(true)->exists()) {
+                $this->components->info('Setting up default channel');
+
+                Channel::create([
+                    'name' => 'Webstore',
+                    'handle' => 'webstore',
+                    'default' => true,
+                    'url' => 'http://localhost',
+                ]);
+            }
+
+            if (! Language::count()) {
+                $this->components->info('Adding default language');
+
+                Language::create([
+                    'code' => 'en',
+                    'name' => 'English',
+                    'default' => true,
+                ]);
+            }
+
+            if (! Currency::whereDefault(true)->exists()) {
+                $this->components->info('Adding a default currency (USD)');
+
+                Currency::create([
+                    'code' => 'USD',
+                    'name' => 'US Dollar',
+                    'exchange_rate' => 1,
+                    'decimal_places' => 2,
+                    'default' => true,
+                    'enabled' => true,
+                ]);
+            }
+
+            if (! CustomerGroup::whereDefault(true)->exists()) {
+                $this->components->info('Adding a default customer group.');
+
+                CustomerGroup::create([
+                    'name' => 'Retail',
+                    'handle' => 'retail',
+                    'default' => true,
+                ]);
+            }
+
+            if (! CollectionGroup::count()) {
+                $this->components->info('Adding an initial collection group');
+
+                CollectionGroup::create([
+                    'name' => 'Main',
+                    'handle' => 'main',
+                ]);
+            }
+
+            if (! TaxClass::count()) {
+                $this->components->info('Adding a default tax class.');
+
+                TaxClass::create([
+                    'name' => 'Default Tax Class',
+                    'default' => true,
+                ]);
+            }
+
+            if (! TaxZone::count()) {
+                $this->components->info('Adding a default tax zone.');
+
+                $taxZone = TaxZone::create([
+                    'name' => 'Default Tax Zone',
+                    'zone_type' => 'country',
+                    'price_display' => 'tax_exclusive',
+                    'default' => true,
+                    'active' => true,
+                ]);
+                $taxZone->countries()->createMany(
+                    Country::get()->map(fn ($country) => [
+                        'country_id' => $country->id,
+                    ])
+                );
+            }
+
+            if (! Attribute::count()) {
+                $this->components->info('Setting up initial attributes');
+
+                $group = AttributeGroup::create([
+                    'attributable_type' => Product::morphName(),
+                    'name' => collect([
+                        'en' => 'Details',
+                    ]),
+                    'handle' => 'details',
+                    'position' => 1,
+                ]);
+
+                $collectionGroup = AttributeGroup::create([
+                    'attributable_type' => Collection::morphName(),
+                    'name' => collect([
+                        'en' => 'Details',
+                    ]),
+                    'handle' => 'collection_details',
+                    'position' => 1,
+                ]);
+
+                Attribute::create([
+                    'attribute_type' => 'product',
+                    'attribute_group_id' => $group->id,
+                    'position' => 1,
+                    'name' => [
+                        'en' => 'Name',
+                    ],
+                    'handle' => 'name',
+                    'section' => 'main',
+                    'type' => TranslatedText::class,
+                    'required' => true,
+                    'default_value' => null,
+                    'configuration' => [
+                        'richtext' => false,
+                    ],
+                    'system' => true,
+                    'description' => [
+                        'en' => '',
+                    ],
+                ]);
+
+                Attribute::create([
+                    'attribute_type' => 'collection',
+                    'attribute_group_id' => $collectionGroup->id,
+                    'position' => 1,
+                    'name' => [
+                        'en' => 'Name',
+                    ],
+                    'handle' => 'name',
+                    'section' => 'main',
+                    'type' => TranslatedText::class,
+                    'required' => true,
+                    'default_value' => null,
+                    'configuration' => [
+                        'richtext' => false,
+                    ],
+                    'system' => true,
+                    'description' => [
+                        'en' => '',
+                    ],
+                ]);
+
+                Attribute::create([
+                    'attribute_type' => 'product',
+                    'attribute_group_id' => $group->id,
+                    'position' => 2,
+                    'name' => [
+                        'en' => 'Description',
+                    ],
+                    'handle' => 'description',
+                    'section' => 'main',
+                    'type' => TranslatedText::class,
+                    'required' => false,
+                    'default_value' => null,
+                    'configuration' => [
+                        'richtext' => true,
+                    ],
+                    'system' => false,
+                    'description' => [
+                        'en' => '',
+                    ],
+                ]);
+
+                Attribute::create([
+                    'attribute_type' => 'collection',
+                    'attribute_group_id' => $collectionGroup->id,
+                    'position' => 2,
+                    'name' => [
+                        'en' => 'Description',
+                    ],
+                    'handle' => 'description',
+                    'section' => 'main',
+                    'type' => TranslatedText::class,
+                    'required' => false,
+                    'default_value' => null,
+                    'configuration' => [
+                        'richtext' => true,
+                    ],
+                    'system' => false,
+                    'description' => [
+                        'en' => '',
+                    ],
+                ]);
+            }
+
+            if (! ProductType::count()) {
+                $this->components->info('Adding a product type.');
+
+                $type = ProductType::create([
+                    'name' => 'Stock',
+                ]);
+
+                $type->mappedAttributes()->attach(
+                    Attribute::whereAttributeType(
+                        Product::morphName()
+                    )->get()->pluck('id')
+                );
+            }
+        });
+
+        $this->components->info('Seeding storefront label translations');
+        $this->seedStorefrontLabels($translations);
+
+        $this->components->info('Seeding payment method settings');
+        $this->seedPaymentMethods();
+
+        $this->components->info('Publishing Filament assets');
+        $this->call('filament:assets');
+
+        $this->components->info('Lunar default data seeded.');
+    }
+
+    /**
+     * 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 Languages resource) is left untouched; only keys missing
+     * entirely are created. This is what makes it safe to add new keys to
+     * StorefrontLabels later and re-run this on an already-installed store without
+     * either skipping the new keys (the old all-or-nothing guard) or reverting an
+     * admin's edits back to the hardcoded default (a naive updateOrCreate would).
+     */
+    private function seedStorefrontLabels(TranslationService $translations): void
+    {
+        $labels = StorefrontLabels::all();
+
+        $existingKeys = LanguageLine::where('group', 'storefront')
+            ->whereIn('key', array_keys($labels))
+            ->pluck('key');
+
+        foreach ($labels as $key => $text) {
+            if ($existingKeys->contains($key)) {
+                continue;
+            }
+
+            $translations->create('storefront', $key, $text);
+        }
+    }
+
+    /**
+     * Per-type skip-if-exists, same idempotent convention as
+     * seedStorefrontLabels() — a type already present (including one an
+     * admin has since edited via the Filament Payment Methods resource) is
+     * left untouched. Safe to re-run after a new payment type is added to
+     * config('lunar.payments.types') (e.g. installing a Stripe/Nexi
+     * package), which is the whole reason this isn't a one-time-only seed.
+     *
+     * Seeded disabled — a newly-seeded row (whether from this store's
+     * initial install, or a payment provider package installed later)
+     * shouldn't go live for shoppers before staff have actually reviewed
+     * it (real credentials configured, a fee set, etc.) and turned it on
+     * via the Payment Methods resource. See CheckoutService::
+     * getPaymentMethods(), which only offers a type once both 'enabled'
+     * here and its driver's own isConfigured() check pass.
+     */
+    private function seedPaymentMethods(): void
+    {
+        $existingTypes = PaymentMethod::pluck('type');
+
+        foreach (array_keys(config('lunar.payments.types', [])) as $type) {
+            if ($existingTypes->contains($type)) {
+                continue;
+            }
+
+            PaymentMethod::create([
+                'type' => $type,
+                'enabled' => false,
+                'data' => [],
+            ]);
+        }
+    }
+}

src/Command/MigrateImportCommand.php

@@ -8,43 +8,44 @@ use Modules\Core\MigrateImport\RunMigrateImportJob;
 
 class MigrateImportCommand extends Command
 {
-    protected $signature = "boboko:migrate:import
+    protected $signature = 'boboko:migrate:import
         {--source= : The source platform to import from}
         {--type= : The import mechanism for the chosen source}
-        {--file= : Path to the export file (when type is export)}";
+        {--file= : Path to the export file (when type is export)}';
 
-    protected $description = "Migrate data (products, customers, etc.) from an external source";
+    protected $description = 'Migrate data (products, customers, etc.) from an external source';
 
-    // Supported sources. Only "shopify" is wired up for now.
+    // Supported sources. Only "shopify" and "judgeme" are wired up for now.
     private const SOURCES = [
-        "shopify",
+        'shopify',
+        'judgeme',
         // "woocommerce",
     ];
 
     // Supported import types per source. Only "export" is wired up for now.
     private const TYPES = [
-        "export",
+        'export',
         // "api",
     ];
 
     public function handle(): void
     {
-        $source = $this->option("source")
-            ?? $this->choice("Select a source:", self::SOURCES, 0);
+        $source = $this->option('source')
+            ?? $this->choice('Select a source:', self::SOURCES, 0);
 
-        $type = $this->option("type")
-            ?? $this->choice("Select an import type:", self::TYPES, 0);
+        $type = $this->option('type')
+            ?? $this->choice('Select an import type:', self::TYPES, 0);
 
-        if ($type === "api") {
+        if ($type === 'api') {
             $credentials = [
-                "api_key" => $this->secret("API key:"),
-                "api_secret" => $this->secret("API secret:"),
+                'api_key' => $this->secret('API key:'),
+                'api_secret' => $this->secret('API secret:'),
             ];
             $filePath = null;
         } else {
-            $importsPath = storage_path("app/private/imports");
+            $importsPath = storage_path('app/private/imports');
 
-            $filePath = $this->option("file")
+            $filePath = $this->option('file')
                 ?? $this->resolveImportPath($importsPath, $this->ask("Path to the export file, relative to {$importsPath}:"));
 
             while (blank($filePath) || ! is_file($filePath)) {
@@ -70,7 +71,7 @@ class MigrateImportCommand extends Command
 
         RunMigrateImportJob::dispatch($spec);
 
-        $this->info("Import queued.");
+        $this->info('Import queued.');
     }
 
     // Answers are relative to storage/app/private/imports (e.g. "shopify" or
@@ -82,7 +83,7 @@ class MigrateImportCommand extends Command
             return $answer;
         }
 
-        $path = str_starts_with($answer, "/") ? $answer : "{$importsPath}/{$answer}";
+        $path = str_starts_with($answer, '/') ? $answer : "{$importsPath}/{$answer}";
 
         if (is_dir($path)) {
             $csv = collect(glob("{$path}/*.csv"))->first();

src/CorePlugin.php

@@ -2,16 +2,36 @@
 
 namespace Modules\Core;
 
+use Lunar\Admin\Filament\Resources\OrderResource\Pages\ManageOrder;
 use Filament\Contracts\Plugin;
 use Filament\Panel;
+use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Support\Facades\Mail;
+use Lunar\Admin\Filament\Resources\ProductOptionResource;
+use Lunar\Admin\Filament\Resources\ProductOptionResource\RelationManagers\ValuesRelationManager;
+use Lunar\Admin\Filament\Resources\OrderResource;
+use Lunar\Admin\Filament\Resources\ProductResource;
 use Lunar\Admin\Filament\Resources\StaffResource;
 use Lunar\Admin\Models\Staff as LunarStaff;
 use Lunar\Admin\Support\Facades\LunarPanel;
+use Lunar\Models\Product;
+use Lunar\Shipping\Filament\Resources\ShippingMethodResource;
+use Lunar\Shipping\Filament\Resources\ShippingMethodResource\Pages\ListShippingMethod;
 use Lunar\Shipping\ShippingPlugin;
 use Modules\Core\Auth\Extensions\StaffResourceExtension;
 use Modules\Core\Auth\Filament\Pages\Login;
 use Modules\Core\Auth\Mail\InviteMail;
+use Modules\Core\Cart\Filament\Resources\CartResource;
+use Modules\Core\Catalog\Filament\Extensions\ProductOptionResourceExtension;
+use Modules\Core\Catalog\Filament\Extensions\ValuesRelationManagerExtension;
+use Modules\Core\Localization\Filament\Resources\LanguageLineResource;
+use Modules\Core\Payment\Filament\Resources\PaymentMethodResource;
+use Modules\Core\Review\Filament\Extensions\ProductResourceExtension;
+use Modules\Core\Review\Models\ProductReview;
+use Modules\Core\Shipping\Extensions\OrderViewExtension;
+use Modules\Core\Shipping\Extensions\ShippingMethodListExtension;
+use Modules\Core\Shipping\Extensions\ShippingMethodResourceExtension;
+use Modules\Core\Shipping\Filament\Pages\ManagePickupManifests;
 
 class CorePlugin implements Plugin
 {
@@ -27,21 +47,37 @@ class CorePlugin implements Plugin
             ->brandLogo(asset('static/logos/core/boboko-logo.svg'))
             ->darkModeBrandLogo(asset('static/logos/core/boboko-logo-white.svg'))
             ->login(Login::class)
-            ->plugin(ShippingPlugin::make());
+            ->resources([
+                LanguageLineResource::class,
+                CartResource::class,
+                PaymentMethodResource::class,
+            ])
+            ->plugin(ShippingPlugin::make())
+            ->pages([ManagePickupManifests::class]);
 
         LunarPanel::extensions([
             StaffResource::class => StaffResourceExtension::class,
+            ProductResource::class => ProductResourceExtension::class,
+            ProductOptionResource::class => ProductOptionResourceExtension::class,
+            ValuesRelationManager::class => ValuesRelationManagerExtension::class,
+            ShippingMethodResource::class => ShippingMethodResourceExtension::class,
+            ListShippingMethod::class => ShippingMethodListExtension::class,
+            ManageOrder::class => OrderViewExtension::class,
         ]);
 
+        Product::macro('reviews', function (): HasMany {
+            /** @var Product $this */
+            return $this->hasMany(ProductReview::class);
+        });
+
         LunarStaff::addActivitylogExcept([
             'otp_code',
             'otp_expires_at',
             'password',
             'remember_token',
             'email_verified_at',
-            'two_factor_secret',
-            'two_factor_recovery_codes',
-            'two_factor_confirmed_at',
+            'app_authentication_secret',
+            'app_authentication_recovery_codes',
         ]);
 
         LunarStaff::created(function (LunarStaff $staff) {

src/Customer/RelationManagers/AddressRelationManager.php

@@ -2,12 +2,12 @@
 
 namespace Modules\Core\Customer\RelationManagers;
 
-use Filament\Forms\Components\Group;
+use Filament\Actions\CreateAction;
+use Filament\Actions\EditAction;
+use Filament\Actions\DeleteAction;
+use Filament\Schemas\Components\Group;
 use Filament\Forms\Components\Select;
 use Filament\Forms\Components\TextInput;
-use Filament\Tables\Actions\CreateAction;
-use Filament\Tables\Actions\DeleteAction;
-use Filament\Tables\Actions\EditAction;
 use Filament\Tables\Columns\TextColumn;
 use Filament\Tables\Table;
 use Illuminate\Database\Eloquent\Model;
@@ -38,9 +38,9 @@ class AddressRelationManager extends BaseAddressRelationManager
                 ),
             ])
             ->headerActions([
-                CreateAction::make()->form($this->addressForm()),
+                CreateAction::make()->schema($this->addressForm()),
             ])
-            ->actions([
+            ->recordActions([
                 EditAction::make('editAddress')
                     ->fillForm(fn (AddressContract $record): array => [
                         'line_one' => $record->line_one,
@@ -51,7 +51,7 @@ class AddressRelationManager extends BaseAddressRelationManager
                         'contact_email' => $record->contact_email,
                         'contact_phone' => $record->contact_phone,
                     ])
-                    ->form($this->addressForm()),
+                    ->schema($this->addressForm()),
                 DeleteAction::make('deleteAddress'),
             ]);
     }

src/Customer/RelationManagers/UserRelationManager.php

@@ -2,6 +2,8 @@
 
 namespace Modules\Core\Customer\RelationManagers;
 
+use Filament\Tables\Columns\TextColumn;
+use Filament\Actions\EditAction;
 use Filament\Forms\Components\TextInput;
 use Filament\Tables;
 use Filament\Tables\Table;
@@ -14,16 +16,16 @@ class UserRelationManager extends BaseUserRelationManager
     public function getDefaultTable(Table $table): Table
     {
         return $table->columns([
-            Tables\Columns\TextColumn::make('name')
+            TextColumn::make('name')
                 ->label(__('lunarpanel::user.table.name.label')),
-            Tables\Columns\TextColumn::make('email')
+            TextColumn::make('email')
                 ->label(__('lunarpanel::user.table.email.label')),
-        ])->actions([
-            Tables\Actions\EditAction::make('edit')
+        ])->recordActions([
+            EditAction::make('edit')
                 ->after(
                     fn (Model $record) => CustomerUserEdited::dispatch($record)
                 )
-                ->form([
+                ->schema([
                     TextInput::make('email')
                         ->label(__('lunarpanel::user.form.email.label'))
                         ->required()

src/Localization/Events/LanguageCreated.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Modules\Core\Localization\Events;
+
+use Lunar\Models\Language;
+
+class LanguageCreated
+{
+    public function __construct(
+        public readonly Language $language,
+    ) {}
+}

src/Localization/Events/LanguageDeleted.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Modules\Core\Localization\Events;
+
+use Lunar\Models\Language;
+
+class LanguageDeleted
+{
+    public function __construct(
+        public readonly Language $language,
+    ) {}
+}

src/Localization/Events/LanguageUpdated.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Modules\Core\Localization\Events;
+
+use Lunar\Models\Language;
+
+class LanguageUpdated
+{
+    /**
+     * @param  array{code: string}  $old  Snapshot of watched attributes before the update.
+     */
+    public function __construct(
+        public readonly Language $language,
+        public readonly array $old,
+    ) {}
+}

src/Localization/Events/TranslationCreated.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Modules\Core\Localization\Events;
+
+use Spatie\TranslationLoader\LanguageLine;
+
+class TranslationCreated
+{
+    public function __construct(
+        public readonly LanguageLine $languageLine,
+    ) {}
+}

src/Localization/Events/TranslationDeleted.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Modules\Core\Localization\Events;
+
+use Spatie\TranslationLoader\LanguageLine;
+
+class TranslationDeleted
+{
+    public function __construct(
+        public readonly LanguageLine $languageLine,
+    ) {}
+}

src/Localization/Events/TranslationUpdated.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Modules\Core\Localization\Events;
+
+use Spatie\TranslationLoader\LanguageLine;
+
+class TranslationUpdated
+{
+    /**
+     * @param  array{group: string, key: string, text: array}  $old  Snapshot before the update.
+     */
+    public function __construct(
+        public readonly LanguageLine $languageLine,
+        public readonly array $old,
+    ) {}
+}

src/Localization/Filament/Resources/LanguageLineResource.php

@@ -0,0 +1,116 @@
+<?php
+
+namespace Modules\Core\Localization\Filament\Resources;
+
+use Filament\Schemas\Schema;
+use Filament\Forms\Components\TextInput;
+use Filament\Schemas\Components\Fieldset;
+use Filament\Tables\Columns\TextColumn;
+use Filament\Tables\Filters\SelectFilter;
+use Modules\Core\Localization\Filament\Resources\LanguageLineResource\Pages\ListLanguageLines;
+use Modules\Core\Localization\Filament\Resources\LanguageLineResource\Pages\CreateLanguageLine;
+use Modules\Core\Localization\Filament\Resources\LanguageLineResource\Pages\EditLanguageLine;
+use Filament\Forms\Components\Textarea;
+use Illuminate\Support\Collection;
+use Filament\Forms;
+use Filament\Resources\Resource;
+use Filament\Tables;
+use Filament\Tables\Table;
+use Lunar\Models\Language;
+use Modules\Core\Localization\Filament\Resources\LanguageLineResource\Pages;
+use Spatie\TranslationLoader\LanguageLine;
+
+class LanguageLineResource extends Resource
+{
+    protected static ?string $model = LanguageLine::class;
+
+    protected static string | \BackedEnum | null $navigationIcon = 'heroicon-o-language';
+
+    protected static string | \UnitEnum | null $navigationGroup = 'Settings';
+
+    protected static ?string $modelLabel = 'Translation';
+
+    protected static ?string $pluralModelLabel = 'Translations';
+
+    public static function form(Schema $schema): Schema
+    {
+        return $schema->components([
+            TextInput::make('group')
+                ->required()
+                ->maxLength(255)
+                ->default('storefront')
+                ->helperText('Namespace for this label, e.g. "storefront" for e-shop UI text.'),
+
+            TextInput::make('key')
+                ->required()
+                ->maxLength(255)
+                ->helperText('Dot-notation key, e.g. "nav.cart".'),
+
+            Fieldset::make('Translations')
+                ->schema(static::localeInputs()),
+        ]);
+    }
+
+    public static function table(Table $table): Table
+    {
+        return $table
+            ->columns([
+                TextColumn::make('group')
+                    ->badge()
+                    ->sortable(),
+                TextColumn::make('key')
+                    ->searchable()
+                    ->sortable(),
+                ...static::localeColumns(),
+            ])
+            ->filters([
+                SelectFilter::make('group')
+                    ->options(fn () => LanguageLine::query()->distinct()->pluck('group', 'group')),
+            ])
+            ->defaultSort('key');
+    }
+
+    public static function getRelations(): array
+    {
+        return [];
+    }
+
+    public static function getPages(): array
+    {
+        return [
+            'index' => ListLanguageLines::route('/'),
+            'create' => CreateLanguageLine::route('/create'),
+            'edit' => EditLanguageLine::route('/{record}/edit'),
+        ];
+    }
+
+    /**
+     * @return array<Textarea>
+     */
+    private static function localeInputs(): array
+    {
+        return static::localeCodes()
+            ->map(fn (string $code) => Textarea::make("text.{$code}")
+                ->label(strtoupper($code))
+                ->rows(2))
+            ->all();
+    }
+
+    /**
+     * @return array<TextColumn>
+     */
+    private static function localeColumns(): array
+    {
+        return static::localeCodes()
+            ->map(fn (string $code) => TextColumn::make("text.{$code}")
+                ->label(strtoupper($code))
+                ->limit(40)
+                ->toggleable())
+            ->all();
+    }
+
+    private static function localeCodes(): Collection
+    {
+        return Language::query()->pluck('code');
+    }
+}

src/Localization/Filament/Resources/LanguageLineResource/Pages/CreateLanguageLine.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Modules\Core\Localization\Filament\Resources\LanguageLineResource\Pages;
+
+use Filament\Resources\Pages\CreateRecord;
+use Illuminate\Database\Eloquent\Model;
+use Modules\Core\Localization\Filament\Resources\LanguageLineResource;
+use Modules\Core\Localization\Services\TranslationService;
+
+class CreateLanguageLine extends CreateRecord
+{
+    protected static string $resource = LanguageLineResource::class;
+
+    protected function handleRecordCreation(array $data): Model
+    {
+        return app(TranslationService::class)->create(
+            $data['group'],
+            $data['key'],
+            $data['text'] ?? [],
+        );
+    }
+}

src/Localization/Filament/Resources/LanguageLineResource/Pages/EditLanguageLine.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace Modules\Core\Localization\Filament\Resources\LanguageLineResource\Pages;
+
+use Filament\Actions\DeleteAction;
+use Filament\Actions;
+use Filament\Actions\Action;
+use Filament\Resources\Pages\EditRecord;
+use Illuminate\Database\Eloquent\Model;
+use Modules\Core\Localization\Filament\Resources\LanguageLineResource;
+use Modules\Core\Localization\Services\TranslationService;
+use Spatie\TranslationLoader\LanguageLine;
+
+class EditLanguageLine extends EditRecord
+{
+    protected static string $resource = LanguageLineResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [
+            DeleteAction::make()
+                ->action(function (LanguageLine $record) {
+                    app(TranslationService::class)->delete($record);
+
+                    $this->redirect($this->getResource()::getUrl('index'));
+                }),
+        ];
+    }
+
+    /**
+     * Filament's default Cancel button uses window.history.back(), which
+     * restores the browser's cached previous page instead of re-fetching —
+     * so an edit made just before clicking Cancel doesn't show up in the
+     * list until a manual refresh. Redirect through Livewire instead, which
+     * always re-queries.
+     */
+    protected function getCancelFormAction(): Action
+    {
+        return Action::make('cancel')
+            ->label(__('filament-panels::resources/pages/edit-record.form.actions.cancel.label'))
+            ->url(static::getResource()::getUrl('index'))
+            ->color('gray');
+    }
+
+    protected function handleRecordUpdate(Model $record, array $data): Model
+    {
+        return app(TranslationService::class)->update(
+            $record,
+            $data['group'],
+            $data['key'],
+            $data['text'] ?? [],
+        );
+    }
+}

src/Localization/Filament/Resources/LanguageLineResource/Pages/ListLanguageLines.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Modules\Core\Localization\Filament\Resources\LanguageLineResource\Pages;
+
+use Filament\Actions\CreateAction;
+use Filament\Actions;
+use Filament\Resources\Pages\ListRecords;
+use Modules\Core\Localization\Filament\Resources\LanguageLineResource;
+
+class ListLanguageLines extends ListRecords
+{
+    protected static string $resource = LanguageLineResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [
+            CreateAction::make(),
+        ];
+    }
+}

src/Localization/Listeners/FlushLanguageCache.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Modules\Core\Localization\Listeners;
+
+use Modules\Core\Localization\Events\LanguageCreated;
+use Modules\Core\Localization\Events\LanguageDeleted;
+use Modules\Core\Localization\Events\LanguageUpdated;
+use Modules\Core\Localization\Services\LanguageCache;
+
+class FlushLanguageCache
+{
+    public function __construct(private readonly LanguageCache $languages) {}
+
+    public function handle(LanguageCreated|LanguageUpdated|LanguageDeleted $event): void
+    {
+        $this->languages->forget();
+    }
+}

src/Localization/Listeners/FlushTranslationCache.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Modules\Core\Localization\Listeners;
+
+use Illuminate\Support\Facades\Cache;
+use Modules\Core\Localization\Events\TranslationCreated;
+use Modules\Core\Localization\Events\TranslationDeleted;
+use Modules\Core\Localization\Events\TranslationUpdated;
+use Spatie\TranslationLoader\LanguageLine;
+
+/**
+ * LanguageLine::boot() already flushes the cache for the current group's locales
+ * present after a save, but misses two cases on update: locales removed from
+ * `text` (e.g. dropping the "el" key leaves `{group}.el` stale), and a changed
+ * `group`/`key` (the old group's cached array never gets told a row left it).
+ * This listener flushes every group+locale combination touched by either the
+ * old or new state so nothing can remain stale.
+ */
+class FlushTranslationCache
+{
+    public function handle(TranslationCreated|TranslationUpdated|TranslationDeleted $event): void
+    {
+        $this->flush($event->languageLine->group, array_keys($event->languageLine->text ?? []));
+
+        if ($event instanceof TranslationUpdated) {
+            $this->flush($event->old['group'], array_keys($event->old['text'] ?? []));
+        }
+    }
+
+    private function flush(string $group, array $locales): void
+    {
+        foreach ($locales as $locale) {
+            Cache::forget(LanguageLine::getCacheKey($group, $locale));
+        }
+    }
+}

src/Localization/Listeners/LogTranslationActivity.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace Modules\Core\Localization\Listeners;
+
+use Illuminate\Support\Arr;
+use Modules\Core\Localization\Events\TranslationCreated;
+use Modules\Core\Localization\Events\TranslationDeleted;
+use Modules\Core\Localization\Events\TranslationUpdated;
+use Modules\Core\Logging\ActivityLogService;
+use Spatie\TranslationLoader\LanguageLine;
+
+class LogTranslationActivity
+{
+    public function __construct(
+        private readonly ActivityLogService $activityLog,
+    ) {}
+
+    public function handle(TranslationCreated|TranslationUpdated|TranslationDeleted $event): void
+    {
+        $languageLine = $event->languageLine;
+
+        match (true) {
+            $event instanceof TranslationCreated => $this->activityLog->created(
+                $languageLine,
+                $this->flatten($languageLine),
+            ),
+            $event instanceof TranslationUpdated => $this->activityLog->updated(
+                $languageLine,
+                Arr::dot($event->old),
+                $this->flatten($languageLine),
+            ),
+            $event instanceof TranslationDeleted => $this->activityLog->deleted(
+                $languageLine,
+                $this->flatten($languageLine),
+            ),
+        };
+    }
+
+    /**
+     * Filament's Activity resource renders `properties` with a flat KeyValue
+     * field, which can't display a nested value like `text: {en, el}` — it
+     * shows as "[object Object]". Flatten to dot-notation ("text.en",
+     * "text.el") so every property is a plain string, viewable as-is.
+     */
+    private function flatten(LanguageLine $languageLine): array
+    {
+        return Arr::dot([
+            'group' => $languageLine->group,
+            'key' => $languageLine->key,
+            'text' => $languageLine->text,
+        ]);
+    }
+}

src/Localization/Listeners/MigrateTranslationsForRenamedLanguage.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace Modules\Core\Localization\Listeners;
+
+use Illuminate\Support\Facades\Cache;
+use Modules\Core\Localization\Events\LanguageUpdated;
+use Spatie\TranslationLoader\LanguageLine;
+
+/**
+ * A renamed Language::code (e.g. "el" -> "gr") would otherwise strand every
+ * LanguageLine's translated text under the old, now-unroutable key —
+ * getTranslationsForGroup($newCode, ...) would silently return nothing for
+ * that locale even though the translated content still exists. Move the
+ * text.{oldCode} key to text.{newCode} on every affected row instead.
+ */
+class MigrateTranslationsForRenamedLanguage
+{
+    public function handle(LanguageUpdated $event): void
+    {
+        $oldCode = $event->old['code'];
+        $newCode = $event->language->code;
+
+        if ($oldCode === $newCode) {
+            return;
+        }
+
+        $affectedGroups = [];
+
+        LanguageLine::query()
+            ->whereJsonContainsKey('text->'.$oldCode)
+            ->each(function (LanguageLine $languageLine) use ($oldCode, $newCode, &$affectedGroups) {
+                $text = $languageLine->text;
+                $text[$newCode] = $text[$oldCode];
+                unset($text[$oldCode]);
+
+                $languageLine->update(['text' => $text]);
+
+                $affectedGroups[$languageLine->group] = true;
+            });
+
+        foreach (array_keys($affectedGroups) as $group) {
+            Cache::forget(LanguageLine::getCacheKey($group, $oldCode));
+            Cache::forget(LanguageLine::getCacheKey($group, $newCode));
+        }
+    }
+}

src/Localization/Middleware/LocaleMiddleware.php

@@ -0,0 +1,107 @@
+<?php
+
+namespace Modules\Core\Localization\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\App;
+use Illuminate\Support\Facades\URL;
+use Illuminate\Support\Facades\View;
+use Lunar\Models\Language;
+use Modules\Core\Localization\Services\LanguageCache;
+use Symfony\Component\HttpFoundation\Response;
+
+class LocaleMiddleware
+{
+    public function __construct(private readonly LanguageCache $languages) {}
+
+    public function handle(Request $request, Closure $next): Response
+    {
+        $languages = $this->languages->all();
+
+        if ($languages->isEmpty()) {
+            return $next($request);
+        }
+
+        $segment = (string) $request->segment(1);
+        $language = $languages->firstWhere('code', $segment);
+
+        if (! $language) {
+            return $this->redirectToLocalizedUrl($request, $languages);
+        }
+
+        App::setLocale($language->code);
+        $request->attributes->set('locale', $language->code);
+        $request->attributes->set('language', $language);
+
+        // Lets route() calls omit {locale} anywhere in the request lifecycle
+        // (controllers, views) — without this, every route() call would need
+        // locale passed explicitly every time.
+        URL::defaults(['locale' => $language->code]);
+
+        $this->shareLocaleViewData($request, $language, $languages);
+
+        return $next($request);
+    }
+
+    /**
+     * Shares the current locale and every OTHER available locale (each with its
+     * own URL for the current page) with all views, so the header language
+     * switcher and layout hreflang tags don't have to recompute it.
+     *
+     * `altLocales` is a collection, not a single value — firstWhere('code', '!=',
+     * ...) would only ever surface one alternate, which happens to look correct
+     * with exactly 2 configured languages (there's only one "other" to find) but
+     * silently drops every locale past the first for a 3+ language store, with no
+     * error, just fewer switcher options than actually configured. A view iterates
+     * `$altLocales` to render as many links/dropdown entries as there are
+     * alternates, whether that's 1 or 10.
+     */
+    private function shareLocaleViewData(Request $request, Language $language, Collection $languages): void
+    {
+        $route = $request->route();
+        $routeName = $route?->getName();
+
+        $altLocales = $languages
+            ->reject(fn (Language $other) => $other->code === $language->code)
+            ->map(fn (Language $other) => [
+                'code' => $other->code,
+                'name' => $other->name,
+                'url' => $routeName
+                    ? route($routeName, array_merge($route->parameters(), ['locale' => $other->code]))
+                    : url('/'.$other->code),
+            ])
+            ->values();
+
+        View::share('currentLocale', $language->code);
+        View::share('altLocales', $altLocales);
+    }
+
+    private function redirectToLocalizedUrl(Request $request, Collection $languages): Response
+    {
+        $locale = $this->negotiateLocale($request, $languages);
+
+        $path = trim($request->getPathInfo(), '/');
+        $target = '/'.$locale.($path !== '' ? '/'.$path : '');
+
+        $query = $request->getQueryString();
+        if ($query) {
+            $target .= '?'.$query;
+        }
+
+        return redirect($target);
+    }
+
+    private function negotiateLocale(Request $request, Collection $languages): string
+    {
+        $preferred = $request->getPreferredLanguage($languages->pluck('code')->all());
+
+        if ($preferred) {
+            return $preferred;
+        }
+
+        return $languages->firstWhere('default', true)?->code
+            ?? $languages->first()->code;
+    }
+}

src/Localization/Models/LanguageLine.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Modules\Core\Localization\Models;
+
+use Modules\Core\Localization\Services\LanguageCache;
+use Spatie\TranslationLoader\LanguageLine as BaseLanguageLine;
+
+/**
+ * Overrides the base package's locale fallback (config('app.fallback_locale'), a
+ * static .env value) with the store's actual default language — Lunar's
+ * `languages.default` flag, the same source LocaleMiddleware/LanguageCache already
+ * treat as the single source of truth for "this store's default language".
+ *
+ * Without this, changing the default language via the Filament Languages resource
+ * has no effect on which locale an untranslated storefront label falls back to —
+ * two disconnected "default locale" concepts silently drifting apart. Swapped in
+ * via config('translation-loader.model') (see LocalizationServiceProvider), the
+ * package's own documented extension point for this.
+ */
+class LanguageLine extends BaseLanguageLine
+{
+    public function getTranslation(string $locale): ?string
+    {
+        if (isset($this->text[$locale])) {
+            return $this->text[$locale];
+        }
+
+        $fallback = app(LanguageCache::class)->defaultLocale();
+
+        return $fallback !== null ? ($this->text[$fallback] ?? null) : null;
+    }
+}

src/Localization/Observers/LanguageCacheObserver.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Modules\Core\Localization\Observers;
+
+use Illuminate\Support\Facades\Event;
+use Lunar\Models\Language;
+use Modules\Core\Localization\Events\LanguageCreated;
+use Modules\Core\Localization\Events\LanguageDeleted;
+use Modules\Core\Localization\Events\LanguageUpdated;
+
+class LanguageCacheObserver
+{
+    public function created(Language $language): void
+    {
+        Event::dispatch(new LanguageCreated($language));
+    }
+
+    public function updated(Language $language): void
+    {
+        Event::dispatch(new LanguageUpdated($language, [
+            'code' => $language->getOriginal('code'),
+        ]));
+    }
+
+    public function deleted(Language $language): void
+    {
+        Event::dispatch(new LanguageDeleted($language));
+    }
+}

src/Localization/Services/LanguageCache.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace Modules\Core\Localization\Services;
+
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Cache;
+use Lunar\Models\Language;
+
+/**
+ * Cached read layer over Lunar's `languages` table — the single source both
+ * Modules\Core\Localization\Middleware\LocaleMiddleware (request-time locale resolution) and
+ * any other locale-aware code (e.g. Modules\Core\Catalog\Services\ProductService) read
+ * from, so the language list is fetched once per cache lifetime rather than once
+ * per caller. Cached forever, invalidated via forget() by
+ * Modules\Core\Localization\Listeners\FlushLanguageCache on
+ * LanguageCreated/LanguageUpdated/LanguageDeleted.
+ */
+class LanguageCache
+{
+    private const CACHE_KEY = 'core.localization.languages';
+
+    public function all(): Collection
+    {
+        return Cache::rememberForever(
+            self::CACHE_KEY,
+            fn () => Language::query()->get(['id', 'code', 'name', 'default']),
+        );
+    }
+
+    /**
+     * The store's default language code (e.g. 'el') - the fixed fallback other
+     * locale-aware code should use, as opposed to config('app.locale') which
+     * App::setLocale() mutates per request and so can't serve as a stable
+     * fallback.
+     */
+    public function defaultLocale(): ?string
+    {
+        return $this->all()->firstWhere('default', true)?->code;
+    }
+
+    /**
+     * Every configured store locale code (e.g. ['el', 'en']) - for code that needs
+     * to enumerate all locales a TranslatedText attribute was indexed under (see
+     * Modules\Core\Catalog\Services\ProductService::withLocalizedFields()), rather than
+     * hardcoding locale codes.
+     *
+     * @return array<int, string>
+     */
+    public function availableLocales(): array
+    {
+        return $this->all()->pluck('code')->all();
+    }
+
+    public function forget(): void
+    {
+        Cache::forget(self::CACHE_KEY);
+    }
+}

src/Localization/Services/StorefrontLabels.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace Modules\Core\Localization\Services;
+
+/**
+ * Default storefront UI label translations (group `storefront`), seeded by
+ * Modules\Core\Command\InstallLunarCommand. Kept as its own class, separate from
+ * the seeding logic, so the actual label list can be scanned/diffed without wading
+ * through the upsert mechanics — see InstallLunarCommand::seedStorefrontLabels()
+ * for how (and how safely) these get written.
+ */
+class StorefrontLabels
+{
+    /**
+     * @return array<string, array<string, string>> keyed by `group.key` dot-notation,
+     *   each value a locale => text map (`en`/`el`).
+     */
+    public static function all(): array
+    {
+        return [
+            'nav.home' => ['en' => 'Home', 'el' => 'Αρχική'],
+            'nav.products' => ['en' => 'Products', 'el' => 'Προϊόντα'],
+            'nav.cart' => ['en' => 'Cart', 'el' => 'Καλάθι'],
+            'nav.account' => ['en' => 'Account', 'el' => 'Λογαριασμός'],
+            'nav.back' => ['en' => 'Back', 'el' => 'Πίσω'],
+            'nav.contact' => ['en' => 'Contact', 'el' => 'Επικοινωνία'],
+            'cart.empty' => ['en' => 'Your cart is empty', 'el' => 'Το καλάθι σας είναι άδειο'],
+            'cart.checkout' => ['en' => 'Checkout', 'el' => 'Ολοκλήρωση Παραγγελίας'],
+            'cart.total' => ['en' => 'Total', 'el' => 'Σύνολο'],
+            'cart.remove' => ['en' => 'Remove', 'el' => 'Αφαίρεση'],
+            'product.add_to_cart' => ['en' => 'Add to Cart', 'el' => 'Προσθήκη στο Καλάθι'],
+            'product.out_of_stock' => ['en' => 'Out of Stock', 'el' => 'Εξαντλήθηκε'],
+            'product.price' => ['en' => 'Price', 'el' => 'Τιμή'],
+            'product.description' => ['en' => 'Description', 'el' => 'Περιγραφή'],
+            'product.no_image' => ['en' => 'No image', 'el' => 'Χωρίς εικόνα'],
+            'product.read_more' => ['en' => 'Read more', 'el' => 'Περισσότερα'],
+            'product.reviews' => ['en' => 'Reviews', 'el' => 'Αξιολογήσεις'],
+            'auth.login' => ['en' => 'Log In', 'el' => 'Σύνδεση'],
+            'auth.logout' => ['en' => 'Log Out', 'el' => 'Αποσύνδεση'],
+            'search.placeholder' => ['en' => 'Search products…', 'el' => 'Αναζήτηση προϊόντων…'],
+            'customer_reviews' => [
+                'en' => '{0} No customer reviews|{1} :count customer review|[2,*] :count customer reviews',
+                'el' => '{0} Καμία αξιολόγηση πελάτη|{1} :count αξιολόγηση πελάτη|[2,*] :count αξιολογήσεις πελατών',
+            ],
+            'pagination.nav_label' => ['en' => 'Pagination', 'el' => 'Σελιδοποίηση'],
+            'pagination.next' => ['en' => 'Next page', 'el' => 'Επόμενη σελίδα'],
+            'pagination.previous' => ['en' => 'Previous page', 'el' => 'Προηγούμενη σελίδα'],
+            'pagination.page' => ['en' => 'Page :page', 'el' => 'Σελίδα :page'],
+            'review.rating' => ['en' => 'Rating', 'el' => 'Βαθμολογία'],
+            'review.write_label' => ['en' => 'Write a review', 'el' => 'Γράψε μια αξιολόγηση'],
+            'review.name' => ['en' => 'Name', 'el' => 'Όνομα'],
+            'review.name_optional' => ['en' => 'Optional', 'el' => 'Προαιρετικό'],
+            'review.email' => ['en' => 'Email', 'el' => 'Email'],
+            'review.email_not_published' => ['en' => 'Will not be published', 'el' => 'Δεν θα δημοσιευτεί'],
+            'review.save_info' => [
+                'en' => 'Save my name and email for the next time I comment.',
+                'el' => 'Αποθήκευσε το όνομα και το email μου για την επόμενη φορά που θα σχολιάσω.',
+            ],
+            'review.submit' => ['en' => 'Submit', 'el' => 'Υποβολή'],
+            'review.stars_count' => ['en' => '{1} :count star|[2,*] :count stars', 'el' => '{1} :count αστέρι|[2,*] :count αστέρια'],
+            'review.no_reviews_yet' => ['en' => 'No reviews yet.', 'el' => 'Δεν υπάρχουν αξιολογήσεις ακόμα.'],
+            'review.write_first' => ['en' => 'Write the first review', 'el' => 'Γράψε την πρώτη'],
+            'review.write_new' => ['en' => 'Add a review', 'el' => 'Πρόσθεσε μια'],
+            'review.for_product' => ['en' => 'review for ":name"', 'el' => 'αξιολόγηση για το «:name»'],
+            'shop.showing_results' => [
+                'en' => '{0} No products found|{1} Showing :first–:last of :total result|[2,*] Showing :first–:last of :total results',
+                'el' => '{0} Δεν βρέθηκαν προϊόντα|{1} Εμφάνιση :first–:last από :total αποτέλεσμα|[2,*] Εμφάνιση :first–:last από :total αποτελέσματα',
+            ],
+            'shop.sort_label' => ['en' => 'Sort products', 'el' => 'Ταξινόμηση προϊόντων'],
+            'shop.sort_default' => ['en' => 'Default sorting', 'el' => 'Προεπιλεγμένη ταξινόμηση'],
+            'shop.sort_popularity' => ['en' => 'Popularity', 'el' => 'Δημοφιλή'],
+            'shop.sort_price_asc' => ['en' => 'Price: Low to High', 'el' => 'Τιμή: Αύξουσα'],
+            'shop.sort_price_desc' => ['en' => 'Price: High to Low', 'el' => 'Τιμή: Φθίνουσα'],
+            'shop.sort_newest' => ['en' => 'Newest', 'el' => 'Νεότερα'],
+            'shop.no_products' => ['en' => 'No products found in this category.', 'el' => 'Δεν βρέθηκαν προϊόντα σε αυτή την κατηγορία.'],
+            'shop.search_label' => ['en' => 'Search products', 'el' => 'Αναζήτηση προϊόντων'],
+            'shop.search_placeholder' => ['en' => 'Search products…', 'el' => 'Αναζήτησε προϊόντα…'],
+            'shop.filter_price' => ['en' => 'Filter by price', 'el' => 'Φίλτρο τιμής'],
+            'shop.price_min' => ['en' => 'Min price', 'el' => 'Ελάχιστη τιμή'],
+            'shop.price_max' => ['en' => 'Max price', 'el' => 'Μέγιστη τιμή'],
+            'shop.reset' => ['en' => 'Reset', 'el' => 'Επαναφορά'],
+            'shop.apply' => ['en' => 'Apply', 'el' => 'Εφαρμογή'],
+            'shop.availability' => ['en' => 'Availability', 'el' => 'Διαθεσιμότητα'],
+            'shop.in_stock_only' => ['en' => 'In-stock products only', 'el' => 'Μόνο διαθέσιμα προϊόντα'],
+        ];
+    }
+}

src/Localization/Services/TranslationReader.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Modules\Core\Localization\Services;
+
+use Illuminate\Support\Facades\App;
+use Spatie\TranslationLoader\LanguageLine;
+
+class TranslationReader
+{
+    private const DEFAULT_GROUP = 'storefront';
+
+    /**
+     * All labels in a group for the given (or current) locale, keyed by their
+     * dot-notation key — e.g. ['nav.cart' => 'Cart', 'nav.home' => 'Home'].
+     * Backed by LanguageLine's own forever-cache, so this is a cache hit after
+     * the first call for a given group+locale.
+     */
+    public function group(string $group = self::DEFAULT_GROUP, ?string $locale = null): array
+    {
+        return LanguageLine::getTranslationsForGroup($locale ?? App::getLocale(), $group);
+    }
+}

src/Localization/Services/TranslationService.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace Modules\Core\Localization\Services;
+
+use Illuminate\Support\Facades\Event;
+use Modules\Core\Localization\Events\TranslationCreated;
+use Modules\Core\Localization\Events\TranslationDeleted;
+use Modules\Core\Localization\Events\TranslationUpdated;
+use Spatie\TranslationLoader\LanguageLine;
+
+class TranslationService
+{
+    public function create(string $group, string $key, array $text): LanguageLine
+    {
+        $languageLine = LanguageLine::create([
+            'group' => $group,
+            'key' => $key,
+            'text' => $text,
+        ]);
+
+        Event::dispatch(new TranslationCreated($languageLine));
+
+        return $languageLine;
+    }
+
+    public function update(LanguageLine $languageLine, string $group, string $key, array $text): LanguageLine
+    {
+        // Callers (e.g. Filament's EditRecord) may hand us a model instance
+        // already filled with the new form values in memory — refresh from the
+        // database first so $old reflects what's actually persisted, not what's
+        // about to be written.
+        $persisted = $languageLine->fresh();
+
+        $old = [
+            'group' => $persisted->group,
+            'key' => $persisted->key,
+            'text' => $persisted->text,
+        ];
+
+        $languageLine->update([
+            'group' => $group,
+            'key' => $key,
+            'text' => $text,
+        ]);
+
+        Event::dispatch(new TranslationUpdated($languageLine, $old));
+
+        return $languageLine;
+    }
+
+    public function delete(LanguageLine $languageLine): void
+    {
+        $languageLine->delete();
+
+        Event::dispatch(new TranslationDeleted($languageLine));
+    }
+}