docs: general updates to documentation pages (medusajs#13055)

Author: shahednasser

www/apps/book/app/learn/fundamentals/admin/widgets/page.mdx

@@ -6,13 +6,13 @@ export const metadata = {
 
 # {metadata.title}
 
-In this chapter, you’ll learn more about widgets and how to use them.
+In this chapter, you’ll learn about widgets and how to use them.
 
 ## What is an Admin Widget?
 
-The Medusa Admin dashboard's pages are customizable to insert widgets of custom content in pre-defined injection zones. You create these widgets as React components that allow admin users to perform custom actions.
+The Medusa Admin's pages are customizable for inserting widgets of custom content in pre-defined injection zones. For example, you can add a widget on the product details page that allows admin users to sync products to a third-party service.
 
-For example, you can add a widget on the product details page that allow admin users to sync products to a third-party service.
+You create these widgets as React components that render the content and functionality of the widget.
 
 ---
 
@@ -25,15 +25,18 @@ For example, you can add a widget on the product details page that allow admin u
   }]}
 />
 
-You create a widget in a `.tsx` file under the `src/admin/widgets` directory. The file’s default export must be the widget, which is the React component that renders the custom content. The file must also export the widget’s configurations indicating where to insert the widget.
+You create a widget in a `.tsx` file under the `src/admin/widgets` directory. The file must export:
+
+1. A React component that renders the widget. This will be the file's default export.
+2. The widget’s configurations indicating where to insert the widget.
 
 For example, create the file `src/admin/widgets/product-widget.tsx` with the following content:
 
 ![Example of widget file in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732867137/Medusa%20Book/widget-dir-overview_dqsbct.jpg)
 
 export const widgetHighlights = [
   ["5", "ProductWidget", "The React component of the product widget."], 
-  ["17", "zone", "The zone to inject the widget to."]
+  ["17", "zone", "The zone to inject the widget into."]
 ]
 
 ```tsx title="src/admin/widgets/product-widget.tsx" highlights={widgetHighlights}
@@ -59,11 +62,11 @@ export const config = defineWidgetConfig({
 export default ProductWidget
 ```
 
-You export the `ProductWidget` component, which shows the heading `Product Widget`. In the widget, you use [Medusa UI](!ui!), a package that Medusa maintains to allow you to customize the dashboard with the same components used to build it.
+In the example above, the widget is injected at the top of a product’s details.
 
-To export the widget's configurations, you use `defineWidgetConfig` from the Admin Extension SDK. It accepts as a parameter an object with the `zone` property, whose value is a string or an array of strings, each being the name of the zone to inject the widget into.
+You export the `ProductWidget` component, which displays the heading `Product Widget`. In the widget, you use [Medusa UI](!ui!) to customize the dashboard with the same components used to build it.
 
-In the example above, the widget is injected at the top of a product’s details.
+To export the widget's configuration, you use `defineWidgetConfig` from the Admin Extension SDK. It accepts an object as a parameter with the `zone` property, whose value is a string or an array of strings, each being the name of the zone to inject the widget into.
 
 <Note title="Important" type="warning">
 
@@ -83,9 +86,9 @@ Then, open a product’s details page. You’ll find your custom widget at the t
 
 ---
 
-## Props Passed in Detail Pages
+## Props Passed to Widgets on Detail Pages
 
-Widgets that are injected into a details page receive a `data` prop, which is the main data of the details page.
+Widgets that are injected into a detail page receive a `data` prop, which is the main data of the details page.
 
 For example, a widget injected into the `product.details.before` zone receives the product's details in the `data` prop:
 
@@ -130,23 +133,25 @@ The props type is `DetailWidgetProps`, and it accepts as a type argument the exp
 
 ---
 
-## Injection Zone
+## Injection Zones List
 
-Refer to [this reference](!resources!/admin-widget-injection-zones) for the full list of injection zones and their props.
+Refer to the [Admin Widget Injection Zones](!resources!/admin-widget-injection-zones) reference for the full list of injection zones and their props.
 
 ---
 
 ## Admin Components List
 
-To build admin customizations that match the Medusa Admin's designs and layouts, refer to [this guide](!resources!/admin-components) to find common components.
+While the Medusa Admin uses the [Medusa UI](!ui!) components, it also expands on them for styling and design purposes.
+
+To build admin customizations that match the Medusa Admin's designs and layouts, refer to the [Admin Components](!resources!/admin-components) guide. You'll find components like `Header`, `JSON View`, and more that match the Medusa Admin's design.
 
 ---
 
 ## Show Widgets Conditionally
 
 In some cases, you may want to show a widget only if certain conditions are met. For example, you may want to show a widget only if the product has a brand.
 
