docs: add more context and description to recipe steps (#9861)

www/apps/resources/app/recipes/digital-products/examples/standard/page.mdx

@@ -51,7 +51,11 @@ By following this example, you’ll have a commerce application with the followi
 
 ## Step 1: Create the Digital Product Module
 
-The first step is to create a digital product module that holds the data models related to a digital product.
+Medusa creates commerce features in modules. For example, product features and data models are created in the Product Module.
+
+You also create custom commerce data models and features in custom modules. They're integrated into the Medusa application similar to Medusa's modules without side effects.
+
+So, you'll create a digital product module that holds the data models related to a digital product and allows you to manage them.
 
 Create the directory `src/modules/digital-product`.
 
@@ -211,7 +215,16 @@ module.exports = defineConfig({
 
 ## Step 2: Define Links
 
-In this step, you’ll define links between your module’s data models and data models from Medusa’s commerce modules.
+Modules are isolated in Medusa, making them reusable, replaceable, and integrable in your application without side effects.
+
+So, you can't have relations between data models in modules. Instead, you define a link between them.
+
+Links are relations between data models of different modules that maintain the isolation between the modules.
+
+In this step, you’ll define links between your module’s data models and data models from Medusa’s commerce modules:
+
+1. Link between the `DigitalProduct` model and the Product Module's `ProductVariant` model.
+2. Link between the `DigitalProductOrder` model and the Order Module's `Order` model.
 
 Start by creating the file `src/links/digital-product-variant.ts` with the following content:
 
@@ -279,6 +292,8 @@ npx medusa db:migrate
 
 ## Step 4: List Digital Products Admin API Route
 
+To expose custom commerce features to frontend applications, such as the Medusa Admin dashboard or a storefront, you expose an endpoint by creating an API route.
+
 In this step, you’ll create the admin API route to list digital products.
 
 Create the file `src/api/admin/digital-products/route.ts` with the following content:
@@ -368,7 +383,9 @@ Make sure to replace `{token}` with the JWT token you retrieved.
 
 ## Step 5: Create Digital Product Workflow
 
-In this step, you’ll create a workflow that creates a digital product. You’ll use this workflow in the next section.
+To implement and expose a feature that manipulates data, you create a workflow that uses services to implement the functionality, then create an API route that executes that workflow.
+
+In this step, you’ll create a workflow that creates a digital product. You’ll use this workflow in an API route in the next section.
 
 This workflow has the following steps:
 
@@ -617,7 +634,7 @@ You’ll test out the workflow in the next section.
 
 ## Step 6: Create Digital Product API Route
 
-In this step, you’ll add the API route to create a digital product.
+In this step, you’ll add the API route to create a digital product using the `createDigitalProductWorkflow`.
 
 In the file `src/api/admin/digital-products/route.ts` add a new route handler:
 
@@ -716,9 +733,7 @@ This adds a validation middleware to ensure that the body of `POST` requests sen
 
 ## Step 7: Upload Digital Product Media API Route
 
-To upload the digital product media files, use Medusa’s file module.
-
-In this step, you’ll create an API route for uploading preview and main digital product media files.
+To upload the digital product media files, use Medusa’s File Module.
 
 <Note>
 
@@ -726,6 +741,8 @@ Your Medusa application uses the local file module provider by default, which up
 
 </Note>
 
+In this step, you’ll create an API route for uploading preview and main digital product media files.
+
 Before creating the API route, install the [multer express middleware](https://expressjs.com/en/resources/middleware/multer.html) to support file uploads:
 
 ```bash npm2yarn
@@ -809,6 +826,8 @@ You’ll test out this API route in the next step as you use these API routes in
 
 ## Step 8: Add Digital Products UI Route in Admin
 
+The Medusa Admin is customizable, allowing you to inject widgets into existing pages or add UI routes to create new pages.
+
 In this step, you’ll add a UI route to the Medusa Admin that displays a list of digital products.
 
 Before you create the UI route, create the file `src/admin/types/index.ts` that holds the following types:
@@ -1819,7 +1838,7 @@ In a later step, you’ll add an API route to allow customers to view and downlo
 
 ## Step 12: Fulfill Digital Order Workflow
 
-In this step, you'll create a workflow that fulfills a digital order by sending a notification to the customer. Later, you'll execute this workflow in a subscriber.
+In this step, you'll create a workflow that fulfills a digital order by sending a notification to the customer. Later, you'll execute this workflow in a subscriber that listens to the `digital_product_order.created` event.
 
 The workflow has the following steps:
 
@@ -2031,6 +2050,8 @@ module.exports = defineConfig({
 
 ## Step 13: Handle the Digital Product Order Event
 
+A subscriber is an asynchronous function that, when an event is emitted, is executed. You can implement in subscribers features that aren't essential to the original flow that emitted the event.
+
 In this step, you'll create a subscriber that listens to the `digital_product_order.created` event and executes the workflow from the above step.
 
 Create the file `src/subscribers/handle-digital-order.ts` with the following content:

www/apps/resources/app/recipes/marketplace/examples/restaurant-delivery/page.mdx

@@ -65,7 +65,11 @@ This recipe is adapted from [Medusa Eats](https://github.com/medusajs/medusa-eat
 
 ## Step 1: Create a Restaurant Module
 
-In this step, you’ll create a Restaurant Module that defines the models related to a restaurant.
+Medusa creates commerce features in modules. For example, product features and data models are created in the Product Module.
+
+You also create custom commerce data models and features in custom modules. They're integrated into the Medusa application similar to Medusa's modules without side effects.
+
+So, you'll create a restaurant module that holds the data models related to a restaurant and allows you to manage them.
 
 Create the directory `src/modules/restaurant`.
 
@@ -317,7 +321,18 @@ module.exports = defineConfig({
 
 ## Step 3: Define Links
 
-In this step, you’ll define links between the Restaurant and Delivery modules, and other modules.
+Modules are isolated in Medusa, making them reusable, replaceable, and integrable in your application without side effects.
+
+So, you can't have relations between data models in modules. Instead, you define a link between them.
+
+Links are relations between data models of different modules that maintain the isolation between the modules.
+
+In this step, you’ll define links between the Restaurant and Delivery modules, and other modules:
+
+1. Link between the `Restaurant` model and the Product Module's `Product` model.
+2. Link between the `Restaurant` model and the Delivery Module's `Delivery` model.
+3. Link between the `Delivery` model and the Cart Module's `Cart` model.
+4. Link between the `Delivery` model and the Order Module's `Order` model.
 
 ### Restaurant \<> Product Link
 
@@ -425,6 +440,8 @@ npx medusa db:migrate
 
 ## Step 5: Create Restaurant API Route
 
+To expose custom commerce features to frontend applications, such as the Medusa Admin dashboard or a storefront, you expose an endpoint by creating an API route.
+
 In this step, you’ll create the API route used to create a restaurant. This route requires no authentication, as anyone can create a restaurant.
 
 ### Create Types
@@ -704,7 +721,9 @@ Medusa provides an authentication flow that allows you to authenticate custom us
 
 ### Create Workflow
 
-Start by implementing the functionality to create a user in a workflow. The workflow has two steps:
+To implement and expose a feature that manipulates data, you create a workflow that uses services to implement the functionality, then create an API route that executes that workflow.
+
+So, you'll start by implementing the functionality to create a user in a workflow. The workflow has two steps:
 
 1. Create the user in the database.
 2. Set the actor type of the user’s authentication identity (created by the `/auth/{actor_type}/{provider}/register` API route). For this step, you’ll use the `setAuthAppMetadataStep` step imported from the `@medusajs/medusa/core-flows` package.
@@ -882,7 +901,7 @@ In the workflow, you:
 
 ### Create API Route
 
-You’ll now create the API route to create a new user.
+You’ll now create the API route to create a new user using the `createUserWorkflow`.
 
 Start by creating the file `src/api/users/validation-schemas.ts` that holds the schema necessary to validate the request body:
 
@@ -938,6 +957,8 @@ This creates a `POST` API route at `/users` that creates a driver or a restauran
 
 ### Add Authentication Middleware
 
+A middleware is executed when an HTTP request is received and before the route handler. It can be used to guard routes based on restrictions or authentication.
+
 The `/users` API route must only be accessed with the authentication token in the header. So, you must add an authentication middleware on the route.
 
 Create the file `src/api/middlewares.ts` with the following content:

www/apps/resources/app/recipes/marketplace/examples/vendors/page.mdx

@@ -50,7 +50,11 @@ By following this example, you’ll have a marketplace with the following featur
 
 ## Step 1: Create Marketplace Module
 
-The first step is to create a marketplace module that holds the data models for a vendor and an admin. 
+Medusa creates commerce features in modules. For example, product features and data models are created in the Product Module.
+
+You also create custom commerce data models and features in custom modules. They're integrated into the Medusa application similar to Medusa's modules without side effects.
+
+So, you'll create a marketplace module that holds the data models for a vendor and an admin and allows you to manage them.
 
 Create the directory `src/modules/marketplace`.
 
@@ -157,6 +161,12 @@ module.exports = defineConfig({
 
 ## Step 2: Define Links to Product and Order Data Models
 
+Modules are isolated in Medusa, making them reusable, replaceable, and integrable in your application without side effects.
+
+So, you can't have relations between data models in modules. Instead, you define a link between them.
+
+Links are relations between data models of different modules that maintain the isolation between the modules.
+
 Each vendor has products and orders. So, in this step, you’ll define links between the `Vendor` data model and the `Product` and `Order` data models from the Product and Order modules, respectively.
 
 <Note title="Tip">
@@ -227,7 +237,9 @@ npx medusa db:migrate
 
 ## Step 4: Create Vendor Admin Workflow
 
-In this step, you’ll create the workflow used to create a vendor admin.
+To implement and expose a feature that manipulates data, you create a workflow that uses services to implement the functionality, then create an API route that executes that workflow.
+
+In this step, you’ll create the workflow used to create a vendor admin. You'll use it in the next step in an API route.
 
 The workflow’s steps are:
 
@@ -347,6 +359,8 @@ You return the created vendor admin.
 
 ## Step 5: Create Vendor API Route
 
+To expose custom commerce features to frontend applications, such as the Medusa Admin dashboard or a storefront, you expose an endpoint by creating an API route.
+
 In this step, you’ll create the API route that runs the workflow from the previous step.
 
 Start by creating the file `src/api/vendors/route.ts` with the following content:

www/apps/resources/app/recipes/subscriptions/examples/standard/page.mdx

@@ -51,7 +51,11 @@ By following this example, you’ll have a subscription commerce store with the
 
 ## Step 1: Create Subscription Module
 
-The first step is to create a subscription module that holds the subscription's data model and provides data-management features through its service.
+Medusa creates commerce features in modules. For example, product features and data models are created in the Product Module.
+
+You also create custom commerce data models and features in custom modules. They're integrated into the Medusa application similar to Medusa's modules without side effects.
+
+So, you'll create a subscription module that holds the data models related to a subscription and allows you to manage them.
 
 Create the directory `src/modules/subscription`.
 
@@ -176,7 +180,17 @@ module.exports = defineConfig({
 
 ## Step 2: Define Links
 
-In this step, you’ll define links between the Subscription Module’s `Subscription` data model and the data models of Medusa’s commerce modules.
+Modules are isolated in Medusa, making them reusable, replaceable, and integrable in your application without side effects.
+
+So, you can't have relations between data models in modules. Instead, you define a link between them.
+
+Links are relations between data models of different modules that maintain the isolation between the modules.
+
+In this step, you’ll define links between the Subscription Module’s `Subscription` data model and the data models of Medusa’s commerce modules:
+
+1. Link between the `Subscription` data model and the Cart Module's `Cart` model.
+2. Link between the `Subscription` data model and the Customer Module's `Customer` model.
+3. Link between the `Subscription` data model and the Order Module's `Order` model.
 
 ### Define a Link to Cart
 
@@ -436,6 +450,8 @@ This method is used in the next step.
 
 ## Step 5: Create Subscription Workflow
 
+To implement and expose a feature that manipulates data, you create a workflow that uses services to implement the functionality, then create an API route that executes that workflow.
+
 In this step, you’ll create the workflow that you’ll execute when a customer purchases a subscription.
 
 The workflow accepts a cart’s ID, and it has three steps:
@@ -648,6 +664,8 @@ The workflow returns the created subscription and order.
 
 ## Step 6: Override Complete Cart API Route
 
+To expose custom commerce features to frontend applications, such as the Medusa Admin dashboard or a storefront, you expose an endpoint by creating an API route.
+
 In this step, you’ll change what happens when the [Complete Cart API route](!api!/store#carts_postcartsidcomplete) is used to complete the customer’s purchase and place an order.
 
 Create the file `src/api/store/carts/[id]/complete/route.ts` with the following content:
@@ -1076,6 +1094,8 @@ In the next section, you’ll extend the Medusa admin and use these API routes t
 
 ## Step 8: Extend Admin
 
+The Medusa Admin is customizable, allowing you to inject widgets into existing pages or add UI routes to create new pages.
+
 In this step, you’ll add two UI routes:
 
 1. One to view all subscriptions.
@@ -1874,6 +1894,8 @@ In the next step, you’ll execute the workflow in a scheduled job.
 
 ## Step 10: Create New Subscription Orders Scheduled Job
 
+A scheduled job is an asynchronous function executed at a specified interval pattern. Use scheduled jobs to execute a task at a regular interval.
+
 In this step, you’ll create a scheduled job that runs once a day. It finds all subscriptions whose `next_order_date` property is the current date and uses the workflow from the previous step to create an order for them.
 
 Create the file `src/jobs/create-subscription-orders.ts` with the following content: