docs: update auth docs + add new storefront guides

www/apps/resources/app/architectural-modules/notification/sendgrid/page.mdx

@@ -168,7 +168,7 @@ export default async function productCreateHandler({
         disposition: "attachment or inline attachment",
         id: "id", // only needed for inline attachment
       },
-    ]
+    ],
   })
 }
 

www/apps/resources/app/commerce-modules/auth/auth-flows/page.mdx

@@ -50,24 +50,38 @@ This method calls the `authenticate` method of the provider specified in the fir
 
 ## Auth Flow 1: Basic Authentication
 
-The basic authentication flow requires first using the `register` method, then the `authenticate` method.
-
-If the `authenticate` method returns the following object:
+The basic authentication flow requires first using the `register` method, then the `authenticate` method:
 
 ```ts
-data = {
-	success: true,
-	authIdentity: {
+const { success, authIdentity } = await authModuleService.register(
+  "emailpass",
+  // passed to auth provider
+  {
     // ...
-  },
+  }
+)
+
+// later (can be another route for log-in)
+const { success, authIdentity, location } = await authModuleService.authenticate(
+  "emailpass",
+  // passed to auth provider
+  {
+    // ...
+  }
+)
+
+if (success && !location) {
+  // user is authenticated
 }
 ```
 
-Then, the user is authenticated successfully, and their authentication details are available within the `authIdentity` object.
+If `success` is true and `location` isn't set, the user is authenticated successfully, and their authentication details are available within the `authIdentity` object.
+
+The next section explains the flow if `location` is set.
 
 <Note>
 
-Check out the [AuthIdentity](/references/auth/models/AuthIdentity) reference for the expected properties in `authIdentity`.
+Check out the [AuthIdentity](/references/auth/models/AuthIdentity) reference for the received properties in `authIdentity`.
 
 </Note>
 
@@ -77,46 +91,61 @@ Check out the [AuthIdentity](/references/auth/models/AuthIdentity) reference for
 
 ## Auth Flow 2: Third-Party Service Authentication
 
-The third-party service authentication method requires using the `authenticate` method first.
-
-If the `authenticate` method returns the following object:
+The third-party service authentication method requires using the `authenticate` method first:
 
 ```ts
-data = {
-  success: true,
-  location: "https://....",
+const { success, authIdentity, location } = await authModuleService.authenticate(
+  "emailpass",
+  // passed to auth provider
+  {
+    // ...
+  }
+)
+
+if (location) {
+  // return the location for the front-end to redirect to
 }
+
+if (!success) {
+  // authentication failed
+}
+
+// authentication successful
 ```
 
-It means the authentication process requires the user to perform an action with a third-party service. For example, when using the `google` provider, the user goes to the URL specified in the `location`'s value to log in with their Google account. 
+If the `authenticate` method returns a `location` property, the authentication process requires the user to perform an action with a third-party service. So, you return the `location` to the front-end or client to redirect to that URL.
+
+For example, when using the `google` provider, the `location` is the URL that the user is navigated to login.
 
 ![Diagram showcasing the first part of the third-party authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711374847/Medusa%20Resources/third-party-auth-1_enyedy.jpg)
 
 ### validateCallback
 
 Providers handling this authentication flow must implement the `validateCallback` method. It implements the logic to validate the authentication with the third-party service.
 
-So, once the user performs the required action, the third-party service must redirect to an API route that uses the [validateCallback method of the Auth Module's main service](/references/auth/validateCallback). The method calls the specified provider’s `validateCallback` method passing it the authentication details it received in the second parameter:
-
-```ts
-const data = await authModuleService.validateCallback(
-    "google",
-    // passed to auth provider
-    {
-      // ...
-    }
-  )
-```
+So, once the user performs the required action with the third-party service (for example, log-in with Google), the frontend must redirect to an API route that uses the [validateCallback method of the Auth Module's main service](/references/auth/validateCallback).
 
-If the authentication is successful, the `validateCallback` method returns the same data as the basic authentication:
+The method calls the specified provider’s `validateCallback` method passing it the authentication details it received in the second parameter:
 
 ```ts
-data = {
-	success: true,
-	authIdentity: {
-    // ...
-  },
+const { success, authIdentity } = await authModuleService.validateCallback(
+  "google",
+  // passed to auth provider
+  {
+    // request data, such as
+    url,
+    headers,
+    query,
+    body,
+    protocol,
+  }
+)
+
+if (success) {
+  // authentication succeeded
 }
 ```
 
+If the returned `success` property is `true`, the authentication with the third-party provider was successful.
+
 ![Diagram showcasing the second part of the third-party authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711375123/Medusa%20Resources/third-party-auth-2_kmjxju.jpg)

www/apps/resources/app/commerce-modules/auth/auth-identity-and-actor-types/page.mdx

@@ -8,17 +8,17 @@ In this document, you’ll learn about concepts related to identity and actors i
 
 ## What is an Auth Identity?
 
-The [AuthIdentity data model](/references/auth/model/AuthIdentity) represents a previously-authenticated user.
+The [AuthIdentity data model](/references/auth/model/AuthIdentity) represents a registered user.
 
-When a user is authenticated, a record of `AuthIdentity` is created. This record is used to validate the user’s authentication in future requests.
+When a user is registered, a record of `AuthIdentity` is created. This record is used to validate the user’s authentication in future requests.
 
 ---
 
 ## Actor Types
 
 An actor type is a type of user that can be authenticated. This user is a record of a data model defined by a module.
 
-For example, the `customer` belongs to the Customer Module’s `Customer` data model. Similarly, the `user` belongs to the User Module’s `User` data model.
+For example, the `customer` actor type belongs to the Customer Module’s `Customer` data model. Similarly, the `user` actor type belongs to the User Module’s `User` data model.
 
 ### Protect Routes by Actor Type
 
@@ -48,7 +48,7 @@ export default defineMiddlewares({
 })
 ```
 
-By specifying `user` as the first parameter of `authenticate`, only authenticated users of actor type `user` can access API routes starting with `/custom/admin`.
+By specifying `user` as the first parameter of `authenticate`, only authenticated users of actor type `user` (admin users) can access API routes starting with `/custom/admin`.
 
 ---
 

www/apps/resources/app/commerce-modules/auth/auth-providers/emailpass/page.mdx

@@ -8,8 +8,6 @@ export const metadata = {
 
 In this document, you’ll learn about the Emailpass auth module provider and how to install and use it in the Auth Module.
 
-## Features
-
 Using the Emailpass auth module provider, you allow users to register and login with an email and password.
 
 ---
@@ -31,6 +29,7 @@ const modules = {
     resolve: "@medusajs/auth",
     options: {
       providers: [
+        // other providers...
         {
           resolve: "@medusajs/auth-emailpass",
           id: "emailpass",