@mercurjs/docs 2.2.0-rc.1 → 2.2.0-rc.2

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/llms.txt

@@ -28,6 +28,15 @@ package (`node_modules/@mercurjs/docs/`).
 - [LLMs](content/resources/ai/llms.mdx) — Feed Mercur documentation directly to LLMs for accurate, context-aware assistance.
 - [MCP Server](content/resources/ai/mcp.mdx) — Connect your AI environment to Mercur documentation via Model Context Protocol.
 - [Building with AI](content/resources/ai/overview.mdx) — Mercur ships version-matched docs inside your project so AI coding agents build from accurate APIs instead of stale training data.
+- [API routes](content/resources/best-practices/api-routes.mdx) — Thin HTTP adapters — typed request/response generics, Zod validation with createFindParams, filterable fields, middlewares as filters, and queryConfig.
+- [Custom fields](content/resources/best-practices/custom-fields.mdx) — The full loop — add a custom field in core, render it in the panels with defineCustomFieldsConfig, pull linked data with the link property, and type it end-to-end.
+- [Frontend](content/resources/best-practices/frontend.mdx) — Build panel UI the right way — @medusajs/ui usage, custom-field extensions (forms, tables, read-only section fields), and new pages, with the correct imports.
+- [Module links](content/resources/best-practices/module-links.mdx) — Relate modules without coupling them — defineLink, the link-direction rule, built-in link steps, and filtering by links.
+- [Modules](content/resources/best-practices/modules.mdx) — Keep modules thin — data access and CRUD only. Naming, decorators, and what must never live in a module service.
+- [Best Practices Overview](content/resources/best-practices/overview.mdx) — How to build with Mercur — the layered architecture, the non-negotiable rules, and where each piece of logic belongs.
+- [Subscribers & jobs](content/resources/best-practices/subscribers-and-jobs.mdx) — React to events and run periodic work safely — fetch from { id }, mutate via workflows, log-don't-throw, idempotency and loop guards, cron jobs.
+- [Types & augmentation](content/resources/best-practices/types.mdx) — Type the panels against your own backend extensions — augment framework DTOs with declaration merging so every SDK endpoint carries your custom data.
+- [Workflows](content/resources/best-practices/workflows.mdx) — Where all business logic and mutations live — composition-function constraints, one-mutation-per-step with compensation, reusing built-in steps, and the query engine.
 - [Custom Fields](content/resources/customization/custom-fields.mdx) — Extend any Medusa entity with additional fields without modifying core code.
 - [Extend a workflow](content/resources/customization/extend-a-workflow.mdx) — Inject custom logic into an existing Mercur workflow through hooks — without rewriting it.
 - [Extending Panels](content/resources/customization/extending-panels.mdx) — Add pages, inject widgets, customize navigation, and extend forms and tables in the admin and vendor panels.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercurjs/docs",
-  "version": "2.2.0-rc.1",
+  "version": "2.2.0-rc.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/mercurjs/mercur",