@mercurjs/docs 2.3.6-canary.0 → 2.3.6-canary.10

package/content/learn/migration-to-2-0.mdx

@@ -116,7 +116,7 @@ The 1.x `OrderSet` entity is renamed to `OrderGroup` in 2.x. This is a breaking
 
 Two fields were removed from the group:
 
-- **`payment_collection_id`**: payment collections are now linked at the individual order level. Query the linked orders to get the payment collection.
+- **`payment_collection_id`**: orders share the cart's payment collection until the payment is captured, then each gets its own. Read `payment_collections` on the orders (see [Order Groups](/learn/order-groups)).
 - **`sales_channel_id`**: the sales channel is stored on each individual order.
 
 Two fields are now computed at query time rather than stored: **`seller_count`** (distinct sellers across linked orders) and **`total`** (sum of order totals).

package/content/learn/order-groups.mdx

@@ -54,16 +54,39 @@ Order groups are created automatically during checkout by the `completeCartWithS
    - Each seller and the customer (if new relationship)
 6. **Finalize** — Inventory is reserved, payment is authorized, and the `order_group.created` event is emitted
 
-<Info>
-  A single payment collection is shared across all of a cart's split orders and stays on the **cart**, not on each order. Split orders are **not** linked directly to the payment collection (Medusa's `order ↔ payment_collection` link is one-to-one on the payment-collection side). Read the payment collection through the cart:
+## Payments
+
+The customer pays for the cart once: one payment collection on the cart, one payment at the payment provider. Medusa links a payment collection to a single order, so the orders of a cart share that payment through the cart until it is captured:
+
+```text
+order → cart → payment_collection → payment
+```
+
+When the cart payment is captured, it is split. Every order gets a payment collection of its own, linked to the order, with a captured payment for the order's share. That payment is on the same provider as the cart payment and points at the same charge. Shares are proportional to the order totals, rounded to the currency precision, and sum exactly to the captured amount.
 
-  ```text
-  order → cart → payment_collection
-  ```
+```text
+order → payment_collections → payment
+```
 
-  Order-group and vendor order reads normalize `cart.payment_collection` back onto `payment_collections` and recompute `payment_status` from it, so consumers keep the familiar shape. When requesting fields on vendor order routes, make sure the request does not replace route defaults that already include `cart.payment_collection.*` (a `fields=` list containing bare fields replaces defaults in Medusa; use `+`-prefixed fields to merge, or include the `cart.payment_collection.*` paths explicitly).
+From then on Medusa's order and payment workflows and the stock admin and vendor routes work on the order unchanged.
+
+| Moment | What happens |
+|--------|--------------|
+| Cancel an order before capture | No payment is touched: the authorization is still needed by the cart's other orders. Once every order of the cart is canceled, the authorization is voided. |
+| Capture | The cart payment is captured as a whole, by the provider webhook or from the dashboard, and split between the orders. What was charged for orders canceled earlier is refunded. |
+| Refund an order's payment | The amount is refunded at the provider against the customer's charge and recorded on that order. It cannot exceed the order's share. |
+| Cancel an order after capture | The order's share is refunded. |
+
+Order reads expose whichever applies under `payment_collections`: the cart's collection before the capture, the order's own afterwards.
+
+<Info>
+  The split, and voiding the authorization after the last cancel, run in subscribers to `payment.captured` and `order.canceled`, shortly after the request returns. A provider that captures on authorization is split during checkout.
 </Info>
 
+<Note>
+  Orders whose payment was captured before this model was introduced are not split retroactively and keep the cart's shared collection.
+</Note>
+
 ## Events
 
 | Event | Payload | When |

package/content/learn/payouts.mdx

@@ -155,7 +155,8 @@ curl -X POST http://localhost:9000/vendor/payout-accounts/<account-id>/onboardin
   -H "Authorization: Bearer <seller-token>" \
   -H "Content-Type: application/json" \
   -d '{
-    "context": {
+    "data": {
+      "refresh_url": "https://my-store.com/settings/payouts",
       "return_url": "https://my-store.com/settings/payouts"
     }
   }'

package/content/references/api/vendor/payout-accounts/create-onboarding.mdx

@@ -15,11 +15,11 @@ Creates an onboarding session with the payout provider. For Stripe Connect, the
 ## Body parameters
 
 <ParamField body="data" type="object">
-  Provider-specific data forwarded when creating the onboarding.
+  Provider-specific data forwarded when creating the onboarding (e.g. `refresh_url` and `return_url` for Stripe Connect). Merged over the payout account's stored `data`.
 </ParamField>
 
 <ParamField body="context" type="object">
-  Provider-specific context (e.g. `refresh_url` and `return_url` for Stripe Connect).
+  Additional context forwarded to the provider, such as an `idempotency_key`.
 </ParamField>
 
 ## Response
@@ -40,13 +40,13 @@ curl -X POST 'http://localhost:9000/vendor/payout-accounts/pacc_01HXYZ/onboardin
   -H 'Authorization: Bearer <token>' \
   -H 'x-seller-id: <seller_id>' \
   -H 'Content-Type: application/json' \
-  -d '{"context": {"refresh_url": "https://vendor.example.com/payouts", "return_url": "https://vendor.example.com/payouts"}}'
+  -d '{"data": {"refresh_url": "https://vendor.example.com/payouts", "return_url": "https://vendor.example.com/payouts"}}'
 ```
 
 ```ts JS Client
 const { onboarding } = await client.vendor.payoutAccounts.$id.onboarding.mutate({
   $id: "pacc_01HXYZ",
-  context: {
+  data: {
     refresh_url: "https://vendor.example.com/payouts",
     return_url: "https://vendor.example.com/payouts",
   },
@@ -60,7 +60,6 @@ const { onboarding } = await client.vendor.payoutAccounts.$id.onboarding.mutate(
   "onboarding": {
     "id": "onb_01HXYZ",
     "data": { "url": "https://connect.stripe.com/setup/s/..." },
-    "context": { "return_url": "https://vendor.example.com/payouts" },
     "created_at": "2026-01-15T10:00:00.000Z"
   }
 }

package/content/references/api/vendor/payout-accounts/create-payout-account.mdx

@@ -9,11 +9,11 @@ Creates a payout account for the current seller through the configured payout pr
 ## Body parameters
 
 <ParamField body="data" type="object">
-  Provider-specific data forwarded when creating the account.
+  Provider-specific data forwarded when creating the account (e.g. `{ "country": "US" }` for Stripe Connect). Defaults to `{}`.
 </ParamField>
 
 <ParamField body="context" type="object">
-  Provider-specific context (e.g. `{ "country": "US" }` for Stripe Connect).
+  Additional context forwarded to the provider, such as an `idempotency_key`.
 </ParamField>
 
 ## Response
@@ -35,12 +35,12 @@ curl -X POST 'http://localhost:9000/vendor/payout-accounts' \
   -H 'Authorization: Bearer <token>' \
   -H 'x-seller-id: <seller_id>' \
   -H 'Content-Type: application/json' \
-  -d '{"context": {"country": "US"}}'
+  -d '{"data": {"country": "US"}}'
 ```
 
 ```ts JS Client
 const { payout_account } = await client.vendor.payoutAccounts.mutate({
-  context: { country: "US" },
+  data: { country: "US" },
 })
 ```
 </RequestExample>
