@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/resources/tutorials/add-order-detail-button.mdx

@@ -1,21 +1,22 @@
 ---
-title: "Add a button to order details"
-description: "Drop a 'Copy link' button onto the vendor order detail page with a widget — no forking, no page override."
+title: "How to Add an Action Button"
+sidebarTitle: "Add an Action Button"
+description: "Add a Copy link button to the vendor order detail page with a widget, without forking or overriding the page."
 ---
 
-The order detail page is a built-in panel screen you don't own. To add a small piece of UI to it — a button, a badge, a note — you don't copy the page. You drop a **widget** at one of its zones, and the SDK renders your component there while the rest of the page keeps working exactly as shipped.
+Add a small piece of UI to a built-in panel screen without copying it.
 
-This tutorial adds a **"Copy link"** button to the order summary section that copies a link to the order.
+The order detail page is a panel screen you don't own. To add a button, a badge, or a note to it, you drop a **widget** at one of its zones. The SDK renders your component there, and the rest of the page keeps working exactly as shipped. This tutorial adds a **Copy link** button to the order summary section that copies a link to the order.
 
 <Info>
-  **Additive, not a replacement.** A widget layers your component onto a built-in page at a documented zone. Reach for it first whenever you just want to *add* something to an existing screen.
+  A widget is additive, not a replacement. It layers your component onto a built-in page at a documented zone. Reach for it first whenever you just want to add something to an existing screen.
 </Info>
 
 ## Add the button
 
 <Steps>
   <Step title="Create the widget file">
-    Drop a file under `src/widgets/`. Export the component as the **default** and a `config` built with `defineWidgetConfig`. Target `orders.detail.summary.after` — your component renders in the order summary section footer and receives the loaded order as `data`.
+    Drop a file under `src/widgets/`. Export the component as the **default** and a `config` built with `defineWidgetConfig`. Target `orders.detail.summary.after`. Your component renders in the order summary section footer and receives the loaded order as `data`.
 
     ```tsx apps/vendor/src/widgets/order-copy-link.tsx
     import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
@@ -52,24 +53,30 @@ This tutorial adds a **"Copy link"** button to the order summary section that co
     export default OrderCopyLink
     ```
   </Step>
-  <Step title="Understand the zone id">
-    A zone id is `<domain>.<view>.<slot>.<placement>`. The last segment is the placement:
+
+  <Step title="Read the zone id">
+    A zone id is `<domain>.<view>.<slot>.<placement>`. The last segment is the placement.
 
     | Placement | Effect |
     |-----------|--------|
     | `before` | Renders before the built-in content of the zone |
     | `after` | Renders after the built-in content |
 
-    Multiple `before` / `after` widgets on the same zone stack in registration order.
+    Multiple `before` or `after` widgets on the same zone stack in registration order.
   </Step>
+
   <Step title="Reload the panel">
-    Start the project (`bun run dev`) and open any order in the vendor portal. Widget files hot-reload — the "Copy link" button appears in the summary section footer, and the rest of the page is untouched.
+    Start the project and open any order in the vendor portal. Widget files hot-reload. The Copy link button appears in the summary section footer, and the rest of the page is untouched.
+
+    ```bash Terminal
+    bun run dev
+    ```
   </Step>
 </Steps>
 
 ## Order detail zones
 
-Zones mounted on the vendor order detail page:
+These zones are mounted on the vendor order detail page.
 
 | Zone | Where it renders |
 |------|------------------|
@@ -77,27 +84,33 @@ Zones mounted on the vendor order detail page:
 | `orders.detail.main.before` / `.after` | Around the main column (summary, payment, fulfillment) |
 | `orders.detail.side.before` / `.after` | Around the sidebar (customer, activity) |
 
-Each is passed the loaded `order` as `data`. The full, valid set is typed as `WidgetZoneId` and generated from the panel's own zone hosts — let your editor autocomplete `zone:` to see every option. A zone no page renders can't be targeted and won't type-check.
+Each zone is passed the loaded `order` as `data`. The full, valid set is typed as `WidgetZoneId` and generated from the panel's own zone hosts. Let your editor autocomplete `zone:` to see every option.
+
+<Tip>
+  A zone that no page renders can't be targeted and won't type-check. Set `zone: "not.a.zone"` and `tsc` (`bun run lint`) fails with a "not assignable to `WidgetZoneId`" error.
+</Tip>
 
 ## Verify
 
