[codex] Clarify pre-live user API docs

docs/tutorials/oidc/user-apis-quickstart.mdx

@@ -23,6 +23,17 @@ sidebar_label: "User APIs Quickstart"
 
 Quran Foundation User APIs use OAuth2 Authorization Code flow with PKCE and OpenID Connect. For most newly issued Request Access clients, the safest default is a confidential-client setup: your app handles the login redirect, but your backend keeps `CLIENT_SECRET` and exchanges the code for tokens.
 
+## Production vs Pre-live
+
+:::warning Pre-live uses a separate user stack
+If you are testing User APIs in pre-live, keep the entire flow in pre-live.
+
+- Use the [Pre-live User-related APIs reference](/docs/user_related_apis_prelive/user-related-apis) when testing pre-live endpoints.
+- Use [prelive.quran.com](https://prelive.quran.com) for auth paths and auth-backed user data checks.
+- Use [prelive.quranreflect.org](https://prelive.quranreflect.org) for Quran Reflect paths and data checks.
+- Do not mix production login state, production user data, or production docs with pre-live testing.
+:::
+
 ## Recommended Architecture
 
 :::important Default integration shape
@@ -127,7 +138,7 @@ Request only the scopes your app actually needs.
 - Embedding `CLIENT_SECRET` in a mobile app or browser app.
 - Calling `/oauth2/token` directly from a confidential client without backend client authentication.
 - Skipping OAuth2 `state` validation, or `nonce` validation when you rely on `id_token`.
-- Mixing prelive and production OAuth2 environments.
+- Mixing pre-live and production OAuth2 environments, sessions, or manual test surfaces.
 - Requesting more scopes than your app needs.
 - Treating the `id_token` as an API access token instead of using the `access_token`.
 - Calling User APIs directly from browser JavaScript in a confidential web integration instead of routing the request through your backend or proxy.

src/components/UserRelatedApiEnvironmentNotice/index.tsx

@@ -25,13 +25,64 @@ const getCopy = (environment: "production" | "pre-live") => {
   if (environment === "pre-live") {
     return {
       title: "Pre-live user-related API docs",
-      body: "",
+      body: (
+        <>
+          <p>
+            Pre-live user APIs run on a separate user stack. Keep auth, API
+            calls, and manual verification in pre-live when testing this
+            environment.
+          </p>
+          <ul className={styles.list}>
+            <li>
+              Use{" "}
+              <a
+                href="https://prelive.quran.com"
+                target="_blank"
+                rel="noreferrer"
+              >
+                prelive.quran.com
+              </a>{" "}
+              for auth paths and auth-backed user data checks.
+            </li>
+            <li>
+              Use{" "}
+              <a
+                href="https://prelive.quranreflect.org"
+                target="_blank"
+                rel="noreferrer"
+              >
+                prelive.quranreflect.org
+              </a>{" "}
+              for Quran Reflect paths and data checks.
+            </li>
+            <li>Do not mix production sessions or production user data with pre-live testing.</li>
+          </ul>
+        </>
+      ),
     };
   }
 
   return {
     title: "Production user-related API docs",
-    body: "",
+    body: (
+      <p>
+        These pages describe the production user stack. If you need to test
+        pre-live, switch environments above and keep auth, API calls, and
+        manual checks in pre-live, including{" "}
+        <a href="https://prelive.quran.com" target="_blank" rel="noreferrer">
+          prelive.quran.com
+        </a>{" "}
+        for auth paths and{" "}
+        <a
+          href="https://prelive.quranreflect.org"
+          target="_blank"
+          rel="noreferrer"
+        >
+          prelive.quranreflect.org
+        </a>{" "}
+        for Quran Reflect paths.
+      </p>
+    ),
   };
 };
 
@@ -108,7 +159,7 @@ export default function UserRelatedApiEnvironmentNotice({
           })}
         </nav>
       </div>
-      <p className={styles.body}>{copy.body}</p>
+      <div className={styles.body}>{copy.body}</div>
     </div>
   );
 }

src/components/UserRelatedApiEnvironmentNotice/paths.js

@@ -1,12 +1,14 @@
 const PROD_CATEGORY_PATH = '/docs/category/user-related-apis';
 const PRELIVE_CATEGORY_PATH = '/docs/category/user-related-apis-pre-live';
+const PROD_INTRO_PATH = '/docs/user_related_apis_versioned/user-related-apis';
+const PRELIVE_INTRO_PATH = '/docs/user_related_apis_prelive/user-related-apis';
 const PROD_LATEST_PREFIX = '/docs/user_related_apis_versioned/';
 const PRELIVE_PREFIX = '/docs/user_related_apis_prelive/';
 const PROD_VERSION_PREFIX_REGEX = /^\d+\.\d+\.\d+(\/|$)/;
 
 const stripPrefix = (value, prefix) => value.slice(prefix.length);
 const getFallbackPath = (environment) =>
-  environment === 'production' ? PROD_CATEGORY_PATH : PRELIVE_CATEGORY_PATH;
+  environment === 'production' ? PROD_INTRO_PATH : PRELIVE_INTRO_PATH;
 
 function getUserRelatedDocsAvailablePaths(allDocsData) {
   const paths = new Set();

src/components/UserRelatedApiEnvironmentNotice/styles.module.css

@@ -38,6 +38,27 @@
   color: var(--ifm-color-emphasis-800);
 }
 
+.body p {
+  margin: 0;
+}
+
+.body > * + * {
+  margin-top: 0.75rem;
+}
+
+.body a {
+  font-weight: 600;
+}
+
+.list {
+  margin: 0;
+  padding-left: 1.25rem;
+}
+
+.list li + li {
+  margin-top: 0.35rem;
+}
+
 .switcher {
   display: inline-flex;
   align-items: center;