@mercurjs/docs 2.2.1 → 2.3.0-canary.1

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

@@ -0,0 +1,102 @@
+---
+title: "Panel extensions"
+sidebarTitle: "Overview"
+description: "Customize the admin and vendor panels with pages, widgets, custom fields, and navigation, without forking them."
+---
+
+Panel extensions let you customize the Admin and Vendor panels without forking
+them. You drop a file into a panel's `src/` folder and the SDK registers it at
+build time. There is no manifest to maintain and no core code to patch.
+
+## What you can add
+
+Each extension is a file in a known location. The file's folder decides what it
+does.
+
+- **Pages:** add a route and a page with a `page.tsx` under `src/routes/`.
+- **Widgets:** render a component in a slot on a built-in page with `defineWidgetConfig`.
+- **Custom fields:** add fields, rows, and columns to a built-in model with `defineCustomFieldsConfig`.
+- **Navigation:** reorder, hide, or relabel sidebar items with `defineNavigationConfig`.
+
+## File conventions
+
+An extension is discovered by its location under a panel's `src/`. The folder is
+the surface, so there is no registration step beyond creating the file.
+
+| Path                     | Adds                                     | Documented in                                                 |
+| ------------------------ | ---------------------------------------- | ------------------------------------------------------------- |
+| `src/routes/**/page.tsx` | A page and route                         | [Create a new page](/references/panel-extensions/create-page) |
+| `src/widgets/**`         | A widget on a zone                       | [Widgets](/references/panel-extensions/widgets)               |
+| `src/custom-fields/**`   | Model form, display, and list extensions | [Custom Fields](/references/panel-extensions/custom-fields)   |
+| `src/_navigation.ts`     | Sidebar overrides                        | [Create a new page](/references/panel-extensions/create-page) |
+| `src/i18n/index.ts`      | Translation resources                    | Default-exports the i18n resource map                         |
+
+Widgets and custom fields crawl subfolders, so group related files however you
+like. Navigation is a single host-owned file, not a folder crawl.
+
+## Separate apps, no surface field
+
+Admin (`@mercurjs/admin`, port 7000) and vendor (`@mercurjs/vendor`, port 7001)
+are separate Vite apps. A file under a panel's `src/` targets that panel, so the
+folder you author in is the surface. There is no `surface` field to set. The
+helpers are the same in both. Import the config helpers from
+`@mercurjs/dashboard-sdk` and `createFormHelper` from `@mercurjs/dashboard-shared`.
+
+## Typed targets
+
+Zone ids, nav item ids, models, and built-in field ids are typed per panel from a
+generated `extension-targets.d.ts`. Reference it once per host app so every
+extension file type-checks with no per-file import.
+
+```typescript apps/vendor/src/extension-targets.d.ts
+/// <reference types="@mercurjs/vendor/extension-targets" />
+```
+
+```typescript apps/admin-test/src/extension-targets.d.ts
+/// <reference types="@mercurjs/admin/extension-targets" />
+```
+
+A wrong `zone`, `model`, or nav `id` fails `tsc` (`bun run lint`) rather than
+silently doing nothing at runtime.
+
+## Persistence
+
+<Warning>
+  **The MVP is a UI surface only.** Custom fields render, validate, and display
+  through the built-in forms, sections, and tables. There is no generic core-side
+  write path. For `product`, values submit under `additional_data` and persist
+  onto `metadata`. To store data for other models, wire your own route or
+  workflow, or use the backend
+  [Custom Fields module](/rc/resources/customization/custom-fields).
+</Warning>
+
+## Explore the extensions
+
+<CardGroup cols={2}>
+  <Card title="Widgets" href="/references/panel-extensions/widgets">
+    Render a component in a named zone with `defineWidgetConfig`.
+  </Card>
+  <Card title="Custom Fields" href="/references/panel-extensions/custom-fields">
+    Add form fields, detail rows, and list columns with `defineCustomFieldsConfig`.
+  </Card>
+  <Card title="Create a new page" href="/references/panel-extensions/create-page">
+    Add a route with file-based routing, then register it in the sidebar.
+  </Card>
+</CardGroup>
+
+## Related guides
+
+<CardGroup cols={2}>
+  <Card title="Extend forms and tables" href="/rc/resources/tutorials/extend-forms-and-tables">
+    Step-by-step build with `defineCustomFieldsConfig`.
+  </Card>
+  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
+    Inject a component into a zone.
+  </Card>
+  <Card title="Customize navigation" href="/rc/resources/tutorials/customize-navigation">
+    Reorder and hide sidebar items.
+  </Card>
+  <Card title="Custom Fields module" href="/resources/best-practices/custom-fields">
+    The backend storage layer.
+  </Card>
+</CardGroup>

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

