Merge branch 'main' into ia/docs-team-proposal

Author: alexisintech

docs/_partials/billing/api-experimental-guide.mdx

@@ -1,3 +1,3 @@
 > [!WARNING]
 >
-> This feature is currently in Beta. The low-level JavaScript APIs exposed via `Clerk.billing` are experimental and may undergo breaking changes. To mitigate potential disruptions, we recommend [pinning](https://docs.renovatebot.com/dependency-pinning/#what-is-dependency-pinning) your SDK and `clerk-js` package versions.
+> Billing is currently in Beta and its APIs are experimental and may undergo breaking changes. To mitigate potential disruptions, we recommend [pinning](/docs/pinning) your SDK and `clerk-js` package versions.

docs/_partials/billing/api-experimental.mdx

@@ -20,7 +20,7 @@ By default, the verification method that is enabled is **email verification code
 
 To use email links, you must configure the following settings in the Clerk Dashboard:
 
-1. On the [**User & authentication**](https://dashboard.clerk.com/last-active?path=user-authentication/user-and-authentication) page of the Clerk Dashboard, under **Email**, enable the **Email verification link** option. By default, **Require the same device and browser** is enabled, which means that email links are required to be verified from the same device and browser on which the sign-up or sign-in was initiated. For this guide, leave this setting enabled.
+1. On the [**User & authentication**](https://dashboard.clerk.com/last-active?path=user-authentication/user-and-authentication) page of the Clerk Dashboard, in the **Email** tab, under the **Sign-in with email** section, enable the **Email verification link** option. By default, **Require the same device and browser** is enabled, which means that email links are required to be verified from the same device and browser on which the sign-up or sign-in was initiated. For this guide, leave this setting enabled.
 1. Disable **Email verification code**.
 1. Save your changes.
 

docs/_partials/billing/billing-experimental.mdx

@@ -138,9 +138,7 @@ This guide demonstrates how to use Clerk's API to build a custom flow for resett
                 <label htmlFor="password">Enter your new password</label>
                 <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} />
 
-                <label htmlFor="code">
-                  Enter the password reset code that was sent to your email
-                </label>
+                <label htmlFor="code">Enter the password reset code that was sent to your email</label>
                 <input type="text" value={code} onChange={(e) => setCode(e.target.value)} />
 
                 <button>Reset</button>

docs/guides/development/custom-flows/account-updates/add-email.mdx

@@ -5,7 +5,7 @@ description: Learn how to use the Clerk API to build a custom flow for adding a
 
 <Include src="_partials/custom-flows-callout" />
 
-<Include src="_partials/billing/api-experimental-guide" />
+<Include src="_partials/billing/billing-experimental" />
 
 This guide will walk you through how to build a custom user interface that allows users to **add a new payment method to their account**. This is a common feature in a user's billing or account settings page, allowing them to pre-emptively add a payment method for future use.
 

docs/guides/development/custom-flows/account-updates/forgot-password.mdx

@@ -5,7 +5,7 @@ description: Learn how to use the Clerk API to build a custom checkout flow that
 
 <Include src="_partials/custom-flows-callout" />
 
-<Include src="_partials/billing/api-experimental-guide" />
+<Include src="_partials/billing/billing-experimental" />
 
 This guide will walk you through how to build a custom user interface for a checkout flow that allows users to checkout **with an existing payment method**. For the custom flow that allows users to **add a new payment method** during checkout, see the [dedicated guide](/docs/guides/development/custom-flows/billing/checkout-new-payment-method).
 

docs/guides/development/custom-flows/billing/add-new-payment-method.mdx

@@ -5,7 +5,7 @@ description: Learn how to use the Clerk API to build a custom checkout flow that
 
 <Include src="_partials/custom-flows-callout" />
 
-<Include src="_partials/billing/api-experimental-guide" />
+<Include src="_partials/billing/billing-experimental" />
 
 This guide will walk you through how to build a custom user interface for a checkout flow that allows users to **add a new payment method during checkout**.
 

docs/guides/development/custom-flows/billing/checkout-existing-payment-method.mdx

@@ -17,4 +17,4 @@ With same device and browser protection on, users will see the following warning
 
 ![Error message displayed if email link is opened in a different device or browser if email link same device/browser protection is enabled](/docs/images/security/email-link_require-same-client.webp)
 
-To configure this security setting, navigate to the [**User & authentication**](https://dashboard.clerk.com/last-active?path=user-authentication/user-and-authentication) page in the Clerk Dashboard.
+To configure this security setting, navigate to the [**User & authentication**](https://dashboard.clerk.com/last-active?path=user-authentication/user-and-authentication) page in the Clerk Dashboard and ensure that under the **Sign-in with email** section, the **Email verification link** option is enabled.

docs/guides/development/custom-flows/billing/checkout-new-payment-method.mdx

@@ -0,0 +1,23 @@
+---
+title: Pin a Clerk SDK
+description: Learn how to pin a Clerk SDK to a specific version.
+---
+
+Dependency pinning allows you to specify exact package versions in your project, ensuring consistent behavior across different environments and preventing unexpected updates from breaking your application.
+
+Typically, package managers use semantic versioning ([SemVer](https://semver.org/)) ranges when installing packages. When you install your Clerk SDK, you'll typically see an entry like `"@clerk/nextjs": "^1.1.0"` in your package.json. The caret (^) symbol means "any version that is compatible with 1.1.0" - this includes patch releases (1.1.1, 1.1.2) and minor releases (1.2.0, 1.3.0) but excludes major releases (2.0.0).
+
+Another range operator is the tilde (\~) symbol for more restrictive versioning. An entry like `"@clerk/nextjs": "~1.1.0"` means "any version from 1.1.0 up to (but not including) 1.2.0" - this only allows patch updates within the same minor version.
+
+When you **pin a dependency**, you specify the exact version **without any range operators**. For example, `"@clerk/nextjs": "1.1.0"` means "use exactly version 1.1.0, no other version." This approach gives you complete control over which version your application uses.
+
+With Clerk, we recommend pinning your Clerk SDK in **both** of these ways:
+
+1. Pin your Clerk SDK in your `package.json` file to a specific version (no range operators).
+   ```json {{ filename: 'package.json', prettier: false }}
+   "@clerk/nextjs": "1.1.0"
+   ```
+1. Set the `clerkJsVersion` property when you initialize the Clerk integration. For most SDKs, this is done in the `<ClerkProvider>` component. For SDKs like Astro or Nuxt, this is done in the configuration file.
+   ```tsx {{ prettier: false }}
+   <ClerkProvider clerkJsVersion="1.1.0">
+   ```