@mercurjs/docs 2.2.0-canary.40

package/content/resources/tutorials/import-export-products.mdx

@@ -0,0 +1,96 @@
+---
+title: "Import and export products via CSV"
+description: "Install the product-import-export block and give vendors CSV import and export drawers on their product list."
+---
+
+Bulk catalog operations belong to vendors, not the operator — a seller migrating from another platform needs to bring hundreds of listings with them. The `product-import-export` block adds CSV import and export to the Vendor Portal: API routes, workflows built on Medusa's product CSV steps, and drawer UIs wired into the product list.
+
+<Info>
+  **This block is also a masterclass in Mercur's extension model.** It ships backend workflows and routes into your API package, and it overrides the vendor `/products` page by dropping a route file that [re-composes the built-in page's compound slots](/rc/resources/tutorials/recompose-a-page) — adding Import/Export buttons while keeping the stock table untouched. After installing, read its source; you own every file.
+</Info>
+
+## What you'll build
+
+A vendor product list with **Import** and **Export** header buttons, a working CSV round-trip, and the block's source code in your project.
+
+## Install and wire the block
+
+<Steps>
+  <Step title="Install the block">
+    ```bash
+    bunx @mercurjs/cli@rc add product-import-export
+    ```
+
+    The CLI copies the block's files into the directories mapped by your `blocks.json` aliases — workflows and routes into the API package, pages and hooks into the vendor app.
+  </Step>
+  <Step title="Install its dependencies">
+    The block uses Medusa's CSV flows and `multer` for uploads. Install them in the **API workspace**, not the project root:
+
+    ```bash
+    cd packages/api
+    bun add @medusajs/core-flows multer @types/multer
+    ```
+  </Step>
+  <Step title="Register the middleware">
+    The import route needs its upload middleware. Add it to your API's `middlewares.ts`:
+
+    ```typescript packages/api/src/api/middlewares.ts
+    import { defineMiddlewares } from '@medusajs/medusa'
+    import { productImportExportMiddlewares } from './vendor/products/middlewares'
+
+    export default defineMiddlewares({
+      routes: [...productImportExportMiddlewares],
+    })
+    ```
+  </Step>
+  <Step title="Regenerate types">
+    The block added `POST /vendor/products/import` and `GET /vendor/products/export`. Regenerate the route map so the vendor app's typed client knows about them:
+
+    ```bash
+    bunx @mercurjs/cli@rc codegen
+    ```
+
+    <Note>
+      No new modules and no migrations — the block reuses Medusa's built-in product CSV steps, so there's nothing to add to `medusa-config.ts` for this one. Always read a block's post-install output: each block declares its own setup steps.
+    </Note>
+  </Step>
+  <Step title="Run a round-trip">
+    Start the project and open the Vendor Portal's **Products** page — the header now shows Import and Export next to Create.
+
+    1. **Export** — opens the drawer at `/products/export` and downloads the seller's current products as CSV.
+    2. Edit the CSV: tweak a title, add a row.
+    3. **Import** — the drawer at `/products/import` accepts the file, validates rows, and shows an import summary before applying.
+  </Step>
+</Steps>
+
+## Verify
+
+1. The Products header shows Import and Export buttons; the rest of the page (search, filters, pagination) behaves exactly as before.
+2. The exported CSV contains the seller's products — and only theirs; the workflow scopes to the authenticated seller.
+3. After importing the edited CSV, the changed title appears in the product list.
+4. The block's source lives in your repo (e.g. `packages/api/src/workflows/import-seller-products.ts`, `apps/vendor/src/routes/products/page.tsx`) — run `bunx @mercurjs/cli@rc diff product-import-export` to compare against the registry later.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Can I customize the CSV columns or validation?">
+    Yes — the block is source code in your repo. The import workflow (`import-seller-products.ts`) and its validation step are yours to edit; the drawer UI under `routes/products/import/` includes the CSV template helper you can extend.
+  </Accordion>
+  <Accordion title="I already customized my /products page — will the block overwrite it?">
+    The block ships its own `routes/products/page.tsx`. If you already have one, the CLI asks before overwriting (or use `--overwrite` explicitly). Merge by hand in that case: keep your composition and add the block's Import/Export buttons to your `HeaderActions`.
+  </Accordion>
+  <Accordion title="Does import respect the product approval flow?">
+    Imported products enter through the same vendor create path as manual submissions — so they follow the [product-request pipeline](/rc/resources/tutorials/handle-product-requests) and land as `proposed` for operator review, not as instantly published records.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Re-compose a built-in page" href="/rc/resources/tutorials/recompose-a-page">
+    The page-override technique this block uses, explained step by step.
+  </Card>
+  <Card title="Build your own block" href="/rc/resources/tutorials/build-a-block">
+    Package a feature like this one and publish it to your own registry.
+  </Card>
+</CardGroup>

package/content/resources/tutorials/master-products-and-offers.mdx

@@ -0,0 +1,89 @@
+---
+title: "Work with master products and offers"
+description: "Two sellers compete on one catalog entry: publish a master product, create competing offers, and read per-offer prices from the Store API."
+---
+
+Mercur's catalog is a **master catalog**: one canonical product record, many sellers listing against it. The product defines *what the item is*; each seller's **offer** defines *how they sell it* — their SKU, price, stock, and shipping. This tutorial builds the classic "buy box" scenario: two sellers, one product, two competing offers.
+
+<Info>
+  **No seller owns a product.** There is no owner column. Creating a product adds a candidate to the shared catalog — the creator gets attribution (so their unpublished submissions appear in their own list) but no rights over the record after publication. What looks like ownership elsewhere is split into selling eligibility, creator attribution, and the status lifecycle. See [Products](/rc/learn/products).
+</Info>
+
+## What you'll build
+
+A published master product with offers from two sellers at different prices, visible side by side through the Store API with per-offer calculated prices.
+
+## Product vs offer
+
+| Concern | Lives on | Example |
+|---------|----------|---------|
+| What the item is | Master product | "Classic White T-Shirt", variants, attributes |
+| Who may sell it | `product_seller` allowlist | Empty = every seller; assigned = only those sellers |
+| How a seller sells it | Offer | SKU, price, stock, shipping profile |
+
+## Build the buy box
+
+<Steps>
+  <Step title="Publish a master product">
+    As Seller A, create a product in the Vendor Portal — say "Classic White T-Shirt" with a size variant. It enters as `proposed`; as the operator, confirm it in the Admin Panel so it's `published` (the review flow is covered in [Handle product requests](/rc/resources/tutorials/handle-product-requests)).
+
+    The published product now belongs to the shared catalog. Note what it does **not** have: a seller price or seller stock.
+  </Step>
+  <Step title="Seller A creates an offer">
+    In Seller A's Vendor Portal, create an offer against the product's variant: their own SKU, a price of $25, stock of 100, and one of their shipping profiles.
+
+    <Warning>
+      Offer inventory is linked to the **offer, not the variant**. Each seller manages stock for their own listing independently — a variant has no marketplace-wide stock figure, and its own `inventory_items` relation is empty for offer-based listings. Always read stock through the offer.
+    </Warning>
+  </Step>
+  <Step title="Seller B lists the same product">
+    As Seller B, find the same published product in the catalog and create a competing offer on the same variant — different SKU, $23, stock of 40. The `(seller_id, sku)` pair is unique per seller, so both sellers can use whatever SKU scheme they like.
+
+    Nothing about the master product changed. Two commercial listings now point at one catalog entry.
+  </Step>
+  <Step title="Read the buy box from the Store API">
+    The Store API exposes offers directly, each with its own calculated price:
+
+    ```bash
+    curl "http://localhost:9000/store/offers?product_id=prod_123" \
+      -H "x-publishable-api-key: <key>"
+    ```
+
+    Offers share the variant's price set scoped by an offer rule — each offer carries its own prices without duplicating the variant, and the storefront computes a `calculated_price` per offer. A buy-box storefront fetches the product once, then renders every seller's offer against it.
+  </Step>
+  <Step title="Check out against an offer">
+    Add Seller B's offer to a cart and place the order. The cart line item links to the **specific offer** purchased, and that link is preserved onto the order line item — so fulfillment, [commission calculation](/rc/learn/commissions), and [payouts](/rc/learn/payouts) all resolve to Seller B, even though both sellers list the same variant.
+  </Step>
+</Steps>
+
+## Verify
+
+1. Both offers appear in `GET /store/offers?product_id=...` with different `calculated_price` values.
+2. Each seller's Vendor Portal shows only their own offer; the Admin Panel lists both with store, pricing, and inventory.
+3. After the checkout in step 5, the order lands with Seller B; Seller A's offer and stock are untouched.
+4. Reducing Seller B's offer stock doesn't affect Seller A's availability — inventory is per offer.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="How do I restrict who may sell a product?">
+    The operator manages the `product_seller` allowlist: a product with assignments is visible and sellable only for those sellers, while a product with **no** assignments is open to every seller. Eligibility limits selling — it does not limit who may propose edits to the shared record.
+  </Accordion>
+  <Accordion title="Can two sellers use the same SKU?">
+    Yes — SKU uniqueness is per seller (`seller_id` + `sku`). Seller A and Seller B can both use `TSHIRT-WHITE-M`; a single seller cannot list the same SKU twice.
+  </Accordion>
+  <Accordion title="Who fulfills, refunds, and gets paid when several sellers list the same variant?">
+    Always the seller whose **offer** was purchased. The offer link travels from cart line to order line, so fulfillment, returns, commission, and payout all resolve through it — the variant alone is never enough to identify the seller.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Offers" href="/rc/learn/offers">
+    The offer data model, relationships, and checkout links.
+  </Card>
+  <Card title="Order Groups" href="/rc/learn/order-groups">
+    What happens when a cart spans both sellers — the multi-vendor split.
+  </Card>
+</CardGroup>

