Bump version to 0.16.1

Fix: Correcting spaceing on login form
Bump Version to 0.16.0
2026-09-09 23:25:22 +03:00 · 2026-09-09 23:22:13 +03:00 · 2026-09-09 01:19:31 +03:00 · 2026-09-09 01:12:21 +03:00 · 2026-09-09 00:48:52 +03:00 · 2026-09-09 00:48:09 +03:00
196 changed files with 12926 additions and 307 deletions
@@ -4,6 +4,328 @@ 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.16.1] - 2026-09-09
+
+### Fixed
+- OTP login page (`resources/views/auth/filament/pages/login.blade.php`) had no visible spacing
+  between the email/OTP input, error text, and buttons following the Filament v3 → v4 upgrade.
+  The view relied on a bare `grid gap-y-4` Tailwind utility class, but since this view ships from
+  the `boboko-core` package rather than a consuming app, that class was never present in any
+  host app's compiled Tailwind output. Replaced with an inline `style` (flex column, `row-gap:
+  1rem`) so the layout no longer depends on the consuming app's Tailwind content scanning.
+
+## [0.16.0] - 2026-09-08
+
+### Added
+- `Modules\Core\Checkout\Services\CheckoutService::setRecoveryConsent(bool $consent): Cart` — the
+  shopper's promotional/abandoned-cart-recovery opt-in, given once during guest checkout and
+  deliberately independent of `setShippingAddress()`/`setBillingAddress()`: consent is a
+  cart-level decision, not tied to any one `CartAddress` — changing which address is on the cart
+  later never resets or re-asks for it. Only an explicit call to this method (the checkbox itself
+  being submitted) ever changes it; calling it again with `false` is how a later opt-out is
+  recorded, per the legal requirement that consent be provable and withdrawable. Stored on
+  `Cart::meta` (interim, per the design this implements — a real column/consent record is the
+  eventual target, tracked as follow-up) as `recovery_consent` (bool), `recovery_consent_at`
+  (ISO 8601, `null` when `false`), and `recovery_consent_policy_version`
+  (`config('legal.privacy_policy_version')` at the moment of consent, so a later dispute is
+  answered from what was actually agreed to). Dispatches new
+  `Modules\Core\Checkout\Events\RecoveryConsentSet`. Newsletter opt-in is explicitly a separate
+  scope — never merged into this flag.
+- `Modules\Core\Checkout\Services\CheckoutService::initiatePayment()` now requires `bool
+  $termsAccepted` and `string $policyVersion` as mandatory parameters (not optional data a caller
+  might omit) — throws the new `Modules\Core\Checkout\Exceptions\TermsNotAcceptedException`
+  *before* `Cart::createOrder()` is ever called if `$termsAccepted` is `false`, so an order can
+  never exist without a recorded acceptance (refused, not created-then-flagged). On success,
+  writes `terms_accepted` (`true`), `terms_accepted_at` (ISO 8601), and
+  `terms_accepted_policy_version` onto the created `Order`'s own `meta` — the durable,
+  order-level audit trail for a consumer-contract acceptance dispute, written directly (not via
+  an event/listener) since the `Order` row doesn't exist until `createOrder()` returns.
+- `Modules\Core\Cart\Commands\DetectAbandonedCarts` — both its `CartAbandoned` and
+  `CheckoutAbandoned` detection queries now require `meta->recovery_consent = true`. A
+  non-consenting cart's abandonment is never dispatched at all (not merely filtered later at
+  whatever future recovery-email send step reads it) — the correct enforcement point per the
+  legal requirement that recovery/marketing sends only ever reach carts that opted in.
+- `config/legal.php` (merged by a new `Modules\Core\Providers\CheckoutServiceProvider`) —
+  `privacy_policy_version`/`terms_version`, plain `env()`-backed strings bumped by whoever edits
+  the corresponding legal page. Recorded alongside every consent/acceptance rather than read live
+  at dispute time, so what a shopper actually agreed to is answered from the cart/order itself.
+  `CheckoutServiceProvider` itself is new — `Checkout` previously had no dedicated service
+  provider at all (its service/events were resolved/dispatched without one).
+
+## [0.15.0] - 2026-09-07
+
+### Changed
+- **Breaking:** `Modules\Core\Payment\Models\PaymentMethod` is now the full DB-instance layer for
+  Payment, same three-layer split (registry / DB instance / cross-cutting config) `Shipping`
+  already has via `ShippingMethod` — see `docs/payments.md`. Every value that used to live in
+  `config('lunar.payments.types.{type}.*')` (`payment_driver`, `capture_mode`, `captured_status`)
+  moves onto the `PaymentMethod` row itself as real columns: `driver` (the new
+  `PaymentDriverRegistry` key — NOT the same as `type`; two rows can share one driver), `name`
+  (admin-facing label, nothing played this role before), `capture_mode`, `captured_status`,
+  `authorized_status`, `position` (admin-controlled ordering, new — reorderable in the Filament
+  table), `driver_missing_at`. `config('lunar.payments.types')` is gone entirely; `config/
+  payment.php` now holds only `cart_pipeline` (genuinely cross-cutting — every store gets the
+  same pipeline wiring regardless of how many payment methods it configures).
+- **Breaking:** `Modules\Core\Payment\Services\PaymentDriverResolver` is deleted, replaced by
+  `Modules\Core\Payment\Services\PaymentDriverRegistry` — `register(string $key, string
+  $driverClass)`/`resolve(string $key): ?object`/`all(): array<string, string>`. Deliberately
+  knows nothing about `PaymentMethod` or the database (mirrors `Lunar\Shipping\Managers\
+  ShippingManager`'s built-in-methods + `Manager::extend()` split, purpose-built rather than
+  extending `Illuminate\Support\Manager` — Payment's drivers implement several independent
+  capability interfaces at once, not one uniform contract). Built-ins (`OfflinePaymentDriver`
+  as `'offline'`, `StripePaymentDriver` as `'stripe'`) registered in
+  `PaymentServiceProvider::boot()`, exactly how `Shipping::extend('acs', ...)` already works.
+- **Breaking:** `Modules\Core\Checkout\Services\CheckoutService::getPaymentMethods()` now returns
+  `Illuminate\Support\Collection<int, PaymentMethod>` (ordered by `position`), not
+  `array<string>`. A method is offered only once three independent checks all pass — `enabled`
+  (admin turned it on), `driver_missing_at` is null (the driver class still exists), and the
+  resolved driver's own `Configurable::isConfigured()` (its runtime requirements are met) — each
+  failure meaning something different to an admin diagnosing why a method isn't showing up.
+  `initiatePayment()` resolves the driver via the selected row's own `driver` column, not `type`.
+- `Modules\Core\Payment\Filament\Resources\PaymentMethodResource` — `canCreate()`/`canDelete()`
+  now both `true` (previously hardcoded `false`, since a row could only ever be a config-defined
+  type before this release). New create/edit form (`name`, `type`, `driver` — a `Select`
+  populated live from `PaymentDriverRegistry::all()`, `capture_mode`, `captured_status`,
+  `authorized_status`); reorderable table (`->reorderable('position')`); a distinct "Driver
+  status" icon column (separate from the `enabled` toggle) showing whether `driver_missing_at`
+  is set.
+- `Modules\Core\Order\Listeners\ApplyResolvedPaymentStatus` reads `captured_status`/
+  `authorized_status` off the `PaymentMethod` row (`where('type', $event->type)`) instead of
+  `config(...)`.
+- `Modules\Core\Command\InstallLunarCommand::seedPaymentMethods()` no longer iterates
+  `config('lunar.payments.types')` — it seeds exactly one opinionated `cash-on-delivery` starter
+  row, every value a plain literal in the command itself (not sourced from config or the
+  registry — a driver has no business carrying opinions about what its captured order status
+  should be called; that's a merchant decision). Skip-if-exists, same as before.
+
+### Added
+- `php artisan boboko:payment:sync-drivers` — reconciles every `PaymentMethod` row's `driver`
+  against `PaymentDriverRegistry`, setting `driver_missing_at` when a driver no longer resolves
+  (a package removed, a custom `register()` call deleted) and clearing it automatically if that
+  driver is registered again in a later deploy. Deliberately its own standalone command, meant to
+  run unconditionally on every container start/deploy (Dockerfile entrypoint, alongside
+  `migrate`) — "did the set of registered drivers change" is a deploy-time event, cheap enough to
+  check every time regardless of whether anything actually changed. Verified live: flags a row
+  whose `driver` was manually corrupted, and auto-clears the flag once the driver resolves again.
+- `docs/payments.md` — new "Registry, DB instance, and cross-cutting config" section: the
+  three-layer split researched against `Shipping`'s own already-existing pattern and three real
+  e-commerce platforms (Shopify, WooCommerce, Medusa.js), the "would a store ever plausibly want
+  two different answers to this" test for deciding config vs. DB-column placement, and the
+  three-check availability chain.
+
+- `Modules\Core\Payment\Services\PaymentMethodCache` (`Cache::rememberForever`, same pattern as
+  `Localization\Services\LanguageCache`) + `Modules\Core\Payment\Services\PaymentMethodService`
+  (`create`/`update`/`delete`/`list`) — the single read/write gateway for `PaymentMethod` now used
+  by every Filament resource action (create, edit, edit-fee, delete, the inline `enabled` toggle)
+  instead of the Eloquent model directly, so the cache is invalidated and
+  `PaymentMethodCreated`/`PaymentMethodUpdated`/`PaymentMethodDeleted`/`PaymentMethodsReordered`
+  dispatch on every write, with no exceptions other than Filament's own drag-to-reorder (which
+  does a raw bulk SQL `UPDATE` on the position column directly via
+  `CanReorderRecords`/`reorderTable()`, before `afterReordering()` fires — a confirmed, unavoidable
+  Filament limitation; the reorder hook only clears the cache and dispatches
+  `PaymentMethodsReordered` afterward). `CheckoutService::getPaymentMethods()` and
+  `ApplyResolvedPaymentStatus` both now read through the cache instead of querying `PaymentMethod`
+  directly.
+- `Modules\Core\Payment\Models\CoreTransaction` (a `Lunar\Models\Transaction` subclass) +
+  `Modules\Core\Payment\Support\TransactionDriverAdapter`, registered via
+  `Lunar\Facades\ModelManifest::replace(Lunar\Models\Contracts\Transaction::class,
+  CoreTransaction::class)` — the same contract-swap mechanism already used elsewhere for
+  `Customer`/`Staff`. Fixes a real crash (`InvalidArgumentException: Driver [cash-on-delivery] not
+  supported`) the first time anything called `$transaction->refund()`/`->capture()`:
+  `Lunar\Models\Transaction::driver()` calls Lunar's own, entirely separate
+  `Lunar\Facades\Payments::driver()` manager, which had never heard of any of this codebase's
+  driver keys. `CoreTransaction::driver()` returns `TransactionDriverAdapter` instead, which
+  resolves the transaction's real `PaymentMethod`/`PaymentDriverRegistry` driver and calls it —
+  Lunar's own admin panel "Refund"/"Capture" buttons now transparently reach the real payment
+  system underneath, including correctly reporting failure (not a silently-faked success) when
+  the resolved driver doesn't implement `SupportsRefunds`/`SupportsCaptures`.
+- `TransactionDriverAdapter::refundVia(Transaction $transaction, ?string $driverKey, int $amount,
+  ?string $notes = null)` — refund through an explicitly chosen driver, independent of the one
+  the original payment went through (e.g. a cash-on-delivery order refunded via Bank Transfer,
+  which has no notion of the original offline payment at all). The order page's refund action
+  gained a "Refund via" `Select` (every `PaymentDriverRegistry` driver implementing
+  `SupportsRefunds`, defaulting to the transaction's own driver) that routes through this method
+  instead of `Lunar\Models\Transaction::refund()`, whose fixed signature has no room for a driver
+  override.
+- `Modules\Core\Payment\Drivers\BankTransferPaymentDriver` (registered as `'bank-transfer'`) —
+  manual/attested, same trust model as `OfflinePaymentDriver`: no gateway call, `pay()`/`refund()`
+  decide success immediately on a staff member's say-so. Implements both `SupportsPay` and
+  `SupportsRefunds`; exists specifically so a payment taken through a different method can still
+  be refunded via bank transfer. The admin UI for receiving a payment this way (bank reference,
+  notes, proof-of-transfer upload) is a follow-up — the driver itself is complete and usable via
+  the registry today.
+- `Modules\Core\Order\Filament\Infolists\TransactionEntry` (swapped in for Lunar's own
+  `Lunar\Admin\Support\Infolists\Components\Transaction` via a new
+  `OrderTransactionsExtension::extendTransactionsRepeatableEntry()` hook) — the order page's
+  transaction cards now also show a note recorded in `Transaction.meta['notes']` when the `notes`
+  column itself is empty. `Order\Services\TransactionRecorder` only ever wrote `notes` from
+  `PaymentResult::$failureReason`, which is never set on a successful result — a manual driver's
+  staff-entered note (e.g. `BankTransferPaymentDriver`'s) was being recorded but had nowhere to
+  render.
+- `Modules\Core\Payment\Listeners\LogPaymentMethodActivity` — `PaymentMethod` now has an admin
+  activity trail, unlike `Order`/`Transaction`/`Staff` it previously had none. Routes
+  `PaymentMethodCreated`/`Updated`/`Deleted` through the existing `Logging\ActivityLogService`
+  (the same one `Localization\Listeners\LogTranslationActivity` already uses) rather than adding
+  `PaymentMethod` to `Lunar\Base\Traits\LogsActivity`'s generic model-observer logging —
+  `PaymentMethodUpdated::$old`/`PaymentMethodDeleted::$method`'s snapshot already carry more
+  deliberate before/after context than Eloquent's own dirty-attribute diffing would reconstruct.
+  `PaymentMethodsReordered` is deliberately NOT logged — a multi-row position change doesn't fit
+  `ActivityLogService`'s one-`Model`-subject shape, and isn't worth a new method for a low-stakes,
+  purely-cosmetic setting.
+- New `payment_methods.refunded_status` column + form field (same `Select` pattern as
+  `captured_status`/`authorized_status`) — `ApplyResolvedPaymentStatus` now also reacts to
+  `PaymentRefunded`, so `Order.status` actually changes on a refund; before this, only the
+  *derived* `Order::paymentStatus()` reflected a refund (reading `transactions` live), while the
+  stored `status` column — what admin filtering, customer emails, etc. actually key off — never
+  moved. Resolves the ORIGINAL payment method for this lookup, not the refund event's own
+  `$type`: a refund routed through a different driver via `refundVia()` (e.g. cash-on-delivery
+  refunded through Bank Transfer) carries the REFUND driver's registry key as `$event->type`,
+  which usually isn't even a real `PaymentMethod.type` — the listener now finds the order's
+  earliest successful `capture`/`intent` transaction instead and reads `refunded_status` off
+  *that* transaction's own `PaymentMethod` row, since that's the payment the refund is actually
+  reversing. Deliberately no `void_status` yet — a void never moved money, so it doesn't carry
+  the same "the customer needs to see this changed" weight a refund does.
+
+### Fixed
+- Existing `PaymentMethod` rows seeded before this release (`cash-on-delivery`, `cash-in-hand`)
+  had `driver`/`capture_mode`/`captured_status` all `NULL` after the migration ran — a data
+  backfill was required (not automated by the migration itself) to restore them to a resolvable
+  state; flagged here since a consuming app upgrading past this release needs the same backfill
+  for its own pre-existing rows before `getPaymentMethods()` will offer them again.
+- `Lunar\Admin\Filament\Resources\OrderResource\Pages\ManageOrder::getRefundAction()`/
+  `getCaptureAction()` and `OrderItemsTable::getBulkRefundAction()` report a failed refund/capture
+  by calling `$action->failureNotification(...)`, `$action->failure()`, then `$action->halt()` —
+  but `Filament\Actions\Concerns\InteractsWithActions::callMountedAction()` only ever sends that
+  notification from a code path that runs after the action's closure returns normally; `halt()`
+  throws `Filament\Support\Exceptions\Halt`, caught by an earlier `catch` block that rolls back and
+  returns, so the notification was built but never sent — clicking "Refund" on a payment method
+  that genuinely can't be refunded looked like nothing happened at all, no error, no toast. Real,
+  pre-existing Filament/Lunar bug, invisible until this release's `TransactionDriverAdapter` made
+  an honest failure (rather than a hard crash or a silently-faked success) actually reachable.
+  Fixed via new `Modules\Core\Order\Filament\Extensions\OrderRefundActionsExtension`/
+  `OrderItemsTableExtension`, which wrap the affected actions' closures to send the queued failure
+  notification themselves before re-throwing `Halt`.
+- `TransactionDriverAdapter::refund()`/`capture()` never included `order_id` in the `$context`
+  passed to the driver, so `Order\Listeners\RecordPaymentTransaction`/`ApplyResolvedPaymentStatus`
+  (both requiring `$context['order_id']`) silently no-op'd for every admin-initiated refund/capture
+  through any driver — no audit `Transaction` row was ever created, regardless of whether the
+  refund/capture itself succeeded. Fixed by passing `$transaction->order_id` through.
+
+## [0.14.0] - 2026-09-03
+
+### Changed
+- **Breaking:** `Modules\Core\Catalog\Services\ProductSearchService::search()` now returns `Modules\Core\Catalog\DTOs\ProductListingResult` — the exact same shape `ProductService::list()` already returns — instead of a bare `Illuminate\Database\Eloquent\Collection<Product>` of hydrated models with no pagination at all. New signature: `search(string $query, ?ProductFilters $filters = null, ?ProductSort $sort = null, int $perPage = 24, int $page = 1): ProductListingResult`. `->products` is a real `LengthAwarePaginator` of plain, localized indexed-document arrays (not Eloquent models, not Scout's raw response) — a search results page and a category listing page are now interchangeable from a controller's perspective: same DTO, same `ProductCard::fromIndexed()` mapping, same pagination/sort/tag/price-slider handling. `->priceBounds`/`->availableTags` are scoped to the search query itself (delegated to `ProductService::priceSliderBounds()`/`availableTags()`, both of which already accepted a `$query` param for this).
+- `Modules\Core\Catalog\Services\ProductService::availableTags()` is now `public` (was `private`) and takes an optional `$query` parameter, so `ProductSearchService::search()` can reuse it directly instead of reimplementing the same facet call.
+
+### Added
+- `Modules\Core\Catalog\Support\ProductDocumentLocalizer` — the per-locale field resolution and raw-Meilisearch-response unwrapping (`withLocalizedFields()`, `hitsFrom()`) extracted out of `ProductService` into its own class, since `ProductSearchService` needed the exact same logic against the exact same kind of document. Both services now depend on this one class instead of `ProductService` owning logic a second service also needed.
+
+## [0.13.0] - 2026-09-03
+
+### Changed
+- **Breaking:** `Payment` is now a genuinely standalone module — no direct calls into `Checkout`/`Order`, no reaching into their Eloquent models, communication only via events. The entire old `confirm()`-based flow is gone: `Modules\Core\Payment\Contracts\PaymentDriver` (and the already-stale `Modules\Core\Checkout\Contracts\PaymentDriver` duplicate), `Checkout\Events\PaymentConfirmed`, `Payment\Contracts\InitiatesPayment`, `Payment\DataTransferObjects\PaymentInitiation`, `Payment\Enums\PaymentInitiationMode`, `Payment\Events\PaymentSucceeded`/`PaymentFailed`, `Payment\Events\OrderPaymentStatusResolved`, and `Payment\Exceptions\PaymentNotConfirmedException` are all deleted. This flow was non-functional on `master` before this release — `CheckoutService::confirmPayment()` dispatched an event nothing listened for, so no order was ever placed after payment.
+- **Breaking:** Every payment operation is now its own explicit, opt-in contract, modeled on how real gateways (Stripe, Mastercard's own gateway, Nexi) actually split these operations — see `docs/payments.md`: `Modules\Core\Payment\Contracts\SupportsPay` (atomic authorize+capture), `SupportsAuthorization` (hold only), `SupportsCaptures` (settle a prior hold), `SupportsVoids` (release a prior hold without settling), `SupportsRefunds` (reverse settled funds), `HandlesPaymentCallback` (resolve an async pay()/authorize() later, from a webhook), and `Configurable` (`isConfigured()`, split out of the old single `PaymentDriver` interface). A driver implements only the operations its gateway actually supports.
+- **Breaking:** Every amount flowing through these contracts is `Lunar\DataTypes\Price` (Lunar's own bundled minor-unit-value + `Currency` type) — never a bare `int` paired separately with a `Currency`. Each driver converts at its own boundary (e.g. `StripeManager::toStripeAmount()`/`fromStripeAmount()`); `Payment` itself only ever speaks Lunar's `Price`.
+- **Breaking:** `Modules\Core\Checkout\Services\CheckoutService::placeOrder()` and `confirmPayment()` are both replaced by a single `initiatePayment(string $fingerprint, array $data = []): Modules\Core\Payment\DTOs\PaymentResult`. It creates the draft `Order` (`Cart::createOrder()`, idempotent against an existing draft) and hands off directly to the resolved driver's `pay()`/`authorize()`, per that type's new `config('lunar.payments.types.{type}.capture_mode')` key. `Checkout\Events\OrderPlaced` no longer dispatches from `CheckoutService` — it now fires from `Modules\Core\Order\Listeners\ApplyResolvedPaymentStatus` once a `PaymentCaptured`/`PaymentAuthorized` event actually transitions the order's `placed_at`, since a draft order can now exist well before payment resolves (an async gateway).
+- `Modules\Core\Payment\Services\PaymentDriverResolver::resolve()` now returns `?object` instead of the deleted `PaymentDriver` interface — a driver implements several independent capability interfaces at once, so a caller does its own `instanceof SupportsPay`/`instanceof SupportsAuthorization` check, the same pattern the capability interfaces themselves are designed around.
+- `config/payment.php`'s `cash-on-delivery` entry gains `capture_mode` (`'pay'`, since `OfflinePaymentDriver` only implements `SupportsPay`) and `captured_status` (`'payment-offline'`, replacing the previously dead `'authorized' => 'awaiting-payment'` key, which nothing ever read).
+
+### Added
+- `Modules\Core\Payment\DTOs\PaymentResult` — the one return shape every operation (`pay`, `authorize`, `capture`, `void`, `refund`, `handleCallback`) produces, regardless of gateway: `status` (`Modules\Core\Payment\Enums\PaymentResultStatus`: `Succeeded`/`Failed`/`Pending`), `reference`, `amount` (a `Price`), `failureReason`, `retriable` (real on Stripe/Mastercard's own soft-decline classification, always `false` on Nexi — it has no such signal), `raw` (the untouched gateway response, for audit), `meta`, and `continuation` (see below).
+- `Modules\Core\Payment\DTOs\PaymentContinuation` / `Modules\Core\Payment\Enums\PaymentContinuationType` — what a caller does next with a `Pending` `PaymentResult`, gateway-agnostically (`Redirect` or `ClientSecret`), so a storefront controller never needs gateway-specific knowledge of e.g. Stripe's own `PaymentIntent` fields to drive a 3-D Secure/redirect continuation.
+- Eight new events, one terminal pair per operation, replacing the old single `PaymentSucceeded`/`PaymentFailed`: `PaymentAuthorized`/`PaymentAuthorizationFailed`, `PaymentCaptured`/`PaymentCaptureFailed`, `PaymentVoided`/`PaymentVoidFailed`, `PaymentRefunded`/`PaymentRefundFailed`. `PaymentCaptured` is deliberately the same event whether money was taken via `pay()` (one gateway call) or `authorize()`→`capture()` (two calls) — "a payment has been captured" is the same business fact either way. Every event carries `{type, result: PaymentResult, context}` — `context` is an opaque bag the caller hands in and gets back untouched, so `Payment` never needs to know what a `Cart` or `Order` is.
+- `Modules\Core\Order\Listeners\ApplyResolvedPaymentStatus` (rewired, not new — previously listened to the now-deleted `OrderPaymentStatusResolved`) is the only place an `Order`'s `status` column is written in reaction to a payment outcome: it listens to `PaymentCaptured`/`PaymentAuthorized` directly, reads `$event->context['order_id']`, and resolves the new status from `config('lunar.payments.types.{type}.captured_status')`/`authorized_status`.
+- `Modules\Core\Payment\Drivers\StripePaymentDriver` rewritten onto the new contracts — implements all six capability interfaces plus `Configurable`. Solves `handleCallback()`'s async-correlation problem (a webhook is a separate HTTP request from the `pay()`/`authorize()` call that started it) the same way `lunarphp/stripe`'s own `StripePaymentType`/`ProcessStripeWebhook` do: real `cart_id`/`order_id` columns on `Lunar\Stripe\Models\StripePaymentIntent`, plus two new columns this driver needs (`context`, `payment_type`) added by a new migration — `database/migrations/2026_09_03_000002_add_context_to_stripe_payment_intents.php`.
+- `Modules\Core\Payment\Http\Controllers\StripeWebhookController` + `src/Payment/routes/webhooks.php` (`POST /payments/stripe/webhook`, loaded by `PaymentServiceProvider`) — a boboko-owned webhook endpoint, deliberately not `lunarphp/stripe`'s own route (which dispatches into Lunar's own `Payments::driver('stripe')` flow, the flow this driver replaces). Reuses `Lunar\Stripe\Http\Middleware\StripeWebhookMiddleware` and `Stripe\Webhook::constructEvent()` directly — both are genuine Stripe SDK signature verification, safe to reuse without touching the rest of that vendor package's flow. Requires `config('services.stripe.webhooks.lunar')` set in a consuming app; no `stripe` config type entry is added to `config/payment.php` in this release — enabling Stripe for real is a follow-up.
+- `docs/payments.md` — full design notes: the operation/contract table cross-referenced against Mastercard/Stripe/Nexi's real APIs, why `PaymentResult` normalizes only what every gateway can always provide, the async-correlation pattern, and what's explicitly out of scope (a `Transaction`-writing listener, the `stripe` config entry, frontend Stripe Elements integration).
+
+### Fixed
+- `Modules\Core\Checkout\Services\CheckoutService::selectPaymentMethod()` crashed (`Call to a member function toArray() on null`) the first time it ran against a cart whose `meta` column was still a genuine SQL `NULL` (any freshly-created cart) — `Cart::$meta`'s `AsArrayObject` cast returns `null`, not an empty array-like object, for a `null` column. Fixed with a null-safe fallback.
+- `Modules\Core\Shipping\Carriers\Acs\AcsRateDriver`/`BoxNowRateDriver` referenced `Lunar\Shipping\DTOs\ShippingOptionRequest`, a namespace that doesn't exist in the installed `lunarphp/table-rate-shipping` version (the real class is `Lunar\Shipping\DataTransferObjects\ShippingOptionRequest`) — crashed `Illuminate\Support\Manager`'s interface-compatibility check the moment anything touched `ShippingManager::getSupportedDrivers()`, including simply adding a line to a cart (via `Modules\Core\Shipping\Listeners\FlushLivePricingCache`).
+
+## [0.13.1] - 2026-09-03
+
+### Added
+- `Modules\Core\Order\Listeners\RecordPaymentTransaction` — writes the `lunar_transactions` row for a successful `PaymentCaptured`/`PaymentAuthorized`/`PaymentVoided`/`PaymentRefunded` event, via a new `Modules\Core\Order\Services\TransactionRecorder` (moved here from `Payment\Services`, and rewritten to take a `PaymentResult` directly instead of the deleted `CaptureResult`/`RefundResult` DTOs — `Payment` never writes to `Order`'s models, `Transaction.order_id` being required is exactly why this lives in `Order`, same reasoning as `ApplyResolvedPaymentStatus`). Closes a real gap introduced in `0.13.0`: `Order::paymentStatus()` (which derives its answer entirely from `$order->transactions`) always resolved to `PaymentStatus::Offline` — its "no transactions at all" fallback — regardless of what actually happened, since nothing had ever written a row. Verified live: a captured offline payment now produces a `type: capture` transaction and `Order::paymentStatus()` correctly resolves to `captured`.
+
+## [0.12.1] - 2026-09-03
+
+### Fixed
+- `Modules\Core\MigrateImport\Shopify\ShopifyExportImporter` now attaches a variant's `Variant Image` CSV column to that `ProductVariant`'s own `images()` media pivot (`media_product_variant`, `primary`/`position`). Previously the variant image was never read at all — every image from the CSV, including ones the export clearly scopes to one specific variant, went only into the product's own top-level gallery, so a variant swatch/option change had no way to show its own photo.
+- `Modules\Core\MigrateImport\Shopify\Resolvers\ProductOptionResolver::resolveOption()` now sets `label` (same value as `name`) when creating a `Lunar\Models\ProductOption`, not just `name`. A `ProductOption` with a null `label` crashes Lunar's own `ProductOptionIndexer::toSearchableArray()` (`foreach()` on `null`) the moment that option gets reindexed — every option created by the importer before this fix has a null `label` and needs a wipe-and-reimport (see `docs/shopify-reimport.md`, new in this release) to pick up the fix, since `firstOrCreate()` never revisits an already-existing row.
+- `product_reviews.product_id`'s foreign key had no `ON DELETE` clause, so deleting a reviewed `Product` threw a constraint violation instead of the review going with it, unlike every other product-dependent table. New migration adds `cascadeOnDelete()`.
+
+### Added
+- `Modules\Core\Catalog\Services\ProductIndexer::mapVariant()` now embeds `gtin`, `mpn`, `ean`, `backorder`, `unit_quantity`, `shippable`, `tax_ref`, and `dimensions` (length/width/height/weight/volume, each with `value`+`unit`) on every indexed variant — previously only `id`/`sku`/`stock`/`purchasable`/`options`/`prices`/`media` were embedded, so a search result or filter needing any of these had no way to get at them without a separate Postgres query per variant.
+- `ProductIndexer::toSearchableArray()` adds a top-level, filterable `skus` field (every variant's SKU, deduplicated) — filtering/matching by SKU no longer requires reaching into the nested `variants` array.
+- `docs/shopify-reimport.md` — runbook for wiping every imported product (cascading through Lunar so Meilisearch documents go too) and re-running the importer from scratch, needed whenever a fix like the two above only takes effect on newly-created rows.
+
+## [0.12.0] - 2026-09-03
+
+### Changed
+- **Breaking:** `Modules\Core\Catalog\Services\ProductService::list()` now returns `Modules\Core\Catalog\DTOs\ProductListingResult` (`->products`: the same `Illuminate\Pagination\LengthAwarePaginator` as before, `->priceBounds`: a new `Modules\Core\Catalog\DTOs\PriceSliderBounds`) instead of returning the paginator directly. A caller doing `$service->list(...)->items()`/`->through(...)` must update to `$service->list(...)->products->items()`/`->through(...)`. This collapses what used to be two separate calls a controller had to orchestrate itself (`list()` for products, `priceRange()` + manual floor/ceil/"is this actually filtered" math for the slider) into one.
+- **Breaking:** `Modules\Core\Catalog\Services\ProductSearchService::search()`'s signature changed from `search(string $query, ?string $locale = null)` to `search(string $query, ?ProductFilters $filters = null, ?ProductSort $sort = null)` — the `$locale` parameter is gone (see "every configured language, always" below); `$filters`/`$sort` apply the same `Modules\Core\Catalog\Support\ProductFilterBuilder`/`ProductSort::toMeilisearchSort()` semantics `ProductService::list()` already used, so a text search can now be narrowed by price/brand/stock and sorted the same way a category listing can.
+- `ProductSearchService` now targets every configured store language's fields on every search (`Lunar\Models\Language::all()`), not just the current request locale plus the store's default language. The old `{current, default}` pairing silently stopped catching anything outside those two locales whenever they were equal (a single-language store, or a shopper browsing in the default language) — always searching every configured language closes that gap in both directions. See `docs/product-search.md`.
+- Extracted `Modules\Core\Catalog\Services\ProductService`'s private `buildFilter()` into a new standalone `Modules\Core\Catalog\Support\ProductFilterBuilder`, so `ProductSearchService` can apply the exact same Meilisearch filter-clause semantics to a text query, instead of reimplementing filter-building a second time.
+
+### Added
+- `Modules\Core\Catalog\Services\ProductService::priceSliderBounds()` — `priceRange()` rounded to whole currency units (floor/ceil) plus whether the given selected min/max actually narrows it, returned as a `PriceSliderBounds` DTO. Used internally by `list()` now; also callable directly for a caller (e.g. a text-search results page) that needs slider bounds without a full `list()` call.
+- `Modules\Core\Catalog\Services\ProductService::priceRange()` gained an optional `string $query = ''` parameter, so a caller can scope the price range to a text search's own matches (pass the shopper's search text) instead of always spanning the whole catalog.
+- `Modules\Core\Catalog\Services\ProductService::random(int $limit)` — random products still scoped to the Meilisearch index's own channel/status visibility, unlike a raw `Product::inRandomOrder()` (which has no notion of that filtering). Meilisearch has no `ORDER BY RANDOM()` equivalent, so this fetches every matching id only (`attributesToRetrieve: ['id']`), shuffles in PHP, then fetches the full localized documents for just the ids picked, restoring the shuffled order afterward (Meilisearch's `id IN [...]` filter doesn't preserve list order on its own).
+- `Modules\Core\Catalog\Services\ProductService::variantSummaries(array $product)` — the id/price/image of every variant on a product document, for a variant picker/swatch list, without a caller reaching into `$product['variants'][n]['prices'][0]`/`['media'][0]` itself.
+- `Modules\Core\Catalog\Services\ProductSearchService::search()` now also targets `variants.options.value` — a variant's own option value (e.g. "Κάπτεν Γαμέρικα" on a "Name" option) is matchable by search even when that text never appears in the product's own name or description.
+- `php artisan lunar:meilisearch:tune-product-search` (`Modules\Core\Command\TuneProductSearchCommand`) — tightens `minWordSizeForTypos` (1 typo only at 8+ characters, 2 typos only at 12+) and disables Meilisearch's `prefixSearch` on the product index. Meilisearch's defaults for both were loose enough to produce bad matches on short Greek words (confirmed the specific case was `prefixSearch`'s default `indexingTime` behavior on a shared word-start, not typo tolerance, via `showMatchesPosition`). Consuming apps should run this after `lunar:meilisearch:setup` whenever the product index needs (re)provisioning — **requires Meilisearch v1.12+** (`prefixSearch` didn't exist as a configurable setting before then).
+
+## [0.11.1] - 2026-09-01
+
+### Fixed
+- `Modules\Core\Catalog\Services\RecommendationService::recommend()` built its result with the base `Illuminate\Support\Collection` (`collect()`) instead of `Illuminate\Database\Eloquent\Collection`, even though every element is a `Product` model. `ProductIndexer::toSearchableArray()` calling `->load(['media', 'variants.prices'])` on that result threw `BadMethodCallException: Method Illuminate\Support\Collection::load does not exist` — silently failing every `MakeSearchable` queue job for a saved product (visible only as `FAIL` in the queue log, with the real exception in `storage/logs/laravel.log`). Fixed by having `RecommendationService` accumulate into a real `Eloquent\Collection` from the start.
+
+## [0.11.0] - 2026-09-01
+
+### Added
+- `Modules\Core\Catalog\Services\RecommendationService` — computes "related products" for a given product as a configurable, ordered chain of strategies (`config('catalog.recommendation_rules')`), not one hardcoded rule. Tops up from each successive rule until the limit (default 4) is reached or every rule is exhausted — e.g. 3 products from a same-category rule plus 1 from a random fallback — deduplicated across rules so the same product is never returned twice. Ships with `Modules\Core\Catalog\Recommendations\SameCategoryRule` (other products sharing the source product's first collection) and `RandomRule` (the universal fallback, placed last in the default chain). A new rule is just a class implementing `Modules\Core\Catalog\Contracts\RecommendationRule`. Documented in `docs/product-recommendations.md`.
+- `Modules\Core\Catalog\Services\ProductIndexer` embeds the result directly into each product's own Meilisearch document as `recommendations: [{id, name, price, image}, ...]` (`recommendations.id` filterable) — a product detail page renders its "related products" section with zero extra queries, same reasoning as the existing `collections` field. Deliberately embeds an `id` for the view to build a locale-correct URL from, not a resolved `href` — `product.show` is locale-prefixed, so a URL baked in at index time would only be correct for whichever locale happened to be active during that index run.
+- `Modules\Core\Catalog\Events\ProductSaved`/`ProductDeleted`, dispatched from `Product::saved()`/`Product::deleted()` in `CatalogServiceProvider` (the latter fires for both a soft delete and a force delete, matching Scout's own `unsearchable()` trigger point) — feed `Modules\Core\Catalog\Listeners\ReindexProductsRecommendingProduct`, which reverse-searches Meilisearch for every product currently recommending the changed/deleted one (`recommendations.id = "..."` — there's no Postgres relation for this, a recommendation only exists inside the index) and re-indexes them via Scout's own `->searchable()`. Product creation is deliberately not hooked into this: a new product not yet appearing as a recommendation elsewhere is an accepted staleness window, the same tradeoff already documented for `in_stock`/`price` — see `docs/product-recommendations.md`.
+- `CatalogServiceProvider` schedules `lunar:search:index "Lunar\Models\Product" --refresh` daily at 03:00 — a safety net on top of the event-driven reindexing above, covering a newly-created product not yet appearing as a recommendation and any other drift already accepted between reindexes. `--refresh` also re-syncs filterable/sortable index settings, not just documents.
+
+## [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
@@ -2,7 +2,7 @@
  "name": "boboko/core",
  "description": "Core module — authentication and shared panel behaviour",
  "type": "library",
-  "version": "0.8.0",
+  "version": "0.16.1",
  "autoload": {
    "psr-4": {
      "Modules\\Core\\": "src/"
@@ -10,14 +10,15 @@
  },
  "require": {
    "php": "^8.5",
-    "lunarphp/lunar": "1.3.0",
+    "lunarphp/lunar": "1.5.0",
    "laravel/framework": "^12.0",
    "laravel/tinker": "^3.0",
    "symfony/yaml": "^7.0",
-    "lunarphp/table-rate-shipping": "^1.3",
+    "lunarphp/table-rate-shipping": "1.5.0",
    "lunarphp/search": "*",
    "lunarphp/meilisearch": "*",
-    "spatie/laravel-translation-loader": "^2.8"
+    "spatie/laravel-translation-loader": "^2.8",
+    "lunarphp/stripe": "^1.5"
  },
  "require-dev": {
    "fakerphp/faker": "^1.23",
@@ -27,7 +28,8 @@
    "mockery/mockery": "^1.6",
    "nunomaduro/collision": "^8.6",
    "pestphp/pest": "^4.6",
-    "pestphp/pest-plugin-laravel": "^4.1"
+    "pestphp/pest-plugin-laravel": "^4.1",
+    "filament/upgrade": "^4.0"
  },
  "extra": {
    "laravel": {
@@ -35,10 +37,14 @@
        "Modules\\Core\\Providers\\CoreServiceProvider",
        "Modules\\Core\\Providers\\AuthServiceProvider",
        "Modules\\Core\\Providers\\CustomerServiceProvider",
+        "Modules\\Core\\Providers\\CheckoutServiceProvider",
+        "Modules\\Core\\Providers\\PaymentServiceProvider",
        "Modules\\Core\\Providers\\LocalizationServiceProvider",
        "Modules\\Core\\Providers\\CatalogServiceProvider",
        "Modules\\Core\\Providers\\CartServiceProvider",
-        "Modules\\Core\\Providers\\ReviewServiceProvider"
+        "Modules\\Core\\Providers\\ReviewServiceProvider",
+        "Modules\\Core\\Providers\\ShippingServiceProvider",
+        "Modules\\Core\\Providers\\OrderServiceProvider"
      ]
    }
  },
@@ -0,0 +1,25 @@
+<?php
+
+use Modules\Core\Catalog\Recommendations\RandomRule;
+use Modules\Core\Catalog\Recommendations\SameCategoryRule;
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Product recommendation rules
+    |--------------------------------------------------------------------------
+    |
+    | Tried in order by Modules\Core\Catalog\Services\RecommendationService —
+    | the first rule that returns at least one product wins. The order here IS
+    | the fallback chain: SameCategoryRule first, then RandomRule as a
+    | last-resort so a product page is never left with zero recommendations
+    | (as long as the store has more than one product). A consuming app can
+    | reorder, add, or remove rules freely — nothing about the chain shape is
+    | hardcoded in the service itself.
+    |
+    */
+    'recommendation_rules' => [
+        SameCategoryRule::class,
+        RandomRule::class,
+    ],
+];
@@ -0,0 +1,21 @@
+<?php
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Policy versions
+    |--------------------------------------------------------------------------
+    |
+    | Plain version strings, bumped by whoever edits the corresponding legal
+    | page — recorded alongside every consent/acceptance so a later dispute
+    | ("what did the shopper actually agree to?") can be answered from the
+    | order/cart itself rather than a live lookup against whatever the pages
+    | say TODAY. Not tied to any CMS/database row on purpose — this stays a
+    | plain config value the same way payment.php's cart_pipeline is a plain
+    | cross-cutting setting, not a per-instance one.
+    |
+    */
+    'privacy_policy_version' => env('LEGAL_PRIVACY_POLICY_VERSION', '2026-01-01'),
+
+    'terms_version' => env('LEGAL_TERMS_VERSION', '2026-01-01'),
+];
@@ -0,0 +1,28 @@
+<?php
+
+use Modules\Core\Payment\Pipelines\Cart\ApplyCashOnDeliveryFee;
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | 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.
+    |
+    | This is the one thing left in this file — everything about WHICH
+    | payment methods exist (driver mapping, capture_mode, statuses) moved
+    | onto Modules\Core\Payment\Models\PaymentMethod's own row (see
+    | docs/payments.md): that's a per-instance, merchant decision, not a
+    | store-wide-singular setting, so it never belonged in config at all.
+    | This pipeline registration IS genuinely cross-cutting — every store
+    | using this driver gets the same cart-pipeline wiring, regardless of
+    | how many payment methods it configures.
+    |
+    */
+    'cart_pipeline' => [
+        ApplyCashOnDeliveryFee::class,
+    ],
+];
@@ -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),
+
+];
@@ -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),
+
+];
@@ -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');
+    }
+};
@@ -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');
+    }
+};
@@ -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');
+    }
+};
@@ -0,0 +1,43 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * product_reviews.product_id's original foreign key (2026_07_10_000001) had
+ * no ON DELETE clause, so deleting a Product with reviews throws a
+ * constraint violation instead of the review rows going with it — unlike
+ * every other Product-dependent table (variants, media, etc.), which does
+ * cascade. A review is dependent, disposable data, not something worth
+ * blocking a product deletion over.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('product_reviews', function (Blueprint $table) {
+            $table->dropForeign(['product_id']);
+        });
+
+        Schema::table('product_reviews', function (Blueprint $table) {
+            $table->foreign('product_id')
+                ->references('id')
+                ->on(config('lunar.database.table_prefix').'products')
+                ->cascadeOnDelete();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('product_reviews', function (Blueprint $table) {
+            $table->dropForeign(['product_id']);
+        });
+
+        Schema::table('product_reviews', function (Blueprint $table) {
+            $table->foreign('product_id')
+                ->references('id')
+                ->on(config('lunar.database.table_prefix').'products');
+        });
+    }
+};
@@ -0,0 +1,47 @@
+<?php
+
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+use Lunar\Base\Migration;
+
+/**
+ * lunarphp/stripe's own stripe_payment_intents table already correlates a
+ * Stripe intent back to a cart/order via cart_id/order_id — exactly what
+ * Modules\Core\Payment\Drivers\StripePaymentDriver needs to recover
+ * $context in handleCallback(), a separate request (a webhook) from the
+ * pay()/authorize() call that originated it. Two columns this driver
+ * needs that the vendor table doesn't have:
+ *   - context: the full opaque $context bag pay()/authorize() received,
+ *     stored so handleCallback() can dispatch the SAME context the
+ *     original call would have, without Payment inventing its own
+ *     correlation table — see docs/payments.md "Async resolution".
+ *   - payment_type: the payment type key (e.g. 'stripe') pay()/authorize()
+ *     were called with — needed to dispatch Payment events with the
+ *     correct $type in handleCallback(), which otherwise has no way to
+ *     know it (a webhook payload doesn't carry it).
+ *
+ * Extends Lunar\Base\Migration (not the plain base Migration) so $this->prefix
+ * resolves the SAME table-prefix config every Lunar-owned table uses
+ * (config('lunar.database.table_prefix')) — the vendor migration that
+ * creates this table (lunarphp/stripe's create_stripe_payment_intents_table)
+ * already does this, so a store running with a non-default prefix (this
+ * one runs with 'lunar_') would otherwise have this migration fail against
+ * a table name that doesn't exist.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table($this->prefix.'stripe_payment_intents', function (Blueprint $table) {
+            $table->json('context')->nullable()->after('status');
+            $table->string('payment_type')->nullable()->after('context');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table($this->prefix.'stripe_payment_intents', function (Blueprint $table) {
+            $table->dropColumn(['context', 'payment_type']);
+        });
+    }
+};
@@ -0,0 +1,52 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Moves the driver mapping and per-type behavior that used to live in
+ * config('lunar.payments.types.{type}.*') onto the PaymentMethod row
+ * itself — same DB-instance-vs-config split Modules\Core\Shipping's own
+ * shipping_methods table already has (code/driver/name/enabled columns,
+ * no driver mapping in any config file). See docs/payments.md.
+ *
+ *   - driver: the Modules\Core\Payment\Services\PaymentDriverRegistry key
+ *     (NOT the same as `type` — two rows can share one driver).
+ *   - name: admin-facing label. Nothing played this role before; `type`
+ *     was always the machine slug.
+ *   - capture_mode / captured_status / authorized_status: per-instance
+ *     behavior — fails the "would a store ever want two different answers
+ *     to this" cross-cutting-config test, so these move off config.
+ *   - position: admin-controlled display/checkout order.
+ *   - driver_missing_at: set by the payment:sync-drivers command when
+ *     `driver` no longer resolves via the registry — deliberately
+ *     separate from `enabled`, so a driver vanishing (a deploy removed
+ *     it) is never confused with an admin's own manual toggle, and a
+ *     driver that comes back later auto-clears this with no admin action.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('payment_methods', function (Blueprint $table) {
+            $table->string('name')->nullable()->after('type');
+            $table->string('driver')->nullable()->after('name');
+            $table->string('capture_mode')->nullable()->after('driver');
+            $table->string('captured_status')->nullable()->after('capture_mode');
+            $table->string('authorized_status')->nullable()->after('captured_status');
+            $table->unsignedInteger('position')->default(0)->after('authorized_status');
+            $table->timestamp('driver_missing_at')->nullable()->after('position');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('payment_methods', function (Blueprint $table) {
+            $table->dropColumn([
+                'name', 'driver', 'capture_mode', 'captured_status',
+                'authorized_status', 'position', 'driver_missing_at',
+            ]);
+        });
+    }
+};
@@ -0,0 +1,38 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * captured_status/authorized_status (added in 2026_09_05_000001) cover a
+ * payment being taken, but nothing wrote Order.status on a REFUND —
+ * Order::paymentStatus() (Order\Support\OrderStatus::payment(), derived
+ * live from transactions) already reflects a refund correctly, but the
+ * stored status column — the one admin filtering, customer emails, etc.
+ * actually key off — never moved. Same reasoning as captured_status/
+ * authorized_status: a store could plausibly want a different resulting
+ * status per payment method (e.g. a "Refunded" vs. a "Refund Pending"
+ * variant), so this is a PaymentMethod column, not cross-cutting config.
+ *
+ * Deliberately no separate void_status — void never moved money (it
+ * releases an authorization hold before any capture), so it doesn't carry
+ * the same "the customer needs to see this changed" weight a refund does;
+ * add one later if a real need for it shows up.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('payment_methods', function (Blueprint $table) {
+            $table->string('refunded_status')->nullable()->after('authorized_status');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('payment_methods', function (Blueprint $table) {
+            $table->dropColumn('refunded_status');
+        });
+    }
+};
@@ -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.
@@ -0,0 +1,189 @@
+# Payment — Design Notes
+
+**Status: abstraction layer built, drivers/wiring in progress.** `Payment` is designed as a
+standalone module: it never calls into `Checkout` or `Order`, never touches their Eloquent
+models, and communicates only via events. This document is the design spec for that
+abstraction — contracts, DTOs, events — independent of how `Checkout`/`Order` end up consuming
+it (that wiring is a separate, later pass).
+
+---
+
+## Operations, not gateways
+
+The driver contracts model the actual operations a payment gateway can perform, not vendor
+terminology. Every real gateway checked while designing this converges on the same small set
+under different names:
+
+| Operation | Mastercard | Stripe | Nexi |
+|---|---|---|---|
+| Atomic charge (authorize+capture in one call) | `Pay` | `capture_method: automatic` | `ActionType::PAY()` |
+| Hold only, settle/release later | `Authorize` | `capture_method: manual` | `ActionType::PREAUTH()` |
+| Settle a prior hold | `Capture` | `PaymentIntent::capture()` | `CaptureRequest`/`CaptureResponse` |
+| Release a prior hold without settling | `Void`/`Cancel` | `PaymentIntent::cancel()` | `CancelRequest`/`CancelResponse` |
+| Reverse settled funds | `Refund` | `Refund::create()` | (refund endpoint) |
+
+A driver implements only the interfaces its gateway actually supports:
+
+- An offline/cash type (`cash-on-delivery`, `cash-in-hand`) only ever settles atomically —
+  implements `SupportsPay` alone.
+- A card gateway capable of either mode per-transaction (Stripe, most card processors)
+  implements `SupportsPay`, `SupportsAuthorization`, `SupportsCaptures`, `SupportsVoids`, and
+  `SupportsRefunds` all at once — which one gets *called* for a given attempt is the caller's
+  policy choice (e.g. `config('lunar.stripe.policy')`), not something baked into the driver's
+  shape.
+- A redirect/wallet gateway with no separate hold step (Viva/Klarna in typical flows)
+  implements `SupportsPay` and `SupportsRefunds`, never `SupportsCaptures`/`SupportsVoids`.
+
+### `pay()` and `authorize()` stay separate methods even when a gateway implements both as "the same call with a flag"
+
+Stripe has no separate `authorize`/`pay` API endpoints — one `PaymentIntent`, confirmed with
+either `capture_method: automatic` or `manual`. Mastercard and Nexi *do* have genuinely
+separate operations. The contract abstracts over both shapes uniformly: every driver capable
+of both exposes two distinct methods, `pay()` and `authorize()`. A Mastercard-style driver
+calls two different endpoints under the hood; a Stripe-style driver calls the same endpoint
+twice with a different flag each time. Neither difference is visible to a caller.
+
+### `capture()`/`void()` are only ever valid against a prior `authorize()`
+
+They are not standalone operations — `capture()` settles a specific hold identified by the
+`reference` `authorize()` returned; `void()` releases that same hold instead. A driver that
+never implements `SupportsAuthorization` never produces a reference either of these methods
+could act on.
+
+---
+
+## `PaymentResult` — the one return shape, every operation, every driver
+
+```php
+enum PaymentResultStatus { case Succeeded; case Failed; case Pending; }
+
+final class PaymentResult {
+    public function __construct(
+        public readonly PaymentResultStatus $status,
+        public readonly string $reference,
+        public readonly int $amount,
+        public readonly ?string $failureReason = null,
+        public readonly bool $retriable = false,
+        public readonly array $raw = [],
+        public readonly array $meta = [],
+    ) {}
+}
+```
+
+Real gateway responses vary wildly in richness — confirmed by reading three SDKs directly:
+
+- **Stripe's `PaymentIntent`** is rich: `status`, `amount`, `amount_capturable`,
+  `amount_received`, `last_payment_error`, a full `getLastResponse()`.
+- **Nexi's `CaptureResponse`/`CancelResponse`** are minimal: just `operationId` +
+  `operationTime` — no echoed amount or status at all. Success is inferred from getting a
+  response rather than an SDK exception.
+- **Mastercard's** gateway sits in between, with `gatewayCode`/`acquirerCode`/
+  `merchantAdviceCode`.
+
+`PaymentResult` only requires what every driver can always know: `status`, `reference`,
+`amount` (the amount **we** requested — not necessarily echoed back by a sparse gateway like
+Nexi's capture). Everything else is best-effort: `failureReason`/`retriable` are normalized
+only when the gateway has something to normalize from; `raw` is the unconditional escape
+hatch — the untouched gateway response body, always populated, for genuine audit fidelity
+regardless of how sparse the normalized fields ended up.
+
+### `retriable` — real on some gateways, absent on others
+
+Stripe classifies declines as soft (`do_not_honor`, `insufficient_funds` — worth retrying,
+after a delay) vs. hard (`stolen_card`, `expired_card` — never retry the same method).
+Mastercard has the equivalent via `authorizationResponse.merchantAdviceCode` and card-scheme
+soft-decline codes. **Nexi has no such signal at all** — `OperationResult` is just
+`DECLINED`/`DENIED_BY_RISK`/`FAILED`/etc. with no retriability classification. `retriable`
+therefore defaults to `false` (assume not safely retriable) rather than guessing when a
+driver's gateway has nothing to base it on.
+
+---
+
+## Events — one terminal pair per operation, keyed to the business fact, not the call path
+
+`Modules\Core\Payment\Events`:
+
+| Event pair | Dispatched by |
+|---|---|
+| `PaymentAuthorized` / `PaymentAuthorizationFailed` | `SupportsAuthorization::authorize()`, or a later `HandlesPaymentCallback::handleCallback()` resolving it |
+| `PaymentCaptured` / `PaymentCaptureFailed` | `SupportsPay::pay()` **or** `SupportsCaptures::capture()` |
+| `PaymentVoided` / `PaymentVoidFailed` | `SupportsVoids::void()` |
+| `PaymentRefunded` / `PaymentRefundFailed` | `SupportsRefunds::refund()` |
+
+`PaymentCaptured` is deliberately the *same* event whether money was taken via `pay()` (one
+gateway call) or `authorize()` → `capture()` (two calls) — "a payment has been captured" is
+the same business fact either way, and a listener reacting to it never needs to know which
+path produced it. There is no separate "payment succeeded" wrapper event distinct from
+`PaymentCaptured`.
+
+Every event carries `{type: string, result: PaymentResult, context: array}`. `Payment` has no
+concept of a `Cart`, an `Order`, or a checkout fingerprint — `$context` is an opaque bag the
+caller hands in on the way down (`pay($type, $data, $context)`) and gets back untouched on
+whichever event that call (or a later `handleCallback()`) produces. Each listener interprets
+`$context` on its own terms, or ignores the event if the keys it needs aren't present —
+`Checkout` is only one possible consumer of these events, not the only one.
+
+---
+
+## Async resolution — `HandlesPaymentCallback`
+
+Only implemented by a driver whose `pay()`/`authorize()` can return `PaymentResultStatus::Pending`
+— a redirect the shopper completes elsewhere, a webhook that arrives later. A driver whose
+gateway always resolves synchronously never implements this.
+
+```php
+public function handleCallback(string $reference, array $data, array $context = []): PaymentResult;
+```
+
+Resolves into the *same* event pair the original `pay()`/`authorize()` call would have
+produced had it resolved synchronously.
+
+### The correlation problem: `handleCallback()` runs in a different request
+
+`$context` passed into the original `pay()`/`authorize()` call does not survive to
+`handleCallback()` on its own — that call is typically a separate HTTP request (a webhook)
+with no memory of the request that started the payment. Something has to persist enough to
+answer "which order/cart does gateway reference X belong to?" between the two calls.
+
+**Read directly from `lunarphp/stripe`'s own source** (`StripePaymentType::authorize()`,
+`ProcessStripeWebhook`, `WebhookController`) to see how Lunar itself solves this — confirmed
+it does **not** stash a generic opaque blob. It writes the correlating ids as real, typed
+columns on `Lunar\Stripe\Models\StripePaymentIntent` (`cart_id`, `order_id`) at the moment the
+intent is created/first seen, then reads them back the same way when the webhook arrives:
+
+```php
+// ProcessStripeWebhook::handle() — falls back through two real lookups,
+// neither of them a generic context blob:
+$cart = StripePaymentIntent::where('intent_id', $this->paymentIntentId)->first()?->cart
+    ?: Cart::where('meta->payment_intent', '=', $this->paymentIntentId)->first();
+```
+
+**`StripePaymentDriver` follows this exact precedent**: it reads `cart_id`/`order_id` out of
+`$context` at `pay()`/`authorize()` time and writes them onto its own `StripePaymentIntent`
+row (a table already owned by `lunarphp/stripe`, already shaped for exactly this), then reads
+them back the same way in `handleCallback()`. No generic `context` json column, no new table.
+
+### This pattern is per-driver, not a shared table
+
+`stripe_payment_intents` is Stripe-specific — keyed on `intent_id`, typed around
+`Stripe\PaymentIntent`'s own status values. It cannot be reused as-is for a future non-Stripe
+async driver (Nexi, Viva): that driver's own gateway reference has a different shape entirely,
+and shoehorning it into Stripe-named columns would make the table misleading. The **pattern**
+generalizes — *any* driver needing async callback resolution owns a small table keyed by its
+own gateway's reference, storing whatever correlation data that driver specifically needs —
+but each driver gets its own table, matching what it actually needs to correlate, rather than
+a shared generic one.
+
+---
+
+## Explicitly out of scope for this pass
+
+- **`Checkout`/`Order` wiring** — how `Checkout` calls into `Payment`, how `Order`/`Checkout`
+  react to `Payment`'s events, where a draft `Order` gets created relative to when `Payment` is
+  called. Deliberately designed and built separately, after `Payment` itself was complete —
+  `Payment` must stand on its own regardless of what ends up consuming it.
+- **`Transaction` persistence** — Lunar's own `transactions` table (`type`: `intent`/`capture`/
+  `refund`, `parent_transaction_id` chaining) already models the audit trail these events
+  would feed, once a listener is built to write to it. `Payment` itself does not write
+  `Transaction` rows — see the events table above; that is a listener's job, in whichever
+  module ends up owning the write (likely `Order`, since `Transaction.order_id` is required).
@@ -1,8 +1,9 @@
 # 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.
+lookup for a storefront — `list()`, `getById()`, `getBySlug()`, `random()`, `variantSummaries()` —
+all reading directly from the Meilisearch index rather than the database. One data source for
+everything this service does.

 This is separate from `Modules\Core\Catalog\Services\ProductSearchService` (see `product-search.md`), which
 handles free-text query search. `ProductService` is for browsing/lookup without a search term.
@@ -28,13 +29,14 @@ use Modules\Core\Catalog\Enums\ProductSort;

 $service = app(ProductService::class);

-// List everything, paginated — returns a real Illuminate\Pagination\LengthAwarePaginator,
-// built from the localized Meilisearch hits (not Scout's own paginateRaw() result — see
-// "Meilisearch driver quirk" below), so it behaves like any other Laravel paginator.
-$products = $service->list(perPage: 24, page: 1);
+// One call for everything a listing page needs — products AND the price slider's
+// bounds together, as a Modules\Core\Catalog\DTOs\ProductListingResult. A caller
+// used to have to call list() and priceSliderBounds() (or the older priceRange())
+// separately and glue the results together itself; that's now list()'s own job.
+$listing = $service->list(perPage: 24, page: 1);

 // Filter by collection, brand, price range, and/or stock
-$products = $service->list(
+$listing = $service->list(
    filters: new ProductFilters(collectionId: 17, minPrice: 10.0, maxPrice: 50.0, inStockOnly: true),
    perPage: 24,
    page: 1,
@@ -42,8 +44,13 @@ $products = $service->list(

 // Sort — cheapest/priciest first, or newest first. Omit for Meilisearch's default
 // relevance ordering (irrelevant here since the query is always empty).
-$products = $service->list(perPage: 24, page: 1, sort: ProductSort::PriceAsc);
+$listing = $service->list(perPage: 24, page: 1, sort: ProductSort::PriceAsc);

+$products = $listing->products;  // a real Illuminate\Pagination\LengthAwarePaginator,
+                                  // built from the localized Meilisearch hits (not Scout's
+                                  // own paginateRaw() result — see "Meilisearch driver
+                                  // quirk" below), so it behaves like any other Laravel
+                                  // paginator.
 $products->items();            // array of Meilisearch documents (plain arrays, not models)
 $products->total();
 $products->perPage();
@@ -51,12 +58,32 @@ $products->currentPage();
 $products->lastPage();
 $products->links();            // in a Blade view — renders pagination links as usual

+$bounds = $listing->priceBounds;  // Modules\Core\Catalog\DTOs\PriceSliderBounds
+$bounds->floor;    // ?int — floor() of the matching range's minimum, in whole currency units
+$bounds->ceil;     // ?int — ceil() of the matching range's maximum
+$bounds->filtered; // bool — whether the applied filters' minPrice/maxPrice actually
+                   // narrow the slider below/above these bounds (drives whether a
+                   // "clear filter" control should show)
+
 // Single product, by primary key
 $product = $service->getById(367);   // array, or null if not found

 // Single product, by URL slug (any locale — slugs are indexed across all languages)
 $product = $service->getBySlug('erotika-mprelok');   // array, or null if not found

+// $limit random products — still scoped to the index's own default channel/status
+// visibility, unlike Eloquent's Product::inRandomOrder() (which has no notion of
+// that filtering at all). Meilisearch has no ORDER BY RANDOM() equivalent, so this
+// pulls every matching id only, shuffles in PHP, then fetches the full localized
+// documents for just the ids picked — see random()'s own docblock.
+$randomProducts = $service->random(13);   // array of documents, same shape as list()'s items
+
+// The id/price/image of every variant on a product document — the base price and
+// thumbnail a variant picker/swatch list needs, without reaching into
+// $product['variants'][n]['prices'][0]/['media'][0] yourself.
+$variants = $service->variantSummaries($product);
+// [['id' => 1204, 'price' => 19.99, 'image' => 'https://.../thumb.jpg'], ...]
+
 // Facet counts for a sidebar — value => matching product count, scoped to whatever
 // $filters is passed. Does NOT exclude the faceted field itself from $filters — see
 // facets()'s docblock for why, and how to build a standard "every option's count,
@@ -64,11 +91,13 @@ $product = $service->getBySlug('erotika-mprelok');   // array, or null if not fo
 $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.
+// Min/max price across matching products — the raw, unrounded values list() itself
+// uses to build priceBounds above. minPrice/maxPrice are ALWAYS excluded from the
+// filter driving this (unlike facets(), which doesn't auto-exclude) — the slider's
+// own bounds shouldn't shrink to whatever range is currently selected on it. Other
+// filters (collectionId, brand, inStockOnly) still apply normally. Pass $query too
+// to scope the range to a text search's own matches (see product-search.md) rather
+// than the whole catalog.
 $range = $service->priceRange(new ProductFilters(collectionId: 17));
 // ['min' => 0.0, 'max' => 120.0]
 ```
