docs: expand docs for SMS recovery (#2261)

* add section in account page

* expand recovery docs

* mention limit of 10

* links

* expand recovery docs

* expand recovery docs

* make format

* Update docs/identities/get-started/account-recovery.mdx

Co-authored-by: Vincent <[email protected]>

* Update docs/identities/get-started/account-recovery.mdx

Co-authored-by: Vincent <[email protected]>

* Update docs/identities/get-started/account-recovery.mdx

Co-authored-by: Vincent <[email protected]>

* Update docs/identities/get-started/account-recovery.mdx

Co-authored-by: Vincent <[email protected]>

* make format

* Update docs/identities/get-started/account-recovery.mdx

Co-authored-by: Vincent <[email protected]>

* Update docs/identities/get-started/account-recovery.mdx

Co-authored-by: Vincent <[email protected]>

* Update docs/identities/get-started/account-recovery.mdx

Co-authored-by: Vincent <[email protected]>

* Update docs/kratos/self-service/flows/account-recovery-password-reset.mdx

Co-authored-by: Vincent <[email protected]>

* Update docs/kratos/self-service/flows/account-recovery-password-reset.mdx

Co-authored-by: Vincent <[email protected]>

* Update docs/kratos/self-service/flows/account-recovery-password-reset.mdx

Co-authored-by: Vincent <[email protected]>

* Update docs/kratos/self-service/flows/account-recovery-password-reset.mdx

Co-authored-by: Vincent <[email protected]>

* Update docs/kratos/self-service/flows/account-recovery-password-reset.mdx

Co-authored-by: Vincent <[email protected]>

* merge Admin/Dev sections & mention ignored fields

* format

* fix ignored fields

* make format

* fix

* s/elements/Account Experience/

* fix link & add API link

* Update docs/identities/get-started/account-recovery.mdx

Co-authored-by: Vincent <[email protected]>

* Update docs/kratos/self-service/flows/account-recovery-password-reset.mdx

Co-authored-by: Vincent <[email protected]>

* s/a SMS/an SMS/

* address review comments

* address review comments

* address review comments

* address review comments

* address review comments

* revamp section about api changes

* wording

* make format

---------

Co-authored-by: Vincent <[email protected]>

Author: gaultier

docs/identities/get-started/account-recovery.mdx

@@ -42,16 +42,72 @@ configure account recovery in your Ory project.
 </BrowserWindow>
 ```
 
-### Enable SMS account recovery
+### Enable users to choose email or SMS recovery method
 
-Enable the feature flag `choose_recovery_address` to be able to send a recovery code via SMS.
+This feature is enabled via a project-level feature flag, which is `on` by default for new projects in Ory Network.
+
+This feature is only available for the one-time password recovery option, and not when using magic links for recovery.
+
+A [SMS HTTP gateway](../../kratos/emails-sms/10_sending-sms.mdx) must be configured to deliver SMS messages.
+
+#### As a user
+
+For users that use only email as their identifier (a phone number was not provided), the recovery process remains the same.
+
+To receive a recovery code via SMS, the user's phone number must be registered as a recovery address.
+
+If the user has multiple recovery addresses registered, they will be prompted to choose one from a masked list during the recovery
+process.
+
+To confirm ownership, the user may be asked to enter the complete address after selecting it. This verification step is skipped if
+they already entered that same address to begin the recovery process.
+
+#### As an administrator
+
+Enable the `choose_recovery_address` feature flag to send a SMS containing a recovery code.
+
+It is safe to toggle this feature flag. Changes only take effect when a new recovery flow is initiated; existing flows are
+unaffected.
+
+##### When using EOL/Open-source
+
+Edit the configuration of Kratos (Ory Identities) to set the `choose_recovery_address` feature flag to `true`:
+
+```diff
+feature_flags:
+    use_continue_with_transitions: true
++   choose_recovery_address: true
+```
+
+##### When using Ory Network
 
 1. Log in to your [Ory Console](https://console.ory.sh/)
 2. Select your workspace and project
 3. Navigate to <ConsoleLink route="project.settings.advanced" />
 4. Toggle "Receive a recovery code via SMS" to 'on'
 5. Click **Save**
 
+##### As a developer
+
+When integrating with the API directly, your applications must send and receive these fields. Refer to the
+[API documentation](../../reference/api#tag/frontend/operation/updateRecoveryFlow) for more details.
+
+When using the built-in Account Experience UI, there is nothing special to do. Otherwise, you need to do some changes.
+
+New fields have been added to the payload when getting and updating the recovery flow that are exclusively used when this feature
+flag is enabled:
+
+- `recovery_address`
+- `recovery_select_address`
+- `recovery_confirm_address`
+- `screen`
+
+And these fields will have no effect anymore (they can be present in the payload, but will be ignored):
+
+- `email`
+
+A maximum of 10 recovery addresses are shown to a user during the recovery flow.
+
 ### Recovery strategy
 
 You can choose between the following recovery strategies:
@@ -188,5 +244,5 @@ If the address is malformed, or well-formed but not registered as a recovery add
   > If this was you, check if you signed up using a different address.
   >
   > If this was not you, please ignore this email.
-- If the address is a phone number (meaning a SMS would be sent), or if the configuration value
+- If the address is a phone number (meaning an SMS would be sent), or if the configuration value
   `selfservice.flows.recovery.notify_unknown_recipients` is disabled, nothing will be sent.

docs/kratos/self-service/flows/account-recovery-password-reset.mdx

@@ -160,12 +160,24 @@ In the Ory Console go to <ConsoleLink route="project.mfa" />
 ### Account recovery address
 
 To start account recovery, Ory Identities must know which address to send the recovery message to. Usually this is the email
-address the user provides when registering their account. Other fields inside the `traits` section are supported as well.
+address the user provides when registering their account. Other fields inside the `traits` section are supported as well such as
+phone number to receive the code via an SMS.
+
+If a user has multiple recovery addresses and the `choose_recovery_address` feature flag is
+[enabled](../../../identities/get-started/account-recovery.mdx#enable-the-feature-flag-choose_recovery_address-unlocks-sending-a-recovery-code-via-sms),
+the process is as follows:
+
+1. The user enters any of their registered addresses to begin the recovery flow.
+1. A masked list of their recovery addresses is displayed. Up to 10 addresses are shown.
+1. After selecting an address, the user must enter it in full. This step verifies ownership and helps prevent information leaks.
+1. The recovery message is sent to the confirmed address via email or SMS.
+
+A [SMS HTTP gateway](../../emails-sms/10_sending-sms.mdx) must be configured to deliver SMS messages.
 
 :::info
 
-If the email address used for recovery is the same as the email used for verification and the account isn't activated when the
-recovery flow is started, completing the recovery flow also verifies the user's email address.
+If the address used for recovery is the same as the address used for verification and the account isn't activated when the
+recovery flow is started, completing the recovery flow also verifies the user's address.
 
 Read [this document](./verify-email-account-activation.mdx) to learn about the account verification flow.
 
@@ -204,14 +216,79 @@ To specify a trait of the identity to be used for recovery, use the following id
  }
 ```
 
+Example to allow recovery via an email or an SMS:
+
+```json
+{
+  "$id": "https://example.com/registration.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Person",
+  "type": "object",
+  "properties": {
+    "traits": {
+      "type": "object",
+      "properties": {
+        "email": {
+          "title": "Email",
+          "type": "string",
+          "format": "email",
+          "ory.sh/kratos": {
+            "credentials": {
+              "password": {
+                "identifier": true
+              },
+              "code": {
+                "identifier": true,
+                "via": "email"
+              }
+            },
+            "recovery": {
+              "via": "email"
+            }
+          }
+        },
+        "telephoneNumber": {
+          "type": "string",
+          "format": "tel",
+          "title": "Telephone Number",
+          "minLength": 3,
+          "ory.sh/kratos": {
+            "credentials": {
+              "password": {
+                "identifier": true
+              },
+              "code": {
+                "identifier": true,
+                "via": "sms"
+              }
+            },
+            "verification": {
+              "via": "sms"
+            },
+            "recovery": {
+              "via": "sms"
+            }
+          }
+        }
+      },
+      "required": ["email"],
+      "additionalProperties": false
+    }
+  }
+}
+```
+
 ### Attempted recovery notifications
 
 When this option is on and users attempt to initiate recovery for unregistered addresses, the system sends an attempted recovery
 notification to the email address that was used in the attempt. This prevents account enumeration attacks as explained in this
 [blog post by Troy Hunt](https://www.troyhunt.com/website-enumeration-insanity-how-our-personal-data-is-leaked/). By default, this
 feature is disabled in newly created Ory Network projects.
 
-Follow these steps to enable sending attempted recovery notifications:
+For cost reasons, the attempted recovery notification does not apply to SMS. An attempt to recover an account using an incorrect
+phone number will not trigger an SMS message.
+
+Follow these steps to send attempted recovery notification emails:
 
 ```mdx-code-block
 <Tabs groupId="console-or-cli">
@@ -260,12 +337,13 @@ Go to <ConsoleLink route="project.recovery" /> and toggle **Notify unknown recip
 </Tabs>
 ```
 
-### Email templates
+### Templates
 
-Ory Identities comes with default email templates for recovery flows.
+Ory Identities comes with default templates for recovery flows.
 
 You can replace the defaults and customize the messages to match the look and feel of your solution. Read the
-[email templates documentation](../../emails-sms/05_custom-email-templates.mdx) to learn more.
+[email templates documentation](../../emails-sms/05_custom-email-templates.mdx) and
+[SMS templates documentation](../../emails-sms/10_sending-sms.mdx#templates) to learn more.
 
 ## Invalidate other sessions
 
@@ -324,11 +402,11 @@ Learn how to [add and configure hooks for self-service user flows](../../hooks/0
 
 ## Fallback recovery address
 
-In some scenarios, users may want to recover their account using a different email address than the one they used to register, for
-example if they no longer have access to the original email address. To use two (or more) recovery email addresses, you need to
-define a secondary email field, such as `email_secondary` in the traits section of the identity schema. This field will serve as
-the fallback email address for account recovery. Read more about identity schemas
-[here](../../manage-identities/05_identity-schema.mdx).
+A user may need a fallback recovery address if they lose access to the address used for registration.
+
+To enable this, define a secondary field, such as email_secondary, in the traits section of your
+[identity schema](../../manage-identities/05_identity-schema.mdx). This field will serve as the alternative address for account
+recovery.
 
 This is an example of an identity schema with a secondary email address:
 
@@ -400,6 +478,10 @@ In this schema, you define both `email` and `email_secondary` fields as recovery
 messages to both addresses when the recovery flow is initiated. The user should provide the `email_secondary` field during
 registration or update it later in their account settings so it can be used in the recovery process.
 
+This is different from the scenario where a user has multiple recovery addresses of different types, such as one email address and
+one phone number. In that case, the user is prompted to choose which address to use, and a recovery message is sent to only the
+one they select.
+
 ## Native recovery flows
 
 Ory Identities supports recovery flows in native applications. This allows you to build a native application that allows the user