package/content/resources/tutorials/recompose-a-page.mdx

@@ -0,0 +1,129 @@
+---
+title: "Re-compose a built-in page"
+description: "Override a built-in panel page by dropping a route file at the same path and re-composing its compound component slots."
+---
+
+Every page in the admin and vendor panels is exported as a **compound component** — a root plus named slots like `Header`, `HeaderActions`, and `DataTable`. That means you never fork a page to change one part of it: you drop a `page.tsx` at the same route path, render the original page, and swap only the slot you care about. Everything you don't touch keeps its default behavior — data fetching, filters, pagination, i18n, all of it.
+
+<Info>
+  **This is not Medusa's widget system.** Medusa's admin lets you inject widgets into predefined zones around a page. Mercur takes a different approach: pages are React compound components you re-compose directly. There are no injection zones and no `defineWidgetConfig` — you get the actual page component and decide what renders inside it. See [Extending Panels](/rc/resources/customization/extending-panels) for the full comparison.
+</Info>
+
+## What you'll build
+
+A vendor portal `/products` page with **Import** and **Export** buttons added next to the built-in Create button — while the table, search, filters, and everything else stay exactly as shipped. This is the same technique the official `product-import-export` block uses.
+
+## Slot anatomy
+
+Built-in pages are exported from the `/pages` subpath of each panel package:
+
+```typescript
+import { ProductListPage } from "@mercurjs/vendor/pages"   // vendor portal
+import { CustomerListPage } from "@mercurjs/admin/pages"   // admin panel
+```
+
+Each list page exposes the same family of slots:
+
+| Slot | Renders |
+|------|---------|
+| `Table` | The `Container` shell holding header + table |
+| `Header` | The title/actions row |
+| `HeaderTitle` | Heading and subtitle |
+| `HeaderActions` | The action button cluster |
+| `HeaderCreateButton` | The built-in Create button |
+| `DataTable` | The wired data table — fetching, columns, filters, pagination |
+
+Detail pages expose section slots instead (e.g. `CustomerDetailPage.Main`, `CustomerDetailPage.Sidebar`, `CustomerDetailPage.MainGeneralSection`).
+
+## Override the page
+
+<Steps>
+  <Step title="Drop a route file at the same path">
+    Create the file in your vendor app at the path that matches the built-in route. `/products` maps to `src/routes/products/page.tsx`:
+
+    ```tsx apps/vendor/src/routes/products/page.tsx
+    import { Link } from "react-router-dom"
+    import { Button } from "@medusajs/ui"
+    import { ArrowDownTray, ArrowUpTray } from "@medusajs/icons"
+    import { ProductListPage } from "@mercurjs/vendor/pages"
+
+    export default function ProductsWithImportExport() {
+      return (
+        <ProductListPage>
+          <ProductListPage.Table>
+            <ProductListPage.Header>
+              <ProductListPage.HeaderTitle />
+              <ProductListPage.HeaderActions>
+                <Button size="small" variant="secondary" asChild>
+                  <Link to="import">
+                    <ArrowUpTray />
+                    Import
+                  </Link>
+                </Button>
+                <Button size="small" variant="secondary" asChild>
+                  <Link to="export">
+                    <ArrowDownTray />
+                    Export
+                  </Link>
+                </Button>
+                <ProductListPage.HeaderCreateButton />
+              </ProductListPage.HeaderActions>
+            </ProductListPage.Header>
+            <ProductListPage.DataTable />
+          </ProductListPage.Table>
+        </ProductListPage>
+      )
+    }
+    ```
+  </Step>
+  <Step title="Reuse the slots you don't change">
+    Note what happened in that file: `HeaderTitle`, `HeaderCreateButton`, and `DataTable` are the originals, rendered untouched. Only `HeaderActions` gained two buttons. You re-compose top-down — render the page, re-declare only the branch you're changing, and keep original slots for everything inside it.
+  </Step>
+  <Step title="Reload the panel">
+    The dashboard SDK picks the file up automatically (adding or removing a route file triggers a full reload in dev). Because the path matches a built-in route, **your page replaces the built-in one** — no configuration, no registration.
+  </Step>
+</Steps>
+
+<Note>
+  When a custom route's path matches a built-in route, your page replaces the built-in one. Routes at new paths are appended instead. That one rule is the entire override mechanism.
+</Note>
+
+## How defaults work
+
+If you render a compound page with **no children**, it renders its full default composition — so `<ProductListPage />` alone is identical to the built-in page. Every page root follows the pattern:
+
+```tsx
+Children.count(children) > 0 ? children : <DefaultComposition />
+```
+
+## Verify
+
+1. Run your project (`bun run dev`) and open the vendor portal.
+2. Navigate to **Products** — the list should look identical to before, plus Import and Export buttons in the header.
+3. Search, filter, and paginate the table — all built-in behavior must still work, since `DataTable` is untouched.
+4. Delete your `src/routes/products/page.tsx` and reload — the built-in page comes back. Nothing was forked.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Where do I find which slots a page exposes?">
+    Import the page from `@mercurjs/vendor/pages` or `@mercurjs/admin/pages` and let your editor's autocomplete list the attached members — every slot is a static property on the page component. The naming is consistent across pages: list pages expose `Table`/`Header`/`HeaderTitle`/`HeaderActions`/`HeaderCreateButton`/`DataTable`; detail pages expose `Main`/`Sidebar` plus one property per section.
+  </Accordion>
+  <Accordion title="Can I remove a built-in element, like the Create button?">
+    Yes — re-composition is declarative. Anything you don't render doesn't appear: re-declare `HeaderActions` with only your own buttons and omit `HeaderCreateButton`.
+  </Accordion>
+  <Accordion title="What about changing the table columns?">
+    `DataTable` is a single slot — you either keep it wholesale or replace it with your own table. For a different column set, replace the slot with your own component built on the shared `DataTable`/`useDataTable` primitives from the panel package.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Replace panel components" href="/rc/resources/tutorials/replace-panel-components">
+    Swap global chrome like the sidebar or topbar instead of a single page.
+  </Card>
+  <Card title="Add a custom API route" href="/rc/resources/tutorials/custom-api-route">
+    Back your custom page with a typed endpoint of your own.
+  </Card>
+</CardGroup>

