@mercurjs/docs 2.2.0-canary.51 → 2.2.0-canary.53

package/content/resources/best-practices/overview.mdx

@@ -0,0 +1,115 @@
+---
+title: "Best Practices Overview"
+description: "How to build with Mercur — the layered architecture, the non-negotiable rules, and where each piece of logic belongs."
+---
+
+This section is a practical guide for developing on Mercur, written for both **human developers** and **AI coding agents**. It captures the conventions the codebase already follows so that new code reads as if it belongs, stays testable, and survives upgrades of the underlying Medusa framework.
+
+<Note>
+  Mercur is a Medusa plugin. Every rule here is either a Medusa framework requirement or a Mercur convention that keeps the marketplace layer consistent. When Medusa's docs and this guide agree, follow both; when in doubt, mirror an existing module, workflow, or route in `packages/core`.
+</Note>
+
+## The layered architecture
+
+Every feature in Mercur flows through the same four layers, top to bottom. Data and requests move **down**; results move back **up**. A layer may only talk to the layer directly beneath it.
+
+```mermaid
+graph TD
+    F["Frontend<br/>(Admin · Vendor panels, Storefront)"]
+    A["API Route<br/>(/admin/* · /vendor/* · /store/*)"]
+    W["Workflow<br/>(orchestration + compensation)"]
+    M["Module<br/>(thin data access / CRUD)"]
+    DB[(PostgreSQL)]
+
+    F -->|"typed SDK request"| A
+    A -->|"run(workflow)"| W
+    W -->|"module service calls (steps)"| M
+    M --> DB
+```
+
+<CardGroup cols={2}>
+  <Card title="Module" icon="cube">
+    Owns one domain's data. Thin CRUD only — no orchestration, no cross-module calls.
+  </Card>
+  <Card title="Workflow" icon="diagram-project">
+    Orchestrates a business operation across modules, step by step, with automatic rollback (compensation) on failure.
+  </Card>
+  <Card title="API Route" icon="plug">
+    A thin HTTP adapter: validate input, run a workflow (or query for reads), shape the response.
+  </Card>
+  <Card title="Frontend" icon="window">
+    Admin/Vendor panels and storefront. Talks to the API only through the typed SDK — never raw `fetch`.
+  </Card>
+</CardGroup>
+
+Why this shape matters:
+
+- **Testability** — business logic lives in workflows, which can be run in isolation without an HTTP request.
+- **Reusability** — a workflow can be called from a route, a subscriber, or a scheduled job.
+- **Upgrade safety** — modules stay thin, so Medusa framework upgrades rarely touch your logic.
+- **Rollback** — because mutations are workflow steps, a failure halfway through automatically undoes the earlier steps.
+
+## The non-negotiables
+
+These are hard rules. Breaking one produces code that looks like it works but silently violates the architecture — no rollback, broken upgrades, or data written outside a workflow.
+
+<Warning>
+  **All mutations go through a workflow.** Never write to the database directly from an API route, a subscriber, or a scheduled job. Reads may query directly; writes must run a workflow so they get validation, compensation, and event emission.
+</Warning>
+
+<Warning>
+  **Only `GET`, `POST`, and `DELETE`.** Mercur (following Medusa) does not use `PUT` or `PATCH`. Updates are modeled as `POST` to the resource. Keep every route to these three verbs.
+</Warning>
+
+<Warning>
+  **No cross-module service calls.** A module service must never import or call another module's service. Modules are isolated. Cross-module reads happen through **Query** (the graph); cross-module relationships are declared with **module links**; cross-module writes are coordinated in a **workflow**.
+</Warning>
+
+Two more that follow from the above:
+
+- **Modules are thin.** A module service is CRUD plus small, self-contained helpers. If a method touches more than one module's data, it belongs in a workflow, not the service.
+- **One mutation per step.** Each workflow step performs a single mutation and defines how to compensate it. This is what makes rollback reliable.
+
+## Logic-placement cheat sheet
+
+When you're about to write a piece of logic, find the concern in this table before you decide where the code goes. The **"Never put it in"** column is the part people get wrong.
+
+| Concern | Put it in | Never put it in |
+| --- | --- | --- |
+| **Input shape / type validation** | API route (Zod schema on the request) | Module service, workflow |
+| **Ownership / scoping** (e.g. this seller may only see its own orders) | API middleware (filters) + workflow guard | The frontend alone |
+| **Business orchestration** (multi-step, multi-module operations) | Workflow (steps + compensation) | API route handler, module service |
+| **A single data mutation** | Workflow step (module service call inside it) | API route, subscriber, job |
+| **Cross-module reads** | Query (`query.graph`) | Direct service-to-service imports |
+| **Cross-module relationships** | Module link (`defineLink`) | A foreign key inside one module's model |
+| **Reacting to something that happened** (emails, sync, indexing) | Subscriber (listens to an event, runs a workflow) | Inline inside the route that caused it |
+| **Periodic / time-based work** (polling, daily settlement) | Scheduled job (runs a workflow) | A subscriber, a route |
+| **Emitting domain events** | Workflow step (`emitEventStep`) | Module service, subscriber |
+| **Response shaping / field selection** | API route `queryConfig` (fields) | The module service |
+| **Presentation, composition, UX** | Frontend (panels / storefront) | The API or any backend layer |
+
+<Tip>
+  A quick mental test: *"Does this change data?"* → it must run inside a workflow. *"Does this react to a change?"* → it's a subscriber. *"Does this run on a schedule?"* → it's a job. *"Is this just reading and shaping data for a screen?"* → it's a route + Query. Everything else is either module CRUD or frontend.
+</Tip>
+
+## How to read the rest of this section
+
+Each page that follows drills into one layer and its rules:
+
+<CardGroup cols={2}>
+  <Card title="Modules" href="/rc/resources/best-practices/modules" icon="cube">
+    Thin CRUD, naming, and what must never live in a service.
+  </Card>
+  <Card title="Module links" href="/rc/resources/best-practices/module-links" icon="link">
+    `defineLink`, link direction, and filtering by links.
+  </Card>
+  <Card title="Workflows" href="/rc/resources/best-practices/workflows" icon="diagram-project">
+    Composition constraints, steps, compensation, and the query engine.
+  </Card>
+  <Card title="API routes" href="/rc/resources/best-practices/api-routes" icon="plug">
+    Thin adapters, Zod validation, middlewares as filters, `queryConfig`.
+  </Card>
+  <Card title="Subscribers & jobs" href="/rc/resources/best-practices/subscribers-and-jobs" icon="clock">
+    Event-driven side effects and scheduled work done safely.
+  </Card>
+</CardGroup>

