feat: migration guide updates

docs/migrate-to-ory/auth0.mdx

@@ -1,12 +1,10 @@
 ---
 id: auth0
-title: Migrate users from Auth0 to Ory
-sidebar_label: Migrate from Auth0
+title: Migrate user identities from Auth0 to Ory
+sidebar_label: Migrate user identities from Auth0 to Ory
 slug: migrate-from-auth0
 ---
 
-# Migrate from Auth0
-
 This guide shows you how to migrate user accounts from Auth0 to Ory. The instructions in this document assume that your Auth0
 setup includes a database connection and that the users whose accounts you migrate use emails and passwords as their login
 credentials.
@@ -148,3 +146,5 @@ 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.

docs/migrate-to-ory/migrate/create-project.mdx

@@ -0,0 +1,16 @@
+---
+id: create-project
+title: Create an Ory Network project
+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. 
+
+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).
+
+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.

docs/migrate-to-ory/migrate/design-id-schema.mdx

@@ -0,0 +1,37 @@
+---
+id: design-id-schema
+title: Design your identity schema
+sidebar_label: Design your identity schema
+sidebar_position: 3
+---
+
+To align identities from your current system with Ory, you can customize the identity schema to meet your specific requirements. 
+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. 
+
+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 
+information like subscription status, legacy user IDs, or basic roles). Metadata comes in two forms: public (visible to 
+users via session endpoints) and admin (only accessible through admin APIs). 
+
+## Best practices for identity schema design:
+
+### Do:
+
+- Use the identity schema for basic profile information that's used across your system, including usernames, email addresses, 
+phone numbers, first names, and last names
+- Store authentication-related data like login identifiers and verification addresses in traits
+- Use metadata fields for system-managed information like legacy user IDs, subscription status, or basic roles
+
+### Don't:
+
+- Store sensitive internal data or information that should be obfuscated from users in the identity schema, since users can 
+see traits and other data (except credentials) using the `/sessions/whoami` endpoint
+- Store business logic or application-specific data like credit card information, shipping addresses, shopping cart items, or 
+detailed user preferences—keep this in your application database instead
+
+Ory provides preset schemas to help you get started quickly. For detailed guidance on customizing schemas, see the 
+[identity schemas](../../kratos/manage-identities/identity-schema) documentation.

docs/migrate-to-ory/migrate/faq-migrate.mdx

@@ -0,0 +1,8 @@
+---
+id: faq-migrate
+title: Migration FAQ
+sidebar_label: Migration FAQ
+sidebar_position: 1
+---
+
+TODO: Living section for specific questions/answers that Sales get asked but which don't neatly fit within the migration process.

docs/migrate-to-ory/migrate/go-live.mdx

@@ -0,0 +1,24 @@
+---
+id: go-live
+title: Go live
+sidebar_label: Go live
+sidebar_position: 2
+---
+
+After successfully migrating your data and testing the integration in your development or staging environment, it's time to go
+live with Ory in your production environment.
+
+1. Final testing: Before switching over to Ory in production, conduct thorough testing of all user authentication flows, identity
+   management features, and access controls. This includes testing edge cases, error handling, and load testing to ensure the
+   system can handle your user base.
+1. Prepare a rollback plan: In case any issues arise during the go-live process, have a rollback plan in place. This may involve
+   reverting to your previous authentication system or restoring data from backups.
+1. Schedule the go-live: Choose a time for the go-live that minimizes the impact on your users, such as during low-traffic
+   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
+   <ConsoleLink route="project.activity.events" />.
+1. Optimize and refine: After the go-live, continue to monitor the system and gather user feedback.
+
+Once your Ory integration is stable and users are successfully authenticating with the new system, your migration is complete.

docs/migrate-to-ory/migrate/index.mdx

@@ -0,0 +1,111 @@
+---
+id: index
+title: Understand your current IAM system
+sidebar_label: Understand your current IAM system
+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 
+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.
+
+:::
+
+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)
+
+
+### CIAM (Customer Identity and Access Management)
+
+Your company sells products or services directly to individual consumers.
+
+#### Key IAM requirements
+- Self-service registration, login, and profile management for end users
+- Social login, multi-factor passwordless options, and robust account recovery
+- Privacy compliance (GDPR, CCPA)
+- High-scale performance for millions of users
+
+### B2B (Business-to-Business)
+
+Your company sells products or services directly to other businesses rather than individual consumers. Your customers are organizations 
+that use these products or services to run their own operations.
+
+#### Key IAM requirements
+
+- Multi-organization user management
+- SSO with SAML/OIDC providers
+- Self-service partner onboarding
+- Role-based permissions and API controls
+- Privacy compliance (GDPR, CCPA)
+- High-scale performance for millions of users
+
+### Workforce (Business-to-Enterprise)
+
+Your company provides products or services. Your company wants to manage access for a single organization's extended workforce. You want to 
+consolidate employee user accounts and identities across multi-tenant brands, applications and systems. You need to seamlessly connect with 
+existing enterprise identity providers and other 3rd party systems, and streamline user onboarding, offboarding, and permission management. 
+
+#### Key IAM requirements
+- Streamline onboarding/offboarding of employee, contractor, and temporary workers
+- Role-based access aligned with organizational hierarchy
+- HR system integration with flexible identity schemas
+- Integrate with enterprise identity providers and third-party systems
+- Time-bound permissions and role assignments
+- Zero-trust security, MFA, and SSO for enterprise applications
+- Privacy compliance (GDPR, CCPA)
+- High-scale performance for millions of users
+
+### Agentic AI
+
+Your company wants to enable AI applications to securely connect to data sources and tools. For example, servers that host resources and
+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
+
+## 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 
+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
+    - 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).
+
+At the end of this process you should have a living document with diagrams that capture:
+
+- All identity-related (authentication and authorization) flows
+- Your system's existing functionality
+- Any existing dependencies on external systems
+- Edge cases requiring special handling
+
+This will serve as your blueprint for planning, designing, testing, and validating your migration.
+
+```mdx-code-block
+import Help from '@site/docs/_common/need-help.mdx'
+
+<Help/>
+```