-1. Open an order — the "Copy link" button renders in the summary section footer.
-2. Click it — the link is copied and a toast appears.
-3. Change the zone to `orders.detail.side.before` and reload — the button moves to the top of the sidebar.
-4. Set `zone: "not.a.zone"` — `tsc` (`bun run lint`) fails with a "not assignable to `WidgetZoneId`" error.
-5. Delete the file — the button disappears; nothing else changed.
+Confirm the widget works end to end.
+
+1. Open an order. The Copy link button renders in the summary section footer.
+2. Click it. The link is copied and a toast appears.
+3. Change the zone to `orders.detail.side.before` and reload. The button moves to the top of the sidebar.
+4. Set `zone: "not.a.zone"`. `tsc` (`bun run lint`) fails with a "not assignable to `WidgetZoneId`" error.
+5. Delete the file. The button disappears, and nothing else changed.
 
 ## FAQ
 
 <AccordionGroup>
   <Accordion title="What can I read from the order?">
-    The zone passes the loaded order as `data` (`HttpTypes.AdminOrder`) — id, display id, totals, items, `payment_collections`, customer, and more. Build the link (or any UI) from it.
+    The zone passes the loaded order as `data` (`HttpTypes.AdminOrder`): id, display id, totals, items, `payment_collections`, customer, and more. Build the link (or any UI) from it.
   </Accordion>
   <Accordion title="Can a block ship this instead of the host app?">
-    Yes. Put the same file in a [block](/rc/learn/blocks)'s `vendor_ui` entry under `src/widgets/`; installing the block adds the button with no wiring.
+    Yes. Put the same file in a [block](/rc/learn/blocks)'s `vendor_ui` entry under `src/widgets/`. Installing the block adds the button with no wiring.
   </Accordion>
   <Accordion title="Can I render more than a button?">
-    The zone renders any React component — a badge, an action menu, a whole section. You have the full order in `data`.
+    The zone renders any React component, such as a badge, an action menu, or a whole section. You have the full order in `data`.
   </Accordion>
 </AccordionGroup>
 

package/content/resources/tutorials/attributes-and-variant-axes.mdx

@@ -1,48 +1,49 @@
 ---
-title: "Create attributes and variant axes"
-description: "Build the attribute catalog: a filterable attribute, a variant axis backed by a native product option, and an inline product-scoped axis."
+title: "How to Create Variant-Axis Attributes"
+sidebarTitle: "Create Variant-Axis Attributes"
+description: "Build an attribute catalog with a filterable attribute, a global variant axis, and an inline product-scoped axis."
 ---
 
-Attributes give the shared catalog structured, typed data — and for `multi_select` attributes, they can drive variant generation. This tutorial sets up the two kinds that matter most: a plain filterable attribute and a **variant axis**, which under the hood is a native Medusa global product option.
+Attributes give the shared catalog structured, typed data. For `multi_select` attributes, they can also drive variant generation.
 
-<Warning>
-  This is a release-candidate feature built on Medusa's global product options (Medusa 2.16 preview). Details may still shift before the stable release.
-</Warning>
+This tutorial sets up the two kinds that matter most: a plain filterable attribute and a variant axis. A variant axis is a native Medusa global product option under the hood.
 
 <Info>
-  **A variant axis IS a product option.** Attributes marked `is_variant_axis` aren't a parallel system bolted onto products — each one mirrors one-to-one onto a Medusa `ProductOption` and its values. Variants are then built with Medusa's standard machinery (`variants[].options`), exactly as in a plain Medusa project. Non-axis attributes never become options; they attach as plain value links. This is why only `multi_select` attributes can be axes — an axis needs an enumerable set of values to combine into variants.
+  **A variant axis IS a product option.** Attributes marked `is_variant_axis` are not a parallel system bolted onto products. Each one mirrors one-to-one onto a Medusa `ProductOption` and its values. Variants are then built with Medusa's standard machinery (`variants[].options`), exactly as in a plain Medusa project. Non-axis attributes never become options. They attach as plain value links. This is why only `multi_select` attributes can be axes: an axis needs an enumerable set of values to combine into variants.
 </Info>
 
 ## What you'll build
 
-- A global `Material` attribute (multi-select, filterable) used for storefront filtering.
-- A global `Color` variant axis shared across the catalog.
-- An inline, product-scoped `Fit` axis created on the fly from a product form.
+- **Material:** a global `multi_select`, filterable attribute used for storefront filtering.
+- **Color:** a global variant axis shared across the catalog.
+- **Fit:** an inline, product-scoped axis created on the fly from a product form.
 
 ## Global vs product-scoped
 
 | Kind | Backed by | Appears in the global catalog? | Use for |
 |------|-----------|-------------------------------|---------|
