@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/resources/tutorials/customize-navigation.mdx

@@ -1,21 +1,24 @@
 ---
-title: "Customize navigation"
-description: "Reorder, hide, relabel, and re-parent built-in sidebar items with a single _navigation.ts file and defineNavigationConfig."
+title: "How to Customize Navigation"
+sidebarTitle: "Customize Navigation"
+description: "Reorder, hide, relabel, and re-parent the panel's built-in sidebar items from a single _navigation.ts file."
 ---
 
-The built-in sidebar ships a fixed set of items — Orders, Products, Customers, and so on. To reshape them without replacing the whole sidebar, author one host-owned file: `src/_navigation.ts`. It reorders, hides, relabels, and re-parents **built-in** items, and it is the single source of truth for the sidebar's shape.
+Reshape the built-in sidebar without replacing it. You author one host-owned file, `src/_navigation.ts`, and it reorders, hides, relabels, and re-parents the built-in items.
+
+The sidebar ships a fixed set of items such as Orders, Products, and Customers. `_navigation.ts` is the single source of truth for their shape. It overrides existing items only, so a new item still comes from a page you add.
 
 <Info>
-  **When to use this vs. a `config` export.** New pages you add via [drop-in routes](/rc/resources/tutorials/custom-panel-page) place their own sidebar item through `defineRouteConfig({ label, rank, nested })`. `_navigation.ts` is for the items you *didn't* create — the built-in ones. The two layer cleanly: custom routes place themselves; `_navigation.ts` reshapes the built-ins.
+  **When to use this vs. a `config` export.** New pages you add via [drop-in routes](/rc/resources/tutorials/custom-panel-page) place their own sidebar item through `defineRouteConfig({ label, rank, nested })`. `_navigation.ts` is for the items you *didn't* create, the built-in ones. The two layer cleanly: custom routes place themselves, and `_navigation.ts` reshapes the built-ins.
 </Info>
 
 ## What you'll build
 
 A vendor sidebar with Orders pinned to the top, Price Lists hidden, and Campaigns moved under Orders.
 
-## Register the typed targets (once)
+## Register the typed targets
 
-Nav item ids are typed and generated per panel. Register them once with a single ambient reference in your app's `src` (already shipped by `create-mercur-app`):
+Nav item ids are typed and generated per panel. Register them once with a single ambient reference in your app's `src`. The `create-mercur-app` scaffold already ships this file.
 
 ```typescript apps/vendor/src/extension-targets.d.ts
 /// <reference types="@mercurjs/vendor/extension-targets" />
@@ -27,7 +30,7 @@ With it present, `id` and `nested` autocomplete and an unknown id fails `tsc`.
 
 <Steps>
   <Step title="Create src/_navigation.ts">
-    The file is host-owned and underscore-prefixed. Default-export a `defineNavigationConfig` with an `items` array of overrides:
+    The file is host-owned and underscore-prefixed. Default-export a `defineNavigationConfig` with an `items` array of overrides.
 
     ```ts apps/vendor/src/_navigation.ts
     import { defineNavigationConfig } from "@mercurjs/dashboard-sdk"