package/content/resources/tutorials/replace-panel-components.mdx

@@ -0,0 +1,116 @@
+---
+title: "Replace panel components"
+description: "Swap the sidebar, topbar actions, or store setup screen for your own components through dashboard SDK configuration."
+---
+
+Some customizations aren't about one page — they change the panel's global chrome. For those, the dashboard SDK exposes a small set of **named component overrides**: you point the plugin config at your own file, and the panel renders your component in place of the built-in one everywhere it appears.
+
+<Info>
+  **Choose the right tool.** A component override replaces one of four global layout slots across the whole panel. If you want to change a single page, [re-compose it](/rc/resources/tutorials/recompose-a-page) instead — and if you want to add a new screen, just [drop in a route](/rc/resources/tutorials/custom-panel-page). The decision guide in [Extending Panels](/rc/resources/customization/extending-panels#choosing-your-extension-mechanism) compares all three.
+</Info>
+
+## What you'll build
+
+A vendor portal with custom topbar actions (a help link and a status badge) and a custom main sidebar, configured entirely from `vite.config.ts`.
+
+## The available slots
+
+Exactly four layout components can be replaced:
+
+| Component | Where it renders |
+|-----------|------------------|
+| `MainSidebar` | Primary navigation sidebar on every main page |
+| `SettingsSidebar` | Sidebar of the `/settings` section |
+| `TopbarActions` | Action cluster on the right side of the top bar |
+| `StoreSetup` | The store setup screen shown to new sellers (vendor portal) |
+
+Anything else — a page, a section, a table — is customized through routes and compound components, not through overrides.
+
+## Set up the override
+
+<Steps>
+  <Step title="Write the replacement component">
+    Create the component anywhere under `src/`. It must have a **default export**:
+
+    ```tsx apps/vendor/src/components/topbar-actions.tsx
+    import { Badge, Button } from "@medusajs/ui"
+
+    export default function TopbarActions() {
+      return (
+        <div className="flex items-center gap-x-2">
+          <Badge size="2xsmall" color="green">
+            All systems operational
+          </Badge>
+          <Button size="small" variant="transparent" asChild>
+            <a href="https://help.example.com" target="_blank" rel="noreferrer">
+              Help
+            </a>
+          </Button>
+        </div>
+      )
+    }
+    ```
+  </Step>
+  <Step title="Register it in the Vite config">
+    Component overrides live in the `components` option of `mercurDashboardPlugin`, in your panel app's `vite.config.ts`. Paths are **relative to `src/`**:
+
+    ```typescript apps/vendor/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',
+          components: {
+            TopbarActions: 'components/topbar-actions',
+            MainSidebar: 'components/main-sidebar',
+          },
+        }),
+      ],
+    })
+    ```
+
+    The plugin resolves each path at build time and swaps your component in through the `virtual:mercur/components` module — no runtime registration, no context providers to wire.
+  </Step>
+  <Step title="Restart the dev server">
+    Vite config changes require a restart. After it, your components render everywhere their slots appear.
+  </Step>
+</Steps>
+
+<Tip>
+  Build overrides with `@medusajs/ui` components and Medusa UI color tokens so they match the rest of the panel. The panels ship no other UI library.
+</Tip>
+
+## Verify
+
+1. Open the vendor portal — the top bar shows your badge and Help link on every page.
+2. Navigate between main pages and `/settings` — the override applies everywhere its slot renders.
+3. Remove the `components` entry and restart — the built-in components return. The originals were never modified.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="If I replace MainSidebar, do my custom routes still show up in the menu?">
+    Only if your sidebar renders them. A `MainSidebar` override replaces the **entire** navigation sidebar, including the auto-generated menu items from route `config` exports — read them from `virtual:mercur/menu-items` if you want to keep automatic navigation. If you only want to add or reorder items, you don't need an override at all: the `config` export on route files (with `rank` and `nested`) covers that.
+  </Accordion>
+  <Accordion title="Can I override other components, like the login page or a form?">
+    No — these four slots are the complete list. The login flow, forms, and everything page-level are customized through drop-in routes and [compound re-composition](/rc/resources/tutorials/recompose-a-page).
+  </Accordion>
+  <Accordion title="Do overrides apply to both panels?">
+    Each panel app has its own `vite.config.ts`, so overrides are configured per panel. `StoreSetup` only exists in the vendor portal; the other three slots exist in both.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Re-compose a built-in page" href="/rc/resources/tutorials/recompose-a-page">
+    Change one page's composition instead of global chrome.
+  </Card>
+  <Card title="Extending Panels" href="/rc/resources/customization/extending-panels">
+    The full reference for routes, navigation, branding, and overrides.
+  </Card>
+</CardGroup>

package/content/resources/tutorials/seller-payouts-stripe.mdx

@@ -0,0 +1,89 @@
+---
+title: "Set up seller payouts"
+description: "Take a seller from zero to paid: Stripe Connect onboarding, an order through fulfillment, capture, and the automated payout."
+---
+
+Payouts are the last mile of a marketplace — the marketplace collects the customer's payment, deducts its commission, and transfers the remainder to the seller. In Mercur that pipeline is **fully automated**: once a seller is onboarded and an order is fulfilled, scheduled jobs and subscribers handle capture and transfer without any manual step. This tutorial follows one order through the entire pipeline.
+
+<Info>
+  **Nothing pays out until the seller's account is `ACTIVE`.** Every stage of the pipeline checks the payout account status. A seller who skips onboarding can sell, but their orders sit uncaptured until the authorization window forces the issue — which is exactly why surfacing onboarding status in the vendor portal matters.
+</Info>
+
+## What you'll build
+
+A working payout loop: a seller with an active Stripe Connect account, one fulfilled order, a captured payment, and a payout record that settles via webhook.
+
+## Prerequisites
+
+Stripe Connect must be configured first — provider registration, API keys, and **both** webhooks (payment and payout). Follow the [Stripe Connect integration guide](/rc/resources/integrations/stripe-connect) up to and including "Set up webhooks", then come back here. For local development, keep `stripe listen` forwarding running.
+
+## Run the pipeline
+
+<Steps>
+  <Step title="Onboard the seller">
+    In the Vendor Portal, the seller opens **Settings → Payouts** and starts onboarding. Under the hood this creates a `PayoutAccount` (status `PENDING`) and an `Onboarding` record holding the Stripe onboarding link:
+
+    ```bash
+    curl -X POST http://localhost:9000/vendor/payout-accounts/<account-id>/onboarding \
+      -H "Authorization: Bearer <seller-token>" \
+      -H "Content-Type: application/json" \
+      -d '{ "context": { "return_url": "http://localhost:7001/settings/payouts" } }'
+    ```
+
+    The seller completes Stripe's hosted flow (identity, bank account) — in test mode, Stripe's test data completes it in a minute. When Stripe activates the account, the payout webhook delivers an `account.activated` event and Mercur flips the account to `ACTIVE`. No polling — the webhook is the source of truth.
+  </Step>
+  <Step title="Place and fulfill an order">
+    Place an order for one of the seller's listings, then in the Vendor Portal fulfill it. Fulfillment matters: by default, capture requires the order to reach `fulfilled` status (configurable via the payout module's `requiredFulfillmentStatus` option).
+  </Step>
+  <Step title="Watch the capture">
+    A scheduled job runs every 15 minutes looking for orders that are ready: payment `authorized`, seller `ACTIVE`, fulfillment status met, no payout yet. When the capture deadline approaches it emits `order.capture_requested`, and a subscriber captures the payment.
+
+    To move faster while testing, wait for the next 15-minute tick after fulfillment.
+
+    <Warning>
+      Payment authorizations expire — 7 days by default (`authorizationWindowMs`). Sellers who don't fulfill within the window (`sellerActionWindowMs`, 72h default) risk the capture buffer kicking in or the authorization expiring entirely. Tune these in the payout module options with your fulfillment SLAs in mind.
+    </Warning>
+  </Step>
+  <Step title="The payout lands">
+    Once per day (1 AM UTC) a job scans captured orders without payouts and emits `payout.requested` per order. The `createPayoutWorkflow` then:
+
+    1. Loads the order with its commission lines.
+    2. Calculates `payout_amount = order.total − total_commission`.
+    3. Calls Stripe to create the transfer and records a `Payout` (status `PENDING`).
+
+    Stripe's webhook then walks the payout through `PROCESSING` → `PAID` (or `FAILED`).
+  </Step>
+</Steps>
+
+## Verify
+
+1. **Account**: `GET /vendor/payout-accounts/<id>` returns `status: "ACTIVE"` after onboarding.
+2. **Capture**: after fulfillment plus one job tick, the order's payment shows as captured.
+3. **Payout**: `GET /admin/payouts` lists a payout for the order, with `amount` equal to the order total minus the commission lines from your [commission configuration](/rc/resources/tutorials/configure-commissions).
+4. **Vendor view**: the seller sees the payout and its status in the Vendor Portal's payout history.
+5. **Stripe**: the transfer appears on the connected account in the Stripe test dashboard.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="What if the seller never completes onboarding?">
+    Their orders stay uncaptured. The capture job skips orders whose seller isn't `ACTIVE`, and once the authorization window lapses the payment expires (an `order.authorization_expired` event fires). Surface the onboarding status prominently and chase incomplete sellers early.
+  </Accordion>
+  <Accordion title="Why hasn't a payout appeared even though the order is captured?">
+    The payout job runs once per day at 1 AM UTC — a captured order waits for the next daily tick. Also check that no payout already exists for the order and that the seller's account is still `ACTIVE` (a `RESTRICTED` account pauses payouts until the provider clears it).
+  </Accordion>
+  <Accordion title="What do the payout statuses mean?">
+    `PENDING` — transfer initiated; `PROCESSING` — the provider is moving funds; `PAID` — settled; `FAILED` / `CANCELED` — the transfer didn't complete. All transitions after `PENDING` come from provider webhook events, so a stuck status usually means the payout webhook isn't reaching your API.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Payout" href="/rc/learn/payouts">
+    The full pipeline reference — statuses, jobs, webhook events, module options.
+  </Card>
+  <Card title="Stripe Connect" href="/rc/resources/integrations/stripe-connect">
+    Provider configuration, transfers vs payouts, refunds, and EU considerations.
+  </Card>
+</CardGroup>

