@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/resources/customization/custom-fields.mdx

@@ -3,37 +3,37 @@ title: "Custom Fields"
 description: "Extend any Medusa entity with additional fields without modifying core code."
 ---
 
-Custom Fields let you attach extra data to any existing Medusa entity — products, customers, orders, and more — through configuration alone. No migrations to write, no models to define. The module handles table creation and schema updates automatically when you run `db:migrate`.
+Custom Fields let you attach extra data to any existing Medusa entity, such as products, customers, and orders, through configuration alone. No migrations to write, no models to define. The module handles table creation and schema updates automatically when you run `db:migrate`.
 
 <Info>
-  **Where this sits in the stack.** Custom Fields is a Mercur module (`@mercurjs/core/modules/custom-fields`) layered on top of Medusa's standard module-link system — it generates the side table, the link, and the schema for you. It's the lightest way to add data to an entity.
+  **Where this sits in the stack.** Custom Fields is a Mercur module (`@mercurjs/core/modules/custom-fields`) layered on top of Medusa's standard module-link system. It generates the side table, the link, and the schema for you. It's the lightest way to add data to an entity.
 </Info>
 
 <Note>
-  **This is the *data* layer — not the panel UI.** This module *stores* extra data. The panel-side `defineCustomFieldsConfig` helper (see [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables)) *renders* fields into the built-in forms, sections, and tables. They share a name but solve different halves of the problem: use this module for storage and queryability, and the panel helper to expose the values to admins and vendors.
+  **This is the *data* layer, not the panel UI.** This module *stores* extra data. The panel-side `defineCustomFieldsConfig` helper (see [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables)) *renders* fields into the built-in forms, sections, and tables. They share a name but solve different halves of the problem: use this module for storage and queryability, and the panel helper to expose the values to admins and vendors.
 </Note>
 
 ## When to use Custom Fields
 
 <Tip>
-  **Use Custom Fields when** the data is a plain property of an existing entity — it belongs to exactly one record, has no lifecycle of its own, and you mostly read it alongside its parent. Typical cases:
+  **Use Custom Fields when** the data is a plain property of an existing entity. It belongs to exactly one record, has no lifecycle of its own, and you mostly read it alongside its parent. Typical cases:
 
   - A `brand`, `warranty_months`, or `is_featured` flag on a product
   - A `company_name` or loyalty `tier` on a customer
   - An internal `source` or `priority` tag on an order
 
-  You get a typed column, a default value, and queryability through `query.graph` — for the cost of one config entry and a `db:migrate`.
+  You get a typed column, a default value, and queryability through `query.graph`, for the cost of one config entry and a `db:migrate`.
 </Tip>
 
 <Warning>
   **Build a custom Medusa module instead when** the data outgrows "extra columns":
 
-  - It has its **own lifecycle** — created, updated, and deleted independently of the parent (e.g. reviews, support tickets)
+  - It has its **own lifecycle**, created, updated, and deleted independently of the parent (e.g. reviews, support tickets)
   - It has **relations** to more than one entity, or many records per parent
-  - It carries **business logic** — validation rules, state transitions, workflows
+  - It carries **business logic**, such as validation rules, state transitions, and workflows
   - You need **its own API routes** and permissions around it
 
-  Custom Fields is strictly one row per parent entity. Forcing a one-to-many or stateful concept into a JSON field works until it doesn't — model it as a module (or check whether a [block](/rc/learn/blocks) already ships it).
+  Custom Fields is strictly one row per parent entity. Forcing a one-to-many or stateful concept into a JSON field works until it doesn't. Model it as a module (or check whether a [block](/rc/learn/blocks) already ships it).
 </Warning>
 
 ## How it works