-| Global attribute | Shared `ProductOption` (when axis) or value links | Yes | Data every product can use — Material, Color, Condition |
+| Global attribute | Shared `ProductOption` (when axis) or value links | Yes | Data every product can use, such as Material, Color, or Condition |
 | Product-scoped attribute | Exclusive, product-owned option (when axis) | No | One-off fields or axes for a single product |
 
 ## Build the attribute catalog
 
 <Steps>
   <Step title="Create a filterable attribute">
-    In the Admin Panel, the operator owns the attribute catalog. Create **Material** as a global `multi_select` attribute with values like Cotton, Wool, Linen, and turn on `is_filterable`. Global attributes (`product_id = null`) can be attached to any product and linked to categories so the right attributes surface for the right product types.
+    In the Admin Panel, the operator owns the attribute catalog. Create **Material** as a global `multi_select` attribute with values like Cotton, Wool, or Linen, and turn on `is_filterable`.
 
-    Since it's not a variant axis, Material describes the product — it will never generate variants.
+    Global attributes (`product_id = null`) can be attached to any product and linked to categories, so the right attributes surface for the right product types.
+
+    Since it is not a variant axis, Material describes the product. It never generates variants.
   </Step>
   <Step title="Create a variant axis">
-    Create **Color** the same way, but enable `is_variant_axis`. This is only allowed for `multi_select` attributes — the platform rejects the flag on any other type.
+    Create **Color** the same way, but enable `is_variant_axis`. This is only allowed for `multi_select` attributes. The platform rejects the flag on any other type.
 
-    Because Color is a **global** axis, it's backed by one shared product option. Every product that uses it links to that option, restricted to the subset of values the product actually offers — so "Color" means the same thing across the whole catalog, while one product can offer only Red and Blue.
+    Because Color is a **global** axis, it is backed by one shared product option. Every product that uses it links to that option, restricted to the subset of values the product actually offers. So "Color" means the same thing across the whole catalog, while one product can offer only Red and Blue.
   </Step>
   <Step title="Attach attributes to a product">
-    Products manage attributes through one **batch** endpoint that adds, removes, and updates in a single request:
+    Products manage attributes through one **batch** endpoint that adds, removes, and updates in a single request.
 
-    ```bash
+    ```bash Terminal
     curl -X POST "http://localhost:9000/vendor/products/prod_123/attributes/batch" \
       -H "Authorization: Bearer <token>" \
       -H "Content-Type: application/json" \
@@ -54,12 +55,12 @@ Attributes give the shared catalog structured, typed data — and for `multi_sel
       }'
     ```
 
-    At product create time, the same entry shape is passed as a unified `attributes[]` array. Because Color is an axis, selecting Red and Blue makes them available as variant options — variants are then defined with standard Medusa `variants[].options` mapping `"Color"` to `"Red"` or `"Blue"`.
+    At product create time, the same entry shape is passed as a unified `attributes[]` array. Because Color is an axis, selecting Red and Blue makes them available as variant options. Variants are then defined with standard Medusa `variants[].options` mapping `"Color"` to `"Red"` or `"Blue"`.
   </Step>
   <Step title="Add an inline product-scoped axis">
-    Sometimes one product needs an axis that doesn't belong in the shared catalog. Define it **inline** by `title` instead of referencing an `id`:
+    Sometimes one product needs an axis that does not belong in the shared catalog. Define it **inline** by `title` instead of referencing an `id`.
 
-    ```bash
+    ```bash Terminal
     curl -X POST "http://localhost:9000/vendor/products/prod_123/attributes/batch" \
       -H "Authorization: Bearer <token>" \
       -H "Content-Type: application/json" \
@@ -70,18 +71,18 @@ Attributes give the shared catalog structured, typed data — and for `multi_sel
       }'
     ```
 
-    This creates a product-scoped attribute on the fly, backed by an **exclusive**, product-owned option. It won't appear in the global attribute list — it belongs to this product alone.
+    This creates a product-scoped attribute on the fly, backed by an **exclusive**, product-owned option. It does not appear in the global attribute list. It belongs to this product alone.
   </Step>
 </Steps>
 
 <Note>
-  Attribute changes on products submitted by vendors flow through the same [change-request pipeline](/rc/learn/product-requests) as other product edits — `ATTRIBUTE_ADD` / `ATTRIBUTE_UPDATE` / `ATTRIBUTE_REMOVE` actions the operator reviews.
+  Attribute changes on products submitted by vendors flow through the same [change-request pipeline](/rc/learn/product-requests) as other product edits: `ATTRIBUTE_ADD`, `ATTRIBUTE_UPDATE`, or `ATTRIBUTE_REMOVE` actions the operator reviews.
 </Note>
 
 ## Verify
 
