@mercurjs/docs 2.2.1 → 2.3.0-canary.1

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

@@ -1,12 +1,13 @@
 ---
-title: "Best Practices Overview"
-description: "How to build with Mercur — the layered architecture, the non-negotiable rules, and where each piece of logic belongs."
+title: "How-to Guides"
+sidebarTitle: "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`.
+  Mercur is a marketplace platform built on Medusa. Every rule here is either a Medusa 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
@@ -29,7 +30,7 @@ graph TD
 
 <CardGroup cols={2}>
   <Card title="Module" icon="cube">
-    Owns one domain's data. Thin CRUD only — no orchestration, no cross-module calls.
+    Owns one domain's data. Thin CRUD only, with no orchestration and 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.
@@ -38,20 +39,20 @@ graph TD
     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`.
+    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.
+- **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.
+These are hard rules. Breaking one produces code that looks like it works but silently violates the architecture, with 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.
@@ -92,24 +93,51 @@ When you're about to write a piece of logic, find the concern in this table befo
   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
+## Guides
 
-Each page that follows drills into one layer and its rules:
+Follow these guides to build each layer the Mercur way.
+
+### Server
 
 <CardGroup cols={2}>
-  <Card title="Modules" href="/rc/resources/best-practices/modules" icon="cube">
+  <Card title="Create a Module" href="/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">
+  <Card title="Link Modules" href="/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">
+  <Card title="Create a Workflow" href="/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">
+  <Card title="Create an API Route" href="/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">
+  <Card title="Subscribers & Jobs" href="/resources/best-practices/subscribers-and-jobs" icon="clock">
     Event-driven side effects and scheduled work done safely.
   </Card>
+  <Card title="Add a Custom Field" href="/resources/best-practices/custom-fields" icon="table-cells">
+    Attach data to an entity end-to-end, from core to the panels.
+  </Card>
+</CardGroup>
+
+### Panels
+
+<CardGroup cols={2}>
+  <Card title="Extend the Panels" href="/resources/customization/extending-panels" icon="window">
+    The extension model shared by the Admin and Vendor panels.
+  </Card>
+  <Card title="Add a Widget" href="/resources/tutorials/add-a-widget" icon="puzzle-piece">
+    Inject a component into a built-in page zone.
+  </Card>
+</CardGroup>
+
+### Blocks
+
+<CardGroup cols={2}>
+  <Card title="Add a Block" href="/resources/tutorials/add-a-block" icon="cubes">
+    Install a feature block into your project.
+  </Card>
+  <Card title="Build a Block" href="/resources/tutorials/build-a-block" icon="hammer">
+    Package your own feature as a distributable block.
+  </Card>
 </CardGroup>

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

@@ -1,15 +1,16 @@
 ---
-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."
+title: "How to React to Events and Schedule Jobs"
+sidebarTitle: "Subscribers & Jobs"
+description: "Run work outside the request cycle: react to events with subscribers, run periodic work with scheduled jobs, and always mutate through workflows."
 ---
 
-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 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
+## 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.
+A subscriber listens for a domain event (emitted by a workflow via `emitEventStep`) and runs an asynchronous side effect, such as sending a notification, syncing a search index, or creating a link. It lives in `src/subscribers/` and exports a handler plus a `config` naming the event.
 
-```ts title="src/subscribers/brand-created.ts"
+```ts apps/api/src/subscribers/brand-created.ts
 import { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
 
 export default async function brandCreatedHandler({
@@ -28,10 +29,12 @@ export const config: SubscriberConfig = {
 ### 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.
+  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
+Fetch what you need through Query, keyed by the id on the event.
+
+```ts apps/api/src/subscribers/brand-created.ts
 const query = container.resolve(ContainerRegistrationKeys.QUERY)
 const { data: [brand] } = await query.graph({
   entity: "brand",
@@ -42,9 +45,9 @@ const { data: [brand] } = await query.graph({
 
 ### 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.
+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
+```ts apps/api/src/subscribers/brand-created.ts
 await createBrandNotificationWorkflow(container).run({
   input: { brand_id: brand.id },
 })
@@ -53,10 +56,10 @@ await createBrandNotificationWorkflow(container).run({
 ### 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.
+  A subscriber runs detached from the request. Throwing does not 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
+```ts apps/api/src/subscribers/brand-created.ts
 const logger = container.resolve("logger")
 try {
   await doWork()
@@ -67,20 +70,20 @@ try {
 
 ### 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:
+Events can be delivered more than once, and a subscriber that mutates data can re-trigger the very event it listens to. You have 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.
+- **Idempotency:** make the handler safe to run twice. Check current state before acting (for example, "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
+## 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`.
+A scheduled job runs on a cron interval to do time-based work, such as polling for records that became ready, reconciling drifted counters, or emitting 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"
+```ts apps/api/src/jobs/deactivate-stale-brands.ts
 import { MedusaContainer } from "@medusajs/framework/types"
 
 export default async function deactivateStaleBrands(container: MedusaContainer) {
@@ -93,7 +96,7 @@ export default async function deactivateStaleBrands(container: MedusaContainer)
     filters: { is_active: true /* + your staleness condition */ },
   })
 
-  // pass all ids at once — the workflow handles the batch, not the job
+  // pass all ids at once, the workflow handles the batch, not the job
   await deactivateBrandsWorkflow(container).run({
     input: { ids: stale.map((b) => b.id) },
   })
@@ -109,19 +112,21 @@ export const config = {
 
 ### When to use a job vs a subscriber
 
+Pick the trigger that matches how the work starts.
+
 | 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.
+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.
+- **Batch 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, so 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:** report how many records processed each run so drift is visible.
 
 ## Checklist
 
@@ -131,3 +136,11 @@ A time-based pipeline often combines both: a daily job finds records that became
 - 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.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Workflows" href="/rc/resources/best-practices/workflows">
+    Do all mutations through a workflow so subscribers and jobs stay thin triggers.
+  </Card>
+</CardGroup>

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

@@ -1,31 +1,32 @@
 ---
-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."
+title: "How to Use Shared Types"
+sidebarTitle: "Use Shared Types"
+description: "Type the panels against your own backend extensions by augmenting framework DTOs with declaration merging."
 ---
 
-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.
+The panels are fully typed against the API through `@mercurjs/types` and the typed SDK. When you extend the backend with [custom fields](/rc/resources/best-practices/custom-fields), a [linked module](/rc/resources/best-practices/module-links), or an extra field on a DTO, those additions are not in the shipped types yet. You close the gap in the frontend with a small declaration-merging `.d.ts` file. Write it 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.
+  Never use `any` to paper over a missing field. Casting a response to `any`, or to `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.
+Say you added a custom field on the backend, such as `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` does not 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"`.
+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.
+Everything downstream refers back to that same interface: `@mercurjs/types`, the SDK response wrappers such as `AdminProductResponse` and list responses, and the panel hooks. 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`):
+Drop a declaration file anywhere under the panel's `src/`. It is picked up by the app's `tsconfig`.
 
-```ts title="apps/vendor/src/types/custom-fields.d.ts"
+```ts apps/vendor/src/types/custom-fields.d.ts
 import "@medusajs/types"
 
 declare module "@medusajs/types" {
@@ -38,17 +39,17 @@ declare module "@medusajs/types" {
 ```
 
 <Warning>
-  Two rules or the augmentation silently does nothing:
+  Follow 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.
+  - The module name in `declare module "..."` must be the package that declares the interface you are merging into. Here that is `@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"
+```ts Every product endpoint carries the field
 const { products } = await sdk.vendor.products.query()
 products[0].custom_fields?.is_featured // ✅ typed, no cast
 
@@ -57,16 +58,16 @@ 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.
+  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.
+The augmentation is not limited to a custom field's own value. It is 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 (see [panel extensions](/references/panel-extensions/overview)). A `link: "brand"` merges `brand.*` into the built-in product fetch for you, with 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**:
+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)"
+```ts src/custom-fields/product.tsx: declare the link (runtime)
 export default defineCustomFieldsConfig({
   model: "product",
   link: "brand", // brand.* is fetched with every product
@@ -78,7 +79,7 @@ export default defineCustomFieldsConfig({
 })
 ```
 
-```ts title="src/types/brand.d.ts — declare the shape (types)"
+```ts src/types/brand.d.ts: declare the shape (types)
 import "@medusajs/types"
 
 declare module "@medusajs/types" {
@@ -88,7 +89,7 @@ declare module "@medusajs/types" {
 }
 ```
 
-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`:
+Now any code that imports `ProductDTO`, whether a page, a hook, or 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 })
@@ -96,7 +97,7 @@ 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.
+  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, then consume it as a plain typed property everywhere.
 </Tip>
 
 ## Where each type goes
@@ -108,13 +109,27 @@ product.brand?.name // ✅ present (via link) and typed (via augmentation)
 | 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.
+  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 {}`).
+- 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.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Custom fields" href="/rc/resources/best-practices/custom-fields">
+    Add fields, rows, actions, and columns to a built-in model, and declare a `link`.
+  </Card>
+  <Card title="Module links" href="/rc/resources/best-practices/module-links">
+    Link a custom module to a built-in entity and fetch its data alongside.
+  </Card>
+  <Card title="Panel extensions" href="/references/panel-extensions/overview">
+    See how the panel fetches linked module data alongside the entity.
+  </Card>
+</CardGroup>

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

@@ -1,21 +1,22 @@
 ---
-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."
+title: "How to Create a Workflow"
+sidebarTitle: "Create a Workflow"
+description: "Coordinate a business operation across modules as workflow steps, each with automatic rollback, reusing built-in steps and reading through 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).
+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**) when 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.
+  **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.
+  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:
+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**:
@@ -26,12 +27,12 @@ The function you pass to `createWorkflow` is a **composition function**. It runs
   - 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.
+  These run at composition time, not execution time, so they either do nothing useful or break replay and 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"
+```ts src/workflows/create-brands.ts
 import {
   createWorkflow,
   transform,
@@ -56,14 +57,14 @@ export const createBrandsWorkflow = createWorkflow(
 ```
 
 <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.
+  Need a conditional or a computed value? Use `transform` to derive data, `when` to run a step conditionally, and put date, random, or id generation **inside a step**. Never branch in the composition body itself.
 </Tip>
 
-## One mutation per step + compensation
+## One mutation per step and 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.
+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"
+```ts 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"
@@ -86,7 +87,7 @@ export const createBrandsStep = createStep(
 )
 ```
 
-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.
+When 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
 
@@ -98,7 +99,7 @@ Don't hand-roll what the framework already ships. Medusa's `core-flows` exports
 | Emit a domain event | `emitEventStep` |
 | Call another workflow as a step | `otherWorkflow.runAsStep({ input })` |
 
-```ts title="Composing built-in steps + a sub-workflow"
+```ts
 import { emitEventStep } from "@medusajs/medusa/core-flows"
 
 export const createBrandsWorkflow = createWorkflow(
@@ -118,12 +119,12 @@ export const createBrandsWorkflow = createWorkflow(
 ```
 
 <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.
+  Prefer `runAsStep` over duplicating logic. When 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
+## 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:
+Expose extension points with `createHook` so consumers can inject behaviour such as validation or 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 })
@@ -140,13 +141,13 @@ return new WorkflowResponse(brands, {
 })
 ```
 
-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).
+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`:
+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"
+```ts
 import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
 
 const query = container.resolve(ContainerRegistrationKeys.QUERY)
@@ -159,7 +160,7 @@ const { data: brands } = await query.graph({
 ```
 
 <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.
+  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
@@ -171,3 +172,14 @@ const { data: brands } = await query.graph({
 - 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.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Extend a workflow" href="/rc/resources/customization/extend-a-workflow">
+    Register handlers on a workflow's hooks to add behaviour without forking.
+  </Card>
+  <Card title="Best practices overview" href="/rc/resources/best-practices/overview">
+    See how workflows fit the wider Mercur architecture.
+  </Card>
+</CardGroup>