docs: final review comments

unatasha8 · unatasha8 · commit b80511d9ecd9 · 2025-11-07T22:54:19.000-08:00
diff --git a/docs/migrate-to-ory/auth0.mdx b/docs/migrate-to-ory/auth0.mdx
@@ -145,6 +145,4 @@ Follow these steps to import Auth0 users to Ory:
 
    ```shell
    ory list identities --project <project-id> --workspace <workspace-id>
-   ```
-# FAQ
-TODO: Living section for specific questions/answers that Sales get asked but which don't neatly fit within the Auth0 migration process.
+   ```
diff --git a/docs/migrate-to-ory/migrate/create-project.mdx b/docs/migrate-to-ory/migrate/create-project.mdx
@@ -5,12 +5,17 @@ sidebar_label: Create an Ory Network project
 sidebar_position: 3
 ---
 
-Now that you have chosen your migration strategy, you can begin the actual migration process by setting up your Ory Network
-projects in a development, staging, and production environment. 
+Now that you have chosen your migration strategy, you can begin the actual migration process. Perform the migration in a 
+development or staging environment before migrating to your production environment. This allows you to test and refine the 
+process without affecting your live data or users.
 
-You can create a new Ory Network project using the Ory CLI. The command `ory create project` allows you to specify the environment
-of the project, the output format, the name of the project, and the workspace to use. More details about creating a project can be
-found [here](../../cli/ory-create-project).
+1. Get an [Ory Network account](https://console.ory.sh/login?flow=c59cbae0-ea41-44e4-b46a-f9e1857be3a2).
+1. Install Ory CLI and [set up your local environment](https://www.ory.com/docs/getting-started/local-development) to start 
+developing with Ory.
+1. Create an Ory project and get your Ory project ID.
+1. [Set up the necessary dependencies and configurations](https://www.ory.com/docs/identities/get-started/setup) to integrate 
+Ory's features into your application.
+1. Review a [quick start](https://www.ory.com/docs/welcome) for your framework.
 
-Before migrating to your production environment, perform the migration in a development or staging environment. This allows you to
-test and refine the process without affecting your live data or users.
+You can use the Ory CLI to specify the environment of the project, the output format, the name of the project, and the workspace to use. 
+See the [Ory CLI Reference](../../cli/ory-create-project) for the `ory create project` command and additional options.
diff --git a/docs/migrate-to-ory/migrate/design-id-schema.mdx b/docs/migrate-to-ory/migrate/design-id-schema.mdx
@@ -9,8 +9,8 @@ To align identities from your current system with Ory, you can customize the ide
 This ability to customize the identity schema means you can enhance and improve your old identity schema during the migration process. 
 
 The identity schema, which implements the JSON Schema standard, defines the types of data the system can store for users—such as 
-names, email addresses, phone numbers, or birthdays—and controls business logic by specifying which fields serve as login 
-identifiers and which are used for verification or recovery. 
+names, email addresses, phone numbers, or birthdays. It also controls business logic by specifying which fields serve as login 
+identifiers and which are used for verification or recovery.
 
 Identities have two main data types: traits (attributes that users can modify themselves, such as username or email address) 
 and metadata (attributes defined by system admins that can only be updated through admin APIs. Metadata is useful for storing 
diff --git a/docs/migrate-to-ory/migrate/go-live.mdx b/docs/migrate-to-ory/migrate/go-live.mdx
@@ -17,8 +17,10 @@ live with Ory in your production environment.
    periods. Communicate the planned migration to your users in advance, including any expected downtime or changes they should be
    aware of.
 1. Monitor the transition: As you switch over to Ory, closely monitor the system for any issues, such as failed authentications,
-   performance bottlenecks, or user complaints. Use live events to monitor the system under
+   performance bottlenecks, or user complaints. To monitor the system, view live events at 
    <ConsoleLink route="project.activity.events" />.
-1. Optimize and refine: After the go-live, continue to monitor the system and gather user feedback.
+1. Optimize and refine: After the go-live, continue to monitor the system, gather user feedback, and make adjustments as needed to 
+improve performance and user experience.
 
-Once your Ory integration is stable and users are successfully authenticating with the new system, your migration is complete.
+Once your Ory integration is stable and users are successfully authenticating with the new system, your migration is complete.
+Continue to leverage Ory's features to enhance your authentication and identity management over time.
diff --git a/docs/migrate-to-ory/migrate/index.mdx b/docs/migrate-to-ory/migrate/index.mdx
@@ -7,26 +7,29 @@ sidebar_position: 1
 # Understand your current IAM system
 
 Before you can migrate smoothly, you need a complete picture of how your identity management system works today. This step ensures 
-nothing gets missed — from everyday login flows to rare edge cases — and sets the foundation for mapping existing functionality to 
+nothing gets missed—from everyday login flows to rare edge cases—and sets the foundation for mapping existing functionality to 
 Ory Network's equivalent capabilities.
 
 :::info Why it matters
 
-Not understanding your existing system’s behavior is the #1 cause of unexpected regressions during cutover. With Ory Network, you 
-gain full control, and with it, the ability to shape your system’s flows exactly to your needs.
-
+Mapping your full login lifecycle is the best way to de-risk migration. Your current IAM system may be abstracting away key 
+functionality without you realizing it. With Ory Network, you gain full control to shape and optimize every flow to your needs.
 :::
 
+## Identify your IAM scenario
 Below are example IAM scenarios supported by Ory Network. Use them to identify which scenario best fits your specific IAM needs and 
 understand the unique requirements of each approach. Each scenario differs in complexity and implementation needs. Use these IAM 
 scenarios to map the identity flows for your application.
 
-## Identify your IAM scenario
-- [CIAM](#ciam-customer-identity-and-access-management)
-- [B2B](#b2b-business-to-business)
-- [Workforce](#workforce-business-to-enterprise)
-- [Agentic AI](#agentic-ai)
-
+<Tabs
+  defaultValue="CIAM"
+  values={[
+    {label: 'CIAM', value: 'CIAM'},
+    {label: 'B2B', value: 'B2B'},
+    {label: 'Workforce', value: 'Workforce'},
+    {label: 'Agentic AI', value: 'Agentic AI'},
+  ]}>
+<TabItem value="CIAM">
 
 ### CIAM (Customer Identity and Access Management)
 
@@ -38,6 +41,9 @@ Your company sells products or services directly to individual consumers.
 - Privacy compliance (GDPR, CCPA)
 - High-scale performance for millions of users
 
+</TabItem>
+<TabItem value="B2B">
+
 ### B2B (Business-to-Business)
 
 Your company sells products or services directly to other businesses rather than individual consumers. Your customers are organizations 
@@ -51,6 +57,8 @@ that use these products or services to run their own operations.
 - Role-based permissions and API controls
 - Privacy compliance (GDPR, CCPA)
 - High-scale performance for millions of users
+</TabItem>
+<TabItem value="Workforce">
 
 ### Workforce (Business-to-Enterprise)
 
@@ -67,6 +75,8 @@ existing enterprise identity providers and other 3rd party systems, and streamli
 - Zero-trust security, MFA, and SSO for enterprise applications
 - Privacy compliance (GDPR, CCPA)
 - High-scale performance for millions of users
+</TabItem>
+<TabItem value="Agentic AI">
 
 ### Agentic AI
 
@@ -76,28 +86,30 @@ clients (AI applications) that discover and use those resources.
 #### Key IAM requirements
 - Standardized protocol that works across many tools and data sources
 - Built-in authentication and access control
+</TabItem>
+</Tabs>
 
 ## Map all identity flows in your application
 
-Build a complete picture of every identity-related process in your system. Use your IAM scenario’s Key IAM requirements to identify 
+Document every identity-related (authentication and authorization) process in your system. Use your IAM scenario’s Key IAM requirements to identify 
 these flows. This ensures you don’t miss critical flows during migration.
 
 1. Identify all entry points where an identity-related process occurs (e.g., web app login, mobile app sign-in, API tokens, social or enterprise sign-ins).
 1. Create a comprehensive inventory of flows, for example:
-    - Registration/sign-up
-    - Sign-in/sign-out
+    - Registration
+    - Sign-in and sign-out
     - Multi-Factor Authentication (MFA)
     - Password reset and account recovery
     - Account linking (social, enterprise logins)
     - User profile management
     - Token refresh and session handling
     - Recovery flows, consent screens, or partner-specific integrations
 1. Create flow diagrams (sequence diagrams or flow charts) to surface dependencies and hidden complexity.
-1. Note where identity-related (authentication and authorization) processes interact with other systems (databases, CRMs, partner apps, or external APIs).
+1. Note where identity-related processes interact with other systems (databases, CRMs, partner apps, or external APIs).
 
-At the end of this process you should have a living document with diagrams that capture:
+At the end of this process you should have a living document (one that you'll update as you discover more) with diagrams that capture:
 
-- All identity-related (authentication and authorization) flows
+- All identity-related flows
 - Your system's existing functionality
 - Any existing dependencies on external systems
 - Edge cases requiring special handling
diff --git a/docs/migrate-to-ory/migrate/integrate-backend.mdx b/docs/migrate-to-ory/migrate/integrate-backend.mdx
@@ -6,11 +6,11 @@ sidebar_position: 1
 ---
 
 When the frontend makes an API call to your backend, it will include the necessary cookies. Your backend must then forward these
-cookies when calling the Ory API to validate the session. For example in a Go backend, you could use a
+cookies when calling the Ory API to validate the session. For example, in a Go backend, you could use a
 [middleware](../../getting-started/integrate-auth/go#validate-and-login) to intercept API requests and validate the session by
-calling Ory’s toSession() method. Ensure that the cookies received from the front end are forwarded in this call. Since backend
-calls to Ory’s API won’t automatically include cookies, you must manually attach the relevant cookies to these requests. This is
-important for the backend to be able to check the session.
+calling Ory’s `toSession()` method. Ensure that the cookies received from the frontend are forwarded in this call. Since backend
+calls to Ory’s API won’t automatically include cookies, you must manually attach the relevant cookies to these requests. This 
+allows the backend to validate the session.
 
 When using Ory to manage identities, it is best practice to store business logic in your application database and keep only
 authentication-relevant data in Ory. Here’s a general approach:
@@ -21,8 +21,9 @@ authentication-relevant data in Ory. Here’s a general approach:
    link Ory-managed identities with your business logic.
 1. Establish a connection between the Ory identity and the user record in your database by storing the `user.id` in
    `identity.metadata_public.id`. This ensures that subsequent API calls can easily map the Ory identity to the correct internal
-   user. More about metadata in the [Identity metadata & traits ](../../kratos/manage-identities/managing-users-identities-metadata)
-   documentation.
-1. Now when the frontend makes API calls containing the Ory cookie or token, the backend should verify the session using the
-   whoami API endpoint. This endpoint returns the session details, including the identity, allowing the backend to authenticate
-   the request and link it to the internal user record.
+   user. See [Identity metadata & traits ](../../kratos/manage-identities/managing-users-identities-metadata) documentation for details.
+1. When the frontend makes API calls containing the Ory cookie or token, the backend should verify the session using the
+   [`whoami`](https://www.ory.com/docs/kratos/reference/api#tag/frontend/operation/toSession) API endpoint. This endpoint returns the session details, including the identity, allowing the backend to authenticate
+   the request and link it to the internal user record.
+
+   
diff --git a/docs/migrate-to-ory/migrate/integrate-frontend.mdx b/docs/migrate-to-ory/migrate/integrate-frontend.mdx
@@ -9,23 +9,31 @@ To make authenticated API calls using Ory, start by properly configuring your do
 is set to the root domain (e.g., example.org) when you add a custom domain. This ensures that cookies can be shared across all
 subdomains.
 
-- Example subdomain structure:
-  - Run Ory at auth.example.org.
-  - Host your backend API at api.example.org.
-  - Serve your frontend UI at www.example.org or another designated subdomain.
+Example subdomain structure:
+- Run Ory at auth.example.org.
+- Host your backend API at api.example.org.
+- Serve your frontend UI at www.example.org or another designated subdomain.
 
-This setup allows both your front end and back end to access the authentication session cookies managed by Ory.
+This setup allows both your frontend and backend applications to access the authentication session cookies managed by Ory.
 
-To begin integrating Ory into your frontend, it's helpful to start with the
+To begin integrating Ory into your frontend, start with the
 ["protect a page with login" guides](../../getting-started/overview) that cover the basics of developing with Ory for various
 programming languages and frameworks, including SDK usage and essential setup steps.
 
+## Account Experience
+
 Ory Network has two types of user interfaces. We recommend starting with the built-in
 [Account Experience](../../account-experience/index.mdx), which offers a standard user interface, covering all self-service flows
-with the option to style branding to get you up and running. If you prefer a custom user interface that matches your current
-design 1:1, Ory allows you to create and style a custom UI that integrates seamlessly with your existing setup. You can do this
-using the API directly, the SDK for your language, or - if you are working in the React ecosystem - Ory Elements. Ory Elements is
-a component library designed to make building login, registration, and account pages for Ory easy. It is modular and customizable,
-allowing you to use only the components you need while tailoring them to fit your implementation's design. The UI created with Ory
-Elements changes dynamically to adapt to your Ory Network configuration. More details about customizing the user interface with
-Ory Elements can be found [here](../../elements/index.mdx).
+with the option to style branding to get you up and running. 
+
+## Custom user interface
+
+If you prefer a custom user interface that matches your current design exactly, Ory allows you to create and style a custom UI that 
+integrates seamlessly with your existing setup. You can do this using the API directly, the SDK for your language, or, if you are working 
+in the React ecosystem, Ory Elements. 
+
+### Ory Elements
+
+[Ory Elements](../../elements/index.mdx) is a component library designed to make building login, registration, and account 
+pages for Ory easy. It is modular and customizable, allowing you to use only the components you need while tailoring them to fit your 
+implementation's design. The UI created with Ory Elements changes dynamically to adapt to your Ory Network configuration.
diff --git a/docs/migrate-to-ory/migrate/map-to-orycap.mdx b/docs/migrate-to-ory/migrate/map-to-orycap.mdx
@@ -6,12 +6,14 @@ sidebar_position: 1
 ---
 
 Using your list of identity-related flows, create a side-by-side table to map existing functionality to Ory Network’s equivalent 
-capabilities. While the majority of the time you'll find your existing functionality neatly maps to Ory's capabilities, now is the best time to
-identify when it does not. Some examples:
+capabilities. While most of the time you'll find your existing functionality neatly maps to Ory's capabilities, this is 
+the best time to identify when it does not. Some examples:
 
-- Not all vendors strickly comply with standards, whereas Ory does, so you might discover you need to
-change how you implement functionality to be compliant. 
-- You might have a unique use case to solve that requires additional help from our support.
+
+
+- Not all vendors strictly comply with standards, whereas Ory does, so you might need to change how you implement functionality 
+to be compliant with standards
+- You might have a unique use case that requires additional help from our support team
 
 Table 1: An example of mapping functionality
 
diff --git a/docs/migrate-to-ory/migrate/migrate-identities.mdx b/docs/migrate-to-ory/migrate/migrate-identities.mdx
diff --git a/docs/migrate-to-ory/migrate/migrate-strategies.mdx b/docs/migrate-to-ory/migrate/migrate-strategies.mdx
diff --git a/docs/migrate-to-ory/migrate/test-validate.mdx b/docs/migrate-to-ory/migrate/test-validate.mdx
diff --git a/src/sidebar.ts b/src/sidebar.ts