-1. **Material** and **Color** appear in the Admin Panel's attribute catalog; **Fit** does not (it's product-scoped).
-2. The product detail shows Material as descriptive data and Color/Fit as variant axes.
+1. **Material** and **Color** appear in the Admin Panel's attribute catalog. **Fit** does not, because it is product-scoped.
+2. The product detail shows Material as descriptive data and Color and Fit as variant axes.
 3. The product's variants combine the selected Color and Fit values, built from real product options.
 4. The Store API exposes Material for filtering on product listings (`is_filterable`).
 
@@ -89,13 +90,13 @@ Attributes give the shared catalog structured, typed data — and for `multi_sel
 
 <AccordionGroup>
   <Accordion title="Why can't a text or toggle attribute be a variant axis?">
-    An axis needs an enumerable, finite value set to combine into variants — Red/Blue × Slim/Regular. Free text has no enumerable values, and a toggle's two fixed values rarely describe purchasable variations. Only `multi_select` qualifies, and the platform enforces it.
+    An axis needs an enumerable, finite value set to combine into variants, for example Red/Blue times Slim/Regular. Free text has no enumerable values, and a toggle's two fixed values rarely describe purchasable variations. Only `multi_select` qualifies, and the platform enforces it.
   </Accordion>
   <Accordion title="What's the difference between a value link and an option?">
-    Non-axis attributes attach to a product as plain **value links** — descriptive data for display and filtering. Axis attributes are mirrored onto real Medusa **product options**, which participate in variant generation. Same authoring UI, structurally different underneath.
+    Non-axis attributes attach to a product as plain **value links**: descriptive data for display and filtering. Axis attributes are mirrored onto real Medusa **product options**, which participate in variant generation. Same authoring UI, structurally different underneath.
   </Accordion>
   <Accordion title="Can I promote a product-scoped attribute to a global one later?">
-    Not automatically — a product-scoped axis is backed by an exclusive option owned by that product. Create the global attribute in the catalog and re-attach products to it; treat inline attributes as intentionally local.
+    Not automatically. A product-scoped axis is backed by an exclusive option owned by that product. Create the global attribute in the catalog and re-attach products to it. Treat inline attributes as intentionally local.
   </Accordion>
 </AccordionGroup>
 

package/content/resources/tutorials/build-a-block.mdx

@@ -1,17 +1,20 @@
 ---
-title: "Build your own block"
-description: "Author a reusable feature as a block — backend, panel UI, and docs — build it into a registry, and install it into any Mercur project."
+title: "How to Build a Block"
+sidebarTitle: "Build a Block"
+description: "Author a reusable feature as a block covering backend, panel UI, and docs, then build it into a registry and install it into any Mercur project."
 ---
 
-Blocks are how features travel between Mercur projects: not as npm packages you depend on, but as **source code copied into the target project**. Anything you've built once — a module, workflows, routes, panel pages — can be packaged as a block, published through a registry, and installed with `mercurjs add`. This tutorial builds a minimal "announcements" block and ships it through your own registry.
+Blocks are how features travel between Mercur projects. You ship them as source code copied into the target project, not as npm packages you depend on.
+
+Anything you build once, such as a module, workflows, routes, or panel pages, can be packaged as a block, published through a registry, and installed with `mercurjs add`. This tutorial builds a minimal "announcements" block and ships it through your own registry.
 
 <Info>
-  **Blocks are source, not dependencies.** When someone installs your block, they get the files — editable, diffable, theirs. Updates are opt-in via `mercurjs diff` and `add --overwrite`, never forced through a lockfile. That's the trade: you give up automatic upgrades, users gain full ownership. Design blocks so they're readable after install.
+  **Blocks are source, not dependencies.** When someone installs your block, they get the files: editable, diffable, theirs. Updates are opt-in via `mercurjs diff` and `add --overwrite`, never forced through a lockfile. That is the trade: you give up automatic upgrades, and users gain full ownership. Design blocks so they read cleanly after install.
 </Info>
 
 ## What you'll build
 
-An `announcements` block containing a module (data model + service), a vendor API route, and a vendor portal page — built into registry JSON and installed into a Mercur project.
+You build an `announcements` block containing a module (data model and service), a vendor API route, and a vendor portal page. Then you build it into registry JSON and install it into a Mercur project.
 
 ## File types and where they land
 
@@ -44,9 +47,11 @@ Each file in a block carries a `type` that maps to an alias in the consumer's `b
                 └── page.tsx               # vendor portal page
     ```
 
-    Write the files exactly as they should land in a consumer's project — real imports, real Medusa module definitions. The build step resolves imports and rewrites them to the consumer's path aliases at install time. For the panel page, use the same conventions as any [custom panel page](/rc/resources/tutorials/custom-panel-page): a default export plus a `config` for the sidebar entry.
+    Write the files exactly as they should land in a consumer's project: real imports, real Medusa module definitions. The build step resolves imports and rewrites them to the consumer's path aliases at install time. For the panel page, use the same conventions as any [custom panel page](/rc/resources/tutorials/custom-panel-page): a default export plus a `config` for the sidebar entry.
   </Step>
   <Step title="Declare it in registry.json">
+    Add one entry per block to the `items` array.
+
     ```json registry.json
     {
       "$schema": "https://registry.mercurjs.com/registry.json",
@@ -70,20 +75,22 @@ Each file in a block carries a `type` that maps to an alias in the consumer's `b
     }
     ```
 
-    Two fields do the heavy lifting: **`type`** on each file decides where it lands, and **`docs`** is the markdown shown after install. Put every manual step in `docs` — module registration, migrations, middleware, codegen. It's the only instruction the installer sees.
+    Two fields do the heavy lifting. **`type`** on each file decides where the file lands, and **`docs`** is the markdown shown after install. Put every manual step in `docs`: module registration, migrations, middleware, codegen. It is the only instruction the installer sees.
   </Step>
   <Step title="Build the registry">
-    ```bash
+    Run the CLI build from the registry root.
+
+    ```bash Terminal
     bunx @mercurjs/cli@latest build
     ```
 