-To disable the widget from showing, return an empty fragment from the widget component:
+To prevent the widget from showing, return an empty fragment from the widget component:
 
 ```tsx title="src/admin/widgets/product-widget.tsx"
 import { defineWidgetConfig } from "@medusajs/admin-sdk"

www/apps/book/app/learn/fundamentals/api-routes/http-methods/page.mdx

@@ -8,7 +8,7 @@ In this chapter, you'll learn about how to add new API routes for each HTTP meth
 
 ## HTTP Method Handler
 
-An API route is created for every HTTP method you export a handler function for in a route file.
+An API route is created for every HTTP method you export a handler function for in a `route.ts` or `route.js` file.
 
 Allowed HTTP methods are: `GET`, `POST`, `DELETE`, `PUT`, `PATCH`, `OPTIONS`, and `HEAD`.
 
@@ -39,7 +39,7 @@ export const POST = async (
 }
 ```
 
-This adds two API Routes:
+This file adds two API Routes:
 
-- A `GET` route at `http://localhost:9000/hello-world`.
-- A `POST` route at `http://localhost:9000/hello-world`.
+- A `GET` API route at `http://localhost:9000/hello-world`.
+- A `POST` API route at `http://localhost:9000/hello-world`.

www/apps/book/app/learn/fundamentals/api-routes/page.mdx