@@ -77,8 +106,8 @@ All `ProductFilters` fields are optional; only the ones set are added to the Mei

 `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`.
+`priceRange()` (or `list()`'s own `priceBounds`) for `price` instead, which reads Meilisearch's
+`facetStats` (min/max), a different feature from `facetDistribution`.

 ---

@@ -106,11 +135,12 @@ needs, listing and detail alike:
 | `collections` | `$product->collections` | Array of `{id, name}` — directly assigned collections only, `name` is the translated collection name. Not filterable — see `collection_ids`. |
 | `collection_ids` | `$product->collections` + `->ancestors` | Filterable. Flat array of every directly-assigned collection's id, unioned with all of its ancestors' ids. `ProductFilters(collectionId: ...)` filters against this field, not `collections`, since products are typically attached only to leaf collections — a plain direct-match filter would never return anything for a parent/root category page. |
 | `slugs` | `$product->urls->pluck('slug')` | Filterable. Every locale's `Url::slug` for the product, so `getBySlug()` resolves purely from the index — no database read. |
+| `skus` | `$product->variants->pluck('sku')` | Filterable. Every variant's `sku`, deduplicated, empty ones dropped. Same "resolve from the index alone" reasoning as `slugs`, for a future SKU-based lookup/filter. |
 | `price` | Cheapest variant's base price | Filterable. Float in major units (e.g. `19.99`, not `1999`). Base price only — no customer group, default currency (`Currency::getDefault()`) only. `null` if the product has no priced variant yet, so it's excluded from range filters rather than treated as free. |
 | `brand` | Already indexed by Lunar's base indexer | Newly marked **filterable** — it existed in the document already, just wasn't usable in a `filter` clause. |
 | `tags` | `$product->tags->pluck('value')` | Display only. |
 | `media` | `$product->media` | Full gallery (id/url/thumb per image), not just the single thumbnail Lunar's base indexer sends. |
-| `variants` | `$product->variants` | Per variant: `id`, `sku`, `stock`, `purchasable`, `options` (option/value names, in the current locale), `prices` (per currency/customer group), `media` (variant-specific images). |
+| `variants` | `$product->variants` | Per variant: `id`, `sku`, `gtin`, `mpn`, `ean`, `stock`, `backorder`, `unit_quantity`, `purchasable`, `shippable`, `tax_ref`, `dimensions` (`length`/`width`/`height`/`weight`/`volume`, each `{value, unit}`), `options` (option/value names, in the current locale), `prices` (per currency/customer group), `media` (the variant's own images — `ProductVariant::images()`, a separate pivot from the product's own gallery above, populated by `ShopifyExportImporter` from Shopify's `Variant Image` CSV column). |
 | `reviews` | `Modules\Core\Review\Models\ProductReview` | `{items, count, average_rating}` — see "Reviews" below. |
 | `in_stock` | `$model->variants` | Filterable boolean. `true` if ANY variant currently passes `ProductVariant::canBeFulfilledAtQuantity(1)` — Lunar's own purchasability rule (`purchasable === 'always'` ignores stock entirely; `in_stock` checks `stock` alone; anything else checks `stock + backorder`). Only as fresh as the last reindex — see "Stock goes stale" below. |

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

 ```php
+use Modules\Core\Catalog\DTOs\ProductFilters;
+use Modules\Core\Catalog\Enums\ProductSort;
 use Modules\Core\Catalog\Services\ProductSearchService;

 $results = app(ProductSearchService::class)->search('running shoes');
-// or an explicit locale, bypassing App::getLocale():
-$results = app(ProductSearchService::class)->search('running shoes', 'el');
+
+// Filters/sort apply the exact same semantics ProductService::list() uses for
+// collection browsing (same ProductFilterBuilder, same ProductSort) — a shopper
+// narrowing a text search by price/brand/stock gets identical filter behavior
+// to narrowing a category listing.
+$results = app(ProductSearchService::class)->search(
+    'running shoes',
+    filters: new ProductFilters(brand: 'Acme', minPrice: 20.0, inStockOnly: true),
+    sort: ProductSort::PriceAsc,
+);
 ```

 Returns an `Illuminate\Database\Eloquent\Collection` of `Lunar\Models\Product` — Scout's
 `->get()` hydrates real models from the database after the Meilisearch query, so relations
 (`variants`, `brand`, `media`, etc.) are available on the results as normal.

-`$locale` defaults to `App::getLocale()` — already set correctly on every storefront request by
-`Modules\Core\Localization\Middleware\LocaleMiddleware` (see `localization.md`), so callers in controllers
-don't need to pass it explicitly.
+There is no `$locale` parameter — see "Field list is dynamic, not hardcoded" below for why
+every configured store language is always searched, regardless of the current request locale.

 ---

-## Missing-translation fallback
+## Missing-translation fallback, in both directions

 If a product was only ever given an English name, `name_el` doesn't exist on that document at
 all (Lunar's indexer only writes a `{handle}_{locale}` field for locales actually present in the
 attribute's stored data — see `ScoutIndexer::mapSearchableAttributes()`). Searching strictly
-against `name_el` would make that product invisible to Greek-locale search, even though it's a
-real catalog item.
+against the current request's locale field would make that product invisible whenever a shopper's
+locale doesn't match the language it happens to be translated into.

-To avoid silently hiding incompletely-translated products, `ProductSearchService` targets **both**
-the resolved locale's fields **and** the default language's fields
-(`Lunar\Models\Language::getDefault()->code`) — e.g. searching in `el` targets `name_el`,
-`name_en`, `description_el`, `description_en` together (assuming `en` is the default language).
-A product missing an `el` translation still matches via its `en` fields.
+`ProductSearchService` avoids this by targeting **every configured store language's fields**
+(`Lunar\Models\Language::all()`) on every search, not just the current request locale plus the
+store default — e.g. with `el`/`en` configured, every search targets `name_el`, `name_en`,
+`description_el`, `description_en` together, regardless of which locale the shopper is browsing
+in. This is deliberately not scoped to "current locale + default locale": if the current locale
+already equals the default (a single-language store, or a shopper browsing in the default
+language), that pairing collapses to one locale and stops catching anything else — always
+searching every configured language avoids that gap in both directions, at the cost of a larger
+`attributesToSearchOn` list as the store's language count grows.
+
+---
+
+## Variant option values are searched too
+
+Alongside the locale-suffixed attribute fields, every search also targets
+`variants.options.value` directly — e.g. a variant named "Κάπτεν Γαμέρικα" on a "Name" option
+matches a search for that text, even though it never appears in the product's own name or
+description. This isn't one of Lunar's own attributes (`AttributeManifest` has no entry for it),
+so it can't be discovered the way `name`/`description` are — it's a structural field of
+`Modules\Core\Catalog\Services\ProductIndexer`'s own document shape (see `ProductIndexer::mapVariant()`),
+added here directly. Not locale-suffixed — each option value is stored as one already-resolved
+string per variant.

 ---

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

 Findings from comparing a real Shopify product export CSV against Lunar's schema (`vendor/lunarphp/core`), plus the resulting implementation plan for `MigrateImport\Shopify\ShopifyExportImporter`.

+Need to discard everything and re-import from scratch (e.g. after a schema/indexer change that
+only applies to newly-created rows)? See `docs/shopify-reimport.md`.
+
 ## Idempotency problem

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

    @if (! $otpSent)
        <form wire:submit="requestOtp">
-            <div class="grid gap-y-4">
+            <div style="display: flex; flex-direction: column; row-gap: 1rem;">
                <x-filament::input.wrapper>
                    <x-filament::input
                        type="email"
@@ -24,7 +24,7 @@
        </form>
    @else
        <form wire:submit="authenticate">
-            <div class="grid gap-y-4">
+            <div style="display: flex; flex-direction: column; row-gap: 1rem;">
                <p class="text-sm text-gray-500">
                    A login code was sent to <strong>{{ $email }}</strong>.
                </p>
@@ -0,0 +1,127 @@
+@php
+    $transaction = $getRecord();
+    $notes = $transaction->notes ?: ($transaction->meta['notes'] ?? null);
+@endphp
+
+@once
+    @php
+        $renderPaymentIcons();
+    @endphp
+@endonce
+<div
+    @class([
+        'text-sm rounded-lg shadow-md border dark:bg-gray-900',
+        'text-gray-950 dark:text-white',
+        match($transaction->type){
+            'refund' => 'border-orange-300',
+            'intent' => 'border-sky-300',
+            'capture' => 'border-green-300',
+            default => 'border-gray-300',
+        },
+        '!border-red-500 bg-red-50' => !$transaction->success,
+        'bg-gray-50' => $transaction->success,
+    ])
+>
+    <div class="p-2 space-y-2">
+        <div class="px-4 py-2 rounded text-xs bg-white dark:bg-gray-800 shadow text-gray-600 dark:text-gray-400 ring-1 ring-gray-100 dark:ring-gray-700">
+            <span>{{ $transaction->driver }}</span> //
+            <span>{{ $transaction->reference }}</span>
+        </div>
+
+        <div class="flex items-center justify-between p-4 bg-white dark:bg-gray-800 rounded shadow ring-1 ring-gray-100 dark:ring-gray-700">
+            <div class="flex items-center gap-6">
+                <div>
+                    <strong class="text-xs">
+                        {{ $transaction->status }}
+                    </strong>
+                </div>
+
+                <div>
+                    <svg viewBox="0 0 50 50" class="w-10">
+                        <use xlink:href="#{{ strtolower($transaction->card_type) }}"></use>
+                    </svg>
+                </div>
+
+                @if($transaction->last_four)
+                    <p class="text-sm">
+                        <span class="inline-block -translate-y-px">
+                            &lowast;&lowast;&lowast;&lowast; &lowast;&lowast;&lowast;&lowast; &lowast;&lowast;&lowast;&lowast;
+                        </span>
+
+                        <span class="font-medium">
+                            {{ (string) $transaction->last_four }}
+                        </span>
+                    </p>
+                @endif
+            </div>
+
+            <strong
+                @class([
+                    "text-sm",
+                    'text-red-500' => !$transaction->success,
+                    match($transaction->type){
+                        'refund' => "text-orange-500",
+                        default => "text-gray-900 dark:text-gray-100",
+                    },
+                ])
+            >
+                @if($transaction->type == 'refund')-@endif{{ $transaction->amount->formatted }}
+            </strong>
+        </div>
+
+        <div class="px-4 py-2 bg-white dark:bg-gray-800 shadow rounded flex items-center justify-between text-gray-600 dark:text-gray-400 ring-1 ring-gray-100 dark:ring-gray-700">
+            <div class="text-xs flex items-center gap-2">
+                <div>
+                    <x-filament::icon
+                        icon="heroicon-o-clock"
+                        class="w-4"
+                    />
+                </div>
+                <span>{{ $transaction->created_at->format('jS F Y h:ia') }}</span>
+            </div>
+
+            <div class="flex space-x-2">
+            @foreach($transaction->paymentChecks() as $check)
+                    <x-filament::badge
+                        :icon="$check->successful ? 'heroicon-m-check' : 'heroicon-m-x-mark'"
+                        :color="$check->successful ?  \Filament\Support\Colors\Color::Sky : 'gray'"
+                    >
+                        {{ $check->label }}: {{ $check->message }}
+                    </x-filament::badge>
+            @endforeach
+            </div>
+        </div>
+
+        @if($notes)
+            <div class="px-4 py-2 bg-white dark:bg-gray-800 shadow flex items-center rounded gap-2 ring-1 ring-gray-100 dark:ring-gray-700">
+                <div>
+                    <x-filament::icon
+                        icon="heroicon-o-chat-bubble-oval-left-ellipsis"
+                        class="w-4"
+                    />
+                </div>
+
+                <p class="text-sm">{{ $notes }}</p>
+            </div>
+        @endif
+    </div>
+
+    <div
+        @class([
+            "bottom-0 left-0 block w-full text-center rounded-b-lg border-t text-xs py-1",
+            "!bg-red-50 !dark:bg-red-400/10 !border-red-300 !text-red-600 !dark:text-red-400" => !$transaction->success,
+            match($transaction->type){
+                'refund' => "bg-orange-50 dark:bg-orange-400/10 border-orange-300 text-orange-600 dark:text-orange-400",
+                'intent' => "bg-sky-50 dark:bg-sky-400/10 border-sky-300 text-sky-600 dark:text-sky-400",
+                'capture' => "bg-green-50 dark:bg-green-400/10 border-green-300 text-green-600 dark:text-green-400",
+                default => "bg-gray-50 dark:bg-gray-400/10 border-gray-300 text-gray-600 dark:text-gray-400",
+            },
+        ])
+    >
+        @if(!$transaction->success)
+            {{ __('lunarpanel::order.transactions.failed') }}
+        @else
+            {{ __('lunarpanel::order.transactions.'.$transaction->type) }}
+        @endif
+    </div>
+</div>
@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>Payment of <strong>{{ $amount }}</strong> for your order <strong>{{ $reference }}</strong> has been captured.</p>
@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>Good news — your order <strong>{{ $reference }}</strong> has been delivered.</p>
@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>A refund of <strong>{{ $amount }}</strong> has been issued for your order <strong>{{ $reference }}</strong>.</p>
@@ -0,0 +1,3 @@
+<p>Hi,</p>
+
+<p>Your order <strong>{{ $reference }}</strong> is now: <strong>{{ $statusLabel }}</strong></p>
@@ -0,0 +1,3 @@
+<x-filament-panels::page>
+    {{ $this->table }}
+</x-filament-panels::page>
@@ -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);
    }
 }