-    This reads `registry.json`, resolves each block's imports, embeds file contents, and writes one JSON per block into `r/` — `r/announcements.json`, plus an index `r/registry.json`.
+    This reads `registry.json`, resolves each block's imports, embeds file contents, and writes one JSON per block into `r/`: `r/announcements.json`, plus an index `r/registry.json`.
   </Step>
   <Step title="Host it">
-    Serve the `r/` directory from any static host (GitHub Pages, Vercel, S3 — anything that makes `{name}.json` publicly reachable).
+    Serve the `r/` directory from any static host (GitHub Pages, Vercel, S3, or anything that makes `{name}.json` publicly reachable).
   </Step>
   <Step title="Install it into a project">
-    In a consumer project, register your registry in `blocks.json` and install:
+    In a consumer project, register your registry in `blocks.json`.
 
     ```json blocks.json
     {
@@ -93,7 +100,9 @@ Each file in a block carries a `type` that maps to an alias in the consumer's `b
     }
     ```
 
-    ```bash
+    Then install the block.
+
+    ```bash Terminal
     bunx @mercurjs/cli@latest add @my-org/announcements
     ```
 
@@ -103,19 +112,21 @@ Each file in a block carries a `type` that maps to an alias in the consumer's `b
 
 ## Verify
 
+Confirm the block built and installed correctly:
+
 1. `r/announcements.json` exists after the build and embeds every file's content.
 2. In the consumer project, the files landed under the alias-mapped paths and imports resolve.
 3. After following your own `docs` steps (module registration, migrations, codegen), `bun run build` passes and the vendor portal shows the Announcements page.
-4. `bunx @mercurjs/cli@latest diff @my-org/announcements` reports no changes — the installed copy matches the registry.
+4. `bunx @mercurjs/cli@latest diff @my-org/announcements` reports no changes. The installed copy matches the registry.
 
 ## FAQ
 
 <AccordionGroup>
   <Accordion title="How do I depend on another block or an npm package?">
-    Other blocks go in `registryDependencies` (e.g. `@my-org/reviews`) — the CLI installs them in order automatically. NPM packages go in `dependencies`; the build also auto-detects them from your imports, so you rarely list transitive ones by hand.
+    Other blocks go in `registryDependencies` (for example `@my-org/reviews`). The CLI installs them in order automatically. NPM packages go in `dependencies`. The build also auto-detects them from your imports, so you rarely list transitive ones by hand.
   </Accordion>
   <Accordion title="Can I make the registry private?">
-    Yes — use the object form with headers in the consumer's `blocks.json`: `{ "url": "…/{name}.json", "headers": { "Authorization": "Bearer ${REGISTRY_TOKEN}" } }`. The env var is resolved from the installer's environment. See [Registry](/rc/learn/registry).
+    Yes. Use the object form with headers in the consumer's `blocks.json`: `{ "url": "…/{name}.json", "headers": { "Authorization": "Bearer ${REGISTRY_TOKEN}" } }`. The env var is resolved from the installer's environment. See [Registry](/rc/learn/registry).
   </Accordion>
   <Accordion title="How do consumers get updates to my block?">
     They run `mercurjs diff <block>` to compare their local copy against your registry, then `add --overwrite` to take the new version. Because blocks are source, consumers with local edits merge deliberately rather than being force-upgraded.

