[IA] docs team proposal

.github/workflows/lint.yml

@@ -11,7 +11,6 @@ jobs:
       - uses: actions/checkout@v3
       - run: npm i
       - run: npm run lint:formatting
-      - run: npm run lint:check-links
       - run: npm run lint:check-frontmatter
 
   check_quickstarts:

.github/workflows/migration.yml

@@ -7,7 +7,6 @@ on:
   push:
     paths:
       - 'proposal-mapping.json'
-      - 'proposal.md'
       - 'scripts/migration-assistant/map-content.ts'
       - 'docs/**'
 
@@ -17,5 +16,4 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - run: npm i
-      - run: npm run migration:generate-manifest
       - run: npm run migration:map-content

.gitignore

@@ -44,5 +44,4 @@ yarn.lock
 
 /docs/docs
 /docs/docs/
-public/manifest.proposal.json
 /local-clerk-typedoc

CONTRIBUTING.md

@@ -242,13 +242,13 @@ To update the SDK selector, the files you need are in `clerk/clerk`:
 
 If the SDK has docs that are internal, i.e. maintained in `clerk-docs`, then follow these instructions. If the SDK has docs that are external, e.g. Python located at `https://github.com/clerk/clerk-sdk-python/blob/main/README.md`, then see the [section on adding an external SDK](#add-an-external-sdk).
 
-To add a new SDK, you'll need the SDK name (e.g. `Next.js`), key (e.g. `nextjs`), and 2 SVG icons: one in color and one in grayscale. These must be converted to JSX syntax, not HTML / standard SVG syntax. You will need these SVG's because we list the Clerk SDK's on [https://clerk.com/docs](https://clerk.com/docs), [https://clerk.com/docs/references/overview](https://clerk.com/docs/references/overview), and if there is a quickstart for it, [https://clerk.com/docs/quickstarts/overview](https://clerk.com/docs/quickstarts/overview).
+To add a new SDK, you'll need the SDK name (e.g. `Next.js`), key (e.g. `nextjs`), and 2 SVG icons: one in color and one in grayscale. These must be converted to JSX syntax, not HTML / standard SVG syntax. You will need these SVG's because we list the Clerk SDK's on [https://clerk.com/docs](https://clerk.com/docs), [https://clerk.com/docs/reference/overview](https://clerk.com/docs/reference/overview), and if there is a quickstart for it, [https://clerk.com/docs/quickstarts/overview](https://clerk.com/docs/quickstarts/overview).
 
 In this repo (`clerk/clerk-docs`):
 
 1. In the `manifest.schema.json`, add a reference name in the `icon` enum and add the SDK key to the `sdk` enum.
 1. Add the color SVG to the partials icon folder `_partials/icons/`.
-1. Add the SDK to `index.mdx`, `references/overview.mdx`, and if there is a quickstart for it, `quickstarts/overview.mdx`.
+1. Add the SDK to `index.mdx`, `reference/overview.mdx`, and if there is a quickstart for it, `quickstarts/overview.mdx`.
 1. In the `manifest.json`, find the `"title": "Clerk SDK",` object. It should be the first object in the `"navigation"` array. Add the SDK accordingly. For example, it could include files like a quickstart, a references section with an overview and some reference docs, or a guides section with some dedicated guides for that SDK.
 
 Now, the sidenav is set up to render the items for the new SDK you've added, and to link to the routes/doc files that you defined. However, you've got to get the SDK selector working as well:
@@ -262,13 +262,13 @@ In the `clerk/clerk` repo:
 
 If the SDK has docs that are external, e.g. Python located at `https://github.com/clerk/clerk-sdk-python/blob/main/README.md`, then follow these instructions. If the SDK has docs that are internal, i.e. maintained in `clerk-docs`, then see the [section on adding a new SDK](#add-a-new-sdk).
 
-To add a new SDK, you'll need the SDK name (e.g. `Python`), key (e.g. `python`), and 2 SVG icons: one in color and one in grayscale. These must be converted to JSX syntax, not HTML / standard SVG syntax. You will need these SVG's because we list the Clerk SDK's on [https://clerk.com/docs](https://clerk.com/docs) and [https://clerk.com/docs/references/overview](https://clerk.com/docs/references/overview).
+To add a new SDK, you'll need the SDK name (e.g. `Python`), key (e.g. `python`), and 2 SVG icons: one in color and one in grayscale. These must be converted to JSX syntax, not HTML / standard SVG syntax. You will need these SVG's because we list the Clerk SDK's on [https://clerk.com/docs](https://clerk.com/docs) and [https://clerk.com/docs/reference/overview](https://clerk.com/docs/reference/overview).
 
 In this repo (`clerk/clerk-docs`):
 
 1. In the `manifest.schema.json`, add a reference name in the `icon` enum and add the SDK key to the `sdk` enum.
 1. Add the color SVG to the partials icon folder `_partials/icons/`.
-1. Add the SDK to `index.mdx` and `references/overview.mdx`.
+1. Add the SDK to `index.mdx` and `reference/overview.mdx`.
 
 Now, the sidenav is set up to render the items for the new SDK you've added, and to link to the routes/doc files that you defined. However, you've got to get the SDK selector working as well:
 
@@ -828,7 +828,7 @@ The `<Cards>` component can be used to display a grid of cards in various styles
 
 ---
 
-- [UI Components](/docs/components/overview)
+- [UI Components](/docs/reference/components/overview)
 - Clerk's prebuilt UI components give you a beautiful, fully-functional user management experience in minutes.
 
 </Cards>
@@ -850,7 +850,7 @@ The `<Cards>` component can be used to display a grid of cards in various styles
 
 ---
 
-- [UI Components](/docs/components/overview)
+- [UI Components](/docs/reference/components/overview)
 - Clerk's prebuilt UI components give you a beautiful, fully-functional user management experience in minutes.
 - {<svg viewBox="0 0 32 32">{/*  */}</svg>}
 
@@ -873,7 +873,7 @@ The `<Cards>` component can be used to display a grid of cards in various styles
 
 ---
 
-- [UI Components](/docs/components/overview)
+- [UI Components](/docs/reference/components/overview)
 - Clerk's prebuilt UI components give you a beautiful, fully-functional user management experience in minutes.
 - {<svg viewBox="0 0 32 32">{/*  */}</svg>}
 
@@ -890,13 +890,13 @@ The `<Cards>` component can be used to display a grid of cards in various styles
 ```mdx
 <Cards variant="image">
 
-- [What is Clerk authentication?](/docs/authentication/overview)
+- [What is Clerk authentication?](/docs/guides/configure/auth-strategies/sign-up-sign-in-options)
 - Clerk offers multiple authentication strategies to identify legitimate users of your application, and to allow them to make authenticated requests to your backend.
 - ![](/what-is-clerk.png)
 
 ---
 
-- [What is the “User” object?](/docs/users/overview)
+- [What is the “User” object?](/docs/guides/users/managing)
 - The User object contains all account information that describes a user of your app in Clerk. Users can authenticate and manage their accounts, update their personal and contact info, or set up security features for their accounts.
 - ![](/user-object.png)
 

docs/_partials/astro/auth-store.mdx

@@ -1,4 +1,4 @@
-The following example demonstrates how to use the [`$authStore`](/docs/references/astro/auth-store) to access the current auth state. It uses `userId` to detect if the user is signed in.
+The following example demonstrates how to use the [`$authStore`](/docs/reference/astro/client-side-helpers/auth-store) to access the current auth state. It uses `userId` to detect if the user is signed in.
 
 <CodeBlockTabs options={['React', 'Vue', 'Svelte']}>
   ```tsx {{ filename: 'components/external-data.tsx' }}

docs/_partials/astro/user-store.mdx

@@ -1,6 +1,6 @@
-The following example demonstrates how to use the [`$userStore`](/docs/references/astro/user-store) to access the `User` object. It returns `undefined` while Clerk is still loading and `null` if the user is not signed in.
+The following example demonstrates how to use the [`$userStore`](/docs/reference/astro/client-side-helpers/user-store) to access the `User` object. It returns `undefined` while Clerk is still loading and `null` if the user is not signed in.
 
-For more information, see the [`User` reference](/docs/references/javascript/user){{ target: '_blank' }}.
+For more information, see the [`User` reference](/docs/reference/javascript/user){{ target: '_blank' }}.
 
 <CodeBlockTabs options={['React', 'Vue', 'Svelte']}>
   ```tsx {{ filename: 'user.tsx' }}

docs/_partials/auth-object-table.mdx

@@ -4,11 +4,11 @@ The `Auth` object is available on the `request` object in server contexts. Some
 
 | Framework | How to access the `Auth` object |
 | - | - |
-| Next.js App Router | [`auth()`](/docs/references/nextjs/auth) |
-| Next.js Pages Router | [`getAuth()`](/docs/references/nextjs/get-auth) |
-| Astro | [`locals.auth()`](/docs/references/astro/locals#locals-auth) |
-| Express | [`req.auth`](/docs/references/express/overview) |
-| React Router | [`getAuth()`](/docs/references/react-router/get-auth) |
-| Remix | [`getAuth()`](/docs/references/remix/read-session-data#get-auth) |
-| Tanstack React Start | [`getAuth()`](/docs/references/tanstack-react-start/get-auth) |
+| Next.js App Router | [`auth()`](/docs/reference/nextjs/app-router/auth) |
+| Next.js Pages Router | [`getAuth()`](/docs/reference/nextjs/pages-router/get-auth) |
+| Astro | [`locals.auth()`](/docs/reference/astro/locals#locals-auth) |
+| Express | [`req.auth`](/docs/reference/express/overview) |
+| React Router | [`getAuth()`](/docs/reference/react-router/get-auth) |
+| Remix | [`getAuth()`](/docs/reference/remix/overview#get-auth) |
+| Tanstack React Start | [`getAuth()`](/docs/reference/tanstack-react-start/get-auth) |
 | Other | `request.auth` |

docs/_partials/authentication/passkeys-restriction.mdx

@@ -4,13 +4,12 @@ Passkeys are tied to the domain they are created on and **cannot be used across
 - Passkeys created on `your-domain.com` **can be used** on `accounts.your-domain.com` (subdomain of the same root domain).
 - Passkeys created on `staging1.your-domain.com` **cannot be used** on `staging2.your-domain.com` (sibling subdomains) unless the passkey was scoped to `your-domain.com` (i.e. the shared root domain).
 
-**If you're using [satellite domains](/docs/advanced-usage/satellite-domains)**, in both development and production, passkeys won't be portable between your primary domain and your satellite domains so you should avoid using them.
+**If you're using [satellite domains](/docs/guides/dashboard/dns-domains/satellite-domains)**, in both development and production, passkeys won't be portable between your primary domain and your satellite domains so you should avoid using them.
 
 If you're **not** using satellite domains:
 
 - **In development**, you can either:
-
-  - **The recommended approach**. Use Clerk's [components](/docs/components/overview), [Elements](/docs/customization/elements/overview), or [custom flows](/docs/custom-flows/overview), instead of the [Account Portal](/docs/account-portal/overview). This ensures the passkey is created and used entirely on your development domain, so passkeys created on `localhost` will only work on `localhost`.
+  - **The recommended approach**. Use Clerk's [components](/docs/reference/components/overview), [Elements](/docs/guides/customizing-clerk/elements/overview), or [custom flows](/docs/guides/development/custom-flows/overview), instead of the [Account Portal](/docs/guides/customizing-clerk/account-portal). This ensures the passkey is created and used entirely on your development domain, so passkeys created on `localhost` will only work on `localhost`.
   - Create a passkey directly through the Account Portal instead of your local application to keep it tied to the Account Portal's domain. Passkeys created on your Account Portal (e.g., `your-app.accounts.dev`) will only work on that domain, which can cause issues if you switch between `localhost` and the Account Portal during development. If you choose this approach, ensure all testing happens on the same domain where the passkey was created.
 
 - **In production,** your Account Portal is usually hosted on a subdomain of your main domain (e.g. `accounts.your-domain.com`), enabling passkeys to work seamlessly across your app. However, as stated above, if you use **satellite domains**, passkeys will not work as intended.

docs/_partials/authentication/social-connections/test-your-connection.mdx

@@ -1,4 +1,4 @@
-The simplest way to test your connection is to visit your Clerk app's [Account Portal](/docs/account-portal/overview), which is available for all Clerk apps out-of-the-box.
+The simplest way to test your connection is to visit your Clerk app's [Account Portal](/docs/guides/customizing-clerk/account-portal), which is available for all Clerk apps out-of-the-box.
 
 1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page.
 1. Next to **Sign-in**, select the button to visit the sign-in page. The URL should resemble:

docs/versioning/available-versions.mdx → docs/_partials/available-versions.mdx

@@ -1,13 +1,6 @@
----
-title: Available versions
-description: A list of the available API versions and their breaking changes.
----
-
-Below is a list of all the available API versions with their respective breaking changes. For information on how to apply the appropriate version, see [Versioning overview](/docs/versioning/overview).
-
 ### 2025-04-10
 
-Adds support for [version 2 of Clerk session tokens](/docs/backend-requests/resources/session-tokens).
+Adds support for [version 2 of Clerk session tokens](/docs/guides/sessions/session-tokens).
 The following SDKs are compatible with this version:
 
 | SDK | Version |

docs/_partials/backend/usage.mdx

@@ -1,2 +1,2 @@
 > [!NOTE]
-> Importing `clerkClient` varies based on your framework. Refer to the [Backend SDK overview](/docs/references/backend/overview) for usage details, including guidance on [how to access the `userId` and other properties](/docs/references/backend/overview#get-the-user-id-and-other-properties).
+> Importing `clerkClient` varies based on your framework. Refer to the [JS Backend SDK overview](/docs/js-backend/getting-started/quickstart) for usage details, including guidance on [how to access the `userId` and other properties](/docs/js-backend/getting-started/quickstart#get-the-user-id-and-other-properties).

docs/_partials/clerk-middleware-options.mdx

@@ -39,14 +39,14 @@ The `clerkMiddleware()` function accepts an optional object. The following optio
   - `jwtKey`
   - `string`
 
-  Used to verify the session token in a networkless manner. Supply the **JWKS Public Key** from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables) instead.** For more information, refer to [Manual JWT verification](/docs/backend-requests/manual-jwt).
+  Used to verify the session token in a networkless manner. Supply the **JWKS Public Key** from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard. **It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables) instead.** For more information, refer to [Manual JWT verification](/docs/guides/sessions/manual-jwt-verification).
 
   ---
 
   - `organizationSyncOptions?`
   - <code>[OrganizationSyncOptions](#organization-sync-options) | undefined</code>
 
-  Used to activate a specific [organization](/docs/organizations/overview) or [personal account](/docs/organizations/overview#allow-personal-accounts) based on URL path parameters. If there's a mismatch between the active organization in the session (e.g., as reported by [`auth()`](/docs/references/nextjs/auth)) and the organization indicated by the URL, the middleware will attempt to activate the organization specified in the URL.
+  Used to activate a specific [organization](/docs/guides/organizations/overview) or [personal account](/docs/guides/dashboard/overview) based on URL path parameters. If there's a mismatch between the active organization in the session (e.g., as reported by [`auth()`](/docs/reference/nextjs/app-router/auth)) and the organization indicated by the URL, the middleware will attempt to activate the organization specified in the URL.
 
   ---
 
@@ -60,14 +60,14 @@ The `clerkMiddleware()` function accepts an optional object. The following optio
   - `signInUrl`
   - `string`
 
-  The full URL or path to your sign-in page. Needs to point to your primary application on the client-side. **Required for a satellite application in a development instance.** It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+  The full URL or path to your sign-in page. Needs to point to your primary application on the client-side. **Required for a satellite application in a development instance.** It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
 
   ---
 
   - `signUpUrl`
   - `string`
 
-  The full URL or path to your sign-up page. Needs to point to your primary application on the client-side. **Required for a satellite application in a development instance.** It's recommended to use [the environment variable](/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
+  The full URL or path to your sign-up page. Needs to point to your primary application on the client-side. **Required for a satellite application in a development instance.** It's recommended to use [the environment variable](/docs/guides/development/clerk-environment-variables#sign-in-and-sign-up-redirects) instead.
 
   ---
 

docs/_partials/clerk-options.mdx

@@ -9,7 +9,7 @@
   - `jwtKey?`
   - `string`
 
-  The **JWKS Public Key** from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) in the Clerk Dashboard. For more information, refer to [Manual JWT verification](/docs/backend-requests/manual-jwt).
+  The **JWKS Public Key** from the [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) in the Clerk Dashboard. For more information, refer to [Manual JWT verification](/docs/guides/sessions/manual-jwt-verification).
 
   ---
 
@@ -23,7 +23,7 @@
   - `domain?`
   - `string`
 
-  The domain of a [satellite application](/docs/advanced-usage/satellite-domains) in a multi-domain setup.
+  The domain of a [satellite application](/docs/guides/dashboard/dns-domains/satellite-domains) in a multi-domain setup.
 
   ---
 
@@ -51,7 +51,7 @@
   - `telemetry?`
   - `{ disabled: boolean, debug: boolean }`
 
-  [Telemetry](/docs/telemetry) configuration.
+  [Telemetry](/docs/guides/how-clerk-works/security/clerk-telemetry) configuration.
 
   ---
 

docs/_partials/clerk-provider/explanation.mdx

@@ -1 +1 @@
-The [`<ClerkProvider>`](/docs/components/clerk-provider) component provides session and user context to Clerk's hooks and components. It's recommended to wrap your entire app at the entry point with `<ClerkProvider>` to make authentication globally accessible. See the [reference docs](/docs/components/clerk-provider) for other configuration options.
+The [`<ClerkProvider>`](/docs/reference/components/clerk-provider) component provides session and user context to Clerk's hooks and components. It's recommended to wrap your entire app at the entry point with `<ClerkProvider>` to make authentication globally accessible. See the [reference docs](/docs/reference/components/clerk-provider) for other configuration options.