docs: general improvements (medusajs#13530)

Author: shahednasser

www/apps/book/app/learn/fundamentals/workflows/workflow-hooks/page.mdx

@@ -4,11 +4,11 @@ export const metadata = {
 
 # {metadata.title}
 
-In this chapter, you'll learn what a workflow hook is and how to consume them.
+In this chapter, you'll learn what workflow hooks are and how to use them.
 
 ## What is a Workflow Hook?
 
-A workflow hook is a point in a workflow where you can inject custom functionality as a step function, called a hook handler.
+A workflow hook is a specific point in a workflow where you can inject custom functionality. This custom functionality is called a hook handler.
 
 Medusa exposes hooks in many of its workflows that are used in its API routes. You can consume those hooks to add your custom logic.
 
@@ -28,13 +28,13 @@ You want to perform a custom action during a workflow's execution, such as when
 
 ## How to Consume a Hook?
 
-A workflow has a special `hooks` property which is an object that holds its hooks.
+A workflow has a special `hooks` property. This property is an object that contains all available hooks.
 
 So, in a TypeScript or JavaScript file created under the `src/workflows/hooks` directory:
 
-- Import the workflow.
-- Access its hook using the `hooks` property.
-- Pass the hook a step function as a parameter to consume it.
+1. Import the workflow.
+2. Access the hook using the `hooks` property.
+3. Pass a step function as a parameter to the hook.
 
 For example, to consume the `productsCreated` hook of Medusa's `createProductsWorkflow`, create the file `src/workflows/hooks/product-created.ts` with the following content:
 
@@ -52,15 +52,15 @@ createProductsWorkflow.hooks.productsCreated(
 )
 ```
 
-The `productsCreated` hook is available on the workflow's `hooks` property by its name.
+The `productsCreated` hook is available in the workflow's `hooks` property.
 
-You invoke the hook, passing a step function (the hook handler) as a parameter.
+You call the hook and pass a step function (the hook handler) as a parameter.
 
-Now, when a product is created using the [Create Product API route](!api!/admin#products_postproducts), your hook handler is executed after the product is created.
+Now, when a product is created using the [Create Product API route](!api!/admin#products_postproducts), your hook handler runs after the product is created.
 
 <Note>
 
-A hook can have only one handler.
+A hook can have only one handler. So, you can't consume the same hook multiple times.
 
 </Note>
 
@@ -74,7 +74,9 @@ Refer to the [createProductsWorkflow reference](!resources!/references/medusa-wo
 
 Since a hook handler is essentially a step function, it receives the hook's input as a first parameter, and an object holding a `container` property as a second parameter.
 
-Each hook has different input. For example, the `productsCreated` hook receives an object having a `products` property holding the created product.
+Each hook has different input. For example, the `productsCreated` hook receives an object with a `products` property that contains the created product.
+
+You can find the input for each workflow's hooks in the [Core Workflows Reference](!resources!/medusa-workflows-reference).
 
 ### Hook Handler Compensation
 
@@ -97,15 +99,15 @@ createProductsWorkflow.hooks.productsCreated(
 )
 ```
 
-The compensation function is executed if an error occurs in the workflow to undo the actions performed by the hook handler.
+The compensation function runs if an error occurs in the workflow. It undoes the actions performed by the hook handler.
 
-The compensation function receives as an input the second parameter passed to the `StepResponse` returned by the step function.
+The compensation function receives the second parameter passed to the `StepResponse` returned by the step function as input.
 
-It also accepts as a second parameter an object holding a `container` property to resolve resources from the Medusa container.
+It also accepts an object with a `container` property as a second parameter. This allows you to resolve resources from the Medusa container.
 
 ### Additional Data Property
 
-Medusa's workflows pass in the hook's input an `additional_data` property:
+Medusa's workflows include an `additional_data` property in the hook's input:
 
 ```ts title="src/workflows/hooks/product-created.ts" highlights={[["4", "additional_data"]]}
 import { createProductsWorkflow } from "@medusajs/medusa/core-flows"
@@ -117,17 +119,13 @@ createProductsWorkflow.hooks.productsCreated(
 )
 ```
 
-This property is an object that holds additional data passed to the workflow through the request sent to the API route using the workflow.
-
-<Note>
+This property is an object that contains additional data passed to the workflow through the request sent to the API route.
 
-Learn how to pass `additional_data` in requests to API routes in [this chapter](../../api-routes/additional-data/page.mdx).
-
-</Note>
+Learn how to pass `additional_data` in requests to API routes in the [Additional Data](../../api-routes/additional-data/page.mdx) chapter.
 
 ### Pass Additional Data to Workflow
 
-You can also pass that additional data when executing the workflow. Pass it as a parameter to the `.run` method of the workflow:
+You can also pass additional data when running the workflow. Pass it as a parameter to the workflow's `.run` method:
 
 ```ts title="src/workflows/hooks/product-created.ts" highlights={[["10", "additional_data"]]}
 import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
@@ -147,4 +145,4 @@ export async function POST(req: MedusaRequest, res: MedusaResponse) {
 }
 ```
 
-Your hook handler then receives that passed data in the `additional_data` object.
+Your hook handler then receives the passed data in the `additional_data` object.

www/apps/book/app/learn/storefront-development/page.mdx

@@ -6,9 +6,15 @@ export const metadata = {
 
 # {metadata.title}
 
-The Medusa application is made up of a Node.js server and an admin dashboard. Storefronts are installed, built, and hosted separately from the Medusa application, giving you the flexibility to choose the frontend tech stack that you and your team are proficient in, and implement unique design systems and user experience.
+In this chapter, you'll learn about storefronts and how to build one.
 
-You can build your storefront from scratch with your preferred tech stack, or start with our Next.js Starter storefront. The Next.js Starter storefront provides rich commerce features and a sleek design. Developers and businesses can use it as-is or build on top of it to tailor it for the business's unique use case, design, and customer experience.
+## Storefronts in Medusa
+
+The Medusa application includes a Node.js server and an admin dashboard. Storefronts are separate applications that you install, build, and host independently from Medusa. This gives you the flexibility to choose your preferred frontend tech stack and implement unique designs and user experiences.
+
+In your storefront, you can retrieve data and perform commerce operations by sending requests to the Medusa application's [Store API routes](!api!/store) and your custom API routes.
+
+You can build your storefront from scratch with your preferred tech stack, or start with our Next.js Starter storefront. The Next.js Starter storefront provides rich commerce features and a modern design. You can use it as-is or customize it to match your business needs, design requirements, and customer experience goals.
 
 <CardList
   items={[
@@ -25,12 +31,12 @@ You can build your storefront from scratch with your preferred tech stack, or st
 
 ---
 
-## Passing a Publishable API Key in Storefront Requests
+## Using a Publishable API Key in Storefront Requests
 
-When sending a request to an API route starting with `/store`, you must include a publishable API key in the header of your request.
+When sending requests to API routes that start with `/store`, you must include a publishable API key in the request header.
 
 A publishable API key sets the scope of your request to one or more sales channels.
 
-Then, when you retrieve products, only products of those sales channels are retrieved. This also ensures you retrieve correct inventory data, and associate created orders with the scoped sales channel.
+When you retrieve products, only products from those sales channels are returned. This also ensures you get correct inventory data and associate created orders with the right sales channel.
 
-Learn more about passing the publishable API key in [this storefront development guide](!resources!/storefront-development/publishable-api-keys).
+Learn more about using the publishable API key in the [Storefront Development guide](!resources!/storefront-development/publishable-api-keys).

www/apps/book/generated/edit-dates.mjs

@@ -5,9 +5,9 @@ export const generatedEditDates = {
   "app/learn/page.mdx": "2025-06-27T11:39:15.941Z",
   "app/learn/fundamentals/modules/commerce-modules/page.mdx": "2025-04-17T08:51:32.723Z",
   "app/learn/fundamentals/workflows/retry-failed-steps/page.mdx": "2025-09-15T09:38:18.299Z",
-  "app/learn/fundamentals/workflows/workflow-hooks/page.mdx": "2024-12-09T10:44:33.781Z",
+  "app/learn/fundamentals/workflows/workflow-hooks/page.mdx": "2025-09-16T15:52:33.602Z",
   "app/learn/debugging-and-testing/logging/page.mdx": "2025-08-28T15:31:57.879Z",
-  "app/learn/storefront-development/page.mdx": "2024-12-10T09:11:04.993Z",
+  "app/learn/storefront-development/page.mdx": "2025-09-16T15:57:42.189Z",
   "app/learn/fundamentals/page.mdx": "2024-07-04T17:26:03+03:00",
   "app/learn/fundamentals/admin-customizations/page.mdx": "2024-10-07T12:41:39.218Z",
   "app/learn/fundamentals/workflows/workflow-timeout/page.mdx": "2025-04-24T13:15:14.472Z",