package/content/resources/tutorials/custom-api-route.mdx

@@ -1,23 +1,26 @@
 ---
-title: "Add a custom API route"
-description: "Create a backend endpoint, regenerate the route map, and call it from a panel page with full type safety end to end."
+title: "How to Add a Custom API Route"
+sidebarTitle: "Add a Custom Route"
+description: "Add a backend endpoint, regenerate the route map, and call it from a panel page with full type safety."
 ---
 
-Mercur's typed API client isn't hand-maintained — its types are **generated from your actual route files**. That means a custom endpoint you add to the API package becomes a first-class, fully typed client call after one codegen run. This tutorial walks the whole loop: route → codegen → typed call from a custom panel page.
+Mercur's typed API client is generated from your actual route files, not hand-maintained. A custom endpoint you add to the API package becomes a first-class, fully typed client call after one codegen run.
+
+This tutorial walks the whole loop: route, then codegen, then a typed call from a custom panel page.
 
 <Info>
-  **The contract is generated, not declared.** You never write an interface for your endpoint. `mercurjs codegen` reads the route's handler and validators and emits the `Routes` type the client consumes — so the panel call site breaks at compile time the moment the backend changes. This loop is also what makes Mercur projects reliable targets for AI agents: see [Building with AI](/rc/resources/ai/overview).
+  The contract is generated, not declared. You never write an interface for your endpoint. `mercurjs codegen` reads the route's handler and validators and emits the `Routes` type the client consumes, so the panel call site breaks at compile time the moment the backend changes. This loop is also what makes Mercur projects reliable targets for AI agents. See [Building with AI](/rc/resources/ai/overview).
 </Info>
 
 ## What you'll build
 
-A `GET /vendor/sales-summary` endpoint returning the seller's order count, called from a custom vendor portal page via `client.vendor.salesSummary.query()` with inferred types.
+A `GET /vendor/sales-summary` endpoint returns the seller's order count. You call it from a custom vendor portal page via `client.vendor.salesSummary.query()` with inferred types.
 
 ## Build the loop
 
 <Steps>
   <Step title="Create the route">
