docs: add more clarification to reset password in API reference

www/apps/api-reference/specs/admin/openapi.full.yaml

@@ -43546,10 +43546,12 @@ paths:
       summary: Generate Reset Password Token for Admin User
       x-sidebar-summary: Generate Reset Password Token
       description: |
-        Generate a reset password token for an admin user. This API route emits the `` event, passing it the token as a payload. You can listen to that event and send the user a notification. The notification should have a URL that accepts a `token` query parameter.
+        Generate a reset password token for an admin user. This API route doesn't reset the admin's password or send them the reset instructions in a notification.
 
+        Instead, This API route emits the `auth.password_reset` event, passing it the token as a payload. You can listen to that event in a subscriber as explained in [this guide](https://docs.medusajs.com/resources/commerce-modules/auth/reset-password), then send the user a notification. The notification is sent using a [Notification Module Provider](https://docs.medusajs.com/resources/architectural-modules/notification), and it should have the URL to reset the password in the Medusa Admin dashboard, such as `http://localhost:9000/app/reset-password?token=123`.
 
-         Use the generated token to update the user's password using the Reset Password API route.
+
+         Use the generated token to update the user's password using the [Reset Password API route](https://docs.medusajs.com/api/admin#auth_postactor_typeauth_providerupdate).
       externalDocs:
         url: https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#generate-reset-password-token-route
         description: Learn more about this API route.
@@ -43602,7 +43604,7 @@ paths:
       operationId: PostActor_typeAuth_providerUpdate
       summary: Reset an Admin User's Password
       x-sidebar-summary: Reset Password
-      description: Reset a user's password. Generate the reset password token first using the Get Reset Password Token API route.
+      description: Reset an admin user's password using a reset-password token generated with the [Generate Reset Password Token API route](https://docs.medusajs.com/api/admin#auth_postactor_typeauth_providerresetpassword).
       externalDocs:
         url: https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#reset-password-route
         description: Learn more about this API route.

www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_reset-password.yaml

@@ -3,13 +3,23 @@ post:
   summary: Generate Reset Password Token for Admin User
   x-sidebar-summary: Generate Reset Password Token
   description: >
-    Generate a reset password token for an admin user. This API route emits the
-    `` event, passing it the token as a payload. You can listen to that event
-    and send the user a notification. The notification should have a URL that
-    accepts a `token` query parameter.
+    Generate a reset password token for an admin user. This API route doesn't
+    reset the admin's password or send them the reset instructions in a
+    notification.
 
 
-     Use the generated token to update the user's password using the Reset Password API route.
+    Instead, This API route emits the `auth.password_reset` event, passing it
+    the token as a payload. You can listen to that event in a subscriber as
+    explained in [this
+    guide](https://docs.medusajs.com/resources/commerce-modules/auth/reset-password),
+    then send the user a notification. The notification is sent using a
+    [Notification Module
+    Provider](https://docs.medusajs.com/resources/architectural-modules/notification),
+    and it should have the URL to reset the password in the Medusa Admin
+    dashboard, such as `http://localhost:9000/app/reset-password?token=123`.
+
+
+     Use the generated token to update the user's password using the [Reset Password API route](https://docs.medusajs.com/api/admin#auth_postactor_typeauth_providerupdate).
   externalDocs:
     url: >-
       https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#generate-reset-password-token-route

www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_update.yaml

@@ -3,8 +3,9 @@ post:
   summary: Reset an Admin User's Password
   x-sidebar-summary: Reset Password
   description: >-
-    Reset a user's password. Generate the reset password token first using the
-    Get Reset Password Token API route.
+    Reset an admin user's password using a reset-password token generated with
+    the [Generate Reset Password Token API
+    route](https://docs.medusajs.com/api/admin#auth_postactor_typeauth_providerresetpassword).
   externalDocs:
     url: >-
       https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#reset-password-route

www/apps/api-reference/specs/store/openapi.full.yaml

@@ -331,10 +331,12 @@ paths:
       summary: Generate Reset Password Token for Customer
       x-sidebar-summary: Generate Reset Password Token
       description: |
-        Generate a reset password token for a customer. This API route emits the `auth.password_reset` event, passing it the token as a payload. You can listen to that event and send the user a notification. The notification should have a URL that accepts a `token` query parameter.
+        Generate a reset password token for a customer. This API route doesn't reset the customer password or send them the reset instructions in a notification.
 
+        Instead, This API route emits the `auth.password_reset` event, passing it the token as a payload. You can listen to that event in a subscriber as explained in [this guide](https://docs.medusajs.com/resources/commerce-modules/auth/reset-password), then send the customer a notification. The notification is sent using a [Notification Module Provider](https://docs.medusajs.com/resources/architectural-modules/notification), and it should have a URL that accepts a `token` query parameter, allowing the customer to reset their password from the storefront.
 
-         Use the generated token to update the user's password using the Reset Password API route.
+
+         Use the generated token to update the customer's password using the [Reset Password API route](https://docs.medusajs.com/api/store#auth_postactor_typeauth_providerupdate).
       externalDocs:
         url: https://docs.medusajs.com/v2/resources/storefront-development/customers/reset-password#1-request-reset-password-page
         description: 'Storefront development: How to create the request reset password page.'
@@ -387,7 +389,7 @@ paths:
       operationId: PostActor_typeAuth_providerUpdate
       summary: Reset a Customer's Password
       x-sidebar-summary: Reset Password
-      description: Reset a customer's password. Generate the reset password token first using the Get Reset Password Token API route.
+      description: Reset a customer's password using a reset-password token generated with the [Generate Reset Password Token API route](https://docs.medusajs.com/api/store#auth_postactor_typeauth_providerresetpassword).
       externalDocs:
         url: https://docs.medusajs.com/v2/resources/storefront-development/customers/reset-password#2-reset-password-page
         description: 'Storefront development: How to create the reset password page.'

www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}_reset-password.yaml

@@ -3,13 +3,22 @@ post:
   summary: Generate Reset Password Token for Customer
   x-sidebar-summary: Generate Reset Password Token
   description: >
-    Generate a reset password token for a customer. This API route emits the
-    `auth.password_reset` event, passing it the token as a payload. You can
-    listen to that event and send the user a notification. The notification
-    should have a URL that accepts a `token` query parameter.
+    Generate a reset password token for a customer. This API route doesn't reset
+    the customer password or send them the reset instructions in a notification.
 
 
-     Use the generated token to update the user's password using the Reset Password API route.
+    Instead, This API route emits the `auth.password_reset` event, passing it
+    the token as a payload. You can listen to that event in a subscriber as
+    explained in [this
+    guide](https://docs.medusajs.com/resources/commerce-modules/auth/reset-password),
+    then send the customer a notification. The notification is sent using a
+    [Notification Module
+    Provider](https://docs.medusajs.com/resources/architectural-modules/notification),
+    and it should have a URL that accepts a `token` query parameter, allowing
+    the customer to reset their password from the storefront.
+
+
+     Use the generated token to update the customer's password using the [Reset Password API route](https://docs.medusajs.com/api/store#auth_postactor_typeauth_providerupdate).
   externalDocs:
     url: >-
       https://docs.medusajs.com/v2/resources/storefront-development/customers/reset-password#1-request-reset-password-page

www/apps/api-reference/specs/store/paths/auth_customer_{auth_provider}_update.yaml

@@ -3,8 +3,9 @@ post:
   summary: Reset a Customer's Password
   x-sidebar-summary: Reset Password
   description: >-
-    Reset a customer's password. Generate the reset password token first using
-    the Get Reset Password Token API route.
+    Reset a customer's password using a reset-password token generated with the
+    [Generate Reset Password Token API
+    route](https://docs.medusajs.com/api/store#auth_postactor_typeauth_providerresetpassword).
   externalDocs:
     url: >-
       https://docs.medusajs.com/v2/resources/storefront-development/customers/reset-password#2-reset-password-page

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

@@ -65,7 +65,7 @@ export default async function resetPasswordTokenHandler({
 
   const urlPrefix = actor_type === "customer" ? 
     "https://storefront.com" : 
-    "https://admin.com"
+    "https://admin.com/app"
 
   await notificationModuleService.createNotifications({
     to: email,

www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_reset-password.ts

@@ -4,10 +4,13 @@
  * summary: Generate Reset Password Token for Admin User
  * x-sidebar-summary: Generate Reset Password Token
  * description: >
- *   Generate a reset password token for an admin user. This API route emits the `` event, passing it the token as a payload. You can listen to that event and send the user a notification. The notification should have a URL that accepts a `token` query parameter.
+ *   Generate a reset password token for an admin user. This API route doesn't reset the admin's password or send them the reset instructions in a notification.
  * 
  * 
- *    Use the generated token to update the user's password using the Reset Password API route.
+ *   Instead, This API route emits the `auth.password_reset` event, passing it the token as a payload. You can listen to that event in a subscriber as explained in [this guide](https://docs.medusajs.com/resources/commerce-modules/auth/reset-password), then send the user a notification. The notification is sent using a [Notification Module Provider](https://docs.medusajs.com/resources/architectural-modules/notification), and it should have the URL to reset the password in the Medusa Admin dashboard, such as `http://localhost:9000/app/reset-password?token=123`.
+ * 
+ * 
+ *    Use the generated token to update the user's password using the [Reset Password API route](https://docs.medusajs.com/api/admin#auth_postactor_typeauth_providerupdate).
  * externalDocs:
  *   url: https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#generate-reset-password-token-route
  *   description: Learn more about this API route.

www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_update.ts

@@ -3,7 +3,7 @@
  * operationId: PostActor_typeAuth_providerUpdate
  * summary: Reset an Admin User's Password
  * x-sidebar-summary: Reset Password
- * description: Reset a user's password. Generate the reset password token first using the Get Reset Password Token API route.
+ * description: Reset an admin user's password using a reset-password token generated with the [Generate Reset Password Token API route](https://docs.medusajs.com/api/admin#auth_postactor_typeauth_providerresetpassword).
  * externalDocs:
  *   url: https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#reset-password-route
  *   description: Learn more about this API route.

www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_reset-password.ts

@@ -4,10 +4,13 @@
  * summary: Generate Reset Password Token for Customer
  * x-sidebar-summary: Generate Reset Password Token
  * description: >
- *   Generate a reset password token for a customer. This API route emits the `auth.password_reset` event, passing it the token as a payload. You can listen to that event and send the user a notification. The notification should have a URL that accepts a `token` query parameter.
+ *   Generate a reset password token for a customer. This API route doesn't reset the customer password or send them the reset instructions in a notification.
  * 
  * 
- *    Use the generated token to update the user's password using the Reset Password API route.
+ *   Instead, This API route emits the `auth.password_reset` event, passing it the token as a payload. You can listen to that event in a subscriber as explained in [this guide](https://docs.medusajs.com/resources/commerce-modules/auth/reset-password), then send the customer a notification. The notification is sent using a [Notification Module Provider](https://docs.medusajs.com/resources/architectural-modules/notification), and it should have a URL that accepts a `token` query parameter, allowing the customer to reset their password from the storefront.
+ * 
+ * 
+ *    Use the generated token to update the customer's password using the [Reset Password API route](https://docs.medusajs.com/api/store#auth_postactor_typeauth_providerupdate).
  * externalDocs:
  *   url: https://docs.medusajs.com/v2/resources/storefront-development/customers/reset-password#1-request-reset-password-page
  *   description: "Storefront development: How to create the request reset password page."

www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_update.ts

@@ -3,7 +3,7 @@
  * operationId: PostActor_typeAuth_providerUpdate
  * summary: Reset a Customer's Password
  * x-sidebar-summary: Reset Password
- * description: Reset a customer's password. Generate the reset password token first using the Get Reset Password Token API route.
+ * description: Reset a customer's password using a reset-password token generated with the [Generate Reset Password Token API route](https://docs.medusajs.com/api/store#auth_postactor_typeauth_providerresetpassword).
  * externalDocs:
  *   url: https://docs.medusajs.com/v2/resources/storefront-development/customers/reset-password#2-reset-password-page
  *   description: "Storefront development: How to create the reset password page."