update advanced guides with warnings on when and how to use (#1549)

docs/advanced-usage/clerk-idp.mdx

@@ -4,11 +4,19 @@ description: Learn how to use Clerk to facilitate Single Sign-On (SSO) with othe
 ---
 
 > [!WARNING]
-> This feature will not return a Clerk JWT and does not provide authentication. Please see the [FAQ](#how-can-the-access-tokens-obtained-from-the-token-url-be-used) below for more information.
+> **This feature is not designed for handling authentication directly in your application.** To handle authentication _in your_ application, you can [configure one of the many OAuth providers that Clerk offers](/docs/authentication/social-connections/oauth#configuration), such as Google.
 
-Clerk can be configured as an identity provider to facilitate Single Sign-On (SSO) with other clients that support the OAuth 2.0 protocol. With this feature, your users can sign in with your Clerk application on other websites to authorize sharing of their user info.
+Clerk can be configured as an identity provider to facilitate Single Sign-On (SSO) with other clients that support the OAuth 2.0 protocol. This feature allows users to sign in to other applications using their Clerk credentials, enabling user information sharing between your Clerk application and external websites.
 
-![Clerk IDP Flow](/docs/images/advance/clerk-idp-flow.svg)
+## When should you use Clerk as an OAuth provider?
+
+You can use Clerk as an OAuth provider if you want your users to sign in to a third party site or a tool using their credentials from your application. **This is not the same as supporting an OAuth provider, such as Google, in your application. If you want your users to be able to sign in to your application with an OAuth provider, see [the dedicated guide](/docs/authentication/social-connections/oauth#configuration).**
+
+## How it works
+
+The following diagram shows the flow for using Clerk as an OAuth provider.
+
+![Diagram of the Clerk as an IdP flow](/docs/images/advance/clerk-idp-flow.svg)
 
 <Steps>
   ### Retrieve callback URL from the client application

docs/advanced-usage/satellite-domains.mdx

@@ -3,8 +3,10 @@ title: Authentication across different domains
 description: Learn how to share sessions across different domains by adding satellite domains to your application.
 ---
 
-> [!IMPORTANT]
-> This guide addresses authentication across different domains with shared sessions, for example `example-site.com` and `example-site-admin.com`. Authentication across subdomains with shared sessions works by default with Clerk.
+> [!WARNING]
+> This guide addresses authentication across different domains with shared sessions. For example, `example-site.com` and `example-site-admin.com`.
+>
+> [Authentication across subdomains](/docs/deployments/overview#authentication-across-subdomains) with shared sessions works by default with Clerk.
 
 Clerk supports sharing sessions across different domains by adding one or many satellite domains to an application.
 

docs/advanced-usage/using-proxies.mdx

@@ -3,6 +3,9 @@ title: Proxying the Clerk Frontend API
 description: Learn how to proxy the Clerk Frontend API through your domain.
 ---
 
+> [!WARNING]
+> This guide is for users who need to proxy Clerk's Frontend API for deployment. If your application already uses a CNAME subdomain that is required for deploying with Clerk, then you must proxy Clerk's API using a different subdomain. Refer to [the Clerk deployment guide](/docs/deployments/overview#dns-records) on how to configure DNS records for deployment.
+
 Clerk supports two configuration methods for connecting to the Clerk Frontend API: CNAME and Proxy.
 
 The recommended way to connect to the Clerk Frontend API is to [set up CNAME records and use DNS](/docs/deployments/overview). However, if you're unable to use this approach, or would like more control over your integration with Clerk, you can use a proxy.

docs/deployments/overview.mdx

@@ -52,6 +52,11 @@ To see what DNS records you need to add:
 
 When you set a root domain for your production deployment, Clerk's authentication will work across all subdomains. User sessions will also be shared across the subdomains.
 
+**Examples**
+
+- `example-site.com` and `dashboard.example-site.com`
+- `dashboard.example-site.com` and `accounts.example-site.com`
+
 To share sessions and authentication across two different domains with the same Clerk application, see the [Authentication across different domains guide](/docs/advanced-usage/satellite-domains).
 
 ## Deploy certificates

docs/organizations/metadata.mdx

@@ -3,6 +3,9 @@ title: Organization metadata
 description: Organization objects hold a set of metadata that can be used internally to store arbitrary information.
 ---
 
+> [!CAUTION]
+> This guide is for users who want to build a _custom_ user interface using the Clerk API. To create organizations using a _prebuilt_ UI, you should use Clerk's [prebuilt components](/docs/components/overview).
+
 Organization metadata allows you to store information about an organization that is not part of the standard fields, such as custom attributes that are specific to your application.
 
 There are two types of metadata: **public** and **private**.