@@ -0,0 +1,212 @@
+---
+title: "Widgets"
+sidebarTitle: "Widgets"
+description: "Render a React component in a fixed slot on a built-in admin or vendor page."
+---
+
+A widget is a React component that renders in a named slot on a built-in page.
+Use a widget to show extra information or an action next to the data a page
+already displays, such as a payout summary on the order detail page.
+
+You add a widget by dropping a file into a panel's `src/widgets/` folder. The SDK
+finds it at build time. There is no manifest to edit and no route to register.
+
+## Create a widget
+
+<Steps>
+  <Step title="Add a widget file">
+    Create a file anywhere under `src/widgets/` in the panel you want to extend.
+    The file name is up to you.
+
+    ```tsx apps/vendor/src/widgets/product-list-banner.tsx
+    import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
+    import { Container, Text } from "@medusajs/ui"
+
+    const ProductListBanner = () => {
+      return (
+        <Container>
+          <Text>Welcome to your catalog.</Text>
+        </Container>
+      )
+    }
+
+    export default ProductListBanner
+    ```
+  </Step>
+
+  <Step title="Target a zone with `defineWidgetConfig`">
+    Export a `config` that names the zone to render in. The last segment of the
+    zone id, `before` or `after`, sets the placement.
+
+    ```tsx apps/vendor/src/widgets/product-list-banner.tsx
+    export const config = defineWidgetConfig({
+      zone: "product.list.before",
+    })
+    ```
+
+    Zone ids are typed. A zone that does not exist fails `tsc` (`bun run lint`),
+    so you cannot target a page that has no slot. See [Available zones](#vendor-zones)
+    for the full list.
+  </Step>
+
+  <Step title="Run the panel">
+    Start the panel and open the page you targeted. The widget renders in its
+    zone.
+
+    ```bash Terminal
+    bun run dev
+    ```
+
+    The vendor panel runs on `http://localhost:7001` and the admin panel on
+    `http://localhost:7000`.
+  </Step>
+</Steps>
+
+## Configuration
+
+`defineWidgetConfig` takes one object.
+
+| Field  | Type                             | Description                                                              |
+| ------ | -------------------------------- | ----------------------------------------------------------------------- |
+| `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.     |
+
+## Component props
+
+The widget component receives a single prop.
+
+| Prop   | Type      | Description                                                                                     |
+| ------ | --------- | ---------------------------------------------------------------------------------------------- |
+| `data` | `unknown` | The zone's contextual entity, such as the loaded product on a `product.detail.*` zone. Undefined on list and public zones that have no single entity. |
+
+```tsx
+import { Container } from "@medusajs/ui"
+import type { HttpTypes } from "@medusajs/types"
+
+const ProductDetailNote = ({ data }: { data?: HttpTypes.AdminProduct }) => (
+  <Container>{data?.title}</Container>
+)
+```
+
+<Note>
+  The public `login.logo`, `login.before`, and `login.after` zones render before
+  authentication and receive no `data`.
+</Note>
+
+## Zone ids
+
+A zone id reads `<domain>.<view>.<placement>`.
+
+- **Domain** is the page family, such as `product`, `orders`, or `customers`.
+- **View** is the surface within that family: `list` for a list page, or
+  `detail.main` and `detail.side` for the two columns of a detail page.
+- **Placement** is `before` or `after`. It is the last segment and decides
+  whether the widget renders above or below the target.
+
+Each surface in the tables below expands to two zone ids. The `product` detail
+main column, for example, gives you `product.detail.main.before` and
+`product.detail.main.after`.
+
+## Vendor zones
+
+Widgets in `@mercurjs/vendor` (`apps/vendor`) can target these surfaces. Each cell
+expands to a `.before` and an `.after` zone.
+
+| Domain             | List | Detail main | Detail side | Other |
+| ------------------ | :--: | :---------: | :---------: | ----- |
+| `campaigns`        |  ✓   |      ✓      |      ✓      |       |
+| `categories`       |  ✓   |      ✓      |      ✓      |       |
+| `collections`      |  ✓   |      ✓      |             |       |
+| `customer-groups`  |  ✓   |      ✓      |             |       |
+| `customers`        |  ✓   |      ✓      |      ✓      |       |
+| `inventory`        |  ✓   |      ✓      |      ✓      |       |
+| `locations`        |  ✓   |      ✓      |      ✓      |       |
+| `offer-variants`   |      |      ✓      |      ✓      |       |
+| `offers`           |  ✓   |      ✓      |      ✓      |       |
+| `orders`           |  ✓   |      ✓      |      ✓      | `detail.summary` |
+| `payouts`          |  ✓   |      ✓      |             |       |
+| `price-lists`      |  ✓   |      ✓      |      ✓      |       |
+| `product`          |  ✓   |      ✓      |      ✓      |       |
+| `product-tags`     |  ✓   |      ✓      |             |       |
+| `product-types`    |  ✓   |      ✓      |             |       |
+| `product-variants` |      |      ✓      |             |       |
+| `profile`          |      |      ✓      |             |       |
+| `promotions`       |  ✓   |      ✓      |      ✓      |       |
+| `regions`          |  ✓   |      ✓      |             |       |
+| `reservations`     |  ✓   |      ✓      |      ✓      |       |
+| `return-reasons`   |  ✓   |             |             |       |
+| `shipping-profiles`|  ✓   |      ✓      |             |       |
+| `tax-regions`      |  ✓   |      ✓      |             | `province.detail.main` |
+| `team`             |  ✓   |             |             |       |
+
+### Vendor public and setup zones
+
+These sit outside the list and detail shape. The `login.*` zones render before
+authentication and receive no `data`.
+
+| Zone base       | Ids                                             | Renders                            |
+| --------------- | ----------------------------------------------- | ---------------------------------- |
+| `login.logo`    | `login.logo.before`, `login.logo.after`         | Around the logo on the login page. |
+| `login.before`  | `login.before.before`, `login.before.after`     | Before the login form.             |
+| `login.after`   | `login.after.before`, `login.after.after`       | After the login form.              |
+| `seller.setup`  | `seller.setup.before`, `seller.setup.after`     | Around the store setup step.       |
+
+## Admin zones
+
+Widgets in `@mercurjs/admin` (`apps/admin-test`) can target these surfaces. Each
+cell expands to a `.before` and an `.after` zone.
+
+| Domain                  | List | Detail main | Detail side | Other |
+| ----------------------- | :--: | :---------: | :---------: | ----- |
+| `api-keys`              |  ✓   |      ✓      |             |       |
+| `attributes`            |  ✓   |      ✓      |             |       |
+| `campaigns`             |  ✓   |      ✓      |      ✓      |       |
+| `categories`            |  ✓   |      ✓      |      ✓      |       |
+| `collections`           |  ✓   |      ✓      |             |       |
+| `commissions`           |  ✓   |      ✓      |             |       |
+| `customer-groups`       |  ✓   |      ✓      |             |       |
+| `customers`             |  ✓   |      ✓      |      ✓      |       |
+| `inventory`             |  ✓   |      ✓      |      ✓      |       |
+| `locations`             |  ✓   |      ✓      |      ✓      |       |
+| `marketplace`           |      |      ✓      |             |       |
+| `offer-variants`        |      |      ✓      |      ✓      |       |
+| `offers`                |  ✓   |      ✓      |      ✓      |       |
+| `orders`                |  ✓   |      ✓      |      ✓      |       |
+| `payouts`               |  ✓   |      ✓      |             |       |
+| `price-lists`           |  ✓   |      ✓      |      ✓      |       |
+| `product`               |      |      ✓      |      ✓      |       |
+| `products`              |  ✓   |             |             |       |
+| `product-tags`          |  ✓   |      ✓      |             |       |
+| `product-types`         |  ✓   |      ✓      |             |       |
+| `product-variants`      |      |      ✓      |      ✓      |       |
+| `profile`               |      |      ✓      |             |       |
+| `promotions`            |  ✓   |      ✓      |      ✓      |       |
+| `refund-reasons`        |  ✓   |             |             |       |
+| `regions`               |  ✓   |      ✓      |             |       |
+| `reservation`           |  ✓   |      ✓      |      ✓      |       |
+| `return-reasons`        |  ✓   |             |             |       |
+| `sales-channels`        |  ✓   |      ✓      |             |       |
+| `shipping-option-types` |  ✓   |      ✓      |             |       |
+| `shipping-profiles`     |  ✓   |      ✓      |             |       |
+| `stores`                |  ✓   |      ✓      |      ✓      |       |
+| `tax-regions`           |  ✓   |      ✓      |             | `province.detail.main` |
+| `users`                 |  ✓   |      ✓      |             |       |
+
+<Note>
+  Admin splits the product list and product detail across two domains. List zones
+  are `products.list.*` (plural) and detail zones are `product.detail.*`
+  (singular). Vendor uses `product` for both. Detail-page reservation zones are
+  `reservation.*` (singular) in admin and `reservations.*` (plural) in vendor.
+  Follow the tables above rather than guessing the pluralization.
+</Note>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Custom Fields" href="/references/panel-extensions/custom-fields">
+    Add fields, section rows, and list columns to a built-in model.
+  </Card>
+  <Card title="Create a new page" href="/references/panel-extensions/create-page">
+    Add a route with file-based routing and register it in the sidebar.
+  </Card>
+</CardGroup>

package/content/resources/ai/mcp.mdx

@@ -147,6 +147,6 @@ Use it when you need to look up API references, understand how a module works, f
 
 | Approach | Best for |
 |----------|----------|
-| **[Bundled docs](/rc/resources/ai/overview)** | Coding agents inside a project — version-matched, offline, no setup |
+| **[Bundled docs](/rc/resources/ai/overview)** | Coding agents inside a project: version-matched, offline, no setup |
 | **MCP Server** | Live search from your editor, always the latest published docs |
-| **[llms.txt](/rc/resources/ai/llms)** | Feeding full context to a chat assistant (Claude, ChatGPT) |
+| **[llms.txt](https://docs.mercurjs.com/llms-full.txt)** | Feeding full context to a chat assistant (Claude, ChatGPT) |

package/content/resources/ai/overview.mdx

@@ -1,12 +1,13 @@
 ---
 title: "Building with AI"
+sidebarTitle: "Overview"
 description: "Mercur ships version-matched docs inside your project so AI coding agents build from accurate APIs instead of stale training data."
 ---
 
-Mercur is built so AI coding agents work from **accurate, version-matched documentation** instead of their training data — which is almost always out of date for a fast-moving framework. The docs ship *inside your project's dependencies*, and your project tells agents to read them before writing any code.
+Mercur is built so AI coding agents work from **accurate, version-matched documentation** instead of their training data. Training data is almost always out of date for a fast-moving platform. The docs ship *inside your project's dependencies*, and your project tells agents to read them before writing any code.
 
 <Info>
-  **Why agents do well here.** Every extension surface an agent touches has a machine-checkable contract: routes generate the [typed client](/rc/tools/api-client) (wrong calls fail to compile), pages follow [file conventions](/rc/resources/customization/extending-panels) the SDK validates at build time, and blocks are diffable source. An agent doesn't need to guess whether its change works — the toolchain tells it.
+  **Why agents do well here.** Every extension surface an agent touches has a machine-checkable contract: routes generate a typed client (wrong calls fail to compile), pages follow [file conventions](/rc/resources/customization/extending-panels) the SDK validates at build time, and blocks are diffable source. An agent doesn't need to guess whether its change works. The toolchain tells it.
 </Info>
 
 ## How it works
@@ -17,25 +18,25 @@ When you install a Mercur project, the documentation is bundled as a dependency
 node_modules/@mercurjs/docs/
 ├── llms.txt              # index: every page with a one-line description
 └── content/
-    ├── learn/            # concepts — sellers, products, offers, commissions…
+    ├── learn/            # concepts: sellers, products, offers, commissions…
     ├── resources/        # tutorials, integrations, deployment, this guide
     ├── tools/            # CLI, API client, dashboard SDK
     ├── references/       # module, HTTP API, and configuration reference
     └── user-guide/       # admin and vendor panel usage
 ```
 
-Because the docs travel with the package, an agent always has documentation that **matches your installed version** — no network request, no external lookup, and no drift between what the agent reads and what your code actually runs.
+Because the docs travel with the package, an agent always has documentation that **matches your installed version**. There is no network request, no external lookup, and no drift between what the agent reads and what your code actually runs.
 
 ## Set up your project
 
 ### New projects
 
-Projects created with `bunx @mercurjs/cli@latest create` are ready out of the box. The template ships:
+Projects created with `bun create mercur-app@latest` are ready out of the box. The template ships:
 
 - `@mercurjs/docs` as a dependency, so the docs land in `node_modules` on install
 - an `AGENTS.md` and a `CLAUDE.md` at the project root that tell agents to read the bundled docs first
 
-Most AI coding agents — Claude Code, Cursor, GitHub Copilot, and others — read `AGENTS.md` automatically when they start a session. There is nothing else to configure.
+Most AI coding agents, such as Claude Code, Cursor, and GitHub Copilot, read `AGENTS.md` automatically when they start a session. There is nothing else to configure.
 
 ### Existing projects
 
@@ -50,7 +51,7 @@ Then create an `AGENTS.md` at the project root with a single, focused instructio
 ```md AGENTS.md
 # Mercur: read the docs before coding
 
-Before any non-trivial change, read the bundled documentation — it is
+Before any non-trivial change, read the bundled documentation. It is
 version-matched to this project's installed packages, and far more accurate
 than training data.
 
@@ -68,30 +69,34 @@ Don't guess at an API, data model, or file convention the docs already describe.
 
 ## What the agent reads
 
-The workflow is deliberately simple: **index first, then the page.** An agent reads `llms.txt` to see what exists, then opens the one or two `content/` pages relevant to the task before implementing. The bundled docs cover the full domain model (sellers, products, offers, attributes, commissions, payouts, order groups), the CLI, the typed API client, the dashboard SDK, module references, and how-to guides — so the agent looks up the correct contract rather than inventing one.
+The workflow is deliberately simple: **index first, then the page.** An agent reads `llms.txt` to see what exists, then opens the one or two `content/` pages relevant to the task before implementing. The bundled docs cover the full domain model (sellers, products, offers, attributes, commissions, payouts, order groups), the CLI, the typed API client, the dashboard SDK, module references, and how-to guides. The agent looks up the correct contract rather than inventing one.
 
 ## Verify its work
 
-Mercur gives an agent a fast, machine-checkable way to know whether a change is correct — the equivalent of a grading loop it can run itself:
+Mercur gives an agent a fast, machine-checkable way to know whether a change is correct. It is the equivalent of a grading loop the agent can run itself:
 
 | Check | What it proves |
 |-------|----------------|
 | `bun run build` | Types resolve and the generated client matches the routes |
 | `bun run lint` | Code conforms to the project's rules |
 | Integration tests (`packages/api`) | Backend behavior still holds |
-| `bunx @mercurjs/cli@latest diff` | Local blocks vs. the registry — what changed and what drifted |
+| `bunx @mercurjs/cli@latest diff` | Local blocks vs. the registry: what changed and what drifted |
 
-Because these are objective, an agent can define what "done" looks like, run the checks, read the output, and iterate until they pass — instead of stopping at "looks plausible."
+Because these are objective, an agent can define what "done" looks like, run the checks, read the output, and iterate until they pass, instead of stopping at "looks plausible."
 
-## Beyond bundled docs
+## More AI tooling
 
-The bundled docs are for agents working *inside your project*. For chat assistants and hosted tools, Mercur also publishes its docs online:
+The bundled docs are the foundation. Layer more on top:
 
 <CardGroup cols={2}>
-  <Card title="llms.txt" href="/rc/resources/ai/llms">
-    Feed the full documentation to Claude, ChatGPT, or any LLM.
+  <Card title="Skills" icon="wand-magic-sparkles" href="/resources/ai/skills">
+    Add the official Medusa agent skills for the framework Mercur runs on.
   </Card>
-  <Card title="MCP server" href="/rc/resources/ai/mcp">
+  <Card title="MCP server" icon="plug" href="/resources/ai/mcp">
     Let your editor search the docs live via Model Context Protocol.
   </Card>
 </CardGroup>
+
+For chat assistants like Claude or ChatGPT, Mercur also publishes a hosted
+[`llms.txt`](https://docs.mercurjs.com/llms.txt) index and a full
+[`llms-full.txt`](https://docs.mercurjs.com/llms-full.txt) you can load as context.

package/content/resources/ai/skills.mdx

@@ -0,0 +1,67 @@
+---
+title: "Skills"
+description: "Agent skills for building on Mercur: the bundled-docs contract plus the official Medusa agent skills."
+---
+
+Agent skills are packaged instructions that teach an AI coding agent how to perform
+a specific kind of task the right way for your stack, such as a migration, a form,
+or a module. On Mercur, skills build on two foundations: the **version-matched docs**
+bundled in your project, and the **official Medusa agent skills** for the
+framework Mercur runs on.
+
+## Start with the bundled docs
+
+Mercur's own mechanism is the documentation bundled at
+`node_modules/@mercurjs/docs/` plus an `AGENTS.md` that tells agents to read it
+before writing code. That's the contract every agent should read first. It's
+version-matched to your installed packages, so an agent looks up the real API
+instead of guessing.
+
+<Card title="Building with AI" icon="robot" href="/resources/ai/overview">
+  How the bundled docs work and how to point your agent at them.
+</Card>
+
+## Official Medusa agent skills
+
+Mercur is built on Medusa, so the [official Medusa agent skills](https://docs.medusajs.com/learn/introduction/build-with-llms-ai/agentic-skills)
+apply directly to the Medusa layer under your marketplace: modules, workflows,
+API routes, migrations, admin widgets, and storefronts. Install them as plugins
+in Claude Code, or copy them into any AI tool that supports custom skills.
+
+```bash Claude Code
+claude
+/plugin marketplace add medusajs/medusa-agent-skills
+/plugin install medusa-dev@medusa
+```
+
+### Available plugins
+
+| Plugin | What it does |
+| --- | --- |
+| `medusa-dev` | Build features, fix bugs, and generate accurate Medusa code |
+| `ecommerce-storefront` | A `storefront-best-practices` skill for any frontend framework |
+| `learn-medusa` | An interactive experience for learning Medusa |
+
+### `medusa-dev` commands
+
+| Command | Description |
+| --- | --- |
+| `/medusa-dev:db-migrate` | Run database migrations |
+| `/medusa-dev:db-generate <module>` | Generate migrations for a custom module |
+| `/medusa-dev:new-user <email> <password>` | Create an admin user |
+
+<Note>
+  Using a different agent? These are plain skills. Copy them from the
+  [medusajs/medusa-agent-skills](https://github.com/medusajs/medusa-agent-skills)
+  marketplace into any tool that supports custom skills.
+</Note>
+
+## Combine skills with the Mercur docs
+
+For the framework layer, such as a custom module, a workflow, or an admin widget,
+lean on the Medusa skills. For anything marketplace-specific, such as sellers,
+offers, commissions, payouts, or order groups, pair them with the bundled Mercur
+docs so the agent has both the framework skill and the version-matched marketplace
+contract. The [Platform](/platform/store/overview) reference is written to be
+read by agents: each domain's data models, workflows, service, and events are
+documented exactly where an agent looks for them.