@@ -77,7 +77,7 @@ The Custom Fields module creates a separate table for each entity you extend (e.
     ```
 
     <Warning>
-      The key in `customFields` (e.g. `Product`, `Customer`) must match the entity name as registered in Medusa's joiner configuration — a mismatched name fails at link resolution, not at config load, so double-check spelling and casing.
+      The key in `customFields` (e.g. `Product`, `Customer`) must match the entity name as registered in Medusa's joiner configuration. A mismatched name fails at link resolution, not at config load, so double-check spelling and casing.
     </Warning>
   </Step>
   <Step title="Run migrations">
@@ -121,7 +121,7 @@ The Custom Fields module creates a separate table for each entity you extend (e.
 | -------------- | ---------- | ------- | ------------------------------------------------ |
 | `nullable`     | `boolean`  | `true`  | Whether the field can be null                    |
 | `defaultValue` | `any`      | `null`  | Default value for the field                      |
-| `enum`         | `string[]` | —       | Required for `enum` type. List of allowed values |
+| `enum`         | `string[]` | None    | Required for `enum` type. List of allowed values |
 
 ## Using the service directly
 
@@ -157,20 +157,20 @@ import {
 } from "@mercurjs/core/workflows";
 ```
 
-- **`upsertCustomFieldsStep`** — Takes `{ alias, data }` where `alias` is the entity name (e.g. `"product"`) and `data` contains the entity ID and field values.
-- **`deleteCustomFieldsStep`** — Takes `{ alias, ids }` to soft-delete custom field records by their IDs.
+- **`upsertCustomFieldsStep`:** takes `{ alias, data }` where `alias` is the entity name (e.g. `"product"`) and `data` contains the entity ID and field values.
+- **`deleteCustomFieldsStep`:** takes `{ alias, ids }` to soft-delete custom field records by their IDs.
 
 ## FAQ
 
 <AccordionGroup>
   <Accordion title="Can I add or change fields after the first migration?">
-    Yes — edit the `customFields` config and run `db:migrate` again; the module updates the side table's schema. Removing a field from config stops exposing it; treat destructive column changes with the same care as any schema migration.
+    Yes. Edit the `customFields` config and run `db:migrate` again; the module updates the side table's schema. Removing a field from config stops exposing it; treat destructive column changes with the same care as any schema migration.
   </Accordion>
   <Accordion title="How do vendors or admins edit these values from the panels?">
-    Through your own UI: add a page or a [panel custom field](/rc/resources/customization/extending-panels#custom-fields) and call an API route that uses the service's `upsert` — or compose `upsertCustomFieldsStep` into a workflow behind a [custom route](/rc/resources/tutorials/custom-api-route).
+    Through your own UI: add a page or a [panel custom field](/rc/resources/customization/extending-panels#custom-fields) and call an API route that uses the service's `upsert`, or compose `upsertCustomFieldsStep` into a workflow behind a [custom route](/rc/resources/tutorials/custom-api-route).
   </Accordion>
   <Accordion title="Can one entity have multiple custom-field records?">
-    No — the side table has a unique constraint on the parent ID, enforcing one-to-one. If you need many records per parent, that's a custom module, not custom fields.
+    No. The side table has a unique constraint on the parent ID, enforcing one-to-one. If you need many records per parent, that's a custom module, not custom fields.
   </Accordion>
 </AccordionGroup>
 

package/content/resources/customization/extend-a-workflow.mdx

@@ -1,6 +1,7 @@
 ---
-title: "Extend a workflow"
-description: "Inject custom logic into an existing Mercur workflow through hooks — without rewriting it."
+title: "How to Extend a Workflow"
+sidebarTitle: "Extend a Workflow"
+description: "Inject custom logic into an existing Mercur workflow through hooks, without rewriting it."
 ---
 
 <Note>
@@ -8,12 +9,14 @@ description: "Inject custom logic into an existing Mercur workflow through hooks
 </Note>
 
 <Info>
-  **Workflows are Medusa's extension model — Mercur keeps it.** Unlike the panels (where Mercur ships [its own customization framework](/rc/resources/customization/extending-panels)), backend logic follows Medusa conventions unchanged: Mercur's workflows expose hooks you inject steps into, with the same compensation/rollback semantics as any Medusa workflow. Skills learned in plain Medusa transfer here one-to-one.
+  **Workflows are Medusa's extension model, and Mercur keeps it.** Unlike the panels (where Mercur ships [its own customization framework](/rc/resources/customization/extending-panels)), backend logic follows Medusa conventions unchanged: Mercur's workflows expose hooks you inject steps into, with the same compensation/rollback semantics as any Medusa workflow. Skills learned in plain Medusa transfer here one-to-one.
 </Info>
 
+You extend a Mercur workflow by injecting your own step into a hook it exposes, so your logic runs inside the existing flow instead of a fork of it.
+
 ## Why hooks
 
-Extend behavior without forking or rewriting the workflow.
+Hooks let you add behavior without forking or rewriting the workflow.
 
 <Steps>
   <Step title="Pick the target hook">

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

@@ -1,47 +1,50 @@
 ---
-title: "Extending Panels"
-description: "Add pages, inject widgets, customize navigation, and extend forms and tables in the admin and vendor panels."
+title: "How to Extend the Panels"
+sidebarTitle: "Extend the Panels"
+description: "Add pages, widgets, navigation overrides, and form and table fields to the admin and vendor panels without forking."
 ---
 
-Both the admin panel and vendor portal use the same SDK (`@mercurjs/dashboard-sdk`). Customization is **file-based and convention-driven** — you add pages, widgets, and field extensions by dropping files under `src/`, and configure navigation through a single file. Nothing is registered by hand; the SDK crawls your `src/` at build time and wires everything in.
+Both the admin panel and the vendor portal run on the same SDK, `@mercurjs/dashboard-sdk`. You customize them by dropping files under `src/`.
+
+Customization is file-based and convention-driven. You add pages, widgets, and field extensions by placing files under `src/`, and you shape navigation through a single file. Nothing is registered by hand. The SDK crawls your `src/` at build time and wires everything in.
 
 <Info>
-  **Coming from Medusa?** The extension model is deliberately Medusa-shaped. The helpers you know — `defineWidgetConfig`, `defineRouteConfig`, `defineCustomFieldsConfig`, `createFormHelper` — all exist here, re-exported from `@mercurjs/dashboard-sdk` (without Medusa's `unstable_` prefix). What's different: Mercur ships **two** panels (admin *and* vendor) from one framework, so a file only ever targets the panel it lives in (there is no `surface` field), and widget zones carry a `before | after` placement suffix on the zone id. Everything is additive by default — your contribution augments the built-in page instead of replacing it.
+  **Coming from Medusa?** The extension model is deliberately Medusa-shaped. The helpers you know, such as `defineWidgetConfig`, `defineRouteConfig`, `defineCustomFieldsConfig`, and `createFormHelper`, all exist here, re-exported from `@mercurjs/dashboard-sdk` (without Medusa's `unstable_` prefix). Two things differ. Mercur ships two panels (admin and vendor) from one framework, so a file only ever targets the panel it lives in (there is no `surface` field), and widget zones carry a `before | after` placement suffix on the zone id. Everything is additive by default: your contribution augments the built-in page instead of replacing it.
 </Info>
 
 ## The extension mechanisms
 
-Every panel customization is **additive** — you augment a built-in page without owning it. One concern per file, discovered by the build-time crawl:
+Every panel customization is additive. You augment a built-in page without owning it. Each file handles one concern and is discovered by the build-time crawl:
 
-- **Widgets** — inject a React component at a named zone on a built-in page (`defineWidgetConfig`).
-- **Navigation** — reorder, hide, relabel, or re-parent built-in sidebar items (`defineNavigationConfig`).
-- **Custom fields** — add validated fields to built-in forms, replace/remove/add fields in detail sections, and add columns to list tables (`defineCustomFieldsConfig` + `createFormHelper`).
-- **Pages** — add a brand-new screen with a drop-in `page.tsx` route.
+- **Widgets:** inject a React component at a named zone on a built-in page (`defineWidgetConfig`).
+- **Navigation:** reorder, hide, relabel, or re-parent built-in sidebar items (`defineNavigationConfig`).
+- **Custom fields:** add validated fields to built-in forms, replace, remove, or add fields in detail sections, and add columns to list tables (`defineCustomFieldsConfig` plus `createFormHelper`).
+- **Pages:** add a brand-new screen with a drop-in `page.tsx` route.
 
 <Note>
-  Additive tools leave the rest of the built-in page — data fetching, filters, pagination, i18n — completely intact. A widget, a nav override, or a custom field changes only the spot you target.
+  Additive tools leave the rest of the built-in page completely intact, including data fetching, filters, pagination, and i18n. A widget, a nav override, or a custom field changes only the spot you target.
 </Note>
 
-## Choosing your extension mechanism
+## Choose your extension mechanism
 
-Rule of thumb: **injecting UI into an existing page? Use a widget. Adding data to a form or section? Use a custom field. Reshaping the sidebar? Use the navigation file. Adding a whole new screen? Drop in a route.**
+Use this rule of thumb. Injecting UI into an existing page? Use a widget. Adding data to a form or section? Use a custom field. Reshaping the sidebar? Use the navigation file. Adding a whole new screen? Drop in a route.
 
 | You want to… | Use | Why it's the right tool |
 |--------------|-----|------------------------|
-| Show a banner, panel, or CTA on a built-in page | A **widget** (`defineWidgetConfig`) | Renders at a named zone; the rest of the page is untouched — see [Add a widget](/rc/resources/tutorials/add-a-widget) |
-| Add a field to a built-in form, or add/replace/remove a field in a detail section | A **custom field** (`defineCustomFieldsConfig`) | Validated field wired into the existing form/section — see [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables) |
-| Add or override a column on a built-in list table | The `list` block of a **custom field** file | Model-scoped column extension — see [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables) |
-| Reorder / hide / relabel / re-parent sidebar items | The **navigation** file (`defineNavigationConfig`) | One host-owned `_navigation.ts` — see [Customize navigation](/rc/resources/tutorials/customize-navigation) |
-| Add a new screen or feature | A drop-in `page.tsx` route | New URL, auto-registered, sidebar entry via `config` — see [Add a page](/rc/resources/tutorials/custom-panel-page) |
-| Reuse a feature across projects | A [block](/rc/learn/blocks) | Ships API + admin + vendor files installable with `mercurjs add` |
+| Show a banner, panel, or CTA on a built-in page | A **widget** (`defineWidgetConfig`) | Renders at a named zone; the rest of the page is untouched. See [Add a widget](/rc/resources/tutorials/add-a-widget) |
+| Add a field to a built-in form, or add, replace, or remove a field in a detail section | A **custom field** (`defineCustomFieldsConfig`) | Validated field wired into the existing form or section. See [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables) |
+| Add or override a column on a built-in list table | The `list` block of a **custom field** file | Model-scoped column extension. See [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables) |
+| Reorder, hide, relabel, or re-parent sidebar items | The **navigation** file (`defineNavigationConfig`) | One host-owned `_navigation.ts`. See [Customize navigation](/rc/resources/tutorials/customize-navigation) |
+| Add a new screen or feature | A drop-in `page.tsx` route | New URL, auto-registered, sidebar entry via `config`. See [Add a page](/rc/resources/tutorials/custom-panel-page) |
+| Reuse a feature across projects | A [block](/rc/learn/blocks) | Ships API, admin, and vendor files installable with `mercurjs add` |
 
 ## Set up
 
-All configuration lives in the panel app's Vite config — there is no separate `mercur.config.ts`.
+All configuration lives in the panel app's Vite config. There is no separate `mercur.config.ts`.
 
 <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:
+    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'
@@ -63,16 +66,16 @@ All configuration lives in the panel app's Vite config — there is no separate
     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`.
+    The plugin doesn't read `.env` itself. Load environment variables in `vite.config.ts` (for example with Vite's `loadEnv`) and pass them into the plugin options, as the starter template does with `backendUrl`.
   </Step>
   <Step title="Register typed extension targets (once per panel)">
-    Widgets, navigation, and custom fields target **typed ids** (zone ids, nav item ids, model field ids) that each panel package generates from its own built-in pages and ships as `@mercurjs/{admin,vendor}/extension-targets`. Register them once so the ids resolve in every extension file, with a single ambient reference in your app's `src`:
+    Widgets, navigation, and custom fields target typed ids (zone ids, nav item ids, model field ids) that each panel package generates from its own built-in pages and ships as `@mercurjs/{admin,vendor}/extension-targets`. Register them once so the ids resolve in every extension file, with a single ambient reference in your app's `src`.
 
     ```typescript apps/vendor/src/extension-targets.d.ts
     /// <reference types="@mercurjs/vendor/extension-targets" />
     ```
 
-    (For the admin app, reference `@mercurjs/admin/extension-targets`.) With this file present, a typo in a zone, model, field, or nav id fails `tsc` instead of silently doing nothing at runtime. `create-mercur-app` ships this file already.
+    For the admin app, reference `@mercurjs/admin/extension-targets` instead. With this file present, a typo in a zone, model, field, or nav id fails `tsc` instead of silently doing nothing at runtime. `create-mercur-app` ships this file already.
   </Step>
   <Step title="Restart after config changes">
     Options are applied at build time through virtual modules. Adding or removing routes, widgets, and custom-field files hot-reloads automatically, but changes to the plugin options (in `vite.config.ts`) require a dev-server restart.
@@ -94,7 +97,7 @@ All configuration lives in the panel app's Vite config — there is no separate
 
 ## Widgets
 
-Inject a React component at a named zone on a built-in page. Drop a file under `src/widgets/`, export the component as the default and a `config` built with `defineWidgetConfig`:
+A widget injects a React component at a named zone on a built-in page. Drop a file under `src/widgets/`, export the component as the default and a `config` built with `defineWidgetConfig`.
 
 ```tsx src/widgets/product-list-banner.tsx
 import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
@@ -115,9 +118,9 @@ export default function ProductListBanner() {
 }
 ```
 
-The zone id is `<domain>.<view>.<placement>`. The placement is the last segment:
+The zone id reads `<domain>.<view>.<placement>`. The placement is the last segment:
 
-- `before` / `after` — stack your widget before or after the built-in content (multiple widgets stack in registration order).
+- `before` / `after`: stack your widget before or after the built-in content. Multiple widgets stack in registration order.
 
 Zones mounted today (**vendor portal**):
 
@@ -126,11 +129,11 @@ Zones mounted today (**vendor portal**):
 | `product.list.before` / `.after` | Vendor product list page |
 | `login.logo.*` / `login.before.*` / `login.after.*` | The public login screen (rendered before authentication) |
 
-The full set of valid zones is typed as `WidgetZoneId` and generated into each panel's `extension-targets.d.ts` — your editor autocompletes them, and an unknown zone fails `tsc`. Walk through it end to end in [Add a widget](/rc/resources/tutorials/add-a-widget).
+The full set of valid zones is typed as `WidgetZoneId` and generated into each panel's `extension-targets.d.ts`. Your editor autocompletes them, and an unknown zone fails `tsc`. Walk through it end to end in [Add a widget](/rc/resources/tutorials/add-a-widget).
 
 ## Navigation
 
-Custom drop-in routes place their own sidebar item via `defineRouteConfig` (see [Add a page](#add-a-page)). To reshape the **built-in** sidebar items, author a single host-owned file, `src/_navigation.ts`:
+Custom drop-in routes place their own sidebar item via `defineRouteConfig` (see [Add a page](#add-a-page)). To reshape the built-in sidebar items, author a single host-owned file, `src/_navigation.ts`.
 
 ```ts src/_navigation.ts
 import { defineNavigationConfig } from "@mercurjs/dashboard-sdk"
@@ -146,15 +149,15 @@ export default defineNavigationConfig({
 })
 ```
 
-- `id` targets any built-in item — top-level routes *or* nested children — by its stable id, typed as `NavItemId`.
-- `rank` orders an item within its parent; `hidden` removes it from the sidebar; `label` / `icon` relabel it; `nested` re-parents it (`nested: null` promotes to top level, typed against `NavParentId`).
-- Navigation is a **single host-owned file** — installed blocks cannot reorder the sidebar, so it stays one source of truth. It does not change custom routes, which still place themselves via `defineRouteConfig`.
+- `id` targets any built-in item, top-level routes or nested children, by its stable id, typed as `NavItemId`.
+- `rank` orders an item within its parent, `hidden` removes it from the sidebar, `label` and `icon` relabel it, and `nested` re-parents it (`nested: null` promotes to top level, typed against `NavParentId`).
+- Navigation is a single host-owned file. Installed blocks cannot reorder the sidebar, so it stays one source of truth. It does not change custom routes, which still place themselves via `defineRouteConfig`.
 
 Walk through it in [Customize navigation](/rc/resources/tutorials/customize-navigation).
 
 ## Custom fields
 
-Add validated fields to a model's built-in create/edit forms, replace/remove/add fields in its detail sections, and add columns to its list table — all from one model-scoped file. Drop `src/custom-fields/<model>.tsx` and default-export a `defineCustomFieldsConfig`:
+A custom field adds validated fields to a model's built-in create and edit forms, replaces, removes, or adds fields in its detail sections, and adds columns to its list table, all from one model-scoped file. Drop `src/custom-fields/<model>.tsx` and default-export a `defineCustomFieldsConfig`.
 
 ```tsx src/custom-fields/product.tsx
 import { defineCustomFieldsConfig } from "@mercurjs/dashboard-sdk"
@@ -198,22 +201,22 @@ export default defineCustomFieldsConfig({
 })
 ```
 
-- `forms[]` adds validated fields to a form `zone` (`create` / `edit` / `organize` / …). Input type and validation come from a Zod schema via `createFormHelper`; fields render through the standard `Form.Field` chain and participate in the existing submit + validation flow.
-- `displays[]` targets detail-page sections: keyed by field `id`, an entry **adds** a read-only row (unknown id), **replaces** a built-in field's render (matching id + `component`), or **removes** it (matching id + `component: null`).
-- `list` extends the model's list table: add/override columns by id, hide via `viewDefaults.columnVisibility`, reorder via `viewDefaults.columnOrder`.
-- Everything is typed against the panel-generated `CustomFieldsRegistry` — valid `model`, `zone`, and built-in field ids autocomplete; an invalid target fails `tsc`.
+- `forms[]` adds validated fields to a form `zone` (`create`, `edit`, `organize`, and so on). Input type and validation come from a Zod schema via `createFormHelper`. Fields render through the standard `Form.Field` chain and participate in the existing submit and validation flow.
+- `displays[]` targets detail-page sections, keyed by field `id`. An entry **adds** a read-only row (unknown id), **replaces** a built-in field's render (matching id plus `component`), or **removes** it (matching id plus `component: null`).
+- `list` extends the model's list table: add or override columns by id, hide via `viewDefaults.columnVisibility`, reorder via `viewDefaults.columnOrder`.
+- Everything is typed against the panel-generated `CustomFieldsRegistry`. Valid `model`, `zone`, and built-in field ids autocomplete, and an invalid target fails `tsc`.
 
 <Warning>
-  **Panel custom fields vs. the Custom Fields module.** `defineCustomFieldsConfig` (this section) is a **UI** surface — it renders, validates, and displays fields in the panels. It does not create database columns. To *store* extra data on an entity, use the backend [Custom Fields module](/rc/resources/customization/custom-fields), or wire 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`.
+  **Panel custom fields vs. the Custom Fields module.** `defineCustomFieldsConfig` (this section) is a UI surface. It renders, validates, and displays fields in the panels. It does not create database columns. To store extra data on an entity, use the backend [Custom Fields module](/rc/resources/customization/custom-fields), or wire 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`.
 </Warning>
 
-Full walkthrough (forms, sections, list columns): [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables).
+For the full walkthrough (forms, sections, and list columns), see [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables).
 
 ## 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:
+    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"
@@ -231,13 +234,13 @@ Full walkthrough (forms, sections, list columns): [Extend forms and tables](/rc/
     ```
   </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.
+    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 |
+    | `icon` | `ComponentType` | Icon component (for example 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 |
@@ -245,17 +248,17 @@ Full walkthrough (forms, sections, list columns): [Extend forms and tables](/rc/
     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.
+    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. Any other path is added alongside the built-in routes. Delete the file and the built-in page returns. To change *part* of a built-in page without owning it, prefer a widget or a custom field.
+  **Matching paths replace, new paths append.** If your route's path matches a built-in page (for example `src/routes/products/page.tsx` maps to `/products`), your page **replaces** the built-in one. Any other path is added alongside the built-in routes. Delete the file and the built-in page returns. To change part of a built-in page without owning it, prefer a widget or a custom field.
 </Info>
 
 ### Routing conventions
 
-File paths map to URL routes automatically:
+File paths map to URL routes automatically.
 
 | File path | Route | Description |
 |-----------|-------|-------------|
@@ -269,7 +272,7 @@ File paths map to URL routes automatically:
 
 ## Branding
 
-Set `name` and `logo` in the plugin options to customize the sidebar header:
+Set `name` and `logo` in the plugin options to customize the sidebar header.
 
 ```typescript vite.config.ts
 mercurDashboardPlugin({
@@ -329,22 +332,22 @@ mercurDashboardPlugin({
     Yes. `defineWidgetConfig` is re-exported from `@mercurjs/dashboard-sdk` and drives file-based widgets under `src/widgets/`. The difference from Medusa is the `before | after` placement suffix on the zone id and that each panel ships its own typed zone set. See [Add a widget](/rc/resources/tutorials/add-a-widget).
   </Accordion>
   <Accordion title="How do I add a field to a built-in form or detail page?">
-    Use `defineCustomFieldsConfig` in `src/custom-fields/<model>.tsx` — `forms[]` adds validated fields to create/edit forms, and `displays[]` adds/replaces/removes fields in detail sections. See [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables).
+    Use `defineCustomFieldsConfig` in `src/custom-fields/<model>.tsx`. `forms[]` adds validated fields to create and edit forms, and `displays[]` adds, replaces, or removes fields in detail sections. See [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables).
   </Accordion>
   <Accordion title="How do I change just one part of a built-in page?">
-    For a spot inside the page (a banner, an extra field, a column), use a [widget](#widgets) or a [custom field](#custom-fields) — the rest of the page keeps all its behavior.
+    For a spot inside the page (a banner, an extra field, a column), use a [widget](#widgets) or a [custom field](#custom-fields). The rest of the page keeps all its behavior.
   </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.
+    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="Why does my widget / custom field / nav override not type-check?">
-    Make sure the panel's typed targets are registered — a single `src/extension-targets.d.ts` with `/// <reference types="@mercurjs/vendor/extension-targets" />` (or the admin equivalent). Without it, zone/model/nav ids aren't known to TypeScript. `create-mercur-app` ships this file.
+    Make sure the panel's typed targets are registered with a single `src/extension-targets.d.ts` containing `/// <reference types="@mercurjs/vendor/extension-targets" />` (or the admin equivalent). Without it, zone, model, and nav ids aren't known to TypeScript. `create-mercur-app` ships this file.
   </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.
+    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?">
-    Both panels use the same SDK and conventions, and a file only targets the panel it lives in. Which built-in zones, models, and nav ids exist differs per panel (each ships its own `extension-targets.d.ts`). Today the widget zones and product custom fields are mounted in the **vendor** portal; navigation overrides work in both.
+    Both panels use the same SDK and conventions, and a file only targets the panel it lives in. Which built-in zones, models, and nav ids exist differs per panel (each ships its own `extension-targets.d.ts`). Today the widget zones and product custom fields are mounted in the **vendor** portal, and navigation overrides work in both.
   </Accordion>
 </AccordionGroup>
 

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

@@ -1,6 +1,7 @@
 ---
-title: "Medusa Cloud deployment"
-description: "Deploy Mercur — backend, admin panel, and vendor panel — on Medusa Cloud."
+title: "Medusa Cloud"
+sidebarTitle: "Medusa Cloud"
+description: "Deploy the Mercur backend, admin panel, and vendor panel on Medusa Cloud."
 ---
 
 ## Introduction
@@ -12,8 +13,8 @@ Head to the [Medusa Cloud signup page](https://cloud.medusajs.com/signup) to get
 <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.
+  panels are built together with the backend and served from the same origin.
+  No separate hosting is needed.
 </Info>
 
 ## How it works
@@ -22,21 +23,21 @@ 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
+  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.
+  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.
+silently point at `http://localhost:9000`. 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 Mercur project created with [`@mercurjs/cli`](/learn/introduction) 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.)
 
@@ -54,13 +55,13 @@ silently point at `http://localhost:9000` — so make sure to set it as describe
   <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.
+    - **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.
+    - **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)
+    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.
@@ -70,11 +71,11 @@ silently point at `http://localhost:9000` — so make sure to set it as describe
 
     ```bash
     # Panels (build-time): the deployed backend origin, baked into the admin and
-    # vendor panels. Enable the **Build** toggle for this variable — the panels
+    # 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
+    # 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
@@ -119,7 +120,7 @@ silently point at `http://localhost:9000` — so make sure to set it as describe
   </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.
+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
 
@@ -131,7 +132,7 @@ Once the build succeeds, everything is served from `https://<your-subdomain>.med
 | 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`.
+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
@@ -144,14 +145,14 @@ Open the admin panel and sign in with the **Initial user** you configured in the
 ## FAQ
 
 <AccordionGroup>
-  <Accordion title="A panel shows a 'Dashboard not built' page — what went wrong?">
+  <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.
+    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>
 
@@ -161,7 +162,7 @@ Open the admin panel and sign in with the **Initial user** you configured in the
   <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 title="Overview" href="/learn/introduction">
+    Set up Mercur and run a marketplace.
   </Card>
 </CardGroup>