package/content/telemetry.mdx

@@ -0,0 +1,67 @@
+---
+title: "Telemetry"
+description: "Learn about the anonymous usage data collected by the Mercur CLI"
+---
+
+## Overview
+
+The Mercur CLI collects **anonymous usage data** to help us understand how the CLI is used and improve the developer experience. This data is collected by default but can be easily disabled.
+
+## What We Collect
+
+When you run CLI commands (`create`, `init`, `add`, `registry:build`), the following data is sent:
+
+| Data | Description |
+|------|-------------|
+| Event type | Which command was run and its outcome |
+| Node.js version | Your Node.js runtime version |
+| Node environment | The `NODE_ENV` value |
+| Mercur version | Version of `@mercurjs/cli` in your project |
+| Medusa version | Version of `@medusajs/framework` in your project |
+| Package manager | npm, yarn, pnpm, or bun |
+| Project structure | Whether `src/` directory is used, alias prefix |
+| System info | OS, platform, architecture, CPU model/speed/count, RAM |
+| Environment | Whether running in WSL, Docker, or a TTY |
+| Deployment vendor | Detected hosting platform (Railway, Fly.io, Heroku, etc.) |
+| Project ID | SHA-256 hash (base64) of your git remote URL — **not the URL itself** |
+| Project config | Contents of your `blocks.json` configuration |
+| Email | **Only** if you voluntarily provided it during `create-mercur-app` |
+
+## What We Do NOT Collect
+
+- Source code or file contents
+- File names or directory structure
+- Git history or commit messages
+- Personal data (beyond the optional email above)
+
+## How to Opt Out
+
+### Using the CLI
+
+```bash
+mercurjs telemetry --disable
+```
+
+### Using an environment variable
+
+```bash
+export MERCUR_DISABLE_TELEMETRY=true
+```
+
+This is useful for CI/CD environments or shared configurations.
+
+### Check current status
+
+```bash
+mercurjs telemetry
+```
+
+## Where Data Goes
+
+Telemetry events are sent to `https://telemetry.mercurjs.com`. The data is used exclusively by the Mercur team to prioritize features and fix issues.
+
+## Re-enabling Telemetry
+
+```bash
+mercurjs telemetry --enable
+```