package/content/resources/best-practices/subscribers-and-jobs.mdx

@@ -0,0 +1,133 @@
+---
+title: "Subscribers & jobs"
+description: "React to events and run periodic work safely — fetch from { id }, mutate via workflows, log-don't-throw, idempotency and loop guards, cron jobs."
+---
+
+Subscribers and scheduled jobs are the two ways work happens *outside* a request. Both follow the same core rule as everything else: **they never mutate directly — they run a [workflow](/rc/resources/best-practices/workflows).**
+
+## Subscribers — react to events
+
+A subscriber listens for a domain event (emitted by a workflow via `emitEventStep`) and runs an asynchronous side effect: send a notification, sync a search index, create a link. It lives in `src/subscribers/` and exports a handler plus a `config` naming the event.
+
+```ts title="src/subscribers/brand-created.ts"
+import { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+
+export default async function brandCreatedHandler({
+  event,
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const { id } = event.data
+  // ...fetch, then run a workflow
+}
+
+export const config: SubscriberConfig = {
+  event: "brand.created",
+}
+```
+
+### Fetch full data from `{ id }`
+
+<Warning>
+  Event payloads carry **ids, not entities.** A subscriber receives `{ id }` (sometimes a couple of ids) and must fetch the full record it needs via Query. Never rely on a fat event payload — it goes stale and couples the emitter to every consumer's needs.
+</Warning>
+
+```ts
+const query = container.resolve(ContainerRegistrationKeys.QUERY)
+const { data: [brand] } = await query.graph({
+  entity: "brand",
+  fields: ["id", "name", "products.*"],
+  filters: { id: event.data.id },
+})
+```
+
+### Mutate via workflows, never directly
+
+If the subscriber needs to change data, it runs a workflow — same as a route would. The subscriber is the trigger; the workflow is the work.
+
+```ts
+await createBrandNotificationWorkflow(container).run({
+  input: { brand_id: brand.id },
+})
+```
+
+### Log, don't throw
+
+<Warning>
+  A subscriber runs detached from the request. Throwing doesn't surface to a user — it just fails silently or spams retries. **Catch errors and log them** (resolve the `logger`), then decide explicitly whether to rethrow for a retry or swallow.
+</Warning>
+
+```ts
+const logger = container.resolve("logger")
+try {
+  await doWork()
+} catch (e) {
+  logger.error(`brand-created subscriber failed for ${event.data.id}: ${e}`)
+}
+```
+
+### Idempotency and loop guards
+
+Events can be delivered more than once, and a subscriber that mutates data can re-trigger the very event it listens to. Two defences:
+
+- **Idempotency** — make the handler safe to run twice. Check current state before acting (e.g. "is this product already linked to a brand?" before creating the link), or clear the marker that triggered the work so a redelivered event finds nothing left to do.
+- **Loop guards** — if handling event X causes a mutation that emits X again, gate on a condition that becomes false after the first run, or key off a marker you set. Never emit the same event unconditionally from its own subscriber.
+
+<Tip>
+  A good idempotency check reads the current state through Query first and returns early if the work is already done. This makes redelivery harmless and removes the need for exactly-once guarantees.
+</Tip>
+
+## Scheduled jobs — periodic work
+
+A scheduled job runs on a cron interval to do time-based work: poll for records that became ready, reconcile drifted counters, emit a "settle now" event. It lives in `src/jobs/`, exports a handler taking the container, and a `config` with a `name` and a cron `schedule`.
+
+```ts title="src/jobs/deactivate-stale-brands.ts"
+import { MedusaContainer } from "@medusajs/framework/types"
+
+export default async function deactivateStaleBrands(container: MedusaContainer) {
+  const logger = container.resolve("logger")
+  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+
+  const { data: stale } = await query.graph({
+    entity: "brand",
+    fields: ["id"],
+    filters: { is_active: true /* + your staleness condition */ },
+  })
+
+  // pass all ids at once — the workflow handles the batch, not the job
+  await deactivateBrandsWorkflow(container).run({
+    input: { ids: stale.map((b) => b.id) },
+  })
+
+  logger.info(`deactivated ${stale.length} stale brands`)
+}
+
+export const config = {
+  name: "deactivate-stale-brands",
+  schedule: "0 1 * * *", // daily at 01:00 UTC
+}
+```
+
+### When to use a job vs a subscriber
+
+| Trigger | Use |
+| --- | --- |
+| "Something happened" (a workflow emitted an event) | **Subscriber** |
+| "It's time" / "poll for anything that became ready" | **Scheduled job** |
+
+A time-based pipeline often combines both: a daily job finds records that became eligible and emits an event (say `brand.review_due`), and a *subscriber* turns each event into a workflow run. Polling for "what's ready" is the job; reacting to each item is the subscriber.
+
+### Job best practices
+
+- **Do the work in batches** and bound result sets — a job that `SELECT`s an unbounded table will eventually time out. Page through with `LIMIT`/`OFFSET` or a cursor.
+- **Idempotent by design** — a job re-runs on every tick; it must only act on records still needing action (filter on the not-yet-processed state).
+- **Mutations run workflows**, reads run Query — same as everywhere.
+- **Log a summary** each run (how many processed) so drift is visible.
+
+## Checklist
+
+- Subscriber `config.event` names a real emitted event; handler fetches full data from `{ id }` via Query.
+- Subscriber mutations run a workflow; errors are caught and logged, not thrown blindly.
+- Handler is idempotent and can't retrigger its own event without a guard.
+- Job exports `{ name, schedule }`; cron is correct (UTC).
+- Job filters to records still needing work, batches large sets, and logs a summary.
+- Neither a subscriber nor a job writes to the database outside a workflow.

