@mercurjs/docs 2.2.0-canary.40

package/content/resources/customization/extending-panels.mdx

@@ -0,0 +1,309 @@
+---
+title: "Extending Panels"
+description: "Add pages, customize navigation, branding, and replace components in the admin and vendor panels."
+---
+
+Both the admin panel and vendor portal use the same SDK (`@mercurjs/dashboard-sdk`). Customization is file-based and convention-driven — you add pages by creating files, configure navigation through exports, and override components through config.
+
+<Info>
+  **Mercur does not use Medusa's admin customization.** If you're coming from Medusa, forget `defineWidgetConfig`, `defineRouteConfig`, and widget injection zones — none of them exist here. Mercur ships its own admin **and** vendor panels, built on a shared extension framework with three mechanisms: **drop-in routes** (file-based pages that can also *replace* built-in pages), **compound-component re-composition** (every built-in page exposes its parts as slots), and **named layout overrides** (sidebar, topbar, store setup). The trade: instead of injecting widgets into fixed zones around a page Medusa controls, you compose the actual page — which is what makes a two-panel marketplace customizable without forking.
+</Info>
+
+## Choosing your extension mechanism
+
+Junior-friendly rule of thumb: **adding something new? Drop in a route. Changing something that exists? Re-compose it. Changing the frame around every page? Override a component. Sharing it across projects? Make it a block.**
+
+| You want to… | Use | Why it's the right tool |
+|--------------|-----|------------------------|
+| Add a new screen or feature | A drop-in `page.tsx` route | New URL, auto-registered, sidebar entry via the `config` export — see [Add a page](#add-a-page) |
+| Change part of an existing page | A drop-in route **at the same path**, re-composing the page's compound slots | Your route replaces the built-in one; untouched slots keep all their behavior — see the [re-compose tutorial](/rc/resources/tutorials/recompose-a-page) |
+| Change global chrome (sidebar, topbar, store setup) | A component override in the plugin config | One component, applied everywhere its slot renders — see [Replace components](#replace-components) |
+| Reuse a feature across projects | A [block](/rc/learn/blocks) | Ships API + admin + vendor files installable with `mercurjs add` — see the [build-a-block tutorial](/rc/resources/tutorials/build-a-block) |
+
+<Note>
+  The middle row is the one Medusa developers miss most. Because built-in pages are exported as compound components (e.g. `ProductListPage` from `@mercurjs/vendor/pages` with `Header`, `HeaderActions`, `DataTable` slots), "customize the products page" doesn't mean forking it — it means rendering it with your own composition and reusing the slots you don't change.
+</Note>
+
+## Set up
+
+All configuration lives in the panel app's Vite config — there is no separate config file.
+
+<Steps>
+  <Step title="Register the plugin">
+    Add `mercurDashboardPlugin` to the panel app's `vite.config.ts`. The only required option is `medusaConfigPath` — the plugin reads panel paths and ports from your API's Medusa config:
+
+    ```typescript vite.config.ts
+    import { defineConfig } from 'vite'
+    import react from '@vitejs/plugin-react'
+    import { mercurDashboardPlugin } from '@mercurjs/dashboard-sdk'
+
+    export default defineConfig({
+      plugins: [
+        react(),
+        mercurDashboardPlugin({
+          medusaConfigPath: '../../packages/api/medusa-config.ts',
+          name: 'My Marketplace',
+          logo: 'https://example.com/logo.svg',
+        }),
+      ],
+    })
+    ```
+
+    Projects created with `create-mercur-app` ship with this already wired for both panels.
+  </Step>
+  <Step title="Pass environment values explicitly">
+    The plugin doesn't read `.env` itself — load environment variables in `vite.config.ts` (e.g. with Vite's `loadEnv`) and pass them into the plugin options, as the starter template does with `backendUrl`.
+  </Step>
+  <Step title="Restart after config changes">
+    Options are applied at build time through virtual modules. Adding or removing routes hot-reloads automatically, but changes to the plugin options require a dev-server restart.
+  </Step>
+</Steps>
+
+### Configuration options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `medusaConfigPath` | `string` | **Required.** Path to your API's `medusa-config.ts`, relative to the panel project root |
+| `backendUrl` | `string` | Medusa backend URL (default: `http://localhost:9000`) |
+| `vendorUrl` | `string` | Absolute vendor portal URL including its path prefix |
+| `name` | `string` | Application name shown in the sidebar |
+| `logo` | `string` | URL to a logo image |
+| `components` | `object` | Component overrides (see [Replace components](#replace-components)) |
+| `i18n` | `object` | Internationalization settings (`{ defaultLanguage }`) |
+| `enableSellerRegistration` | `boolean` | Enable the public seller registration flow (vendor portal) |
+| `imageLimit` | `number` | Max upload size for images in bytes (default: 2 MB) |
+
+## Add a page
+
+<Steps>
+  <Step title="Create the route file">
+    Create a `page.tsx` inside `src/routes/` and export a default React component. The route is determined by the file path:
+
+    ```tsx src/routes/reviews/page.tsx
+    import { Star } from "@medusajs/icons"
+    import type { RouteConfig } from "@mercurjs/dashboard-sdk"
+
+    export const config: RouteConfig = {
+      label: "Reviews",
+      icon: Star,
+      rank: 10,
+    }
+
+    export default function ReviewsPage() {
+      return <div>Reviews</div>
+    }
+    ```
+  </Step>
+  <Step title="Add the config export for navigation">
+    A sidebar item is generated only when the page exports a `config` with a `label`. Pages without one are still routed — they just don't appear in the menu.
+
+    | Property | Type | Description |
+    |----------|------|-------------|
+    | `label` | `string` | **Required.** Text shown in the sidebar menu |
+    | `icon` | `ComponentType` | Icon component (e.g. from `@medusajs/icons`) |
+    | `rank` | `number` | Sort order — lower numbers appear first |
+    | `nested` | `string` | Parent path for nested menu items |
+    | `translationNs` | `string` | i18n namespace for the label |
+    | `public` | `boolean` | If `true`, the route is accessible without authentication |
+
+    Route files may also export a `loader` (React Router data loader) and `handle` (route metadata) alongside the default component.
+  </Step>
+  <Step title="Open it in the running panel">
+    Start the dev server — the SDK picks the file up automatically. This example creates a `/reviews` route with a "Reviews" sidebar item. No route registration, no configuration file.
+  </Step>
+</Steps>
+
+<Info>
+  **Matching paths replace, new paths append.** If your route's path matches a built-in page (e.g. `src/routes/products/page.tsx` → `/products`), your page **replaces** the built-in one — that's the override mechanism, no registration needed. Any other path is added alongside the built-in routes. Delete the file and the built-in page returns.
+</Info>
+
+### Routing conventions
+
+File paths map to URL routes automatically:
+
+| File path | Route | Description |
+|-----------|-------|-------------|
+| `src/routes/page.tsx` | `/` | Root page |
+| `src/routes/reviews/page.tsx` | `/reviews` | Static segment |
+| `src/routes/reviews/[id]/page.tsx` | `/reviews/:id` | Dynamic segment |
+| `src/routes/reviews/[[id]]/page.tsx` | `/reviews/:id?` | Optional dynamic segment |
+| `src/routes/search/[*]/page.tsx` | `/search/*` | Catch-all |
+| `src/routes/(settings)/page.tsx` | Route grouping | Groups routes without adding a URL segment |
+| `src/routes/dashboard/@sidebar/page.tsx` | Parallel route | Renders alongside parent |
+
+## Navigation
+
+Sidebar items are generated from pages that export a `config` with a `label`.
+
+### Ordering
+
+Use `rank` to control the order. Lower values appear higher:
+
+```tsx
+// src/routes/orders/page.tsx
+export const config: RouteConfig = {
+  label: "Orders",
+  icon: ShoppingCart,
+  rank: 1,
+}
+
+// src/routes/products/page.tsx
+export const config: RouteConfig = {
+  label: "Products",
+  icon: Tag,
+  rank: 2,
+}
+```
+
+### Nested menus
+
+Use `nested` to group pages under a parent:
+
+```tsx src/routes/settings/shipping/page.tsx
+export const config: RouteConfig = {
+  label: "Shipping",
+  nested: "/settings",
+}
+```
+
+This places "Shipping" as a child item under `/settings` in the sidebar.
+
+## Branding
+
+Set `name` and `logo` in the plugin options to customize the sidebar header:
+
+```typescript vite.config.ts
+mercurDashboardPlugin({
+  medusaConfigPath: '../../packages/api/medusa-config.ts',
+  name: 'WeTest',
+  logo: 'https://ui-avatars.com/api/?name=WeTest&background=18181B&color=fff&size=200&bold=true&format=svg',
+})
+```
+
+## Replace components
+
+<Steps>
+  <Step title="Write the replacement">
+    Create the component anywhere under `src/`. It must have a default export:
+
+    ```tsx src/components/custom-topbar-actions.tsx
+    export default function CustomTopbarActions() {
+      return (
+        <div>
+          <button>Help</button>
+          <button>Notifications</button>
+        </div>
+      )
+    }
+    ```
+  </Step>
+  <Step title="Point the config at it">
+    Register it in the `components` option. Paths are relative to `src/`:
+
+    ```typescript vite.config.ts
+    mercurDashboardPlugin({
+      medusaConfigPath: '../../packages/api/medusa-config.ts',
+      name: 'My Marketplace',
+      components: {
+        MainSidebar: 'components/custom-sidebar',
+        SettingsSidebar: 'components/custom-settings-sidebar',
+        TopbarActions: 'components/custom-topbar-actions',
+      },
+    })
+    ```
+  </Step>
+  <Step title="Restart and verify">
+    Restart the dev server — your component now renders everywhere its slot appears. Remove the entry and restart to get the built-in back; the originals are never modified.
+  </Step>
+</Steps>
+
+| Component | Description |
+|-----------|-------------|
+| `MainSidebar` | Primary navigation sidebar |
+| `SettingsSidebar` | Settings section sidebar |
+| `TopbarActions` | Action buttons in the top bar |
+| `StoreSetup` | Store setup screen for new sellers (vendor portal) |
+
+<Warning>
+  These four slots are the complete list — there is no generic "replace any component" registry. If what you want to change isn't one of them, it's a page concern: [re-compose the page](/rc/resources/tutorials/recompose-a-page) instead.
+</Warning>
+
+## Internationalization
+
+<Steps>
+  <Step title="Create translation resources">
+    ```typescript src/i18n/index.ts
+    export default {
+      en: {
+        reviews: {
+          title: "Reviews",
+          description: "Manage product reviews",
+        },
+      },
+      de: {
+        reviews: {
+          title: "Bewertungen",
+          description: "Produktbewertungen verwalten",
+        },
+      },
+    }
+    ```
+  </Step>
+  <Step title="Reference the namespace in your page config">
+    ```tsx src/routes/reviews/page.tsx
+    export const config: RouteConfig = {
+      label: "reviews.title",
+      icon: Star,
+      translationNs: "reviews",
+    }
+    ```
+  </Step>
+  <Step title="Set the default language">
+    ```typescript vite.config.ts
+    mercurDashboardPlugin({
+      medusaConfigPath: '../../packages/api/medusa-config.ts',
+      name: 'My Marketplace',
+      i18n: {
+        defaultLanguage: 'en',
+      },
+    })
+    ```
+  </Step>
+</Steps>
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Can I use Medusa's defineWidgetConfig or widget zones?">
+    No. The Mercur panels don't load Medusa's admin extension system — there are no widget zones to inject into. The equivalent workflows are: drop-in routes for new pages, [compound-component re-composition](/rc/resources/tutorials/recompose-a-page) for changing existing pages, and the four `components` overrides for global chrome. Backend customization (workflows, modules, subscribers) still follows standard Medusa conventions.
+  </Accordion>
+  <Accordion title="How do I change just one part of a built-in page?">
+    Import the page from the `/pages` subpath (`@mercurjs/vendor/pages` or `@mercurjs/admin/pages`), drop a route at the same path, and re-compose its slots — keep the slots you don't change and they retain all their behavior (data fetching, filters, pagination). The [re-compose tutorial](/rc/resources/tutorials/recompose-a-page) walks through a real example.
+  </Accordion>
+  <Accordion title="Why doesn't my page show up in the sidebar?">
+    A sidebar item is only generated when the route file exports a `config` object with a `label`. Also check that the file is named exactly `page.tsx` (or `.ts`/`.jsx`/`.js`) under `src/routes/` and has a **default** export — files without one are skipped entirely.
+  </Accordion>
+  <Accordion title="Is there a mercur.config.ts file?">
+    No — all panel configuration is passed inline to `mercurDashboardPlugin()` in `vite.config.ts`. If you've seen references to a separate config file, they're outdated.
+  </Accordion>
+  <Accordion title="Does this apply to both the admin panel and the vendor portal?">
+    Yes — both panels use the same SDK and the same conventions. The differences are which built-in pages exist (`@mercurjs/admin/pages` vs `@mercurjs/vendor/pages`) and a few vendor-only options like `StoreSetup` and `enableSellerRegistration`.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Add a custom panel page" href="/rc/resources/tutorials/custom-panel-page">
+    Hands-on: your first drop-in route, end to end.
+  </Card>
+  <Card title="Re-compose a built-in page" href="/rc/resources/tutorials/recompose-a-page">
+    Hands-on: override the vendor products page while keeping its table.
+  </Card>
+  <Card title="Replace panel components" href="/rc/resources/tutorials/replace-panel-components">
+    Hands-on: swap the topbar actions and sidebar.
+  </Card>
+  <Card title="Build your own block" href="/rc/resources/tutorials/build-a-block">
+    Package your customization and share it across projects.
+  </Card>
+</CardGroup>

package/content/resources/deployment/medusa-cloud.mdx

@@ -0,0 +1,167 @@
+---
+title: "Medusa Cloud deployment"
+description: "Deploy Mercur — backend, admin panel, and vendor panel — on Medusa Cloud."
+---
+
+## Introduction
+
+[Medusa Cloud](https://cloud.medusajs.com) is a dedicated hosting service for Medusa-based applications. It automatically detects changes on your repository, pulls and builds the code, and provisions a database, Redis, and file storage.
+
+Head to the [Medusa Cloud signup page](https://cloud.medusajs.com/signup) to get started. After registration is complete and your account is active, authorize the Medusa Cloud GitHub app in your organization or personal account.
+
+<Info>
+  A single Medusa Cloud deployment serves everything: the backend API, the
+  **admin panel** at `/dashboard`, and the **vendor panel** at `/seller`. The
+  panels are built together with the backend and served from the same origin —
+  no separate hosting is needed.
+</Info>
+
+## How it works
+
+The `basic` template wires this up out of the box:
+
+- During `build`, the API package builds both panels and bundles their production
+  output into the Medusa build artifact (`.medusa/server/dashboards/<name>`), so hosts
+  that deploy only the artifact — like Medusa Cloud — carry the panels with it
+  (`packages/api/scripts/bundle-dashboards.mjs`).
+- At runtime, the `admin-ui` and `vendor-ui` modules detect the bundled builds and
+  serve them statically at their configured paths (`/dashboard`, `/seller`).
+- The panels bake the backend URL at build time from the `MERCUR_BACKEND_URL`
+  environment variable. Because they are served from the backend's own origin, all
+  API calls are same-origin — no cross-site cookie or CORS gymnastics.
+
+Medusa Cloud builds the monorepo with `NODE_ENV=production`. In that mode the build
+**fails fast** when `MERCUR_BACKEND_URL` is missing instead of shipping panels that
+silently point at `http://localhost:9000` — so make sure to set it as described below.
+
+## Prerequisites
+
+- A Mercur project created with [`@mercurjs/cli`](/rc/learn/installation) and pushed to a GitHub repository
+- A [Medusa Cloud](https://cloud.medusajs.com) account with the GitHub app authorized
+- API keys for any third-party services you plan to use (Stripe, Resend, Algolia, etc.)
+
+## Setup
+
+<Steps>
+  <Step title="Import your repository">
+    From the Medusa Cloud dashboard, choose **Import your existing repository into the Cloud** (the Mercur project lives in your own GitHub repo, not in the bundled DTC/B2B starters).
+    ![Medusa Cloud welcome screen](/images/v2/cloud_1.png)
+  </Step>
+  <Step title="Pick the repository">
+    On the **Repository** step, make sure the Medusa Cloud GitHub app is installed, pick your Mercur repository from the list, and click **Continue**.
+    ![Choose repository](/images/v2/cloud_2.png)
+  </Step>
+  <Step title="Configure the project">
+    On the **Configure** step, fill in:
+
+    - **Project name** and **Custom subdomain**. The subdomain determines your backend URL (`https://<subdomain>.medusajs.app`) — you will reference it in the environment variables below.
+    - **Region** closest to your users.
+    - **Medusa root directory**: `/packages/api`.
+    - **Initial user** — the first admin email and password.
+
+    Leave **Storefront root directory** empty — the Mercur basic template doesn't ship a storefront.
+    ![Configure project — name, region, Medusa root directory](/images/v2/cloud_3.png)
+  </Step>
+  <Step title="Set environment variables">
+    Scroll down to **Environment variables** and add the **Backend Environment Variables** below. Medusa Cloud provisions the database, Redis, and file storage automatically, so you don't need to set those.
+    ![Environment variables](/images/v2/cloud_4.png)
+
+    Only the following variables should be set:
+
+    ```bash
+    # Panels (build-time): the deployed backend origin, baked into the admin and
+    # vendor panels. Enable the **Build** toggle for this variable — the panels
+    # read it while they are being built, not at runtime.
+    MERCUR_BACKEND_URL=https://<your-subdomain>.medusajs.app
+
+    # CORS — the panels are served from the backend's own origin, so it is enough
+    # to list that origin (plus your storefront URL in STORE_CORS, if you have one)
+    STORE_CORS=https://<your-subdomain>.medusajs.app
+    ADMIN_CORS=https://<your-subdomain>.medusajs.app
+    VENDOR_CORS=https://<your-subdomain>.medusajs.app
+    AUTH_CORS=https://<your-subdomain>.medusajs.app
+
+    # Secrets
+    JWT_SECRET=
+    COOKIE_SECRET=
+
+    # Vendor panel URL used in seller emails and onboarding flows
+    MERCUR_VENDOR_URL=https://<your-subdomain>.medusajs.app/seller
+
+    # Stripe (customer payments + Mercur payout provider)
+    STRIPE_API_KEY=
+    STRIPE_WEBHOOK_SECRET=
+    STRIPE_PAYOUT_WEBHOOK_SECRET=
+
+    # Email (optional, e.g. Resend)
+    RESEND_API_KEY=
+    RESEND_FROM_EMAIL=
+
+    # Search (optional)
+    ALGOLIA_APP_ID=
+    ALGOLIA_API_KEY=
+    ```
+
+    <Warning>
+      `MERCUR_BACKEND_URL` must have the **Build** toggle enabled in the Medusa Cloud
+      environment-variable settings. Without it, the production build stops with a clear
+      error rather than baking the localhost default into the panels.
+    </Warning>
+
+    <Info>
+      For Stripe setup, including which keys go where and how to wire both webhooks,
+      see the [Stripe Connect integration
+      guide](/rc/resources/integrations/stripe-connect).
+    </Info>
+  </Step>
+  <Step title="Create and deploy">
+    Click **Create**. The build and deploy process will start and can take a few minutes to complete.
+  </Step>
+</Steps>
+
+You can change these variables later from the project's environment settings, and switch the deployment branch at any time. Medusa Cloud will automatically pull and rebuild your environment whenever a new commit is pushed to the selected branch. Remember that `MERCUR_BACKEND_URL` is baked into the panels at build time — changing it requires a redeploy.
+
+## After deployment
+
+Once the build succeeds, everything is served from `https://<your-subdomain>.medusajs.app`:
+
+| Surface      | URL                                              |
+| ------------ | ------------------------------------------------ |
+| Backend API  | `https://<your-subdomain>.medusajs.app`          |
+| Admin panel  | `https://<your-subdomain>.medusajs.app/dashboard` |
+| Vendor panel | `https://<your-subdomain>.medusajs.app/seller`   |
+
+Open the admin panel and sign in with the **Initial user** you configured in the setup step. If a panel shows a "Dashboard not built" page, the bundling step did not run — check the deployment's build logs for output from `bundle-dashboards`.
+
+<Tip>
+  Prefer hosting the panels separately (for example on Vercel or Netlify)? That
+  still works: deploy `apps/admin` and `apps/vendor` as static Vite builds, set
+  `MERCUR_BACKEND_URL` (or `VITE_MERCUR_BACKEND_URL`) to the backend URL at build
+  time, and add the panel URLs to the backend's `ADMIN_CORS`, `VENDOR_CORS`, and
+  `AUTH_CORS` variables.
+</Tip>
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="A panel shows a 'Dashboard not built' page — what went wrong?">
+    The bundling step didn't run during the build. Check the deployment's build logs for output from `bundle-dashboards`; the most common cause is a build that failed earlier (often a missing `MERCUR_BACKEND_URL` with the Build toggle off).
+  </Accordion>
+  <Accordion title="I changed MERCUR_BACKEND_URL but the panels still call the old URL">
+    The backend URL is **baked into the panels at build time**, not read at runtime. After changing the variable, trigger a redeploy so the panels rebuild with the new value.
+  </Accordion>
+  <Accordion title="Do I need to configure a database or Redis?">
+    No — Medusa Cloud provisions Postgres, Redis, and file storage automatically and injects their connection variables. Only set the variables listed in the setup step.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Stripe Connect" href="/rc/resources/integrations/stripe-connect">
+    Wire payments and payouts on the deployed environment.
+  </Card>
+  <Card title="Build your first marketplace" href="/rc/resources/tutorials/first-marketplace">
+    Run the end-to-end flow against your new deployment.
+  </Card>
+</CardGroup>

package/content/resources/integrations/notifications.mdx

@@ -0,0 +1,39 @@
+---
+title: "Notifications"
+description: "Send transactional emails and marketplace notifications with Resend."
+---
+
+<Note>
+  This guide is being written. The outline below is the intended structure.
+</Note>
+
+<Info>
+  **Two notification surfaces.** Mercur sends provider-backed transactional email (seller approvals, invites, order events) *and* keeps an in-app vendor notification feed in the Vendor Portal. The email side uses Medusa's standard notification-provider model — Resend is the documented default, but any Medusa notification provider plugs in the same way.
+</Info>
+
+## What Resend powers
+
+The emails and notifications Mercur sends, and where they're triggered.
+
+<Steps>
+  <Step title="Prerequisites">
+    Resend account, API key, and environment variables.
+  </Step>
+  <Step title="Configure the provider">
+    Wire Resend as the notification provider.
+  </Step>
+  <Step title="Send a test notification">
+    Trigger a test notification and confirm delivery.
+  </Step>
+</Steps>
+
+## Verify
+
+Trigger a test notification and confirm delivery.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Search" href="/rc/resources/integrations/search" />
+  <Card title="Deploy to Medusa Cloud" href="/rc/resources/deployment/medusa-cloud" />
+</CardGroup>

package/content/resources/integrations/search.mdx

@@ -0,0 +1,122 @@
+---
+title: "Search"
+description: "Mercur's provider-agnostic search module — zero-infrastructure Orama by default, swappable for Algolia, Meilisearch, or your own provider."
+---
+
+Mercur ships a **Search module** in `@mercurjs/core`, modeled on Medusa's pluggable-provider pattern (like the `file` and `notification` modules). The module owns a stable contract — `index`, `remove`, `search` — and delegates storage to exactly one active **provider**. Out of the box that provider is [Orama](https://docs.orama.com): an in-process, in-memory index that needs zero external infrastructure.
+
+<Warning>
+  The search module is a release-candidate feature and its surface may still evolve before the stable release.
+</Warning>
+
+<Info>
+  **Everything above the provider is provider-agnostic.** Subscribers index and remove documents on product, offer, and seller events; the store route calls `search.search(query)`; boot reindexing is event-driven. Swapping Orama for Algolia or Meilisearch means changing one provider registration — no changes to subscribers, the store route, or your storefront.
+</Info>
+
+## What gets indexed
+
+Products **and offers** are searchable. Offers are indexed as **per-offer documents** — one hit per vendor listing — each carrying the offer's scoped price, so search results price identically to `GET /store/offers`. Index updates are driven by subscribers on product, offer, and seller events; you never call `index()` from application code.
+
+## Searching from the storefront
+
+The Store API exposes one endpoint:
+
+```bash
+curl -X POST "http://localhost:9000/store/search" \
+  -H "x-publishable-api-key: <key>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "q": "t-shirt",
+    "limit": 12,
+    "offset": 0,
+    "region_id": "reg_123"
+  }'
+```
+
+| Field | Description |
+|-------|-------------|
+| `q` | Search query (defaults to `""` — browse mode) |
+| `limit` / `offset` | Pagination (limit 1–100, default 12) |
+| `region_id`, `country_code`, `province` | Pricing context — the provider projects the matching price onto each hit's `calculated_price` |
+| `filters` | Passed straight to the active provider, which owns its shape |
+
+The response returns `hits`, `count`, and `facets`.
+
+## The default provider: Orama
+
+The bundled `search-orama` provider keeps the index in RAM inside the API process. That means:
+
+- **Zero setup** — no accounts, keys, or services. Search works on a fresh project.
+- **Boot reindex** — an in-memory index is empty after a restart, so the module emits a reindex event on application start and a subscriber rebuilds the index from the database.
+
+<Note>
+  In-memory search fits development and small-to-medium catalogs. For large catalogs or multi-instance deployments, use a persistent provider — the index then lives in the external service and the boot reindex is unnecessary.
+</Note>
+
+## Swapping in Algolia or Meilisearch
+
+Ready-made provider integrations ship as blocks:
+
+```bash
+bunx @mercurjs/cli@rc add algolia
+# or
+bunx @mercurjs/cli@rc add meilisearch
+```
+
+| Provider | Hosting | Best for |
+|----------|---------|----------|
+| Orama (default) | In-process | Zero-infra development and smaller catalogs |
+| Algolia | Managed SaaS | Fastest setup, hosted relevance tuning |
+| Meilisearch | Self-hosted or cloud | Full control, open source |
+
+Each block installs the provider source and prints the configuration steps (API keys, module options). Follow the block's post-install docs to register the provider and set environment variables.
+
+## Writing your own provider
+
+A provider extends `AbstractSearchProvider` from `@mercurjs/core` and implements three methods:
+
+```typescript
+import { AbstractSearchProvider } from "@mercurjs/core/modules/search"
+import { SearchDoc, SearchQueryBase, SearchResults } from "@mercurjs/types"
+
+export class MySearchProvider extends AbstractSearchProvider {
+  static identifier = "my-search"
+
+  async index(docs: SearchDoc[]): Promise<void> { /* upsert documents */ }
+  async remove(ids: string[]): Promise<void> { /* delete by id */ }
+  async search(query: SearchQueryBase): Promise<SearchResults> { /* query + facets */ }
+}
+```
+
+Because subscribers and the store route only talk to the module contract, your provider slots in without touching anything else. Use the Algolia or Meilisearch block source as a working reference.
+
+## Verify
+
+1. Start a fresh project and `POST /store/search` with an empty `q` — published products return without any search service configured (that's Orama).
+2. Publish a product and search for its title — it appears without a manual reindex (subscribers indexed it).
+3. Restart the API and search again — results still return (the boot reindex rebuilt the in-memory index).
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Can I run two providers at once, e.g. Orama locally and Algolia in production?">
+    Only one provider is active at a time — the module has no multi-provider machinery. But because the provider is chosen by configuration, you can register different providers per environment (default Orama in development, Algolia in production) without touching any other code.
+  </Accordion>
+  <Accordion title="Do I ever need to trigger a reindex manually?">
+    Normally no — subscribers keep the index current, and in-memory providers rebuild on boot. A manual full reindex is only interesting after bulk data changes outside normal flows (e.g. direct DB imports); persistent providers ignore the boot event entirely.
+  </Accordion>
+  <Accordion title="Why does each offer appear as its own search hit?">
+    Because pricing and availability are per offer, not per product. One hit per vendor listing lets results carry the correct `calculated_price` for each seller — the same numbers as `GET /store/offers` — instead of an ambiguous product-level price.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Offers" href="/rc/learn/offers">
+    Why offers are indexed per seller with scoped prices.
+  </Card>
+  <Card title="Add a feature with a block" href="/rc/resources/tutorials/add-a-block">
+    How provider blocks are installed and configured.
+  </Card>
+</CardGroup>