@@ -15,7 +15,7 @@ class Login extends SimplePage
 {
    use WithRateLimiting;

-    protected static string $view = 'core::auth.filament.pages.login';
+    protected string $view = 'core::auth.filament.pages.login';

    public ?string $email = '';
    public ?string $otp = '';
@@ -78,7 +78,7 @@ class Login extends SimplePage
            ]);
        }

-        if ($staff instanceof FilamentUser && !$staff->canAccessPanel(Filament::getCurrentPanel())) {
+        if ($staff instanceof FilamentUser && !$staff->canAccessPanel(Filament::getCurrentOrDefaultPanel())) {
            throw ValidationException::withMessages([
                'email' => 'You do not have access to this panel.',
            ]);
@@ -31,6 +31,13 @@ use Modules\Core\Recovery\Events\CheckoutAbandoned;
 * state at all; every cart still matching the query below refires its event
 * on every run until Recovery (not yet built — see
 * docs/recovery-strategies.md) owns its own dedup/tracking table.
+ *
+ * Both queries require meta->recovery_consent = true — CartAbandoned/
+ * CheckoutAbandoned exist specifically to drive future recovery-email
+ * sends (Checkout\Services\CheckoutService::setRecoveryConsent() is where
+ * that consent is actually recorded), and a non-consenting cart's
+ * abandonment must never be dispatched at all, not merely filtered later
+ * at send time — see docs referenced above for the legal reasoning.
 */
 class DetectAbandonedCarts extends Command
 {
@@ -48,6 +55,7 @@ class DetectAbandonedCarts extends Command
        Cart::query()
            ->whereDoesntHave('orders')
            ->where('updated_at', '<=', $cutoff)
+            ->where('meta->recovery_consent', true)
            ->with('lines')
            ->chunkById(200, function ($carts) use (&$cartsAbandoned) {
                foreach ($carts as $cart) {
@@ -64,6 +72,7 @@ class DetectAbandonedCarts extends Command
        Cart::query()
            ->whereHas('orders', fn ($query) => $query->whereNull('placed_at'))
            ->where('updated_at', '<=', $cutoff)
+            ->where('meta->recovery_consent', true)
            ->with(['orders' => fn ($query) => $query->whereNull('placed_at')])
            ->chunkById(200, function ($carts) use (&$checkoutsAbandoned) {
                foreach ($carts as $cart) {
@@ -12,8 +12,8 @@ use RuntimeException;
 */
 class InvalidCouponException extends RuntimeException
 {
-    public function __construct(public readonly string $code)
+    public function __construct(public readonly string $couponCode)
    {
-        parent::__construct("The coupon code \"{$code}\" is not valid.");
+        parent::__construct("The coupon code \"{$couponCode}\" is not valid.");
    }
 }
@@ -2,6 +2,10 @@

 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;
@@ -24,9 +28,9 @@ class CartResource extends Resource
 {
    protected static ?string $model = Cart::class;

-    protected static ?string $navigationIcon = 'heroicon-o-shopping-cart';
+    protected static string | \BackedEnum | null $navigationIcon = 'heroicon-o-shopping-cart';

-    protected static ?string $navigationGroup = 'Sales';
+    protected static string | \UnitEnum | null $navigationGroup = 'Sales';

    protected static ?string $modelLabel = 'Cart';

@@ -70,37 +74,37 @@ class CartResource extends Resource
    {
        return $table
            ->columns([
-                Tables\Columns\TextColumn::make('id')
+                TextColumn::make('id')
                    ->label('Cart')
                    ->sortable(),
-                Tables\Columns\TextColumn::make('customer.full_name')
+                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),
-                Tables\Columns\TextColumn::make('user.email')
+                TextColumn::make('user.email')
                    ->label('User')
                    ->placeholder('—')
                    ->searchable(),
-                Tables\Columns\TextColumn::make('lines_count')
+                TextColumn::make('lines_count')
                    ->label('Lines')
                    ->counts('lines')
                    ->sortable(),
-                Tables\Columns\TextColumn::make('lines_sum_quantity')
+                TextColumn::make('lines_sum_quantity')
                    ->label('Items')
                    ->sum('lines', 'quantity')
                    ->sortable(),
-                Tables\Columns\TextColumn::make('currency.code')
+                TextColumn::make('currency.code')
                    ->label('Currency'),
-                Tables\Columns\TextColumn::make('updated_at')
+                TextColumn::make('updated_at')
                    ->label('Last activity')
                    ->dateTime()
                    ->sortable(),
            ])
-            ->actions([
-                Tables\Actions\ViewAction::make(),
+            ->recordActions([
+                ViewAction::make(),
            ])
            ->defaultSort('updated_at', 'desc');
    }
@@ -108,8 +112,8 @@ class CartResource extends Resource
    public static function getPages(): array
    {
        return [
-            'index' => Pages\ListCarts::route('/'),
-            'view' => Pages\ViewCart::route('/{record}'),
+            'index' => ListCarts::route('/'),
+            'view' => ViewCart::route('/{record}'),
        ];
    }

@@ -2,7 +2,7 @@

 namespace Modules\Core\Cart\Filament\Resources\CartResource\Pages;

-use Filament\Resources\Components\Tab;
+use Filament\Schemas\Components\Tabs\Tab;
 use Filament\Resources\Pages\ListRecords;
 use Illuminate\Database\Eloquent\Builder;
 use Modules\Core\Cart\Filament\Resources\CartResource;
@@ -35,20 +35,21 @@ class ListCarts extends ListRecords
    public function getTabs(): array
    {
        return [
-            'ongoing' => Tab::make('Ongoing')
-                ->modifyQueryUsing(fn (Builder $query) => $query->active()->where('updated_at', '>', CartResource::abandonedCutoff())),
            'abandoned_cart' => Tab::make('Abandoned Cart')
-                ->modifyQueryUsing(fn (Builder $query) => $query
+                ->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'))
+                ->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(
+                ->modifyQueryUsing(fn(Builder $query) => $query->whereHas(
                    'orders',
-                    fn (Builder $query) => $query->whereNotNull('placed_at'),
+                    fn(Builder $query) => $query->whereNotNull('placed_at'),
                )),
        ];
    }
@@ -2,11 +2,11 @@

 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\Section;
 use Filament\Infolists\Components\TextEntry;
-use Filament\Infolists\Infolist;
 use Filament\Resources\Pages\ViewRecord;
 use Lunar\Admin\Filament\Resources\CustomerResource;
 use Lunar\Models\Cart;
@@ -44,10 +44,10 @@ class ViewCart extends ViewRecord
        return $cart->calculate();
    }

-    public function infolist(Infolist $infolist): Infolist
+    public function infolist(Schema $schema): Schema
    {
-        return $infolist
-            ->schema([
+        return $schema
+            ->components([
                Section::make('Cart')
                    ->columns(3)
                    ->schema([
@@ -2,7 +2,7 @@

 namespace Modules\Core\Catalog\Contracts;

-use Filament\Forms\Components\Component;
+use Filament\Schemas\Components\Component;

 /**
 * A Product Option Type describes how a category of Lunar `ProductOption` (e.g.
@@ -0,0 +1,39 @@
+<?php
+
+namespace Modules\Core\Catalog\Contracts;
+
+use Illuminate\Support\Collection;
+use Lunar\Models\Product;
+
+/**
+ * One strategy for producing recommended products for a given product —
+ * e.g. same category, same tag, best sellers, random. Modules\Core\Catalog\
+ * Services\RecommendationService runs rules registered in
+ * config('catalog.recommendation_rules') in order, topping up from each
+ * successive rule until $limit distinct products are collected or every
+ * rule is exhausted (e.g. 3 from SameCategoryRule + 1 from RandomRule) —
+ * nothing here decides that accumulation itself; a store composes its own
+ * chain by ordering rules in config (e.g. [SameCategoryRule::class,
+ * RandomRule::class]).
+ *
+ * Returns raw Product models, not ProductService::list()'s locale-resolved
+ * array output — this runs at index time (ProductIndexer::toSearchableArray()),
+ * where "the current locale" isn't a meaningful concept the way it is for a
+ * storefront request. ProductIndexer resolves translated fields itself via
+ * translateAttribute(), same as it already does for the embedded `collections`
+ * field — same known index-time-locale tradeoff, not a new one.
+ */
+interface RecommendationRule
+{
+    /**
+     * $exclude carries $product's own id plus every id already picked by an
+     * earlier rule this call — RecommendationService never shows the same
+     * product twice even when two rules would both suggest it, and a rule
+     * shouldn't spend its $limit budget re-returning something already
+     * collected.
+     *
+     * @param  array<int>  $exclude
+     * @return Collection<int, Product> at most $limit products
+     */
+    public function recommend(Product $product, int $limit, array $exclude): Collection;
+}
@@ -0,0 +1,19 @@
+<?php
+
+namespace Modules\Core\Catalog\DTOs;
+
+/**
+ * A price range slider's bounds and whether it's currently narrowed —
+ * built by ProductService::priceSliderBounds(), which owns the floor/ceil
+ * rounding and "is this actually a meaningful filter" comparison, so a
+ * controller (CategoryController, SearchController, ...) doesn't have to
+ * reimplement that rule itself.
+ */
+class PriceSliderBounds
+{
+    public function __construct(
+        public readonly ?int $floor,
+        public readonly ?int $ceil,
+        public readonly bool $filtered,
+    ) {}
+}
@@ -17,10 +17,12 @@ class ProductFilters
     *   not a direct-assignment-only match) — the right semantics for "products on
     *   this category page", since products are typically attached only to leaf
     *   collections.
+     * @param $tag exactly one tag — no multi-select yet.
     */
    public function __construct(
        public readonly ?int $collectionId = null,
        public readonly ?string $brand = null,
+        public readonly ?string $tag = null,
        public readonly ?float $minPrice = null,
        public readonly ?float $maxPrice = null,
        public readonly bool $inStockOnly = false,
@@ -0,0 +1,33 @@
+<?php
+
+namespace Modules\Core\Catalog\DTOs;
+
+use Illuminate\Pagination\LengthAwarePaginator;
+
+/**
+ * Everything a listing page needs from one ProductService::list() call —
+ * the product page itself, the price slider's bounds, and the set of tags
+ * actually present on matching products (for a tag filter sidebar) — so a
+ * controller makes one service call instead of orchestrating list(),
+ * priceSliderBounds(), and facets('tags', ...) separately. list() still
+ * issues multiple Meilisearch requests internally (the product search, the
+ * price facet stats, the tag facet distribution — see priceSliderBounds()'s
+ * own docblock for why the price ones can't be merged into one without
+ * changing the slider's UX), but that's this DTO's job to hide, not the
+ * controller's to know about.
+ */
+class ProductListingResult
+{
+    /**
+     * @param  array<int, string>  $availableTags  every distinct tag value
+     *   present on at least one product matching the listing's OTHER
+     *   filters (collection/price/stock — never the tag filter itself, so
+     *   selecting a tag doesn't collapse the list down to just that tag).
+     *   Sorted alphabetically. Empty if no product in scope has any tag.
+     */
+    public function __construct(
+        public readonly LengthAwarePaginator $products,
+        public readonly PriceSliderBounds $priceBounds,
+        public readonly array $availableTags = [],
+    ) {}
+}
@@ -0,0 +1,23 @@
+<?php
+
+namespace Modules\Core\Catalog\Events;
+
+/**
+ * Dispatched whenever a Product is deleted (see CatalogServiceProvider,
+ * which wires this to the model's own deleted() hook — fires for both a
+ * soft delete and a force delete, same as Laravel Scout's own
+ * ModelObserver::deleted() that triggers unsearchable() for the product
+ * itself). Same purpose as Modules\Core\Catalog\Events\ProductSaved: lets
+ * Modules\Core\Catalog\Listeners\ReindexProductsRecommendingProduct find
+ * and re-index every OTHER product that currently embeds this one in its
+ * `recommendations` field, so a deleted product doesn't linger as a dead
+ * reference elsewhere. Carries only the id, not the Product model — by the
+ * time this fires the model may already be gone (force delete), and the
+ * reverse lookup only ever needs the id to filter on.
+ */
+class ProductDeleted
+{
+    public function __construct(
+        public readonly int $productId,
+    ) {}
+}
@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Core\Catalog\Events;
+
+use Lunar\Models\Product;
+
+/**
+ * Dispatched whenever a Product is saved (see CatalogServiceProvider,
+ * which wires this to the model's own saved() hook) — exists specifically
+ * so Modules\Core\Catalog\Listeners\ReindexProductsRecommendingProduct can
+ * find and re-index every OTHER product that currently embeds this one in
+ * its own `recommendations` field (see ProductIndexer). Those products
+ * have no direct database relationship to this one — a recommendation is
+ * computed and stored only inside Meilisearch (Modules\Core\Catalog\
+ * Services\RecommendationService) — so nothing about their own save
+ * lifecycle would otherwise pick up this product's changed name/price/
+ * image.
+ */
+class ProductSaved
+{
+    public function __construct(
+        public readonly Product $product,
+    ) {}
+}
@@ -2,8 +2,8 @@

 namespace Modules\Core\Catalog\Filament\Extensions;

+use Filament\Schemas\Schema;
 use Filament\Forms\Components\Select;
-use Filament\Forms\Form;
 use Illuminate\Support\Str;
 use Lunar\Admin\Support\Extending\ResourceExtension;
 use Modules\Core\Catalog\Services\ProductOptionTypeManager;
@@ -16,7 +16,7 @@ use Modules\Core\Catalog\Services\ProductOptionTypeManager;
 */
 class ProductOptionResourceExtension extends ResourceExtension
 {
-    public function extendForm(Form $form): Form
+    public function extendForm(Schema $schema): Schema
    {
        $options = collect(ProductOptionTypeManager::get()->all())
            ->keys()
@@ -24,11 +24,11 @@ class ProductOptionResourceExtension extends ResourceExtension
            ->all();

        if ($options === []) {
-            return $form;
+            return $schema;
        }

-        return $form->schema([
-            ...$form->getComponents(),
+        return $schema->components([
+            ...$schema->getComponents(),
            Select::make('meta.option_type')
                ->label('Option Type')
                ->options($options)
@@ -2,7 +2,7 @@

 namespace Modules\Core\Catalog\Filament\Extensions;

-use Filament\Forms\Form;
+use Filament\Schemas\Schema;
 use Lunar\Admin\Support\Extending\RelationManagerExtension;
 use Lunar\Models\ProductOption;
 use Modules\Core\Catalog\Services\ProductOptionTypeManager;
@@ -15,7 +15,7 @@ use Modules\Core\Catalog\Services\ProductOptionTypeManager;
 */
 class ValuesRelationManagerExtension extends RelationManagerExtension
 {
-    public function extendForm(Form $form): Form
+    public function extendForm(Schema $schema): Schema
    {
        /** @var ProductOption $option */
        $option = $this->caller->getOwnerRecord();
@@ -23,11 +23,11 @@ class ValuesRelationManagerExtension extends RelationManagerExtension
        $type = ProductOptionTypeManager::get()->resolve($option->meta['option_type'] ?? null);

        if ($type === null) {
-            return $form;
+            return $schema;
        }

-        return $form->schema([
-            ...$form->getComponents(),
+        return $schema->components([
+            ...$schema->getComponents(),
            ...$type->getMetaForm(),
        ]);
    }
@@ -0,0 +1,64 @@
+<?php
+
+namespace Modules\Core\Catalog\Listeners;
+
+use Lunar\Models\Product;
+use Modules\Core\Catalog\Events\ProductDeleted;
+use Modules\Core\Catalog\Events\ProductSaved;
+
+/**
+ * Keeps every product's embedded `recommendations` field (see
+ * ProductIndexer) in sync when a product they recommend changes or is
+ * removed. Unlike Modules\Core\Catalog\Observers\ProductOptionReindexObserver's
+ * equivalent ("who references this option value"), there is no Postgres
+ * table to query here — a recommendation only exists inside Meilisearch,
+ * computed by RecommendationService at index time — so the reverse lookup
+ * is a Meilisearch filter query against `recommendations.id`, not a
+ * database join.
+ *
+ * Handles both ProductSaved (name/price/image changed — referencing
+ * products' embedded copy is stale) and ProductDeleted (the recommended
+ * product no longer exists at all — referencing products need to drop it
+ * and, since RecommendationService tops up to its limit, naturally pick up
+ * a replacement on reindex). Same reverse lookup either way, just a
+ * different source for the id being searched for.
+ *
+ * Re-indexing via ->searchable() dispatches Scout's own (queued, if
+ * SCOUT_QUEUE is configured) reindex job per matched product — this
+ * listener itself does no synchronous Meilisearch writing.
+ */
+class ReindexProductsRecommendingProduct
+{
+    public function handleSaved(ProductSaved $event): void
+    {
+        $this->reindexReferencingProducts($event->product->id);
+    }
+
+    public function handleDeleted(ProductDeleted $event): void
+    {
+        $this->reindexReferencingProducts($event->productId);
+    }
+
+    private function reindexReferencingProducts(int $productId): void
+    {
+        $hits = Product::search('')
+            ->options([
+                'filter' => "recommendations.id = \"{$productId}\"",
+                'attributesToRetrieve' => ['id'],
+                // Meilisearch's own hitsPerPage default (20) would silently
+                // drop referencing products past that count — this is a
+                // reverse lookup, not a paginated storefront result, so it
+                // needs every match, up to Meilisearch's hard limit.
+                'hitsPerPage' => 1000,
+            ])
+            ->raw()['hits'] ?? [];
+
+        $ids = collect($hits)->pluck('id')->unique()->values();
+
+        if ($ids->isEmpty()) {
+            return;
+        }
+
+        Product::whereIn('id', $ids)->get()->each->searchable();
+    }
+}
@@ -0,0 +1,27 @@
+<?php
+
+namespace Modules\Core\Catalog\Recommendations;
+
+use Illuminate\Support\Collection;
+use Lunar\Models\Product;
+use Modules\Core\Catalog\Contracts\RecommendationRule;
+
+/**
+ * The universal fallback — always returns something as long as the store
+ * has more than one product, since it has no eligibility condition of its
+ * own to come up empty on. Meant to be placed last in
+ * config('catalog.recommendation_rules'), not first: every store using
+ * the default chain gets a real fallback, but one that only kicks in once
+ * more specific rules (same category, same tag, ...) have had a chance.
+ */
+class RandomRule implements RecommendationRule
+{
+    public function recommend(Product $product, int $limit, array $exclude): Collection
+    {
+        return Product::query()
+            ->whereKeyNot($exclude)
+            ->inRandomOrder()
+            ->limit($limit)
+            ->get();
+    }
+}
@@ -0,0 +1,39 @@
+<?php
+
+namespace Modules\Core\Catalog\Recommendations;
+
+use Illuminate\Support\Collection;
+use Lunar\Models\Product;
+use Modules\Core\Catalog\Contracts\RecommendationRule;
+
+/**
+ * Recommends other products sharing at least one of $product's directly-
+ * assigned collections — takes $product's first collection (a product
+ * usually has one primary category; if it has several, the first is as
+ * good a choice as any without a "primary collection" concept to prefer).
+ * Returns nothing if $product has no collection at all, letting the next
+ * rule in the chain (see RecommendationRule's docblock) take over.
+ *
+ * Queries Eloquent directly rather than going through Modules\Core\Catalog\
+ * Services\ProductService — this runs at index time (see
+ * RecommendationRule's docblock), where Meilisearch may be mid-reindex for
+ * this very product and ProductService::list()'s locale-resolution has no
+ * meaningful "current locale" to resolve against anyway.
+ */
+class SameCategoryRule implements RecommendationRule
+{
+    public function recommend(Product $product, int $limit, array $exclude): Collection
+    {
+        $collection = $product->collections->first();
+
+        if ($collection === null) {
+            return collect();
+        }
+
+        return $collection->products()
+            ->whereKeyNot($exclude)
+            ->inRandomOrder()
+            ->limit($limit)
+            ->get();
+    }
+}
@@ -27,8 +27,14 @@ use Spatie\MediaLibrary\MediaCollections\Models\Media;
 *   - 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
+ *   - skus (every variant's sku, deduplicated, filterable) — same "resolve from the
+ *     index alone" reasoning as slugs, for a future SKU-based lookup/filter
 *   - price (cheapest variant, filterable) and full per-variant pricing
- *   - variants: sku, stock, purchasable, option values, prices, media
+ *   - variants: sku, gtin, mpn, ean, stock, backorder, unit_quantity, purchasable,
+ *     shippable, tax_ref, dimensions (length/width/height/weight/volume, each
+ *     {value, unit}), option values, prices, media — the variant's own images
+ *     (ProductVariant::images(), separate from the product's gallery below), not
+ *     the product's own media repeated per variant
 *   - 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
@@ -44,6 +50,21 @@ use Spatie\MediaLibrary\MediaCollections\Models\Media;
 *     Reflects stock as of the last reindex only — nothing currently reindexes a
 *     product when an order decrements its stock (see docs/product-listing.md).
 *
+ *   - recommendations (recommendations.id filterable): [{id, name, price, image}, ...]
+ *     up to 4 other products to show alongside this one (a "related products"
+ *     section), sourced from Modules\Core\Catalog\Services\RecommendationService's
+ *     configured rule chain (config('catalog.recommendation_rules')). Embedded
+ *     card data, not just ids, same reasoning as `collections`: renders
+ *     directly with zero extra Meilisearch calls. `name` is resolved via
+ *     translateAttribute() at index time (not through ProductService's
+ *     per-request locale resolution, since indexing has no "current locale"
+ *     the way a storefront request does) — same known index-time-locale
+ *     tradeoff `collections` already has. `recommendations.id` is filterable
+ *     specifically so Modules\Core\Catalog\Listeners\
+ *     ReindexProductsRecommendingProduct can find every product currently
+ *     recommending a given one, when that one changes — there's no Postgres
+ *     relation for this, a recommendation only exists inside the index.
+ *
 * 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.
@@ -67,6 +88,9 @@ class ProductIndexer extends BaseProductIndexer
            'slugs',
            'channel_ids',
            'in_stock',
+            'recommendations.id',
+            'skus',
+            'tags',
        ];
    }

@@ -110,6 +134,7 @@ class ProductIndexer extends BaseProductIndexer
            ->values()
            ->all();
        $data['slugs'] = $model->urls->pluck('slug')->unique()->values()->all();
+        $data['skus'] = $model->variants->pluck('sku')->filter()->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();
@@ -126,6 +151,16 @@ class ProductIndexer extends BaseProductIndexer
        $data['in_stock'] = $model->variants->contains(
            fn (ProductVariant $variant) => $variant->canBeFulfilledAtQuantity(1)
        );
+        $data['recommendations'] = app(RecommendationService::class)
+            ->recommend($model)
+            ->load(['media', 'variants.prices'])
+            ->map(fn (Product $recommendation) => [
+                'id' => $recommendation->id,
+                'name' => $recommendation->translateAttribute('name'),
+                'price' => $this->cheapestPrice($recommendation, $currency),
+                'image' => $recommendation->media->first() ? $this->mapMedia($recommendation->media->first())['thumb'] : null,
+            ])
+            ->all();

        return $data;
    }
@@ -135,8 +170,22 @@ class ProductIndexer extends BaseProductIndexer
        return [
            'id' => $variant->id,
            'sku' => $variant->sku,
+            'gtin' => $variant->gtin,
+            'mpn' => $variant->mpn,
+            'ean' => $variant->ean,
            'stock' => $variant->stock,
+            'backorder' => $variant->backorder,
+            'unit_quantity' => $variant->unit_quantity,
            'purchasable' => $variant->purchasable,
+            'shippable' => $variant->shippable,
+            'tax_ref' => $variant->tax_ref,
+            'dimensions' => [
+                'length' => ['value' => $variant->length_value, 'unit' => $variant->length_unit],
+                'width' => ['value' => $variant->width_value, 'unit' => $variant->width_unit],
+                'height' => ['value' => $variant->height_value, 'unit' => $variant->height_unit],
+                'weight' => ['value' => $variant->weight_value, 'unit' => $variant->weight_unit],
+                'volume' => ['value' => $variant->volume_value, 'unit' => $variant->volume_unit],
+            ],
            'options' => $variant->values->map(fn ($value) => [
                'option' => $this->translatedName($value->option->name),
                'handle' => $value->option->handle,
@@ -2,11 +2,15 @@

 namespace Modules\Core\Catalog\Services;

-use Illuminate\Database\Eloquent\Collection;
-use Illuminate\Support\Facades\App;
+use Illuminate\Pagination\LengthAwarePaginator;
 use Lunar\Facades\AttributeManifest;
 use Lunar\Models\Language;
 use Lunar\Models\Product;
+use Modules\Core\Catalog\DTOs\ProductFilters;
+use Modules\Core\Catalog\DTOs\ProductListingResult;
+use Modules\Core\Catalog\Enums\ProductSort;
+use Modules\Core\Catalog\Support\ProductDocumentLocalizer;
+use Modules\Core\Catalog\Support\ProductFilterBuilder;

 /**
 * Lunar's Meilisearch indexer flattens translated attributes into locale-suffixed
@@ -17,39 +21,103 @@ use Lunar\Models\Product;
 */
 class ProductSearchService
 {
-    /**
-     * @return Collection<int, Product>
-     */
-    public function search(string $query, ?string $locale = null): Collection
-    {
-        $locale ??= App::getLocale();
-        $defaultLocale = Language::getDefault()->code;
+    public function __construct(
+        private readonly ProductFilterBuilder $filterBuilder,
+        private readonly ProductDocumentLocalizer $localizer,
+        private readonly ProductService $products,
+    ) {}

-        return Product::search($query)
-            ->options([
-                'attributesToSearchOn' => $this->searchableFields($locale, $defaultLocale),
-            ])
-            ->get();
+    /**
+     * Returns the exact same Modules\Core\Catalog\DTOs\ProductListingResult
+     * ProductService::list() does — a search results page and a category
+     * listing page consume identically shaped data, one call each. The
+     * paginator itself carries plain, localized indexed-document arrays
+     * (not hydrated Product models), same as list().
+     *
+     * priceBounds/availableTags are delegated to ProductService's own
+     * priceSliderBounds()/availableTags() rather than reimplemented here —
+     * both already accept a $query param for exactly this reason (a search
+     * page's slider/tag sidebar should reflect only the products search
+     * actually matched, not the whole catalog).
+     *
+     * $filters/$sort apply the exact same semantics ProductService::list()
+     * uses for collection browsing (same ProductFilterBuilder, same
+     * ProductSort::toMeilisearchSort()) — a shopper narrowing a text search
+     * by price/brand/stock gets identical filter behavior to narrowing a
+     * category listing, since both go through the same Meilisearch `filter`
+     * clause underneath.
+     */
+    public function search(
+        string $query,
+        ?ProductFilters $filters = null,
+        ?ProductSort $sort = null,
+        int $perPage = 24,
+        int $page = 1,
+    ): ProductListingResult {
+        $options = [
+            'attributesToSearchOn' => $this->searchableFields(),
+            'filter' => $this->filterBuilder->build($filters),
+        ];
+
+        if ($sort !== null) {
+            $options['sort'] = [$sort->toMeilisearchSort()];
+        }
+
+        $paginator = Product::search($query)
+            ->options($options)
+            ->paginateRaw(perPage: $perPage, page: $page);
+
+        $data = collect($this->localizer->hitsFrom($paginator))
+            ->map(fn (array $product) => $this->localizer->withLocalizedFields($product))
+            ->all();
+
+        $products = new LengthAwarePaginator(
+            items: $data,
+            total: $paginator->total(),
+            perPage: $paginator->perPage(),
+            currentPage: $paginator->currentPage(),
+            options: ['path' => LengthAwarePaginator::resolveCurrentPath()],
+        );
+
+        $priceBounds = $this->products->priceSliderBounds($filters, $filters?->minPrice, $filters?->maxPrice, $query);
+        $availableTags = $this->products->availableTags($filters, $query);
+
+        return new ProductListingResult($products, $priceBounds, $availableTags);
    }

    /**
-     * 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.
+     * Targets every configured store language's fields, not just the current
+     * request locale plus the store default — a shopper browsing in Greek
+     * typing an English word (or vice versa) should still match a product
+     * whose only translation for that text happens to be in a third
+     * language. There's no per-request "current locale" concept in this
+     * method any more: which fields exist to search on is a property of the
+     * store's configured languages, not of who's asking.
+     *
+     * Also targets variants.options.value directly — a variant's option
+     * value (e.g. "Κάπτεν Γαμέρικα" on a "Name" option) is how ProductIndexer
+     * already indexes it (see mapVariant()), but it isn't one of Lunar's own
+     * attributes, so it can't come from AttributeManifest the way name/
+     * description do; it's a structural field of the document, added here
+     * directly instead. Not locale-suffixed like the attribute-manifest
+     * fields — option values are stored as one already-resolved string per
+     * variant (see ProductIndexer::translatedName()), not per-locale.
     *
     * @return array<int, string>
     */
-    private function searchableFields(string $locale, string $defaultLocale): array
+    private function searchableFields(): array
    {
        $handles = AttributeManifest::getSearchableAttributes(Product::morphName())
            ->pluck('handle');

-        $locales = array_unique([$locale, $defaultLocale]);
+        $locales = Language::all()->pluck('code');

-        return $handles
+        $attributeFields = $handles
            ->crossJoin($locales)
-            ->map(fn (array $pair) => "{$pair[0]}_{$pair[1]}")
+            ->map(fn (array $pair) => "{$pair[0]}_{$pair[1]}");
+
+        return $attributeFields
+            ->push('variants.options.value')
            ->values()
            ->all();
    }
@@ -2,16 +2,14 @@

 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\PriceSliderBounds;
 use Modules\Core\Catalog\DTOs\ProductFilters;
+use Modules\Core\Catalog\DTOs\ProductListingResult;
 use Modules\Core\Catalog\Enums\ProductSort;
+use Modules\Core\Catalog\Support\ProductDocumentLocalizer;
+use Modules\Core\Catalog\Support\ProductFilterBuilder;

 /**
 * Storefront product listing/filtering AND single-product lookup, all reading directly
@@ -25,19 +23,34 @@ use Modules\Core\Catalog\Enums\ProductSort;
 class ProductService
 {
    public function __construct(
-        private readonly LanguageCache $languages,
-        private readonly AttributeManifest $attributes,
+        private readonly ProductDocumentLocalizer $localizer,
+        private readonly ProductFilterBuilder $filterBuilder,
    ) {}

    /**
-     * 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.
+     * One call for everything a listing page needs: the product page AND
+     * the price slider's bounds — a controller used to have to call this
+     * plus priceSliderBounds() separately and glue the results together
+     * itself; that orchestration now happens in here instead. Still issues
+     * two Meilisearch requests under the hood (the product search, and a
+     * separate price-facet-stats query — see priceSliderBounds()'s
+     * docblock for why they can't be merged into one without changing the
+     * slider's own UX), but the caller only ever makes one call.
+     *
+     * $filters->minPrice/$filters->maxPrice double as both the applied
+     * product filter AND the "is the slider actually narrowed" comparison
+     * in priceSliderBounds() — the same values, used two ways, so nothing
+     * new needs to be threaded through separately.
+     *
+     * The paginator itself is 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
+    public function list(?ProductFilters $filters = null, int $perPage = 24, int $page = 1, ?ProductSort $sort = null): ProductListingResult
    {
-        $options = ['filter' => $this->buildFilter($filters)];
+        $options = ['filter' => $this->filterBuilder->build($filters)];

        if ($sort !== null) {
            $options['sort'] = [$sort->toMeilisearchSort()];
@@ -47,17 +60,48 @@ class ProductService
            ->options($options)
            ->paginateRaw(perPage: $perPage, page: $page);

-        $data = collect($this->hitsFrom($paginator))
-            ->map(fn (array $product) => $this->withLocalizedFields($product))
+        $data = collect($this->localizer->hitsFrom($paginator))
+            ->map(fn (array $product) => $this->localizer->withLocalizedFields($product))
            ->all();

-        return new LengthAwarePaginator(
+        $products = new LengthAwarePaginator(
            items: $data,
            total: $paginator->total(),
            perPage: $paginator->perPage(),
            currentPage: $paginator->currentPage(),
            options: ['path' => LengthAwarePaginator::resolveCurrentPath()],
        );
+
+        $priceBounds = $this->priceSliderBounds($filters, $filters?->minPrice, $filters?->maxPrice);
+        $availableTags = $this->availableTags($filters);
+
+        return new ProductListingResult($products, $priceBounds, $availableTags);
+    }
+
+    /**
+     * Every distinct `tags` value present on a product matching $filters,
+     * excluding $filters->tag itself — same "scoped but not self-collapsing"
+     * reasoning as priceRange() excluding `price` — so selecting a tag
+     * doesn't shrink the sidebar down to just that one tag. Sorted
+     * alphabetically; Meilisearch's facetDistribution has no defined order
+     * of its own.
+     *
+     * $query defaults to '' (every product, same as list()'s own default
+     * text query) — same reasoning as priceRange()'s own $query: pass the
+     * shopper's search text here too so a search page's own tag sidebar
+     * reflects only the products search actually matched. Public (not
+     * private, unlike the rest of this listing-only orchestration) so
+     * ProductSearchService::search() can reuse it directly rather than
+     * reimplementing the same facet call a second time.
+     *
+     * @return array<int, string>
+     */
+    public function availableTags(?ProductFilters $filters, string $query = ''): array
+    {
+        $filter = $this->filterBuilder->build($filters, exclude: ['tag']);
+        $tags = $this->rawFacets('tags', $filter, $query)['facetDistribution']['tags'] ?? [];
+
+        return collect($tags)->keys()->sort()->values()->all();
    }

    /**
@@ -71,15 +115,18 @@ class ProductService
     * 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.
+     * fields make sense here (`brand`, `tags`, `in_stock`) — a numeric field like
+     * `price` would return one "facet" per exact price, not a usable range bucket.
+     * Use `priceRange()` for `price` instead. `facets('tags', $filters)` is how a
+     * category page gets "which tags actually appear on products in this category" —
+     * pass a $filters that omits `tag` (see `build()`'s $exclude) so the tag list
+     * itself doesn't collapse to whichever tag is already selected.
     *
     * @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] ?? [];
+        return $this->rawFacets($field, $this->filterBuilder->build($filters))['facetDistribution'][$field] ?? [];
    }

    /**
@@ -90,12 +137,17 @@ class ProductService
     * not `facetDistribution` — the right feature for a numeric field's range,
     * where `facets('price')` would otherwise return one entry per exact price.
     *
+     * $query defaults to '' (every product, same as list()'s own default text
+     * query) — pass the shopper's search text here too so a search page's own
+     * price slider spans only the products that search actually matched,
+     * rather than the whole catalog's price range.
+     *
     * @return array{min: ?float, max: ?float} null/null if no product matches
     */
-    public function priceRange(?ProductFilters $filters = null): array
+    public function priceRange(?ProductFilters $filters = null, string $query = ''): array
    {
-        $filter = $this->buildFilter($filters, exclude: ['price']);
-        $stats = $this->rawFacets('price', $filter)['facetStats']['price'] ?? null;
+        $filter = $this->filterBuilder->build($filters, exclude: ['price']);
+        $stats = $this->rawFacets('price', $filter, $query)['facetStats']['price'] ?? null;

        return [
            'min' => $stats['min'] ?? null,
@@ -103,9 +155,36 @@ class ProductService
        ];
    }

-    private function rawFacets(string $field, ?string $filter): array
+    /**
+     * priceRange() rounded to whole euros (floor/ceil, so the slider's ends
+     * are never tighter than what's actually in range) plus whether
+     * $selectedMinPrice/$selectedMaxPrice actually narrow it — the same
+     * "floor/ceil + is this a real filter" rule CategoryController and
+     * SearchController each used to duplicate inline. $selectedMinPrice/
+     * $selectedMaxPrice are the currently-applied filter values (e.g.
+     * CategoryListing::$minPrice), not part of $filters itself, since
+     * $filters here must already exclude price the way priceRange() expects.
+     */
+    public function priceSliderBounds(
+        ?ProductFilters $filters,
+        ?float $selectedMinPrice,
+        ?float $selectedMaxPrice,
+        string $query = '',
+    ): PriceSliderBounds {
+        $priceRange = $this->priceRange($filters, $query);
+
+        $floor = $priceRange['min'] !== null ? (int) floor($priceRange['min']) : null;
+        $ceil = $priceRange['max'] !== null ? (int) ceil($priceRange['max']) : null;
+
+        $filtered = ($selectedMinPrice !== null && $selectedMinPrice > ($floor ?? PHP_INT_MIN))
+            || ($selectedMaxPrice !== null && $selectedMaxPrice < ($ceil ?? PHP_INT_MAX));
+
+        return new PriceSliderBounds($floor, $ceil, $filtered);
+    }
+
+    private function rawFacets(string $field, ?string $filter, string $query = ''): array
    {
-        return Product::search('')
+        return Product::search($query)
            ->options([
                'filter' => $filter,
                'facets' => [$field],
@@ -133,99 +212,86 @@ class ProductService
        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.
+     * The id/price/image of every variant on a product document (from
+     * getById()/getBySlug()'s own 'variants' array) — the base price and
+     * thumbnail a variant picker/swatch list needs, without a caller
+     * reaching into $product['variants'][n]['prices'][0]/['media'][0]
+     * itself. Domain shaping (which price/image represents a variant),
+     * not presentation — a card's href/layout stays a storefront concern
+     * (e.g. App\Catalog\ProductCard in 3dealer), but "the variant's price
+     * is its first price row" is a rule about the data, true regardless of
+     * which app renders it.
     *
-     * 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.
+     * @param  array  $product  A document from getById()/getBySlug().
+     * @return array<int, array{id: int, price: ?float, image: ?string}>
     */
-    private function withLocalizedFields(array $product): array
+    public function variantSummaries(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')
+        return collect($product['variants'] ?? [])
+            ->map(fn (array $variant) => [
+                'id' => $variant['id'],
+                'price' => $variant['prices'][0]['price'] ?? null,
+                'image' => $variant['media'][0]['url'] ?? null,
+            ])
+            ->values()
            ->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.
+     * $limit random products, still scoped to the index's own default
+     * visibility (channel/status), unlike Eloquent's Product::inRandomOrder()
+     * which has no notion of that filtering at all — a random pick can never
+     * surface a hidden/unpublished product this way. Meilisearch itself has
+     * no ORDER BY RANDOM() equivalent, so this pulls every matching id only
+     * (attributesToRetrieve: ['id'], the lightest possible request — no
+     * name/media/variants/etc. for documents that will mostly be discarded),
+     * shuffles in PHP, then fetches the full localized documents for just
+     * the $limit ids actually picked.
+     *
+     * @return array<int, array>
     */
-    private function hitsFrom(LengthAwarePaginatorContract $paginator): array
+    public function random(int $limit): array
    {
-        $rawResponse = $paginator->items();
+        $raw = Product::search('')
+            ->options(['attributesToRetrieve' => ['id']])
+            ->raw();

-        return collect($rawResponse['hits'] ?? [])->values()->all();
+        $ids = collect($raw['hits'] ?? [])->pluck('id')->shuffle()->take($limit)->values();
+
+        if ($ids->isEmpty()) {
+            return [];
+        }
+
+        // Meilisearch's `id IN [...]` doesn't preserve the given order — it's
+        // an unordered set filter, not a list to iterate — so the shuffle
+        // above would otherwise be silently undone by whatever order the
+        // re-fetch comes back in. Re-sort the fetched documents back into
+        // $ids's already-shuffled order instead of trusting the response's.
+        $products = collect($this->findAllWhere('id IN ['.$ids->implode(', ').']'))
+            ->keyBy('id');
+
+        return $ids->map(fn ($id) => $products->get($id))->filter()->values()->all();
+    }
+
+    private function findOneWhere(string $filter): ?array
+    {
+        $products = $this->findAllWhere($filter, limit: 1);
+
+        return $products[0] ?? null;
    }

    /**
-     * @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.
+     * @return array<int, array>
     */
-    private function buildFilter(?ProductFilters $filters, array $exclude = []): ?string
+    private function findAllWhere(string $filter, int $limit = 1000): array
    {
-        if ($filters === null) {
-            return null;
-        }
+        $paginator = Product::search('')
+            ->options(['filter' => $filter])
+            ->paginateRaw(perPage: $limit, page: 1);

-        $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 ');
+        return collect($this->localizer->hitsFrom($paginator))
+            ->map(fn (array $product) => $this->localizer->withLocalizedFields($product))
+            ->all();
    }
 }
@@ -0,0 +1,47 @@
+<?php
+
+namespace Modules\Core\Catalog\Services;
+
+use Illuminate\Database\Eloquent\Collection;
+use Lunar\Models\Product;
+use Modules\Core\Catalog\Contracts\RecommendationRule;
+
+/**
+ * Runs each rule in config('catalog.recommendation_rules'), in order,
+ * topping up from each successive rule until $limit distinct products are
+ * collected or every rule is exhausted — e.g. 3 from SameCategoryRule
+ * (the product's category only has 3 other products) + 1 from RandomRule.
+ * No rule is special-cased as "the fallback" here; a store gets fallback
+ * behaviour purely by how it orders its own config (e.g. SameCategoryRule
+ * before RandomRule). Never returns the same product twice even if two
+ * rules would both suggest it (see RecommendationRule's $exclude), and
+ * never returns fewer than $limit unless the store genuinely doesn't have
+ * that many other products at all.
+ */
+class RecommendationService
+{
+    /**
+     * @return Collection<int, Product>
+     */
+    public function recommend(Product $product, int $limit = 4): Collection
+    {
+        $recommendations = new Collection();
+
+        foreach (config('catalog.recommendation_rules', []) as $ruleClass) {
+            if ($recommendations->count() >= $limit) {
+                break;
+            }
+
+            $exclude = [$product->id, ...$recommendations->pluck('id')];
+            $remaining = $limit - $recommendations->count();
+
+            /** @var RecommendationRule $rule */
+            $rule = app($ruleClass);
+            $recommendations = $recommendations->merge(
+                $rule->recommend($product, $remaining, $exclude)
+            );
+        }
+
+        return $recommendations->take($limit)->values();
+    }
+}
@@ -0,0 +1,86 @@
+<?php
+
+namespace Modules\Core\Catalog\Support;
+
+use Illuminate\Contracts\Pagination\LengthAwarePaginator as LengthAwarePaginatorContract;
+use Illuminate\Support\Facades\App;
+use Lunar\Base\AttributeManifest;
+use Lunar\FieldTypes\TranslatedText;
+use Lunar\Models\Product;
+use Modules\Core\Localization\Services\LanguageCache;
+
+/**
+ * Shared between Modules\Core\Catalog\Services\ProductService and
+ * ProductSearchService — both read the same kind of Meilisearch document
+ * (Modules\Core\Catalog\Services\ProductIndexer's shape) and need the
+ * exact same per-locale field resolution and raw-response unwrapping.
+ * Extracted rather than duplicated so a future fix to the localization-
+ * fallback logic only needs to be made once.
+ */
+class ProductDocumentLocalizer
+{
+    public function __construct(
+        private readonly LanguageCache $languages,
+        private readonly AttributeManifest $attributes,
+    ) {}
+
+    /**
+     * 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.
+     */
+    public 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;
+    }
+
+    /**
+     * 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.
+     */
+    public function hitsFrom(LengthAwarePaginatorContract $paginator): array
+    {
+        $rawResponse = $paginator->items();
+
+        return collect($rawResponse['hits'] ?? [])->values()->all();
+    }
+
+    /**
+     * @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();
+    }
+}
@@ -0,0 +1,41 @@
+<?php
+
+namespace Modules\Core\Catalog\Support;
+
+use Illuminate\Support\Collection;
+use Modules\Core\Catalog\DTOs\ProductFilters;
+
+/**
+ * Builds a Meilisearch `filter` clause from a ProductFilters DTO — extracted
+ * out of ProductService (where it originated, scoped to browsing/filtering
+ * without a search term) so ProductSearchService can apply the exact same
+ * filter semantics to a text query too, rather than reimplementing it.
+ */
+class ProductFilterBuilder
+{
+    /**
+     * @param  array<int, 'collectionId'|'brand'|'tag'|'price'|'inStockOnly'>  $exclude
+     *   filter fields to leave out even if set on $filters — e.g.
+     *   ProductService::priceRange() excludes 'price' so a price slider's own
+     *   bounds don't shrink to whatever range is already selected on it.
+     */
+    public function build(?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,
+            'tag' => $filters->tag !== null ? 'tags = "'.addcslashes($filters->tag, '"\\').'"' : 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 ');
+    }
+}
@@ -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,
+    ) {}
+}
@@ -0,0 +1,25 @@
+<?php
+
+namespace Modules\Core\Checkout\Events;
+
+use Lunar\Models\Order;
+
+/**
+ * Dispatched once an Order's placed_at is set — the handoff point between
+ * Checkout/Payment and Order (see docs/checkout.md's "Three-stage
+ * lifecycle"). Fired by Modules\Core\Order\Listeners\
+ * ApplyResolvedPaymentStatus once it resolves a PaymentCaptured/
+ * PaymentAuthorized event into an actual order status change, not by
+ * CheckoutService directly — a draft Order can exist (via
+ * CheckoutService::initiatePayment()) well before this fires, if payment
+ * resolves asynchronously (e.g. a redirect-based gateway). Checkout has no
+ * opinion about what happens after this fires; Order's own listeners are
+ * what react to it — e.g. a confirmation email, initializing order status
+ * tracking.
+ */
+class OrderPlaced
+{
+    public function __construct(
+        public readonly Order $order,
+    ) {}
+}
@@ -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,
+    ) {}
+}
@@ -0,0 +1,20 @@
+<?php
+
+namespace Modules\Core\Checkout\Events;
+
+use Lunar\Models\Cart;
+
+/**
+ * Dispatched by CheckoutService::setRecoveryConsent() every time the
+ * shopper's promotional/abandoned-cart-recovery opt-in changes — including
+ * an explicit opt-OUT (a later submit with the checkbox unticked), not
+ * just an opt-in. $consent is the new value, already written to
+ * Cart::meta by the time this fires.
+ */
+class RecoveryConsentSet
+{
+    public function __construct(
+        public readonly Cart $cart,
+        public readonly bool $consent,
+    ) {}
+}
@@ -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,
+    ) {}
+}
@@ -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,
+    ) {}
+}
@@ -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.");
+    }
+}
@@ -0,0 +1,19 @@
+<?php
+
+namespace Modules\Core\Checkout\Exceptions;
+
+use RuntimeException;
+
+/**
+ * Thrown by CheckoutService::initiatePayment() when $termsAccepted is
+ * false — an Order is a consumer contract, and its acceptance must be
+ * refused rather than created-then-flagged. No Lunar exception type
+ * covers this, same reasoning as UnknownPaymentTypeException.
+ */
+class TermsNotAcceptedException extends RuntimeException
+{
+    public function __construct()
+    {
+        parent::__construct('The order cannot be placed until the terms have been accepted.');
+    }
+}
@@ -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.");
+    }
+}
@@ -0,0 +1,305 @@
+<?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 Modules\Core\Cart\Services\CartService;
+use Modules\Core\Checkout\Events\BillingAddressSet;
+use Modules\Core\Checkout\Events\PaymentMethodSelected;
+use Modules\Core\Checkout\Events\RecoveryConsentSet;
+use Modules\Core\Checkout\Events\ShippingAddressSet;
+use Modules\Core\Checkout\Events\ShippingOptionSelected;
+use Modules\Core\Checkout\Exceptions\InvalidShippingOptionException;
+use Modules\Core\Checkout\Exceptions\TermsNotAcceptedException;
+use Modules\Core\Checkout\Exceptions\UnknownPaymentTypeException;
+use Modules\Core\Payment\DTOs\PaymentResult;
+use Modules\Core\Payment\Models\PaymentMethod;
+use Modules\Core\Payment\Services\PaymentDriverRegistry;
+use Modules\Core\Payment\Services\PaymentMethodCache;
+
+/**
+ * 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,
+ * ensuring a draft Order exists) and hands off to Payment the instant that
+ * draft exists — see initiatePayment(). What happens to that Order
+ * afterward (status transitions, fulfillment) is deliberately out of
+ * scope here — see docs/payments.md and Checkout\Events\OrderPlaced's
+ * docblock for where that now lives.
+ *
+ * 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,
+        private readonly PaymentDriverRegistry $paymentDrivers,
+        private readonly PaymentMethodCache $paymentMethods,
+    ) {}
+
+    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;
+    }
+
+    /**
+     * The shopper's promotional/abandoned-cart-recovery opt-in — a
+     * cart-level decision, deliberately independent of setShippingAddress()/
+     * setBillingAddress(): consent is given once, and must NOT be reset or
+     * re-asked just because the shopper later changes which address is on
+     * the cart (a different Addressable being set is not a withdrawal of
+     * consent). Only an explicit call to THIS method — the checkbox itself
+     * being submitted, checked or unchecked — ever changes it; calling it
+     * again with false is exactly how a later opt-out is recorded.
+     *
+     * Stored on Cart::meta (interim, per the legal design this implements —
+     * a real column/consent record is the eventual target) as
+     * recovery_consent (bool), recovery_consent_at (ISO 8601 timestamp,
+     * null when $consent is false), and recovery_consent_policy_version
+     * (config('legal.privacy_policy_version') at the moment of consent —
+     * so a later dispute is answered from what was actually agreed to,
+     * not whatever the policy says today). Separate from any future
+     * newsletter opt-in — recovery consent is its own scope, never merged
+     * with marketing-newsletter consent.
+     *
+     * Deliberately does not merge with the meta-writing pattern
+     * selectPaymentMethod() uses (read-merge-save in two separate
+     * statements) — this writes both meta keys in one save, since there's
+     * no dependency between recovery_consent and anything else needing to
+     * be persisted first.
+     */
+    public function setRecoveryConsent(bool $consent): Cart
+    {
+        $cart = $this->cart->currentOrCreate();
+
+        $cart->meta = [
+            ...($cart->meta?->toArray() ?? []),
+            'recovery_consent' => $consent,
+            'recovery_consent_at' => $consent ? now()->toIso8601String() : null,
+            'recovery_consent_policy_version' => $consent ? config('legal.privacy_policy_version') : null,
+        ];
+        $cart->save();
+
+        Event::dispatch(new RecoveryConsentSet($cart, $consent));
+
+        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;
+    }
+
+    /**
+     * Every payment method currently offered to the storefront, ordered by
+     * Modules\Core\Payment\Models\PaymentMethod::position — a row is
+     * offered only when ALL three checks pass, each meaning something
+     * different to an admin diagnosing why a method isn't showing up (see
+     * docs/payments.md):
+     *   1. `enabled` — an admin turned it on.
+     *   2. its `driver` still resolves via PaymentDriverRegistry — the
+     *      driver class hasn't been removed (see the `payment:sync-drivers`
+     *      command, which sets `driver_missing_at` when this fails; a row
+     *      with that set is excluded here regardless of `enabled`, so a
+     *      vanished driver can never silently look "available").
+     *   3. the resolved driver reports Configurable::isConfigured() — its
+     *      own runtime requirements (e.g. an API key) are met.
+     *
+     * @return Collection<int, PaymentMethod>
+     */
+    public function getPaymentMethods(): Collection
+    {
+        return $this->paymentMethods->all()
+            ->filter(fn (PaymentMethod $method) => $method->enabled && $method->driver_missing_at === null)
+            ->filter(fn (PaymentMethod $method) => $this->paymentDrivers->resolve($method->driver)?->isConfigured() ?? false)
+            ->values();
+    }
+
+    /**
+     * 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 initiatePayment() that
+     * the shopper's reviewed total is known, and initiatePayment() 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 payment driver — selecting a method and
+     * initiating 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
+     */
+    public function selectPaymentMethod(string $type): Cart
+    {
+        if (! $this->getPaymentMethods()->contains('type', $type)) {
+            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;
+    }
+
+    /**
+     * The one storefront-facing "place this order and pay for it" call —
+     * the point where Checkout hands off to Payment. Ensures a draft
+     * Order exists (Cart::createOrder() — confirmed idempotent against a
+     * cart's own pre-existing, not-yet-placed-at draft; see
+     * vendor/lunarphp/core/src/Actions/Carts/CreateOrder.php), then
+     * resolves the payment method selected by selectPaymentMethod() and
+     * calls pay() or authorize() on its driver, per that method's own
+     * `capture_mode` column.
+     *
+     * Returns the driver's own PaymentResult UNCHANGED — this method does
+     * not wait for or resolve anything past what pay()/authorize() itself
+     * returns synchronously. A Pending result (an async gateway like
+     * Stripe requiring 3-D Secure/a redirect) is a normal, expected
+     * outcome, not an error — the caller (a storefront controller) is
+     * responsible for whatever the gateway needs next.
+     *
+     * The draft order's own $order->total (not the Cart's) is what gets
+     * passed as $amount — Order::$total is Lunar's own Price-cast
+     * attribute, already resolving the correct Currency via the order's
+     * own currency_code, and is the authoritative total once the draft
+     * row exists.
+     *
+     * $context passed to the driver is {cart_id, order_id} — the exact
+     * keys Modules\Core\Payment\Drivers\StripePaymentDriver::
+     * rememberIntent() already reads.
+     *
+     * Same fingerprint precondition the old placeOrder() had: mandatory,
+     * not optional, checked before the draft is created.
+     *
+     * $termsAccepted is likewise mandatory, not optional data a caller
+     * might omit — an Order is a consumer contract, and its acceptance
+     * must be refused (TermsNotAcceptedException, before createOrder() is
+     * ever called — the order is never created-then-flagged) rather than
+     * assumed. $policyVersion is recorded alongside it on the created
+     * Order's own meta (terms_accepted, terms_accepted_at,
+     * terms_accepted_policy_version) — the order-level equivalent of
+     * setRecoveryConsent()'s cart-level record, and the durable audit
+     * trail for a later "what did the shopper actually agree to"
+     * dispute. Written directly here (not via a separate event/listener)
+     * since the Order row this attaches to doesn't exist before
+     * createOrder() runs, and nothing else needs to react to this
+     * specific write independently of the order simply existing.
+     *
+     * @param  array<string, mixed>  $data  passed through untouched to
+     *   the driver's pay()/authorize() — e.g. Stripe's payment_method
+     *   token.
+     *
+     * @throws UnknownPaymentTypeException if the cart's selected
+     *   payment_method (from selectPaymentMethod()) is no longer offered
+     *   — re-checked here, not just at selection time, since a method
+     *   could be disabled (or its driver removed) in between
+     * @throws TermsNotAcceptedException if $termsAccepted is false
+     * @throws FingerprintMismatchException
+     * @throws CartException
+     */
+    public function initiatePayment(string $fingerprint, bool $termsAccepted, string $policyVersion, array $data = []): PaymentResult
+    {
+        if (! $termsAccepted) {
+            throw new TermsNotAcceptedException;
+        }
+
+        $cart = $this->cart->currentOrCreate();
+        $cart->checkFingerprint($fingerprint);
+
+        $type = $cart->meta['payment_method'] ?? null;
+        $method = $type !== null ? $this->getPaymentMethods()->firstWhere('type', $type) : null;
+
+        if ($method === null) {
+            throw new UnknownPaymentTypeException((string) $type);
+        }
+
+        $order = $cart->createOrder();
+
+        $order->meta = [
+            ...($order->meta?->toArray() ?? []),
+            'terms_accepted' => true,
+            'terms_accepted_at' => now()->toIso8601String(),
+            'terms_accepted_policy_version' => $policyVersion,
+        ];
+        $order->save();
+
+        $driver = $this->paymentDrivers->resolve($method->driver);
+        $context = ['cart_id' => $cart->id, 'order_id' => $order->id];
+
+        return $method->capture_mode === 'authorize'
+            ? $driver->authorize($type, $order->total, $data, $context)
+            : $driver->pay($type, $order->total, $data, $context);
+    }
+}
@@ -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,
                },
            ),
@@ -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) {
@@ -21,6 +21,7 @@ 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
@@ -247,6 +248,9 @@ class InstallLunarCommand extends Command
        $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');

@@ -278,4 +282,41 @@ class InstallLunarCommand extends Command
            $translations->create('storefront', $key, $text);
        }
    }
+
+    /**
+     * A single, deliberately opinionated starter row on fresh install —
+     * `PaymentMethod` is now fully admin-creatable/deletable (see
+     * docs/payments.md), so this is no longer "seed every config-defined
+     * type," it's "give a fresh store one reasonable payment method to
+     * start from instead of zero." Every value here is a plain literal in
+     * THIS command, not sourced from config or PaymentDriverRegistry — a
+     * driver has no business carrying opinions about what its captured
+     * order status should be called; that's a merchant decision.
+     *
+     * Skip-if-exists on `type`, same idempotent convention as
+     * seedStorefrontLabels() — an admin who has since edited or deleted
+     * this row (via the Filament Payment Methods resource) is left alone;
+     * re-running lunar:install never recreates a deleted starter row.
+     *
+     * Seeded disabled — shouldn't go live for shoppers before staff have
+     * actually reviewed it and turned it on via the Payment Methods
+     * resource. See CheckoutService::getPaymentMethods().
+     */
+    private function seedPaymentMethods(): void
+    {
+        if (PaymentMethod::where('type', 'cash-on-delivery')->exists()) {
+            return;
+        }
+
+        PaymentMethod::create([
+            'type' => 'cash-on-delivery',
+            'name' => 'Cash on Delivery',
+            'driver' => 'offline',
+            'capture_mode' => 'pay',
+            'captured_status' => 'payment-offline',
+            'position' => 0,
+            'enabled' => false,
+            'data' => [],
+        ]);
+    }
 }
@@ -0,0 +1,52 @@
+<?php
+
+namespace Modules\Core\Command;
+
+use Illuminate\Console\Command;
+use Modules\Core\Payment\Models\PaymentMethod;
+use Modules\Core\Payment\Services\PaymentDriverRegistry;
+
+/**
+ * Reconciles every Modules\Core\Payment\Models\PaymentMethod row's `driver`
+ * column against PaymentDriverRegistry — the registry only knows "which
+ * driver classes exist THIS deploy," and only at the moment something
+ * calls resolve(); nothing else notices a driver disappearing (a package
+ * removed, a custom Registry::register() call deleted) on its own. Meant
+ * to run unconditionally on every container start/deploy (alongside
+ * `migrate`), not on a schedule — "did the set of registered drivers
+ * change" is a deploy-time event, cheap enough to check every single time
+ * regardless of whether anything actually changed. See docs/payments.md.
+ *
+ * Sets/clears `driver_missing_at` — deliberately NOT the `enabled` column,
+ * so an admin's own manual toggle is never confused with "the driver
+ * vanished," and a driver that comes back in a later deploy auto-clears
+ * this with no admin action needed.
+ */
+class SyncPaymentDriversCommand extends Command
+{
+    protected $signature = 'boboko:payment:sync-drivers';
+
+    protected $description = 'Flag PaymentMethod rows whose driver no longer resolves via the registry, and clear the flag for ones that do again';
+
+    public function handle(PaymentDriverRegistry $registry): int
+    {
+        $missing = 0;
+        $restored = 0;
+
+        PaymentMethod::query()->each(function (PaymentMethod $method) use ($registry, &$missing, &$restored) {
+            $resolves = $method->driver !== null && $registry->resolve($method->driver) !== null;
+
+            if (! $resolves && $method->driver_missing_at === null) {
+                $method->update(['driver_missing_at' => now()]);
+                $missing++;
+            } elseif ($resolves && $method->driver_missing_at !== null) {
+                $method->update(['driver_missing_at' => null]);
+                $restored++;
+            }
+        });
+
+        $this->components->info("Payment driver sync complete: {$missing} newly flagged, {$restored} restored.");
+
+        return self::SUCCESS;
+    }
+}
@@ -0,0 +1,67 @@
+<?php
+
+namespace Modules\Core\Command;
+
+use Illuminate\Console\Command;
+use Laravel\Scout\EngineManager;
+use Laravel\Scout\Engines\MeilisearchEngine;
+use Lunar\Models\Product;
+
+/**
+ * lunarphp/meilisearch's own `lunar:meilisearch:setup` only pushes
+ * filterableAttributes/sortableAttributes (see MeilisearchSetup::handle())
+ * — it has no notion of typo tolerance or prefix search, and Meilisearch's
+ * defaults for both are loose enough to produce bad matches on short Greek
+ * words. Confirmed via showMatchesPosition that a query for "Κάπτεν" was
+ * matching "κανένας" purely through prefixSearch's default 'indexingTime'
+ * behavior (their edit distance is far past anything typo tolerance would
+ * bridge) — fixed by disabling prefix search below, verified afterward with
+ * "Super"/"Superheroes"-style prefix probes returning no results for a
+ * partial word. minWordSizeForTypos is tightened defensively alongside it
+ * so short words in general get less typo-tolerant fuzzing, even though a
+ * separate short-word collision case ("Κάπτεν" vs "κάποτε", high letter
+ * overlap despite real edit distance) persisted after both settings were
+ * confirmed live and wasn't fully root-caused — treated as a known,
+ * narrow edge case rather than a blocker. Run this after
+ * `lunar:meilisearch:setup`, whenever Product's index needs
+ * (re)provisioning.
+ *
+ * Disabling prefix search here is a deliberate tradeoff: it also turns off
+ * legitimate partial-word matching (typing "car" matching "cart" before
+ * you finish the word) — useful for a future autocomplete/search-as-you-
+ * type UI. If that's built later, re-enable prefixSearch deliberately then,
+ * informed by real UX needs, rather than leaving it on by accident today.
+ */
+class TuneProductSearchCommand extends Command
+{
+    protected $signature = 'lunar:meilisearch:tune-product-search';
+
+    protected $description = 'Tighten typo-tolerance and disable prefix search on the product search index';
+
+    public function handle(EngineManager $engineManager): void
+    {
+        /** @var MeilisearchEngine $engine */
+        $engine = $engineManager->createMeilisearchDriver();
+
+        $index = $engine->getIndex((new Product)->searchableAs());
+
+        $this->components->info('Updating typo tolerance for product search...');
+
+        $task = $index->updateTypoTolerance([
+            'minWordSizeForTypos' => [
+                'oneTypo' => 8,
+                'twoTypos' => 12,
+            ],
+        ]);
+
+        $engine->waitForTask($task['taskUid']);
+
+        $this->components->info('Disabling prefix search for product search...');
+
+        $task = $index->updatePrefixSearch('disabled');
+
+        $engine->waitForTask($task['taskUid']);
+
+        $this->components->info('Product search index tuned.');
+    }
+}
@@ -2,17 +2,22 @@

 namespace Modules\Core;

+use Lunar\Admin\Filament\Resources\OrderResource\Pages\ManageOrder;
+use Lunar\Admin\Filament\Resources\OrderResource\Pages\Components\OrderItemsTable;
 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;
@@ -21,8 +26,16 @@ 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\Order\Filament\Extensions\OrderItemsTableExtension;
+use Modules\Core\Order\Filament\Extensions\OrderRefundActionsExtension;
+use Modules\Core\Order\Filament\Extensions\OrderTransactionsExtension;
+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
 {
@@ -41,14 +54,20 @@ class CorePlugin implements Plugin
            ->resources([
                LanguageLineResource::class,
                CartResource::class,
+                PaymentMethodResource::class,
            ])
-            ->plugin(ShippingPlugin::make());
+            ->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, OrderRefundActionsExtension::class, OrderTransactionsExtension::class],
+            OrderItemsTable::class => OrderItemsTableExtension::class,
        ]);

        Product::macro('reviews', function (): HasMany {
@@ -62,9 +81,8 @@ class CorePlugin implements Plugin
            '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) {
@@ -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'),
            ]);
    }
@@ -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()
@@ -2,8 +2,17 @@

 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\Forms\Form;
 use Filament\Resources\Resource;
 use Filament\Tables;
 use Filament\Tables\Table;
@@ -15,29 +24,29 @@ class LanguageLineResource extends Resource
 {
    protected static ?string $model = LanguageLine::class;

-    protected static ?string $navigationIcon = 'heroicon-o-language';
+    protected static string | \BackedEnum | null $navigationIcon = 'heroicon-o-language';

-    protected static ?string $navigationGroup = 'Settings';
+    protected static string | \UnitEnum | null $navigationGroup = 'Settings';

    protected static ?string $modelLabel = 'Translation';

    protected static ?string $pluralModelLabel = 'Translations';

-    public static function form(Form $form): Form
+    public static function form(Schema $schema): Schema
    {
-        return $form->schema([
-            Forms\Components\TextInput::make('group')
+        return $schema->components([
+            TextInput::make('group')
                ->required()
                ->maxLength(255)
                ->default('storefront')
                ->helperText('Namespace for this label, e.g. "storefront" for e-shop UI text.'),

-            Forms\Components\TextInput::make('key')
+            TextInput::make('key')
                ->required()
                ->maxLength(255)
                ->helperText('Dot-notation key, e.g. "nav.cart".'),

-            Forms\Components\Fieldset::make('Translations')
+            Fieldset::make('Translations')
                ->schema(static::localeInputs()),
        ]);
    }
@@ -46,16 +55,16 @@ class LanguageLineResource extends Resource
    {
        return $table
            ->columns([
-                Tables\Columns\TextColumn::make('group')
+                TextColumn::make('group')
                    ->badge()
                    ->sortable(),
-                Tables\Columns\TextColumn::make('key')
+                TextColumn::make('key')
                    ->searchable()
                    ->sortable(),
                ...static::localeColumns(),
            ])
            ->filters([
-                Tables\Filters\SelectFilter::make('group')
+                SelectFilter::make('group')
                    ->options(fn () => LanguageLine::query()->distinct()->pluck('group', 'group')),
            ])
            ->defaultSort('key');
@@ -69,38 +78,38 @@ class LanguageLineResource extends Resource
    public static function getPages(): array
    {
        return [
-            'index' => Pages\ListLanguageLines::route('/'),
-            'create' => Pages\CreateLanguageLine::route('/create'),
-            'edit' => Pages\EditLanguageLine::route('/{record}/edit'),
+            'index' => ListLanguageLines::route('/'),
+            'create' => CreateLanguageLine::route('/create'),
+            'edit' => EditLanguageLine::route('/{record}/edit'),
        ];
    }

    /**
-     * @return array<Forms\Components\Textarea>
+     * @return array<Textarea>
     */
    private static function localeInputs(): array
    {
        return static::localeCodes()
-            ->map(fn (string $code) => Forms\Components\Textarea::make("text.{$code}")
+            ->map(fn (string $code) => Textarea::make("text.{$code}")
                ->label(strtoupper($code))
                ->rows(2))
            ->all();
    }

    /**
-     * @return array<Tables\Columns\TextColumn>
+     * @return array<TextColumn>
     */
    private static function localeColumns(): array
    {
        return static::localeCodes()
-            ->map(fn (string $code) => Tables\Columns\TextColumn::make("text.{$code}")
+            ->map(fn (string $code) => TextColumn::make("text.{$code}")
                ->label(strtoupper($code))
                ->limit(40)
                ->toggleable())
            ->all();
    }

-    private static function localeCodes(): \Illuminate\Support\Collection
+    private static function localeCodes(): Collection
    {
        return Language::query()->pluck('code');
    }
@@ -2,6 +2,7 @@

 namespace Modules\Core\Localization\Filament\Resources\LanguageLineResource\Pages;

+use Filament\Actions\DeleteAction;
 use Filament\Actions;
 use Filament\Actions\Action;
 use Filament\Resources\Pages\EditRecord;
@@ -17,7 +18,7 @@ class EditLanguageLine extends EditRecord
    protected function getHeaderActions(): array
    {
        return [
-            Actions\DeleteAction::make()
+            DeleteAction::make()
                ->action(function (LanguageLine $record) {
                    app(TranslationService::class)->delete($record);

@@ -2,6 +2,7 @@

 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;
@@ -13,7 +14,7 @@ class ListLanguageLines extends ListRecords
    protected function getHeaderActions(): array
    {
        return [
-            Actions\CreateAction::make(),
+            CreateAction::make(),
        ];
    }
 }
@@ -38,6 +38,7 @@ class StorefrontLabels
            'auth.login' => ['en' => 'Log In', 'el' => 'Σύνδεση'],
            'auth.logout' => ['en' => 'Log Out', 'el' => 'Αποσύνδεση'],
            'search.placeholder' => ['en' => 'Search products…', 'el' => 'Αναζήτηση προϊόντων…'],
+            'search.results_for' => ['en' => 'Search results for ', 'el' => 'Αποτελέσματα αναζήτησης για '],
            'customer_reviews' => [
                'en' => '{0} No customer reviews|{1} :count customer review|[2,*] :count customer reviews',
                'el' => '{0} Καμία αξιολόγηση πελάτη|{1} :count αξιολόγηση πελάτη|[2,*] :count αξιολογήσεις πελατών',
@@ -76,6 +77,9 @@ class StorefrontLabels
            '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' => 'Μόνο διαθέσιμα προϊόντα'],
@@ -2,6 +2,7 @@

 namespace Modules\Core\MigrateImport;

+use InvalidArgumentException;
 use Modules\Core\MigrateImport\JudgeMe\JudgeMeExportImporter;
 use Modules\Core\MigrateImport\Shopify\ShopifyExportImporter;

@@ -15,7 +16,7 @@ class ImporterFactory
            ['judgeme', 'export'] => new JudgeMeExportImporter,
            // ["woocommerce", "export"] => new WooCommerceExportImporter(),
            // ["woocommerce", "api"] => new WooCommerceApiImporter(),
-            default => throw new \InvalidArgumentException(
+            default => throw new InvalidArgumentException(
                "No importer available for source \"{$spec->source}\" with type \"{$spec->type}\".",
            ),
        };
@@ -2,6 +2,8 @@

 namespace Modules\Core\MigrateImport\JudgeMe;

+use RuntimeException;
+
 class JudgeMeCsvReader
 {
    /**
@@ -12,7 +14,7 @@ class JudgeMeCsvReader
        $handle = fopen($csvPath, 'r');

        if ($handle === false) {
-            throw new \RuntimeException("Could not open CSV file: {$csvPath}");
+            throw new RuntimeException("Could not open CSV file: {$csvPath}");
        }

        $headers = fgetcsv($handle);
@@ -2,6 +2,7 @@

 namespace Modules\Core\MigrateImport\JudgeMe;

+use Throwable;
 use Illuminate\Support\Carbon;
 use Illuminate\Support\Facades\Log;
 use Modules\Core\MigrateImport\Importer;
@@ -75,7 +76,7 @@ class JudgeMeExportImporter implements Importer
        foreach ($urls as $url) {
            try {
                $review->addMediaFromUrl($url)->toMediaCollection(ProductReview::IMAGES_COLLECTION);
-            } catch (\Throwable $e) {
+            } catch (Throwable $e) {
                Log::warning('JudgeMe import: failed to download review image', [
                    'review_id' => $review->id,
                    'url' => $url,
@@ -16,10 +16,16 @@ class ProductOptionResolver
        // the same option instead of creating a near-duplicate.
        $handle = Str::slug($name) ?: 'option';

+        // 'label' must be set even though nothing here reads it back — a null
+        // label crashes Lunar's own ProductOptionIndexer::toSearchableArray()
+        // (foreach (null as ...)) the moment this option gets reindexed, since
+        // it assumes every ProductOption always has one. Same value as 'name'
+        // is a reasonable default; Shopify's CSV has no separate "label" concept.
        return ProductOption::query()->firstOrCreate(
            ['handle' => $handle],
            [
                'name' => [DefaultLocale::code() => $name],
+                'label' => [DefaultLocale::code() => $name],
                'shared' => true,
            ],
        );
@@ -2,6 +2,8 @@

 namespace Modules\Core\MigrateImport\Shopify;

+use RuntimeException;
+
 class ShopifyCsvReader
 {
    /**
@@ -12,7 +14,7 @@ class ShopifyCsvReader
        $handle = fopen($csvPath, 'r');

        if ($handle === false) {
-            throw new \RuntimeException("Could not open CSV file: {$csvPath}");
+            throw new RuntimeException("Could not open CSV file: {$csvPath}");
        }

        $headers = fgetcsv($handle);
@@ -2,6 +2,8 @@

 namespace Modules\Core\MigrateImport\Shopify;

+use Lunar\Models\TaxClass;
+use Lunar\Models\ProductOption;
 use Illuminate\Support\Facades\Log;
 use Lunar\Models\Collection;
 use Lunar\Models\CollectionGroup;
@@ -23,6 +25,7 @@ use Modules\Core\MigrateImport\Shopify\Resolvers\ProductOptionResolver;
 use Modules\Core\MigrateImport\Shopify\Resolvers\ProductTypeResolver;
 use Modules\Core\MigrateImport\Shopify\Resolvers\TagResolver;
 use Modules\Core\MigrateImport\Shopify\Resolvers\TaxClassResolver;
+use Spatie\MediaLibrary\MediaCollections\Models\Media;

 class ShopifyExportImporter implements Importer
 {
@@ -111,7 +114,7 @@ class ShopifyExportImporter implements Importer
        $options = $this->attachOptions($product, $row);

        foreach ($group->variantRows as $index => $variantRow) {
-            $this->importVariant($product, $group->handle, $index, $variantRow, $taxClass, $currency, $options);
+            $this->importVariant($product, $group->handle, $index, $variantRow, $taxClass, $currency, $options, $imagesPath);
        }

        foreach ($group->imageRows as $index => $imageRow) {
@@ -120,7 +123,7 @@ class ShopifyExportImporter implements Importer
    }

    /**
-     * @return array<int, \Lunar\Models\ProductOption>
+     * @return array<int, ProductOption>
     */
    private function attachOptions(Product $product, array $row): array
    {
@@ -146,9 +149,10 @@ class ShopifyExportImporter implements Importer
        string $handle,
        int $index,
        array $row,
-        \Lunar\Models\TaxClass $taxClass,
+        TaxClass $taxClass,
        Currency $currency,
        array $options,
+        string $imagesPath,
    ): void {
        $externalId = "{$handle}#{$index}";
        $existing = ImportMapping::resolve(self::SOURCE, 'variant', $externalId);
@@ -180,6 +184,26 @@ class ShopifyExportImporter implements Importer
            : null;

        $this->priceResolver->resolve($variant, $currency, $price, $comparePrice);
+
+        // Shopify's own "Variant Image" column — the one image a variant picker
+        // actually swaps to when that variant is selected — distinct from the
+        // product's full gallery (imageRows below). Often the same file as one
+        // of the product's own image rows, sometimes not yet imported at all
+        // (e.g. a variant-only image never listed as its own image row) — either
+        // way resolveOrImportImage() handles both via the same Image Src dedup
+        // key, so whichever of importVariant()/importImage() runs first for a
+        // given src does the actual import.
+        $variantImageSrc = trim((string) ($row['Variant Image'] ?? ''));
+
+        if ($variantImageSrc !== '') {
+            $media = $this->resolveOrImportImage($product, $handle, $variantImageSrc, 1, $imagesPath);
+
+            if ($media) {
+                $variant->images()->syncWithoutDetaching([
+                    $media->id => ['primary' => true, 'position' => 1],
+                ]);
+            }
+        }
    }

    private function importImage(
@@ -189,29 +213,54 @@ class ShopifyExportImporter implements Importer
        array $row,
        string $imagesPath,
    ): void {
-        $externalId = $row['Image Src'] ?: "{$handle}#image-{$index}";
        $position = (int) ($row['Image Position'] ?? $index + 1);

-        if (ImportMapping::resolve(self::SOURCE, 'image', $externalId)) {
-            return;
+        $this->resolveOrImportImage($product, $handle, $row['Image Src'], $position, $imagesPath);
+    }
+
+    /**
+     * Resolves the Media already imported for $imageSrc (recorded under
+     * source_type 'image', keyed by Image Src — the same URL Shopify repeats
+     * across a product's own image rows and any variant's "Variant Image"
+     * column), importing it via AssetResolver if this is the first time this
+     * src has been seen. Shared by importImage() (product gallery) and
+     * importVariant() (variant-specific image) so the same physical file is
+     * never uploaded to Spatie MediaLibrary twice just because Shopify's flat
+     * CSV format repeats the URL on multiple rows.
+     */
+    private function resolveOrImportImage(
+        Product $product,
+        string $handle,
+        string $imageSrc,
+        int $position,
+        string $imagesPath,
+    ): ?Media {
+        $externalId = $imageSrc ?: "{$handle}#image-{$position}";
+
+        $existing = ImportMapping::resolve(self::SOURCE, 'image', $externalId);
+
+        if ($existing instanceof Media) {
+            return $existing;
        }

-        $localFile = $this->findLocalFile($imagesPath, $row['Image Src']);
+        $localFile = $this->findLocalFile($imagesPath, $imageSrc);

        if ($localFile === null) {
            Log::warning('Shopify import: image file not found', [
                'handle' => $handle,
-                'image_src' => $row['Image Src'],
+                'image_src' => $imageSrc,
            ]);

-            return;
+            return null;
        }

        $media = $this->assetResolver->resolve($product, $localFile, $position);

        if ($media) {
-            ImportMapping::record(self::SOURCE, 'image', $externalId, $product);
+            ImportMapping::record(self::SOURCE, 'image', $externalId, $media);
        }
+
+        return $media;
    }

    private function findLocalFile(string $imagesPath, string $imageSrc): ?string
@@ -2,6 +2,7 @@

 namespace Modules\Core\Notification;

+use Throwable;
 use Illuminate\Support\Facades\Event;

 class NotificationRegistry
@@ -44,7 +45,7 @@ class NotificationRegistry
                        $notification->delay($event->delaySeconds);
                    }
                    $notification->notifiable()->notify($notification);
-                } catch (\Throwable $e) {
+                } catch (Throwable $e) {
                    report($e);
                }
            });
@@ -2,6 +2,9 @@

 namespace Modules\Core\Option;

+use InvalidArgumentException;
+use Exception;
+use RuntimeException;
 use Traversable;

 /**
@@ -39,7 +42,7 @@ final class LazyOption extends Option
    public function __construct($callback, array $arguments = [])
    {
        if (!is_callable($callback)) {
-            throw new \InvalidArgumentException("Invalid callback given");
+            throw new InvalidArgumentException("Invalid callback given");
        }

        $this->callback = $callback;
@@ -71,7 +74,7 @@ final class LazyOption extends Option
        return $this->option()->getOrCall($callable);
    }

-    public function getOrThrow(\Exception $ex)
+    public function getOrThrow(Exception $ex)
    {
        return $this->option()->getOrThrow($ex);
    }
@@ -146,7 +149,7 @@ final class LazyOption extends Option
            if ($option instanceof Option) {
                $this->option = $option;
            } else {
-                throw new \RuntimeException(
+                throw new RuntimeException(
                    sprintf("Expected instance of %s", Option::class),
                );
            }
@@ -2,6 +2,8 @@

 namespace Modules\Core\Option;

+use RuntimeException;
+use Exception;
 use EmptyIterator;

 /**
@@ -24,7 +26,7 @@ final class None extends Option

    public function get()
    {
-        throw new \RuntimeException("None has no value.");
+        throw new RuntimeException("None has no value.");
    }

    public function getOrCall($callable)
@@ -37,7 +39,7 @@ final class None extends Option
        return $default;
    }

-    public function getOrThrow(\Exception $ex)
+    public function getOrThrow(Exception $ex)
    {
        throw $ex;
    }
@@ -2,6 +2,7 @@

 namespace Modules\Core\Option;

+use Exception;
 use ArrayAccess;
 use IteratorAggregate;

@@ -164,7 +165,7 @@ abstract class Option implements IteratorAggregate
    abstract public function getOrCall($callable);

    /** @return T */
-    abstract public function getOrThrow(\Exception $ex);
+    abstract public function getOrThrow(Exception $ex);

    abstract public function isEmpty(): bool;

@@ -2,6 +2,7 @@

 namespace Modules\Core\Option;

+use RuntimeException;
 use ArrayIterator;
 use Exception;

@@ -56,7 +57,7 @@ final class Some extends Option
        return $this->value;
    }

-    public function getOrThrow(\Exception $ex)
+    public function getOrThrow(Exception $ex)
    {
        return $this->value;
    }
@@ -88,7 +89,7 @@ final class Some extends Option
        /** @var mixed */
        $rs = $callable($this->value);
        if (!$rs instanceof Option) {
-            throw new \RuntimeException(
+            throw new RuntimeException(
                "Callables passed to flatMap() must return an Option. Maybe you should use map() instead?",
            );
        }
@@ -0,0 +1,15 @@
+<?php
+
+namespace Modules\Core\Order\Enums;
+
+/**
+ * Derived from Shipment/ShipmentInfo — no equivalent existed anywhere in
+ * Lunar or this codebase before OrderStatus::fulfillment().
+ */
+enum FulfillmentStatus: string
+{
+    case Unfulfilled = 'unfulfilled';
+    case Shipped = 'shipped';
+    case PartiallyShipped = 'partially-shipped';
+    case Delivered = 'delivered';
+}
@@ -0,0 +1,17 @@
+<?php
+
+namespace Modules\Core\Order\Enums;
+
+/**
+ * Same states/logic as Lunar's own ManageOrder::paymentStatus(), which
+ * only exists as a Filament-page Livewire #[Computed] method — this is
+ * that same derivation, reusable from anywhere via Order::paymentStatus().
+ */
+enum PaymentStatus: string
+{
+    case Offline = 'offline';
+    case Uncaptured = 'uncaptured';
+    case Captured = 'captured';
+    case PartialRefund = 'partial-refund';
+    case Refunded = 'refunded';
+}
@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Core\Order\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Order;
+use Lunar\Models\Transaction;
+
+/**
+ * Dispatched by TransactionObserver::saved() when a Transaction's type
+ * changes to 'capture' (from 'intent') and succeeds. Unlike refunds,
+ * Lunar's Stripe driver (StoreCharges) reuses the same Transaction row
+ * across intent -> capture rather than creating a new one, so this can't
+ * key off `wasRecentlyCreated` the way OrderRefunded does.
+ */
+class OrderCaptured
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Order $order,
+        public readonly Transaction $transaction,
+    ) {}
+}
@@ -0,0 +1,24 @@
+<?php
+
+namespace Modules\Core\Order\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Order;
+use Modules\Core\Shipping\Models\ShipmentInfo;
+
+/**
+ * Dispatched by Order's DeriveOrderDeliveredFromShipment listener, which
+ * reacts to Shipping's ShipmentStatusUpdatedByCarrier — delivery is a
+ * tracking checkpoint, not a manual status write, so it never goes through
+ * OrderStatusUpdated. Order.status itself is left untouched here; this is
+ * only the signal for delivery notifications and similar reactions.
+ */
+class OrderDelivered
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Order $order,
+        public readonly ShipmentInfo $shipmentInfo,
+    ) {}
+}
@@ -0,0 +1,25 @@
+<?php
+
+namespace Modules\Core\Order\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Lunar\Models\Order;
+use Lunar\Models\Transaction;
+
+/**
+ * Dispatched by TransactionObserver::saved() whenever a successful
+ * type=refund Transaction row is written — every payment driver (Lunar's
+ * own StripePaymentType::refund(), or a future boboko-owned driver for a
+ * provider Lunar doesn't ship) creates a new row for each refund, so
+ * `created` alone (filtered to type+success) is enough here, unlike
+ * captures which can reuse an existing row.
+ */
+class OrderRefunded
+{
+    use Dispatchable;
+
+    public function __construct(
+        public readonly Order $order,
+        public readonly Transaction $transaction,
+    ) {}
+}
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
arvanitakis	4d0e326cb9	Bump version to 0.16.1	2026-09-09 23:25:22 +03:00
arvanitakis	d4f9766940	Fix: Correcting spaceing on login form	2026-09-09 23:22:13 +03:00
arvanitakis	359e1e262e	Bump Version to 0.16.0	2026-09-09 01:19:31 +03:00
arvanitakis	fb684dc97b	Feat: Adding Concent Updates	2026-09-09 01:12:21 +03:00
arvanitakis	9c95c0bccb	Bump Version to 0.15.0	2026-09-09 00:48:52 +03:00
arvanitakis	73bfc748b4	Feature: Moving Payment Methods to DB, adding fees, Transaction Updates, Refund Updates, General Updates to Payments	2026-09-09 00:48:09 +03:00
arvanitakis	4ff9bdacc3	Bump version to 0.14.0	2026-09-04 13:06:26 +03:00
arvanitakis	55832d9549	Feat: Adding search results for translation	2026-09-04 13:06:07 +03:00
arvanitakis	7b46a83e5e	Feat: Product Search Service Restructure	2026-09-04 13:03:38 +03:00
arvanitakis	e9aa08a338	Bump version to 0.13.1	2026-09-03 18:28:22 +03:00
arvanitakis	0676a1f5c7	Feat: Recording Payment Transactions	2026-09-03 18:26:48 +03:00
arvanitakis	8e8ec17d09	Bump version to 0.13.0	2026-09-03 17:44:22 +03:00
arvanitakis	e6f1ca179a	Fix: Fixing various bugs occured on payment lifecycle	2026-09-03 17:42:30 +03:00
arvanitakis	79e525d53f	Fix: Stripe Intents Table is a Lunar Table, so needs a prefix. This is covered by the Lunar\Base\Migration	2026-09-03 17:31:39 +03:00
arvanitakis	456943dc74	Feature: Payment resolver, Payment Provider, Completing Stripe Webhooks, Wiring Payments to checkout service	2026-09-03 17:27:34 +03:00
arvanitakis	35c3334690	Feat: Payment Restructuring to be fully event-driven	2026-09-03 17:00:24 +03:00
arvanitakis	a987a2d57c	Feature: Abstraction on Payments based on their operations	2026-09-03 16:01:33 +03:00
arvanitakis	0fa2188146	Feat: Refactoring Shipping DataTransferObjects to DTOs namespace	2026-09-03 15:58:51 +03:00
arvanitakis	a1301d4b46	Merge branch 'master' into Payments	2026-09-03 13:34:32 +03:00
arvanitakis	215f43f3ef	Feat: Adding tags to product filters	2026-09-03 13:34:04 +03:00
arvanitakis	c439299144	Bump version to 0.12.1	2026-09-03 13:23:50 +03:00
arvanitakis	6963515971	Fix: Small update to label parsing	2026-09-03 13:22:09 +03:00
arvanitakis	f43f72f633	Feat: Updates to Product Indexer, Shopify Importer, Adding cascade delete on reviews	2026-09-03 12:26:00 +03:00
arvanitakis	448da869a9	Bump version to 0.12.0	2026-09-03 11:44:36 +03:00
arvanitakis	1287b513cd	Feat: Updating Product Service with new Methods, DTOs for ListingResult And Slider Bounds	2026-09-03 11:44:23 +03:00
arvanitakis	b2919f1f4b	Feature: Product Search Service Updates	2026-09-03 11:04:19 +03:00
arvanitakis	8cb54e065e	Feat: Updates to Payments, Checkout Services, Payment Events	2026-09-02 16:14:52 +03:00
arvanitakis	3497553b41	Feature: Order Service Provider, Order Events Observers	2026-09-01 14:04:12 +03:00
arvanitakis	29e77a973b	Feat: Orders Feature Survey	2026-09-01 13:34:37 +03:00
arvanitakis	026ab5bc2d	BUmp version to 0.11.1	2026-09-01 13:04:54 +03:00
arvanitakis	483c0ce00f	Fix: Recommendations are an eloquent collection, not an Generic Collection	2026-09-01 13:03:39 +03:00
arvanitakis	ce405d20e6	Bump Version to 0.11.0	2026-09-01 12:08:47 +03:00
arvanitakis	0f07751559	Feature: Recommendation Service This commit introduces a RecommendationService that is used when indexing products. The service is utilizing a recommendation rules interface, so many rules can be created and applied during indexing the products	2026-09-01 12:06:29 +03:00
arvanitakis	53d8a5aefe	Bump Version to 0.10.1	2026-09-01 12:04:06 +03:00
arvanitakis	380e860386	Feat: Adding Translations to the Seeder	2026-09-01 10:52:56 +03:00
arvanitakis	d680200ab1	Bump Version to 0.10.0	2026-08-31 14:18:51 +03:00
arvanitakis	9529036585	Feat: Updating PaymentDrivers and CheckoutService to handle payment methods	2026-08-31 14:12:21 +03:00
arvanitakis	2db1e1331f	Feat: Creating PaymentMethods, Setting Fees, Availabilities	2026-08-31 13:54:20 +03:00
arvanitakis	d873cb4931	Feat: Upgrading Lunar to 1.5	2026-08-31 13:16:13 +03:00
arvanitakis	661e8b9a96	Feat: Adding Payment Drivers, configuring stripe	2026-08-31 12:50:29 +03:00
arvanitakis	637da37b9b	Merge branch 'master' into Payment-Methods	2026-08-29 14:17:48 +03:00
arvanitakis	be0c037c62	Bump version to 0.9.0	2026-08-29 13:41:17 +03:00
arvanitakis	f85fb51ecd	Feature: Adding Caches and Fallbacks to Live Pricing Requests	2026-08-29 10:31:58 +03:00
arvanitakis	6671c5e9d1	Feature: Adding Checkout Services and Events	2026-08-29 01:14:58 +03:00
arvanitakis	ca36c31cab	Hotfix: Correcting Wrong Position on Checkout, Correcting Cart Display Pages	2026-08-29 00:27:20 +03:00
arvanitakis	c6c44db742	Feature: Sweeping features of most known e-commerce shops, creating artifacts for the research	2026-08-28 13:19:29 +03:00
arvanitakis	7b63f43695	Merge branch 'Shipping-Carriers' into Checkout	2026-08-28 13:17:58 +03:00
arvanitakis	9f30a7324e	Feature: Shipment Updates to handle COD	2026-07-19 18:27:24 +03:00
arvanitakis	435a4dd290	Feat: Adding Shippment Tracking	2026-07-19 17:41:09 +03:00
arvanitakis	808c769595	Add cash-on-delivery payment type with cart fee pipeline	2026-07-19 03:35:16 +03:00
arvanitakis	d34e450526	Fix: Move carrier live-pricing choice onto ShippingMethod.charge_by Reverts the earlier per-rate pricing_mode column in favor of extending Lunar's existing charge_by field (cart_total/weight) with a third "live" option, gated by a SupportsLivePricing capability check on the driver. Adds a shared ResolvesFixedPricing trait so any carrier driver can fall back to Lunar's normal price-break resolution, matching the vendor ShipBy driver's own charge_by handling instead of introducing a separate mechanism. Also fixes an incorrect Get() path in the admin form that silently hid the new "live" option.	2026-07-19 02:24:10 +03:00
arvanitakis	4acabe4185	Feature: Wire up carrier-agnostic shipping admin UI Registers ShippingServiceProvider (carrier config, driver/fulfillment bindings, Rates page override) and wires the shipping admin surface into CorePlugin: dynamic carrier dropdown on Shipping Method create/edit, a "Create Shipment" order action resolved generically by carrier, and a Pickup Manifests page for carriers that support manifest batching.	2026-07-19 00:52:01 +03:00
arvanitakis	37c2e1194c	Feature: Add Box Now locker delivery integration Box Now rate driver (fixed pricing only — no live pricing API) and fulfillment service (delivery request creation, label printing, cancellation). Unlike ACS, Box Now books courier pickup automatically on delivery request creation, so no manifest/pickup-list step is implemented. Storefront locker selection is not yet built; createShipment() expects the chosen locker's locationId to be supplied by the caller.	2026-07-19 00:51:23 +03:00
arvanitakis	89255687a1	Feature: Add ACS courier integration ACS rate driver (live price quotes via ACS_Price_Calculation, cached postcode-to-station lookups) and fulfillment service (voucher creation, label printing, end-of-day pickup manifest). Adds a per-rate pricing_mode column so admins can choose live API pricing vs. a fixed price on ACS-driven shipping rates, surfaced via a custom Rates page.	2026-07-19 00:50:51 +03:00
arvanitakis	3599329b57	Feature: Add ManifestResult DTO for carrier manifest batching Completes the carrier-agnostic shipping abstraction (CarrierFulfillmentInterface, SupportsManifestBatching, Shipment model) with the result type SupportsManifestBatching::issueManifest() returns.	2026-07-19 00:50:15 +03:00
arvanitakis	9618d19cfa	Feature: Creating Migration For Adding Pricing Mode to Shipping Rates	2026-07-19 00:42:13 +03:00
arvanitakis	08135c4c8f	Feature: Creating Shipping Carrier Contracts	2026-07-16 17:14:41 +03:00
arvanitakis	e18b2fa44c	Feature: Creating Shipment migration and model	2026-07-16 17:14:23 +03:00