package/content/resources/best-practices/types.mdx

@@ -0,0 +1,120 @@
+---
+title: "Types & augmentation"
+description: "Type the panels against your own backend extensions — augment framework DTOs with declaration merging so every SDK endpoint carries your custom data."
+---
+
+The panels are fully typed against the API through `@mercurjs/types` and the typed SDK. When you extend the backend — adding [custom fields](/rc/resources/best-practices/custom-fields), a [linked module](/rc/resources/best-practices/module-links), an extra field on a DTO — those additions aren't in the shipped types yet. You close the gap in the **frontend** with a small declaration-merging `.d.ts` file. Do that once and *every* SDK call that returns the entity carries your field, typed.
+
+<Warning>
+  **Never use `any` to paper over a missing field.** Casting a response to `any` (or `as { custom_fields: … }` at each call site) throws away type-checking and has to be repeated everywhere. Augment the type once instead.
+</Warning>
+
+## The scenario: a custom field, typed end-to-end
+
+Say you added a custom field on the backend — for example `is_featured` on `product` (see [Custom fields](/rc/resources/best-practices/custom-fields)). The value now comes back from the API, but the panel's `ProductDTO` doesn't know about it, so `product.is_featured` is a type error.
+
+Fix it in the panel with a declaration-merging file.
+
+### Why merging works here
+
+The `ProductDTO` the SDK returns ultimately resolves to Medusa's upstream `ProductDTO`, which is declared as an **`interface`** in `@medusajs/types`. Interfaces are open, so you can **merge into it** with `declare module "@medusajs/types"`.
+
+Because everything downstream — `@mercurjs/types`, the SDK response wrappers (`AdminProductResponse`, list responses), and the panel hooks — refers back to that same interface, your added members appear in all of them at once. You augment in one place and every product-returning endpoint is typed.
+
+### Add the `.d.ts` in the panel
+
+Drop a declaration file anywhere under the panel's `src/` (it's picked up by the app's `tsconfig`):
+
+```ts title="apps/vendor/src/types/custom-fields.d.ts"
+import "@medusajs/types"
+
+declare module "@medusajs/types" {
+  interface ProductDTO {
+    custom_fields?: {
+      is_featured?: boolean
+    }
+  }
+}
+```
+
+<Warning>
+  Two rules or the augmentation silently does nothing:
+
+  - The module name in `declare module "..."` must be the package that declares the interface you're merging into — here `@medusajs/types`, the owner of `UpstreamProductDTO`, **not** `@mercurjs/types` (which only aliases it).
+  - The file must be a module. Add an `import "@medusajs/types"` (or a trailing `export {}`) so TypeScript treats it as one.
+</Warning>
+
+### Now the whole SDK is typed
+
+With that one file in place, no cast is needed anywhere:
+
+```ts title="Every product endpoint carries the field"
+const { products } = await sdk.vendor.products.query()
+products[0].custom_fields?.is_featured // ✅ typed, no cast
+
+const { product } = await sdk.vendor.products.$id.query({ $id: id })
+product.custom_fields?.is_featured     // ✅ typed everywhere ProductDTO flows
+```
+
+<Tip>
+  Types and runtime are separate concerns: this `.d.ts` makes the field *typed*, but it only *arrives* if the fetch asks for it. Let the [custom-fields `link` / registry merge](/rc/resources/best-practices/custom-fields#the-extension-api-link-property) add the fields to the built-in panel fetches rather than hand-adding `+field.*` — the vendor product query in particular rejects arbitrary `*`-relation overrides.
+</Tip>
+
+## Linked data resolves the same way
+
+The augmentation isn't limited to a custom field's own value — it's how you make **linked-module data** typed too. When a [custom-fields config](/rc/resources/best-practices/custom-fields#the-extension-api-link-property) declares a `link`, the panel fetches that module's data alongside the entity ([SPEC-021](/rc/references/panel-extension-api)): `link: "brand"` merges `brand.*` into the built-in product fetch for you — no hand-written field list.
+
+Pair that one config line with a matching augmentation, and the linked data is both **present at runtime** and **typed everywhere `ProductDTO` is imported**:
+
+```ts title="src/custom-fields/product.tsx — declare the link (runtime)"
+export default defineCustomFieldsConfig({
+  model: "product",
+  link: "brand", // brand.* is fetched with every product
+  list: {
+    columns: [
+      { id: "brand_name", header: "Brand", component: ({ row }) => row.brand?.name },
+    ],
+  },
+})
+```
+
+```ts title="src/types/brand.d.ts — declare the shape (types)"
+import "@medusajs/types"
+
+declare module "@medusajs/types" {
+  interface ProductDTO {
+    brand?: { id: string; name: string }
+  }
+}
+```
+
+Now any code that imports `ProductDTO` — a page, a hook, a column renderer — sees `product.brand` resolved, with the data already fetched by the `link`:
+
+```ts
+const { product } = await sdk.vendor.products.$id.query({ $id: id })
+product.brand?.name // ✅ present (via link) and typed (via augmentation)
+```
+
+<Tip>
+  The `link` does the fetching, the `.d.ts` does the typing — you write each once, per model, and every product-returning endpoint in the panel is covered. This is the payoff of augmentation: register the relationship in one place, consume it as a plain typed property everywhere.
+</Tip>
+
+## Where each type goes
+
+| You're adding… | Put it in |
+| --- | --- |
+| A field your API now returns on an entity | A panel `.d.ts` merging into the framework DTO (`declare module "@medusajs/types"`) |
+| A one-off request/response shape for a custom route | Infer it from the Zod validator (`z.infer<typeof Schema>`) and export it |
+| A brand-new Mercur/domain DTO | The domain folder in `@mercurjs/types`, re-exported from `index.ts` |
+
+<Warning>
+  DTOs and enums the platform already ships (`ProductDTO`, `SellerStatus`, `MercurModules`, `HttpTypes`) are imported from `@mercurjs/types` — never redeclared. In the dashboards, `HttpTypes` comes from `@mercurjs/types` too, which is what keeps request/response types aligned with Mercur's extended routes.
+</Warning>
+
+## Checklist
+
+- No `any`, and no per-call-site casts for extended data.
+- Backend additions typed in the panel via a `.d.ts` merging into the **framework** interface that owns the DTO.
+- Augmentation files name the correct package and are real modules (`import`/`export {}`).
+- Extended fields are requested with `+field.*` so they actually arrive.
+- Shipped types imported from `@mercurjs/types`; one-off shapes inferred from Zod.

package/content/resources/best-practices/workflows.mdx

@@ -0,0 +1,173 @@
+---
+title: "Workflows"
+description: "Where all business logic and mutations live — composition-function constraints, one-mutation-per-step with compensation, reusing built-in steps, and the query engine."
+---
+
+A workflow is the orchestration layer: it coordinates a business operation across one or more modules as a series of **steps**, with automatic rollback (**compensation**) if any step fails. Every mutation in Mercur runs inside a workflow — this is the single most important rule in the [architecture](/rc/resources/best-practices/overview).
+
+<Warning>
+  **All mutations go through a workflow.** API routes, subscribers, and scheduled jobs never write to the database directly — they *run a workflow*. That is what gives every mutation validation, event emission, and rollback.
+</Warning>
+
+<Note>
+  Workflows are a [Medusa framework primitive](https://docs.medusajs.com/learn/fundamentals/workflows). This page focuses on the constraints and conventions that trip people (and agents) up.
+</Note>
+
+## The composition function is not normal JavaScript
+
+The function you pass to `createWorkflow` is a **composition function**. It runs once at build time to wire steps together — it does **not** execute your business logic at request time. Because of that, it has hard constraints:
+
+<Warning>
+  Inside a `createWorkflow` composition function you must **not**:
+
+  - use `async` / `await`
+  - use arrow functions for the composition body (use a named `function`)
+  - use `if` / `else`, `for`, `while`, or `try/catch`
+  - use `new Date()`, `Math.random()`, or any non-deterministic call
+  - access properties of a step's output directly (e.g. `result.id`)
+
+  These run at composition time, not execution time, so they either do nothing useful or break replay/rollback.
+</Warning>
+
+Anything that looks like normal logic goes into a **step** (for side effects) or a **`transform`** (for shaping data between steps):
+
+```ts title="src/workflows/create-brands.ts"
+import {
+  createWorkflow,
+  transform,
+  WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+
+import { createBrandsStep } from "./steps"
+
+export const createBrandsWorkflow = createWorkflow(
+  "create-brands",
+  function (input: CreateBrandsWorkflowInput) {
+    // ✅ shape data with transform, not inline expressions
+    const toCreate = transform(input, ({ brands }) =>
+      brands.map((b) => ({ ...b, is_active: b.is_active ?? true }))
+    )
+
+    const brands = createBrandsStep(toCreate)
+
+    return new WorkflowResponse(brands)
+  }
+)
+```
+
+<Tip>
+  Need a conditional or a computed value? Use `transform` to derive data, `when` to run a step conditionally, and put date/random/id generation **inside a step**. Never branch in the composition body itself.
+</Tip>
+
+## One mutation per step + compensation
+
+A step is the unit of work and the unit of rollback. The rule: **each step performs a single mutation and defines how to undo it.** `createStep` takes an invoke function and a compensation function; the invoke returns a `StepResponse` whose second argument is the data the compensation needs.
+
+```ts title="src/workflows/steps/create-brands.ts"
+import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
+import BrandModuleService from "../../modules/brand/service"
+import { BRAND_MODULE } from "../../modules/brand"
+
+export const createBrandsStep = createStep(
+  "create-brands",
+  async (data: CreateBrandInput[], { container }) => {
+    const service = container.resolve<BrandModuleService>(BRAND_MODULE)
+    const brands = await service.createBrands(data)
+    // 2nd arg → passed to the compensation function below
+    return new StepResponse(brands, brands.map((b) => b.id))
+  },
+  async (ids: string[] | undefined, { container }) => {
+    if (!ids?.length) {
+      return
+    }
+    const service = container.resolve<BrandModuleService>(BRAND_MODULE)
+    await service.deleteBrands(ids)
+  }
+)
+```
+
+If a later step in the workflow throws, Medusa runs the compensation functions of the already-completed steps in reverse — the `createBrands` above is undone by `deleteBrands`. Splitting mutations one-per-step is what makes this reliable: a step that does two writes can only half-compensate.
+
+## Reuse built-in steps
+
+Don't hand-roll what the framework already ships. Medusa's `core-flows` exports composable steps you should reuse instead of writing your own:
+
+| Need | Built-in step |
+| --- | --- |
+| Create/remove module links | `createRemoteLinkStep` / `dismissRemoteLinkStep` |
+| Emit a domain event | `emitEventStep` |
+| Call another workflow as a step | `otherWorkflow.runAsStep({ input })` |
+
+```ts title="Composing built-in steps + a sub-workflow"
+import { emitEventStep } from "@medusajs/medusa/core-flows"
+
+export const createBrandsWorkflow = createWorkflow(
+  "create-brands",
+  function (input: CreateBrandsWorkflowInput) {
+    const brands = createBrandsStep(input.brands)
+
+    // reuse a whole workflow as one step
+    notifyOwnersWorkflow.runAsStep({ input: { brands } })
+
+    // reuse the built-in event step
+    emitEventStep({ eventName: "brand.created", data: { ids: brands } })
+
+    return new WorkflowResponse(brands)
+  }
+)
+```
+
+<Tip>
+  Prefer `runAsStep` over duplicating logic. If two workflows need the same sequence, extract it into its own workflow and call it as a step from both — you get one place to maintain and correct compensation for free.
+</Tip>
+
+## Hooks — let others extend your workflow
+
+Expose extension points with `createHook` so consumers can inject behaviour (validation, side effects) without forking the workflow. Add a `validate` hook before the mutation and a `brandsCreated` hook after it:
+
+```ts
+const validate = createHook("validate", { input })
+
+const brands = createBrandsStep(input.brands)
+
+const brandsCreated = createHook("brandsCreated", {
+  brands,
+  additional_data: input.additional_data,
+})
+
+return new WorkflowResponse(brands, {
+  hooks: [validate, brandsCreated],
+})
+```
+
+Consumers register a handler on the hook to run custom logic at that point. This is the sanctioned way to extend a workflow — see [Extend a workflow](/rc/resources/customization/extend-a-workflow).
+
+## The query engine
+
+Reads inside a step (and anywhere else) go through **Query** — the graph engine that resolves data across modules and links. Resolve it from the container and call `query.graph`:
+
+```ts title="Reading across modules inside a step"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+const query = container.resolve(ContainerRegistrationKeys.QUERY)
+
+const { data: brands } = await query.graph({
+  entity: "brand",
+  fields: ["id", "name", "products.*"], // follows the product ↔ brand link
+  filters: { is_active: true },
+})
+```
+
+<Warning>
+  Query is for **reads**. Never try to mutate through it, and never resolve another module's service inside a step to read its data — go through Query so module isolation and links are respected.
+</Warning>
+
+## Checklist for a workflow
+
+- Composition function is a named `function`, with no `async`/`await`, `if`, loops, `try/catch`, `new Date()`, or step-output property access.
+- Data shaping between steps uses `transform`; conditional steps use `when`.
+- Each step does exactly one mutation and defines a compensation function.
+- `StepResponse` passes the compensation the data it needs to undo the work.
+- Built-in steps (`createRemoteLinkStep`, `emitEventStep`) and `runAsStep` are reused instead of reimplemented.
+- Reads use `query.graph`; no cross-module service calls.
+- Extension points are exposed as hooks, not by forking.

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

@@ -0,0 +1,113 @@
+---
+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."
+---
+
+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.
+
+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.
+</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`.
+
+    ```tsx apps/vendor/src/widgets/order-copy-link.tsx
+    import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
+    import type { HttpTypes } from "@medusajs/types"
+    import { Button, Container, toast } from "@medusajs/ui"
+
+    export const config = defineWidgetConfig({
+      zone: "orders.detail.summary.after",
+    })
+
+    const OrderCopyLink = ({ data: order }: { data?: HttpTypes.AdminOrder }) => {
+      if (!order) return null
+
+      const orderLink = `${window.location.origin}/orders/${order.id}`
+
+      const handleCopy = async () => {
+        try {
+          await navigator.clipboard.writeText(orderLink)
+          toast.success("Link copied")
+        } catch {
+          toast.error("Couldn't copy the link")
+        }
+      }
+
+      return (
+        <Container className="flex items-center justify-end p-3">
+          <Button size="small" variant="secondary" onClick={handleCopy}>
+            Copy link
+          </Button>
+        </Container>
+      )
+    }
+
+    export default OrderCopyLink
+    ```
+  </Step>
+  <Step title="Understand 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.
+  </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.
+  </Step>
+</Steps>
+
+## Order detail zones
+
+Zones mounted on the vendor order detail page:
+
+| Zone | Where it renders |
+|------|------------------|
+| `orders.detail.summary.before` / `.after` | Inside the order summary section (around its footer) |
+| `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.
+
+## 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.
+
+## 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.
+  </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.
+  </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`.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
+    The general widget model and the full list of zones.
+  </Card>
+  <Card title="Extend forms and tables" href="/rc/resources/tutorials/extend-forms-and-tables">
+    Add validated fields and columns with defineCustomFieldsConfig.
+  </Card>
+</CardGroup>