-    API routes follow Medusa's file conventions inside your API package. The URL path mirrors the directory path:
+    API routes follow Medusa's file conventions inside your API package. The URL path mirrors the directory path.
 
     ```typescript packages/api/src/api/vendor/sales-summary/route.ts
     import { AuthenticatedMedusaRequest, MedusaResponse } from "@medusajs/framework/http"
@@ -42,11 +45,13 @@ A `GET /vendor/sales-summary` endpoint returning the seller's order count, calle
     Routes under `src/api/vendor/*` run behind the vendor authentication middleware, so `req.auth_context` identifies the calling seller. Use `src/api/admin/*` for operator endpoints and `src/api/store/*` for public storefront endpoints.
   </Step>
   <Step title="Regenerate the route map">
-    ```bash
+    Run codegen to scan your route files.
+
+    ```bash Terminal
     bunx @mercurjs/cli@latest codegen
     ```
 
-    Codegen scans your route files and rewrites the generated `Routes` type that your panel apps already import:
+    Codegen rewrites the generated `Routes` type that your panel apps already import:
 
     ```typescript apps/vendor/src/lib/client.ts
     import { createClient, type InferClient } from "@mercurjs/client"
@@ -60,14 +65,14 @@ A `GET /vendor/sales-summary` endpoint returning the seller's order count, calle
     })
     ```
 
-    This file ships with the starter template — you don't need to touch it. After codegen, `client.vendor.salesSummary` simply exists, typed.
+    This file ships with the starter template, so you don't need to touch it. After codegen, `client.vendor.salesSummary` simply exists, typed.
 
     <Tip>
       Run `bunx @mercurjs/cli@latest codegen --watch` during development so the route map regenerates as you edit route files.
     </Tip>
   </Step>
   <Step title="Call it from a panel page">
-    Drop a page into the vendor app and call the endpoint through the client. Route segments map to camelCase properties, and the HTTP method is chosen by the terminal call: `query` (GET), `mutate` (POST), `delete` (DELETE).
+    Drop a page into the vendor app and call the endpoint through the client. Route segments map to camelCase properties, and the terminal call chooses the HTTP method: `query` (GET), `mutate` (POST), or `delete` (DELETE).
 
     ```tsx apps/vendor/src/routes/sales-summary/page.tsx
     import { useQuery } from "@tanstack/react-query"
@@ -97,7 +102,7 @@ A `GET /vendor/sales-summary` endpoint returning the seller's order count, calle
           </div>
           <div className="px-6 py-4">
             <Text size="small" className="text-ui-fg-subtle">
-              Orders: {data?.order_count ?? "—"}
+              Orders: {data?.order_count ?? "-"}
             </Text>
           </div>
         </Container>
@@ -105,25 +110,32 @@ A `GET /vendor/sales-summary` endpoint returning the seller's order count, calle
     }
     ```
 
-    `InferClientOutput` extracts the response type straight from the client method — change the route's response shape, rerun codegen, and this component stops compiling until you update it.
+    `InferClientOutput` extracts the response type straight from the client method. Change the route's response shape, rerun codegen, and this component stops compiling until you update it.
   </Step>
 </Steps>
 
 ## Verify
 
-1. Start the project (`bun run dev`) and log into the vendor portal.
-2. **Sales summary** appears in the sidebar (the `config` export registered it); the page shows the order count.
-3. `curl http://localhost:9000/vendor/sales-summary` without a token returns an authentication error — the vendor middleware guards your route.
-4. Change the route to return `{ count: ... }` instead of `{ order_count: ... }`, rerun codegen, and confirm the page fails to type-check — that's the generated contract doing its job. Revert after.
+Start the project and log into the vendor portal.
+
+```bash Terminal
+bun run dev
+```
+
+Confirm each of the following:
+
+1. **Sidebar entry:** Sales summary appears in the sidebar (the `config` export registered it), and the page shows the order count.
+2. **Auth guard:** `curl http://localhost:9000/vendor/sales-summary` without a token returns an authentication error. The vendor middleware guards your route.
+3. **Generated contract:** change the route to return `{ count: ... }` instead of `{ order_count: ... }`, rerun codegen, and confirm the page fails to type-check. That is the generated contract doing its job. Revert after.
 
 ## FAQ
 
 <AccordionGroup>
   <Accordion title="How do path parameters work in the client?">
-    Use `$`-prefixed segments: a route at `src/api/vendor/things/[id]/route.ts` is called as `client.vendor.things.$id.query({ $id: "thing_123" })`. The `$id` key is threaded into the URL path; everything else in the object becomes query params (GET) or the JSON body (POST).
+    Use `$`-prefixed segments: a route at `src/api/vendor/things/[id]/route.ts` is called as `client.vendor.things.$id.query({ $id: "thing_123" })`. The `$id` key is threaded into the URL path, and everything else in the object becomes query params (GET) or the JSON body (POST).
   </Accordion>
   <Accordion title="How do I handle errors from the client?">
-    Failed requests throw `ClientError` from `@mercurjs/client`, carrying `status`, `statusText`, and the backend's `message`. Wrap calls in try/catch or let TanStack Query surface the error. Full reference: [API Client](/rc/tools/api-client).
+    Failed requests throw `ClientError` from `@mercurjs/client`, carrying `status`, `statusText`, and the backend's `message`. Wrap calls in try/catch or let TanStack Query surface the error.
   </Accordion>
   <Accordion title="Where do request validation schemas go?">
     Follow Medusa conventions: a `validators.ts` next to the route with a Zod schema, wired through the route's middleware. Codegen reads validators too, so the client's input type reflects them.
@@ -133,8 +145,8 @@ A `GET /vendor/sales-summary` endpoint returning the seller's order count, calle
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="API Client" href="/rc/tools/api-client">
-    Everything the typed client can do — inputs, outputs, errors, React Query.
+  <Card title="API conventions" href="/references/api/conventions">
+    Authentication, pagination, field selection, and error shapes.
   </Card>
   <Card title="Extend a workflow" href="/rc/resources/customization/extend-a-workflow">
     Put multi-step business logic behind your endpoint with rollback support.

package/content/resources/tutorials/custom-panel-page.mdx

@@ -1,23 +1,26 @@
 ---
-title: "Add a custom panel page"
-description: "Add a page to the vendor portal with file-based routing — the dashboard SDK wires it in automatically."
+title: "How to Create a Custom Page"
+sidebarTitle: "Create a Page"
+description: "Add a page to the vendor portal or admin panel with file-based routing and let the dashboard SDK wire it into the sidebar."
 ---
 
-Adding a page to the admin panel or vendor portal takes one file. The dashboard SDK scans `src/routes/` at build time, registers the route, and — if you export a `config` — adds it to the sidebar with a label and icon. No route table, no registration call.
+Add a page to the vendor portal or admin panel from a single file.
+
+The dashboard SDK scans `src/routes/` at build time, registers the route, and, if you export a `config`, adds it to the sidebar with a label and icon. There is no route table and no registration call.
 
 <Info>
-  **Adding vs changing.** This tutorial *adds* a brand-new page — the right move for new features. To *change* an existing page, don't rebuild it: add a [widget](/rc/resources/tutorials/add-a-widget) or a [custom field](/rc/resources/tutorials/extend-forms-and-tables) to inject into it. The [decision guide](/rc/resources/customization/extending-panels#choosing-your-extension-mechanism) compares every extension mechanism.
+  **Adding vs changing.** This tutorial *adds* a brand-new page, the right move for new features. To *change* an existing page, don't rebuild it. Add a [widget](/rc/resources/tutorials/add-a-widget) or a [custom field](/rc/resources/tutorials/extend-forms-and-tables) to inject into it. The [decision guide](/rc/resources/customization/extending-panels#choosing-your-extension-mechanism) compares every extension mechanism.
 </Info>
 
 ## What you'll build
 
-A `/reviews` page in the vendor portal with a sidebar entry — from a single file.
+A `/reviews` page in the vendor portal with a sidebar entry, from a single file.
 
 ## Add the page
 
 <Steps>
   <Step title="Create the route file">
-    Drop a `page.tsx` under `src/routes/` in your vendor app. The file path becomes the URL, and the default export is the page:
+    Drop a `page.tsx` under `src/routes/` in your vendor app. The file path becomes the URL, and the default export is the page.
 
     ```tsx apps/vendor/src/routes/reviews/page.tsx
     import { Container, Heading } from "@medusajs/ui"
@@ -42,17 +45,23 @@ A `/reviews` page in the vendor portal with a sidebar entry — from a single fi
     ```
   </Step>
   <Step title="Let the SDK wire it up">
-    At build time the SDK registers the `/reviews` route, generates the sidebar item from `config` (`label`, `icon`, `rank`), and hot-reloads the route tree when you add or remove page files. Dynamic segments use brackets — `src/routes/reviews/[id]/page.tsx` becomes `/reviews/:id`. The full path-to-route table is in [Extending Panels](/rc/resources/customization/extending-panels#routing-conventions).
+    At build time the SDK registers the `/reviews` route, generates the sidebar item from `config` (`label`, `icon`, `rank`), and hot-reloads the route tree when you add or remove page files. Dynamic segments use brackets: `src/routes/reviews/[id]/page.tsx` becomes `/reviews/:id`. The full path-to-route table is in [Extending Panels](/rc/resources/customization/extending-panels#routing-conventions).
   </Step>
   <Step title="Open it in the running panel">
-    Start the project (`bun run dev`) and open the vendor portal — **Reviews** appears in the sidebar at the position set by `rank`, and `/reviews` renders your component.
+    Start the project, then open the vendor portal.
+
+    ```bash Terminal
+    bun run dev
+    ```
+
+    **Reviews** appears in the sidebar at the position set by `rank`, and `/reviews` renders your component.
   </Step>
 </Steps>
 
 ## Verify
 
 1. The sidebar shows **Reviews** with the star icon.
-2. Navigating to `/reviews` renders the page inside the standard panel layout (sidebar and topbar intact).
+2. Navigating to `/reviews` renders the page inside the standard panel layout, with the sidebar and topbar intact.
 3. Removing the `config` export keeps the route working but drops the sidebar item.
 4. Deleting the file removes the route entirely.
 
@@ -60,13 +69,13 @@ A `/reviews` page in the vendor portal with a sidebar entry — from a single fi
 
 <AccordionGroup>
   <Accordion title="How do I fetch data on my page?">
-    Use the [typed API client](/rc/tools/api-client) with TanStack Query — the panels already ship both. For a full loop including a custom backend endpoint, follow [Add a custom API route](/rc/resources/tutorials/custom-api-route).
+    Use the typed API client with TanStack Query. The panels already ship both. For a full loop including a custom backend endpoint, follow [Add a custom API route](/rc/resources/tutorials/custom-api-route).
   </Accordion>
   <Accordion title="Can the page live under /settings?">
-    Yes — place the file under a `settings/` route segment and set `nested: "/settings"` in the config to group its sidebar item under Settings.
+    Yes. Place the file under a `settings/` route segment and set `nested: "/settings"` in the config to group its sidebar item under Settings.
   </Accordion>
   <Accordion title="Does the same work for the admin panel?">
-    Identically — drop the file in the admin app's `src/routes/` instead. Both panels use the same SDK and conventions.
+    Identically. Drop the file in the admin app's `src/routes/` instead. Both panels use the same SDK and conventions.
   </Accordion>
 </AccordionGroup>