@@ -4,25 +4,25 @@ export const metadata = {
 
 # {metadata.title}
 
-In this chapter, you’ll learn what API Routes are and how to create them.
+In this chapter, you’ll learn what API routes are and how to create them.
 
 ## What is an API Route?
 
-An API Route is an endpoint. It exposes commerce features to external applications, such as storefronts, the admin dashboard, or third-party systems.
+An API route is a REST endpoint that exposes commerce features to external applications, such as storefronts, the admin dashboard, or third-party systems.
 
-The Medusa core application provides a set of admin and store API routes out-of-the-box. You can also create custom API routes to expose your custom functionalities.
+The Medusa core application provides a set of [admin](!api!/admin) and [store](!api!/store) API routes out-of-the-box. You can also create custom API routes to expose your custom functionalities.
 
 ---
 
 ## How to Create an API Route?
 
-An API Route is created in a TypeScript or JavaScript file under the `src/api` directory of your Medusa application. The file’s name must be `route.ts` or `route.js`. 
+You can create an API route in a TypeScript or JavaScript file under the `src/api` directory of your Medusa application. The file’s name must be `route.ts` or `route.js`. 
 
 ![Example of API route in the application's directory structure](https://res.cloudinary.com/dza7lstvk/image/upload/v1732808645/Medusa%20Book/route-dir-overview_dqgzmk.jpg)
 
-Each file exports API Route handler functions for at least one HTTP method (`GET`, `POST`, `DELETE`, etc…).
+Each file exports API route handler functions for at least one HTTP method (`GET`, `POST`, `DELETE`, etc…).
 
-For example, to create a `GET` API Route at `/hello-world`, create the file `src/api/hello-world/route.ts` with the following content:
+For example, to create a `GET` API route at `/hello-world`, create the file `src/api/hello-world/route.ts` with the following content:
 
 ```ts title="src/api/hello-world/route.ts"
 import type {
@@ -40,26 +40,30 @@ export const GET = (
 }
 ```
 
-### Test API Route
+### Test the API Route
 
 To test the API route above, start the Medusa application:
 
 ```bash npm2yarn
 npm run dev
 ```
 
-Then, send a `GET` request to the `/hello-world` API Route:
+Then, send a `GET` request to the `/hello-world` API route:
 
 ```bash
 curl http://localhost:9000/hello-world
 ```
 
----
+You should receive the following response:
 
-## When to Use API Routes
+```json
+{
+  "message": "[GET] Hello world!"
+}
+```
 
-<Note title="Use API routes when" type="success">
+---
 
-You're exposing custom functionality to be used by a storefront, admin dashboard, or any external application.
+## Next Chapters: Learn More About API Routes
 
-</Note>
+Follow the next chapters to learn about the different HTTP methods you can use in API routes, parameters and validation, protecting routes, and more.

www/apps/book/app/learn/fundamentals/api-routes/responses/page.mdx

@@ -8,7 +8,7 @@ In this chapter, you'll learn how to send a response in your API route.
 
 ## Send a JSON Response
 
-To send a JSON response, use the `json` method of the `MedusaResponse` object passed as the second parameter of your API route handler.
+To send a JSON response, use the `json` method of the `MedusaResponse` object that is passed as the second parameter of your API route handler.
 
 For example:
 
@@ -78,7 +78,7 @@ export const streamHighlights = [
   ["7", "writeHead", "Set the response's headers."],
   ["7", "200", "Set the status code."],
   ["8", `"Content-Type"`, "Set the response's content type."],
-  ["13", "interval", "Simulate stream data using an interval"],
+  ["13", "interval", "Simulate stream data using an interval."],
   ["14", "write", "Write stream data."],
   ["17", "on", "Stop the stream when the request is terminated."]
 ]
@@ -109,10 +109,10 @@ export const GET = async (
 
 The `writeHead` method accepts two parameters:
 
-1. The first one is the response's status code.
-2. The second is an object of key-value pairs to set the headers of the response.
+1. The first parameter is the response's status code.
+2. The second parameter is an object of key-value pairs to set the response headers.
 
-This API route opens a stream by setting the `Content-Type` in the header to `text/event-stream`. It then simulates a stream by creating an interval that writes the stream data every three seconds.
+This API route opens a stream by setting the `Content-Type` to `text/event-stream`. It then simulates a stream by creating an interval that writes the stream data every three seconds.
 
 ---
 

www/apps/book/app/learn/fundamentals/custom-cli-scripts/page.mdx

@@ -4,17 +4,22 @@ export const metadata = {
 
 # {metadata.title}
 
-In this chapter, you'll learn how to create and execute custom scripts from Medusa's CLI tool.
+In this chapter, you'll learn how to create and execute custom scripts using Medusa's CLI tool.
 
 ## What is a Custom CLI Script?
 
-A custom CLI script is a function to execute through Medusa's CLI tool. This is useful when creating custom Medusa tooling to run through the CLI.
+A custom CLI script is a function that you can execute using Medusa's CLI tool. It is useful when you need a script that has access to the [Medusa container](../medusa-container/page.mdx) and can be executed using Medusa's CLI.
+
+For example, you can create a custom CLI script that:
+
+- [Seeds data into the database](./seed-data/page.mdx).
+- Runs a script before starting the Medusa application.
 
 ---
 
 ## How to Create a Custom CLI Script?
 
-To create a custom CLI script, create a TypeScript or JavaScript file under the `src/scripts` directory. The file must default export a function.
+To create a custom CLI script, create a TypeScript or JavaScript file under the `src/scripts` directory. The file must export a function by default.
 
 For example, create the file `src/scripts/my-script.ts` with the following content:
 
@@ -37,13 +42,13 @@ export default async function myScript({ container }: ExecArgs) {
 }
 ```
 
-The function receives as a parameter an object having a `container` property, which is an instance of the Medusa Container. Use it to resolve resources in your Medusa application.
+The function receives as a parameter an object with a `container` property, which is an instance of the Medusa Container. Use it to resolve resources in your Medusa application.
 
 ---
 
-## How to Run Custom CLI Script?
+## How to Run a Custom CLI Script?
 
-To run the custom CLI script, run the Medusa CLI's `exec` command:
+To run a custom CLI script, run the Medusa CLI's `exec` command:
 
 ```bash
 npx medusa exec ./src/scripts/my-script.ts
@@ -55,7 +60,7 @@ npx medusa exec ./src/scripts/my-script.ts
 
 Your script can accept arguments from the command line. Arguments are passed to the function's object parameter in the `args` property.
 
-For example:
+For example, create the following CLI script that logs the command line arguments:
 
 ```ts
 import { ExecArgs } from "@medusajs/framework/types"
@@ -65,8 +70,32 @@ export default async function myScript({ args }: ExecArgs) {
 }
 ```
 
-Then, pass the arguments in the `exec` command after the file path:
+Then, run the script with the `exec` command and pass arguments after the script's path.
 
 ```bash
 npx medusa exec ./src/scripts/my-script.ts arg1 arg2
 ```
+
+---
+
+## Run Custom Script on Application Startup
+
+In some cases, you may need to perform an action when the Medusa application starts.
+
+If the action is related to a module, you should use a [loader](../modules/loaders/page.mdx). Otherwise, you can create a custom CLI script and run it before starting the Medusa application.
+
+To run a custom script on application startup, modify the `dev` and `start` commands in `package.json` to execute your script first.
+
+For example:
+
+```json title="package.json"
+{
+  "scripts": {
+    "startup": "medusa exec ./src/scripts/startup.ts",
+    "dev": "npm run startup && medusa develop",
+    "start": "npm run startup && medusa start"
+  }
+}
+```
+
+The `startup` script will run every time you run the Medusa application.

www/apps/book/app/learn/fundamentals/modules/modules-directory-structure/page.mdx

@@ -4,26 +4,26 @@ export const metadata = {
 
 # {metadata.title}
 
-In this document, you'll learn about the expected files and directories in your module.
+In this chapter, you'll learn about the expected files and directories in your module.
 
 ![Module Directory Structure Example](https://res.cloudinary.com/dza7lstvk/image/upload/v1714379976/Medusa%20Book/modules-dir-overview_nqq7ne.jpg)
 
 ## index.ts
 
-The `index.ts` file in the root of your module's directory is the only required file. It must export the module's definition as explained in a [previous chapter](../page.mdx).
+The `index.ts` file is in the root of your module's directory and exports the module's definition as explained in the [Modules](../page.mdx) chapter.
 
 ---
 
 ## service.ts
 
-A module must have a main service. It's created in the `service.ts` file at the root of your module directory as explained in a [previous chapter](../page.mdx).
+A module must have a main service that contains the module's business logic. It's created in the `service.ts` file at the root of your module directory as explained in the [Modules](../page.mdx) chapter.
 
 ---
 
 ## Other Directories
 
-The following directories are optional and their content are explained more in the following chapters:
+The following directories are optional and you can choose to create them based on your module's functionality:
 
-- `models`: Holds the data models representing tables in the database.
-- `migrations`: Holds the migration files used to reflect changes on the database.
-- `loaders`: Holds the scripts to run on the Medusa application's start-up.
+- `models`: Holds the [data models](../../data-models/page.mdx) representing tables in the database.
+- `migrations`: Holds the [migration](../../data-models/write-migration/page.mdx) files used to reflect changes on the database.
+- `loaders`: Holds the [script files to run on the application's startup](../loaders/page.mdx) when Medusa loads the module.

www/apps/book/app/learn/fundamentals/scheduled-jobs/execution-number/page.mdx

@@ -1,14 +1,20 @@
 export const metadata = {
-  title: `${pageNumber} Scheduled Jobs Number of Executions`,
+  title: `${pageNumber} Scheduled Job Number of Executions`,
 }
 
 # {metadata.title}
 
 In this chapter, you'll learn how to set a limit on the number of times a scheduled job is executed.
 
-## numberOfExecutions Option
+## Default Number of Scheduled Job Executions
 
-The export configuration object of the scheduled job accepts an optional property `numberOfExecutions`. Its value is a number indicating how many times the scheduled job can be executed during the Medusa application's runtime.
+By default, a scheduled job is executed whenever it matches its specified pattern. For example, if you set a scheduled job to run every five minutes, it will run every five minutes until you stop the Medusa application.
+
+---
+
+## Configure Number of Scheduled Job Executions
+
+To execute a scheduled job a specific number of times only, you can configure it with the `numberOfExecutions` option. Its value is the number of times the scheduled job can be executed during the Medusa application's runtime.
 
 For example:
 
@@ -18,7 +24,7 @@ export const highlights = [
 
 ```ts highlights={highlights}
 export default async function myCustomJob() {
-  console.log("I'll be executed three times only.")
+  console.log("I'll be executed only three times.")
 }
 
 export const config = {
@@ -31,10 +37,10 @@ export const config = {
 
 The above scheduled job has the `numberOfExecutions` configuration set to `3`.
 
-So, it'll only execute 3 times, each every minute, then it won't be executed anymore.
+So, Medusa will execute this job only 3 times, once every minute, and then it won't be executed anymore during the current runtime.
 
-<Note>
+### Configuration is Per Application Runtime
 
-If you restart the Medusa application, the scheduled job will be executed again until reaching the number of executions specified.
+Medusa tracks the number of executions for a scheduled job during its current runtime. Once the application stops, the next time you start it, the counter will be reset to `0`.
 
-</Note>
+So, if you restart the Medusa application, the scheduled job will be executed again until it reaches the number of executions specified.