@@ -42,21 +45,25 @@ With it present, `id` and `nested` autocomplete and an unknown id fails `tsc`.
     ```
   </Step>
   <Step title="Know the override fields">
-    Each entry targets one built-in item by its stable `id`:
+    Each entry targets one built-in item by its stable `id`.
 
     | Field | Type | Effect |
     |-------|------|--------|
-    | `id` | `NavItemId` | **Required.** The built-in item to override (top-level or nested) |
-    | `rank` | `number` | Order within its parent (lower first) |
-    | `hidden` | `boolean` | Remove it from the sidebar |
-    | `label` | `string` | Relabel (i18n key or literal) |
-    | `icon` | `ComponentType` | Replace its icon |
-    | `nested` | `NavParentId \| null` | Re-parent under another top-level item; `null` promotes a nested item to top level |
-
-    Both `id` and `nested` are checked against the panel's generated `NavItemRegistry` / `NavParentRegistry`.
+    | `id` | `NavItemId` | **Required.** The built-in item to override, top-level or nested. |
+    | `rank` | `number` | Order within its parent, lower first. |
+    | `hidden` | `boolean` | Remove it from the sidebar. |
+    | `label` | `string` | Relabel with an i18n key or literal. |
+    | `icon` | `ComponentType` | Replace its icon. |
+    | `nested` | `NavParentId \| null` | Re-parent under another top-level item. `null` promotes a nested item to top level. |
+
+    Both `id` and `nested` are checked against the panel's generated `NavItemRegistry` and `NavParentRegistry`.
   </Step>
   <Step title="Reload the panel">
-    Open the vendor portal — Orders sits at the top, Price Lists is gone from the menu, and Campaigns now appears under Orders. The route for a hidden item stays reachable directly by URL unless you also remove it.
+    Open the vendor portal. Orders sits at the top, Price Lists is gone from the menu, and Campaigns now appears under Orders.
+
+    <Note>
+      The route for a hidden item stays reachable directly by URL unless you also remove it.
+    </Note>
   </Step>
 </Steps>
 
@@ -78,23 +85,23 @@ export default defineNavigationConfig({
 1. The top-level order reflects your `rank` values, with `orders` first.
 2. `price-lists` no longer appears in the sidebar.
 3. `campaigns` renders as a child under Orders.
-4. Set `id: "not-an-item"` — `bun run lint` (tsc) fails against `NavItemRegistry`.
-5. Delete `_navigation.ts` — the default sidebar returns.
+4. Set `id: "not-an-item"`. `bun run lint` (tsc) fails against `NavItemRegistry`.
+5. Delete `_navigation.ts`. The default sidebar returns.
 
 ## FAQ
 
 <AccordionGroup>
   <Accordion title="Can an installed block reorder the sidebar?">
-    No. Navigation is deliberately host-only — blocks can ship pages, widgets, and custom fields, but the sidebar order stays a single source of truth in your app's `_navigation.ts`.
+    No. Navigation is deliberately host-only. Blocks can ship pages, widgets, and custom fields, but the sidebar order stays a single source of truth in your app's `_navigation.ts`.
   </Accordion>
   <Accordion title="What ids can I target?">
-    Any built-in item, top-level or nested, by its own id — e.g. `orders`, `products`, `categories`, `collections`, `campaigns`, `customer-groups`. Let your editor autocomplete `id:` against `NavItemId`; the full set is generated into your panel's `extension-targets.d.ts`.
+    Any built-in item, top-level or nested, by its own id, such as `orders`, `products`, `categories`, `collections`, `campaigns`, or `customer-groups`. Let your editor autocomplete `id:` against `NavItemId`. The full set is generated into your panel's `extension-targets.d.ts`.
   </Accordion>
   <Accordion title="Does this work in the admin panel too?">
-    Yes — drop `src/_navigation.ts` in the admin app and reference `@mercurjs/admin/extension-targets`. Each panel ships its own nav id set.
+    Yes. Drop `src/_navigation.ts` in the admin app and reference `@mercurjs/admin/extension-targets`. Each panel ships its own nav id set.
   </Accordion>
   <Accordion title="How do I add a brand-new sidebar item?">
-    That's a [drop-in route](/rc/resources/tutorials/custom-panel-page) with a `config` export — `_navigation.ts` only reshapes built-in items, it doesn't create routes.
+    That's a [drop-in route](/rc/resources/tutorials/custom-panel-page) with a `config` export. `_navigation.ts` only reshapes built-in items, it doesn't create routes.
   </Accordion>
 </AccordionGroup>
 

package/content/resources/tutorials/extend-forms-and-tables.mdx

@@ -1,21 +1,22 @@
 ---
-title: "Extend forms and tables"
-description: "Add validated fields to built-in forms, replace fields in detail sections, and add list columns with defineCustomFieldsConfig and createFormHelper."
+title: "How to Extend Forms and Tables"
+sidebarTitle: "Extend Forms & Tables"
+description: "Add validated fields, detail-section displays, and list columns to a built-in model from a single file with defineCustomFieldsConfig."
 ---
 
-`defineCustomFieldsConfig` is Mercur's model-scoped extension surface: from one file per model, you add validated fields to built-in create/edit forms, replace/remove/add fields in detail sections, and add columns to the list table — all wired into the built-in page, all typed against the model's generated registry.
+`defineCustomFieldsConfig` is Mercur's model-scoped extension surface. From one file per model you add validated fields to built-in create and edit forms, replace, remove, or add fields in detail sections, and add columns to the list table. Everything wires into the built-in page and stays typed against the model's generated registry.
 
 <Info>
-  **UI, not schema.** This helper is a *panel* surface — it renders, validates, and displays fields. It does not create database columns. To *store* extra data, use the backend [Custom Fields module](/rc/resources/customization/custom-fields) or your own API route/workflow. In the MVP, panel custom fields for `product` are submitted under `additional_data` and persisted onto the product's `metadata`.
+  **UI, not schema.** This helper is a panel surface. It renders, validates, and displays fields. It does not create database columns. To store extra data, use the backend [Custom Fields module](/rc/resources/customization/custom-fields) or your own API route or workflow. In the MVP, panel custom fields for `product` are submitted under `additional_data` and persisted onto the product's `metadata`.
 </Info>
 
 ## What you'll build
 
-An `ERP ID` field on the vendor product edit form, shown in the product's detail section and as a list-table column — from a single `src/custom-fields/product.tsx`.
+An `ERP ID` field on the vendor product edit form, shown in the product's detail section and as a list-table column, all from a single `src/custom-fields/product.tsx`.
 
-## Register the typed targets (once)
+## Register the typed targets
 
-Models, form zones, display zones, and built-in field ids are typed per panel. Register them once (shipped by `create-mercur-app`):
+Models, form zones, display zones, and built-in field ids are typed per panel. You register them once, and `create-mercur-app` ships this reference for you.
 
 ```typescript apps/vendor/src/extension-targets.d.ts
 /// <reference types="@mercurjs/vendor/extension-targets" />
@@ -25,7 +26,7 @@ Models, form zones, display zones, and built-in field ids are typed per panel. R
 
 <Steps>
   <Step title="Create the model file">
-    Drop `src/custom-fields/<model>.tsx` and default-export a `defineCustomFieldsConfig`. `createFormHelper` (from `@mercurjs/dashboard-shared`) turns a Zod schema into an input type + validation:
+    Drop `src/custom-fields/<model>.tsx` and default-export a `defineCustomFieldsConfig`. `createFormHelper` from `@mercurjs/dashboard-shared` turns a Zod schema into an input type plus validation.
 
     ```tsx apps/vendor/src/custom-fields/product.tsx
     import { defineCustomFieldsConfig } from "@mercurjs/dashboard-sdk"
@@ -53,10 +54,11 @@ Models, form zones, display zones, and built-in field ids are typed per panel. R
     })
     ```
   </Step>
+
   <Step title="Add a detail-section display">
-    `displays[]` targets a detail-page section by its `zone` id. Keyed by field `id`, an entry **adds**, **replaces**, or **removes** a field:
+    `displays[]` targets a detail-page section by its `zone` id. Keyed by field `id`, an entry adds, replaces, or removes a field.
 
-    ```tsx
+    ```tsx apps/vendor/src/custom-fields/product.tsx
     import { Text } from "@medusajs/ui"
 
     // ...inside defineCustomFieldsConfig:
@@ -64,7 +66,7 @@ Models, form zones, display zones, and built-in field ids are typed per panel. R
       {
         zone: "general",
         fields: [
-          // ADD — an unknown id appends a new read-only row
+          // ADD: an unknown id appends a new read-only row
           {
             id: "erp_id",
             component: ({ data }) => (
@@ -73,9 +75,9 @@ Models, form zones, display zones, and built-in field ids are typed per panel. R
               </Text>
             ),
           },
-          // REMOVE — a built-in id + null hides the field
+          // REMOVE: a built-in id + null hides the field
           { id: "subtitle", component: null },
-          // REPLACE — a built-in id + component overrides its render
+          // REPLACE: a built-in id + component overrides its render
           {
             id: "handle",
             component: ({ data }) => (
@@ -89,12 +91,15 @@ Models, form zones, display zones, and built-in field ids are typed per panel. R
     ],
     ```
 
-    Built-in field ids (like `subtitle`, `handle`, `status`, `title`) autocomplete from the panel's generated `CustomFieldsRegistry`; an unknown id is treated as an added row.
+    <Tip>
+      Built-in field ids such as `subtitle`, `handle`, `status`, and `title` autocomplete from the panel's generated `CustomFieldsRegistry`. An unknown id is treated as an added row.
+    </Tip>
   </Step>
+
   <Step title="Add a list column">
-    The `list` block extends the model's list table — add or override columns by id, hide built-in columns, and reorder:
+    The `list` block extends the model's list table. Add or override columns by id, hide built-in columns, and reorder.
 
-    ```tsx
+    ```tsx apps/vendor/src/custom-fields/product.tsx
     // ...inside defineCustomFieldsConfig:
     list: {
       columns: [
@@ -111,14 +116,15 @@ Models, form zones, display zones, and built-in field ids are typed per panel. R
     },
     ```
   </Step>
+
   <Step title="Reload the panel">
-    Open the vendor portal. The product **edit** drawer shows the ERP ID field (validated on submit and persisted via `additional_data`), the detail **general** section shows the ERP ID row (with `subtitle` removed and `handle` re-rendered), and the product **list** shows the ERP column.
+    Open the vendor portal. The product edit drawer shows the ERP ID field, validated on submit and persisted via `additional_data`. The detail general section shows the ERP ID row, with `subtitle` removed and `handle` re-rendered. The product list shows the ERP column.
   </Step>
 </Steps>
 
-## The `createFormHelper` surface
+## The createFormHelper surface
 
-`createFormHelper<T>()` exposes a Zod-based surface that drives both the input type and its validation:
+`createFormHelper<T>()` exposes a Zod-based surface that drives both the input type and its validation.
 
 ```ts
 const form = createFormHelper<T>()
@@ -133,11 +139,11 @@ form.define({
 })
 ```
 
-Fields render through the standard `Form.Field → Form.Item` chain (never a raw `Controller`) and participate in the existing `TabbedForm` / `RouteDrawer` submit and validation flow.
+Fields render through the standard `Form.Field → Form.Item` chain, never a raw `Controller`. They participate in the existing `TabbedForm` and `RouteDrawer` submit and validation flow.
 
 ## Linked-module data
 
-To read data from a linked module alongside the entity, declare it with `link`; those relations are fetched with the entity and become available to columns and displays:
+To read data from a linked module alongside the entity, declare it with `link`. Those relations are fetched with the entity and become available to columns and displays.
 
 ```ts
 export default defineCustomFieldsConfig({
@@ -149,30 +155,32 @@ export default defineCustomFieldsConfig({
 })
 ```
 
-The SDK derives the fetch query from `link` and merges it into the built-in query with the `+`/`-` convention — you never hand-write the field list.
+<Note>
+  The SDK derives the fetch query from `link` and merges it into the built-in query with the `+` and `-` convention. You never hand-write the field list.
+</Note>
 
 ## Verify
 
 1. The ERP ID field renders in the product edit drawer and validates on submit.
-2. Saving persists the value (visible on reload) via `additional_data` → `metadata`.
+2. Saving persists the value, visible on reload, via `additional_data` to `metadata`.
 3. The detail general section shows the ERP row, hides `subtitle`, and re-renders `handle`.
 4. The product list shows the ERP column, hides `collection`, and reorders columns.
-5. Set `zone: "nope"` in `forms` — `bun run lint` (tsc) fails against the model's registry.
+5. Set `zone: "nope"` in `forms`. `bun run lint` (tsc) fails against the model's registry.
 
 ## FAQ
 
 <AccordionGroup>
   <Accordion title="Which models and zones are available?">
-    Today: the `product` model in the vendor portal, with form zone `edit` and display zone `general`. The valid set per panel is generated into `CustomFieldsRegistry` in `extension-targets.d.ts` — autocomplete `model` / `zone` to see what's mounted.
+    Today: the `product` model in the vendor portal, with form zone `edit` and display zone `general`. The valid set per panel is generated into `CustomFieldsRegistry` in `extension-targets.d.ts`. Autocomplete `model` and `zone` to see what's mounted.
   </Accordion>
   <Accordion title="Where is the value actually stored?">
-    In the MVP, product custom fields are submitted under `additional_data` and persisted onto `product.metadata`. `defineCustomFieldsConfig` itself doesn't create a column — for durable, queryable storage model it with the backend [Custom Fields module](/rc/resources/customization/custom-fields) or a custom route/workflow.
+    In the MVP, product custom fields are submitted under `additional_data` and persisted onto `product.metadata`. `defineCustomFieldsConfig` itself doesn't create a column. For durable, queryable storage, model it with the backend [Custom Fields module](/rc/resources/customization/custom-fields) or a custom route or workflow.
   </Accordion>
   <Accordion title="Can I extend the onboarding wizard?">
-    That's the same helper with `zone: "onboarding"` and `tab` set to a wizard step id (vendor only). It's designed but not mounted in the current MVP — the runtime host exists; the wizard mount is a follow-up.
+    That's the same helper with `zone: "onboarding"` and `tab` set to a wizard step id (vendor only). It's designed but not mounted in the current MVP. The runtime host exists. The wizard mount is a follow-up.
   </Accordion>
   <Accordion title="Can a block ship custom fields?">
-    Yes — a [block](/rc/learn/blocks) can include `src/custom-fields/` files in its `vendor_ui` / `admin_ui` entry, aggregated like the host app's.
+    Yes. A [block](/rc/learn/blocks) can include `src/custom-fields/` files in its `vendor_ui` or `admin_ui` entry, aggregated like the host app's.
   </Accordion>
 </AccordionGroup>
 

package/content/resources/tutorials/extend-onboarding.mdx

@@ -1,21 +1,24 @@
 ---
-title: "Extend the onboarding flow"
-description: "Add a field to the vendor store-setup surface, submit it through additional_data, and persist it durably from a workflow hook — end to end, without forking."
+title: "How to Extend Onboarding"
+sidebarTitle: "Extend Onboarding"
+description: "Add a field to the vendor store-setup surface, carry it through additional_data, and persist it from a workflow hook without forking core."
 ---
 
-The vendor **store-setup / onboarding** surface is a widget zone (`seller.setup`) that renders the full `seller` object as its `data`. That makes onboarding a full extension seam: drop a widget to add UI, carry the new value to the API on the built-in seller routes through `additional_data`, and persist it from a workflow hook — the same three layers you'd wire in plain Medusa, kept intact by Mercur.
+Add a custom field to the vendor onboarding flow and store its value durably, end to end.
+
+The vendor store-setup and onboarding surface is a widget zone, `seller.setup`, that renders the full `seller` object as its `data`. That makes onboarding a full extension seam. You drop a widget to add UI, carry the new value to the API on the built-in seller routes through `additional_data`, and persist it from a workflow hook. These are the same three layers you wire in plain Medusa, kept intact by Mercur.
 
 <Info>
-  **Three layers, one flow.** The panel (a `seller.setup` widget) *renders and collects*. The vendor seller route *carries* the value through `additional_data` — no core schema change. A `sellersUpdated` workflow hook *persists* it. Each layer is additive: nothing built-in is replaced.
+  **Three layers, one flow.** The panel, a `seller.setup` widget, renders and collects. The vendor seller route carries the value through `additional_data` with no core schema change. A `sellersUpdated` workflow hook persists it. Each layer is additive: nothing built-in is replaced.
 </Info>
 
-## What you'll build
+## What you build
 
-A "Tax ID" prompt on the vendor store-setup surface. The vendor types a VAT number; it rides `additional_data` to `POST /vendor/sellers/:id`, and a workflow hook stores it durably through the [Custom Fields module](/rc/resources/customization/custom-fields).
+A "Tax ID" prompt on the vendor store-setup surface. The vendor types a VAT number. It rides `additional_data` to `POST /vendor/sellers/:id`, and a workflow hook stores it durably through the [Custom Fields module](/rc/resources/customization/custom-fields).
 
-## Register the typed targets (once)
+## Register the typed targets
 
-Widget zones are typed ids the vendor panel generates from its own pages and ships as `@mercurjs/vendor/extension-targets`. Register them once (shipped by `create-mercur-app`):
+Widget zones are typed ids the vendor panel generates from its own pages and ships as `@mercurjs/vendor/extension-targets`. Register them once. `create-mercur-app` ships this file for you.
 
 ```typescript apps/vendor/src/extension-targets.d.ts
 /// <reference types="@mercurjs/vendor/extension-targets" />
@@ -23,11 +26,11 @@ Widget zones are typed ids the vendor panel generates from its own pages and shi
 
 With it present, `seller.setup` autocompletes and an invalid zone fails `tsc` instead of silently doing nothing.
 
-## 1 — Render on the onboarding surface
+## Render on the onboarding surface
 
 <Steps>
   <Step title="Add the store-setup widget">
-    Drop a file under `src/widgets/`. Export the component as the **default** and a `config` with `zone: "seller.setup.before"`. The zone hands your component the `seller` as `data`:
+    Drop a file under `src/widgets/`. Export the component as the **default** and a `config` with `zone: "seller.setup.before"`. The zone hands your component the `seller` as `data`.
 
     ```tsx apps/vendor/src/widgets/tax-id-setup.tsx
     import "@mercurjs/vendor/extension-targets"
@@ -50,7 +53,7 @@ With it present, `seller.setup` autocompletes and an invalid zone fails `tsc` in
         mutationFn: () =>
           client.vendor.sellers.$id.mutate({
             $id: seller!.id,
-            // additional_data is accepted on every vendor seller route —
+            // additional_data is accepted on every vendor seller route.
             // it never touches the built-in seller columns.
             additional_data: { tax_id: taxId },
           }),
@@ -94,26 +97,26 @@ With it present, `seller.setup` autocompletes and an invalid zone fails `tsc` in
     ```
   </Step>
   <Step title="Understand where it renders">
-    `seller.setup` is hosted in two places, both passing the same `seller` as `data`:
+    `seller.setup` is hosted in two places, both passing the same `seller` as `data`.
 
     | Host | When it shows |
     |------|---------------|
-    | The vendor shell (above the page outlet) | On top-level routes — the dashboard "home" onboarding banner |
+    | The vendor shell (above the page outlet) | On top-level routes (the dashboard "home" onboarding banner) |
     | The store settings detail page | Always, above the store status banner |
 
-    A single widget file covers both. Multiple `seller.setup.before` / `.after` widgets stack in registration order.
+    A single widget file covers both. Multiple `seller.setup.before` and `.after` widgets stack in registration order.
   </Step>
 </Steps>
 
 <Note>
-  **`client` is your app's typed SDK.** `create-mercur-app` ships `apps/vendor/src/lib/client.ts` — a `createClient<Routes>()` instance. `client.vendor.sellers.$id.mutate(...)` is the typed `POST /vendor/sellers/:id`, so the request and response types match the backend route.
+  **`client` is your app's typed SDK.** `create-mercur-app` ships `apps/vendor/src/lib/client.ts`, a `createClient<Routes>()` instance. `client.vendor.sellers.$id.mutate(...)` is the typed `POST /vendor/sellers/:id`, so the request and response types match the backend route.
 </Note>
 
-## 2 — Carry the value through `additional_data`
+## Carry the value through additional_data
 
-You don't touch the seller route or its validator. Every vendor and admin seller route already wraps its body with `WithAdditionalData`, so an unknown `additional_data` object is accepted and forwarded into the workflow untouched:
+You don't touch the seller route or its validator. Every vendor and admin seller route already wraps its body with `WithAdditionalData`, so an unknown `additional_data` object is accepted and forwarded into the workflow untouched.
 
-```ts packages/core/src/api/vendor/sellers/[id]/route.ts (built-in — for reference)
+```ts packages/core/src/api/vendor/sellers/[id]/route.ts
 const { additional_data, ...update } = req.validatedBody
 
 await updateSellersWorkflow(req.scope).run({
@@ -125,15 +128,15 @@ await updateSellersWorkflow(req.scope).run({
 })
 ```
 
-That is the whole "wiring" step: your `{ tax_id }` payload arrives in the workflow as `additional_data` without a schema change.
+That is the whole wiring step. Your `{ tax_id }` payload arrives in the workflow as `additional_data` without a schema change.
 
-## 3 — Persist it from a workflow hook
+## Persist it from a workflow hook
 
 `updateSellersWorkflow` exposes a `sellersUpdated` hook that runs after the update with `{ sellers, additional_data }`. Subscribe to it in your Medusa app and persist the value.
 
 <Steps>
   <Step title="Declare a durable field">
-    Register a `Seller` custom field so the value gets a real, queryable column (no migration to hand-write):
+    Register a `Seller` custom field so the value gets a real, queryable column. No migration to hand-write.
 
     ```ts apps/api/medusa-config.ts
     module.exports = defineConfig({
@@ -153,12 +156,12 @@ That is the whole "wiring" step: your `{ tax_id }` payload arrives in the workfl
     })
     ```
 
-    ```bash
+    ```bash Terminal
     bunx medusa db:migrate
     ```
   </Step>
   <Step title="Subscribe to the hook">
-    Drop a file under `src/workflows/` in your Medusa app. Medusa imports everything under `src/workflows` at boot, so registering the hook is just defining it. Read `additional_data`, upsert through the Custom Fields service:
+    Drop a file under `src/workflows/` in your Medusa app. Medusa imports everything under `src/workflows` at boot, so registering the hook is just defining it. Read `additional_data` and upsert through the Custom Fields service.
 
     ```ts apps/api/src/workflows/hooks/seller-tax-id.ts
     import { updateSellersWorkflow } from "@mercurjs/core/workflows"
@@ -182,11 +185,11 @@ That is the whole "wiring" step: your `{ tax_id }` payload arrives in the workfl
     ```
 
     <Tip>
-      The hook fires for **every** seller update, not only your widget's — always guard on the field being present (`typeof taxId !== "string"`) so unrelated edits (name, address, status) pass through untouched.
+      The hook fires for **every** seller update, not only your widget's. Always guard on the field being present (`typeof taxId !== "string"`) so unrelated edits, such as name, address, or status, pass through untouched.
     </Tip>
   </Step>
   <Step title="Read it back">
-    The value is now linked to the seller and queryable through Medusa's remote query:
+    The value is now linked to the seller and queryable through Medusa's remote query.
 
     ```ts
     const { data: [seller] } = await query.graph({
@@ -217,27 +220,27 @@ seller.custom_fields.tax_id  (durable, queryable)
 
 ## Verify
 
-1. Open the vendor portal — the Tax ID prompt renders on the dashboard home and on **Settings → Store**.
-2. Enter a value and save — the mutation succeeds (`toast.success`) and hits `POST /vendor/sellers/:id`.
+1. Open the vendor portal. The Tax ID prompt renders on the dashboard home and on **Settings → Store**.
+2. Enter a value and save. The mutation succeeds (`toast.success`) and hits `POST /vendor/sellers/:id`.
 3. `query.graph({ entity: "seller", fields: ["custom_fields.tax_id"] })` returns the saved value.
-4. Edit an unrelated field (store name) — the seller update still works and the guard skips the upsert.
-5. Set `zone: "not.a.zone"` on the widget — `bun run lint` (tsc) fails against `WidgetZoneId`.
-6. Delete the widget file — the prompt disappears; the seller route and hook are unaffected.
+4. Edit an unrelated field, such as store name. The seller update still works and the guard skips the upsert.
+5. Set `zone: "not.a.zone"` on the widget. `bun run lint` (tsc) fails against `WidgetZoneId`.
+6. Delete the widget file. The prompt disappears. The seller route and hook are unaffected.
 
 ## FAQ
 
 <AccordionGroup>
   <Accordion title="Why additional_data instead of adding a body field?">
-    The seller routes' validators are core-owned. `additional_data` is the sanctioned escape hatch — every vendor and admin route wraps its body with `WithAdditionalData`, so you carry extra context to the workflow hooks without patching the request schema or forking the route.
+    The seller routes' validators are core-owned. `additional_data` is the sanctioned escape hatch. Every vendor and admin route wraps its body with `WithAdditionalData`, so you carry extra context to the workflow hooks without patching the request schema or forking the route.
   </Accordion>
   <Accordion title="Which seller workflows expose hooks?">
-    `updateSellersWorkflow` exposes `sellersUpdated`, and `createSellerAccountWorkflow` (the `POST /vendor/sellers` onboarding submit) exposes `sellerAccountCreated` — both carry `{ additional_data }`. Use `sellerAccountCreated` to capture data at first registration and `sellersUpdated` for later edits. See the [workflow references](/rc/references/workflows/seller/update-sellers).
+    `updateSellersWorkflow` exposes `sellersUpdated`, and `createSellerAccountWorkflow` (the `POST /vendor/sellers` onboarding submit) exposes `sellerAccountCreated`. Both carry `{ additional_data }`. Use `sellerAccountCreated` to capture data at first registration and `sellersUpdated` for later edits. See the [Store workflows](/platform/store/reference/workflows).
   </Accordion>
   <Accordion title="Can I store it on the seller's metadata instead?">
-    Yes — for a quick, non-queryable value, resolve the seller module in the hook and write to `seller.metadata`. Reach for the [Custom Fields module](/rc/resources/customization/custom-fields) when you want a typed, queryable column, which is what most onboarding data (tax IDs, compliance flags) needs.
+    Yes. For a quick, non-queryable value, resolve the seller module in the hook and write to `seller.metadata`. Reach for the [Custom Fields module](/rc/resources/customization/custom-fields) when you want a typed, queryable column, which is what most onboarding data such as tax IDs or compliance flags needs.
   </Accordion>
   <Accordion title="Does the hook run inside the request?">
-    Yes — workflow hooks run as steps of the workflow the route invokes, with the same compensation/rollback semantics. If your hook throws, the seller update rolls back. Keep slow or best-effort work (external syncs) in a subscriber on the emitted `seller.updated` event instead.
+    Yes. Workflow hooks run as steps of the workflow the route invokes, with the same compensation and rollback semantics. If your hook throws, the seller update rolls back. Keep slow or best-effort work, such as external syncs, in a subscriber on the emitted `seller.updated` event instead.
   </Accordion>
 </AccordionGroup>
 
@@ -245,7 +248,7 @@ seller.custom_fields.tax_id  (durable, queryable)
 
 <CardGroup cols={2}>
   <Card title="Extend a workflow" href="/rc/resources/customization/extend-a-workflow">
-    The full hook + compensation model for Mercur workflows.
+    The full hook and compensation model for Mercur workflows.
   </Card>
   <Card title="Custom Fields module" href="/rc/resources/customization/custom-fields">
     Durable, queryable storage for the data your hook writes.

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

@@ -1,20 +1,23 @@
 ---
-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."
+title: "How to Create Master Products and Offers"
+sidebarTitle: "Master Products & Offers"
+description: "Publish one master product, add two competing seller 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.
+Mercur runs a master catalog. One canonical product record holds 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).
+  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 three things: 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.
+You end with a published master product carrying offers from two sellers at different prices. Both offers are visible side by side through the Store API, each with its own calculated price.
 
 ## Product vs offer
 
+Three concerns live in three places. Keep them separate as you build.
+
 | Concern | Lives on | Example |
 |---------|----------|---------|
 | What the item is | Master product | "Classic White T-Shirt", variants, attributes |
@@ -25,55 +28,57 @@ A published master product with offers from two sellers at different prices, vis
 
 <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)).
+    As Seller A, create a product in the Vendor Portal, such as "Classic White T-Shirt" with a size variant. It enters as `proposed`. As the operator, confirm it in the Admin Panel so it becomes `published`. The review flow is covered by the [Product Edit](/platform/product-edit/overview) module.
 
-    The published product now belongs to the shared catalog. Note what it does **not** have: a seller price or seller stock.
+    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.
+  <Step title="Create Seller A's offer">
+    In Seller A's Vendor Portal, create an offer against the product's variant. Give it 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.
+      Offer inventory links 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.
+  <Step title="List the same product as Seller B">
+    As Seller B, find the same published product in the catalog and create a competing offer on the same variant: a 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:
+    The Store API exposes offers directly, each with its own calculated price. Fetch them by product id:
 
-    ```bash
+    ```bash Terminal
     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.
+    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.
+    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. 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
 
+Confirm the buy box behaves as expected.
+
 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.
+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 does not 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.
+    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.
+    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.
+    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>
 
@@ -84,6 +89,6 @@ A published master product with offers from two sellers at different prices, vis
     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.
+    What happens when a cart spans both sellers: the multi-vendor split.
   </Card>
 </CardGroup>

package/content/telemetry.mdx

@@ -39,7 +39,7 @@ When you run CLI commands (`create`, `init`, `add`, `registry:build`), the follo
 ### Using the CLI
 
 ```bash
-mercurjs telemetry --disable
+bunx @mercurjs/cli@latest telemetry --disable
 ```
 
 ### Using an environment variable
@@ -53,7 +53,7 @@ This is useful for CI/CD environments or shared configurations.
 ### Check current status
 
 ```bash
-mercurjs telemetry
+bunx @mercurjs/cli@latest telemetry
 ```
 
 ## Where Data Goes
@@ -63,5 +63,5 @@ Telemetry events are sent to `https://telemetry.mercurjs.com`. The data is used
 ## Re-enabling Telemetry
 
 ```bash
-mercurjs telemetry --enable
+bunx @mercurjs/cli@latest telemetry --enable
 ```