@@ -51,7 +51,7 @@ const { payout_account } = await client.vendor.payoutAccounts.mutate({
   "payout_account": {
     "id": "pacc_01HXYZ",
     "status": "pending",
-    "context": { "country": "US" },
+    "data": { "id": "acct_1Q2w3E4r5T6y7U8i" },
     "created_at": "2026-01-15T10:00:00.000Z"
   }
 }

package/content/references/panel-extensions/create-page.mdx

@@ -101,6 +101,7 @@ The `config` object controls the page's sidebar entry.
 | `icon`          | `ComponentType` (optional) | Sidebar icon, from `@medusajs/icons`.                          |
 | `rank`          | `number` (optional)        | Order among sibling items. Lower ranks first.                  |
 | `nested`        | `string` (optional)        | Parent item id to nest this entry under.                       |
+| `group`         | `string` (optional)        | Sidebar group to list the entry under, as a string literal. See [Groups](#groups). |
 | `translationNs` | `string` (optional)        | i18n namespace used to resolve `label` as a translation key.   |
 | `public`        | `boolean` (optional)       | Render the route before authentication under the public layout. |
 
@@ -131,7 +132,7 @@ Read the loader's result with `useLoaderData()` inside the component.
 
 ## Reshape built-in navigation
 
-Use `defineNavigationConfig` to reorder, hide, relabel, or re-parent built-in
+Use `defineNavigationConfig` to reorder, hide, relabel, re-parent, or group built-in
 sidebar items. It lives in a single host-owned file, `src/_navigation.ts`. Blocks
 cannot contribute navigation overrides.
 
@@ -159,6 +160,49 @@ Each entry is a `NavItemOverride`.
 | `label`  | `string` (optional)              | i18n key or literal replacing the item's label.                                 |
 | `icon`   | `ComponentType` (optional)       | Icon component replacing the item's icon, from `@medusajs/icons`.              |
 | `nested` | `NavParentId \| null` (optional) | Re-parent under a built-in parent id. `null` promotes a nested item to top level. |
+| `group`  | `NavGroupId` (optional)          | List the item under a group declared in `groups`, or a built-in settings group. |
+
+### Groups
+
+`groups` declares group headings by keyword, and an item's `group` assigns it to
+one. A group renders in whichever sidebar its items live in.
+
+The main sidebar has no built-in groups. Top-level items assigned to a declared
+group render below the ungrouped list, under the group's heading. The settings
+sidebar ships `general`, `developer`, and `myAccount` in the admin panel and
+`general` in the vendor portal, which `groups` can also override by id. Settings
+items are targeted as `settings/<segment>`.
+
+```ts apps/admin/src/_navigation.ts
+import { defineNavigationConfig } from "@mercurjs/dashboard-sdk"
+
+export default defineNavigationConfig({
+  groups: [
+    { id: "catalog", label: "Catalog" },
+    { id: "integrations", label: "Integrations", rank: 1 },
+    { id: "developer", hidden: true },
+  ],
+  items: [
+    { id: "products", group: "catalog" },
+    { id: "inventory", group: "catalog" },
+    { id: "settings/tax-regions", group: "integrations" },
+  ],
+})
+```
+
+Each entry is a `NavGroupConfig`.
+
+| Field           | Type                 | Description                                                                 |
+| --------------- | -------------------- | --------------------------------------------------------------------------- |
+| `id`            | `string`             | A new keyword that declares a group, or a built-in settings group id to override. |
+| `label`         | `string` (optional)  | Heading text. A literal, or an i18n key with `translationNs`. Defaults to the `id`. |
+| `translationNs` | `string` (optional)  | i18n namespace used to resolve `label`.                                     |
+| `rank`          | `number` (optional)  | Order among groups, lower first. Defaults to declaration order. Built-in settings groups rank `0`, `1`, `2`. |
+| `hidden`        | `boolean` (optional) | Remove the group and its items from the sidebar.                            |
+
+A custom page joins a group through `config.group`. An undeclared group falls
+back to the default placement (the ungrouped list, or the first settings group),
+and a group with no visible items isn't rendered.
 
 Navigation overrides reshape existing items only. To add a new item, register a
 page with a `config.label` as shown above.

package/content/references/panel-extensions/widgets.mdx

@@ -70,6 +70,7 @@ finds it at build time. There is no manifest to edit and no route to register.
 | ------ | -------------------------------- | ----------------------------------------------------------------------- |
 | `zone` | `WidgetZoneId \| WidgetZoneId[]` | The zone or zones to render in. Multiple widgets in one zone stack in registration order. |
 | `id`   | `string` (optional)              | A stable id. Derived from the file path at build time when omitted.     |
+| `label` | `string` (optional)             | The tab label, as an i18n key or a literal. Only used by [tab zones](#tabs). |
 
 ## Component props
 
@@ -93,6 +94,89 @@ const ProductDetailNote = ({ data }: { data?: HttpTypes.AdminProduct }) => (
   authentication and receive no `data`.
 </Note>
 
+## Tabs
+
+Some detail pages group their content into tabs. A tab zone lets a widget add a
+tab of its own: the widget's `label` names the tab and its component renders as
+the tab's panel. The placement decides whether the tab sits before or after the
+built-in ones.
+
+```tsx apps/admin-test/src/widgets/store-loyalty-tab.tsx
+import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
+import { Container, Heading } from "@medusajs/ui"
+import type { SellerDTO } from "@mercurjs/types"
+
+const StoreLoyaltyTab = ({ data }: { data?: SellerDTO }) => (
+  <Container>
+    <Heading level="h2">Loyalty for {data?.name}</Heading>
+  </Container>
+)
+
+export const config = defineWidgetConfig({
+  zone: "stores.detail.tabs.after",
+  id: "loyalty",
+  label: "Loyalty",
+})
+
+export default StoreLoyaltyTab
+```
+
+A widget that targets a tab zone without a `label` is not shown. `permission`
+works as on any other widget and hides the tab from actors who lack it.
+
+| Panel | Tab zone            | Page                                                    |
+| ----- | ------------------- | ------------------------------------------------------- |
+| Admin | `stores.detail.tabs` | Store detail, next to Orders, Offers, Users and Time off. |
+
+## List item rows
+
+The locations list renders one card per stock location. The `locations.list.item`
+zone sits inside each card, so a widget there adds a row to the card instead of a
+separate block above or below the list. `locations.list.item.before` renders
+between the card header and the built-in rows, and `locations.list.item.after`
+renders after them. `data` is the stock location of that card.
+
+```tsx apps/vendor/src/widgets/location-local-delivery-row.tsx
+import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
+import { StatusBadge, Text } from "@medusajs/ui"
+import type { HttpTypes } from "@mercurjs/types"
+
+type StockLocation = HttpTypes.VendorStockLocationResponse["stock_location"]
+
+const LocationLocalDeliveryRow = ({ data }: { data?: StockLocation }) => {
+  const enabled = data?.fulfillment_sets?.some(
+    (set) => set.type === "local_delivery"
+  )
+
+  return (
+    <div className="flex items-center justify-between px-6 py-4">
+      <Text size="small" weight="plus" className="text-ui-fg-subtle flex-1">
+        Local delivery
+      </Text>
+      <div className="flex-1">
+        <StatusBadge color={enabled ? "green" : "grey"}>
+          {enabled ? "Enabled" : "Disabled"}
+        </StatusBadge>
+      </div>
+    </div>
+  )
+}
+
+export const config = defineWidgetConfig({
+  zone: "locations.list.item.after",
+})
+
+export default LocationLocalDeliveryRow
+```
+
+Return a single row element, without a `Container` of its own. The card draws the
+divider between rows.
+
+| Panel  | Zone                  | Page                                   |
+| ------ | --------------------- | -------------------------------------- |
+| Vendor | `locations.list.item` | Settings → Locations, each location card. |
+| Admin  | `locations.list.item` | Settings → Locations, each location card. |
+
 ## Zone ids
 
 A zone id reads `<domain>.<view>.<placement>`.
@@ -120,7 +204,7 @@ expands to a `.before` and an `.after` zone.
 | `customer-groups`  |  ✓   |      ✓      |             |       |
 | `customers`        |  ✓   |      ✓      |      ✓      |       |
 | `inventory`        |  ✓   |      ✓      |      ✓      |       |
-| `locations`        |  ✓   |      ✓      |      ✓      |       |
+| `locations`        |  ✓   |      ✓      |      ✓      | `list.item` |
 | `offer-variants`   |      |      ✓      |      ✓      |       |
 | `offers`           |  ✓   |      ✓      |      ✓      |       |
 | `orders`           |  ✓   |      ✓      |      ✓      | `detail.summary` |
@@ -167,7 +251,7 @@ cell expands to a `.before` and an `.after` zone.
 | `customer-groups`       |  ✓   |      ✓      |             |       |
 | `customers`             |  ✓   |      ✓      |      ✓      |       |
 | `inventory`             |  ✓   |      ✓      |      ✓      |       |
-| `locations`             |  ✓   |      ✓      |      ✓      |       |
+| `locations`             |  ✓   |      ✓      |      ✓      | `list.item` |
 | `marketplace`           |      |      ✓      |             |       |
 | `offer-variants`        |      |      ✓      |      ✓      |       |
 | `offers`                |  ✓   |      ✓      |      ✓      |       |

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

@@ -151,6 +151,7 @@ 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` and `icon` relabel it, and `nested` re-parents it (`nested: null` promotes to top level, typed against `NavParentId`).
+- `groups` declares group headings by keyword, and an item's `group` lists it under one, in the main sidebar or the settings sidebar (settings items are targeted as `settings/<segment>`). The built-in settings groups can be reshaped by id. A custom page picks its group with `group` in its route config.
 - 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).
@@ -242,6 +243,7 @@ For the full walkthrough (forms, sections, and list columns), see [Extend forms
     | `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 |
+    | `group` | `string` | Sidebar group declared in `_navigation.ts` to list the item under |
     | `translationNs` | `string` | i18n namespace for the label |
     | `public` | `boolean` | If `true`, the route is accessible without authentication |
 
@@ -270,6 +272,51 @@ File paths map to URL routes automatically.
 | `src/routes/(settings)/page.tsx` | Route grouping | Groups routes without adding a URL segment |
 | `src/routes/dashboard/@sidebar/page.tsx` | Parallel route | Renders alongside parent |
 
+### Adding permissions from a plugin
+
+A plugin that ships its own pages usually needs its own permission keys. Declare them on the server, then register the same keys with the dashboard SDK so pages can be guarded and hidden from navigation.
+
+**1. Define the keys on the server.** Import the definitions file once (for example from your module's `index.ts`) so the keys join the catalog:
+
+```typescript src/permissions.ts
+import { defineMercurPermissions } from "@mercurjs/core/permissions/registry"
+
+export const messagingPermissions = defineMercurPermissions([
+  { key: "messaging", group: "messaging", surface: ["vendor"], rights: ["view", "edit", "manage"] },
+])
+```
+
+Guard the plugin's API routes with the same key (`requirePermission("messaging", "view")`).
+
+**2. Register the keys with the dashboard SDK.** `PermissionKey` is built from the `PermissionKeys` interface, so augment it:
+
+```typescript src/permissions.d.ts
+declare module "@mercurjs/dashboard-sdk" {
+  interface PermissionKeys {
+    messaging: true
+  }
+}
+
+export {}
+```
+
+The key now type-checks everywhere the SDK accepts a permission:
+
+```tsx src/routes/messages/page.tsx
+import type { RouteConfig, RouteHandle } from "@mercurjs/dashboard-sdk"
+
+export const config: RouteConfig = {
+  label: "Messages",
+  permissions: ["messaging:view"],
+}
+
+export const handle: RouteHandle = {
+  permissions: "messaging:view",
+}
+```
+
+`can("messaging", "edit")` and `buildPermission("messaging", "manage")` accept it too. This only affects types: the dashboard reads the member's effective rights from the API at runtime.
+
 ## Branding
 
 Set `name` and `logo` in the plugin options to customize the sidebar header.

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

@@ -1,7 +1,7 @@
 ---
 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."
+description: "Reorder, hide, relabel, re-parent, and group the panel's built-in sidebar items from a single _navigation.ts file."
 ---
 
 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.
@@ -55,8 +55,9 @@ With it present, `id` and `nested` autocomplete and an unknown id fails `tsc`.
     | `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. |
+    | `group` | `NavGroupId` | List the item under a [group heading](#group-items-under-headings). |
 
-    Both `id` and `nested` are checked against the panel's generated `NavItemRegistry` and `NavParentRegistry`.
+    `id`, `nested`, and `group` are checked against the panel's generated `NavItemRegistry`, `NavParentRegistry`, and `NavGroupRegistry`.
   </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.
@@ -80,6 +81,80 @@ export default defineNavigationConfig({
 })
 ```
 
+## Group items under headings
+
+Declare groups by keyword in `groups`, then assign items to them with `group`. A group renders in whichever sidebar its items live in, and a group with no visible items isn't rendered.
+
+### Main sidebar
+
+The main sidebar ships without groups. Items you assign to a declared group move out of the default list and render below it, under the group's heading.
+
+```ts apps/vendor/src/_navigation.ts
+import { defineNavigationConfig } from "@mercurjs/dashboard-sdk"
+
+export default defineNavigationConfig({
+  groups: [
+    { id: "catalog", label: "Catalog" },
+    { id: "finance", label: "Finance" },
+  ],
+  items: [
+    { id: "products", group: "catalog" },
+    { id: "inventory", group: "catalog" },
+    { id: "payouts", group: "finance" },
+  ],
+})
+```
+
+Only top-level items can be grouped. Nested children follow their parent.
+
+### Settings sidebar
+
+The settings sidebar already lists its items under groups. The admin panel ships `general`, `developer`, and `myAccount`. The vendor portal ships `general`. You can reshape these built-in groups, add your own, and move items between them. Settings items are targeted by their path without the leading slash, such as `settings/users`.
+
+```ts apps/admin/src/_navigation.ts
+import { defineNavigationConfig } from "@mercurjs/dashboard-sdk"
+
+export default defineNavigationConfig({
+  groups: [
+    { id: "integrations", label: "Integrations", rank: 1 }, // new group, after General
+    { id: "developer", label: "API" },                      // relabel a built-in group
+  ],
+  items: [
+    { id: "settings/secret-api-keys", group: "integrations" },
+    { id: "settings/tax-regions", group: "integrations", rank: 0 },
+  ],
+})
+```
+
+### Group fields
+
+| Field | Type | Effect |
+|-------|------|--------|
+| `id` | `string` | **Required.** A new keyword to declare a group, or a built-in settings group id to override. |
+| `label` | `string` | Heading text. A literal, or an i18n key when `translationNs` is set. Defaults to the `id`. |
+| `translationNs` | `string` | i18n namespace used to resolve `label`. |
+| `rank` | `number` | Order among groups, lower first. Defaults to declaration order. Built-in settings groups rank `0`, `1`, `2`. |
+| `hidden` | `boolean` | Remove the group and its items from the sidebar. |
+
+An item's `group` only accepts a built-in group id or an id declared in the same file's `groups`, so a typo fails `tsc`.
+
+### Group a custom page
+
+A custom page picks its group in its own route config with the same keyword.
+
+```tsx apps/admin/src/routes/settings/webhooks/page.tsx
+import type { RouteConfig } from "@mercurjs/dashboard-sdk"
+
+export const config: RouteConfig = {
+  label: "Webhooks",
+  group: "integrations",
+}
+```
+
+<Note>
+  A page whose group isn't declared falls back to the default placement: the ungrouped list in the main sidebar, or the first group in the settings sidebar.
+</Note>
+
 ## Verify
 
 1. The top-level order reflects your `rank` values, with `orders` first.
@@ -94,6 +169,9 @@ export default defineNavigationConfig({
   <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`.
   </Accordion>
+  <Accordion title="Can a block put its page in a group?">
+    Yes. A block's page sets `group` in its route config like any other page. If the host hasn't declared that group, the page falls back to the default placement.
+  </Accordion>
   <Accordion title="What ids can I target?">
     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>

package/llms.txt

@@ -51,7 +51,7 @@ package (`node_modules/@mercurjs/docs/`).
 - [How to Build a Block](content/resources/tutorials/build-a-block.mdx) — 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.
 - [How to Add a Custom API Route](content/resources/tutorials/custom-api-route.mdx) — Add a backend endpoint, regenerate the route map, and call it from a panel page with full type safety.
 - [How to Create a Custom Page](content/resources/tutorials/custom-panel-page.mdx) — Add a page to the vendor portal or admin panel with file-based routing and let the dashboard SDK wire it into the sidebar.
-- [How to Customize Navigation](content/resources/tutorials/customize-navigation.mdx) — Reorder, hide, relabel, and re-parent the panel's built-in sidebar items from a single _navigation.ts file.
+- [How to Customize Navigation](content/resources/tutorials/customize-navigation.mdx) — Reorder, hide, relabel, re-parent, and group the panel's built-in sidebar items from a single _navigation.ts file.
 - [How to Extend Forms and Tables](content/resources/tutorials/extend-forms-and-tables.mdx) — Add validated fields, detail-section displays, and list columns to a built-in model from a single file with defineCustomFieldsConfig.
 - [How to Extend Onboarding](content/resources/tutorials/extend-onboarding.mdx) — Add a field to the vendor store-setup surface, carry it through additional_data, and persist it from a workflow hook without forking core.
 - [How to Create Master Products and Offers](content/resources/tutorials/master-products-and-offers.mdx) — Publish one master product, add two competing seller offers, and read per-offer prices from the Store API.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercurjs/docs",
-  "version": "2.3.6-canary.0",
+  "version": "2.3.6-canary.10",
   "repository": {
     "type": "git",
     "url": "https://github.com/mercurjs/mercur",