Bring back old content environments dev/prod (#2738)

Author: SarahSoutoul

docs/guides/development/managing-environments.mdx

@@ -11,16 +11,17 @@ A `Development` instance is Clerk's default instance type and has characteristic
 
 Some notable examples of `Development`-only characteristics in a Clerk application are:
 
-- A `Development` banner is shown prominently in the Clerk Dashboard to make clear you're managing or configuring non-production data
-- Email and SMS templates are prefixed with the environment type to prevent against using `Development` instances for production purposes
-- Some social connections use shared credentials by default
-- [The Account Portal](/docs/guides/customizing-clerk/account-portal) will use a Clerk development domain that ends with `accounts.dev` instead of your app's production domain
-- OAuth consent screens will show the development domain that ends with `accounts.dev` instead of your production domain
-- Search engines will not be able to crawl and index your application
-- Development instances have a 100 users cap and user data can not be transferred between instances
+- A `Development` banner is shown prominently in the Clerk Dashboard to make clear you're managing or configuring non-production data.
+- Email and SMS templates are prefixed with the environment type to prevent against using `Development` instances for production purposes.
+- Some social connections use shared credentials by default.
+- [The Account Portal](/docs/guides/customizing-clerk/account-portal) will use a Clerk development domain that ends with `accounts.dev` instead of your app's production domain.
+- OAuth consent screens will show the development domain that ends with `accounts.dev` instead of your production domain.
+- Search engines will not be able to crawl and index your application.
+- Development instances are capped at 100 users, and user data can not be transferred between instances.
+- The architecture of Clerk's sessions management is different in development environments compared to production environments, due to the need to communicate cross-domain between `localhost` and `<slug>.accounts.dev`. The `__clerk_db_jwt` object is _only_ used in development environments. For more specific details on the differences between Clerk's session management architecture in development and production environments, see the [technical breakdown below](#session-architecture-differences).
 
 > [!NOTE]
-> All paid functionality is available in a `Development` instance. However, when you deploy your application to `Production`, you will be asked to upgrade to a `Pro` account. See [our pricing page](/pricing) for full details.
+> All paid functionality is available in a `Development` instance. However, when you deploy your application to `Production`, you will be asked to upgrade to a `Pro` account if you are using paid features. See [our pricing page](/pricing) for full details.
 
 ## Production instance
 
@@ -100,3 +101,12 @@ To use an additional root domain, you must first configure your host to deploy p
 - **Netlify:** use the [Automatic Deploy Subdomain](https://docs.netlify.com/domains-https/custom-domains/automatic-deploy-subdomains/) feature.
 
 You can configure this environment with either your development API keys (recommended) or you can create an additional production instance and use those production API keys.
+
+## Session architecture differences
+
+> [!TIP]
+> In order to understand this section, it's recommended to have a solid understanding of how Clerk's session management architecture works. For more information on this topic, check out the guide on [how Clerk works](/docs/guides/how-clerk-works/overview).
+
+Clerk manages session state differently in production and development environments.
+
+<Include src="_partials/clerkdbjwt-vs-client-cookie" />

docs/guides/how-clerk-works/overview.mdx

@@ -263,7 +263,7 @@ For this reason:
 1. Never deploy a development environment to production.
 1. Do not rely on `__clerk_db_jwt` in your application code, as it will break in production.
 
-For more information on the differences between development and production environments, see the [dedicated guide on Clerk environments](/docs/guides/development/managing-environments).
+For more information on the differences between development and production environments, see the [dedicated guide on Clerk environments](/docs/guides/development/managing-environments#session-architecture-differences).
 
 ### Session token
 
@@ -344,4 +344,4 @@ This server -> browser -> FAPI request includes the client token, so FAPI is abl
   - the anatomy of clerk's sign up and sign in flows
   - subdomain session sharing
   - satellite domains
-*/}
+  */}