docs/migrate-to-ory/migrate/integrate-backend.mdx

@@ -0,0 +1,28 @@
+---
+id: integrate-backend
+title: Integrate your backend
+sidebar_label: Integrate your backend
+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
+[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.
+
+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:
+
+1. Configure [Ory Actions](../../kratos/hooks/configure-hooks) to send webhooks to your server after user registration or other
+   identity-related events. The webhook payload will include the data of the newly created identity.
+1. Upon receiving the webhook, your server can create a corresponding user record in your database. This allows your system to
+   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.

docs/migrate-to-ory/migrate/integrate-frontend.mdx

@@ -0,0 +1,31 @@
+---
+id: integrate-frontend
+title: Integrate your frontend
+sidebar_label: Integrate your frontend
+sidebar_position: 1
+---
+
+To make authenticated API calls using Ory, start by properly configuring your domain and subdomains. By default the cookie domain
+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.
+
+This setup allows both your front end and back end to access the authentication session cookies managed by Ory.
+
+To begin integrating Ory into your frontend, it's helpful to 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.
+
+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).

docs/migrate-to-ory/migrate/map-to-orycap.mdx

@@ -0,0 +1,20 @@
+---
+id: map-to-orycap
+title: Map your existing functionality to Ory Network capabilities
+sidebar_label: Map your existing functionality to Ory Network capabilities
+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:
+
+- 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.
+
+Table 1: An example of mapping functionality
+
+| Existing Functionality | Ory Capabilities |
+|---|---|
+| JSON Web Tokens | [Ory Session cookies/tokens](https://www.ory.sh/docs/identities/session-to-jwt-cors)|

docs/migrate-to-ory/migrate/migrate-identities.mdx

@@ -0,0 +1,37 @@
+---
+id: migrate-identities
+title: Migrate your existing identities
+sidebar_label: Migrate your existing identities
+sidebar_position: 3
+---
+With authentication now set up on your frontend and backend, the next step is to prepare your existing user identities for
+migration. You should have already chosen your identity migration strategy in [Phase 1: Plan and prepare](http://localhost:3002/docs/migrate-to-ory/migrate/migrate-strategies); 
+"bulk" or "graceful" migration. You will now implement your chosen identity migration strategy.
+
+## Bulk import of identities
+
+If you're using a managed identity solution, it’s a good idea to start the export of existing identities early, especially 
+if there's no straightforward way to export the identities and you might need to go through a support process. Identify the 
+hashing algorithm used for credentials—if your passwords aren't hashed, Ory handles hashing automatically during import. 
+If Ory supports your hashing algorithm, use the [create identity API](../../reference/api#tag/identity/operation/createIdentity) 
+to import users. If the hashing algorithm isn't supported or if you can't get the hashed passwords from your current 
+authentication system, you may want to do a "graceful" migration. 
+
+The create identity API supports bulk imports with a maximum of 1000 identities per request—larger imports require multiple 
+requests. The endpoint accepts a JSON array of identities, each of which must have a create property that holds the identity 
+that should be created. See the [Import identities ](../../kratos/manage-identities/25_import-user-accounts-identities.mdx) 
+documentation for complete details.
+
+- For Auth0 migrations, see the dedicated [Migrate user identities from Auth0 to Ory](../migrate-from-auth0) guide. 
+
+## Graceful import of identities
+
+Ory does not support the direct import of active sessions from your existing system. To ensure that users with active sessions
+from the old system can continue accessing your services without needing to reauthenticate immediately, implement a transition
+period during which both the old and new systems operate concurrently. During this period, use the [password migration hook](https://www.ory.com/docs/kratos/manage-identities/import-user-accounts-identities#password-migration-using-a-web-hook) 
+to migrate your existing users. All user authentication flows—including login, registration, password recovery, and settings management—should be 
+managed by Ory. However, your backend must be configured to recognize and accept sessions from both the old system and Ory. 
+As the transition progresses, gradually phase out the old system. Once most or all active sessions from the old system have
+expired or been replaced by new sessions in Ory, you can complete the migration to Ory exclusively. This gradual approach
+minimizes user disruption and provides your development team with the time needed to resolve any potential issues that may arise
+during the migration.