diff --git a/main/.mintlify/skills/acul-screen-generator/SKILL.md b/main/.mintlify/skills/acul-screen-generator/SKILL.md
deleted file mode 100644
index 54aa917b72..0000000000
--- a/main/.mintlify/skills/acul-screen-generator/SKILL.md
+++ /dev/null
@@ -1,377 +0,0 @@
----
-name: acul-screen-generator
-description: Generates complete, branded Auth0 Advanced Custom Universal Login (ACUL) screen implementations using the React or Vanilla JS SDK. Use when a developer asks to create, add, or modify ACUL login screens with custom branding, social login, theming, or specific authentication flows. Triggers on requests like "generate a custom login screen", "add a signup screen to my ACUL project", "customize my Auth0 Universal Login with our brand colors", "apply our theme to all ACUL screens", or any task involving Auth0 Universal Login customization with @auth0/auth0-acul-react or @auth0/auth0-acul-js.
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# ACUL Screen Generator
-
-Generates production-ready, fully themed Auth0 ACUL screen components. Follows a strict 8-phase workflow (Phases 0–7): CLI authentication → intent detection → project setup → screen requirements → tech stack and design → theme extraction → structured code generation → dev mode wiring.
-
-## Reference Hierarchy
-
-Always resolve the correct reference for a screen using this priority order:
-
-```
-1. auth0-acul-samples  (31 React screens, 3 React-JS screens)
-   → Complete modular implementation: index.tsx + components/ + hooks/ + locales/
-   → React:    https://github.com/auth0-samples/auth0-acul-samples/tree/main/react/src/screens/<screen-name>
-   → React-JS: https://github.com/auth0-samples/auth0-acul-samples/tree/main/react-js/src/screens/<screen-name>
-
-2. SDK examples  (68 React, 71 JS — all screens)
-   → Code snippets showing SDK imports, hooks, and action functions
-   → React: https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-react/examples/<screen-name>.md
-   → JS:    https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-js/examples/<screen-name>.md
-
-3. assets/react-templates/ or assets/js-templates/
-   → Structural component pattern only — never use their hooks/actions for other screens
-```
-
-For which screens are in auth0-acul-samples → read `references/screen-catalog.md`.
-
----
-
-## auth0-acul-samples Architecture
-
-When a screen is available in auth0-acul-samples, generate code using this modular pattern — not a monolithic component.
-
-**Directory structure per screen:**
-```
-<screen-name>/
-├── index.tsx                        thin entry: wires manager hook + applies theme + renders layout
-├── components/
-│   ├── Header.tsx                   logo, title, subtitle from screen.texts
-│   ├── <ScreenName>Form.tsx         form fields, submit, captcha, passkey button
-│   ├── Footer.tsx                   signup link, forgot password, back link
-│   └── AlternativeLogins.tsx        social login buttons (if screen has social)
-├── hooks/
-│   └── use<ScreenName>Manager.ts    wraps SDK hooks, exposes clean handlers + feature flags
-└── locales/
-    └── en.json                      fallback text strings
-```
-
-**index.tsx pattern:**
-```tsx
-import { ULThemeCard, ULThemePageLayout } from '@/components'
-import { applyAuth0Theme } from '@/utils/theme/themeEngine'
-import Header from './components/Header'
-import <ScreenName>Form from './components/<ScreenName>Form'
-import Footer from './components/Footer'
-import { use<ScreenName>Manager } from './hooks/use<ScreenName>Manager'
-
-export const <ScreenName>Screen = () => {
-  const { sdkInstance, texts, locales } = use<ScreenName>Manager()
-  applyAuth0Theme(sdkInstance)
-  document.title = texts?.pageTitle ?? locales.pageTitle
-
-  return (
-    <ULThemePageLayout>
-      <ULThemeCard>
-        <Header texts={texts} />
-        <AlternativeLogins alignment="top" />    {/* conditional */}
-        <<ScreenName>Form />
-        <Footer texts={texts} links={links} />
-        <AlternativeLogins alignment="bottom" />  {/* conditional */}
-      </ULThemeCard>
-    </ULThemePageLayout>
-  )
-}
-```
-
-**hooks/use\<ScreenName\>Manager.ts pattern:**
-```ts
-import { useLoginId, useScreen, useTransaction } from '@auth0/auth0-acul-react/<screen-name>'
-import { executeSafely } from '@/utils/helpers/executeSafely'
-import locales from '../locales/en.json'
-
-export const use<ScreenName>Manager = () => {
-  const sdkInstance = useLoginId()       // screen-specific SDK hook
-  const screen = useScreen()
-  const { alternateConnections } = useTransaction()
-
-  const handleSubmit = async (data) => executeSafely(() => login(data))
-  const handleFederatedLogin = async (conn) => executeSafely(() => federatedLogin({ connection: conn }))
-
-  return {
-    sdkInstance,
-    texts: screen.texts,
-    locales,
-    alternateConnections,
-    handleSubmit,
-    handleFederatedLogin,
-    isPasskeyEnabled: screen.isPasskeyEnabled,
-    isCaptchaAvailable: screen.isCaptchaAvailable,
-  }
-}
-```
-
-When a screen is **not** in auth0-acul-samples, fall back to a single-file component based on the SDK example.
-
-## Prerequisites
-
-- Auth0 CLI installed: `brew install auth0`
-- Custom domain configured on the Auth0 tenant (hard ACUL requirement)
-- Node.js 18+
-
----
-
-## Phase 0: CLI Authentication & Tenant Check
-
-```bash
-auth0 login
-auth0 acul config list --rendering-mode advanced
-```
-
-If `auth0 acul config list` returns an error about custom domain: stop and inform the customer they must configure a custom domain on their tenant before ACUL is available.
-
-For full CLI flag reference → read `references/cli-commands.md`.
-
----
-
-## Phase 1: Intent Detection
-
-Ask the customer which mode they need:
-
-- **A) Build from scratch** — new project, select screens, full setup
-- **B) Add a screen** — existing project, add one or more new screens
-- **C) Modify a screen** — existing project, change an existing screen's code or styling
-
-This choice gates Phases 2A / 2B / 2C.
-
----
-
-## Phase 2A: Scratch — Project Init
-
-Gather: app name, framework (`react` or `js`), initial screen list.
-
-```bash
-auth0 acul init <app_name> -t react -s login-id,login-password,signup
-auth0 acul config generate <screen-name>    # repeat per screen
-```
-
-Verify `acul_config.json` is created in the project directory. Proceed to Phase 3.
-
----
-
-## Phase 2B: Add Screen — CLI + Reference Fetch
-
-1. Verify `acul_config.json` exists in the project directory.
-   - If missing → stop. Instruct customer to run `auth0 acul init` first.
-
-2. Run:
-   ```bash
-   auth0 acul screen add <screen-name> -d <project-dir>
-   ```
-   If CLI errors or screen is not recognised → continue to step 3.
-
-3. **Always resolve the reference using the hierarchy** (regardless of CLI success or failure):
-
-   **Step 3a — Check auth0-acul-samples first:**
-   - Read `references/screen-catalog.md` to check if the screen has a `✅` in the Samples column
-   - If yes → fetch the screen directory from:
-     - React: `https://github.com/auth0-samples/auth0-acul-samples/tree/main/react/src/screens/<screen-name>`
-     - React-JS: `https://github.com/auth0-samples/auth0-acul-samples/tree/main/react-js/src/screens/<screen-name>`
-   - Fetch `index.tsx` and the `hooks/use<ScreenName>Manager.ts` file to understand the full implementation
-   - Use the samples architecture (modular: index + components + hooks + locales)
-
-   **Step 3b — If not in samples, fetch SDK example:**
-   - React: `https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-react/examples/<screen-name>.md`
-   - JS: `https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-js/examples/<screen-name>.md`
-   - Parse for: exact import path, hook pattern (generic vs screen-specific), action functions and payload shapes
-   - Use a single-file component (no modular split needed)
-
-   This step is mandatory. The 68+ ACUL screens use fundamentally different hook patterns — wrong pattern = broken code.
-
-   For all screen names and which are in samples → read `references/screen-catalog.md`.
-
----
-
-## Phase 2C: Modify Screen — Fetch Current State
-
-1. Verify `acul_config.json` exists.
-
-2. Fetch current rendering configuration:
-   ```bash
-   auth0 acul config get <screen-name> -f <screen-name>.json
-   auth0 acul config list --rendering-mode advanced
-   ```
-
-3. Read the existing screen file from the customer's codebase.
-
-4. **Always resolve the reference using the same hierarchy as Phase 2B** (samples first, SDK example second). Even when modifying an existing file, the reference confirms whether the current code uses the correct hook pattern, action functions, and component structure before making changes.
-
----
-
-## Phase 3: Screen Requirements
-
-Gather from the customer:
-
-- **Screen type** — for full list of available screens → read `references/screen-catalog.md`
-- **Components needed:**
-  - Social providers: Google, GitHub, Apple, Microsoft, Facebook
-  - Form fields: email, username, phone, password, confirm-password
-  - MFA type (if applicable): OTP, SMS, push, WebAuthn
-  - Optional extras: captcha, passkey button, remember-me, terms checkbox
-- **For modify mode:** what specifically to change (layout, colors, add/remove a component)
-
----
-
-## Phase 4: Tech Stack Detection
-
-Confirm or detect:
-
-- **Framework:** React (`@auth0/auth0-acul-react`) or JS (`@auth0/auth0-acul-js`)
-- **Styling library:** Tailwind CSS / CSS Modules / styled-components / plain CSS
-- **Existing theme file?** Check for `tailwind.config.ts`, `styles/tokens.css`, `theme/index.ts`
-
-Load the appropriate SDK reference:
-- React → read `references/acul-react-sdk.md`
-- JS → read `references/acul-js-sdk.md`
-
-For social button implementation → read `references/social-providers.md`.
-
----
-
-## Phase 5: Theme Extraction & Scope
-
-### Design input — detect which the customer has provided:
-
-**Option A — Image or mockup (jpeg / png / screenshot):**
-Analyze the image and extract:
-- Primary, secondary, accent colors (as hex)
-- Background and card/surface colors
-- Font family and weights
-- Border radius style (sharp / slight / rounded / pill)
-- Spacing rhythm (compact / normal / spacious)
-- Layout type: centered card / full-bleed / split-panel / floating card
-
-**Option B — Brand colors only (no image):**
-Derive the full token set from the provided hex values:
-```
-primary        → button bg, links, focus ring
-primary-hover  → primary darkened ~10%
-primary-text   → white if primary is dark, else #111827
-background     → page background
-surface        → card/panel background
-text-primary   → headings (#111827 light / #F1F5F9 dark)
-text-secondary → labels, placeholders
-border         → input borders
-error          → #EF4444 (unless specified)
-success        → #22C55E (unless specified)
-```
-
-### Theme scope — ask the customer:
-
-- **Single screen:** apply tokens inline to just this component's styles
-- **All screens:** generate a shared theme file first, then apply consistently across every screen
-
-For theme file patterns per styling library → read `references/theming-patterns.md`.
-
-**Theme file to generate per styling library (all-screens scope):**
-
-| Styling library | Template to use | Output file |
-|----------------|-----------------|-------------|
-| Tailwind | `assets/theme-templates/tailwind.config.ts` | `tailwind.config.ts` |
-| CSS Modules | `assets/theme-templates/tokens.css` | `styles/tokens.css` |
-| styled-components | `assets/theme-templates/theme-provider.ts` | `theme/index.ts` |
-| Plain CSS | `assets/theme-templates/globals.css` | `styles/globals.css` |
-
-Replace all `{{TOKEN}}` placeholders with extracted token values.
-
----
-
-## Phase 6: Structured Code Generation
-
-Generation approach depends on whether the screen is in auth0-acul-samples.
-
-### Path A — Screen is in auth0-acul-samples (modular architecture)
-
-Generate the full directory structure using the samples pattern (see "auth0-acul-samples Architecture" above):
-
-```
-<screen-name>/
-├── index.tsx
-├── components/
-│   ├── Header.tsx
-│   ├── <ScreenName>Form.tsx
-│   ├── Footer.tsx
-│   └── AlternativeLogins.tsx       (only if screen has social login)
-├── hooks/
-│   └── use<ScreenName>Manager.ts
-└── locales/
-    └── en.json
-```
-
-- `index.tsx` — thin: calls `use<ScreenName>Manager()`, calls `applyAuth0Theme()`, renders `ULThemePageLayout` → `ULThemeCard` → sub-components
-- `use<ScreenName>Manager.ts` — wraps SDK hooks from the samples reference, exposes typed handlers and feature flags
-- Form component — uses react-hook-form, reads from manager hook, no direct SDK calls
-- Header/Footer — stateless, receive texts as props
-- `en.json` — fallback strings matching keys used in `screen.texts.*`
-
-Apply design tokens from Phase 5 to the layout components and form component styling.
-
-### Path B — Screen is NOT in auth0-acul-samples (single-file component)
-
-Generate a single `<screen-name>.tsx` (React) or `<screen-name>.js` (JS) using the structure from `assets/react-templates/` or `assets/js-templates/` as a pattern, with hooks and actions sourced entirely from the SDK example fetched in Phase 2.
-
-JSX structure order:
-```
-Outer layout wrapper → Card/panel → Logo slot → Title (screen.texts) →
-Error banner (conditional) → Form fields → Captcha (conditional) →
-Submit button → Passkey button (conditional) → Social divider + buttons
-(conditional on alternateConnections) → Footer links
-```
-
-### Validation before outputting any code
-
-- SDK import path exactly matches the screen name (e.g., `@auth0/auth0-acul-react/mfa-otp-challenge`)
-- Hook pattern (generic `useScreen()` vs screen-specific hook) sourced from the reference, not assumed
-- Action function names and payload shapes sourced from the reference
-- Error state uses SDK source (`hasErrors` / `getErrors()`) — never local-only error state
-- No hardcoded UI strings — use `screen.texts.*` with locale fallback
-- `applyAuth0Theme()` called in index.tsx for Path A screens
-
-**All-screens scope:** repeat Path A or Path B (whichever applies per screen) for every screen in the project, all importing from the shared theme file. Consistent component structure within each path.
-
----
-
-## Phase 7: Dev Mode Wiring
-
-Provide the customer with ready-to-run commands:
-
-```bash
-# Local preview — no tenant connection needed
-auth0 acul dev -p 3000 -d <project-dir>
-
-# Connected mode — syncs assets to tenant (stage/dev only)
-auth0 acul dev --connected -s <screen-name> -d <project-dir>
-```
-
-⚠️ Always include this warning when connected mode is suggested:
-> Connected mode updates your Auth0 tenant in real time. Only use this on a stage or development tenant — never on production.
-
----
-
-## Reference Files
-
-| File | Load when |
-|------|-----------|
-| `references/acul-react-sdk.md` | Framework is React |
-| `references/acul-js-sdk.md` | Framework is JS / Vanilla |
-| `references/screen-catalog.md` | Selecting screen type or triggering CLI fallback |
-| `references/social-providers.md` | Social login buttons are needed |
-| `references/theming-patterns.md` | Generating or applying a shared theme file |
-| `references/cli-commands.md` | Need full CLI flag details |
-
-## Asset Templates
-
-| File | Use when |
-|------|----------|
-| `assets/theme-templates/tailwind.config.ts` | Tailwind, all-screens scope |
-| `assets/theme-templates/tokens.css` | CSS Modules, all-screens scope |
-| `assets/theme-templates/theme-provider.ts` | styled-components |
-| `assets/theme-templates/globals.css` | Plain CSS, all-screens scope |
-| `assets/react-templates/<screen>.tsx` | React component boilerplate base |
-| `assets/js-templates/<screen>.js` | JS component boilerplate base |
diff --git a/main/.mintlify/skills/auth0-android/SKILL.md b/main/.mintlify/skills/auth0-android/SKILL.md
deleted file mode 100644
index 0048023133..0000000000
--- a/main/.mintlify/skills/auth0-android/SKILL.md
+++ /dev/null
@@ -1,183 +0,0 @@
----
-name: auth0-android
-description: Use when adding authentication to Android applications (Kotlin/Java) with Web Auth, biometric-protected credentials, and MFA - integrates com.auth0.android:auth0 SDK for native Android apps
-license: Proprietary
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 Android Integration
-
-Add authentication to Android applications using `com.auth0.android:auth0`.
-
-> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
-> ```
-> gh api repos/auth0/Auth0.Android/releases/latest --jq '.tag_name'
-> ```
-> Use the returned version in all `implementation` dependency lines instead of any hardcoded version below. If the command fails, fall back to checking https://github.com/auth0/Auth0.Android/releases.
-
-## Prerequisites
-
-- Android API 21 or higher
-- Kotlin or Java project
-- Auth0 account with a Native application configured
-- If you don't have Auth0 set up, see [auth0-quickstart](/auth0-quickstart)
-
-## When NOT to Use
-
-- **React Native apps**: Use [auth0-react-native](/auth0-react-native)
-- **Flutter apps**: Use the native Flutter Auth0 SDK
-- **Web SPAs** (React, Angular, Vue): Use [auth0-react](/auth0-react), [auth0-angular](/auth0-angular), or [auth0-vue](/auth0-vue)
-- **Node.js/Express servers**: Use [auth0-express](/auth0-express)
-- **iOS/macOS apps**: Use [auth0-swift](/auth0-swift)
-
-## Quick Start Workflow
-
-1. **Install SDK**: Add the Auth0 Android SDK dependency to your `build.gradle`:
-   ```gradle
-   implementation 'com.auth0.android:auth0:{LATEST_VERSION}'
-   ```
-
-2. **Configure Auth0**:
-
-    See [**Setup Guide**](references/setup.md) for automatic/manual setup, post-setup required project changes, and callback URL configuration.
-
-3. **Initialize**: Create an Auth0 account instance:
-   ```kotlin
-   import com.auth0.android.Auth0
-
-   val account = Auth0.getInstance(context)
-   ```
-
-4. **Add Auth UI**: Implement login and logout with Web Auth:
-
-   > **Agent instruction:** Before adding new UI elements, search the project for existing click handlers for login, logout, sign-in, or sign-out buttons (e.g., `loginButton`, `signInButton`, `logoutButton`, `signOutButton`, or `setOnClickListener` with auth-related naming). If existing handlers are found, hook the Auth0 code into them without modifying the existing UI. Only create new buttons if no existing handlers are found.
-
-   **Login:**
-   ```kotlin
-   import com.auth0.android.Auth0
-   import com.auth0.android.authentication.AuthenticationAPIClient
-   import com.auth0.android.authentication.storage.SecureCredentialsManager
-   import com.auth0.android.authentication.storage.SharedPreferencesStorage
-   import com.auth0.android.callback.Callback
-   import com.auth0.android.authentication.AuthenticationException
-   import com.auth0.android.provider.WebAuthProvider
-   import com.auth0.android.result.Credentials
-
-   val account = Auth0.getInstance(context)
-   val authentication = AuthenticationAPIClient(account)
-   val storage = SharedPreferencesStorage(context)
-   val credentialsManager = SecureCredentialsManager(context, authentication, storage)
-
-   WebAuthProvider.login(account)
-       .withScheme(getString(R.string.com_auth0_scheme))
-       .withScope("openid profile email offline_access")
-       .start(this, object : Callback<Credentials, AuthenticationException> {
-           override fun onSuccess(result: Credentials) {
-               // User authenticated
-               val idToken = result.idToken
-               val accessToken = result.accessToken
-               // Store credentials securely
-               credentialsManager.saveCredentials(result)
-           }
-           override fun onFailure(error: AuthenticationException) {
-               // Handle authentication failure
-               Log.e("Auth0", "Authentication failed", error)
-           }
-       })
-   ```
-
-   **Logout:**
-   ```kotlin
-   WebAuthProvider.logout(account)
-       .withScheme(getString(R.string.com_auth0_scheme))
-       .start(this, object : Callback<Void?, AuthenticationException> {
-           override fun onSuccess(result: Void) {
-               // User logged out
-           }
-           override fun onFailure(error: AuthenticationException) {
-               Log.e("Auth0", "Logout failed", error)
-           }
-       })
-   ```
-
-5. **Build & Verify**:
-
-   > **Agent instruction:** After completing the integration, build the project to verify it compiles successfully:
-   > ```bash
-   > ./gradlew assembleDebug
-   > ```
-   > If the build fails, analyze the error output and fix the issues. Common integration build failures include:
-   > - **Unresolved reference**: Missing import statements — add the required `import com.auth0.android.*` imports
-   > - **Cannot resolve symbol `R.string.com_auth0_scheme`**: `strings.xml` not updated — verify `com_auth0_scheme`, `com_auth0_client_id`, and `com_auth0_domain` entries exist
-   > - **Incompatible types in callback**: Callback type parameters don't match — ensure `Callback<Credentials, AuthenticationException>` for login and `Callback<Void?, AuthenticationException>` for logout
-   > - **Unresolved `lifecycleScope`**: Missing dependency — add `implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.6.+'` or move code out of coroutine scope
-   > - **minSdk too low**: SDK requires API 21+ — update `minSdkVersion` to at least 21
-   > - **Java version mismatch**: SDK requires Java 8 — add `compileOptions` with `JavaVersion.VERSION_1_8`
-   >
-   > Re-run the build after each fix. Track the number of build-fix iterations.
-   >
-   > **Failcheck:** If the build still fails after 5–6 fix attempts, stop and ask the user using `AskUserQuestion`:
-   > _"The build is still failing after several fix attempts. How would you like to proceed?"_
-   > - **Let the skill continue fixing iteratively** — continue the build-fix loop for another 5–6 attempts
-   > - **Fix it manually** — show the remaining errors and let the user resolve them
-   > - **Skip build verification** — proceed without a successful build
-   >
-   > Repeat this check after every 5–6 iterations if errors persist. Do not leave the project in a non-compiling state without the user's explicit consent.
-
-   The callback URL must match your Auth0 application settings: `{SCHEME}://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback`
-
-## Detailed Documentation
-
-- [**Setup Guide**](references/setup.md) — Install SDK, configure Auth0 application, set up callback URLs, Android App Links, custom schemes, ProGuard/R8
-- [**Integration Patterns**](references/integration.md) — Web Auth login/logout, credential storage, biometric authentication, database login, passwordless authentication, MFA handling, custom tabs, error handling
-- [**Testing & Reference**](references/api.md) — Testing checklist, common issues, security considerations, API reference
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| App type not set to Native in Auth0 Dashboard | Create a Native application type in your Auth0 tenant. The Android SDK requires Native app configuration, not Machine-to-Machine or other types. |
-| Missing callback URL in Allowed Callback URLs | Add `{SCHEME}://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback` to your Auth0 application's Allowed Callback URLs setting, where `{SCHEME}` matches `com_auth0_scheme` in `strings.xml` (e.g., `demo` by default). |
-| Missing `<uses-permission android:name="android.permission.INTERNET" />` | Add the INTERNET permission to `AndroidManifest.xml`. The SDK requires network access for authentication. |
-| Custom scheme in lowercase | Android requires scheme names to be lowercase. Use `https` (recommended) or lowercase custom scheme like `myapp://callback`. |
-| Forgetting `.validateClaims()` on direct auth calls | Always call `.validateClaims()` when using `AuthenticationAPIClient` directly (for database, passwordless, or API login). Web Auth validates automatically. |
-| Storing tokens in SharedPreferences without encryption | Use `SecureCredentialsManager` to store credentials. Never store tokens manually in plain text. The manager encrypts tokens at rest. |
-| Missing manifest placeholders | Add `manifestPlaceholders = [auth0Domain: "@string/com_auth0_domain", auth0Scheme: "@string/com_auth0_scheme"]` to your `build.gradle` `defaultConfig` block. |
-
-## Related Skills
-
-- [auth0-quickstart](/auth0-quickstart) — Set up an Auth0 account and application
-- [auth0-mfa](/auth0-mfa) — Configure multi-factor authentication
-- [auth0-swift](/auth0-swift) — iOS/macOS authentication
-
-## Quick Reference
-
-### Core Classes
-
-| Class | Purpose |
-|-------|---------|
-| `Auth0` | Entry point for SDK, holds app credentials |
-| `WebAuthProvider` | OAuth 2.0 login/logout via browser |
-| `AuthenticationAPIClient` | Direct API calls (database login, passwordless, MFA) |
-| `SecureCredentialsManager` | Secure storage and retrieval of credentials |
-| `Credentials` | User tokens and expiration |
-
-### Common Use Cases
-
-- [Log in with Web Auth](references/integration.md#web-auth-login)
-- [Log out](references/integration.md#web-auth-logout)
-- [Store credentials securely](references/integration.md#credential-storage)
-- [Require biometric authentication](references/integration.md#biometric-protected-credentials)
-- [Database login](references/integration.md#database-login)
-- [Passwordless authentication](references/integration.md#passwordless-authentication)
-- [Handle MFA](references/integration.md#mfa-handling)
-- [Call protected APIs](references/integration.md#calling-protected-apis)
-
-## References
-
-- [Auth0 Android SDK Documentation](https://auth0.com/docs/libraries/auth0-android)
-- [Auth0 Android GitHub Repository](https://github.com/auth0/auth0-android)
-- [Android SDK Javadoc](https://auth0.com/docs/references/android)
-- [Auth0 Android Quickstart](https://auth0.com/docs/quickstart/native/android)
-- [Sample App](https://github.com/auth0-samples/auth0-android-sample)
diff --git a/main/.mintlify/skills/auth0-angular/SKILL.md b/main/.mintlify/skills/auth0-angular/SKILL.md
deleted file mode 100644
index 6d71fcdea1..0000000000
--- a/main/.mintlify/skills/auth0-angular/SKILL.md
+++ /dev/null
@@ -1,204 +0,0 @@
----
-name: auth0-angular
-description: Use when adding authentication to Angular applications with route guards and HTTP interceptors - integrates @auth0/auth0-angular SDK for SPAs
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 Angular Integration
-
-Add authentication to Angular applications using @auth0/auth0-angular.
-
----
-
-## Prerequisites
-
-- Angular 13+ application
-- Auth0 account and application configured
-- If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first
-
-## When NOT to Use
-
-- **AngularJS (1.x)** - This SDK requires Angular 13+, use legacy solutions for AngularJS
-- **Mobile applications** - Use `auth0-react-native` for React Native or native SDKs for Ionic
-- **Backend APIs** - Use JWT validation middleware for your server language
-
----
-
-## Quick Start Workflow
-
-### 1. Install SDK
-
-```bash
-npm install @auth0/auth0-angular
-```
-
-### 2. Configure Environment
-
-**For automated setup with Auth0 CLI**, see [Setup Guide](references/setup.md) for complete scripts.
-
-**For manual setup:**
-
-Update `src/environments/environment.ts`:
-
-```typescript
-export const environment = {
-  production: false,
-  auth0: {
-    domain: 'your-tenant.auth0.com',
-    clientId: 'your-client-id',
-    authorizationParams: {
-      redirect_uri: window.location.origin
-    }
-  }
-};
-```
-
-### 3. Configure Auth Module
-
-**For standalone components (Angular 14+):**
-
-Update `src/app/app.config.ts`:
-
-```typescript
-import { ApplicationConfig } from '@angular/core';
-import { provideAuth0 } from '@auth0/auth0-angular';
-import { environment } from '../environments/environment';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideAuth0({
-      domain: environment.auth0.domain,
-      clientId: environment.auth0.clientId,
-      authorizationParams: environment.auth0.authorizationParams
-    })
-  ]
-};
-```
-
-**For NgModule-based apps:**
-
-Update `src/app/app.module.ts`:
-
-```typescript
-import { AuthModule } from '@auth0/auth0-angular';
-import { environment } from '../environments/environment';
-
-@NgModule({
-  imports: [
-    AuthModule.forRoot({
-      domain: environment.auth0.domain,
-      clientId: environment.auth0.clientId,
-      authorizationParams: environment.auth0.authorizationParams
-    })
-  ]
-})
-export class AppModule {}
-```
-
-### 4. Add Authentication UI
-
-Update `src/app/app.component.ts`:
-
-```typescript
-import { Component } from '@angular/core';
-import { AuthService } from '@auth0/auth0-angular';
-
-@Component({
-  selector: 'app-root',
-  template: `
-    <div *ngIf="auth.isLoading$ | async; else loaded">
-      <p>Loading...</p>
-    </div>
-
-    <ng-template #loaded>
-      <ng-container *ngIf="auth.isAuthenticated$ | async; else loggedOut">
-        <div *ngIf="auth.user$ | async as user">
-          <img [src]="user.picture" [alt]="user.name" />
-          <h2>Welcome, {{ user.name }}!</h2>
-          <button (click)="logout()">Logout</button>
-        </div>
-      </ng-container>
-
-      <ng-template #loggedOut">
-        <button (click)="login()">Login</button>
-      </ng-template>
-    </ng-template>
-  `
-})
-export class AppComponent {
-  constructor(public auth: AuthService) {}
-
-  login(): void {
-    this.auth.loginWithRedirect();
-  }
-
-  logout(): void {
-    this.auth.logout({ logoutParams: { returnTo: window.location.origin } });
-  }
-}
-```
-
-### 5. Test Authentication
-
-Start your dev server and test the login flow:
-
-```bash
-ng serve
-```
-
----
-
-## Detailed Documentation
-
-- **[Setup Guide](references/setup.md)** - Automated setup scripts (Bash/PowerShell), CLI commands, manual configuration
-- **[Integration Guide](references/integration.md)** - Protected routes with guards, HTTP interceptors, error handling
-- **[API Reference](references/api.md)** - Complete SDK API, configuration options, services reference, testing strategies
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Forgot to add redirect URI in Auth0 Dashboard | Add your application URL (e.g., `http://localhost:4200`, `https://app.example.com`) to Allowed Callback URLs in Auth0 Dashboard |
-| Not configuring AuthModule properly | Must call `AuthModule.forRoot()` in NgModule or `provideAuth0()` in standalone config |
-| Accessing auth before initialization | Use `isLoading$` observable to wait for SDK initialization |
-| Storing tokens manually | Never manually store tokens - SDK handles secure storage automatically |
-| Missing HTTP interceptor | Use `authHttpInterceptorFn` or `AuthHttpInterceptor` to attach tokens to API calls |
-| Route guard not protecting routes | Apply `AuthGuard` (or `authGuardFn`) to protected routes in routing config |
-
----
-
-## Related Skills
-
-- `auth0-quickstart` - Basic Auth0 setup
-- `auth0-migration` - Migrate from another auth provider
-- `auth0-mfa` - Add Multi-Factor Authentication
-
----
-
-## Quick Reference
-
-**Core Services:**
-- `AuthService` - Main authentication service
-- `isAuthenticated$` - Observable check if user is logged in
-- `user$` - Observable user profile information
-- `loginWithRedirect()` - Initiate login
-- `logout()` - Log out user
-- `getAccessTokenSilently()` - Get access token for API calls
-
-**Common Use Cases:**
-- Login/Logout buttons → See Step 4 above
-- Protected routes with guards → [Integration Guide](references/integration.md#protected-routes)
-- HTTP interceptors for API calls → [Integration Guide](references/integration.md#http-interceptor)
-- Error handling → [Integration Guide](references/integration.md#error-handling)
-
----
-
-## References
-
-- [Auth0 Angular SDK Documentation](https://auth0.com/docs/libraries/auth0-angular)
-- [Auth0 Angular Quickstart](https://auth0.com/docs/quickstart/spa/angular)
-- [SDK GitHub Repository](https://github.com/auth0/auth0-angular)
diff --git a/main/.mintlify/skills/auth0-aspnetcore-api/SKILL.md b/main/.mintlify/skills/auth0-aspnetcore-api/SKILL.md
deleted file mode 100644
index 3a84b49086..0000000000
--- a/main/.mintlify/skills/auth0-aspnetcore-api/SKILL.md
+++ /dev/null
@@ -1,230 +0,0 @@
----
-name: auth0-aspnetcore-api
-description: "Use when securing ASP.NET Core Web API endpoints with JWT Bearer token validation, scope/permission checks, or stateless auth - integrates Auth0.AspNetCore.Authentication.Api for REST APIs receiving access tokens from frontends or mobile apps. Also handles DPoP proof-of-possession token binding. Triggers on: AddAuth0ApiAuthentication, .NET Web API auth, JWT validation, UseAuthentication, UseAuthorization."
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 ASP.NET Core Web API Integration
-
-Protect ASP.NET Core Web API endpoints with JWT access token validation using Auth0.AspNetCore.Authentication.Api.
-
----
-
-## Prerequisites
-
-- .NET 8.0 SDK or higher
-- Auth0 API configured (not Application - must be API resource)
-- If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first
-
-## When NOT to Use
-
-- **Server-rendered web applications** - Use session-based auth (Auth0.AspNetCore.Authentication) for MVC/Razor Pages apps
-- **Single Page Applications** - Use `auth0-react`, `auth0-vue`, or `auth0-angular` for client-side auth
-- **Mobile applications** - Use `auth0-react-native` for React Native/Expo
-- **Blazor WebAssembly** - Requires different auth approach (OIDC client-side)
-
----
-
-## Quick Start Workflow
-
-### 1. Install SDK
-
-```bash
-dotnet add package Auth0.AspNetCore.Authentication.Api
-```
-
-### 2. Create Auth0 API
-
-You need an **API** (not Application) in Auth0.
-
-> **STOP — ask the user before proceeding.**
->
-> Ask exactly this question and wait for their answer before doing anything else:
->
-> > "How would you like to create the Auth0 API resource?
-> > 1. **Automated** — I'll run Auth0 CLI scripts that create the resource and write the exact values to your appsettings.json automatically.
-> > 2. **Manual** — You create the API yourself in the Auth0 Dashboard (or via `auth0 apis create`) and provide me the Domain and Audience.
-> >
-> > Which do you prefer? (1 = Automated / 2 = Manual)"
->
-> Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.
-
-**If the user chose Automated**, follow the [Setup Guide](references/setup.md) for complete CLI scripts. The automated path writes `appsettings.json` for you — skip Step 3 below and proceed directly to Step 4.
-
-**If the user chose Manual**, follow the [Setup Guide](references/setup.md) (Manual Setup section) for full instructions including User Secrets and environment variable options. Then continue with Step 3 below.
-
-Quick reference for manual API creation:
-
-```bash
-# Using Auth0 CLI
-auth0 apis create \
-  --name "My ASP.NET Core API" \
-  --identifier https://my-api.example.com
-```
-
-Or create manually in Auth0 Dashboard → Applications → APIs
-
-### 3. Configure appsettings.json
-
-```json
-{
-  "Auth0": {
-    "Domain": "your-tenant.auth0.com",
-    "Audience": "https://my-api.example.com"
-  }
-}
-```
-
-**Important:** Domain must NOT include `https://`. The library constructs the authority URL automatically.
-
-### 4. Configure Program.cs
-
-```csharp
-var builder = WebApplication.CreateBuilder(args);
-
-// Register Auth0 JWT validation
-builder.Services.AddAuth0ApiAuthentication(options =>
-{
-    options.Domain = builder.Configuration["Auth0:Domain"];
-    options.JwtBearerOptions = new JwtBearerOptions
-    {
-        Audience = builder.Configuration["Auth0:Audience"]
-    };
-});
-
-builder.Services.AddAuthorization();
-
-var app = builder.Build();
-
-// Middleware order matters: authentication before authorization
-app.UseAuthentication();
-app.UseAuthorization();
-
-// Add your endpoints here (see Step 5)
-app.MapGet("/api/public", () => Results.Ok(new { message = "Public" }));
-
-app.Run();
-```
-
-### 5. Protect Endpoints
-
-**Minimal API:**
-
-```csharp
-// Public endpoint - no authentication
-app.MapGet("/api/public", () => Results.Ok(new { message = "Hello from a public endpoint!" }));
-
-// Protected endpoint - requires valid JWT
-app.MapGet("/api/private", (HttpContext ctx) =>
-{
-    var userId = ctx.User.FindFirst("sub")?.Value;
-    return Results.Ok(new { message = "Hello from a protected endpoint!", userId });
-}).RequireAuthorization();
-```
-
-**Controller-based:**
-
-```csharp
-[ApiController]
-[Route("api")]
-public class MessagesController : ControllerBase
-{
-    [HttpGet("public")]
-    public IActionResult Public() =>
-        Ok(new { message = "Hello from a public endpoint!" });
-
-    [Authorize]
-    [HttpGet("private")]
-    public IActionResult Private() =>
-        Ok(new { message = "Hello from a protected endpoint!", userId = User.FindFirst("sub")?.Value });
-}
-```
-
-### 6. Test API
-
-Test public endpoint:
-
-```bash
-curl http://localhost:5000/api/public
-```
-
-Test protected endpoint (requires access token):
-
-```bash
-curl http://localhost:5000/api/private \
-  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
-```
-
-Get a test token via Client Credentials flow or Auth0 Dashboard → APIs → Test tab.
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Domain includes `https://` | Use `your-tenant.auth0.com` format only - no scheme prefix |
-| Audience doesn't match API Identifier | Must exactly match the API Identifier set in Auth0 Dashboard |
-| Created Application instead of API in Auth0 | Must create API resource in Auth0 Dashboard → Applications → APIs |
-| Wrong middleware order | `UseAuthentication()` must come before `UseAuthorization()` |
-| Using ID token instead of access token | Must use **access token** for API auth, not ID token |
-| HTTPS certificate errors locally | Run `dotnet dev-certs https --trust` |
-
----
-
-## Scope-Based Authorization
-
-See [Integration Guide](references/integration.md#scope-based-authorization) for defining and enforcing scope policies.
-
----
-
-## DPoP Support
-
-Built-in proof-of-possession token binding per RFC 9449. See [Integration Guide](references/integration.md#dpop-support) for configuration.
-
----
-
-## Related Skills
-
-- `auth0-quickstart` - Basic Auth0 setup
-- `auth0-mfa` - Add Multi-Factor Authentication
-
----
-
-## Quick Reference
-
-**Configuration Options:**
-- `options.Domain` - Auth0 tenant domain, no `https://` prefix (required)
-- `options.JwtBearerOptions.Audience` - API Identifier from Auth0 API settings (required)
-- `options.JwtBearerOptions` - Full access to underlying Microsoft JWT Bearer options
-
-**User Claims:**
-- `ctx.User.FindFirst("sub")?.Value` - User ID (subject)
-- `ctx.User.FindFirst("scope")?.Value` - Space-separated scopes
-- `ctx.User.FindAll("scope")` - All scope claims
-
-**Common Use Cases:**
-- Protect Minimal API routes → `.RequireAuthorization()` (see Step 5)
-- Protect controller actions → `[Authorize]` attribute (see Step 5)
-- Scope enforcement → [Integration Guide](references/integration.md#scope-based-authorization)
-- DPoP token binding → [Integration Guide](references/integration.md#dpop-support)
-- Advanced JWT Bearer config → [API Reference](references/api.md)
-
----
-
-## Detailed Documentation
-
-- **[Setup Guide](references/setup.md)** - Auth0 CLI setup, environment configuration
-- **[Integration Guide](references/integration.md)** - Scope policies, DPoP, controller patterns, error handling
-- **[API Reference](references/api.md)** - Complete configuration options and extension methods
-
----
-
-## References
-
-- [Auth0 ASP.NET Core Web API Quickstart](https://auth0.com/docs/quickstart/backend/aspnet-core-webapi)
-- [SDK GitHub Repository](https://github.com/auth0/aspnetcore-api)
-- [API Documentation](https://auth0.github.io/aspnetcore-api)
-- [Access Tokens Guide](https://auth0.com/docs/secure/tokens/access-tokens)
diff --git a/main/.mintlify/skills/auth0-cli/references/cli.md b/main/.mintlify/skills/auth0-cli/references/cli.md
deleted file mode 100644
index b5d30d4b1c..0000000000
--- a/main/.mintlify/skills/auth0-cli/references/cli.md
+++ /dev/null
@@ -1,964 +0,0 @@
-# Auth0 CLI — Full Command Reference
-
-Detailed flags, examples, and usage patterns for every Auth0 CLI command. All examples use `--json` or `--json-compact` output format for machine-readable results.
-
----
-
-## Table of Contents
-
-- [Authentication](#authentication)
-- [Apps](#apps)
-- [APIs](#apis)
-- [Users](#users)
-- [Roles](#roles)
-- [Organizations](#organizations)
-- [Actions](#actions)
-- [Logs](#logs)
-- [Domains](#domains)
-- [Universal Login](#universal-login)
-- [Terraform](#terraform)
-- [Test](#test)
-- [Quickstarts](#quickstarts)
-- [Attack Protection](#attack-protection)
-- [Log Streams](#log-streams)
-- [IPs](#ips)
-- [Raw API Mode](#raw-api-mode)
-- [Output Formatting](#output-formatting)
-- [Shared Flags](#shared-flags)
-
----
-
-## Authentication
-
-Every CLI session requires an active login.
-
-```bash
-# Interactive device-code login (default for personal use)
-auth0 login
-
-# Request extra Management API scopes (needed if commands fail with 403)
-auth0 login --scopes "read:client_grants,create:client_grants"
-
-# Machine login with client secret (CI/CD, non-interactive)
-auth0 login --domain <tenant>.auth0.com --client-id <id> --client-secret <secret>
-
-# Machine login with private key JWT
-auth0 login --domain <tenant>.auth0.com --client-id <id> \
-  --client-assertion-signing-alg RS256 \
-  --client-assertion-private-key <key-or-path>
-```
-
-| Flag | Description |
-|------|-------------|
-| `--domain` | Tenant domain (required for machine login) |
-| `--client-id` | Application client ID (for machine login) |
-| `--client-secret` | Application client secret (for secret-based machine login) |
-| `--client-assertion-signing-alg` | Signing algorithm: RS256, RS384, PS256 (for JWT machine login) |
-| `--client-assertion-private-key` | Private key content or file path (for JWT machine login) |
-| `--scopes` | Additional Management API scopes to request during user login |
-
-Three authentication modes:
-1. **User login** (device code flow) — no credentials needed, opens browser. Default for personal machines.
-2. **Machine login with secret** — requires `--domain`, `--client-id`, `--client-secret`. For CI/CD.
-3. **Machine login with JWT** — requires `--domain`, `--client-id`, `--client-assertion-signing-alg`, `--client-assertion-private-key`. For Private Cloud or high-security environments.
-
-Always run `auth0 login` at the start of any workflow. If commands later fail with 403/insufficient scope, re-login with `--scopes` to add the missing scope.
-
-### Tenant management
-
-```bash
-auth0 tenants list        # list all authenticated tenants
-auth0 tenants use         # switch active tenant (interactive)
-auth0 tenants open        # open tenant settings in browser
-```
-
-### Logout
-
-```bash
-auth0 logout              # interactive tenant selection
-auth0 logout <tenant>     # logout specific tenant
-```
-
----
-
-## Apps
-
-Manage Auth0 applications — the entity that holds your client ID, client secret, callback URLs, and app type.
-
-**Alias:** `auth0 clients`
-
-### apps list
-
-```bash
-auth0 apps list --json
-auth0 apps list --reveal-secrets --number 100 --json-compact
-```
-
-| Flag | Short | Default | Description |
-|------|-------|---------|-------------|
-| `--number` | `-n` | 100 | Number of apps to retrieve (1–1000) |
-| `--reveal-secrets` | `-r` | false | Show client secret and signing keys in output |
-| `--json` | | false | JSON output |
-| `--json-compact` | | false | Compact JSON output |
-| `--csv` | | false | CSV output |
-
-### apps show
-
-```bash
-auth0 apps show <client-id> --json
-auth0 apps show <client-id> --reveal-secrets --json-compact
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--reveal-secrets` | `-r` | Show client secret and signing keys |
-| `--json` | | JSON output |
-| `--json-compact` | | Compact JSON output |
-
-### apps create
-
-```bash
-# SPA (React, Vue, Angular — browser-only, no backend)
-auth0 apps create --name "My SPA" --type spa \
-  --callbacks "http://localhost:3000" \
-  --logout-urls "http://localhost:3000" \
-  --origins "http://localhost:3000" \
-  --web-origins "http://localhost:3000" \
-  --json
-
-# Regular web app (Next.js, Express, server-rendered)
-auth0 apps create --name "My Web App" --type regular \
-  --callbacks "http://localhost:3000/api/auth/callback" \
-  --logout-urls "http://localhost:3000" \
-  --json
-
-# Machine-to-Machine (backend service, cron job, CLI tool)
-auth0 apps create --name "My API Service" --type m2m --json
-
-# Native (iOS, Android, React Native)
-auth0 apps create --name "My Mobile App" --type native --json
-
-# Resource Server (API + client in one entity)
-auth0 apps create --name "My API Client" --type resource_server \
-  --resource-server-identifier "https://api.example.com" \
-  --json
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--name` | `-n` | **Required.** Application name |
-| `--type` | `-t` | **Required.** One of: `native`, `spa`, `regular`, `m2m`, `resource_server` |
-| `--description` | `-d` | Description (max 140 chars) |
-| `--callbacks` | `-c` | Comma-separated callback URLs. Must include protocol (https://). |
-| `--origins` | `-o` | Allowed CORS origin URLs. Supports subdomain wildcards (e.g., `https://*.contoso.com`). |
-| `--web-origins` | `-w` | Allowed web origins for Cross-Origin Auth, Device Flow, and web message response mode |
-| `--logout-urls` | `-l` | Allowed logout redirect URLs. Supports subdomain wildcards. |
-| `--auth-method` | `-a` | Token endpoint auth: `None` (public app), `Post` (HTTP POST), or `Basic` (HTTP Basic) |
-| `--grants` | `-g` | Grant types: code, implicit, refresh-token, credentials, password, password-realm, mfa-oob, mfa-otp, mfa-recovery-code, device-code |
-| `--metadata` | | Key-value pairs (max 255 chars each). Repeatable: `--metadata "foo=bar" --metadata "baz=qux"` or comma-separated: `--metadata "foo=bar,baz=qux"` |
-| `--resource-server-identifier` | | API identifier (only for `resource_server` type, cannot be changed after creation) |
-| `--refresh-token` | `-z` | Refresh token config as JSON |
-| `--reveal-secrets` | `-r` | Show secrets in output |
-| `--json` | | JSON output |
-
-### apps update
-
-```bash
-auth0 apps update <client-id> --name "New Name" --json
-auth0 apps update <client-id> --callbacks "http://localhost:3000,https://myapp.com" --json
-```
-
-Same flags as `create` (except `--type` and `--resource-server-identifier` cannot change app type after creation).
-
-### apps delete
-
-```bash
-auth0 apps delete <client-id>
-auth0 apps delete <client-id> --force          # skip confirmation
-auth0 apps delete <id1> <id2> <id3> --force    # batch delete
-```
-
-### apps open / use
-
-```bash
-auth0 apps open <client-id>     # opens settings in Auth0 Dashboard
-auth0 apps use <client-id>      # set as default app for CLI session
-auth0 apps use --none            # clear default app
-```
-
-### apps session-transfer
-
-Manage session transfer settings for native-to-web app transitions.
-
-```bash
-auth0 apps session-transfer show <client-id> --json
-auth0 apps session-transfer update <client-id> \
-  --can-create-token \
-  --allowed-auth-methods cookie,query \
-  --enforce-device-binding ip \
-  --json
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--can-create-token` | `-t` | Allow creation of session transfer tokens |
-| `--allowed-auth-methods` | `-m` | Auth methods: cookie, query |
-| `--enforce-device-binding` | `-e` | Device binding: none, ip, or asn |
-
----
-
-## APIs
-
-Manage Auth0 API resources (Resource Servers). Register these when you want to protect a backend API with Auth0 tokens.
-
-**Key distinction:** `apps` = the client requesting tokens. `apis` = the resource accepting tokens.
-
-**Alias:** `auth0 resource-servers`
-
-### apis list
-
-```bash
-auth0 apis list --json
-auth0 apis list --number 50 --json-compact
-```
-
-| Flag | Short | Default | Description |
-|------|-------|---------|-------------|
-| `--number` | `-n` | 100 | Number of APIs to retrieve (1–1000) |
-| `--json` / `--json-compact` / `--csv` | | | Output format |
-
-### apis show
-
-```bash
-auth0 apis show <api-id|api-audience> --json
-auth0 apis show <api-id|api-audience> --json-compact
-```
-
-Note: accepts either the API ID or the audience identifier.
-
-### apis create
-
-```bash
-auth0 apis create --name "My Backend API" --identifier "https://api.myapp.com" --json
-auth0 apis create --name "My API" --identifier "https://api.myapp.com" \
-  --scopes "read:data,write:data" \
-  --token-lifetime 3600 \
-  --offline-access \
-  --json
-```
-
-| Flag | Short | Default | Description |
-|------|-------|---------|-------------|
-| `--name` | `-n` | | **Required.** API name |
-| `--identifier` | `-i` | | **Required.** Unique audience URI. Cannot be changed after creation. |
-| `--scopes` | `-s` | | Comma-separated list of scopes (permissions) |
-| `--token-lifetime` | `-l` | 86400 | Access token validity in seconds (default: 1 day) |
-| `--offline-access` | `-o` | false | Allow issuing refresh tokens |
-| `--signing-alg` | | RS256 | Signing algorithm: HS256, RS256. PS256 via addon. |
-| `--subject-type-authorization` | | | JSON access policies for user/client flows. E.g., `'{"user":{"policy":"require_client_grant"},"client":{"policy":"deny_all"}}'` |
-| `--json` / `--json-compact` | | | Output format |
-
-The `--identifier` becomes the `audience` parameter in token requests. Use a URL format by convention, but it doesn't need to resolve to a real endpoint.
-
-### apis update
-
-```bash
-auth0 apis update <api-id|api-audience> --name "New Name" --scopes "read:data,write:data,delete:data" --json
-```
-
-Same flags as `create` except `--identifier` cannot be changed.
-
-### apis delete
-
-```bash
-auth0 apis delete <api-id|api-audience>
-auth0 apis delete <id1> <id2> --force    # batch delete
-```
-
-### apis scopes list
-
-```bash
-auth0 apis scopes list <api-id|api-audience> --json
-auth0 apis scopes list <api-id|api-audience> --json-compact
-```
-
-Lists the scopes defined on an API. To update scopes, use `auth0 apis update <id> --scopes "..."`.
-
-### apis open
-
-```bash
-auth0 apis open <api-id|api-audience>    # opens settings in dashboard
-```
-
----
-
-## Users
-
-Create, search, inspect, or manage users in your tenant.
-
-### users search
-
-```bash
-auth0 users search --query "email:user@example.com" --json
-auth0 users search --query "email:*@mycompany.com" --sort "created_at:-1" --number 10 --json-compact
-auth0 users search --query 'app_metadata.role:"admin"' --json-compact
-```
-
-| Flag | Short | Default | Description |
-|------|-------|---------|-------------|
-| `--query` | `-q` | | **Required.** Lucene query syntax. E.g., `email:"user@*.com" OR (user_id:"user-id-123" AND name:"Bob")` |
-| `--sort` | `-s` | | Sort field and order. Use `field:1` for ascending, `field:-1` for descending. E.g., `created_at:-1` |
-| `--number` | `-n` | 50 | Number of users to retrieve (1–1000) |
-| `--picker` | `-p` | false | Interactive picker to view user details |
-| `--json` / `--json-compact` / `--csv` | | | Output format |
-
-### users search-by-email
-
-```bash
-auth0 users search-by-email <email> --json
-auth0 users search-by-email user@example.com --json-compact
-```
-
-Simpler alternative to `search` when you just need an exact email match.
-
-### users create
-
-```bash
-auth0 users create \
-  --connection-name "Username-Password-Authentication" \
-  --email "testuser@example.com" \
-  --password "SecureP@ss123!" \
-  --name "Test User" \
-  --json
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--connection-name` | `-c` | **Required.** Database connection name |
-| `--email` | `-e` | User email |
-| `--password` | `-p` | Initial password (mandatory for non-SMS connections) |
-| `--name` | `-n` | Full name |
-| `--username` | `-u` | Username (only if the connection requires it) |
-| `--phone-number` | `-m` | Phone number |
-| `--json` / `--json-compact` | | Output format |
-
-`Username-Password-Authentication` is the default database connection name unless your tenant has a custom one.
-
-### users show
-
-```bash
-auth0 users show <user-id> --json
-```
-
-User IDs follow the format `auth0|<id>` for database users, `google-oauth2|<id>` for Google, etc. Shows warning if user is blocked.
-
-### users update
-
-```bash
-auth0 users update <user-id> --name "Updated Name" --json
-auth0 users update <user-id> --email "new@example.com" --blocked false --json
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--connection-name` | `-c` | Database connection name |
-| `--name` | `-n` | Full name |
-| `--email` | `-e` | Email |
-| `--username` | `-u` | Username |
-| `--password` | `-p` | Password |
-| `--phone-number` | `-m` | Phone number |
-| `--blocked` | `-b` | Block/unblock user authentication |
-| `--json` / `--json-compact` | | Output format |
-
-### users delete
-
-```bash
-auth0 users delete <user-id>
-auth0 users delete <id1> <id2> <id3> --force    # batch delete
-```
-
-### users import
-
-Bulk import users. File size limit is 500KB per job — start multiple imports for larger datasets.
-
-```bash
-auth0 users import \
-  --connection-name "Username-Password-Authentication" \
-  --template "Basic Example" \
-  --upsert \
-  --json
-
-auth0 users import \
-  --connection-name "Username-Password-Authentication" \
-  --users '[{"email":"user1@example.com","password":"pass1"}]' \
-  --json
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--connection-name` | `-c` | **Required.** Database connection name |
-| `--template` | `-t` | JSON template: `Empty`, `Basic Example`, `Custom Password Hash Example`, `MFA Factors Example` |
-| `--users` | `-u` | JSON array of users (mutually exclusive with `--template`) |
-| `--upsert` | | When true, updates pre-existing users that match on email |
-| `--email-results` | | Send completion email to tenant owners (default: true) |
-
-### users blocks
-
-Manage brute-force protection blocks. Use when a user reports being locked out.
-
-```bash
-auth0 users blocks list <user-id-or-email> --json              # list blocks
-auth0 users blocks list user@example.com --json-compact
-auth0 users blocks unblock <user-id-or-email>                  # remove blocks
-auth0 users blocks unblock user1@example.com user2@example.com # batch unblock
-```
-
-Accepts user ID, username, email, or phone number as identifier.
-
-### users roles
-
-Manage a user's role assignments. For RBAC (Role-Based Access Control).
-
-```bash
-auth0 users roles show <user-id> --json                            # list assigned roles
-auth0 users roles show <user-id> --json-compact                    # compact JSON output
-auth0 users roles assign <user-id> --roles <role-id1>,<role-id2>   # assign roles
-auth0 users roles remove <user-id> --roles <role-id>               # remove roles
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--roles` | `-r` | **Required.** Comma-separated role IDs |
-| `--number` | `-n` | Number of roles to retrieve (for `show`) |
-
-### users open
-
-```bash
-auth0 users open <user-id>    # opens user settings in dashboard
-```
-
----
-
-## Roles
-
-Create roles and manage permissions for RBAC (Role-Based Access Control). Roles are containers for permissions — you assign permissions to roles, then assign roles to users.
-
-### roles list / show / create / update / delete
-
-```bash
-auth0 roles list --json
-auth0 roles list --json-compact
-
-auth0 roles show <role-id> --json
-auth0 roles show <role-id> --json-compact
-
-auth0 roles create --name "admin" --description "Full admin access" --json
-auth0 roles create --name "editor" --description "Can edit content" --json-compact
-
-auth0 roles update <role-id> --name "super-admin" --description "Updated description" --json
-
-auth0 roles delete <role-id>
-auth0 roles delete <role-id> --force
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--name` | `-n` | **Required (create).** Role name |
-| `--description` | `-d` | **Required (create).** Role description |
-| `--number` | `-n` | Number of roles to retrieve (for `list`, default 100) |
-| `--json` / `--json-compact` / `--csv` | | Output format |
-| `--force` | | Skip confirmation (for `delete`) |
-
-### roles permissions
-
-Add or remove API permissions (scopes) from a role.
-
-```bash
-auth0 roles permissions list <role-id> --json
-auth0 roles permissions list <role-id> --json-compact
-
-auth0 roles permissions add <role-id> \
-  --api-id <api-id> \
-  --permissions "read:data,write:data" \
-  --json
-
-auth0 roles permissions remove <role-id> \
-  --api-id <api-id> \
-  --permissions "write:data" \
-  --json
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--api-id` | `-a` | **Required.** API (resource server) ID |
-| `--permissions` | `-p` | **Required.** Comma-separated permissions to add/remove |
-
-**Typical RBAC workflow:**
-```bash
-# 1. Create a role
-auth0 roles create --name "editor" --description "Content editors" --json
-# 2. Add API permissions to the role
-auth0 roles permissions add <role-id> --api-id <api-id> --permissions "read:articles,write:articles" --json
-# 3. Assign role to a user
-auth0 users roles assign <user-id> --roles <role-id>
-# 4. Verify role assignment
-auth0 users roles show <user-id> --json-compact
-```
-
----
-
-## Organizations
-
-B2B / multi-tenant scenarios where your customers are companies, each with their own set of users, connections, and branding.
-
-**Alias:** `auth0 orgs`
-
-### organizations list / show / create / update / delete
-
-```bash
-auth0 orgs list --json
-auth0 orgs show <org-id> --json
-
-auth0 orgs create --name "acme-corp" --display "Acme Corporation" \
-  --logo "https://acme.com/logo.png" \
-  --accent "#FF6600" --background "#FFFFFF" \
-  --json
-
-auth0 orgs update <org-id> --display "Acme Corp Inc." --accent "#0066FF" --json
-
-auth0 orgs delete <org-id> --force
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--name` | `-n` | **Required (create).** Organization name (URL-safe slug) |
-| `--display` | `-d` | Display name shown in UI |
-| `--logo` | `-l` | Logo URL |
-| `--accent` | `-a` | Accent color (hex) for organization branding |
-| `--background` | `-b` | Background color (hex) |
-| `--metadata` | `-m` | Key-value metadata |
-
-### organizations members / roles / invitations
-
-```bash
-# Members
-auth0 orgs members list <org-id> --json
-
-# Roles within an organization
-auth0 orgs roles list <org-id> --json
-auth0 orgs roles members list <org-id> --role-id <role-id> --json
-
-# Invitations
-auth0 orgs invitations list --org-id <org-id> --json
-auth0 orgs invitations show --org-id <org-id> --invitation-id <id> --json
-auth0 orgs invitations create --org-id <org-id> \
-  --inviter-name "Admin" \
-  --invitee-email "new@acme.com" \
-  --client-id <app-client-id> \
-  --roles <role-id1>,<role-id2> \
-  --json
-auth0 orgs invitations delete --org-id <org-id> --invitation-id <id> --force
-```
-
----
-
-## Actions
-
-Create and deploy serverless functions that run at specific points in the Auth0 pipeline (login, registration, M2M token exchange, etc.). Actions replaced the deprecated Rules system.
-
-### actions list / show / create / update / delete / deploy
-
-```bash
-auth0 actions list --json
-
-auth0 actions show <action-id> --json
-
-auth0 actions create \
-  --name "Add Custom Claims" \
-  --trigger "post-login" \
-  --code 'exports.onExecutePostLogin = async (event, api) => { api.accessToken.setCustomClaim("role", event.user.app_metadata.role); }' \
-  --json
-
-auth0 actions update <action-id> \
-  --name "Add Custom Claims v2" \
-  --code 'exports.onExecutePostLogin = async (event, api) => { /* updated */ }' \
-  --json
-
-auth0 actions deploy <action-id>    # deploy a draft action
-
-auth0 actions delete <action-id> --force
-
-auth0 actions open <action-id>      # open in dashboard
-auth0 actions diff <action-id>      # diff between versions (interactive)
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--name` | `-n` | Action name |
-| `--trigger` | `-t` | **Required (create).** Trigger: `post-login`, `credentials-exchange`, `pre-user-registration`, `post-user-registration`, `post-change-password`, `send-phone-message` |
-| `--code` | `-c` | **Required (create).** JavaScript code for the action |
-| `--dependency` | `-d` | npm dependencies (repeatable, format: `name@version`) |
-| `--secret` | `-s` | Secrets (repeatable, format: `KEY=value`) |
-| `--runtime` | `-r` | Node.js runtime version |
-| `--force` | | Skip confirmation (for `update`/`delete`) |
-| `--json` / `--json-compact` | | Output format |
-
-**Important:** After creating or updating an action, you must `deploy` it for the changes to take effect in live traffic.
-
----
-
-## Logs
-
-When something breaks in an auth flow, `logs tail` is your first debugging tool — faster than opening the dashboard. It shows live events from your tenant.
-
-### logs tail
-
-```bash
-auth0 logs tail --json
-auth0 logs tail --filter "type:f" --json-compact     # failed logins only
-auth0 logs tail --filter "type:s" --json-compact     # successful logins only
-auth0 logs tail --filter "type:fp" --json-compact    # failed password changes
-```
-
-| Flag | Short | Default | Description |
-|------|-------|---------|-------------|
-| `--filter` | `-f` | | Lucene query syntax. See [query syntax docs](https://auth0.com/docs/logs/log-search-query-syntax). |
-| `--number` | `-n` | 50 | Number of log entries to show (1–1000) |
-
-Polls every 2 seconds and deduplicates events.
-
-### logs list
-
-```bash
-auth0 logs list --json
-auth0 logs list --filter "type:f" --number 20 --json-compact
-```
-
-| Flag | Short | Default | Description |
-|------|-------|---------|-------------|
-| `--filter` | `-f` | | Lucene query syntax filter |
-| `--number` | `-n` | 50 | Number of entries (1–1000) |
-| `--picker` | `-p` | false | Interactive picker to view log details |
-| `--json` / `--json-compact` / `--csv` | | | Output format |
-
-### Common log type codes
-
-| Code | Event | When to look for it |
-|------|-------|---------------------|
-| `s` | Success login | Confirm a login completed |
-| `f` | Failed login | Wrong password, locked account, blocked IP |
-| `slo` | Success logout | Confirm logout flow worked |
-| `ss` | Silent auth success | SPA token renewal succeeded |
-| `fs` | Silent auth failure | SPA token renewal failed — user sees login prompt |
-| `fp` | Failed password change | Password change issues |
-| `sce` | Success change email | Email update completed |
-
----
-
-## Domains
-
-Configure custom domains on your Auth0 tenant. Custom domains replace `<tenant>.auth0.com` with your own branded domain (e.g., `auth.myapp.com`).
-
-```bash
-auth0 domains list --json
-
-auth0 domains show <domain-id> --json
-
-auth0 domains create --domain "auth.myapp.com" --type "auth0_managed_certs" --json
-
-auth0 domains verify <domain-id> --json    # verify DNS configuration
-
-auth0 domains delete <domain-id> --force
-
-auth0 domains default show --json           # show the default custom domain
-auth0 domains default set --domain <id>     # set the default
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--domain` | `-d` | **Required (create).** The custom domain (e.g., `auth.myapp.com`) |
-| `--type` | `-t` | Domain type (e.g., `auth0_managed_certs`, `self_managed_certs`) |
-| `--policy` | `-p` | TLS policy |
-| `--ip-header` | `-i` | Custom IP header for proxy setups |
-
----
-
-## Universal Login
-
-Configure and brand your Auth0 Universal Login page — the hosted login page users see.
-
-**Alias:** `auth0 ul`
-
-```bash
-auth0 ul show --json                # show current UL configuration
-
-auth0 ul update \
-  --accent "#FF6600" \
-  --background "#FFFFFF" \
-  --logo "https://myapp.com/logo.png" \
-  --favicon "https://myapp.com/favicon.ico" \
-  --font "https://fonts.googleapis.com/css2?family=Inter" \
-  --json
-
-auth0 ul customize                  # set rendering mode (new/classic/advanced)
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--accent` | `-a` | Accent color (hex) for buttons and links |
-| `--background` | `-b` | Background color (hex) |
-| `--logo` | `-l` | Logo URL |
-| `--favicon` | `-f` | Favicon URL |
-| `--font` | `-c` | Font URL (Google Fonts or custom) |
-
-### universal-login templates
-
-```bash
-auth0 ul templates show             # show current custom HTML template
-auth0 ul templates update           # update the custom HTML template
-```
-
-### universal-login prompts (custom text)
-
-Customize the text shown on login prompts for each language.
-
-```bash
-auth0 ul prompts show <prompt> --language <lang> --json
-auth0 ul prompts update <prompt> --language <lang> --text '{...}' --json
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--language` | `-l` | Language code (e.g., `en`, `es`, `fr`) |
-| `--text` | `-t` | JSON object with custom text keys |
-
----
-
-## Terraform
-
-Export your current Auth0 tenant configuration as Terraform HCL — useful for infrastructure as code, environment replication, or migrating to Terraform management.
-
-```bash
-auth0 terraform generate
-auth0 terraform generate --output-dir ./terraform
-auth0 terraform generate --output-dir ./terraform --resources "auth0_client,auth0_connection"
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--output-dir` | `-o` | Directory to write Terraform files |
-| `--resources` | `-r` | Comma-separated list of resource types to export (defaults to all) |
-| `--tf-version` | `-v` | Terraform provider version |
-
----
-
-## Test
-
-Quickly verify that authentication works for a specific application without building a UI. Opens a browser to run the actual login flow.
-
-```bash
-auth0 test login <client-id>
-auth0 test login <client-id> --connection-name "google-oauth2"
-auth0 test login <client-id> --audience "https://api.myapp.com" --scopes "openid profile email"
-auth0 test login <client-id> --organization "org_123abc"
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--connection-name` | `-c` | Specific connection to use (e.g., `google-oauth2`, `Username-Password-Authentication`) |
-| `--audience` | `-a` | API audience to request in the token |
-| `--scopes` | `-s` | Scopes to request |
-| `--domain` | `-d` | Custom domain to use |
-| `--organization` | `-o` | Organization ID or name |
-| `--params` | `-p` | Additional authorization parameters |
-
-After creating an app or configuring a connection, use `auth0 test login` to verify the flow works end-to-end before integrating into your application code.
-
----
-
-## Quickstarts
-
-Get working sample applications for your framework/language.
-
-```bash
-auth0 quickstarts list --json            # list available quickstarts
-auth0 quickstarts download               # download a quickstart (interactive)
-auth0 quickstarts setup                  # download and configure with your app credentials
-```
-
-**Alias:** `auth0 qs`
-
----
-
-## Attack Protection
-
-Manage Auth0's built-in attack protection features.
-
-**Alias:** `auth0 ap`
-
-```bash
-# Brute-force protection
-auth0 protection brute-force-protection show --json
-auth0 protection brute-force-protection update --enabled true
-
-# Breached password detection
-auth0 protection breached-password-detection show --json
-auth0 protection breached-password-detection update --enabled true
-
-# Suspicious IP throttling
-auth0 protection suspicious-ip-throttling show --json
-auth0 protection suspicious-ip-throttling update --enabled true
-
-# Bot detection
-auth0 protection bot-detection show --json
-auth0 protection bot-detection update --enabled true
-
-# Check/unblock IPs (under suspicious-ip-throttling)
-auth0 protection suspicious-ip-throttling ips check <ip>
-auth0 protection suspicious-ip-throttling ips unblock <ip>
-```
-
----
-
-## Log Streams
-
-Send Auth0 tenant logs to external services for monitoring, alerting, or long-term storage.
-
-```bash
-auth0 logs streams list --json
-auth0 logs streams show <stream-id> --json
-auth0 logs streams delete <stream-id> --force
-```
-
-Supported stream types (each has its own `create`/`update` sub-command):
-- **eventbridge** — AWS EventBridge
-- **eventgrid** — Azure Event Grid
-- **http** — Custom webhook
-- **datadog** — Datadog
-- **splunk** — Splunk
-- **sumo** — Sumo Logic
-
-```bash
-auth0 logs streams create http     # interactive setup for webhook stream
-auth0 logs streams create datadog  # interactive setup for Datadog
-```
-
----
-
-## IPs
-
-```bash
-auth0 ips check <ip-address>      # check if an IP is blocked
-auth0 ips unblock <ip-address>    # unblock an IP
-```
-
----
-
-## Raw API Mode
-
-When a dedicated command doesn't exist for what you need, `auth0 api` lets you call any [Auth0 Management API v2](https://auth0.com/docs/api/management/v2) endpoint directly with your tenant credentials already handled. Think of it as `curl` for the Management API — but without managing tokens.
-
-```bash
-auth0 api <method> <url-path> [flags]
-```
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--data` | `-d` | JSON payload for POST/PATCH/PUT requests. Can also pipe via stdin. |
-| `--query` | `-q` | Query parameters (repeatable: `-q "page=0" -q "per_page=5"`) |
-| `--force` | | Skip confirmation on DELETE requests |
-
-**Method defaults:** GET when no `--data` is provided, POST when `--data` is provided. You can explicitly set the method as the first argument.
-
-The `<url-path>` is relative to `/api/v2/` — do NOT include the full URL. E.g., `tenants/settings`, not `https://tenant.auth0.com/api/v2/tenants/settings`.
-
-**Examples:**
-
-```bash
-# Connections (no dedicated CLI command for full CRUD)
-auth0 api get connections
-auth0 api get connections/<connection-id>
-
-# Client grants
-auth0 api get client-grants
-auth0 api post client-grants --data '{"client_id":"...","audience":"...","scope":["read:data"]}'
-
-# Tenant settings
-auth0 api get tenants/settings
-
-# Daily stats
-auth0 api get stats/daily -q "from=20240101" -q "to=20240131"
-
-# Paginate results
-auth0 api get clients -q "page=0" -q "per_page=10"
-
-# Pipe JSON from file
-cat config.json | auth0 api post clients
-
-# Hooks (deprecated but still accessible)
-auth0 api get hooks
-```
-
-**Scope errors:** If a call fails with 403 / insufficient_scope, re-login with the missing scope: `auth0 login --scopes "read:client_grants"`.
-
----
-
-## Output Formatting
-
-Append `--json` to any list/show/create/update command to get machine-readable JSON. Three modes (mutually exclusive):
-
-| Flag | Description |
-|------|-------------|
-| `--json` | Pretty-printed JSON with indentation |
-| `--json-compact` | Compact single-line JSON (useful for piping to jq) |
-| `--csv` | CSV format (for spreadsheets) |
-
-**Use `--json` when:**
-- Debugging and you want the full raw response with readable indentation
-- Inspecting a single resource in detail
-
-**Use `--json-compact` when:**
-- Piping to `jq` — compact output avoids whitespace overhead
-- Scripting or automating CLI calls where each record should be one line
-- Chaining commands in a pipeline
-
-```bash
-# Pretty-printed JSON for human inspection
-auth0 apps show <client-id> --json
-
-# Compact JSON piped to jq — preferred for scripting
-auth0 apps list --json-compact | jq '.[] | {client_id, name}'
-
-# Extract a user's email and ID
-auth0 users show <user-id> --json-compact | jq '{id: .user_id, email: .email}'
-
-# Get all API identifiers
-auth0 apis list --json-compact | jq '.[].identifier'
-
-# Search users and pipe to jq
-auth0 users search --query "email:*@mycompany.com" --json-compact | jq '.[].user_id'
-
-# Tail logs as compact JSON for aggregation
-auth0 logs tail --json-compact
-
-# List roles as compact JSON
-auth0 roles list --json-compact | jq '.[].name'
-
-# CSV output for spreadsheets
-auth0 apps list --csv > apps.csv
-```
-
-The default text output is for human reading only — it truncates long values and uses ANSI colors that break parsing. Always use `--json` or `--json-compact` when you need to extract values programmatically. Prefer `--json-compact` when piping to `jq` or other tools.
-
----
-
-## Shared Flags
-
-These flags are available across most commands:
-
-| Flag | Description |
-|------|-------------|
-| `--tenant` | Target a specific tenant (overrides active tenant) |
-| `--no-input` | Disable all interactive prompts (for scripting) |
-| `--no-color` | Disable colored output |
-| `--debug` | Enable debug mode (verbose HTTP logging) |
diff --git a/main/.mintlify/skills/auth0-expo/SKILL.md b/main/.mintlify/skills/auth0-expo/SKILL.md
deleted file mode 100644
index e89e4d49b4..0000000000
--- a/main/.mintlify/skills/auth0-expo/SKILL.md
+++ /dev/null
@@ -1,270 +0,0 @@
----
-name: auth0-expo
-description: Use when adding authentication to Expo (React Native) mobile apps — login, logout, user sessions, protected routes, biometrics, or token management. Integrates react-native-auth0 SDK with Expo Config Plugin for native iOS/Android builds. Trigger for any Expo project needing Auth0, including app.json plugin config, custom scheme setup, or credential management. Do NOT use for bare React Native CLI projects (use auth0-react-native), React web apps (use auth0-react), Next.js (use auth0-nextjs), or backend APIs.
-license: Proprietary
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 Expo Integration
-
-Add authentication to Expo (React Native) applications using `react-native-auth0` with the Expo Config Plugin.
-
-> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
-> ```bash
-> gh api repos/auth0/react-native-auth0/releases/latest --jq '.tag_name'
-> ```
-> Use the returned version in all dependency lines instead of any hardcoded version below. If the command fails, fall back to checking https://github.com/auth0/react-native-auth0/releases.
-
-## Prerequisites
-
-- Expo SDK 53 or higher (react-native-auth0 v5.x requires Expo 53+)
-- React 19 and React Native 0.78.0 or higher
-- Node.js 20+ (for bootstrap script automation)
-- Auth0 account with a **Native** application configured
-- If Auth0 is not set up yet, use the `auth0-quickstart` skill first
-- **Not compatible with Expo Go** — requires custom development client or EAS Build
-
-## When NOT to Use
-
-| Use Case | Recommended Skill |
-|----------|------------------|
-| Bare React Native CLI project (no Expo) | `auth0-react-native` |
-| React web SPA (Vite/CRA) | `auth0-react` |
-| Next.js application | `auth0-nextjs` |
-| Vue.js SPA | `auth0-vue` |
-| Angular SPA | `auth0-angular` |
-| Express.js backend | `auth0-express` |
-| Native Android (Kotlin/Java) | `auth0-android` |
-| Backend API (JWT validation) | `auth0-fastify-api` or `auth0-express` |
-
-## Quick Start Workflow
-
-> **Agent instruction:** First, check whether the user's prompt already includes both Auth0 **Client ID** and **Domain**.
-> - If both are provided, skip the setup-choice question and proceed directly to **Step 2 (Verify Expo Dev Client)** using those values.
-> - If either value is missing, ask the user using `AskUserQuestion`: _"How would you like to configure Auth0 for this Expo project?"_
->   - **Automatic setup (Recommended)** — runs a bootstrap script that creates the Auth0 app, database connection, callback URLs, and writes the plugin config to app.json
->   - **Manual setup** — the user provides their Auth0 Client ID and Domain
->
-> Follow the matching section below based on their choice.
-
-### 1. Configure Auth0
-
-#### Automatic Setup
-
-> **Agent instruction:** Run these quick checks before the bootstrap script. Do NOT run `auth0 login` from the agent — it is interactive and will hang.
->
-> 1. **Check Node.js**: `node --version`. If missing or below 20, ask user: install (`brew install node`) or switch to manual setup.
-> 2. **Check Auth0 CLI**: `command -v auth0`. If missing, ask user: install (`brew install auth0/auth0-cli/auth0`) or switch to manual setup.
-> 3. **Check Auth0 login**: `auth0 tenants list --csv --no-input 2>&1`. If it fails or returns empty:
->    - Tell the user: _"Please run `auth0 login` in your terminal and let me know when done."_
->    - Wait for the user to confirm, then re-run the check to verify.
-> 4. **Confirm active tenant**: Parse the `→` line from the CSV output to identify the active tenant domain. Tell the user: _"Your active Auth0 tenant is: `<domain>`. Is this the correct tenant?"_
->    - If yes, proceed.
->    - If no, ask the user to run `auth0 tenants use <tenant-domain>` in their terminal, then re-run step 3 to confirm the new active tenant.
->
-> Once confirmed, run the bootstrap script:
-> ```bash
-> cd <path-to-skill>/auth0-expo/scripts
-> npm install
-> node bootstrap.mjs <path-to-expo-project>
-> ```
->
-> The script validates the Expo project, creates a Native Auth0 application, sets up a database connection, and writes the plugin config to app.json. The agent should NOT handle client_id or domain manually.
->
-> If the script fails due to session expiry, ask the user to run `auth0 login` again, then re-run the script. For other failures, fall back to **Manual Setup** below.
->
-> After the script completes, proceed to **Step 2 (Verify Expo Dev Client)**.
-
-#### Manual Setup (User-Provided Credentials)
-
-> **Agent instruction:** Ask the user for their Auth0 credentials using `AskUserQuestion`:
->
-> "I need your Auth0 credentials to set up authentication. Please provide:
->
-> 1. **Auth0 Domain** (e.g., `your-tenant.us.auth0.com`)
-> 2. **Client ID** (a 32-character alphanumeric string)
->
-> You can find both in the [Auth0 Dashboard](https://manage.auth0.com/) under **Applications > Applications > your app > Settings**. If you don't have an Auth0 app yet, create one with type **Native** and copy the domain and client ID from the settings page."
->
-> Then write the configuration to app.json and proceed to **Step 2**.
-
-### 2. Verify Expo Dev Client
-
-> **Agent instruction:** Before installing the Auth0 SDK, check if the project has `expo-dev-client` installed. Read the project's `package.json` and look for `expo-dev-client` in `dependencies` or `devDependencies`.
->
-> - **If `expo-dev-client` is found:** Proceed to step 3.
-> - **If `expo-dev-client` is NOT found:** Use `AskUserQuestion` with the following message:
->
->   "The `react-native-auth0` SDK requires a custom Expo development client — it does **not** work with Expo Go. Your project does not have `expo-dev-client` installed.
->
->   How would you like to proceed?
->   1. **Install it for me** — I'll run `npx expo install expo-dev-client` and continue setup
->   2. **I'll set it up myself** — skip this step and continue to Auth0 SDK installation"
->
->   If the user picks option 1, run:
->   ```bash
->   npx expo install expo-dev-client
->   ```
->   Then proceed to step 3. If option 2, proceed to step 3 directly.
-
-### 3. Install SDK
-
-```bash
-npx expo install react-native-auth0
-```
-
-### 4. Configure Expo Config Plugin
-
-Add the react-native-auth0 plugin to `app.json` (or `app.config.js`) with your Auth0 domain and a custom scheme. Also ensure `bundleIdentifier` (iOS) and `package` (Android) are set:
-
-```json
-{
-  "expo": {
-    "ios": { "bundleIdentifier": "com.yourcompany.yourapp" },
-    "android": { "package": "com.yourcompany.yourapp" },
-    "plugins": [
-      ["react-native-auth0", {
-        "domain": "YOUR_AUTH0_DOMAIN",
-        "customScheme": "YOUR_CUSTOM_SCHEME"
-      }]
-    ]
-  }
-}
-```
-
-The `customScheme` must be all lowercase with no special characters (e.g., `auth0sample`). See [**Setup Guide**](./references/setup.md) for HTTPS callbacks, multiple domains, EAS Build, and secret management.
-
-> **Agent instruction:** If you used automatic setup (Step 1), the bootstrap script already wrote the plugin config to app.json — verify it's correct but do not overwrite it. If you used manual setup, write the config now using the user-provided domain and a custom scheme.
-
-### 5. Configure Callback URLs
-
-Add to **Allowed Callback URLs** and **Allowed Logout URLs** in the [Auth0 Dashboard](https://manage.auth0.com/):
-
-```text
-YOUR_CUSTOM_SCHEME://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_ID/callback,
-YOUR_CUSTOM_SCHEME://YOUR_AUTH0_DOMAIN/android/YOUR_PACKAGE/callback
-```
-
-All values must be **lowercase** with **no trailing slash**. For HTTPS callback URLs (App Links / Universal Links), see [Setup Guide](./references/setup.md#using-https-callback-urls-android-app-links).
-
-### 6. Add Authentication with Auth0Provider
-
-Wrap your app with `Auth0Provider` and use the `useAuth0` hook:
-
-> **Agent instruction:** Before adding new UI elements, search the project for existing click handlers for login, logout, sign-in, or sign-out buttons. If existing handlers are found, hook the Auth0 code into them. Only create new buttons if no existing handlers are found.
-
-```typescript
-import React from 'react';
-import { Auth0Provider, useAuth0 } from 'react-native-auth0';
-import { View, Button, Text, ActivityIndicator } from 'react-native';
-
-function HomeScreen() {
-  const { authorize, clearSession, user, isLoading, error } = useAuth0();
-
-  const login = async () => {
-    try {
-      await authorize(
-        { scope: 'openid profile email' },
-        { customScheme: 'YOUR_CUSTOM_SCHEME' }
-      );
-    } catch (e) {
-      console.error('Login error:', e);
-    }
-  };
-
-  const logout = async () => {
-    try {
-      await clearSession({ customScheme: 'YOUR_CUSTOM_SCHEME' });
-    } catch (e) {
-      console.error('Logout error:', e);
-    }
-  };
-
-  if (isLoading) {
-    return <ActivityIndicator size="large" />;
-  }
-
-  return (
-    <View>
-      {user ? (
-        <>
-          <Text>Welcome, {user.name}!</Text>
-          <Text>{user.email}</Text>
-          <Button title="Log Out" onPress={logout} />
-        </>
-      ) : (
-        <Button title="Log In" onPress={login} />
-      )}
-      {error && <Text>{error.message}</Text>}
-    </View>
-  );
-}
-
-export default function App() {
-  return (
-    <Auth0Provider
-      domain="YOUR_AUTH0_DOMAIN"
-      clientId="YOUR_AUTH0_CLIENT_ID"
-    >
-      <HomeScreen />
-    </Auth0Provider>
-  );
-}
-```
-
-### 7. Build & Verify
-
-> **Agent instruction:** After completing the integration, build the project to verify it compiles:
-> ```bash
-> npx expo prebuild --clean
-> npx expo run:ios
-> # or
-> npx expo run:android
-> ```
-> If the build fails, analyze the error output. Common integration build failures include:
-> - **"Invariant Violation: Native module cannot be null"**: Using Expo Go instead of a development build — run `npx expo run:ios` or `npx expo run:android` instead of `npx expo start`
-> - **Plugin not applied**: Missing `react-native-auth0` in app.json plugins array — verify the plugin configuration
-> - **Pod install fails (iOS)**: Run `npx expo prebuild --clean` to regenerate native projects
-> - **Manifest merge failure (Android)**: Conflicting auth0Domain placeholder — ensure only the config plugin sets the domain
->
-> Re-run the build after each fix. Track the number of build-fix iterations.
->
-> **Failcheck:** If the build still fails after 5–6 fix attempts, stop and ask the user using `AskUserQuestion`:
-> _"The build is still failing after several fix attempts. How would you like to proceed?"_
-> - **Let the skill continue fixing iteratively**
-> - **Fix it manually** — show the remaining errors
-> - **Skip build verification** — proceed without a successful build
-
-## Detailed Documentation
-
-- **[Setup Guide](./references/setup.md)** — Dev client requirement, automated setup, Expo config plugin, callback URLs, EAS Build, secret management
-- **[Integration Patterns](./references/integration.md)** — Login/logout, credential management, biometric auth, token refresh, organizations, DPoP, error handling
-- **[API Reference & Testing](./references/api.md)** — Configuration options, useAuth0 hook API, testing checklist, common issues, security
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Using Expo Go instead of development build | react-native-auth0 requires native code. Use `npx expo run:ios` / `npx expo run:android` or create a development build with EAS. |
-| Missing `customScheme` in authorize/clearSession calls | Pass `{ customScheme: 'your-scheme' }` as the second argument to `authorize()` and `clearSession()`. Must match the value in app.json plugin config. |
-| Callback URL mismatch | Ensure callback URL is all lowercase, no trailing slash, and matches Auth0 Dashboard exactly: `{customScheme}://{domain}/ios/{bundleId}/callback` |
-| App type not set to Native | The Auth0 application must be type **Native** in the Dashboard, not SPA or Regular Web. |
-| Missing bundleIdentifier or package in app.json | Both `expo.ios.bundleIdentifier` and `expo.android.package` must be set in app.json for callback URLs to work. |
-| Forgot to wrap app with Auth0Provider | All components using `useAuth0()` must be children of `Auth0Provider`. |
-| Using react-native-auth0 v5.x with Expo < 53 | Version 5.x requires Expo 53+. Use v4.x for older Expo versions. |
-| Not testing on physical device | Biometric authentication (Face ID, fingerprint) only works on a physical device, not simulators. Always test the full auth flow on a real device before release. |
-
-## Related Skills
-
-- [auth0-quickstart](/auth0-quickstart) — Set up an Auth0 account and application
-- [auth0-react-native](/auth0-react-native) — Bare React Native CLI projects
-- [auth0-mfa](/auth0-mfa) — Configure multi-factor authentication
-
-## References
-
-- [Auth0 Expo Quickstart](https://auth0.com/docs/quickstart/native/react-native-expo/interactive)
-- [react-native-auth0 GitHub Repository](https://github.com/auth0/react-native-auth0)
-- [react-native-auth0 API Documentation](https://auth0.github.io/react-native-auth0/)
-- [Expo Sample App](https://github.com/auth0-samples/auth0-react-native-sample/tree/master/00-Login-Expo)
-- [EXAMPLES.md](https://github.com/auth0/react-native-auth0/blob/master/EXAMPLES.md)
diff --git a/main/.mintlify/skills/auth0-express/SKILL.md b/main/.mintlify/skills/auth0-express/SKILL.md
deleted file mode 100644
index a8dfdcf088..0000000000
--- a/main/.mintlify/skills/auth0-express/SKILL.md
+++ /dev/null
@@ -1,193 +0,0 @@
----
-name: auth0-express
-description: Use when adding authentication (login, logout, protected routes) to Express.js web applications - integrates express-openid-connect for session-based auth.
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 Express Integration
-
-Add authentication to Express.js web applications using express-openid-connect.
-
----
-
-## Prerequisites
-
-- Express.js application
-- Auth0 account and application configured
-- If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first
-
-## When NOT to Use
-
-- **Single Page Applications** - Use `auth0-react`, `auth0-vue`, or `auth0-angular` for client-side auth
-- **Next.js applications** - Use `auth0-nextjs` skill which handles both client and server
-- **Mobile applications** - Use `auth0-react-native` for React Native/Expo
-- **Stateless APIs** - Use JWT validation middleware instead of session-based auth
-- **Microservices** - Use JWT validation for service-to-service auth
-
----
-
-## Quick Start Workflow
-
-### 1. Install SDK
-
-```bash
-npm install express-openid-connect dotenv
-```
-
-### 2. Configure Environment
-
-**For automated setup with Auth0 CLI**, see [Setup Guide](references/setup.md) for complete scripts.
-
-**For manual setup:**
-
-Create `.env`:
-
-```bash
-SECRET=<openssl-rand-hex-32>
-BASE_URL=http://localhost:3000
-CLIENT_ID=your-client-id
-CLIENT_SECRET=your-client-secret
-ISSUER_BASE_URL=https://your-tenant.auth0.com
-```
-
-Generate secret: `openssl rand -hex 32`
-
-### 3. Configure Auth Middleware
-
-Update your Express app (`app.js` or `index.js`):
-
-```javascript
-require('dotenv').config();
-const express = require('express');
-const { auth, requiresAuth } = require('express-openid-connect');
-
-const app = express();
-
-// Configure Auth0 middleware
-app.use(auth({
-  authRequired: false,  // Don't require auth for all routes
-  auth0Logout: true,    // Enable logout endpoint
-  secret: process.env.SECRET,
-  baseURL: process.env.BASE_URL,
-  clientID: process.env.CLIENT_ID,
-  issuerBaseURL: process.env.ISSUER_BASE_URL,
-  clientSecret: process.env.CLIENT_SECRET
-}));
-
-app.listen(3000, () => {
-  console.log('Server running on http://localhost:3000');
-});
-```
-
-This automatically creates:
-- `/login` - Login endpoint
-- `/logout` - Logout endpoint
-- `/callback` - OAuth callback
-
-### 4. Add Routes
-
-```javascript
-// Public route
-app.get('/', (req, res) => {
-  res.send(req.oidc.isAuthenticated() ? 'Logged in' : 'Logged out');
-});
-
-// Protected route
-app.get('/profile', requiresAuth(), (req, res) => {
-  res.send(`
-    <h1>Profile</h1>
-    <p>Name: ${req.oidc.user.name}</p>
-    <p>Email: ${req.oidc.user.email}</p>
-    <pre>${JSON.stringify(req.oidc.user, null, 2)}</pre>
-    <a href="/logout">Logout</a>
-  `);
-});
-
-// Login/logout links
-app.get('/', (req, res) => {
-  res.send(`
-    ${req.oidc.isAuthenticated() ? `
-      <p>Welcome, ${req.oidc.user.name}!</p>
-      <a href="/profile">Profile</a>
-      <a href="/logout">Logout</a>
-    ` : `
-      <a href="/login">Login</a>
-    `}
-  `);
-});
-```
-
-### 5. Test Authentication
-
-Start your server:
-
-```bash
-node app.js
-```
-
-Visit `http://localhost:3000` and test the login flow.
-
----
-
-## Detailed Documentation
-
-- **[Setup Guide](references/setup.md)** - Automated setup scripts, environment configuration, Auth0 CLI usage
-- **[Integration Guide](references/integration.md)** - Protected routes, sessions, API integration, error handling
-- **[API Reference](references/api.md)** - Complete middleware API, configuration options, request properties
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Forgot to add callback URL in Auth0 Dashboard | Add `/callback` path to Allowed Callback URLs (e.g., `http://localhost:3000/callback`) |
-| Missing or weak SECRET | Generate secure secret with `openssl rand -hex 32` and store in .env as `SECRET` |
-| Setting authRequired: true globally | Set to false and use `requiresAuth()` middleware on specific routes |
-| App created as SPA type in Auth0 | Must be Regular Web Application type for server-side auth |
-| Session secret exposed in code | Always use environment variables, never hardcode secrets |
-| Wrong baseURL for production | Update BASE_URL to match your production domain |
-| Not handling logout returnTo | Add your domain to Allowed Logout URLs in Auth0 Dashboard |
-
----
-
-## Related Skills
-
-- `auth0-quickstart` - Basic Auth0 setup
-- `auth0-migration` - Migrate from another auth provider
-- `auth0-mfa` - Add Multi-Factor Authentication
-
----
-
-## Quick Reference
-
-**Middleware Options:**
-- `authRequired` - Require auth for all routes (default: false)
-- `auth0Logout` - Enable /logout endpoint (default: false)
-- `secret` - Session secret (required)
-- `baseURL` - Application URL (required)
-- `clientID` - Auth0 client ID (required)
-- `issuerBaseURL` - Auth0 tenant URL (required)
-
-**Request Properties:**
-- `req.oidc.isAuthenticated()` - Check if user is logged in
-- `req.oidc.user` - User profile object
-- `req.oidc.accessToken` - Access token for API calls
-- `req.oidc.idToken` - ID token
-- `req.oidc.refreshToken` - Refresh token
-
-**Common Use Cases:**
-- Protected routes → Use `requiresAuth()` middleware (see Step 4)
-- Check auth status → `req.oidc.isAuthenticated()`
-- Get user info → `req.oidc.user`
-- Call APIs → [Integration Guide](references/integration.md#calling-apis)
-
----
-
-## References
-
-- [Express OpenID Connect Documentation](https://auth0.com/docs/libraries/express-openid-connect)
-- [Auth0 Express Quickstart](https://auth0.com/docs/quickstart/webapp/express)
-- [SDK GitHub Repository](https://github.com/auth0/express-openid-connect)
diff --git a/main/.mintlify/skills/auth0-fastapi-api/SKILL.md b/main/.mintlify/skills/auth0-fastapi-api/SKILL.md
deleted file mode 100644
index 4676a8861c..0000000000
--- a/main/.mintlify/skills/auth0-fastapi-api/SKILL.md
+++ /dev/null
@@ -1,268 +0,0 @@
----
-name: auth0-fastapi-api
-description: "Use when securing FastAPI API endpoints with JWT Bearer token validation, scope/permission checks, or stateless auth - integrates auth0-fastapi-api for REST APIs receiving access tokens from SPAs, mobile apps, or other clients. Also handles DPoP proof-of-possession token binding. Triggers on: Auth0FastAPI, FastAPI API auth, JWT validation, require_auth, DPoP."
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 FastAPI API Integration
-
-Protect FastAPI API endpoints with JWT access token validation using `auth0-fastapi-api`.
-
-> **Note:** This SDK is currently in beta. The API surface may change before the stable 1.0 release. Check [PyPI](https://pypi.org/project/auth0-fastapi-api/) for the latest version. Requires Python >= 3.9 and FastAPI >= 0.115.11.
-
----
-
-## Prerequisites
-
-- FastAPI application (Python 3.9+)
-- Auth0 API resource configured (not an Application — must be an API)
-- If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first
-
-## When NOT to Use
-
-- **Server-rendered web applications** — Use a session-based login/logout flow instead
-- **Single Page Applications** — Use `auth0-react`, `auth0-vue`, or `auth0-angular` for client-side auth
-- **Mobile applications** — Use `auth0-react-native` or `auth0-android`
-- **Issuing tokens** — This skill is for *validating* access tokens, not issuing them
-
----
-
-## Quick Start Workflow
-
-### 1. Install SDK
-
-```bash
-pip install auth0-fastapi-api python-dotenv
-```
-
-### 2. Create Auth0 API
-
-You need an **API** (not Application) in Auth0.
-
-> **STOP — ask the user before proceeding.**
->
-> Ask exactly this question and wait for their answer before doing anything else:
->
-> > "How would you like to create the Auth0 API resource?
-> > 1. **Automated** — I'll run Auth0 CLI scripts that create the resource and write the exact values to your `.env` automatically.
-> > 2. **Manual** — You create the API yourself in the Auth0 Dashboard (or via `auth0 apis create`) and provide me the Domain and Audience.
-> >
-> > Which do you prefer? (1 = Automated / 2 = Manual)"
->
-> Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.
-
-**If the user chose Automated**, follow the [Setup Guide](references/setup.md) for complete CLI scripts. The automated path writes `.env` for you — skip Step 3 below and proceed directly to Step 4.
-
-**If the user chose Manual**, follow the [Setup Guide](references/setup.md) (Manual Setup section) for full instructions. Then continue with Step 3 below.
-
-Quick reference for manual API creation:
-
-```bash
-# Using Auth0 CLI
-auth0 apis create \
-  --name "My FastAPI API" \
-  --identifier https://my-api.example.com
-```
-
-Or create manually in Auth0 Dashboard → Applications → APIs
-
-### 3. Configure Environment
-
-Create `.env`:
-
-```bash
-AUTH0_DOMAIN=your-tenant.us.auth0.com
-AUTH0_AUDIENCE=https://your-api.example.com
-```
-
-`AUTH0_DOMAIN` is your Auth0 tenant domain (without `https://`). `AUTH0_AUDIENCE` is the API identifier you set when creating the API resource in Auth0.
-
-### 4. Initialize Auth0
-
-```python
-import os
-from fastapi import FastAPI, Depends
-from auth0_fastapi_api import Auth0FastAPI
-from dotenv import load_dotenv
-
-load_dotenv()
-
-app = FastAPI()
-
-auth0 = Auth0FastAPI(
-    domain=os.getenv("AUTH0_DOMAIN"),
-    audience=os.getenv("AUTH0_AUDIENCE"),
-)
-```
-
-Create one `Auth0FastAPI` instance per application and reuse it across routes. Never hardcode the domain or audience — always use environment variables.
-
-### 5. Protect Routes
-
-```python
-# Require any valid access token
-@app.get("/api/private")
-async def private(claims: dict = Depends(auth0.require_auth())):
-    return {"user": claims["sub"]}
-
-# No authentication required
-@app.get("/api/public")
-async def public():
-    return {"message": "Public endpoint"}
-```
-
-The `require_auth()` dependency validates the Bearer token, verifies the issuer and audience, and returns the decoded JWT claims.
-
-Error responses:
-- **400** `invalid_request` — Missing or malformed Authorization header
-- **401** `invalid_token` — Expired token, invalid signature, wrong issuer/audience
-- **403** `insufficient_scope` — Valid token but missing required scopes
-- **500** `internal_server_error` — Unexpected errors
-
-Response body format: `{"detail": {"error": "...", "error_description": "..."}}`
-
-### 6. Protect Routes with Scope Checks
-
-```python
-# Requires the read:messages scope
-@app.get("/api/messages")
-async def get_messages(claims: dict = Depends(auth0.require_auth(scopes="read:messages"))):
-    return {"messages": []}
-
-# Requires both read:data and write:data scopes
-@app.post("/api/data")
-async def write_data(claims: dict = Depends(auth0.require_auth(scopes=["read:data", "write:data"]))):
-    return {"created": True}
-```
-
-`require_auth(scopes=...)` checks the `scope` claim in the JWT. All specified scopes must be present (AND logic). Missing scopes return **403**.
-
-### 7. Access Token Claims
-
-The decoded JWT claims are returned directly from the dependency:
-
-```python
-@app.get("/api/profile")
-async def profile(claims: dict = Depends(auth0.require_auth())):
-    return {
-        "sub": claims["sub"],       # user ID
-        "scope": claims.get("scope"),  # granted scopes
-    }
-```
-
-Key claims:
-- `claims["sub"]` — user/client ID
-- `claims["scope"]` — space-separated granted scopes
-- `claims["iss"]` — issuer (your Auth0 domain URL)
-- `claims["aud"]` — audience
-- `claims["exp"]` — expiration timestamp
-- `claims["iat"]` — issued-at timestamp
-
-### 8. Protect Routes Without Needing Claims
-
-```python
-@app.get("/api/protected", dependencies=[Depends(auth0.require_auth())])
-async def protected():
-    return {"message": "You need a valid access token to see this."}
-```
-
-### 9. Test the API
-
-```bash
-# No token — expect 401
-curl http://localhost:8000/api/private
-
-# With a valid access token
-curl http://localhost:8000/api/private \
-  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
-```
-
-Get a test token via Client Credentials flow or Auth0 Dashboard → APIs → Test tab.
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Hardcoding `domain` or `audience` in source | Always read from environment variables — never embed credentials in code |
-| Using `python-jose` or `PyJWT` directly | Not needed; `auth0-fastapi-api` handles all validation via JWKS |
-| Manually parsing `Authorization` header | The SDK extracts and validates the token automatically |
-| Calling `jwt.decode()` manually | The SDK verifies tokens against the JWKS endpoint — do not verify yourself |
-| Using `fastapi-users` for Auth0 JWT validation | That package is for user management, not Auth0 JWT verification |
-| Created an Application instead of an API in Auth0 | Must create an **API** resource (Applications → APIs) — an Application doesn't issue access tokens with the right audience |
-| Passing `domain` as full URL with `https://` | `domain` should be the bare domain, e.g. `my-tenant.us.auth0.com`, not `https://my-tenant.us.auth0.com` |
-| Using an ID token instead of an access token | Must use the **access token** for API auth — ID tokens are for the client app, not for API authorization |
-| Not configuring CORS for SPA clients | Add `CORSMiddleware` to allow requests from your frontend origin |
-| `os.getenv()` returns `None` silently | Ensure `python-dotenv` is installed and `load_dotenv()` is called before `Auth0FastAPI()` initialization — or use `os.environ[]` to fail fast |
-
----
-
-## DPoP Support
-
-Built-in proof-of-possession token binding per RFC 9449. DPoP is enabled by default in mixed mode (accepts both Bearer and DPoP tokens). See [Integration Guide](references/integration.md#dpop-support) for configuration.
-
----
-
-## Related Skills
-
-- `auth0-quickstart` - Basic Auth0 setup and framework detection
-- `auth0-mfa` - Add Multi-Factor Authentication
-
----
-
-## Quick Reference
-
-**Auth0FastAPI configuration:**
-```python
-auth0 = Auth0FastAPI(
-    domain=os.getenv("AUTH0_DOMAIN"),       # required (or use domains)
-    audience=os.getenv("AUTH0_AUDIENCE"),    # required
-    dpop_enabled=True,                       # default; set False for Bearer-only
-    dpop_required=False,                     # default; set True to reject Bearer tokens
-)
-```
-
-**Route protection:**
-```python
-Depends(auth0.require_auth())                    # any valid token
-Depends(auth0.require_auth(scopes="read:res"))   # single scope
-Depends(auth0.require_auth(scopes=["r", "w"]))   # all scopes required
-```
-
-**Accessing claims:**
-```python
-claims["sub"]           # user/client ID
-claims["scope"]         # space-separated scopes
-```
-
-**Environment variables:**
-- `AUTH0_DOMAIN` — your Auth0 tenant domain (e.g. `tenant.us.auth0.com`)
-- `AUTH0_AUDIENCE` — your API identifier (e.g. `https://api.example.com`)
-
-**Common Use Cases:**
-- Protect routes → `Depends(auth0.require_auth())` (see Step 5)
-- Scope enforcement → `Depends(auth0.require_auth(scopes="..."))` (see Step 6)
-- DPoP token binding → [Integration Guide](references/integration.md#dpop-support)
-- Reverse proxy setup → [Integration Guide](references/integration.md#reverse-proxy-support)
-- Advanced configuration → [API Reference](references/api.md)
-
----
-
-## Detailed Documentation
-
-- **[Setup Guide](references/setup.md)** — Auth0 CLI setup, environment configuration, getting test tokens
-- **[Integration Guide](references/integration.md)** — DPoP, scopes, error handling, reverse proxy, testing
-- **[API Reference](references/api.md)** — Complete constructor options, method signatures, error codes
-
----
-
-## References
-
-- [auth0-fastapi-api GitHub](https://github.com/auth0/auth0-fastapi-api)
-- [auth0-fastapi-api on PyPI](https://pypi.org/project/auth0-fastapi-api/)
-- [Auth0 FastAPI API Quickstart](https://auth0.com/docs/quickstart/backend/fastapi)
-- [FastAPI Dependency Injection](https://fastapi.tiangolo.com/tutorial/dependencies/)
-- [Access Tokens Guide](https://auth0.com/docs/secure/tokens/access-tokens)
diff --git a/main/.mintlify/skills/auth0-flask/SKILL.md b/main/.mintlify/skills/auth0-flask/SKILL.md
deleted file mode 100644
index ed2db20732..0000000000
--- a/main/.mintlify/skills/auth0-flask/SKILL.md
+++ /dev/null
@@ -1,377 +0,0 @@
----
-name: auth0-flask
-description: Use when adding login, logout, and user profile to a Flask web application using session-based authentication - integrates auth0-server-python for server-rendered apps with login/callback/profile/logout flows.
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 Flask Web App Integration
-
-Add login, logout, and user profile to a Flask web application using `auth0-server-python`.
-
----
-
-## Prerequisites
-
-- Flask application
-- Auth0 Regular Web Application configured (not an API — must be an Application)
-- If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first
-
-## When NOT to Use
-
-- **Python APIs with JWT Bearer validation** — Use `auth0-fastapi-api` for FastAPI, or see the [Django REST Framework quickstart](https://auth0.com/docs/quickstart/backend/django)
-- **FastAPI web app with login/logout UI** — No dedicated skill yet; see the [FastAPI quickstart](https://auth0.com/docs/quickstart/webapp/python)
-- **Single Page Applications** — Use `auth0-react`, `auth0-vue`, or `auth0-angular` for client-side auth
-- **Next.js applications** — Use `auth0-nextjs` which handles both client and server
-- **Node.js web apps** — Use `auth0-express` or `auth0-fastify` for session-based auth
-
----
-
-## Quick Start Workflow
-
-### 1. Install SDK
-
-```bash
-pip install auth0-server-python "flask[async]" python-dotenv
-```
-
-**Critical:** You must install `flask[async]` (not just `flask`). The `[async]` extra installs `asgiref` which is required for Flask 2.0+ to support `async def` route handlers. Without it, async routes will not work. In `requirements.txt`, use `flask[async]>=2.0.0`.
-
-### 2. Configure Environment
-
-Create `.env`:
-
-```bash
-AUTH0_DOMAIN=your-tenant.us.auth0.com
-AUTH0_CLIENT_ID=your_client_id
-AUTH0_CLIENT_SECRET=your_client_secret
-AUTH0_SECRET=your_generated_app_secret
-AUTH0_REDIRECT_URI=http://localhost:5000/callback
-```
-
-`AUTH0_DOMAIN` is your Auth0 tenant domain (without `https://`). `AUTH0_CLIENT_ID` and `AUTH0_CLIENT_SECRET` come from your Auth0 Application settings. `AUTH0_SECRET` is used for encrypting session data — generate with `openssl rand -hex 64`.
-
-### 3. Configure Auth0 Dashboard
-
-In your Auth0 Application settings:
-- **Allowed Callback URLs**: `http://localhost:5000/callback`
-- **Allowed Logout URLs**: `http://localhost:5000`
-
-### 4. Create Auth Module
-
-Create `auth.py` to initialize the `ServerClient` with Flask session-based stores. The stores use Flask's built-in `session` (cookie-based by default) for a **stateless** setup — no external database needed:
-
-```python
-import os
-from flask import session as flask_session
-from auth0_server_python.auth_server.server_client import ServerClient
-from auth0_server_python.auth_types import StateData, TransactionData
-from auth0_server_python.store import StateStore, TransactionStore
-from dotenv import load_dotenv
-
-load_dotenv()  # Uses .env by default; pass load_dotenv(".env.local") if credentials are in .env.local
-
-
-class FlaskSessionStateStore(StateStore):
-    """State store that uses Flask's session for persistence."""
-
-    def __init__(self, secret: str):
-        super().__init__({"secret": secret})
-
-    async def set(self, identifier, state, remove_if_expires=False, options=None):
-        data = state.dict() if hasattr(state, "dict") else state
-        flask_session[identifier] = self.encrypt(identifier, data)
-
-    async def get(self, identifier, options=None):
-        data = flask_session.get(identifier)
-        if data is None:
-            return None
-        decrypted = self.decrypt(identifier, data)
-        # Ensure to not return a dict, as the underlying SDK expects a StateData instance, not a dict
-        return StateData(**decrypted) if isinstance(decrypted, dict) else decrypted
-
-    async def delete(self, identifier, options=None):
-        flask_session.pop(identifier, None)
-
-    async def delete_by_logout_token(self, claims, options=None):
-        pass
-
-
-class FlaskSessionTransactionStore(TransactionStore):
-    """Transaction store that uses Flask's session for persistence."""
-
-    def __init__(self, secret: str):
-        super().__init__({"secret": secret})
-
-    async def set(self, identifier, state, remove_if_expires=False, options=None):
-        data = state.dict() if hasattr(state, "dict") else state
-        flask_session[identifier] = self.encrypt(identifier, data)
-
-    async def get(self, identifier, options=None):
-        data = flask_session.get(identifier)
-        if data is None:
-            return None
-        decrypted = self.decrypt(identifier, data)
-        # Ensure to not return a dict, as the underlying SDK expects a TransactionData instance, not a dict
-        return TransactionData(**decrypted) if isinstance(decrypted, dict) else decrypted
-
-    async def delete(self, identifier, options=None):
-        flask_session.pop(identifier, None)
-
-
-secret = os.getenv("AUTH0_SECRET")
-
-auth0 = ServerClient(
-    domain=os.getenv("AUTH0_DOMAIN"),
-    client_id=os.getenv("AUTH0_CLIENT_ID"),
-    client_secret=os.getenv("AUTH0_CLIENT_SECRET"),
-    secret=secret,
-    redirect_uri=os.getenv("AUTH0_REDIRECT_URI"),
-    state_store=FlaskSessionStateStore(secret=secret),
-    transaction_store=FlaskSessionTransactionStore(secret=secret),
-    authorization_params={"scope": "openid profile email"},
-)
-```
-
-Create one `ServerClient` instance and reuse it. Never hardcode credentials — always use environment variables.
-
-**How this works:** Flask's default session is cookie-based (stateless). The SDK encrypts session data (tokens, user profile) with JWE before storing it in the session, so data is both signed and encrypted in the cookie. No server-side database is required.
-
-**No `store_options` or `before_request` needed:** The SDK supports passing `store_options` (e.g. request/response objects) to store methods. Since these stores use `flask.session` — which is globally available during a request — they don't need anything from `store_options`, so you can call SDK methods without passing it. If you implement a custom store that manages cookies directly (instead of using `flask.session`), you would need to reintroduce `store_options` with `{"request": request, "response": response}`.
-
-**Cookie size note:** Stateless sessions store all data in a cookie (~4KB limit). For most apps this is sufficient. If you store large amounts of session data or hit cookie size limits, switch to [stateful setup](#stateful-setup-with-redis).
-
-### 5. Configure Flask App
-
-In `app.py`, set up Flask with the secret key and session configuration:
-
-```python
-import os
-from flask import Flask, redirect, request
-from auth import auth0
-from dotenv import load_dotenv
-
-load_dotenv()
-
-app = Flask(__name__)
-app.secret_key = os.getenv("AUTH0_SECRET")
-app.config.update(
-    SESSION_COOKIE_SECURE=False,  # Set to True in production (requires HTTPS)
-    SESSION_COOKIE_HTTPONLY=True,
-    SESSION_COOKIE_SAMESITE="Lax",
-)
-```
-
-**Critical:** `app.secret_key` must be set for Flask session management. Without it, sessions won't work.
-
-**For production:** Set `SESSION_COOKIE_SECURE=True` when deploying with HTTPS. Leaving it as `False` in production allows session cookies to be sent over unencrypted connections.
-
-### 6. Add Home Route
-
-```python
-@app.route("/")
-async def home():
-    user = await auth0.get_user()
-    if user:
-        return f"Hello, {user['name']}! <a href='/profile'>Profile</a> | <a href='/logout'>Logout</a>"
-    return "Welcome! <a href='/login'>Login</a>"
-```
-
-### 7. Add Login Route
-
-```python
-@app.route("/login")
-async def login():
-    authorization_url = await auth0.start_interactive_login()
-    return redirect(authorization_url)
-```
-
-`start_interactive_login()` returns a URL string pointing to Auth0's Universal Login page. You must wrap it in `redirect()`. Authorization params (scope, redirect_uri) are already configured on the `ServerClient`.
-
-### 8. Add Callback Route
-
-```python
-@app.route("/callback")
-async def callback():
-    try:
-        await auth0.complete_interactive_login(str(request.url))
-        return redirect("/")
-    except Exception as e:
-        return f"Authentication error: {str(e)}", 400
-```
-
-Pass `str(request.url)` as the first argument — this is the full callback URL including the authorization code query parameters. Always wrap in try/except since the token exchange can fail (e.g. expired code, CSRF mismatch).
-
-### 9. Add Profile Route (Protected)
-
-```python
-@app.route("/profile")
-async def profile():
-    user = await auth0.get_user()
-    if user is None:
-        return redirect("/login")
-    return (
-        f"<h1>{user['name']}</h1>"
-        f"<p>Email: {user['email']}</p>"
-        f"<img src='{user['picture']}' alt='{user['name']}' width='100' />"
-        f"<p><a href='/logout'>Logout</a></p>"
-    )
-```
-
-`get_user()` returns the user's profile from the session, or `None` if not logged in.
-
-### 10. Add Logout Route
-
-```python
-@app.route("/logout")
-async def logout():
-    url = await auth0.logout()
-    return redirect(url)
-```
-
-`logout()` returns the Auth0 logout URL. Redirect the user to it.
-
-### 11. Test the App
-
-```bash
-flask run
-```
-
-Visit `http://localhost:5000/login` to start the login flow.
-
----
-
-## Stateful Setup with Redis
-
-For production apps or when session data exceeds cookie size limits, use **Flask-Session** with Redis to store sessions server-side. Only a session ID is stored in the cookie.
-
-### 1. Install Dependencies
-
-```bash
-pip install flask-session redis
-```
-
-### 2. Configure Flask-Session
-
-Update `app.py` to use Redis-backed sessions:
-
-```python
-import os
-from flask import Flask, redirect, request
-from flask_session import Session
-from auth import auth0
-from dotenv import load_dotenv
-
-load_dotenv()
-
-app = Flask(__name__)
-app.secret_key = os.getenv("AUTH0_SECRET")
-app.config.update(
-    SESSION_TYPE="redis",
-    SESSION_PERMANENT=True,
-    SESSION_KEY_PREFIX="auth0:",
-    SESSION_COOKIE_SECURE=False,
-    SESSION_COOKIE_HTTPONLY=True,
-    SESSION_COOKIE_SAMESITE="Lax",
-)
-Session(app)
-```
-
-### 3. No Store Changes Needed
-
-The same `FlaskSessionStateStore` and `FlaskSessionTransactionStore` from `auth.py` work without modification. Flask-Session transparently switches the `flask.session` backend from cookies to Redis — the stores continue to use `flask.session` as before.
-
-**Routes are identical** to the stateless setup — no code changes needed.
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Hardcoding `domain`, `client_id`, or `client_secret` in source | Always read from environment variables — never embed credentials in code |
-| Using `Authlib` or `python-jose` directly | Not needed; `auth0-server-python` handles all OAuth/OIDC flows |
-| Using `Flask-Login` or `Flask-Dance` | Not needed; the SDK manages sessions and authentication |
-| Manually parsing JWTs with `jwt.decode()` | The SDK handles token validation internally |
-| Installing `flask` without `[async]` extra | Must use `flask[async]>=2.0.0` in requirements.txt — without it, async route handlers silently fail |
-| Using synchronous route handlers | All routes calling SDK methods must be `async def` and use `await` |
-| Forgetting `app.secret_key` | Required for Flask session management — without it, sessions silently fail |
-| Using `auth0-fastapi-api` in Flask | That package is for FastAPI APIs — use `auth0-server-python` for Flask |
-| Passing `domain` as full URL with `https://` | `domain` should be the bare domain, e.g. `my-tenant.us.auth0.com`, not `https://my-tenant.us.auth0.com` |
-| Not configuring callback URL in Auth0 Dashboard | Must add `http://localhost:5000/callback` to Allowed Callback URLs |
-| Returning `start_interactive_login()` directly | It returns a URL string, not a response — must wrap in `redirect()` |
-| Not handling errors in `/callback` | `complete_interactive_login()` can fail — always wrap in try/except |
-| Calling SDK methods without `await` | All SDK methods are async — forgetting `await` returns a coroutine instead of the result |
-| Passing options positionally to `logout()` | Use `logout(store_options=...)` — the first positional parameter is `LogoutOptions`, not store options |
-| Expecting backchannel logout to work | Not supported with cookie-based sessions — `delete_by_logout_token` is a no-op. Use standard `/logout` route |
-| Deploying with `SESSION_COOKIE_SECURE=False` | Must set to `True` in production — cookies are sent over HTTP otherwise |
-
----
-
-## Key SDK Methods
-
-All methods are async:
-
-| Method | Signature | Purpose |
-|--------|-----------|---------|
-| `start_interactive_login` | `await auth0.start_interactive_login()` | Returns authorization URL string — wrap in `redirect()` |
-| `complete_interactive_login` | `await auth0.complete_interactive_login(str(request.url))` | Processes the callback URL, exchanges code for tokens |
-| `get_user` | `await auth0.get_user()` | Returns current session user dict or `None` |
-| `get_access_token` | `await auth0.get_access_token()` | Returns the access token for calling external APIs |
-| `logout` | `await auth0.logout()` | Returns Auth0 logout URL string |
-
----
-
-## Related Skills
-
-- `auth0-express` — For server-rendered Express web apps with login/logout sessions
-- `auth0-fastify` — For Fastify web applications with session-based auth
-
----
-
-## Quick Reference
-
-**ServerClient configuration:**
-```python
-auth0 = ServerClient(
-    domain=os.getenv("AUTH0_DOMAIN"),                    # required
-    client_id=os.getenv("AUTH0_CLIENT_ID"),              # required
-    client_secret=os.getenv("AUTH0_CLIENT_SECRET"),      # required
-    secret=os.getenv("AUTH0_SECRET"),                    # required (encryption secret)
-    redirect_uri=os.getenv("AUTH0_REDIRECT_URI"),        # required
-    state_store=FlaskSessionStateStore(secret=secret),   # required
-    transaction_store=FlaskSessionTransactionStore(secret=secret),  # required
-    authorization_params={"scope": "openid profile email"},  # recommended
-)
-```
-
-**Route protection pattern:**
-```python
-user = await auth0.get_user()
-if user is None:
-    return redirect("/login")
-```
-
-**Environment variables:**
-- `AUTH0_DOMAIN` — your Auth0 tenant domain (e.g. `tenant.us.auth0.com`)
-- `AUTH0_CLIENT_ID` — your Application's client ID
-- `AUTH0_CLIENT_SECRET` — your Application's client secret
-- `AUTH0_SECRET` — encryption and session secret key
-- `AUTH0_REDIRECT_URI` — callback URL (e.g. `http://localhost:5000/callback`)
-
----
-
-## Detailed Documentation
-
-- **[Setup Guide](references/setup.md)** - Automated setup scripts, environment configuration, Auth0 CLI usage
-- **[Integration Guide](references/integration.md)** - Protected routes, calling APIs, session management, error handling
-- **[API Reference](references/api.md)** - Complete ServerClient API, configuration options, store implementation, security
-
----
-
-## References
-
-- [auth0-server-python on PyPI](https://pypi.org/project/auth0-server-python/)
-- [Auth0 Flask Quickstart](https://auth0.com/docs/quickstart/webapp/python)
-- [Flask Documentation](https://flask.palletsprojects.com/)
diff --git a/main/.mintlify/skills/auth0-java-mvc-common/SKILL.md b/main/.mintlify/skills/auth0-java-mvc-common/SKILL.md
deleted file mode 100644
index fa5225047c..0000000000
--- a/main/.mintlify/skills/auth0-java-mvc-common/SKILL.md
+++ /dev/null
@@ -1,348 +0,0 @@
----
-name: auth0-java-mvc-common
-description: Use when adding Auth0 login, logout, and callback handling to Java Servlet web applications - integrates com.auth0:mvc-auth-commons SDK for server-side Java apps using javax.servlet with session-based authentication. Triggers on AuthenticationController, AuthorizeUrl, Tokens, IdentityVerificationException, Java MVC auth.
-license: MIT
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 Java MVC Common Integration
-
-Add Auth0 authentication to Java Servlet web applications using `com.auth0:mvc-auth-commons`. Provides `AuthenticationController` for building authorize URLs and handling callbacks, with session-based authentication and support for Organizations and Multiple Custom Domains.
-
----
-
-> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
-> ```bash
-> gh api repos/auth0/auth0-java-mvc-common/releases/latest --jq '.tag_name'
-> ```
-> Use the returned version in all dependency lines instead of any hardcoded version below. If the API call fails, use `1.12.0`.
-
-## Prerequisites
-
-- Java 8+ (Java 17+ recommended)
-- Servlet container (Tomcat, Jetty, etc.) with javax.servlet 3+
-- Maven 3.6+ or Gradle 7+
-- Auth0 Regular Web Application configured
-- If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first
-
-## When NOT to Use
-
-| Use Case | Recommended Skill |
-|----------|-------------------|
-| Spring Boot web applications with auto-configuration | Use Spring Boot + Okta starter for auto-configured Spring Boot login |
-| Spring Boot REST APIs (stateless JWT) | Use `auth0-springboot-api` for JWT Bearer token validation |
-| Single Page Applications | Use `auth0-react`, `auth0-vue`, or `auth0-angular` for client-side auth |
-| Mobile applications | Use `auth0-android` or `auth0-swift` for native mobile |
-| Machine-to-machine API calls | Use Auth0 Management API SDK for server-to-server |
-
----
-
-## Quick Start Workflow
-
-> **Agent instruction:** If the user's prompt already provides Auth0 credentials (domain, client ID, client secret), use them directly — skip the bootstrap script and credential questions. Only offer setup options when credentials are missing.
-
-### 1. Install SDK
-
-**Gradle (build.gradle):**
-
-```groovy
-implementation 'com.auth0:mvc-auth-commons:1.12.0'
-```
-
-**Maven (pom.xml):**
-
-```xml
-<dependency>
-    <groupId>com.auth0</groupId>
-    <artifactId>mvc-auth-commons</artifactId>
-    <version>1.12.0</version>
-</dependency>
-```
-
-### 2. Create Auth0 Application
-
-You need a **Regular Web Application** (not SPA or Native) in Auth0.
-
-> **STOP — ask the user before proceeding.**
->
-> Ask exactly this question and wait for their answer before doing anything else:
->
-> > "How would you like to create the Auth0 application?
-> > 1. **Automated** — I'll run Auth0 CLI scripts that create the application and write the values to your config automatically.
-> > 2. **Manual** — You create the application yourself in the Auth0 Dashboard (or via `auth0 apps create`) and provide me the Domain, Client ID, and Client Secret.
-> >
-> > Which do you prefer? (1 = Automated / 2 = Manual)"
->
-> Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.
-
-**If the user chose Automated**, follow the [Setup Guide](references/setup.md) for complete CLI scripts. The automated path writes configuration for you — skip Step 3 below and proceed directly to Step 4.
-
-**If the user chose Manual**, follow the [Setup Guide](references/setup.md) (Manual Setup section). Then continue with Step 3.
-
-Quick reference for manual application creation:
-
-```bash
-# Using Auth0 CLI
-auth0 apps create \
-  --name "My Java Web App" \
-  --type regular \
-  --callbacks http://localhost:3000/callback \
-  --logout-urls http://localhost:3000
-```
-
-Or create manually in Auth0 Dashboard → Applications → Applications → Create Application → Regular Web Applications
-
-### 3. Configure Credentials
-
-Store credentials as environment variables (never hardcode in source):
-
-```bash
-export AUTH0_DOMAIN="your-tenant.auth0.com"
-export AUTH0_CLIENT_ID="your-client-id"
-export AUTH0_CLIENT_SECRET="your-client-secret"
-```
-
-Or use a `.env` file (add to `.gitignore`):
-
-```properties
-AUTH0_DOMAIN=your-tenant.auth0.com
-AUTH0_CLIENT_ID=your-client-id
-AUTH0_CLIENT_SECRET=your-client-secret
-```
-
-> **Agent instruction:** Java does not auto-load `.env` files. `System.getenv()` only reads OS-level environment variables. If you generate a `.env` file, you must also either: (1) add [dotenv-java](https://github.com/cdimascio/dotenv-java) as a dependency and use `Dotenv.load().get("AUTH0_DOMAIN")` instead of `System.getenv()`, or (2) instruct the user to run `source .env` before starting the server. Do not generate code that uses both a `.env` file and `System.getenv()` without a loading mechanism — the values will be `null`.
-
-**Important:** Domain must NOT include `https://`. The library constructs the issuer URL automatically.
-
-### 4. Initialize AuthenticationController
-
-Create a singleton `AuthenticationController` instance:
-
-```java
-import com.auth0.AuthenticationController;
-import com.auth0.jwk.JwkProviderBuilder;
-import com.auth0.jwk.JwkProvider;
-
-public class Auth0Config {
-
-    private static final AuthenticationController controller = createController();
-
-    private static AuthenticationController createController() {
-        String domain = System.getenv("AUTH0_DOMAIN");
-        String clientId = System.getenv("AUTH0_CLIENT_ID");
-        String clientSecret = System.getenv("AUTH0_CLIENT_SECRET");
-
-        JwkProvider jwkProvider = new JwkProviderBuilder(domain).build();
-
-        return AuthenticationController.newBuilder(domain, clientId, clientSecret)
-            .withJwkProvider(jwkProvider)
-            .build();
-    }
-
-    public static AuthenticationController getAuthController() {
-        return controller;
-    }
-}
-```
-
-### 5. Create Login Servlet
-
-```java
-import com.auth0.AuthenticationController;
-import com.auth0.AuthorizeUrl;
-
-import javax.servlet.ServletException;
-import javax.servlet.annotation.WebServlet;
-import javax.servlet.http.HttpServlet;
-import javax.servlet.http.HttpServletRequest;
-import javax.servlet.http.HttpServletResponse;
-import java.io.IOException;
-
-@WebServlet(urlPatterns = {"/login"})
-public class LoginServlet extends HttpServlet {
-
-    @Override
-    protected void doGet(HttpServletRequest request, HttpServletResponse response)
-            throws ServletException, IOException {
-        AuthenticationController controller = Auth0Config.getAuthController();
-
-        // Build callback URL — omit port for standard ports (80/443) to avoid
-        // mismatch with the URL registered in Auth0 Dashboard, especially behind proxies.
-        String scheme = request.getScheme();
-        int port = request.getServerPort();
-        String redirectUrl = scheme + "://" + request.getServerName()
-            + ((port == 80 || port == 443) ? "" : ":" + port) + "/callback";
-
-        AuthorizeUrl authorizeUrl = controller.buildAuthorizeUrl(request, response, redirectUrl)
-            .withScope("openid profile email");
-
-        response.sendRedirect(authorizeUrl.build());
-    }
-}
-```
-
-### 6. Create Callback Servlet
-
-```java
-import com.auth0.AuthenticationController;
-import com.auth0.IdentityVerificationException;
-import com.auth0.Tokens;
-
-import javax.servlet.ServletException;
-import javax.servlet.annotation.WebServlet;
-import javax.servlet.http.HttpServlet;
-import javax.servlet.http.HttpServletRequest;
-import javax.servlet.http.HttpServletResponse;
-import java.io.IOException;
-
-@WebServlet(urlPatterns = {"/callback"})
-public class CallbackServlet extends HttpServlet {
-
-    @Override
-    protected void doGet(HttpServletRequest request, HttpServletResponse response)
-            throws ServletException, IOException {
-        AuthenticationController controller = Auth0Config.getAuthController();
-
-        try {
-            Tokens tokens = controller.handle(request, response);
-
-            request.getSession().setAttribute("accessToken", tokens.getAccessToken());
-            request.getSession().setAttribute("idToken", tokens.getIdToken());
-
-            response.sendRedirect("/dashboard");
-        } catch (IdentityVerificationException e) {
-            response.sendRedirect("/login?error=" + e.getCode());
-        }
-    }
-}
-```
-
-### 7. Protect Routes with Authentication Middleware (Servlet Filter)
-
-```java
-import javax.servlet.*;
-import javax.servlet.annotation.WebFilter;
-import javax.servlet.http.HttpServletRequest;
-import javax.servlet.http.HttpServletResponse;
-import javax.servlet.http.HttpSession;
-import java.io.IOException;
-
-@WebFilter(urlPatterns = {"/dashboard/*", "/api/private/*"})
-public class AuthenticationFilter implements Filter {
-
-    @Override
-    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
-            throws IOException, ServletException {
-        HttpServletRequest request = (HttpServletRequest) req;
-        HttpServletResponse response = (HttpServletResponse) res;
-        HttpSession session = request.getSession(false);
-
-        if (session == null || session.getAttribute("idToken") == null) {
-            response.sendRedirect("/login");
-            return;
-        }
-
-        chain.doFilter(req, res);
-    }
-
-    @Override
-    public void init(FilterConfig filterConfig) {}
-
-    @Override
-    public void destroy() {}
-}
-```
-
-### 8. Test Application
-
-> **Agent instruction:** After writing all code, verify the build succeeds:
-> ```bash
-> ./gradlew build
-> ```
-> or `mvn package`. If build fails, diagnose and fix. After 5-6 failed attempts, use `AskUserQuestion` to get help.
-
-1. Start the application and navigate to `http://localhost:3000/login`
-2. You should be redirected to the Auth0 Universal Login page
-3. After login, the callback servlet handles the response and redirects to `/dashboard`
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Domain includes `https://` | Use `your-tenant.auth0.com` format only — no scheme prefix |
-| Client secret hardcoded in source | Use environment variables or `.env` file, add to `.gitignore` |
-| Created SPA or Native app instead of Regular Web | Must create **Regular Web Application** in Auth0 Dashboard |
-| Callback URL mismatch | Callback URL in code must exactly match what's registered in Auth0 Dashboard |
-| Missing `openid` scope | Always include `openid` in the scope — required for ID token |
-| Not handling `IdentityVerificationException` | Always catch this in the callback handler to show login errors |
-| Using `response_type=token` | Regular web apps must use `code` flow (the default) — never implicit |
-| Session not invalidated on logout | Call `request.getSession().invalidate()` before redirecting to Auth0 logout |
-
----
-
-## Scope and Audience Configuration
-
-See [Integration Guide](references/integration.md) for requesting custom scopes, audience for API access tokens, and Organizations support.
-
----
-
-## Multiple Custom Domains (MCD)
-
-Built-in support for routing users to the correct Auth0 domain via `DomainResolver`. See [Integration Guide](references/integration.md) for configuration.
-
----
-
-## Related Skills
-
-- `auth0-quickstart` — Basic Auth0 setup and account creation
-- `auth0-springboot-api` — Spring Boot REST APIs with JWT Bearer token validation
-
----
-
-## Quick Reference
-
-**Core Classes:**
-- `AuthenticationController` — Main entry point, builds authorize URLs and handles callbacks
-- `AuthenticationController.Builder` — Configures the controller via `newBuilder(domain, clientId, clientSecret)`
-- `AuthorizeUrl` — Fluent builder for `/authorize` URL parameters
-- `Tokens` — Access token, ID token, refresh token from callback
-- `IdentityVerificationException` — Authentication error with error code
-- `DomainResolver` — Interface for Multiple Custom Domain support
-
-**Builder Methods (`AuthorizeUrl`):**
-- `.withScope("openid profile email")` — Set requested scopes
-- `.withAudience("https://my-api")` — Request API access token
-- `.withOrganization("org_xxx")` — Lock to specific Organization
-- `.withInvitation("invite_xxx")` — Accept Organization invitation
-- `.withConnection("google-oauth2")` — Skip to specific connection
-- `.withParameter("key", "value")` — Add custom authorize parameter
-
-**Token Access (`Tokens`):**
-- `tokens.getAccessToken()` — Access token string
-- `tokens.getIdToken()` — ID token (JWT) string
-- `tokens.getRefreshToken()` — Refresh token (if `offline_access` scope requested)
-- `tokens.getExpiresIn()` — Token expiration in seconds
-- `tokens.getType()` — Token type (usually "Bearer")
-- `tokens.getDomain()` — Auth0 domain that issued the tokens
-- `tokens.getIssuer()` — Token issuer URL
-
----
-
-## Detailed Documentation
-
-- **[Setup Guide](references/setup.md)** — Auth0 CLI automation, environment configuration, secret management
-- **[Integration Guide](references/integration.md)** — Organizations, MCD, custom scopes, logout, error handling, advanced patterns
-- **[API Reference](references/api.md)** — Complete configuration options, builder methods, claims reference, testing checklist
-
----
-
-## References
-
-- [Auth0 Java Web App Quickstart](https://auth0.com/docs/quickstart/webapp/java)
-- [SDK GitHub Repository](https://github.com/auth0/auth0-java-mvc-common)
-- [Auth0 Universal Login](https://auth0.com/docs/authenticate/login/auth0-universal-login)
-- [Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)
-- [Auth0 Organizations](https://auth0.com/docs/manage-users/organizations)
diff --git a/main/.mintlify/skills/auth0-mfa/SKILL.md b/main/.mintlify/skills/auth0-mfa/SKILL.md
deleted file mode 100644
index 77efe88e34..0000000000
--- a/main/.mintlify/skills/auth0-mfa/SKILL.md
+++ /dev/null
@@ -1,172 +0,0 @@
----
-name: auth0-mfa
-description: Use when adding MFA, 2FA, TOTP, SMS codes, push notifications, passkeys, or when requiring step-up verification for sensitive operations or meeting compliance requirements (HIPAA, PCI-DSS) - covers adaptive and risk-based authentication with Auth0.
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 MFA Guide
-
-Add Multi-Factor Authentication to protect user accounts and require additional verification for sensitive operations.
-
----
-
-## Overview
-
-### What is MFA?
-
-Multi-Factor Authentication (MFA) requires users to provide two or more verification factors to access their accounts. Auth0 supports multiple MFA factors and enables step-up authentication for sensitive operations.
-
-### When to Use This Skill
-
-- Adding MFA to protect user accounts
-- Requiring additional verification for sensitive actions (payments, settings changes)
-- Implementing adaptive/risk-based authentication
-- Meeting compliance requirements (PCI-DSS, SOC2, HIPAA)
-
-### MFA Factors Supported
-
-| Factor | Type | Description |
-|--------|------|-------------|
-| TOTP | Something you have | Time-based one-time passwords (Google Authenticator, Authy) |
-| SMS | Something you have | One-time codes via text message |
-| Email | Something you have | One-time codes via email |
-| Push | Something you have | Push notifications via Auth0 Guardian app |
-| WebAuthn | Something you have/are | Security keys, biometrics, passkeys |
-| Voice | Something you have | One-time codes via phone call |
-| Recovery Code | Backup | One-time use recovery codes |
-
-### Key Concepts
-
-| Concept | Description |
-|---------|-------------|
-| `acr_values` | Request MFA during authentication |
-| `amr` claim | Authentication Methods Reference - indicates how user authenticated |
-| Step-up auth | Require MFA for specific actions after initial login |
-| Adaptive MFA | Conditionally require MFA based on risk signals |
-
----
-
-## Step 1: Enable MFA in Tenant
-
-### Via Auth0 Dashboard
-
-1. Go to **Security → Multi-factor Auth**
-2. Enable desired factors (TOTP, SMS, etc.)
-3. Configure **Policies**:
-   - **Always** - Require MFA for all logins
-   - **Adaptive** - Risk-based MFA
-   - **Never** - Disable MFA (use step-up instead)
-
-### Via Auth0 CLI
-
-```bash
-# View current MFA configuration
-auth0 api get "guardian/factors"
-
-# Enable TOTP (One-time Password)
-auth0 api put "guardian/factors/otp" --data '{"enabled": true}'
-
-# Enable SMS
-auth0 api put "guardian/factors/sms" --data '{"enabled": true}'
-
-# Enable Push notifications
-auth0 api put "guardian/factors/push-notification" --data '{"enabled": true}'
-
-# Enable WebAuthn (Roaming - Security Keys)
-auth0 api put "guardian/factors/webauthn-roaming" --data '{"enabled": true}'
-
-# Enable WebAuthn (Platform - Biometrics)
-auth0 api put "guardian/factors/webauthn-platform" --data '{"enabled": true}'
-
-# Enable Email
-auth0 api put "guardian/factors/email" --data '{"enabled": true}'
-```
-
-### Configure MFA Policy
-
-```bash
-# Set MFA policy: "all-applications" or "confidence-score"
-auth0 api patch "guardian/policies" --data '["all-applications"]'
-```
-
----
-
-## Step 2: Implement Step-Up Authentication
-
-Step-up auth requires MFA for sensitive operations without requiring it for every login.
-
-### The `acr_values` Parameter
-
-Request MFA by including `acr_values` in your authorization request:
-
-```
-acr_values=http://schemas.openid.net/pape/policies/2007/06/multi-factor
-```
-
-### Implementation Pattern
-
-The general pattern for all frameworks:
-
-1. Check if user has already completed MFA (inspect `amr` claim)
-2. If not, request MFA via `acr_values` parameter
-3. Proceed with sensitive action once MFA is verified
-
-**For complete framework-specific examples, see [Examples Guide](references/examples.md):**
-- React (basic and custom hook)
-- Next.js (App Router)
-- Vue.js
-- Angular
-
----
-
-## Additional Resources
-
-This skill is split into multiple files for better organization:
-
-### [Step-Up Examples](references/examples.md)
-Complete code examples for all frameworks:
-- React (basic and custom hook patterns)
-- Next.js (App Router with API routes)
-- Vue.js (composition API)
-- Angular (services and components)
-
-### [Backend Validation](references/backend.md)
-Learn how to validate MFA status on your backend:
-- Node.js / Express JWT validation
-- Python / Flask validation
-- Middleware examples
-
-### [Advanced Topics](references/advanced.md)
-Advanced MFA implementation patterns:
-- Adaptive MFA with Auth0 Actions
-- Conditional MFA based on risk signals
-- MFA Enrollment API
-
-### [Reference Guide](references/api.md)
-Common patterns and troubleshooting:
-- Remember MFA for 30 days
-- MFA for high-value transactions
-- MFA status display
-- Error handling
-- AMR claim values
-- Testing strategies
-- Security considerations
-
----
-
-## Related Skills
-
-- `auth0-quickstart` - Basic Auth0 setup
-- `auth0-passkeys` - WebAuthn/passkey implementation
-- `auth0-actions` - Custom authentication logic
-
----
-
-## References
-
-- [Auth0 MFA Documentation](https://auth0.com/docs/secure/multi-factor-authentication)
-- [Step-Up Authentication](https://auth0.com/docs/secure/multi-factor-authentication/step-up-authentication)
-- [MFA API](https://auth0.com/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis)
-- [acr_values Parameter](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow#request-parameters)
diff --git a/main/.mintlify/skills/auth0-migration/SKILL.md b/main/.mintlify/skills/auth0-migration/SKILL.md
deleted file mode 100644
index a39d4fd27f..0000000000
--- a/main/.mintlify/skills/auth0-migration/SKILL.md
+++ /dev/null
@@ -1,245 +0,0 @@
----
-name: auth0-migration
-description: Use when migrating or switching from an existing auth provider (Firebase, Cognito, Supabase, Clerk, custom auth) to Auth0 - covers bulk user import, gradual migration strategies, code migration patterns, and JWT validation updates.
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 Migration Guide
-
-Migrate users and authentication flows from existing auth providers to Auth0.
-
----
-
-## Overview
-
-### When to Use This Skill
-
-- Migrating from another auth provider to Auth0
-- Bulk importing existing users
-- Gradually transitioning active user bases
-- Updating JWT validation in APIs
-
-## When NOT to Use
-
-- **Starting fresh with Auth0** - Use `auth0-quickstart` for new projects without existing users
-- **Already using Auth0** - This is for migrating TO Auth0, not between Auth0 tenants
-- **Only adding MFA or features** - Use feature-specific skills if just adding capabilities
-
-### Migration Approaches
-
-- **Bulk Migration:** One-time user import (recommended for small/inactive bases)
-- **Gradual Migration:** Lazy migration over time (recommended for large active bases)
-- **Hybrid:** Import inactive users, lazy-migrate active users
-
----
-
-## Step 0: Detect Existing Auth Provider
-
-**Check if the project already has authentication:**
-
-Search for common auth-related patterns in the codebase:
-
-| Pattern | Indicates |
-|---------|-----------|
-| `signInWithEmailAndPassword`, `onAuthStateChanged` | Firebase Auth |
-| `useUser`, `useSession`, `isSignedIn` | Existing auth hooks |
-| `passport.authenticate`, `LocalStrategy` | Passport.js |
-| `authorize`, `getAccessToken`, `oauth` | OAuth/OIDC |
-| `JWT`, `jwt.verify`, `jsonwebtoken` | Token-based auth |
-| `/api/auth/`, `/login`, `/callback` | Auth routes |
-
-**If existing auth detected, ask:**
-
-> I detected existing authentication in your project. Are you:
-> 1. **Migrating to Auth0** (replace existing auth)
-> 2. **Adding Auth0 alongside** (keep both temporarily)
-> 3. **Starting fresh** (remove old auth, new Auth0 setup)
-
----
-
-## Migration Workflow
-
-### Step 1: Export Existing Users
-
-Export users from your current provider. See [User Import Guide](references/user-import.md) for detailed instructions:
-- [Exporting from Firebase](references/user-import.md#firebase)
-- [Exporting from AWS Cognito](references/user-import.md#aws-cognito)
-- [Exporting from Supabase](references/user-import.md#supabase)
-- [Exporting from Custom Database](references/user-import.md#custom-database)
-
-**Required data per user:**
-- Email address
-- Email verified status
-- Password hash (if available)
-- User metadata/profile data
-- Creation timestamp
-
----
-
-### Step 2: Import Users to Auth0
-
-Import users via Dashboard, CLI, or Management API.
-
-**Quick start:**
-```bash
-# Via Auth0 CLI
-auth0 api post "jobs/users-imports" \
-  --data "connection_id=con_ABC123" \
-  --data "users=@users.json"
-```
-
-**For detailed instructions:**
-- [User JSON Format](references/user-import.md#auth0-user-import-format)
-- [Password Hash Algorithms](references/user-import.md#password-hash-algorithms)
-- [Import Methods](references/user-import.md#importing-to-auth0)
-- [Monitoring Import Progress](references/user-import.md#monitoring-import-progress)
-- [Common Import Errors](references/user-import.md#common-import-errors)
-
----
-
-### Step 3: Migrate Application Code
-
-Update your application code to use Auth0 SDKs.
-
-**See [Code Migration Patterns](references/code-patterns.md) for detailed before/after examples:**
-
-**Frontend:**
-- [React Migration](references/code-patterns.md#react-migration)
-- [Next.js Migration](references/code-patterns.md#nextjs-migration)
-- [Vue.js Migration](references/code-patterns.md#vuejs-migration)
-- [Angular Migration](references/code-patterns.md#angular-migration)
-- [React Native Migration](references/code-patterns.md#react-native-migration)
-
-**Backend:**
-- [Express.js Migration](references/code-patterns.md#expressjs-migration)
-- [API JWT Validation](references/code-patterns.md#backend-api-jwt-validation)
-
-**Provider-Specific:**
-- [Firebase to Auth0](references/code-patterns.md#firebase-to-auth0)
-- [Supabase to Auth0](references/code-patterns.md#supabase-to-auth0)
-- [Clerk to Auth0](references/code-patterns.md#clerk-to-auth0)
-
-**After migrating code, use framework-specific skills:**
-- `auth0-react` for React applications
-- `auth0-nextjs` for Next.js applications
-- `auth0-vue` for Vue.js applications
-- `auth0-angular` for Angular applications
-- `auth0-express` for Express.js applications
-- `auth0-react-native` for React Native/Expo applications
-
----
-
-### Step 4: Update API JWT Validation
-
-If your API validates JWTs, update to validate Auth0 tokens.
-
-**Key differences:**
-- **Algorithm:** HS256 (symmetric) → RS256 (asymmetric)
-- **Issuer:** Custom → `https://YOUR_TENANT.auth0.com/`
-- **JWKS URL:** `https://YOUR_TENANT.auth0.com/.well-known/jwks.json`
-
-**See [JWT Validation Examples](references/code-patterns.md#backend-api-jwt-validation) for:**
-- Node.js / Express implementation
-- Python / Flask implementation
-- Key differences and migration checklist
-
----
-
-## Gradual Migration Strategy
-
-For production applications with active users, use a phased approach:
-
-### Phase 1: Parallel Auth
-
-Support both Auth0 and legacy provider simultaneously:
-
-```typescript
-// Support both providers during migration
-const getUser = async () => {
-  // Try Auth0 first
-  const auth0User = await getAuth0User();
-  if (auth0User) return auth0User;
-
-  // Fall back to legacy provider
-  return await getLegacyUser();
-};
-```
-
-### Phase 2: New Users on Auth0
-
-- All new signups go to Auth0
-- Existing users continue on legacy provider
-- Migrate users on next login (lazy migration)
-
-### Phase 3: Forced Migration
-
-- Prompt remaining users to "update account"
-- Send password reset emails via Auth0
-- Set deadline for legacy system shutdown
-
-### Phase 4: Cleanup
-
-- Remove legacy auth code
-- Archive user export for compliance
-- Update documentation
-
----
-
-## Common Migration Issues
-
-| Issue | Solution |
-|-------|----------|
-| Password hashes incompatible | Use Auth0 custom DB connection with lazy migration |
-| Social logins don't link | Configure same social connection, users auto-link by email |
-| Custom claims missing | Add claims via Auth0 Actions |
-| Token format different | Update API to validate RS256 JWTs with Auth0 issuer |
-| Session persistence | Auth0 uses rotating refresh tokens; update token storage |
-| Users must re-login | Expected for redirect-based auth; communicate to users |
-
----
-
-## Reference Documentation
-
-### User Import
-Complete guide to exporting and importing users:
-- [Exporting from Common Providers](references/user-import.md#exporting-users-from-common-providers)
-- [User JSON Format](references/user-import.md#auth0-user-import-format)
-- [Password Hash Algorithms](references/user-import.md#password-hash-algorithms)
-- [Import Methods](references/user-import.md#importing-to-auth0)
-- [Monitoring & Troubleshooting](references/user-import.md#monitoring-import-progress)
-
-### Code Migration
-Before/after examples for all major frameworks:
-- [React Patterns](references/code-patterns.md#react-migration)
-- [Next.js Patterns](references/code-patterns.md#nextjs-migration)
-- [Express Patterns](references/code-patterns.md#expressjs-migration)
-- [Vue.js Patterns](references/code-patterns.md#vuejs-migration)
-- [Angular Patterns](references/code-patterns.md#angular-migration)
-- [React Native Patterns](references/code-patterns.md#react-native-migration)
-- [API JWT Validation](references/code-patterns.md#backend-api-jwt-validation)
-
----
-
-## Related Skills
-
-### Core Integration
-- `auth0-quickstart` - Initial Auth0 setup after migration
-
-### SDK Skills
-- `auth0-react` - React SPA integration
-- `auth0-nextjs` - Next.js integration
-- `auth0-vue` - Vue.js integration
-- `auth0-angular` - Angular integration
-- `auth0-express` - Express.js integration
-- `auth0-react-native` - React Native/Expo integration
-
----
-
-## References
-
-- [Auth0 User Migration Documentation](https://auth0.com/docs/manage-users/user-migration)
-- [Bulk User Import](https://auth0.com/docs/manage-users/user-migration/bulk-user-imports)
-- [Password Hash Algorithms](https://auth0.com/docs/manage-users/user-migration/bulk-user-imports#password-hashing-algorithms)
-- [Management API - User Import](https://auth0.com/docs/api/management/v2/jobs/post-users-imports)
diff --git a/main/.mintlify/skills/auth0-nextjs/SKILL.md b/main/.mintlify/skills/auth0-nextjs/SKILL.md
deleted file mode 100644
index 8dadd36116..0000000000
--- a/main/.mintlify/skills/auth0-nextjs/SKILL.md
+++ /dev/null
@@ -1,282 +0,0 @@
----
-name: auth0-nextjs
-description: Use when adding authentication to Next.js applications (login, logout, protected pages, middleware, server components) - supports App Router and Pages Router with @auth0/nextjs-auth0 SDK.
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 Next.js Integration
-
-Add authentication to Next.js applications using @auth0/nextjs-auth0. Supports both App Router and Pages Router.
-
----
-
-## Prerequisites
-
-- Next.js 13+ application (App Router or Pages Router)
-- Auth0 account and application configured
-- If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first
-
-## When NOT to Use
-
-- **Client-side only React apps** - Use `auth0-react` for Vite/CRA SPAs
-- **React Native mobile apps** - Use `auth0-react-native` for iOS/Android
-- **Non-Next.js frameworks** - Use framework-specific SDKs (Express, Vue, Angular, etc.)
-- **Stateless APIs only** - Use JWT validation middleware if you don't need session management
-
----
-
-## Quick Start Workflow
-
-### 1. Install SDK
-
-```bash
-npm install @auth0/nextjs-auth0
-```
-
-### 2. Configure Environment
-
-**For automated setup with Auth0 CLI**, see [Setup Guide](references/setup.md) for complete scripts.
-
-**For manual setup:**
-
-Create `.env.local`:
-
-```bash
-AUTH0_SECRET=<generate-a-32-character-secret>
-APP_BASE_URL=http://localhost:3000
-AUTH0_DOMAIN=your-tenant.auth0.com
-AUTH0_CLIENT_ID=your-client-id
-AUTH0_CLIENT_SECRET=your-client-secret
-```
-
-Generate secret: `openssl rand -hex 32`
-
-**Important:** Add `.env.local` to `.gitignore`
-
-### 3. Create Auth0 Client and Middleware
-
-**Detect project structure first:** Check whether the project uses a `src/` directory (i.e. `src/app/` or `src/pages/` exists). This determines where to place files:
-- **With `src/`:** `src/lib/auth0.ts`, `src/middleware.ts` (or `src/proxy.ts` for Next.js 16)
-- **Without `src/`:** `lib/auth0.ts`, `middleware.ts` (or `proxy.ts` for Next.js 16)
-
-Create `lib/auth0.ts` (or `src/lib/auth0.ts` if using the `src/` convention):
-
-```typescript
-import { Auth0Client } from '@auth0/nextjs-auth0/server';
-
-export const auth0 = new Auth0Client({
-  domain: process.env.AUTH0_DOMAIN!,
-  clientId: process.env.AUTH0_CLIENT_ID!,
-  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
-  secret: process.env.AUTH0_SECRET!,
-  appBaseUrl: process.env.APP_BASE_URL!,
-});
-```
-
-**Middleware Configuration (Next.js 15 vs 16):**
-
-**Next.js 15** - Create `middleware.ts` (at project root, or `src/middleware.ts` if using `src/`):
-
-```typescript
-import { NextRequest } from 'next/server';
-import { auth0 } from '@/lib/auth0';
-
-export async function middleware(request: NextRequest) {
-  return await auth0.middleware(request);
-}
-
-export const config = {
-  matcher: [
-    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
-  ],
-};
-```
-
-**Next.js 16** - You have two options:
-
-**Option 1:** Use `middleware.ts` (same as Next.js 15, same `src/` placement rules):
-
-```typescript
-import { NextRequest } from 'next/server';
-import { auth0 } from '@/lib/auth0';
-
-export async function middleware(request: NextRequest) {
-  return await auth0.middleware(request);
-}
-
-export const config = {
-  matcher: [
-    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
-  ],
-};
-```
-
-**Option 2:** Use `proxy.ts` (at project root, or `src/proxy.ts` if using `src/`):
-
-```typescript
-import { NextRequest } from 'next/server';
-import { auth0 } from '@/lib/auth0';
-
-export async function proxy(request: NextRequest) {
-  return await auth0.middleware(request);
-}
-
-export const config = {
-  matcher: [
-    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
-  ],
-};
-```
-
-This automatically creates endpoints:
-- `/auth/login` - Login
-- `/auth/logout` - Logout
-- `/auth/callback` - OAuth callback
-- `/auth/profile` - User profile
-
-### 4. Add User Context (Optional)
-
-**Note:** In v4, wrapping with `<Auth0Provider>` is optional. Only needed if you want to pass an initial user during server rendering to `useUser()`.
-
-**App Router** - Optionally wrap app in `app/layout.tsx`:
-
-```typescript
-import { Auth0Provider } from '@auth0/nextjs-auth0/client';
-import { auth0 } from '@/lib/auth0';
-
-export default async function RootLayout({ children }: { children: React.ReactNode }) {
-  const session = await auth0.getSession();
-
-  return (
-    <html>
-      <body>
-        <Auth0Provider user={session?.user}>{children}</Auth0Provider>
-      </body>
-    </html>
-  );
-}
-```
-
-**Pages Router** - Optionally wrap app in `pages/_app.tsx`:
-
-```typescript
-import { Auth0Provider } from '@auth0/nextjs-auth0/client';
-import type { AppProps } from 'next/app';
-
-export default function App({ Component, pageProps }: AppProps) {
-  return (
-    <Auth0Provider user={pageProps.user}>
-      <Component {...pageProps} />
-    </Auth0Provider>
-  );
-}
-```
-
-### 5. Add Authentication UI
-
-**Client Component** (works in both routers):
-
-```typescript
-'use client'; // Only needed for App Router
-
-import { useUser } from '@auth0/nextjs-auth0/client';
-
-export default function Profile() {
-  const { user, isLoading } = useUser();
-
-  if (isLoading) return <div>Loading...</div>;
-
-  if (user) {
-    return (
-      <div>
-        <img src={user.picture} alt={user.name} />
-        <h2>Welcome, {user.name}!</h2>
-        <a href="/auth/logout">Logout</a>
-      </div>
-    );
-  }
-
-  return <a href="/auth/login">Login</a>;
-}
-```
-
-### 6. Test Authentication
-
-Start your dev server:
-
-```bash
-npm run dev
-```
-
-Visit `http://localhost:3000` and test the login flow.
-
----
-
-## Detailed Documentation
-
-- **[Setup Guide](references/setup.md)** - Automated setup scripts, environment configuration, Auth0 CLI usage
-- **[Integration Guide](references/integration.md)** - Server-side auth, protected routes, API routes, middleware
-- **[API Reference](references/api.md)** - Complete SDK API, hooks, helpers, session management
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Using v3 environment variables | v4 uses `APP_BASE_URL` and `AUTH0_DOMAIN` (not `AUTH0_BASE_URL` or `AUTH0_ISSUER_BASE_URL`) |
-| Forgot to add callback URL in Auth0 Dashboard | Add `/auth/callback` to Allowed Callback URLs (e.g., `http://localhost:3000/auth/callback`) |
-| Missing middleware configuration | v4 requires middleware to mount auth routes - create `middleware.ts` (Next.js 15+16) or `proxy.ts` (Next.js 16 only) with `auth0.middleware()` |
-| Wrong route paths | v4 uses `/auth/login` not `/api/auth/login` - routes drop the `/api` prefix |
-| Missing or weak AUTH0_SECRET | Generate secure secret with `openssl rand -hex 32` and store in .env.local |
-| Using .env instead of .env.local | Next.js requires .env.local for local secrets, and .env.local should be in .gitignore |
-| App created as SPA type in Auth0 | Must be Regular Web Application type for Next.js |
-| Using removed v3 helpers | v4 removed `withPageAuthRequired` and `withApiAuthRequired` - use `getSession()` instead |
-| Using useUser in Server Component | useUser is client-only, use `auth0.getSession()` for Server Components |
-| AUTH0_DOMAIN includes https:// | v4 `AUTH0_DOMAIN` should be just the domain (e.g., `example.auth0.com`), no scheme |
-
----
-
-## Related Skills
-
-- `auth0-quickstart` - Basic Auth0 setup
-- `auth0-migration` - Migrate from another auth provider
-- `auth0-mfa` - Add Multi-Factor Authentication
-
----
-
-## Quick Reference
-
-**V4 Setup:**
-- Detect `src/` convention: check if `src/app/` or `src/pages/` exists — place all files inside `src/` if so
-- Create `lib/auth0.ts` (or `src/lib/auth0.ts`) with `Auth0Client` instance
-- Create middleware configuration (required):
-  - Next.js 15: `middleware.ts` (or `src/middleware.ts`) with `middleware()` function
-  - Next.js 16: `middleware.ts` with `middleware()` OR `proxy.ts` with `proxy()` function (same `src/` rules)
-- Optional: Wrap with `<Auth0Provider>` for SSR user
-
-**Client-Side Hooks:**
-- `useUser()` - Get user in client components
-- `user` - User profile object
-- `isLoading` - Loading state
-
-**Server-Side Methods:**
-- `auth0.getSession()` - Get session in Server Components/API routes/middleware
-- `auth0.getAccessToken()` - Get access token for calling APIs
-
-**Common Use Cases:**
-- Login/Logout links → Use `/auth/login` and `/auth/logout` paths (see Step 5)
-- Protected pages (App Router) → [Integration Guide](references/integration.md#protected-pages-app-router)
-- Protected pages (Pages Router) → [Integration Guide](references/integration.md#protected-pages-pages-router)
-- API routes with auth → [Integration Guide](references/integration.md#protected-api-routes)
-- Middleware protection → [Integration Guide](references/integration.md#middleware)
-
----
-
-## References
-
-- [Auth0 Next.js SDK Documentation](https://auth0.com/docs/libraries/nextjs)
-- [Auth0 Next.js Quickstart](https://auth0.com/docs/quickstart/webapp/nextjs)
-- [SDK GitHub Repository](https://github.com/auth0/nextjs-auth0)
diff --git a/main/.mintlify/skills/auth0-nuxt/SKILL.md b/main/.mintlify/skills/auth0-nuxt/SKILL.md
deleted file mode 100644
index 0629d52879..0000000000
--- a/main/.mintlify/skills/auth0-nuxt/SKILL.md
+++ /dev/null
@@ -1,227 +0,0 @@
----
-name: auth0-nuxt
-description: Use when implementing Auth0 authentication in Nuxt 3/4 applications, configuring session management, protecting routes with middleware, or integrating API access tokens - provides setup patterns, composable usage, and security best practices for the @auth0/auth0-nuxt SDK
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 Nuxt SDK
-
-## Overview
-
-Server-side session authentication for Nuxt 3/4. NOT the same as @auth0/auth0-vue (client-side SPA).
-
-**Core principle:** Uses server-side encrypted cookie sessions, not client-side tokens.
-
-## When to Use
-
-**Use this when:**
-- Building Nuxt 3/4 applications with server-side rendering (Node.js 20 LTS+)
-- Need secure session management with encrypted cookies
-- Protecting server routes and API endpoints
-- Accessing Auth0 Management API or custom APIs
-
-**Don't use this when:**
-- Using Nuxt 2 (not supported - use different Auth0 SDK)
-- Building pure client-side SPA without server (use @auth0/auth0-vue instead)
-- Using non-Auth0 authentication provider
-- Static site generation only (SSG) without server runtime
-
-## Critical Mistakes to Avoid
-
-| Mistake | Solution |
-|---------|----------|
-| Installing `@auth0/auth0-vue` or `@auth0/auth0-spa-js` | Use `@auth0/auth0-nuxt` |
-| Auth0 app type "Single Page Application" | Use "Regular Web Application" |
-| Env vars: `VITE_AUTH0_*` or `VUE_APP_AUTH0_*` | Use `NUXT_AUTH0_*` prefix |
-| Using `useUser()` for security checks | Use `useAuth0(event).getSession()` server-side |
-| Missing callback URLs in Auth0 Dashboard | Add `http://localhost:3000/auth/callback` |
-| Weak/missing session secret | Generate: `openssl rand -hex 64` |
-
-## Quick Setup
-
-```bash
-# 1. Install
-npm install @auth0/auth0-nuxt
-
-# 2. Generate secret
-openssl rand -hex 64
-```
-
-```bash
-# 3. .env
-NUXT_AUTH0_DOMAIN=your-tenant.auth0.com
-NUXT_AUTH0_CLIENT_ID=your-client-id
-NUXT_AUTH0_CLIENT_SECRET=your-client-secret
-NUXT_AUTH0_SESSION_SECRET=<from-openssl>
-NUXT_AUTH0_APP_BASE_URL=http://localhost:3000
-NUXT_AUTH0_AUDIENCE=https://your-api  # optional
-```
-
-```typescript
-// 4. nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['@auth0/auth0-nuxt'],
-  runtimeConfig: {
-    auth0: {
-      domain: '',
-      clientId: '',
-      clientSecret: '',
-      sessionSecret: '',
-      appBaseUrl: 'http://localhost:3000',
-      audience: '',  // optional
-    },
-  },
-})
-```
-
-## Built-in Routes
-
-The SDK automatically mounts these routes:
-
-| Route | Method | Purpose |
-|-------|--------|---------|
-| `/auth/login` | GET | Initiates login flow. Supports `?returnTo=/path` parameter |
-| `/auth/callback` | GET | Handles Auth0 callback after login |
-| `/auth/logout` | GET | Logs user out and redirects to Auth0 logout |
-| `/auth/backchannel-logout` | POST | Receives logout tokens for back-channel logout |
-
-**Customize:** Pass `routes: { login, callback, logout, backchannelLogout }` or `mountRoutes: false` to module config.
-
-## Composables
-
-| Composable | Context | Usage |
-|------------|---------|-------|
-| `useAuth0(event)` | Server-side | Access `getUser()`, `getSession()`, `getAccessToken()`, `logout()` |
-| `useUser()` | Client-side | Display user data only. **Never use for security checks** |
-
-```typescript
-// Server example
-const auth0 = useAuth0(event);
-const session = await auth0.getSession();
-```
-
-```vue
-<script setup>
-const user = useUser();
-</script>
-
-<template>
-  <div v-if="user">Welcome {{ user.name }}</div>
-<template>
-```
-
-## Protecting Routes
-
-**Three layers:** Route middleware (client), server middleware (SSR), API guards.
-
-```typescript
-// middleware/auth.ts - Client navigation
-export default defineNuxtRouteMiddleware((to) => {
-  if (!useUser().value) return navigateTo(`/auth/login?returnTo=${encodeURIComponent(to.path)}`);
-});
-```
-
-```typescript
-// server/middleware/auth.server.ts - SSR protection
-export default defineEventHandler(async (event) => {
-  const url = getRequestURL(event);
-  const auth0Client = useAuth0(event);
-  const session = await auth0Client.getSession();
-  if (!session)  {
-    return sendRedirect(event, `/auth/login?returnTo=${encodeURIComponent(url.pathname)}`);
-  }
-});
-```
-
-```typescript
-// server/api/protected.ts - API endpoint protection
-export default defineEventHandler(async (event) => {
-  const auth0Client = useAuth0(event);
-  const session = await auth0Client.getSession();
-
-  if (!session) {
-    throw createError({
-      statusCode: 401,
-      statusMessage: 'Unauthorized'
-    });
-  }
-
-  return { data: 'protected data' };
-});
-```
-
-**For role-based, permission-based, and advanced patterns:** [route-protection.md](./references/route-protection.md)
-
-## Session Management
-
-### Stateless (Default)
-Uses encrypted, chunked cookies. No configuration needed.
-
-### Stateful (Redis, MongoDB, etc.)
-For larger sessions or distributed systems:
-
-```typescript
-// nuxt.config.ts
-modules: [
-  ['@auth0/auth0-nuxt', {
-    sessionStoreFactoryPath: '~/server/utils/session-store-factory.ts'
-  }]
-]
-```
-
-**For complete session store implementations, see:** [session-stores.md](./references/session-stores.md)
-
-## API Integration
-
-Configure audience for API access tokens:
-
-```typescript
-// nuxt.config.ts
-runtimeConfig: {
-  auth0: {
-    audience: 'https://your-api-identifier',
-  }
-}
-```
-
-Retrieve tokens server-side:
-
-```typescript
-// server/api/call-api.ts
-export default defineEventHandler(async (event) => {
-  const auth0Client = useAuth0(event);
-  const { accessToken } = await auth0Client.getAccessToken();
-
-  return await $fetch('https://api.example.com/data', {
-    headers: {
-      Authorization: `Bearer ${accessToken}`
-    }
-  });
-});
-```
-
-## Security Checklist
-
-- ✅ Server-side validation only (never trust `useUser()`)
-- ✅ HTTPS in production
-- ✅ Strong session secret (`openssl rand -hex 64`)
-- ✅ Never commit `.env` files
-- ✅ Stateful sessions for PII/large data
-
-## Troubleshooting
-
-| Error | Solution |
-|-------|----------|
-| "Module not found" | Install `@auth0/auth0-nuxt`, not `@auth0/auth0-vue` |
-| "Missing domain/clientId/clientSecret" | Check `NUXT_AUTH0_` prefix, `.env` location, `runtimeConfig` |
-| "Redirect URI mismatch" | Match Auth0 Dashboard callback to `appBaseUrl + /auth/callback` |
-| "useAuth0 is not defined" | Use only in server context with H3 event object |
-| Cookies too large | Use stateful sessions or reduce scopes |
-
-## Additional Resources
-
-**Guides:** [Route Protection Patterns](./references/route-protection.md) • [Custom Session Stores](./references/session-stores.md) • [Common Examples](./references/examples.md)
-
-**Links:** [Auth0-Nuxt GitHub](https://github.com/auth0/auth0-nuxt) • [Auth0 Docs](https://auth0.com/docs) • [Nuxt Modules](https://nuxt.com/modules)
diff --git a/main/.mintlify/skills/auth0-quickstart/SKILL.md b/main/.mintlify/skills/auth0-quickstart/SKILL.md
deleted file mode 100644
index 48e1b50f97..0000000000
--- a/main/.mintlify/skills/auth0-quickstart/SKILL.md
+++ /dev/null
@@ -1,234 +0,0 @@
----
-name: auth0-quickstart
-description: Use when adding authentication or login to any app - detects your stack (React, Next.js, Vue, Nuxt, Angular, Express, Fastify, React Native), sets up an Auth0 account if needed, and routes to the correct SDK setup workflow.
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 Quickstart
-
-Detect your framework and get started with Auth0 authentication.
-
----
-
-## Step 1: Detect Your Framework
-
-**Run this command to identify your framework:**
-
-```bash
-# Check package.json dependencies
-cat package.json | grep -E "react|next|vue|nuxt|angular|express|fastify|@nestjs"
-
-# Or check project files
-ls -la | grep -E "angular.json|vue.config.js|next.config"
-```
-
-**Framework Detection Table:**
-
-| Framework | Detection | Skill to Use |
-|-----------|-----------|--------------|
-| React (Vite/CRA) | `"react"` in package.json, no Next.js | `auth0-react` |
-| Next.js | `"next"` in package.json | `auth0-nextjs` |
-| Vue.js | `"vue"` in package.json, no Nuxt | `auth0-vue` |
-| Nuxt | `"nuxt"` in package.json | `auth0-nuxt` |
-| Angular | `angular.json` exists or `"@angular/core"` | `auth0-angular` |
-| Express.js | `"express"` in package.json | `auth0-express` |
-| Fastify (web app) | `"fastify"` in package.json, has `@fastify/view` | `auth0-fastify` |
-| Fastify (API) | `"fastify"` in package.json, no view engine | `auth0-fastify-api` |
-| React Native | `"react-native"` or `"expo"` in package.json | `auth0-react-native` |
-
-**Don't see your framework?** See Tier 2 Frameworks below.
-
----
-
-## Step 2: Auth0 Account Setup
-
-### Install Auth0 CLI
-
-**macOS/Linux:**
-```bash
-brew install auth0/auth0-cli/auth0
-```
-
-**Windows:**
-```bash
-scoop install auth0
-# Or: choco install auth0-cli
-```
-
-**Full installation guide:** See [CLI Reference](references/cli.md#installation)
-
-### Login to Auth0
-
-```bash
-auth0 login
-```
-
-This opens your browser to authenticate with Auth0.
-
----
-
-## Step 3: Create Auth0 Application
-
-Choose application type based on your framework:
-
-**Single Page Applications (React, Vue, Angular):**
-```bash
-auth0 apps create --name "My App" --type spa \
-  --callbacks "http://localhost:3000" \
-  --logout-urls "http://localhost:3000" \
-  --metadata "created_by=agent_skills"
-```
-
-**Regular Web Apps (Next.js, Nuxt, Express, Fastify):**
-```bash
-auth0 apps create --name "My App" --type regular \
-  --callbacks "http://localhost:3000/api/auth/callback" \
-  --logout-urls "http://localhost:3000" \
-  --metadata "created_by=agent_skills"
-```
-
-**Native Apps (React Native):**
-```bash
-auth0 apps create --name "My App" --type native \
-  --callbacks "myapp://callback" \
-  --logout-urls "myapp://logout" \
-  --metadata "created_by=agent_skills"
-```
-
-**Get your credentials:**
-```bash
-auth0 apps list          # Find your app
-auth0 apps show <app-id> # Get client ID and secret
-```
-
-**More CLI commands:** See [CLI Reference](references/cli.md)
-
----
-
-## Step 4: Use Framework-Specific Skill
-
-Based on your framework detection, use the appropriate skill:
-
-### Tier 1 Frameworks (Dedicated Skills)
-
-**Frontend:**
-- **`auth0-react`** - React SPAs (Vite, Create React App)
-- **`auth0-nextjs`** - Next.js (App Router and Pages Router)
-- **`auth0-vue`** - Vue.js 3 applications
-- **`auth0-nuxt`** - Nuxt 3/4 applications
-- **`auth0-angular`** - Angular 12+ applications
-
-**Backend:**
-- **`auth0-express`** - Express.js web applications
-- **`auth0-fastify`** - Fastify web applications
-- **`auth0-fastify-api`** - Fastify API authentication
-
-**Mobile:**
-- **`auth0-react-native`** - React Native and Expo (iOS/Android)
-
-### Tier 2 Frameworks (Use Auth0 Docs)
-
-Not yet available as separate skills. Use Auth0 documentation:
-
-**Frontend:**
-- [SvelteKit](https://auth0.com/docs/quickstart/webapp/sveltekit)
-- [Remix](https://auth0.com/docs/quickstart/webapp/remix)
-
-**Backend:**
-- [Flask (Python)](https://auth0.com/docs/quickstart/webapp/python)
-- [FastAPI (Python)](https://auth0.com/docs/quickstart/backend/python)
-- [Django (Python)](https://auth0.com/docs/quickstart/webapp/django)
-- [Rails (Ruby)](https://auth0.com/docs/quickstart/webapp/rails)
-- [Laravel (PHP)](https://auth0.com/docs/quickstart/webapp/laravel)
-- [Go](https://auth0.com/docs/quickstart/webapp/golang)
-- [ASP.NET Core](https://auth0.com/docs/quickstart/webapp/aspnet-core)
-- [Spring Boot](https://auth0.com/docs/quickstart/webapp/java-spring-boot)
-
-**Mobile:**
-- [iOS (Swift)](https://auth0.com/docs/quickstart/native/ios-swift)
-- [Android (Kotlin)](https://auth0.com/docs/quickstart/native/android)
-- [Flutter](https://auth0.com/docs/quickstart/native/flutter)
-
----
-
-## Migration from Other Providers
-
-**Migrating from another auth provider?** Use the **`auth0-migration`** skill.
-
-The migration skill covers:
-- User export from Firebase, Cognito, Supabase, Clerk, etc.
-- Bulk import to Auth0
-- Code migration patterns (before/after examples)
-- JWT validation updates
-- Gradual migration strategies
-
----
-
-## Reference Documentation
-
-### Environment Variables
-Framework-specific environment variable setup:
-- [Vite, Create React App, Angular](references/environments.md#single-page-applications-spas)
-- [Next.js, Express](references/environments.md#server-side-applications)
-- [React Native, Expo](references/environments.md#mobile-applications)
-
-### Auth0 Concepts
-Core concepts and troubleshooting:
-- [Application Types](references/concepts.md#application-types)
-- [Key Terms](references/concepts.md#key-terms)
-- [OAuth Flows](references/concepts.md#oauth-flows)
-- [Troubleshooting](references/concepts.md#troubleshooting)
-- [Security Best Practices](references/concepts.md#security-best-practices)
-
-### CLI Commands
-Complete Auth0 CLI reference:
-- [CLI Installation](references/cli.md#installation)
-- [Creating Applications](references/cli.md#creating-applications)
-- [User Management](references/cli.md#user-management)
-- [Testing & Debugging](references/cli.md#testing--debugging)
-- [Command Quick Reference](references/cli.md#command-quick-reference)
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Wrong application type | SPAs need "Single Page Application", server apps need "Regular Web Application", mobile needs "Native" |
-| Callback URL not configured | Add your app's callback URL to Allowed Callback URLs in Auth0 Dashboard |
-| Using wrong credentials | Client Secret only needed for Regular Web Apps, not SPAs |
-| Hardcoding credentials in code | Always use environment variables, never commit secrets to git |
-| Not testing locally first | Set up localhost URLs in Auth0 before deploying to production |
-| Mixing application types | Don't use SPA SDK for server-side apps or vice versa |
-
----
-
-## Related Skills
-
-### Core Integration
-- `auth0-migration` - Migrate from other auth providers
-
-### SDK Skills
-- `auth0-react` - React SPA integration
-- `auth0-nextjs` - Next.js integration
-- `auth0-vue` - Vue.js integration
-- `auth0-nuxt` - Nuxt 3/4 integration
-- `auth0-angular` - Angular integration
-- `auth0-express` - Express.js integration
-- `auth0-fastify` - Fastify web app integration
-- `auth0-fastify-api` - Fastify API integration
-- `auth0-react-native` - React Native/Expo integration
-
-### Advanced Features
-- `auth0-mfa` - Multi-Factor Authentication
-
----
-
-## References
-
-- [Auth0 Documentation](https://auth0.com/docs)
-- [Auth0 Quickstart Guides](https://auth0.com/docs/quickstart)
-- [Auth0 CLI Documentation](https://auth0.github.io/auth0-cli/)
-- [Auth0 Community Forum](https://community.auth0.com/)
diff --git a/main/.mintlify/skills/auth0-react-native/SKILL.md b/main/.mintlify/skills/auth0-react-native/SKILL.md
deleted file mode 100644
index b07a2df49a..0000000000
--- a/main/.mintlify/skills/auth0-react-native/SKILL.md
+++ /dev/null
@@ -1,250 +0,0 @@
----
-name: auth0-react-native
-description: Use when adding authentication to React Native or Expo mobile apps (iOS/Android) with biometric support - integrates react-native-auth0 SDK with native deep linking
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 React Native Integration
-
-Add authentication to React Native and Expo mobile applications using react-native-auth0.
-
----
-
-## Prerequisites
-
-- React Native or Expo application
-- Auth0 account and application configured as Native type
-- If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first
-
-## When NOT to Use
-
-- **React web applications** - Use `auth0-react` skill for SPAs (Vite/CRA)
-- **React Server Components** - Use `auth0-nextjs` for Next.js applications
-- **Non-React native apps** - Use platform-specific SDKs (Swift for iOS, Kotlin for Android)
-- **Backend APIs** - Use JWT validation libraries for your server language
-
----
-
-## Quick Start Workflow
-
-### 1. Install SDK
-
-**Expo:**
-```bash
-npx expo install react-native-auth0
-```
-
-**React Native CLI:**
-```bash
-npm install react-native-auth0
-npx pod-install  # iOS only
-```
-
-### 2. Configure Environment
-
-**For automated setup with Auth0 CLI**, see [Setup Guide](references/setup.md) for complete scripts.
-
-**For manual setup:**
-
-Create `.env`:
-
-```bash
-AUTH0_DOMAIN=your-tenant.auth0.com
-AUTH0_CLIENT_ID=your-client-id
-```
-
-### 3. Configure Native Platforms
-
-**iOS** - Update `ios/{YourApp}/Info.plist`:
-
-```xml
-<key>CFBundleURLTypes</key>
-<array>
-  <dict>
-    <key>CFBundleTypeRole</key>
-    <string>None</string>
-    <key>CFBundleURLName</key>
-    <string>auth0</string>
-    <key>CFBundleURLSchemes</key>
-    <array>
-      <string>$(PRODUCT_BUNDLE_IDENTIFIER).auth0</string>
-    </array>
-  </dict>
-</array>
-```
-
-**Android** - Update `android/app/src/main/AndroidManifest.xml`:
-
-```xml
-<activity
-    android:name="com.auth0.android.provider.RedirectActivity"
-    android:exported="true">
-    <intent-filter>
-        <action android:name="android.intent.action.VIEW" />
-        <category android:name="android.intent.category.DEFAULT" />
-        <category android:name="android.intent.category.BROWSABLE" />
-        <data
-            android:host="YOUR_AUTH0_DOMAIN"
-            android:pathPrefix="/android/${applicationId}/callback"
-            android:scheme="${applicationId}" />
-    </intent-filter>
-</activity>
-```
-
-**Expo** - Update `app.json`:
-
-```json
-{
-  "expo": {
-    "scheme": "your-app-scheme",
-    "ios": {
-      "bundleIdentifier": "com.yourcompany.yourapp"
-    },
-    "android": {
-      "package": "com.yourcompany.yourapp"
-    }
-  }
-}
-```
-
-### 4. Add Authentication with Auth0Provider
-
-Wrap your app with `Auth0Provider`:
-
-```typescript
-import React from 'react';
-import { Auth0Provider } from 'react-native-auth0';
-import App from './App';
-
-export default function Root() {
-  return (
-    <Auth0Provider
-      domain={process.env.AUTH0_DOMAIN}
-      clientId={process.env.AUTH0_CLIENT_ID}
-    >
-      <App />
-    </Auth0Provider>
-  );
-}
-```
-
-### 5. Use the useAuth0 Hook
-
-```typescript
-import React from 'react';
-import { View, Button, Text, ActivityIndicator } from 'react-native';
-import { useAuth0 } from 'react-native-auth0';
-
-export default function App() {
-  const { user, authorize, clearSession, isLoading } = useAuth0();
-
-  const login = async () => {
-    try {
-      await authorize({
-        scope: 'openid profile email'
-      });
-    } catch (error) {
-      console.error('Login error:', error);
-    }
-  };
-
-  const logout = async () => {
-    try {
-      await clearSession();
-    } catch (error) {
-      console.error('Logout error:', error);
-    }
-  };
-
-  if (isLoading) {
-    return <ActivityIndicator />;
-  }
-
-  return (
-    <View>
-      {user ? (
-        <>
-          <Text>Welcome, {user.name}!</Text>
-          <Text>{user.email}</Text>
-          <Button title="Logout" onPress={logout} />
-        </>
-      ) : (
-        <Button title="Login" onPress={login} />
-      )}
-    </View>
-  );
-}
-```
-
-### 6. Test Authentication
-
-**Expo:**
-```bash
-npx expo start
-```
-
-**React Native:**
-```bash
-npx react-native run-ios
-# or
-npx react-native run-android
-```
-
----
-
-## Detailed Documentation
-
-- **[Setup Guide](references/setup.md)** - Automated setup, native configuration, deep linking
-- **[Patterns Guide](references/patterns.md)** - Secure storage, biometric auth, token refresh
-- **[API Reference](references/api.md)** - Complete SDK API, methods, configuration options
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Forgot to wrap app with Auth0Provider | All components using useAuth0() must be children of Auth0Provider |
-| Forgot to configure deep linking | Add URL scheme to iOS Info.plist and Android AndroidManifest.xml (see Step 3) |
-| Callback URL mismatch | Ensure callback URL in Auth0 Dashboard matches your app's URL scheme (e.g., `com.yourapp.auth0://YOUR_DOMAIN/ios/com.yourapp/callback`) |
-| iOS build fails after install | Run `npx pod-install` to link native dependencies |
-| App created as SPA type in Auth0 | Must be Native application type for mobile apps |
-| Not handling auth errors | Wrap authorize/clearSession calls in try-catch blocks |
-| Deep link not working on Android | Verify `android:exported="true"` is set on RedirectActivity |
-
----
-
-## Related Skills
-
-- `auth0-quickstart` - Basic Auth0 setup
-- `auth0-migration` - Migrate from another auth provider
-- `auth0-mfa` - Add Multi-Factor Authentication
-
----
-
-## Quick Reference
-
-**Core Hook API:**
-- `useAuth0()` - Main hook for authentication
-- `authorize()` - Initiate login
-- `clearSession()` - Logout
-- `user` - User profile object
-- `getCredentials()` - Get tokens for API calls
-- `isLoading` - Loading state
-
-**Common Use Cases:**
-- Login/Logout → See Step 5 above
-- Secure token storage → Automatic with `Auth0Provider`
-- Biometric authentication → [Patterns Guide](references/patterns.md#biometric-auth)
-- API calls with tokens → [Patterns Guide](references/patterns.md#calling-apis)
-- Token refresh → Automatic with `getCredentials()`
-
----
-
-## References
-
-- [Auth0 React Native SDK Documentation](https://auth0.com/docs/libraries/react-native-auth0)
-- [Auth0 React Native Quickstart](https://auth0.com/docs/quickstart/native/react-native)
-- [SDK GitHub Repository](https://github.com/auth0/react-native-auth0)
diff --git a/main/.mintlify/skills/auth0-react/SKILL.md b/main/.mintlify/skills/auth0-react/SKILL.md
deleted file mode 100644
index e89c866c89..0000000000
--- a/main/.mintlify/skills/auth0-react/SKILL.md
+++ /dev/null
@@ -1,188 +0,0 @@
----
-name: auth0-react
-description: Use when adding authentication to React applications (login, logout, user sessions, protected routes) - integrates @auth0/auth0-react SDK for SPAs with Vite or Create React App
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 React Integration
-
-Add authentication to React single-page applications using @auth0/auth0-react.
-
----
-
-## Prerequisites
-
-- React 16.11+ application (Vite or Create React App) - supports React 16, 17, 18, and 19
-- Auth0 account and application configured
-- If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first
-
-## When NOT to Use
-
-- **Next.js applications** - Use `auth0-nextjs` skill for both App Router and Pages Router
-- **React Native mobile apps** - Use `auth0-react-native` skill for iOS/Android
-- **Server-side rendered React** - Use framework-specific SDK (Next.js, Remix, etc.)
-- **Embedded login** - This SDK uses Auth0 Universal Login (redirect-based)
-- **Backend API authentication** - Use express-openid-connect or JWT validation instead
-
----
-
-## Quick Start Workflow
-
-### 1. Install SDK
-
-```bash
-npm install @auth0/auth0-react
-```
-
-### 2. Configure Environment
-
-**For automated setup with Auth0 CLI**, see [Setup Guide](references/setup.md) for complete scripts.
-
-**For manual setup:**
-
-Create `.env` file:
-
-**Vite:**
-```bash
-VITE_AUTH0_DOMAIN=your-tenant.auth0.com
-VITE_AUTH0_CLIENT_ID=your-client-id
-```
-
-**Create React App:**
-```bash
-REACT_APP_AUTH0_DOMAIN=your-tenant.auth0.com
-REACT_APP_AUTH0_CLIENT_ID=your-client-id
-```
-
-### 3. Wrap App with Auth0Provider
-
-Update `src/main.tsx` (Vite) or `src/index.tsx` (CRA):
-
-```tsx
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { Auth0Provider } from '@auth0/auth0-react';
-import App from './App';
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <Auth0Provider
-      domain={import.meta.env.VITE_AUTH0_DOMAIN} // or process.env.REACT_APP_AUTH0_DOMAIN
-      clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
-      authorizationParams={{
-        redirect_uri: window.location.origin
-      }}
-    >
-      <App />
-    </Auth0Provider>
-  </React.StrictMode>
-);
-```
-
-### 4. Add Authentication UI
-
-```tsx
-import { useAuth0 } from '@auth0/auth0-react';
-
-export function LoginButton() {
-  const { loginWithRedirect, logout, isAuthenticated, user, isLoading } = useAuth0();
-
-  if (isLoading) return <div>Loading...</div>;
-
-  if (isAuthenticated) {
-    return (
-      <div>
-        <span>Welcome, {user?.name}</span>
-        <button onClick={() => logout({ logoutParams: { returnTo: window.location.origin } })}>
-          Logout
-        </button>
-      </div>
-    );
-  }
-
-  return <button onClick={() => loginWithRedirect()}>Login</button>;
-}
-```
-
-### 5. Test Authentication
-
-Start your dev server and test the login flow:
-
-```bash
-npm run dev  # Vite
-# or
-npm start    # CRA
-```
-
----
-
-## Detailed Documentation
-
-- **[Setup Guide](references/setup.md)** - Automated setup scripts (Bash/PowerShell), CLI commands, manual configuration
-- **[Integration Guide](references/integration.md)** - Protected routes, API calls, error handling, advanced patterns
-- **[API Reference](references/api.md)** - Complete SDK API, configuration options, hooks reference, testing strategies
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Forgot to add redirect URI in Auth0 Dashboard | Add your application URL (e.g., `http://localhost:3000`, `https://app.example.com`) to Allowed Callback URLs in Auth0 Dashboard |
-| Using wrong env var prefix | Vite uses `VITE_` prefix, Create React App uses `REACT_APP_` |
-| Not handling loading state | Always check `isLoading` before rendering auth-dependent UI |
-| Storing tokens in localStorage | Never manually store tokens - SDK handles secure storage automatically |
-| Missing Auth0Provider wrapper | Entire app must be wrapped in `<Auth0Provider>` |
-| Provider not at root level | Auth0Provider must wrap all components that use auth hooks |
-| Wrong import path for env vars | Vite uses `import.meta.env.VITE_*`, CRA uses `process.env.REACT_APP_*` |
-| Using `acr_values` redirect for in-app MFA | Use `useAuth0().mfa` API for in-app enrollment/challenge/verify flows |
-| Not catching `MfaRequiredError` | Wrap `getAccessTokenSilently` in try/catch and check `instanceof MfaRequiredError` |
-| Making direct HTTP calls to MFA endpoints | Use the `mfa` property from `useAuth0()` — it handles token management automatically |
-| Forgetting refresh tokens for step-up MFA | Set `useRefreshTokens={true}` on Auth0Provider when using `interactiveErrorHandler="popup"` |
-
----
-
-## Related Skills
-
-- `auth0-quickstart` - Basic Auth0 setup
-- `auth0-migration` - Migrate from another auth provider
-- `auth0-mfa` - Add Multi-Factor Authentication
-
----
-
-## Quick Reference
-
-**Core Hooks:**
-- `useAuth0()` - Main authentication hook
-- `isAuthenticated` - Check if user is logged in
-- `user` - User profile information
-- `loginWithRedirect()` - Initiate login
-- `logout()` - Log out user
-- `getAccessTokenSilently()` - Get access token for API calls
-- `mfa` - MFA API client for enrollment, challenge, and verification
-  - `mfa.getAuthenticators(mfaToken)` - List enrolled authenticators
-  - `mfa.getEnrollmentFactors(mfaToken)` - Get available enrollment factors
-  - `mfa.enroll(params)` - Enroll new authenticator (OTP, SMS, Email, Voice, Push)
-  - `mfa.challenge(params)` - Initiate MFA challenge
-  - `mfa.verify(params)` - Verify MFA challenge and complete authentication
-
-**MFA Error Types (import from `@auth0/auth0-react`):**
-- `MfaRequiredError` - Thrown by `getAccessTokenSilently` when MFA is needed (has `mfa_token` and `mfa_requirements`)
-- `MfaEnrollmentError`, `MfaChallengeError`, `MfaVerifyError` - Thrown by respective `mfa.*` methods
-
-**Common Use Cases:**
-- Login/Logout buttons → See Step 4 above
-- Protected routes → [Integration Guide](references/integration.md#protected-routes)
-- API calls with tokens → [Integration Guide](references/integration.md#calling-apis)
-- Error handling → [Integration Guide](references/integration.md#error-handling)
-- MFA handling → [Integration Guide](references/integration.md#mfa-handling)
-
----
-
-## References
-
-- [Auth0 React SDK Documentation](https://auth0.com/docs/libraries/auth0-react)
-- [Auth0 React Quickstart](https://auth0.com/docs/quickstart/spa/react)
-- [SDK GitHub Repository](https://github.com/auth0/auth0-react)
diff --git a/main/.mintlify/skills/auth0-spa-js/SKILL.md b/main/.mintlify/skills/auth0-spa-js/SKILL.md
deleted file mode 100644
index 846b24e928..0000000000
--- a/main/.mintlify/skills/auth0-spa-js/SKILL.md
+++ /dev/null
@@ -1,204 +0,0 @@
----
-name: auth0-spa-js
-description: Use when adding authentication to Vanilla JS, Svelte, or any framework-agnostic single-page applications - integrates @auth0/auth0-spa-js SDK for SPAs without framework-specific wrappers
-license: Proprietary
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 SPA JS Integration
-
-Add authentication to any browser-based single-page application using `@auth0/auth0-spa-js` — the low-level Auth0 SDK for Vanilla JS, Svelte, SolidJS, and any SPA not using React, Angular, or Vue.
-
-> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
-> ```
-> gh api repos/auth0/auth0-spa-js/releases/latest --jq '.tag_name'
-> ```
-> Use the returned version in all dependency lines instead of any hardcoded version below. If the command fails, fall back to checking https://github.com/auth0/auth0-spa-js/releases.
-
-## Prerequisites
-
-- Modern browser with ES2017+ support
-- npm or yarn (or use CDN for no-bundler apps)
-- Auth0 account with a Single Page Application configured
-- If you don't have Auth0 set up, see [auth0-quickstart](/auth0-quickstart)
-
-## When NOT to Use
-
-- **React SPAs** (hooks, Auth0Provider): Use [auth0-react](/auth0-react)
-- **Angular SPAs** (AuthModule, AuthGuard): Use [auth0-angular](/auth0-angular)
-- **Vue 3 SPAs** (createAuth0, useAuth0): Use [auth0-vue](/auth0-vue)
-- **Next.js** (server-side sessions, App Router): Use [auth0-nextjs](/auth0-nextjs)
-- **Nuxt** (server-side SSR): Use [auth0-nuxt](/auth0-nuxt)
-- **Express server-side web apps**: Use [auth0-express](/auth0-express)
-- **React Native / Expo mobile apps**: Use [auth0-react-native](/auth0-react-native)
-
-## Quick Start Workflow
-
-### 1. Install SDK
-
-```bash
-npm install @auth0/auth0-spa-js
-```
-
-Or via CDN (no bundler). Run this to get the latest version, then use it in your HTML:
-```bash
-VERSION=$(npm view @auth0/auth0-spa-js version)
-```
-```html
-<script src="https://cdn.auth0.com/js/auth0-spa-js/$VERSION/auth0-spa-js.production.js"></script>
-```
-
-### 2. Configure Auth0
-
-**For automated setup with Auth0 CLI**, see [Setup Guide](references/setup.md) for complete scripts.
-
-**For manual setup**, create `.env` (Vite):
-
-```bash
-VITE_AUTH0_DOMAIN=your-tenant.auth0.com
-VITE_AUTH0_CLIENT_ID=your-client-id
-```
-
-In Auth0 Dashboard, set for your **Single Page Application**:
-- **Allowed Callback URLs**: `http://localhost:5173`
-- **Allowed Logout URLs**: `http://localhost:5173`
-- **Allowed Web Origins**: `http://localhost:5173`
-
-### 3. Initialize Auth0 Client
-
-```js
-import { createAuth0Client } from '@auth0/auth0-spa-js';
-
-const auth0 = await createAuth0Client({
-  domain: import.meta.env.VITE_AUTH0_DOMAIN,
-  clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
-  authorizationParams: {
-    redirect_uri: window.location.origin
-  }
-});
-
-// Handle redirect callback after login
-const query = new URLSearchParams(window.location.search);
-if ((query.has('code') || query.has('error')) && query.has('state')) {
-  await auth0.handleRedirectCallback();
-  window.history.replaceState({}, document.title, window.location.pathname);
-}
-```
-
-### 4. Add Login / Logout
-
-> **Agent instruction:** Before adding new UI elements, search the project for existing click handlers for login, logout, sign-in, or sign-out buttons. If existing handlers are found, hook the Auth0 code into them without modifying the existing UI. Only create new buttons if no existing handlers are found.
-
-```js
-// Login
-document.getElementById('login-btn').addEventListener('click', async () => {
-  await auth0.loginWithRedirect();
-});
-
-// Logout
-document.getElementById('logout-btn').addEventListener('click', () => {
-  auth0.logout({
-    logoutParams: { returnTo: window.location.origin }
-  });
-});
-
-// Update UI based on auth state
-const isAuthenticated = await auth0.isAuthenticated();
-if (isAuthenticated) {
-  const user = await auth0.getUser();
-  console.log(user.name, user.email);
-}
-```
-
-### 5. Get Access Tokens for API Calls
-
-```js
-const accessToken = await auth0.getTokenSilently();
-
-const response = await fetch('https://your-api.example.com/data', {
-  headers: { Authorization: `Bearer ${accessToken}` }
-});
-```
-
-### 6. Build & Verify
-
-> **Agent instruction:** After completing the integration, build the project to verify it compiles successfully:
-> ```bash
-> npm run build
-> ```
-> If the build fails, analyze the error output and fix the issues. Common integration build failures include:
-> - **Module not found**: Missing `npm install @auth0/auth0-spa-js` — run the install command
-> - **Cannot find name 'import.meta'**: TypeScript target too low — set `"target": "ES2020"` or higher in `tsconfig.json`
-> - **`createAuth0Client` is not a function**: Wrong import path or CDN usage without bundle step
-> - **Env vars undefined at runtime**: Vite requires `VITE_` prefix; webpack/CRA requires `REACT_APP_` prefix
->
-> Re-run the build after each fix. Track the number of build-fix iterations.
->
-> **Failcheck:** If the build still fails after 5–6 fix attempts, stop and ask the user using `AskUserQuestion`:
-> _"The build is still failing after several fix attempts. How would you like to proceed?"_
-> - **Let the skill continue fixing iteratively** — continue the build-fix loop for another 5–6 attempts
-> - **Fix it manually** — show the remaining errors and let the user resolve them
-> - **Skip build verification** — proceed without a successful build
-
-## Detailed Documentation
-
-- [**Setup Guide**](references/setup.md) — Automated setup scripts (Bash/PowerShell), Auth0 CLI commands, `.env` configuration, callback URL setup
-- [**Integration Patterns**](references/integration.md) — Token management, calling APIs, refresh tokens, organizations, MFA, DPoP, error handling, advanced patterns
-- [**Testing & Reference**](references/api.md) — Configuration options, claims reference, testing checklist, common issues, security considerations
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Callback URL port mismatch (e.g., `localhost:3001` vs `localhost:5173`) | Match Allowed Callback URLs exactly to your dev server port in Auth0 Dashboard |
-| `client_secret` in SPA code | SPAs must never have a client secret — remove it. Auth0 sets auth method to `None` for SPA apps |
-| Tokens stored in `localStorage` | Use in-memory storage (default) or `sessionStorage`. Never `localStorage` — XSS risk |
-| `getTokenSilently()` throws `login_required` on page refresh | Add your app origin to **Allowed Web Origins** in Auth0 Dashboard |
-| `handleRedirectCallback()` not called after redirect | Must call after login redirect to exchange the auth code; without this the URL params persist and re-trigger |
-| Domain includes `https://` prefix | Auth0 domain should be hostname only: `your-tenant.auth0.com`, not `https://your-tenant.auth0.com` |
-| `loginWithPopup()` called from async init code | Popups must be triggered directly from a user gesture (click handler). Never call from init or page load code |
-| Using `Auth0Provider` from `@auth0/auth0-react` in Vanilla JS | For Vanilla JS, use `createAuth0Client()` directly — no provider component needed |
-
-## Related Skills
-
-- [auth0-quickstart](/auth0-quickstart) — Set up an Auth0 account and application
-- [auth0-react](/auth0-react) — Auth0 for React SPAs with hooks
-- [auth0-angular](/auth0-angular) — Auth0 for Angular SPAs
-- [auth0-vue](/auth0-vue) — Auth0 for Vue 3 SPAs
-- [auth0-mfa](/auth0-mfa) — Add Multi-Factor Authentication
-
-## Quick Reference
-
-### Core Methods
-
-| Method | Description |
-|--------|-------------|
-| `createAuth0Client(options)` | Create and initialize client (calls `checkSession` internally) |
-| `new Auth0Client(options)` | Instantiate without auto session check |
-| `auth0.loginWithRedirect(options?)` | Redirect to Auth0 Universal Login |
-| `auth0.loginWithPopup(options?)` | Open Auth0 login in a popup |
-| `auth0.logout(options?)` | Clear session and redirect |
-| `auth0.handleRedirectCallback(url?)` | Process redirect result after login |
-| `auth0.isAuthenticated()` | `Promise<boolean>` |
-| `auth0.getUser()` | `Promise<User \| undefined>` |
-| `auth0.getTokenSilently(options?)` | `Promise<string>` — access token |
-| `auth0.checkSession()` | Attempt silent re-authentication |
-
-### Common Use Cases
-
-- Login/Logout → See Step 4 above
-- Protecting content → [Integration Guide](references/integration.md#protecting-content)
-- API calls with tokens → [Integration Guide](references/integration.md#calling-protected-apis)
-- Refresh tokens → [Integration Guide](references/integration.md#refresh-token-rotation)
-- Organizations → [Integration Guide](references/integration.md#organizations)
-- MFA handling → [Integration Guide](references/integration.md#mfa-handling)
-- Error handling → [Integration Guide](references/integration.md#error-handling)
-
-## References
-
-- [Auth0 SPA JS SDK Documentation](https://auth0.com/docs/libraries/auth0-spa-js)
-- [Auth0 Vanilla JS Quickstart](https://auth0.com/docs/quickstart/spa/vanillajs)
-- [SDK GitHub Repository](https://github.com/auth0/auth0-spa-js)
-- [EXAMPLES.md — Advanced patterns](https://github.com/auth0/auth0-spa-js/blob/main/EXAMPLES.md)
-- [API Documentation](https://auth0.github.io/auth0-spa-js/)
diff --git a/main/.mintlify/skills/auth0-springboot-api/SKILL.md b/main/.mintlify/skills/auth0-springboot-api/SKILL.md
deleted file mode 100644
index 509300ef22..0000000000
--- a/main/.mintlify/skills/auth0-springboot-api/SKILL.md
+++ /dev/null
@@ -1,255 +0,0 @@
----
-name: auth0-springboot-api
-description: Use when securing Spring Boot API endpoints with JWT Bearer token validation, scope-based authorization, or DPoP proof-of-possession - integrates com.auth0:auth0-springboot-api SDK for REST APIs receiving access tokens from frontends or mobile apps. Triggers on Auth0AuthenticationFilter, Spring Boot API auth, JWT validation, SecurityFilterChain, hasAuthority SCOPE.
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 Spring Boot API Integration
-
-Protect Spring Boot API endpoints with JWT access token validation using `com.auth0:auth0-springboot-api`. Features auto-configuration, scope-based authorization, and built-in DPoP (RFC 9449) support.
-
----
-
-> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
-> ```bash
-> gh api repos/auth0/auth0-auth-java/releases/latest --jq '.tag_name'
-> ```
-> Use the returned version in all dependency lines instead of any hardcoded version below. If the API call fails (e.g., no releases yet), use `1.0.0-beta.1`.
-
-## Prerequisites
-
-- Java 17+ and Spring Boot 3.2+
-- Maven 3.6+ or Gradle 7+
-- Auth0 API configured (not Application — must be API resource)
-- If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first
-
-## When NOT to Use
-
-| Use Case | Recommended Skill |
-|----------|------------------|
-| Server-rendered web applications (Spring MVC with sessions) | Use `auth0-java` for Spring Boot web apps with login UI |
-| Single Page Applications | Use `auth0-react`, `auth0-vue`, or `auth0-angular` for client-side auth |
-| Mobile applications | Use `auth0-android` or `auth0-swift` for native mobile |
-| Non-Spring Java APIs | Use `auth0-spring-security-api` for plain Spring Security |
-
----
-
-## Quick Start Workflow
-
-> **Agent instruction:** If the user's prompt already provides Auth0 credentials (domain, audience), use them directly — skip the bootstrap script and credential questions. Only offer setup options when credentials are missing.
-
-### 1. Install SDK
-
-**Gradle (build.gradle):**
-
-```groovy
-implementation 'com.auth0:auth0-springboot-api:1.0.0-beta.1'
-```
-
-**Maven (pom.xml):**
-
-```xml
-<dependency>
-    <groupId>com.auth0</groupId>
-    <artifactId>auth0-springboot-api</artifactId>
-    <version>1.0.0-beta.1</version>
-</dependency>
-```
-
-### 2. Create Auth0 API
-
-You need an **API** (not Application) in Auth0.
-
-> **STOP — ask the user before proceeding.**
->
-> Ask exactly this question and wait for their answer before doing anything else:
->
-> > "How would you like to create the Auth0 API resource?
-> > 1. **Automated** — I'll run Auth0 CLI scripts that create the resource and write the values to your application.yml automatically.
-> > 2. **Manual** — You create the API yourself in the Auth0 Dashboard (or via `auth0 apis create`) and provide me the Domain and Audience.
-> >
-> > Which do you prefer? (1 = Automated / 2 = Manual)"
->
-> Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.
-
-**If the user chose Automated**, follow the [Setup Guide](references/setup.md) for complete CLI scripts. The automated path writes `application.yml` for you — skip Step 3 below and proceed directly to Step 4.
-
-**If the user chose Manual**, follow the [Setup Guide](references/setup.md) (Manual Setup section). Then continue with Step 3.
-
-Quick reference for manual API creation:
-
-```bash
-# Using Auth0 CLI
-auth0 apis create \
-  --name "My Spring Boot API" \
-  --identifier https://my-springboot-api
-```
-
-Or create manually in Auth0 Dashboard → Applications → APIs
-
-### 3. Configure application.yml
-
-```yaml
-auth0:
-  domain: "your-tenant.auth0.com"
-  audience: "https://my-springboot-api"
-```
-
-**Important:** Domain must NOT include `https://`. The library constructs the issuer URL automatically.
-
-Or use `application.properties`:
-
-```properties
-auth0.domain=your-tenant.auth0.com
-auth0.audience=https://my-springboot-api
-```
-
-### 4. Configure Spring Security
-
-```java
-@Configuration
-@EnableMethodSecurity
-public class SecurityConfig {
-
-    @Bean
-    SecurityFilterChain apiSecurity(
-            HttpSecurity http,
-            Auth0AuthenticationFilter authFilter
-    ) throws Exception {
-        return http
-            .csrf(csrf -> csrf.disable())
-            .sessionManagement(session ->
-                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
-            .authorizeHttpRequests(auth -> auth
-                .requestMatchers("/api/public").permitAll()
-                .requestMatchers("/api/protected").authenticated()
-                .requestMatchers("/api/admin/**").hasAuthority("SCOPE_admin")
-                .anyRequest().authenticated())
-            .addFilterBefore(authFilter, UsernamePasswordAuthenticationFilter.class)
-            .build();
-    }
-}
-```
-
-### 5. Protect Endpoints
-
-```java
-@RestController
-@RequestMapping("/api")
-public class ApiController {
-
-    @GetMapping("/public")
-    public ResponseEntity<Map<String, Object>> publicEndpoint() {
-        return ResponseEntity.ok(Map.of("message", "Public endpoint - no token required"));
-    }
-
-    @GetMapping("/protected")
-    public ResponseEntity<Map<String, Object>> protectedEndpoint(Authentication authentication) {
-        Auth0AuthenticationToken token = (Auth0AuthenticationToken) authentication;
-        return ResponseEntity.ok(Map.of(
-            "user", authentication.getName(),
-            "email", token.getClaim("email"),
-            "scopes", token.getScopes()
-        ));
-    }
-}
-```
-
-### 6. Test API
-
-> **Agent instruction:** After writing all code, verify the build succeeds:
-> ```bash
-> ./gradlew bootRun
-> ```
-> or `./mvnw spring-boot:run`. If build fails, diagnose and fix. After 5-6 failed attempts, use `AskUserQuestion` to get help.
-
-Test public endpoint:
-
-```bash
-curl http://localhost:8080/api/public
-```
-
-Test protected endpoint (requires access token):
-
-```bash
-curl http://localhost:8080/api/protected \
-  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
-```
-
-Get a test token via Client Credentials flow or Auth0 Dashboard → APIs → Test tab.
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Domain includes `https://` | Use `your-tenant.auth0.com` format only — no scheme prefix |
-| Audience doesn't match API Identifier | Must exactly match the API Identifier set in Auth0 Dashboard |
-| Created Application instead of API in Auth0 | Must create API resource in Auth0 Dashboard → Applications → APIs |
-| Missing `addFilterBefore` in SecurityConfig | `Auth0AuthenticationFilter` must be added before `UsernamePasswordAuthenticationFilter` |
-| Using ID token instead of access token | Must use **access token** for API auth, not ID token |
-| Checking `scope` claim in wrong format | Scopes map to `SCOPE_` prefixed authorities: use `hasAuthority("SCOPE_read:data")` |
-| Spring Boot env var binding | Use `AUTH0_DOMAIN` not `AUTH0_DOMAIN` with underscores inside property names; Spring removes dashes and is case-insensitive |
-
----
-
-## Scope-Based Authorization
-
-See [Integration Guide](references/integration.md) for defining and enforcing scope-based access control via filter chain, `@PreAuthorize`, or programmatic checks.
-
----
-
-## DPoP Support
-
-Built-in proof-of-possession token binding per RFC 9449. See [Integration Guide](references/integration.md) for configuration modes (DISABLED, ALLOWED, REQUIRED).
-
----
-
-## Related Skills
-
-- `auth0-quickstart` — Basic Auth0 setup and account creation
-- `auth0-java` — Spring Boot web apps with login UI (Regular Web Application)
-
----
-
-## Quick Reference
-
-**Configuration Properties (`application.yml`):**
-- `auth0.domain` — Auth0 tenant domain, no `https://` prefix (required)
-- `auth0.audience` — API Identifier from Auth0 API settings (required)
-- `auth0.dpop-mode` — DPoP mode: `DISABLED`, `ALLOWED` (default), `REQUIRED`
-- `auth0.dpop-iat-offset-seconds` — DPoP proof time window (default: 300)
-- `auth0.dpop-iat-leeway-seconds` — DPoP proof time leeway (default: 30)
-
-**User Claims (via `Auth0AuthenticationToken`):**
-- `authentication.getName()` — User ID (subject / `sub` claim)
-- `token.getClaim("email")` — Any specific claim by name
-- `token.getClaims()` — All JWT claims as `Map<String, Object>`
-- `token.getScopes()` — Scopes as `Set<String>`
-
-**Common Use Cases:**
-- Protect routes → `requestMatchers("/path").authenticated()` (see Step 4)
-- Scope enforcement → `hasAuthority("SCOPE_read:data")` or `@PreAuthorize` (see [Integration Guide](references/integration.md))
-- DPoP token binding → [Integration Guide](references/integration.md)
-- Complete API reference → [API Reference](references/api.md)
-
----
-
-## Detailed Documentation
-
-- **[Setup Guide](references/setup.md)** — Auth0 CLI automation, environment configuration, secret management
-- **[Integration Guide](references/integration.md)** — Scope policies, DPoP, controller patterns, error handling
-- **[API Reference](references/api.md)** — Complete configuration options, claims reference, testing checklist
-
----
-
-## References
-
-- [Auth0 Java Spring Security API Quickstart](https://auth0.com/docs/quickstart/backend/java-spring-security5)
-- [SDK GitHub Repository](https://github.com/auth0/auth0-auth-java)
-- [Spring Security Documentation](https://docs.spring.io/spring-security/reference/)
-- [Access Tokens Guide](https://auth0.com/docs/secure/tokens/access-tokens)
-- [DPoP RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449)
diff --git a/main/.mintlify/skills/auth0-swift/SKILL.md b/main/.mintlify/skills/auth0-swift/SKILL.md
deleted file mode 100644
index 7d325393a3..0000000000
--- a/main/.mintlify/skills/auth0-swift/SKILL.md
+++ /dev/null
@@ -1,259 +0,0 @@
----
-name: auth0-swift
-description: Use when adding Auth0 authentication to an iOS, macOS, tvOS, watchOS, or visionOS application — integrates the Auth0.swift SDK for native Apple platform authentication using Web Auth, CredentialsManager, and biometric protection.
-license: Proprietary
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 Swift Integration
-
-Auth0.swift is the official Auth0 SDK for Apple platforms (iOS, macOS, tvOS, watchOS, visionOS). This skill adds complete native authentication to Swift apps using Web Auth (system browser redirect), secure Keychain credential storage via `CredentialsManager`, and optional biometric protection.
-
-> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
-> ```bash
-> gh api repos/auth0/Auth0.swift/releases/latest --jq '.tag_name'
-> ```
-> Use the returned version in all dependency lines instead of any hardcoded version below. Current known version: `2.18.0`.
-
-## When NOT to Use
-
-- **Android apps**: Use [auth0-android](/auth0-android)
-- **React Native apps**: Use [auth0-react-native](/auth0-react-native)
-- **Flutter apps**: Use the native Flutter Auth0 SDK
-- **Web SPAs** (React, Angular, Vue): Use [auth0-react](/auth0-react), [auth0-angular](/auth0-angular), or [auth0-vue](/auth0-vue)
-- **Node.js/Express servers**: Use [auth0-express](/auth0-express)
-
-## Prerequisites
-
-- **iOS** 14.0+ / **macOS** 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+
-- **Xcode** 16.x
-- **Swift** 6.0+
-- Auth0 account — [Sign up free](https://auth0.com/signup)
-- Node.js 20+ (for bootstrap script automation)
-- Auth0 CLI — `brew install auth0/auth0-cli/auth0` (for bootstrap script)
-
-## Quick Start Workflow
-
-> **Agent instruction:** Follow these steps in order. If you encounter an error at any step, attempt to fix it up to 5 times before calling `AskUserQuestion` to ask the user for guidance. Always search existing code first — if there are existing login/logout handlers, hook into them rather than creating new ones.
-
-### Step 1 — Install SDK
-
-> **Agent instruction:** Check the project directory for an existing package manager file:
-> - `Podfile` present → **CocoaPods**
-> - `Cartfile` present → **Carthage**
-> - `Package.swift` present → **Swift Package Manager**
->
-> If none are found, ask via `AskUserQuestion`: _"Which dependency manager does your project use — Swift Package Manager, CocoaPods, or Carthage?"_
->
-> **Swift Package Manager — `Package.swift` project:** Run this command in the project root to add the dependency automatically, then add `"Auth0"` to the target's `dependencies` array in `Package.swift`:
-> ```bash
-> swift package add-dependency https://github.com/auth0/Auth0.swift --from 2.18.0
-> ```
->
-> **Swift Package Manager — Xcode project (`.xcodeproj`, no `Package.swift`):** The CLI command does not apply. Instruct the user to add the package via Xcode: File → Add Package Dependencies → `https://github.com/auth0/Auth0.swift` → Up to Next Major Version from `2.18.0`.
->
-> **CocoaPods or Carthage:** Follow the matching installation steps in [Setup Guide](./references/setup.md#sdk-installation). Do not just show the instructions — perform the file edits and run the commands.
-
-### Step 2 — Configure Auth0
-
-> **Agent instruction:**
-> - **If Auth0 credentials (domain AND client ID) are already in the user's prompt:** Write `Auth0.plist` directly with those values and proceed to Step 3.
-> - **If no credentials are provided:** Run the bootstrap script — do NOT ask the user to create or configure an Auth0 application manually. Always use the CLI path.
->
-> Follow [Setup Guide — Auth0 Configuration](./references/setup.md#auth0-configuration) for pre-flight checks and the script command.
-
-### Step 3 — Configure Callback URLs
-
-> **Agent instruction:**
-> 1. Read `Auth0.plist` to obtain `ClientId` and `Domain`.
-> 2. Extract the bundle identifier from `project.pbxproj`: search for `PRODUCT_BUNDLE_IDENTIFIER`, skip values containing `$(` or `Tests`.
-> 3. Ask the user via `AskUserQuestion`: _"Which callback URL scheme would you like to use?"_
->    - **Custom scheme** (`{bundle}://`) — simpler, works on all Apple platforms
->    - **HTTPS Universal Links** — recommended for production; prevents URL scheme hijacking
->
-> Then follow **only** the matching path below.
-
-#### Path A — Custom Scheme
-
-> **Agent instruction:** Register the callback URLs using the Auth0 CLI (substitute real values for `CLIENT_ID`, `BUNDLE_ID`, `DOMAIN`):
-> ```bash
-> auth0 apps update CLIENT_ID \
->   --callbacks "BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
->   --logout-urls "BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
->   --no-input
-> ```
-> Then follow the [URL scheme registration steps in Setup Guide](./references/setup.md#register-url-scheme-required-for-custom-scheme-callbacks) to register `$(PRODUCT_BUNDLE_IDENTIFIER)` as a URL type in Xcode.
-
-#### Path B — HTTPS Universal Links
-
-> **Agent instruction:** All four steps below are required — skipping any one will cause the callback redirect to fail silently after login.
->
-> **Step B1 — Register callback URLs via Auth0 CLI:**
-> Register both HTTPS and custom scheme so the app works in all scenarios:
-> ```bash
-> auth0 apps update CLIENT_ID \
->   --callbacks "https://DOMAIN/ios/BUNDLE_ID/callback,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
->   --logout-urls "https://DOMAIN/ios/BUNDLE_ID/callback,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
->   --no-input
-> ```
->
-> **Step B2 — Configure Device Settings via Auth0 CLI:**
-> Extract `DEVELOPMENT_TEAM` from `project.pbxproj` (10-character value, e.g. `ABC12DE34F`). If not found, ask via `AskUserQuestion`: _"What is your Apple Team ID? (developer.apple.com → Account → Membership Details)"_
-> ```bash
-> auth0 api patch applications/CLIENT_ID \
->   --data '{"mobile":{"ios":{"team_id":"TEAM_ID","app_bundle_identifier":"BUNDLE_ID"}}}' \
->   --no-input
-> ```
-> Auth0 will now host `https://DOMAIN/.well-known/apple-app-site-association` automatically — required for Universal Links to work on device.
->
-> **Step B3 — Add Associated Domains entitlement in Xcode:**
-> Add `com.apple.developer.associated-domains` to the app's `.entitlements` file with both `applinks:` and `webcredentials:` entries for the Auth0 domain. See [Setup Guide — Associated Domains](./references/setup.md#associated-domains-setup-https-universal-links) for the complete entitlements XML, Xcode capability steps, and build settings verification.
->
-> **Step B4 — Use `.useHTTPS()` in the SDK:**
-> ```swift
-> Auth0.webAuth().useHTTPS()
-> ```
-
-### Step 4 — Implement Authentication
-
-> **Agent instruction:** Search the project for `@main struct` (SwiftUI) or `AppDelegate`/`UIViewController` (UIKit) to detect the UI framework. If ambiguous, ask via `AskUserQuestion`: _"Does your app use SwiftUI or UIKit?"_ Then follow **only** the matching path below.
-
-#### SwiftUI
-
-> **Agent instruction:** Create `AuthenticationService.swift` as an `ObservableObject`, then wire it into the app entry point and root view. Search for the `@main` struct and `ContentView` (or equivalent root view) and update them as shown.
-
-```swift
-// AuthenticationService.swift
-import Auth0
-import Combine
-
-class AuthenticationService: ObservableObject {
-    @Published var isAuthenticated = false
-    private let credentialsManager = CredentialsManager(authentication: Auth0.authentication())
-
-    init() { isAuthenticated = credentialsManager.canRenew() }
-
-    func login() async {
-        do {
-            let credentials = try await Auth0
-                .webAuth()
-                .useHTTPS()
-                .scope("openid profile email offline_access")
-                .start()
-            _ = credentialsManager.store(credentials: credentials)
-            await MainActor.run { isAuthenticated = true }
-        } catch WebAuthError.userCancelled { }
-        catch { print("Login failed: \(error)") }
-    }
-
-    func logout() async {
-        do { try await Auth0.webAuth().useHTTPS().clearSession() }
-        catch { print("Logout failed: \(error)") }
-        _ = credentialsManager.clear()
-        await MainActor.run { isAuthenticated = false }
-    }
-}
-```
-
-```swift
-// @main App struct — inject AuthenticationService as environment object
-@StateObject private var auth = AuthenticationService()
-// In body: ContentView().environmentObject(auth)
-
-// Root ContentView — branch on authentication state
-@EnvironmentObject var auth: AuthenticationService
-// In body: if auth.isAuthenticated { HomeView() } else { LoginView() }
-```
-
-For complete SwiftUI app lifecycle wiring, see [Integration Patterns](./references/integration.md#swiftui-app-lifecycle-recommended).
-
-#### UIKit
-
-> **Agent instruction:** Create `AuthenticationService.swift` as a plain class, then add login/logout calls to the relevant `UIViewController`. Also check whether the app uses `SFSafariViewController` — if so, add `WebAuthentication.resume(with:)` to `AppDelegate`/`SceneDelegate` (see note below).
-
-```swift
-// AuthenticationService.swift
-import Auth0
-
-class AuthenticationService {
-    private let credentialsManager = CredentialsManager(authentication: Auth0.authentication())
-
-    var isAuthenticated: Bool { credentialsManager.canRenew() }
-
-    func login() async throws {
-        let credentials = try await Auth0
-            .webAuth()
-            .useHTTPS()
-            .scope("openid profile email offline_access")
-            .start()
-        _ = credentialsManager.store(credentials: credentials)
-    }
-
-    func logout() async throws {
-        try await Auth0.webAuth().useHTTPS().clearSession()
-        _ = credentialsManager.clear()
-    }
-}
-```
-
-```swift
-// In your UIViewController
-private let auth = AuthenticationService()
-
-@IBAction func loginTapped(_ sender: UIButton) {
-    Task {
-        do {
-            try await auth.login()
-            await MainActor.run { navigateToHome() }
-        } catch WebAuthError.userCancelled { }
-        catch { print("Login failed: \(error)") }
-    }
-}
-
-@IBAction func logoutTapped(_ sender: UIButton) {
-    Task {
-        do { try await auth.logout() }
-        catch { print("Logout failed: \(error)") }
-        await MainActor.run { navigateToLogin() }
-    }
-}
-```
-
-> **Note — SFSafariViewController only:** If the app uses `.provider(WebAuthentication.safariProvider())` instead of the default `ASWebAuthenticationSession`, add `WebAuthentication.resume(with: url)` to `AppDelegate.application(_:open:url:options:)` and `SceneDelegate.scene(_:openURLContexts:)`. See [Integration Patterns](./references/integration.md#uikit-app-lifecycle) for the exact code.
-
-### Step 5 — Verify Build
-
-> **Agent instruction:** Run a build to verify the integration compiles without errors:
-> ```bash
-> xcodebuild build -scheme YOUR_SCHEME -destination "platform=iOS Simulator,name=iPhone 16"
-> ```
-> If the build fails, review error messages and fix up to 5 times before asking the user.
-
-## Detailed Documentation
-
-- **[Setup Guide](./references/setup.md)** — Auth0 Dashboard configuration, bootstrap script, manual setup, URL scheme registration, CocoaPods/SPM/Carthage install
-- **[Integration Patterns](./references/integration.md)** — Web Auth login/logout, CredentialsManager, biometric protection, MFA, organizations, error handling, SwiftUI/UIKit patterns
-- **[API Reference & Testing](./references/api.md)** — Full API reference, configuration options, claims reference, testing checklist, troubleshooting
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Auth0 app type not set to **Native** | In Auth0 Dashboard, select "Native" when creating the application |
-| Missing callback URL in Auth0 Dashboard | Add both `https://` Universal Link and `{bundle}://` custom scheme to Allowed Callback URLs and Logout URLs |
-| `Auth0.plist` not added to Xcode target | Right-click file in Navigator → "Add Files to Target" → check your app target |
-| Missing `offline_access` scope | Add `"offline_access"` to scope string to receive a refresh token for silent renewal |
-| Tokens stored in `UserDefaults` | Always use `CredentialsManager` — it stores tokens in Keychain with access control |
-| Calling `credentialsManager.credentials()` before `store()` | Store credentials from login result before attempting to retrieve |
-| Opening `.xcodeproj` instead of `.xcworkspace` (CocoaPods) | Always open the `.xcworkspace` file after `pod install` |
-| Not calling `clearSession()` on logout | Always call `clearSession()` to remove the Auth0 session cookie from the browser |
-| Build error "No such module 'Auth0'" | Verify the package is added to the correct target; for CocoaPods, open `.xcworkspace` |
-
-## References
-
-- [Auth0.swift GitHub](https://github.com/auth0/Auth0.swift)
-- [iOS/macOS Quickstart](https://auth0.com/docs/quickstart/native/ios-swift)
-- [Auth0.swift API Documentation](https://auth0.github.io/Auth0.swift/documentation/auth0/)
-- [Auth0 Dashboard](https://manage.auth0.com)
-- [EXAMPLES.md](https://github.com/auth0/Auth0.swift/blob/master/EXAMPLES.md)
diff --git a/main/.mintlify/skills/auth0-vue/SKILL.md b/main/.mintlify/skills/auth0-vue/SKILL.md
deleted file mode 100644
index c1ee49e148..0000000000
--- a/main/.mintlify/skills/auth0-vue/SKILL.md
+++ /dev/null
@@ -1,166 +0,0 @@
----
-name: auth0-vue
-description: Use when adding authentication to Vue.js 3 applications (login, logout, user sessions, protected routes) - integrates @auth0/auth0-vue SDK for SPAs with Vite or Vue CLI
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Auth0 Vue.js Integration
-
-Add authentication to Vue.js 3 single-page applications using @auth0/auth0-vue.
-
----
-
-## Prerequisites
-
-- Vue 3+ application (Vite or Vue CLI)
-- Auth0 account and application configured
-- If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first
-
-## When NOT to Use
-
-- **Server-side rendered Vue apps** - See [Auth0 Nuxt.js guide](https://auth0.com/docs/quickstart/webapp/nuxt) for SSR patterns
-- **Vue 2 applications** - This SDK requires Vue 3+, use legacy @auth0/auth0-spa-js wrapper
-- **Embedded login** - This SDK uses Auth0 Universal Login (redirect-based)
-- **Backend API authentication** - Use express-openid-connect or JWT validation instead
-
----
-
-## Quick Start Workflow
-
-### 1. Install SDK
-
-```bash
-npm install @auth0/auth0-vue
-```
-
-### 2. Configure Environment
-
-**For automated setup with Auth0 CLI**, see [Setup Guide](references/setup.md) for complete scripts.
-
-**For manual setup:**
-
-Create `.env` file:
-
-```bash
-VITE_AUTH0_DOMAIN=your-tenant.auth0.com
-VITE_AUTH0_CLIENT_ID=your-client-id
-```
-
-### 3. Configure Auth0 Plugin
-
-Update `src/main.ts`:
-
-```typescript
-import { createApp } from 'vue';
-import { createAuth0 } from '@auth0/auth0-vue';
-import App from './App.vue';
-
-const app = createApp(App);
-
-app.use(
-  createAuth0({
-    domain: import.meta.env.VITE_AUTH0_DOMAIN,
-    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
-    authorizationParams: {
-      redirect_uri: window.location.origin
-    }
-  })
-);
-
-app.mount('#app');
-```
-
-### 4. Add Authentication UI
-
-Create a login component:
-
-```vue
-<script setup lang="ts">
-import { useAuth0 } from '@auth0/auth0-vue';
-
-const { loginWithRedirect, logout, isAuthenticated, user, isLoading } = useAuth0();
-</script>
-
-<template>
-  <div>
-    <div v-if="isLoading">Loading...</div>
-
-    <div v-else-if="isAuthenticated">
-      <img :src="user?.picture" :alt="user?.name" />
-      <span>Welcome, {{ user?.name }}</span>
-      <button @click="logout({ logoutParams: { returnTo: window.location.origin }})">
-        Logout
-      </button>
-    </div>
-
-    <button v-else @click="loginWithRedirect()">
-      Login
-    </button>
-  </div>
-</template>
-```
-
-### 5. Test Authentication
-
-Start your dev server and test the login flow:
-
-```bash
-npm run dev
-```
-
----
-
-## Detailed Documentation
-
-- **[Setup Guide](references/setup.md)** - Automated setup scripts (Bash/PowerShell), CLI commands, manual configuration
-- **[Integration Guide](references/integration.md)** - Protected routes, API calls, error handling, composables
-- **[API Reference](references/api.md)** - Complete SDK API, configuration options, composables reference, testing strategies
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Forgot to add redirect URI in Auth0 Dashboard | Add your application URL (e.g., `http://localhost:3000`, `https://app.example.com`) to Allowed Callback URLs in Auth0 Dashboard |
-| Using wrong env var prefix | Vite requires `VITE_` prefix, Vue CLI uses `VUE_APP_` |
-| Not handling loading state | Always check `isLoading` before rendering auth-dependent UI |
-| Storing tokens in localStorage | Never manually store tokens - SDK handles secure storage automatically |
-| Missing createAuth0 plugin registration | Must call `app.use(createAuth0({...}))` before mounting app |
-| Accessing auth before plugin loads | Wrap auth-dependent code in `v-if="!isLoading"` |
-
----
-
-## Related Skills
-
-- `auth0-quickstart` - Basic Auth0 setup
-- `auth0-migration` - Migrate from another auth provider
-- `auth0-mfa` - Add Multi-Factor Authentication
-
----
-
-## Quick Reference
-
-**Core Composables:**
-- `useAuth0()` - Main authentication composable
-- `isAuthenticated` - Reactive check if user is logged in
-- `user` - Reactive user profile information
-- `loginWithRedirect()` - Initiate login
-- `logout()` - Log out user
-- `getAccessTokenSilently()` - Get access token for API calls
-
-**Common Use Cases:**
-- Login/Logout buttons → See Step 4 above
-- Protected routes with navigation guards → [Integration Guide](references/integration.md#protected-routes)
-- API calls with tokens → [Integration Guide](references/integration.md#calling-apis)
-- Error handling → [Integration Guide](references/integration.md#error-handling)
-
----
-
-## References
-
-- [Auth0 Vue SDK Documentation](https://auth0.com/docs/libraries/auth0-vue)
-- [Auth0 Vue Quickstart](https://auth0.com/docs/quickstart/spa/vuejs)
-- [SDK GitHub Repository](https://github.com/auth0/auth0-vue)
diff --git a/main/.mintlify/skills/auth0/SKILL.md b/main/.mintlify/skills/auth0/SKILL.md
new file mode 100644
index 0000000000..33c0ce8450
--- /dev/null
+++ b/main/.mintlify/skills/auth0/SKILL.md
@@ -0,0 +1,366 @@
+---
+name: auth0
+description: Use when adding, fixing, or improving authentication in any app — login, logout, signup, route protection, JWT/access token validation, refresh token rotation, MFA, passkeys, step-up auth, SSO, RBAC, Organizations for B2B multi-tenant SaaS, custom login domains, ACUL, or Universal Login branding. Use to audit a tenant (CheckMate) or fix findings. Use even if Auth0 isn't mentioned — any time a developer asks how to authenticate users, secure an API, debug a 401, CORS error, callback URL mismatch, redirect loop, or 429 rate limit, or migrate from Clerk, NextAuth.js, Firebase, Supabase, Cognito, or Passport.js. Covers React, Next.js, Vue, Nuxt, Angular, Express, Flask, FastAPI, Spring Boot, Go, Swift, Android, Flutter, PHP, Laravel, ASP.NET Core, React Native, Expo, Ionic, and all Auth0 SDKs.
+license: Apache-2.0
+metadata:
+  author: Auth0 <support@auth0.com>
+  version: '2.0.1'
+  openclaw:
+    emoji: "\U0001F510"
+    homepage: https://github.com/auth0/agent-skills
+    requires:
+      bins:
+        - auth0
+    os:
+      - darwin
+      - linux
+    install:
+      - id: brew
+        kind: brew
+        formula: auth0/auth0-cli/auth0
+        bins: [auth0]
+        label: 'Install Auth0 CLI (brew)'
+---
+
+# Auth0
+
+Detect intent → detect framework → detect tooling → load 2–3 reference files.
+
+---
+
+## Step 1: Detect intent
+
+Match the request against the **What the developer wants** column — it describes
+the goal in plain language, not just the Auth0 term (someone who says *"make
+users confirm with a code from their phone"* lands on `feature:mfa`). The
+**Intent** you pick is a lookup key: in **Step 4** it appears verbatim as a
+section heading (`### feature:mfa`) listing which reference files to load.
+
+| What the developer wants (plain language + Auth0 term) | Intent |
+|---|---|
+| Add login, signup, sign-in, or "let users log in / create accounts" to an app | **integrate** |
+| Require a second step after the password — a one-time code, SMS or email code, authenticator app, passkey, fingerprint/face (biometric), or security key; or re-confirm identity before a sensitive action. *Auth0: multi-factor authentication (MFA), two-factor (2FA), two-step verification, step-up authentication.* | **feature:mfa** |
+| Let separate companies, teams, workspaces, or tenants each have their own users, members, roles, and login — typically a product sold to businesses. *Auth0: Organizations, multi-org, B2B SaaS.* | **feature:organizations** |
+| Serve the login page from your own web address (e.g. `login.example.com`, `auth.company.com`) instead of the default Auth0 URL. *Auth0: custom domain.* | **feature:custom-domains** |
+| Build fully custom login/signup screens with your own code or framework, beyond what theme settings allow. *Auth0: Advanced Customization for Universal Login (ACUL).* | **feature:acul** |
+| Change how the login page looks — logo, colors, fonts, background, overall theme. *Auth0: branding, Universal Login customization.* | **feature:branding** |
+| Bind tokens to the client so a stolen or leaked token can't be reused/replayed from another machine. *Auth0: DPoP (Demonstrating Proof-of-Possession), sender-constrained tokens.* | **feature:dpop** |
+| Audit an existing Auth0 tenant for security & configuration issues and produce a report — run CheckMate, get a tenant configuration / platform development review, then optionally fix findings via the CLI. *Auth0: tenant audit, CheckMate.* | **audit** |
+| Ask for best practices, "is this secure?", how to handle tokens safely, "how should I do X". *Auth0: guidance / security.* | **guidance** |
+| Hit an error: 401 Unauthorized, 403 Forbidden, CORS, callback URL mismatch, redirect loop. *Auth0: debugging.* | **debug** |
+| Hit rate limiting: 429 Too Many Requests, quota exceeded. *Auth0: rate limits.* | **debug:rate-limit** |
+| Move an existing app off Clerk, NextAuth.js, Firebase, Cognito, Okta, Supabase, Passport.js, or another auth provider. *Auth0: provider migration.* | **migrate** |
+| Upgrade the Auth0 SDK itself to a new major version (e.g. Auth0.swift v2→v3, Auth0.Android v3→v4) — breaking changes, deprecated APIs, "update to the latest SDK". *Auth0: SDK major-version upgrade.* | **upgrade-sdk** |
+| Use the Auth0 CLI directly — "create an app/API with the `auth0` CLI", script tenant setup, or automate Auth0 config in CI — with no application framework in play. *Auth0: CLI / tooling-only.* | **tooling** |
+
+---
+
+## Step 2: Detect framework
+
+> **Skip this step for the `tooling` intent** — a CLI-first request has no
+> framework. Go to Step 3, load the tooling reference; only ask about a
+> framework if the developer later pivots to integrating auth into an app.
+
+Work top-down. **Stop at the first tier that yields a framework.**
+
+### Tier 1 — Auth0 SDK already installed (strongest signal)
+
+Read the project files. **Stop at the first match.**
+
+### Node.js / JavaScript / TypeScript — check `package.json` → `dependencies`
+
+Rows are most-specific first — an Ionic/Capacitor project also carries
+`@auth0/auth0-angular` (etc.), so check the `@capacitor/browser` rows first.
+
+| Package | Framework |
+|---|---|
+| `@capacitor/browser` + `@auth0/auth0-angular` | `ionic-angular` |
+| `@capacitor/browser` + `@auth0/auth0-react` | `ionic-react` |
+| `@capacitor/browser` + `@auth0/auth0-vue` | `ionic-vue` |
+| `@auth0/nextjs-auth0` | `nextjs` |
+| `@auth0/auth0-nuxt` | `nuxt` |
+| `@auth0/auth0-react` | `react` |
+| `@auth0/auth0-vue` | `vue` |
+| `@auth0/auth0-angular` | `angular` |
+| `@auth0/auth0-spa-js` | `spa-js` |
+| `express-openid-connect` | `express` |
+| `@auth0/auth0-fastify` | `fastify` |
+| `@auth0/auth0-fastify-api` | `fastify-api` |
+| `express-oauth2-jwt-bearer` | `express-jwt` |
+| `react-native-auth0` + `app.json` or `app.config.js` present | `expo` |
+| `react-native-auth0` (no Expo files) | `react-native` |
+
+### Python — check `requirements.txt` or `pyproject.toml`
+
+| Package | Framework |
+|---|---|
+| `auth0-server-python` | `flask` |
+| `auth0-fastapi-api` | `fastapi-api` |
+
+### Java / Kotlin — check `build.gradle` or `pom.xml`
+
+| Dependency | Framework |
+|---|---|
+| `mvc-auth-commons` (`com.auth0:mvc-auth-commons`) | `java-mvc` |
+| `spring-security-oauth2-resource-server` | `springboot-api` |
+
+### .NET — check `*.csproj` or `NuGet.Config`
+
+| Package | Framework |
+|---|---|
+| `Auth0.AspNetCore.Authentication` (no `.Api` suffix) | `aspnetcore-auth` |
+| `Auth0.AspNetCore.Authentication.Api` | `aspnetcore-api` |
+| `Auth0.OidcClient.MAUI` | `maui` |
+| `Auth0.OidcClient.AndroidX` | `net-android` |
+| `Auth0.OidcClient.iOS` | `net-ios` |
+| `Auth0.OidcClient.WinForms` | `winforms` |
+| `Auth0.OidcClient.WPF` | `wpf` |
+
+### PHP — check `composer.json`
+
+`auth0/auth0-php` powers both PHP web apps and APIs; the mode is set via
+`SdkConfiguration`'s `strategy`. The `STRATEGY_API` row is more specific — check
+it first.
+
+| Package | Framework |
+|---|---|
+| `auth0/auth0-php` + `SdkConfiguration::STRATEGY_API` (or `strategy: 'api'`) | `php-api` |
+| `auth0/auth0-php` (no `STRATEGY_API` / `STRATEGY_REGULAR` or `strategy: 'webapp'`) | `php` |
+| `auth0/login` (laravel, no `AuthorizationGuard`) | `laravel` |
+| `auth0/login` + `AuthorizationGuard` | `laravel-api` |
+
+> If `auth0/auth0-php` is installed but no `SdkConfiguration` strategy is set
+> yet (fresh project), fall through to variant disambiguation below (intent:
+> building/protecting an API → `php-api`, else `php`).
+
+### Go — check `go.mod`
+
+| Module | Framework |
+|---|---|
+| `github.com/auth0/go-jwt-middleware` | `go` |
+
+### Mobile (native)
+
+| Signal | Framework |
+|---|---|
+| `Package.swift` or `.xcodeproj` + Auth0.swift | `swift` |
+| `build.gradle` + `com.auth0.android:auth0` | `android` |
+| `pubspec.yaml` + `auth0_flutter` + `flutter.web: false` | `flutter-native` |
+| `pubspec.yaml` + `auth0_flutter` + web enabled | `flutter-web` |
+
+### Tier 2 — Framework from non-Auth0 workspace dependencies
+
+If no Auth0 SDK matched, detect the framework from ordinary (non-Auth0)
+dependencies. **Stop at the first match.** For a web-vs-API split, the base is
+chosen here; the variant is resolved in "Variant disambiguation" below. Rows are
+most-specific first — an Ionic project also carries `@angular/core` / `vue` /
+`react`, so check the `@ionic/*` rows first (as in Tier 1).
+
+| Signal | Base framework |
+|---|---|
+| `next` in `package.json` | `nextjs` |
+| `nuxt` in `package.json` | `nuxt` |
+| `@ionic/*` + `@angular/core` | `ionic-angular` |
+| `@ionic/*` + `react` | `ionic-react` |
+| `@ionic/*` + `vue` | `ionic-vue` |
+| `@angular/core` in `package.json` | `angular` |
+| `vue` in `package.json` (no `nuxt`) | `vue` |
+| `expo` in `package.json` | `expo` |
+| `react-native` (no `expo`) | `react-native` |
+| `react` (no meta-framework above) | `react` (SPA) — see note |
+| `express` in `package.json` | `express` (variant below) |
+| `fastify` in `package.json` | `fastify` (variant below) |
+| `flask` in `requirements.txt`/`pyproject.toml` | `flask` |
+| `fastapi` in `requirements.txt`/`pyproject.toml` | `fastapi-api` |
+| `spring-boot` in `pom.xml`/`build.gradle` | `springboot-api` |
+| `laravel/framework` in `composer.json` | `laravel` (variant below) |
+| `composer.json` present (no Laravel) | `php` (variant below) |
+| `go.mod` present + HTTP server/router | `go` |
+| `Package.swift` or `.xcodeproj` | `swift` |
+| `pubspec.yaml` (Flutter, web disabled) | `flutter-native` |
+| `pubspec.yaml` (Flutter, web enabled) | `flutter-web` |
+| `*.csproj` referencing MAUI | `maui` |
+| `*.csproj` (WinForms) | `winforms` |
+| `*.csproj` (WPF) | `wpf` |
+| `*.csproj` ASP.NET (web app or API) | `aspnetcore` (variant below) |
+
+> **`react` note:** a plain React project maps to `react` for an SPA using the
+> React SDK, or `spa-js` if the app is framework-agnostic vanilla JS. If unclear,
+> ask before loading.
+
+### Tier 3 — Framework from the prompt
+
+If no workspace signal matched, read the developer's request for a framework or
+language name and map it here. **Stop at the first match.**
+
+| Developer mentions... | Framework |
+|---|---|
+| Next.js / `next` | `nextjs` |
+| Nuxt | `nuxt` |
+| Angular (not Ionic) | `angular` |
+| Vue (not Nuxt/Ionic) | `vue` |
+| React SPA (not Next.js) | `react` |
+| vanilla JS / plain JS / no framework SPA | `spa-js` |
+| Express (web app / server-rendered) | `express` |
+| Express API / protect API routes | `express-jwt` |
+| Fastify (web) / Fastify API | `fastify` / `fastify-api` |
+| Flask | `flask` |
+| FastAPI | `fastapi-api` |
+| Spring Boot | `springboot-api` |
+| Java MVC / servlet | `java-mvc` |
+| ASP.NET Core web app / API | `aspnetcore-auth` / `aspnetcore-api` |
+| MAUI / WinForms / WPF | `maui` / `winforms` / `wpf` |
+| PHP web app / PHP API | `php` / `php-api` |
+| Laravel web app / Laravel API | `laravel` / `laravel-api` |
+| Go / Golang API | `go` |
+| Swift / iOS | `swift` |
+| Android / Kotlin | `android` |
+| Flutter (native / web) | `flutter-native` / `flutter-web` |
+| React Native / Expo | `react-native` / `expo` |
+| Ionic (Angular/React/Vue) | `ionic-angular` / `ionic-react` / `ionic-vue` |
+
+### Variant disambiguation (web app vs API)
+
+Some frameworks have separate web-app and API references. When Tier 1 did not
+pin the variant, choose **intent-first**:
+
+| Base | Web-app variant | API variant | Choose API when… |
+|---|---|---|---|
+| express | `express` | `express-jwt` | protecting API routes / validating JWTs, no server-rendered UI |
+| fastify | `fastify` | `fastify-api` | resource server / JWT validation only |
+| php | `php` | `php-api` | building/protecting a PHP API, no web UI |
+| laravel | `laravel` | `laravel-api` | API-only (token guard), no Blade UI |
+| aspnetcore | `aspnetcore-auth` | `aspnetcore-api` | Web API / JWT bearer, no cookie login UI |
+
+If intent is still ambiguous (both a UI and protected endpoints, or unclear),
+**state what you detected and ask the developer** web app vs API before loading.
+
+### If nothing matched
+
+Ask the developer what framework/language they are using. Do not guess.
+
+### Conflicts
+
+If Tier 2 (workspace) and Tier 3 (prompt) disagree materially (e.g. the prompt
+says "Next.js" but `package.json` has no `next`), **state the conflict and ask**
+rather than silently picking. Workspace signals outrank the prompt when both are
+present and consistent.
+
+---
+
+## Step 3: Detect tooling
+
+Read the project file tree. This is a project-context decision, not a product preference.
+
+| Project has... | Load |
+|---|---|
+| `terraform/` directory OR any `*.tf` files | `tooling-terraform/index.md` |
+| Auth0 MCP server active in this agent session | `tooling-mcp/index.md` |
+| Anything else (default) | `tooling-cli/index.md` |
+
+---
+
+## Step 4: Load reference files
+
+Find the section below whose heading matches the **Intent** you picked in
+Step 1, then read the reference files it lists.
+
+### integrate
+```
+Read: references/framework-{framework}/index.md
+Read: references/tooling-{tooling}/index.md
+Follow the integration workflow in references/framework-{framework}/index.md.
+Use references/tooling-{tooling}/index.md for all Auth0 tenant configuration steps.
+```
+
+### feature:mfa
+```
+Read: references/feature-mfa/index.md
+Read: references/tooling-{tooling}/index.md
+If framework detected: Read references/framework-{framework}/index.md (for SDK-side step-up trigger)
+```
+
+### feature:organizations
+```
+Read: references/feature-organizations/index.md
+Read: references/tooling-{tooling}/index.md
+If framework detected: Read references/framework-{framework}/index.md
+If multi-tenant architecture / B2B SaaS design question: also Read references/pattern-multi-tenant/index.md
+```
+
+### feature:custom-domains
+```
+Read: references/feature-custom-domains/index.md
+Read: references/tooling-{tooling}/index.md
+```
+
+### feature:acul
+```
+Read: references/feature-acul/index.md
+Read: references/tooling-{tooling}/index.md
+```
+
+### feature:branding
+```
+Read: references/feature-branding/index.md
+Read: references/tooling-{tooling}/index.md
+```
+
+### feature:dpop
+```
+Read: references/feature-dpop/index.md
+Read: references/tooling-{tooling}/index.md
+If a SPA framework is detected (vue/react/angular/spa-js): Read references/framework-{framework}/index.md
+DPoP is SPA-only (no SSR: Next.js/Nuxt) — feature-dpop/index.md states the exclusion.
+```
+
+### guidance
+```
+Read: references/pattern-security/index.md
+If framework detected: Read references/framework-{framework}/index.md (for SDK-specific guidance — token storage, session handling, route protection)
+If token handling / JWT vs opaque / storage: Read references/pattern-token-handling/index.md
+If multi-tenant / B2B architecture: Read references/pattern-multi-tenant/index.md + references/feature-organizations/index.md
+```
+
+### debug
+```
+Read: references/pattern-common-errors/index.md
+If framework detected: Read references/framework-{framework}/index.md
+```
+
+### debug:rate-limit
+```
+Read: references/pattern-rate-limiting/index.md
+```
+
+### migrate
+```
+Read: references/feature-migration/index.md
+Read: references/tooling-{tooling}/index.md
+If framework detected: Read references/framework-{framework}/index.md
+```
+
+### audit
+```
+Read: references/feature-audit/index.md
+Read: references/feature-audit-pricing/index.md
+Read: references/feature-audit-remediation/index.md
+Read: references/tooling-{tooling}/index.md
+Apply findings only with per-command confirmation; verify each change by re-fetch.
+```
+
+### upgrade-sdk
+```
+Read: references/framework-{framework}/index.md
+Follow its "Major Version Migration" section (e.g. Auth0.swift v3, Auth0.Android v4).
+This is an Auth0 SDK version bump — NOT a provider migration. Do not load feature-migration/index.md.
+If no framework is detected: ask which Auth0 SDK the developer is upgrading.
+```
+
+### tooling
+```
+Read: references/tooling-{tooling}/index.md
+No framework file — this is a CLI/tooling-only task (create apps/APIs, script
+tenant setup, automate config in CI). If the developer then wants to integrate
+auth into an app, return to Step 1 with the integrate intent.
+```
diff --git a/main/.mintlify/skills/auth0/assets/acul/js-templates/login-id.js b/main/.mintlify/skills/auth0/assets/acul/js-templates/login-id.js
new file mode 100644
index 0000000000..5c21ccdd72
--- /dev/null
+++ b/main/.mintlify/skills/auth0/assets/acul/js-templates/login-id.js
@@ -0,0 +1,137 @@
+// ACUL JS — login-id screen boilerplate
+// SDK: @auth0/auth0-acul-js
+// Customize: apply design tokens, adjust layout, add/remove social providers
+
+import LoginId from '@auth0/auth0-acul-js/login-id'
+
+const manager = new LoginId()
+
+function getIdentifierLabel() {
+  // Dynamic label based on configured identifiers
+  const ids = manager.screen.loginIdentifiers ?? []
+  if (ids.length === 0) return 'Email or username'
+  return `Enter your ${ids.join(' or ')}`
+}
+
+function renderSocialButtons() {
+  const connections = manager.transaction.alternateConnections ?? []
+  if (!connections.length) return ''
+
+  const buttons = connections.map(conn => `
+    <button
+      class="acul-social-btn"
+      data-connection="${conn.name}"
+      aria-label="Continue with ${conn.displayName}"
+    >
+      ${conn.iconUrl ? `<img src="${conn.iconUrl}" alt="" width="20" height="20" />` : ''}
+      <span>Continue with ${conn.displayName}</span>
+    </button>
+  `).join('')
+
+  return `
+    <div class="acul-divider">
+      <span>${manager.screen.texts?.separatorText ?? 'Or'}</span>
+    </div>
+    <div class="acul-social-buttons">${buttons}</div>
+  `
+}
+
+function renderErrors() {
+  if (!manager.transaction.hasErrors) return ''
+  const msgs = manager.getErrors().map(e => `<p>${e.message}</p>`).join('')
+  return `<div class="acul-error-banner" role="alert">${msgs}</div>`
+}
+
+function render() {
+  const container = document.getElementById('app')
+  container.innerHTML = `
+    <div class="acul-page-wrapper">
+      <div class="acul-card">
+        <div class="acul-logo-slot"></div>
+
+        <h1 class="acul-heading">
+          ${manager.screen.texts?.title ?? 'Log in'}
+        </h1>
+
+        ${renderErrors()}
+
+        <form id="login-id-form" novalidate>
+          <div class="acul-field">
+            <label class="acul-label" for="username">
+              ${manager.screen.texts?.usernameLabel ?? getIdentifierLabel()}
+            </label>
+            <input
+              id="username"
+              class="acul-input"
+              type="text"
+              name="username"
+              autocomplete="username"
+              required
+            />
+          </div>
+
+          ${manager.screen.isCaptchaAvailable ? `
+            <div class="acul-field">
+              <label class="acul-label" for="captcha">
+                ${manager.screen.texts?.captchaLabel ?? 'Security code'}
+              </label>
+              <input id="captcha" class="acul-input" type="text" />
+            </div>
+          ` : ''}
+
+          <button id="submit-btn" type="submit" class="acul-btn-primary">
+            ${manager.screen.texts?.buttonText ?? 'Continue'}
+          </button>
+        </form>
+
+        ${manager.screen.isPasskeyEnabled ? `
+          <button id="passkey-btn" class="acul-btn-secondary">
+            ${manager.screen.texts?.passkeyButtonText ?? 'Use a passkey'}
+          </button>
+        ` : ''}
+
+        ${renderSocialButtons()}
+
+        <div class="acul-footer-links">
+          <a href="#">
+            ${manager.screen.texts?.signupActionLinkText ?? "Don't have an account? Sign up"}
+          </a>
+        </div>
+      </div>
+    </div>
+  `
+
+  attachEventListeners()
+}
+
+function attachEventListeners() {
+  // Form submit
+  document.getElementById('login-id-form')?.addEventListener('submit', async (e) => {
+    e.preventDefault()
+    const submitBtn = document.getElementById('submit-btn')
+    submitBtn.disabled = true
+    submitBtn.textContent = 'Loading...'
+
+    const username = document.getElementById('username').value
+    const captcha = document.getElementById('captcha')?.value
+
+    await manager.login({ username, captcha: captcha || undefined })
+
+    submitBtn.disabled = false
+    submitBtn.textContent = manager.screen.texts?.buttonText ?? 'Continue'
+  })
+
+  // Passkey
+  document.getElementById('passkey-btn')?.addEventListener('click', async () => {
+    await manager.passkeyLogin()
+  })
+
+  // Social login
+  document.querySelectorAll('.acul-social-btn').forEach(btn => {
+    btn.addEventListener('click', async () => {
+      await manager.federatedLogin({ connection: btn.dataset.connection })
+    })
+  })
+}
+
+render()
diff --git a/main/.mintlify/skills/auth0/assets/acul/js-templates/login-password.js b/main/.mintlify/skills/auth0/assets/acul/js-templates/login-password.js
new file mode 100644
index 0000000000..f8d16bda48
--- /dev/null
+++ b/main/.mintlify/skills/auth0/assets/acul/js-templates/login-password.js
@@ -0,0 +1,138 @@
+// ACUL JS — login-password screen boilerplate
+// SDK: @auth0/auth0-acul-js
+// Customize: apply design tokens, adjust layout
+
+import LoginPassword from '@auth0/auth0-acul-js/login-password'
+
+const manager = new LoginPassword()
+
+function renderErrors() {
+  if (!manager.transaction.hasErrors) return ''
+  const msgs = manager.getErrors().map(e => `<p>${e.message}</p>`).join('')
+  return `<div class="acul-error-banner" role="alert">${msgs}</div>`
+}
+
+function renderSocialButtons() {
+  const connections = manager.transaction.alternateConnections ?? []
+  if (!connections.length) return ''
+
+  return `
+    <div class="acul-divider">
+      <span>${manager.screen.texts?.separatorText ?? 'Or'}</span>
+    </div>
+    ${connections.map(conn => `
+      <button class="acul-social-btn" data-connection="${conn.name}">
+        ${conn.iconUrl ? `<img src="${conn.iconUrl}" alt="" width="20" height="20" />` : ''}
+        <span>Continue with ${conn.displayName}</span>
+      </button>
+    `).join('')}
+  `
+}
+
+function render() {
+  const container = document.getElementById('app')
+  container.innerHTML = `
+    <div class="acul-page-wrapper">
+      <div class="acul-card">
+        <div class="acul-logo-slot"></div>
+
+        <h1 class="acul-heading">
+          ${manager.screen.texts?.title ?? 'Enter your password'}
+        </h1>
+
+        ${renderErrors()}
+
+        <form id="login-password-form" novalidate>
+          <div class="acul-field">
+            <label class="acul-label" for="password">
+              ${manager.screen.texts?.passwordLabel ?? 'Password'}
+            </label>
+            <div class="acul-input-wrapper">
+              <input
+                id="password"
+                class="acul-input"
+                type="password"
+                name="password"
+                autocomplete="current-password"
+                required
+              />
+              <button type="button" id="toggle-password" class="acul-input-toggle">
+                Show
+              </button>
+            </div>
+          </div>
+
+          ${manager.screen.isCaptchaAvailable ? `
+            <div class="acul-field">
+              <label class="acul-label" for="captcha">
+                ${manager.screen.texts?.captchaLabel ?? 'Security code'}
+              </label>
+              <input id="captcha" class="acul-input" type="text" />
+            </div>
+          ` : ''}
+
+          <button id="submit-btn" type="submit" class="acul-btn-primary">
+            ${manager.screen.texts?.buttonText ?? 'Log in'}
+          </button>
+        </form>
+
+        ${manager.screen.isPasskeyEnabled ? `
+          <button id="passkey-btn" class="acul-btn-secondary">
+            ${manager.screen.texts?.passkeyButtonText ?? 'Use a passkey instead'}
+          </button>
+        ` : ''}
+
+        ${renderSocialButtons()}
+
+        <div class="acul-footer-links">
+          <a href="#">
+            ${manager.screen.texts?.forgotPasswordText ?? 'Forgot password?'}
+          </a>
+        </div>
+      </div>
+    </div>
+  `
+
+  attachEventListeners()
+}
+
+function attachEventListeners() {
+  document.getElementById('login-password-form')?.addEventListener('submit', async (e) => {
+    e.preventDefault()
+    const submitBtn = document.getElementById('submit-btn')
+    submitBtn.disabled = true
+    submitBtn.textContent = 'Loading...'
+
+    const password = document.getElementById('password').value
+    const captcha = document.getElementById('captcha')?.value
+
+    await manager.login({ password, captcha: captcha || undefined })
+
+    submitBtn.disabled = false
+    submitBtn.textContent = manager.screen.texts?.buttonText ?? 'Log in'
+  })
+
+  document.getElementById('toggle-password')?.addEventListener('click', () => {
+    const input = document.getElementById('password')
+    const btn = document.getElementById('toggle-password')
+    if (input.type === 'password') {
+      input.type = 'text'
+      btn.textContent = 'Hide'
+    } else {
+      input.type = 'password'
+      btn.textContent = 'Show'
+    }
+  })
+
+  document.getElementById('passkey-btn')?.addEventListener('click', async () => {
+    await manager.passkeyLogin()
+  })
+
+  document.querySelectorAll('.acul-social-btn').forEach(btn => {
+    btn.addEventListener('click', async () => {
+      await manager.federatedLogin({ connection: btn.dataset.connection })
+    })
+  })
+}
+
+render()
diff --git a/main/.mintlify/skills/auth0/assets/acul/react-templates/login-id.tsx b/main/.mintlify/skills/auth0/assets/acul/react-templates/login-id.tsx
new file mode 100644
index 0000000000..4b25679e04
--- /dev/null
+++ b/main/.mintlify/skills/auth0/assets/acul/react-templates/login-id.tsx
@@ -0,0 +1,157 @@
+// ACUL React — login-id screen boilerplate
+// SDK: @auth0/auth0-acul-react
+// Customize: apply design tokens, adjust layout, add/remove social providers
+
+import React, { useState } from 'react'
+import {
+  useScreen,
+  useTransaction,
+  useErrors,
+  useLoginIdentifiers,
+  login,
+  federatedLogin,
+  passkeyLogin,
+} from '@auth0/auth0-acul-react/login-id'
+// Import your theme: CSS Modules, Tailwind classes, or styled-components
+
+interface LoginIdScreenProps {}
+
+export const LoginIdScreen: React.FC<LoginIdScreenProps> = () => {
+  // SDK hooks
+  const screen = useScreen()
+  const { alternateConnections } = useTransaction()
+  const { hasErrors, errors } = useErrors()
+  const identifiers = useLoginIdentifiers()
+
+  // Local state
+  const [username, setUsername] = useState('')
+  const [captcha, setCaptcha] = useState('')
+  const [loading, setLoading] = useState(false)
+
+  // Handlers
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setLoading(true)
+    await login({ username, captcha: captcha || undefined })
+    setLoading(false)
+  }
+
+  const handleSocial = async (connectionName: string) => {
+    await federatedLogin({ connection: connectionName })
+  }
+
+  // Dynamic label from configured identifiers
+  const identifierLabel = identifiers?.length
+    ? `Enter your ${identifiers.join(' or ')}`
+    : 'Email or username'
+
+  return (
+    <div className="acul-page-wrapper">
+      <div className="acul-card">
+        {/* Logo slot */}
+        <div className="acul-logo-slot" />
+
+        {/* Heading */}
+        <h1 className="acul-heading">
+          {screen.texts?.title ?? 'Log in'}
+        </h1>
+        {screen.texts?.description && (
+          <p className="acul-subheading">{screen.texts.description}</p>
+        )}
+
+        {/* Error banner */}
+        {hasErrors && (
+          <div className="acul-error-banner" role="alert">
+            {errors.map((err, i) => (
+              <p key={i}>{err.message}</p>
+            ))}
+          </div>
+        )}
+
+        {/* Login form */}
+        <form onSubmit={handleSubmit} noValidate>
+          <div className="acul-field">
+            <label className="acul-label" htmlFor="username">
+              {screen.texts?.usernameLabel ?? identifierLabel}
+            </label>
+            <input
+              id="username"
+              className="acul-input"
+              type="text"
+              name="username"
+              autoComplete="username"
+              value={username}
+              onChange={e => setUsername(e.target.value)}
+              required
+            />
+          </div>
+
+          {/* Captcha (only if configured) */}
+          {screen.isCaptchaAvailable && (
+            <div className="acul-field">
+              <label className="acul-label" htmlFor="captcha">
+                {screen.texts?.captchaLabel ?? 'Security code'}
+              </label>
+              <input
+                id="captcha"
+                className="acul-input"
+                type="text"
+                value={captcha}
+                onChange={e => setCaptcha(e.target.value)}
+              />
+            </div>
+          )}
+
+          <button
+            type="submit"
+            className="acul-btn-primary"
+            disabled={loading || !username}
+          >
+            {loading ? 'Loading...' : (screen.texts?.buttonText ?? 'Continue')}
+          </button>
+        </form>
+
+        {/* Passkey (only if enabled) */}
+        {screen.isPasskeyEnabled && (
+          <button
+            className="acul-btn-secondary"
+            onClick={() => passkeyLogin()}
+          >
+            {screen.texts?.passkeyButtonText ?? 'Use a passkey'}
+          </button>
+        )}
+
+        {/* Social login */}
+        {alternateConnections && alternateConnections.length > 0 && (
+          <>
+            <div className="acul-divider">
+              <span>{screen.texts?.separatorText ?? 'Or'}</span>
+            </div>
+            <div className="acul-social-buttons">
+              {alternateConnections.map(conn => (
+                <button
+                  key={conn.name}
+                  className="acul-social-btn"
+                  onClick={() => handleSocial(conn.name)}
+                  aria-label={`Continue with ${conn.displayName}`}
+                >
+                  {conn.iconUrl && (
+                    <img src={conn.iconUrl} alt="" width={20} height={20} />
+                  )}
+                  <span>Continue with {conn.displayName}</span>
+                </button>
+              ))}
+            </div>
+          </>
+        )}
+
+        {/* Footer links */}
+        <div className="acul-footer-links">
+          <a href={screen.links?.signUp ?? '#'}>
+            {screen.texts?.signupActionLinkText ?? "Don't have an account? Sign up"}
+          </a>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/main/.mintlify/skills/auth0/assets/acul/react-templates/login-password.tsx b/main/.mintlify/skills/auth0/assets/acul/react-templates/login-password.tsx
new file mode 100644
index 0000000000..4cc252bb47
--- /dev/null
+++ b/main/.mintlify/skills/auth0/assets/acul/react-templates/login-password.tsx
@@ -0,0 +1,132 @@
+// ACUL React — login-password screen boilerplate
+// SDK: @auth0/auth0-acul-react
+// Customize: apply design tokens, adjust layout, add/remove social providers
+
+import React, { useState } from 'react'
+import {
+  useScreen,
+  useTransaction,
+  useErrors,
+  login,
+  federatedLogin,
+  passkeyLogin,
+} from '@auth0/auth0-acul-react/login-password'
+
+interface LoginPasswordScreenProps {}
+
+export const LoginPasswordScreen: React.FC<LoginPasswordScreenProps> = () => {
+  const screen = useScreen()
+  const { alternateConnections } = useTransaction()
+  const { hasErrors, errors } = useErrors()
+
+  const [password, setPassword] = useState('')
+  const [captcha, setCaptcha] = useState('')
+  const [loading, setLoading] = useState(false)
+  const [showPassword, setShowPassword] = useState(false)
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setLoading(true)
+    await login({ password, captcha: captcha || undefined })
+    setLoading(false)
+  }
+
+  return (
+    <div className="acul-page-wrapper">
+      <div className="acul-card">
+        <div className="acul-logo-slot" />
+
+        <h1 className="acul-heading">
+          {screen.texts?.title ?? 'Enter your password'}
+        </h1>
+
+        {hasErrors && (
+          <div className="acul-error-banner" role="alert">
+            {errors.map((err, i) => <p key={i}>{err.message}</p>)}
+          </div>
+        )}
+
+        <form onSubmit={handleSubmit} noValidate>
+          <div className="acul-field">
+            <label className="acul-label" htmlFor="password">
+              {screen.texts?.passwordLabel ?? 'Password'}
+            </label>
+            <div className="acul-input-wrapper">
+              <input
+                id="password"
+                className="acul-input"
+                type={showPassword ? 'text' : 'password'}
+                name="password"
+                autoComplete="current-password"
+                value={password}
+                onChange={e => setPassword(e.target.value)}
+                required
+              />
+              <button
+                type="button"
+                className="acul-input-toggle"
+                onClick={() => setShowPassword(v => !v)}
+                aria-label={showPassword ? 'Hide password' : 'Show password'}
+              >
+                {showPassword ? 'Hide' : 'Show'}
+              </button>
+            </div>
+          </div>
+
+          {screen.isCaptchaAvailable && (
+            <div className="acul-field">
+              <label className="acul-label" htmlFor="captcha">
+                {screen.texts?.captchaLabel ?? 'Security code'}
+              </label>
+              <input
+                id="captcha"
+                className="acul-input"
+                type="text"
+                value={captcha}
+                onChange={e => setCaptcha(e.target.value)}
+              />
+            </div>
+          )}
+
+          <button
+            type="submit"
+            className="acul-btn-primary"
+            disabled={loading || !password}
+          >
+            {loading ? 'Loading...' : (screen.texts?.buttonText ?? 'Log in')}
+          </button>
+        </form>
+
+        {screen.isPasskeyEnabled && (
+          <button className="acul-btn-secondary" onClick={() => passkeyLogin()}>
+            {screen.texts?.passkeyButtonText ?? 'Use a passkey instead'}
+          </button>
+        )}
+
+        {alternateConnections && alternateConnections.length > 0 && (
+          <>
+            <div className="acul-divider">
+              <span>{screen.texts?.separatorText ?? 'Or'}</span>
+            </div>
+            {alternateConnections.map(conn => (
+              <button
+                key={conn.name}
+                className="acul-social-btn"
+                onClick={() => federatedLogin({ connection: conn.name })}
+              >
+                {conn.iconUrl && <img src={conn.iconUrl} alt="" width={20} height={20} />}
+                <span>Continue with {conn.displayName}</span>
+              </button>
+            ))}
+          </>
+        )}
+
+        <div className="acul-footer-links">
+          <a href={screen.links?.resetPassword ?? '#'}>
+            {screen.texts?.forgotPasswordText ?? 'Forgot password?'}
+          </a>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/main/.mintlify/skills/auth0/assets/acul/theme-templates/globals.css b/main/.mintlify/skills/auth0/assets/acul/theme-templates/globals.css
new file mode 100644
index 0000000000..98240077bd
--- /dev/null
+++ b/main/.mintlify/skills/auth0/assets/acul/theme-templates/globals.css
@@ -0,0 +1,177 @@
+/* ACUL Screen Generator — Plain CSS globals template
+   Replace {{TOKEN}} placeholders with extracted design tokens from Phase 5
+   Import once in your entry point: import './styles/globals.css' */
+
+:root {
+  --color-primary:          {{COLOR_PRIMARY}};
+  --color-primary-hover:    {{COLOR_PRIMARY_HOVER}};
+  --color-primary-text:     {{COLOR_PRIMARY_TEXT}};
+  --color-background:       {{COLOR_BACKGROUND}};
+  --color-surface:          {{COLOR_SURFACE}};
+  --color-text-primary:     {{COLOR_TEXT_PRIMARY}};
+  --color-text-secondary:   {{COLOR_TEXT_SECONDARY}};
+  --color-text-placeholder: {{COLOR_TEXT_PLACEHOLDER}};
+  --color-border:           {{COLOR_BORDER}};
+  --color-border-focus:     var(--color-primary);
+  --color-error:            {{COLOR_ERROR}};
+  --color-error-bg:         {{COLOR_ERROR_BG}};
+  --color-success:          {{COLOR_SUCCESS}};
+  --font-family:            '{{FONT_FAMILY}}', ui-sans-serif, system-ui, sans-serif;
+  --radius-card:            {{RADIUS_CARD}};
+  --radius-input:           {{RADIUS_INPUT}};
+  --radius-btn:             {{RADIUS_BTN}};
+  --space-card-padding:     {{SPACE_CARD_PADDING}};
+  --shadow-card:            0 1px 3px rgba(0,0,0,0.10), 0 1px 2px rgba(0,0,0,0.06);
+  --shadow-input-focus:     0 0 0 3px {{COLOR_PRIMARY_FOCUS_RING}};
+}
+
+*, *::before, *::after { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  font-family: var(--font-family);
+  background: var(--color-background);
+  color: var(--color-text-primary);
+}
+
+/* Shared layout utilities */
+.acul-page-wrapper {
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+  background: var(--color-background);
+}
+
+.acul-card {
+  width: 100%;
+  max-width: 400px;
+  background: var(--color-surface);
+  border-radius: var(--radius-card);
+  padding: var(--space-card-padding);
+  box-shadow: var(--shadow-card);
+}
+
+.acul-input {
+  width: 100%;
+  padding: 10px 12px;
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-input);
+  font-family: var(--font-family);
+  font-size: 0.875rem;
+  color: var(--color-text-primary);
+  background: var(--color-surface);
+  transition: border-color 0.15s, box-shadow 0.15s;
+}
+
+.acul-input:focus {
+  outline: none;
+  border-color: var(--color-primary);
+  box-shadow: var(--shadow-input-focus);
+}
+
+.acul-input::placeholder {
+  color: var(--color-text-placeholder);
+}
+
+.acul-btn-primary {
+  width: 100%;
+  padding: 10px 16px;
+  background: var(--color-primary);
+  color: var(--color-primary-text);
+  border: none;
+  border-radius: var(--radius-btn);
+  font-family: var(--font-family);
+  font-size: 0.875rem;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background 0.15s;
+}
+
+.acul-btn-primary:hover:not(:disabled) {
+  background: var(--color-primary-hover);
+}
+
+.acul-btn-primary:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.acul-error-banner {
+  padding: 10px 12px;
+  background: var(--color-error-bg);
+  border: 1px solid var(--color-error);
+  border-radius: var(--radius-input);
+  color: var(--color-error);
+  font-size: 0.875rem;
+  margin-bottom: 16px;
+}
+
+.acul-label {
+  display: block;
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: var(--color-text-primary);
+  margin-bottom: 4px;
+}
+
+.acul-social-btn {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  padding: 10px 16px;
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-btn);
+  font-family: var(--font-family);
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: var(--color-text-primary);
+  cursor: pointer;
+  transition: background 0.15s;
+  margin-bottom: 8px;
+}
+
+.acul-social-btn:hover {
+  background: var(--color-background);
+}
+
+.acul-divider {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin: 20px 0;
+}
+
+.acul-divider::before,
+.acul-divider::after {
+  content: '';
+  flex: 1;
+  height: 1px;
+  background: var(--color-border);
+}
+
+.acul-divider span {
+  font-size: 0.8125rem;
+  color: var(--color-text-secondary);
+}
+
+.acul-footer-links {
+  display: flex;
+  justify-content: center;
+  gap: 16px;
+  margin-top: 20px;
+  font-size: 0.8125rem;
+}
+
+.acul-footer-links a {
+  color: var(--color-primary);
+  text-decoration: none;
+}
+
+.acul-footer-links a:hover {
+  text-decoration: underline;
+}
diff --git a/main/.mintlify/skills/auth0/assets/acul/theme-templates/tailwind.config.ts b/main/.mintlify/skills/auth0/assets/acul/theme-templates/tailwind.config.ts
new file mode 100644
index 0000000000..69a6e8a762
--- /dev/null
+++ b/main/.mintlify/skills/auth0/assets/acul/theme-templates/tailwind.config.ts
@@ -0,0 +1,54 @@
+import type { Config } from 'tailwindcss'
+
+// ACUL Screen Generator — Tailwind theme template
+// Replace token values with extracted design tokens from Phase 5
+
+const tokens = {
+  primary:        '{{COLOR_PRIMARY}}',        // e.g., '#4F46E5'
+  primaryHover:   '{{COLOR_PRIMARY_HOVER}}',  // e.g., '#4338CA'
+  primaryText:    '{{COLOR_PRIMARY_TEXT}}',   // e.g., '#FFFFFF'
+  background:     '{{COLOR_BACKGROUND}}',     // e.g., '#F9FAFB'
+  surface:        '{{COLOR_SURFACE}}',        // e.g., '#FFFFFF'
+  textPrimary:    '{{COLOR_TEXT_PRIMARY}}',   // e.g., '#111827'
+  textSecondary:  '{{COLOR_TEXT_SECONDARY}}', // e.g., '#6B7280'
+  border:         '{{COLOR_BORDER}}',         // e.g., '#E5E7EB'
+  error:          '{{COLOR_ERROR}}',          // e.g., '#EF4444'
+  success:        '{{COLOR_SUCCESS}}',        // e.g., '#22C55E'
+  radiusCard:     '{{RADIUS_CARD}}',          // e.g., '12px'
+  radiusInput:    '{{RADIUS_INPUT}}',         // e.g., '8px'
+  radiusBtn:      '{{RADIUS_BTN}}',           // e.g., '8px'
+}
+
+export default {
+  content: ['./src/**/*.{ts,tsx}'],
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          primary:       tokens.primary,
+          'primary-hover': tokens.primaryHover,
+          'primary-text':  tokens.primaryText,
+          background:    tokens.background,
+          surface:       tokens.surface,
+          'text-primary':    tokens.textPrimary,
+          'text-secondary':  tokens.textSecondary,
+          border:        tokens.border,
+          error:         tokens.error,
+          success:       tokens.success,
+        },
+      },
+      borderRadius: {
+        card:  tokens.radiusCard,
+        input: tokens.radiusInput,
+        btn:   tokens.radiusBtn,
+      },
+      boxShadow: {
+        card: '0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06)',
+      },
+      fontFamily: {
+        sans: ['{{FONT_FAMILY}}', 'ui-sans-serif', 'system-ui', 'sans-serif'],
+      },
+    },
+  },
+  plugins: [],
+} satisfies Config
diff --git a/main/.mintlify/skills/auth0/assets/acul/theme-templates/theme-provider.ts b/main/.mintlify/skills/auth0/assets/acul/theme-templates/theme-provider.ts
new file mode 100644
index 0000000000..d87c0265f3
--- /dev/null
+++ b/main/.mintlify/skills/auth0/assets/acul/theme-templates/theme-provider.ts
@@ -0,0 +1,52 @@
+// ACUL Screen Generator — styled-components ThemeProvider template
+// Replace {{TOKEN}} placeholders with extracted design tokens from Phase 5
+
+export const theme = {
+  colors: {
+    primary:          '{{COLOR_PRIMARY}}',         // e.g., '#4F46E5'
+    primaryHover:     '{{COLOR_PRIMARY_HOVER}}',   // e.g., '#4338CA'
+    primaryText:      '{{COLOR_PRIMARY_TEXT}}',    // e.g., '#FFFFFF'
+    background:       '{{COLOR_BACKGROUND}}',      // e.g., '#F9FAFB'
+    surface:          '{{COLOR_SURFACE}}',         // e.g., '#FFFFFF'
+    textPrimary:      '{{COLOR_TEXT_PRIMARY}}',    // e.g., '#111827'
+    textSecondary:    '{{COLOR_TEXT_SECONDARY}}',  // e.g., '#6B7280'
+    textPlaceholder:  '{{COLOR_TEXT_PLACEHOLDER}}',// e.g., '#9CA3AF'
+    border:           '{{COLOR_BORDER}}',          // e.g., '#E5E7EB'
+    error:            '{{COLOR_ERROR}}',           // e.g., '#EF4444'
+    errorBg:          '{{COLOR_ERROR_BG}}',        // e.g., '#FEF2F2'
+    success:          '{{COLOR_SUCCESS}}',         // e.g., '#22C55E'
+  },
+  typography: {
+    fontFamily:     "'{{FONT_FAMILY}}', ui-sans-serif, system-ui, sans-serif",
+    fontSizeHeading:'{{FONT_SIZE_HEADING}}',        // e.g., '1.5rem'
+    fontSizeBody:   '{{FONT_SIZE_BODY}}',           // e.g., '0.875rem'
+    fontWeightBold: '{{FONT_WEIGHT_HEADING}}',      // e.g., '700'
+  },
+  radii: {
+    card:   '{{RADIUS_CARD}}',   // e.g., '12px'
+    input:  '{{RADIUS_INPUT}}',  // e.g., '8px'
+    btn:    '{{RADIUS_BTN}}',    // e.g., '8px'
+    full:   '9999px',
+  },
+  spacing: {
+    cardPadding: '{{SPACE_CARD_PADDING}}',  // e.g., '32px'
+    formGap:     '{{SPACE_FORM_GAP}}',      // e.g., '16px'
+  },
+  shadows: {
+    card:       '0 1px 3px rgba(0,0,0,0.10), 0 1px 2px rgba(0,0,0,0.06)',
+    inputFocus: '0 0 0 3px {{COLOR_PRIMARY_FOCUS_RING}}',
+  },
+} as const
+
+export type Theme = typeof theme
+
+// Usage in app entry point:
+// import { ThemeProvider } from 'styled-components'
+// import { theme } from './theme'
+// <ThemeProvider theme={theme}><App /></ThemeProvider>
+
+// Usage in styled component:
+// const Button = styled.button`
+//   background: ${({ theme }) => theme.colors.primary};
+//   border-radius: ${({ theme }) => theme.radii.btn};
+// `
diff --git a/main/.mintlify/skills/auth0/assets/acul/theme-templates/tokens.css b/main/.mintlify/skills/auth0/assets/acul/theme-templates/tokens.css
new file mode 100644
index 0000000000..c96b7bb7b0
--- /dev/null
+++ b/main/.mintlify/skills/auth0/assets/acul/theme-templates/tokens.css
@@ -0,0 +1,60 @@
+/* ACUL Screen Generator — CSS Custom Properties token template
+   Replace {{TOKEN}} placeholders with extracted design tokens from Phase 5
+   Import this file once in your entry point or each screen's module CSS */
+
+:root {
+  /* Brand colors */
+  --color-primary:         {{COLOR_PRIMARY}};        /* e.g., #4F46E5 */
+  --color-primary-hover:   {{COLOR_PRIMARY_HOVER}};  /* e.g., #4338CA */
+  --color-primary-text:    {{COLOR_PRIMARY_TEXT}};   /* e.g., #FFFFFF */
+
+  /* Backgrounds */
+  --color-background:      {{COLOR_BACKGROUND}};     /* page bg, e.g., #F9FAFB */
+  --color-surface:         {{COLOR_SURFACE}};        /* card bg, e.g., #FFFFFF */
+  --color-surface-raised:  {{COLOR_SURFACE_RAISED}}; /* elevated card, e.g., #FFFFFF */
+
+  /* Text */
+  --color-text-primary:    {{COLOR_TEXT_PRIMARY}};   /* headings, e.g., #111827 */
+  --color-text-secondary:  {{COLOR_TEXT_SECONDARY}}; /* labels, e.g., #6B7280 */
+  --color-text-placeholder:{{COLOR_TEXT_PLACEHOLDER}};/* e.g., #9CA3AF */
+
+  /* Borders */
+  --color-border:          {{COLOR_BORDER}};         /* input borders, e.g., #E5E7EB */
+  --color-border-focus:    var(--color-primary);
+
+  /* States */
+  --color-error:           {{COLOR_ERROR}};          /* e.g., #EF4444 */
+  --color-error-bg:        {{COLOR_ERROR_BG}};       /* e.g., #FEF2F2 */
+  --color-success:         {{COLOR_SUCCESS}};        /* e.g., #22C55E */
+
+  /* Spacing */
+  --space-card-padding:    {{SPACE_CARD_PADDING}};   /* e.g., 32px */
+  --space-form-gap:        {{SPACE_FORM_GAP}};       /* e.g., 16px */
+
+  /* Typography */
+  --font-family:           {{FONT_FAMILY}}, ui-sans-serif, system-ui, sans-serif;
+  --font-size-heading:     {{FONT_SIZE_HEADING}};    /* e.g., 1.5rem */
+  --font-size-body:        {{FONT_SIZE_BODY}};       /* e.g., 0.875rem */
+  --font-weight-heading:   {{FONT_WEIGHT_HEADING}};  /* e.g., 700 */
+
+  /* Border radius */
+  --radius-card:           {{RADIUS_CARD}};          /* e.g., 12px */
+  --radius-input:          {{RADIUS_INPUT}};         /* e.g., 8px */
+  --radius-btn:            {{RADIUS_BTN}};           /* e.g., 8px */
+  --radius-full:           9999px;
+
+  /* Shadows */
+  --shadow-card:           0 1px 3px rgba(0,0,0,0.10), 0 1px 2px rgba(0,0,0,0.06);
+  --shadow-input-focus:    0 0 0 3px {{COLOR_PRIMARY_FOCUS_RING}}; /* primary at 20% */
+}
+
+/* Base resets for ACUL screens */
+*, *::before, *::after { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  font-family: var(--font-family);
+  font-size: var(--font-size-body);
+  color: var(--color-text-primary);
+  background: var(--color-background);
+}
diff --git a/main/.mintlify/skills/auth0/assets/audit/report-template.html b/main/.mintlify/skills/auth0/assets/audit/report-template.html
new file mode 100644
index 0000000000..9c30496837
--- /dev/null
+++ b/main/.mintlify/skills/auth0/assets/audit/report-template.html
@@ -0,0 +1,324 @@
+<!DOCTYPE html>
+<!--
+  Locked HTML report template for the audit workflow (feature-audit reference).
+  Phase 5 (report generation) substitutes every placeholder token with the same data feeding report-template.md.
+  Visual design models the "Auth0 Platform Development Review" reference layout (orange brand accent, severity-coded chips, four-section structure).
+  Render to PDF with scripts/render_pdf.sh (Chrome headless).
+-->
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Auth0 Platform Development Review — {{customer_name}}</title>
+<style>
+  :root {
+    --orange: #E94B1F;
+    --orange-soft: #FCE9E2;
+    --ink: #1A1A2E;
+    --ink-soft: #4F4F66;
+    --line: #E6E6EE;
+    --bg: #FFFFFF;
+    --severity-high: #C8260A;
+    --severity-moderate: #C46B1D;
+    --severity-low: #1F6FB5;
+    --severity-pass: #1F8A4C;
+  }
+  @page {
+    size: Letter;
+    margin: 0.6in 0.7in 0.7in 0.7in;
+    @bottom-right {
+      content: "{{review_month_year}}";
+      font: 9pt -apple-system, "Segoe UI", sans-serif;
+      color: var(--ink-soft);
+    }
+    @bottom-left {
+      content: "Confidential · Auth0 tenant configuration review for {{customer_name}}";
+      font: 9pt -apple-system, "Segoe UI", sans-serif;
+      color: var(--ink-soft);
+    }
+  }
+  * { box-sizing: border-box; }
+  html, body {
+    margin: 0;
+    padding: 0;
+    color: var(--ink);
+    background: var(--bg);
+    font-family: -apple-system, "Inter", "Segoe UI", system-ui, sans-serif;
+    font-size: 10.5pt;
+    line-height: 1.45;
+  }
+  .header {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    padding-bottom: 14pt;
+    border-bottom: 3pt solid var(--orange);
+    margin-bottom: 18pt;
+  }
+  .header h1 {
+    font-size: 24pt;
+    font-weight: 700;
+    margin: 0 0 4pt 0;
+    line-height: 1.15;
+  }
+  .header .subtitle {
+    color: var(--ink-soft);
+    font-size: 11pt;
+  }
+  .plan-badge {
+    border: 1.5pt solid var(--orange);
+    color: var(--orange);
+    border-radius: 18pt;
+    padding: 4pt 12pt;
+    font-size: 10pt;
+    font-weight: 600;
+    white-space: nowrap;
+  }
+  .header-right {
+    text-align: right;
+    font-size: 10pt;
+    color: var(--ink-soft);
+    line-height: 1.5;
+  }
+  .header-right .plan-badge {
+    display: inline-block;
+    margin-bottom: 6pt;
+  }
+  .header-right .meta-line {
+    display: block;
+    color: var(--ink);
+  }
+  .meta-table {
+    width: 100%;
+    border-collapse: collapse;
+    margin: 12pt 0 24pt 0;
+  }
+  .meta-table th, .meta-table td {
+    text-align: left;
+    padding: 10pt 12pt;
+    border-bottom: 1pt solid var(--line);
+    font-size: 10.5pt;
+  }
+  .meta-table th {
+    width: 38%;
+    color: var(--ink-soft);
+    font-weight: 500;
+  }
+  .meta-table td {
+    color: var(--ink);
+    font-weight: 600;
+  }
+  h2.section {
+    color: var(--orange);
+    text-transform: uppercase;
+    font-size: 11pt;
+    letter-spacing: 0.05em;
+    font-weight: 700;
+    margin: 22pt 0 12pt 0;
+  }
+  table.data {
+    width: 100%;
+    border-collapse: collapse;
+    margin: 8pt 0 18pt 0;
+  }
+  table.data th {
+    text-align: left;
+    text-transform: uppercase;
+    font-size: 8.5pt;
+    letter-spacing: 0.05em;
+    color: var(--ink-soft);
+    font-weight: 600;
+    padding: 8pt 12pt;
+    border-bottom: 1pt solid var(--line);
+  }
+  table.data td {
+    padding: 11pt 12pt;
+    border-bottom: 1pt solid var(--line);
+    vertical-align: top;
+  }
+  table.data td.label {
+    font-weight: 600;
+  }
+  .severity {
+    display: inline-block;
+    margin-right: 18pt;
+    font-weight: 600;
+  }
+  .severity.high { color: var(--severity-high); }
+  .severity.moderate { color: var(--severity-moderate); }
+  .severity.low { color: var(--severity-low); }
+  .severity.pass { color: var(--severity-pass); }
+  .gap {
+    border-left: 3pt solid var(--orange);
+    padding: 4pt 0 4pt 14pt;
+    margin: 12pt 0;
+  }
+  .gap .gap-name {
+    font-weight: 700;
+    margin-bottom: 4pt;
+  }
+  .gap p { margin: 0; }
+  .opportunities th, .opportunities td {
+    vertical-align: top;
+  }
+  .opportunities .feature { font-weight: 700; width: 18%; }
+  .opportunities .challenge { width: 36%; color: var(--ink); }
+  .opportunities .solution { width: 18%; color: var(--orange); font-weight: 600; }
+  .opportunities .impact { width: 28%; color: var(--ink-soft); }
+  .roadmap-banner {
+    font-weight: 700;
+    margin: 4pt 0 12pt 0;
+  }
+  .roadmap-banner em { color: var(--orange); font-style: normal; font-weight: 700; }
+  .roadmap p { margin: 6pt 0; }
+  .actions {
+    list-style: none;
+    counter-reset: action;
+    padding: 0;
+    margin: 6pt 0 16pt 0;
+  }
+  .actions li {
+    counter-increment: action;
+    display: flex;
+    align-items: flex-start;
+    margin: 6pt 0;
+  }
+  .actions li::before {
+    content: counter(action);
+    color: var(--ink-soft);
+    font-weight: 600;
+    width: 22pt;
+    flex: 0 0 22pt;
+    text-align: left;
+  }
+  .docs {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 8pt 12pt;
+    margin: 8pt 0 0 0;
+  }
+  .docs a {
+    display: block;
+    padding: 10pt 14pt;
+    border: 1pt solid var(--line);
+    border-radius: 6pt;
+    color: var(--orange);
+    font-weight: 600;
+    text-decoration: none;
+    font-size: 10pt;
+  }
+  hr.section-divider {
+    border: 0;
+    border-top: 1pt solid var(--line);
+    margin: 18pt 0;
+  }
+  .small { font-size: 9pt; color: var(--ink-soft); }
+</style>
+</head>
+<body>
+
+<header class="header">
+  <div>
+    <h1>Auth0 Platform<br>Development Review</h1>
+    {{subtitle_html}}  <!-- a subtitle div reading "Prepared by <org>" if reviewer_org is non-empty; emit empty string otherwise -->
+  </div>
+  <div class="header-right">
+    <span class="plan-badge">{{plan_tag}}</span>
+    <span class="meta-line">{{customer_name}} · {{tenant_domain}}</span>
+    <span class="meta-line">{{review_date_long}}</span>
+  </div>
+</header>
+
+<table class="meta-table">
+  <tr><th>Prepared by</th><td>{{reviewer_name}}</td></tr>
+  <tr><th>Date of Review</th><td>{{review_date_long}}</td></tr>
+  <tr><th>Customer Account</th><td>{{customer_name}} ({{tenant_domain}})</td></tr>
+  <tr><th>Current Auth0 Tier</th><td>{{tier}}</td></tr>
+  <tr><th>Use Case Diagnosis</th><td>{{business_model}} — {{product_summary_short}}</td></tr>
+  <tr><th>Recommended Plan</th><td>{{recommended_plan}} · Auth for AI Agents: {{a4aa_yes_no}}</td></tr>
+</table>
+
+<h2 class="section">1. Account Health</h2>
+
+<table class="data">
+  <thead>
+    <tr><th>Metric</th><th>Status</th></tr>
+  </thead>
+  <tbody>
+    <tr><td class="label">Applications Registered</td><td>{{apps_count}}</td></tr>
+    <tr><td class="label">Login Activity</td><td>{{login_activity}}</td></tr>
+    <tr>
+      <td class="label">Security Findings</td>
+      <td>
+        <span class="severity high">{{findings_high_count}} High</span>
+        <span class="severity moderate">{{findings_moderate_count}} Moderate</span>
+        <span class="severity low">{{findings_low_count}} Low / Info</span>
+        <span class="severity pass">{{findings_passing_count}} Passing</span>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<!-- gaps_html: rendered from the included gap callouts. Each block is a gap div with a
+     gap-name heading and a one-line body paragraph. Only include gaps the data supports. -->
+{{gaps_html}}
+
+<h2 class="section">2. Executive Summary</h2>
+
+<p>{{exec_summary_paragraph}}</p>
+
+<p><strong>Configuration Posture at a Glance</strong></p>
+
+<table class="data">
+  <thead>
+    <tr><th>Severity</th><th>Count</th><th>Key Examples</th></tr>
+  </thead>
+  <tbody>
+    <tr><td class="label" style="color:var(--severity-high)">High</td><td>{{findings_high_count}}</td><td>{{findings_high_examples}}</td></tr>
+    <tr><td class="label" style="color:var(--severity-moderate)">Moderate</td><td>{{findings_moderate_count}}</td><td>{{findings_moderate_examples}}</td></tr>
+    <tr><td class="label" style="color:var(--severity-low)">Low / Info</td><td>{{findings_low_count}}</td><td>{{findings_low_examples}}</td></tr>
+    <tr><td class="label" style="color:var(--severity-pass)">Passing</td><td>{{findings_passing_count}} of {{findings_total_count}}</td><td>{{findings_passing_examples}}</td></tr>
+  </tbody>
+</table>
+
+<h2 class="section">3. Strategic Opportunities &amp; Action Plan</h2>
+
+<table class="data opportunities">
+  <thead>
+    <tr><th>Feature Area</th><th>The Enterprise Challenge</th><th>The Solution</th><th>Strategic Impact</th></tr>
+  </thead>
+  <tbody>
+    <!-- opportunities_rows: one table row per included row — feature area, a personalized
+         challenge cell, the solution label, and the strategic impact. Every challenge cell
+         MUST name a specific product, segment, or capability from the company context. -->
+    {{opportunities_rows}}
+  </tbody>
+</table>
+
+<h2 class="section">4. Recommended Roadmap &amp; Next Steps</h2>
+
+<p class="roadmap-banner">Recommended Plan: <em>{{recommended_plan}}{{a4aa_addon_suffix}}</em></p>
+
+<div class="roadmap">
+  {{plan_recommendation_paragraphs_html}}
+</div>
+
+<p><strong>Immediate Actions — Available Today (Free)</strong></p>
+<ol class="actions">
+  <!-- immediate_actions_html: one list item per item. Each must name affected apps/connections explicitly. -->
+  {{immediate_actions_html}}
+</ol>
+
+<p><strong>After Upgrading</strong></p>
+<ol class="actions">
+  <!-- after_upgrading_html: one list item per item. -->
+  {{after_upgrading_html}}
+</ol>
+
+<p><strong>Key Documentation</strong></p>
+<div class="docs">
+  <!-- docs_html: one anchor link per included row. Match Section 3 rows. -->
+  {{docs_html}}
+</div>
+
+</body>
+</html>
diff --git a/main/.mintlify/skills/auth0/assets/audit/report-template.md b/main/.mintlify/skills/auth0/assets/audit/report-template.md
new file mode 100644
index 0000000000..5c4581c1ea
--- /dev/null
+++ b/main/.mintlify/skills/auth0/assets/audit/report-template.md
@@ -0,0 +1,156 @@
+# Locked report skeleton (Auth0 Platform Development Review)
+
+This is the structural contract the audit workflow reference (Phase 5, report generation) follows for the markdown brief. The HTML/PDF render uses the parallel template at [report-template.html](report-template.html) — same data, same sections, different presentation. Replace every placeholder token with values from the CheckMate report, the lightweight company context (Phase 3), and tenant facts. Visual design models the "Auth0 Platform Development Review" reference layout (orange brand accent, severity-coded chips, four-section structure).
+
+Source-of-truth reminders (see the audit workflow reference, Phase 5) — placeholder → source:
+- tenant_domain → `state/setup.json.tenant_domain` (from `auth0 tenants list --json`); never from the company context
+- customer_name, product_*, business_model, ai_use_case, integrations_* → the company context (Phase 3; sanitized — no fit scores, no firmographics)
+- recommended_plan, a4aa_yes_no → DERIVED in Phase 4 from the use case + the findings + the co-loaded pricing reference (never a company score)
+- reviewer_name, reviewer_org → `state/operator.json.reviewer_name` / `.reviewer_org`
+- plan_tag, tier → `auth0 api get tenants/settings` (fallback "Free Plan")
+- apps_count, apps_* → `auth0 apps list --json`
+- login_activity → derived from `auth0 logs list --number 50`
+- custom_domains_present, log_streams_present, mfa_configured, etc. → tenant facts from Phase 4.4
+- findings_*_count, findings_*_examples → the CheckMate report (a flat array of finding objects), grouped by severity
+
+---
+
+# Auth0 Platform Development Review
+
+{{prepared_by_line}}  <!-- the "Prepared by <org>" line if reviewer_org is non-empty; OMIT this line entirely otherwise -->
+
+> **{{plan_tag}}** · {{customer_name}} · {{tenant_domain}} · {{review_date_long}}
+
+| | |
+|---|---|
+| **Prepared by** | {{reviewer_name}} |
+| **Date of Review** | {{review_date_long}} |
+| **Customer Account** | {{customer_name}} ({{tenant_domain}}) |
+| **Current Auth0 Tier** | {{tier}} |
+| **Use Case Diagnosis** | {{business_model}} — {{product_summary_short}} |
+| **Recommended Plan** | {{recommended_plan}} · Auth for AI Agents: {{a4aa_yes_no}} |
+
+---
+
+## 1. ACCOUNT HEALTH
+
+| METRIC | STATUS |
+|---|---|
+| **Applications Registered** | {{apps_count}} |
+| **Login Activity** | {{login_activity}} |
+| **Security Findings** | **{{findings_high_count}} High** &nbsp;&nbsp; **{{findings_moderate_count}} Moderate** &nbsp;&nbsp; **{{findings_low_count}} Low / Info** &nbsp;&nbsp; **{{findings_passing_count}} Passing** |
+
+> **The Branding Gap**
+> Authentication is served from the default Auth0 domain (`{{tenant_domain}}`). {{customer_user_type_short}} accessing {{product_1}} and {{product_2}} are redirected off-brand during login — undermining trust at a critical moment in the user journey.
+>
+> *(Include only if `custom_domains` is empty.)*
+
+> **The Security Gap**
+> No MFA is configured on any application. For {{customer_user_type_short}} handling {{data_sensitivity_descriptor}}, this is a material risk and a common enterprise procurement blocker.
+>
+> *(Include only if MFA is disabled per tenant facts.)*
+
+> **The Production Readiness Gap**
+> Development URLs (`{{dev_url_example}}`) remain active in production configurations across callbacks, web origins, and logout URLs for {{app_with_dev_urls}}.
+>
+> *(Include only if CheckMate flagged dev URLs / implicit grant types — name offending app from `apps_list`.)*
+
+> **The Compliance Gap** *(optional — include when log streams empty AND regulated industry / EU tenant)*
+> No log streaming is configured. {{customer_name}} operates in {{regulated_context}} and requires {{compliance_framework}} audit trails — currently limited to Auth0's default retention window.
+
+> **The Observability Gap** *(generic version when Compliance Gap doesn't apply)*
+> No log streaming is configured. Without it, diagnosing auth issues or security incidents is limited to Auth0's default retention window.
+
+---
+
+## 2. EXECUTIVE SUMMARY
+
+{{customer_name}} has built a structured Auth0 environment supporting {{products_inline_list}} — with {{apps_count}} registered applications and {{login_activity_descriptor}} login activity.
+
+The current challenge is graduating from a working setup to a **production-grade, enterprise-ready** authentication platform. A CheckMate security audit surfaced **{{findings_high_count}} High** and **{{findings_moderate_count}} Moderate** configuration gaps across security, branding, and observability. The core architecture is solid — these gaps are directly addressable with the right plan.
+
+### Configuration Posture at a Glance
+
+| SEVERITY | COUNT | KEY EXAMPLES |
+|---|---|---|
+| **High** | {{findings_high_count}} | {{findings_high_examples}} |
+| **Moderate** | {{findings_moderate_count}} | {{findings_moderate_examples}} |
+| **Low / Info** | {{findings_low_count}} | {{findings_low_examples}} |
+| **Passing** | {{findings_passing_count}} of {{findings_total_count}} | {{findings_passing_examples}} |
+
+Examples are dot-separated finding titles (top 3-5 per row), e.g. "No custom domain · Localhost URLs in production · Implicit grant types on 4 apps".
+
+---
+
+## 3. STRATEGIC OPPORTUNITIES & ACTION PLAN
+
+| FEATURE AREA | THE ENTERPRISE CHALLENGE | THE SOLUTION | STRATEGIC IMPACT |
+|---|---|---|---|
+| **Brand Trust & UX** | Enterprise clients authenticate through `{{tenant_domain}}` — a generic Auth0 domain — breaking the {{customer_name}} brand at login and invitation acceptance. | **Custom Domains** | Keep enterprise users entirely within your brand. Critical for sales credibility and user trust. |
+| **Per-Organization Management** | {{product_1}} and {{product_2}} serve distinct enterprise accounts with no way to isolate branding, members, or access per customer on the current plan. | **Auth0 Organizations** | Onboard enterprise clients cleanly with per-org branding, member management, and connection settings — scales with your go-to-market. |
+| **Enterprise SSO** | {{customer_name}}'s enterprise clients — {{customer_user_segments}} — already have corporate identity providers (Azure AD, Okta, Google Workspace). Currently they must create separate credentials to access {{product_suite_short}}, adding friction that blocks enterprise procurement. | **Enterprise Connections (SAML / OIDC)** | Let enterprise clients log in with their existing corporate credentials. Removes a common procurement blocker and eliminates the need for a separate set of credentials for your platform. |
+| **Account Security** | No MFA is configured on any application. Enterprise procurement increasingly requires it as a baseline, especially for platforms handling {{data_sensitivity_descriptor}}. | **MFA (WebAuthn / Authenticator App)** | Reduces account takeover risk significantly. Addresses common enterprise procurement requirements{{gdpr_clause}}. |
+| **Observability** | No log streaming is configured. Without it, diagnosing auth issues or security incidents is limited to Auth0's default retention window. | **Log Streaming** | Enables SIEM integration, enterprise audit trails, and the observability required for compliance and incident response. |
+| **AI Agent Security** *(only if `ai_use_case` ∈ AI-Native/AI-Differentiated)* | {{ai_product_1}} and {{ai_product_2}} use AI to interact with third-party {{integration_domain}} services. Managing OAuth tokens for these integrations manually creates security risk and developer overhead. | **Token Vault (A4AA)** | Securely store and rotate OAuth tokens for AI agent integrations — no re-authentication required, no secrets in code. |
+| **Human-in-the-Loop AI** *(only if autonomous-action workflows in enrichment)* | High-stakes {{ai_action_domain}} actions ({{ai_action_example_1}}, {{ai_action_example_2}}) may require explicit user approval before an AI agent executes them. | **CIBA (A4AA)** | Enable async human approval for sensitive AI-driven actions from any device, without disrupting the user experience. |
+
+Include only the rows whose triggers are met. Rewrite the cell text to reference the actual customer's products / segments / data — never leave generic placeholders in the rendered output.
+
+---
+
+## 4. RECOMMENDED ROADMAP & NEXT STEPS
+
+### Recommended Plan: **{{recommended_plan}}**{{a4aa_addon_suffix}}
+
+{{plan_recommendation_paragraph}}
+
+> Example: "**B2B Essentials** unlocks Custom Domains, Organizations, Enterprise Connections, and enhanced MFA — the four highest-impact changes for {{customer_name}}'s enterprise go-to-market.
+>
+> **A4AA Add-on** directly addresses the identity challenges in AI-assisted {{ai_workflow_descriptor}} workflows via Token Vault and CIBA."
+
+### Immediate Actions — Available Today (Free)
+
+> Numbered list of CheckMate findings actionable on the **current** plan. Triage rule: if the fix can be applied with the current tier's feature set per the feature→plan matrix in the co-loaded pricing reference (source of truth — read it, don't guess), it goes here. Each item must name the affected app/connection. These items feed the remediation reference's Loop A.
+
+1. {{immediate_action_1}}
+2. {{immediate_action_2}}
+3. {{immediate_action_3}}
+<!-- continue numbering for each remaining action -->
+
+> Illustrative shape (dummy data — replace every name with the actual tenant's apps):
+> 1. Remove `http://localhost:3000` from web origins, callbacks, and logout URLs in `Customer Portal Web`
+> 2. Disable the implicit grant type on `Default App, Admin Console Web, Customer Portal Web, Mobile App` — migrate to Authorization Code + PKCE
+> 3. Enable rotating refresh tokens on `Default App, Admin Console Web`
+> 4. Configure a Custom Domain — included free (1, credit-card verification required); keeps logins on-brand without an upgrade
+
+### After Upgrading
+
+> Numbered list of fixes requiring the recommended plan. Each item describes the outcome, not the dashboard click path. These items feed the remediation reference's Loop B (gated on user confirming the upgrade).
+
+1. {{after_upgrade_action_1}}
+2. {{after_upgrade_action_2}}
+<!-- continue numbering for each remaining action -->
+
+> Example items from the reference sample (Custom Domains is NOT here — it's free; see Immediate Actions):
+> 1. Set up Auth0 Organizations + Enterprise Connections (SAML / OIDC) for your first enterprise clients (Essentials)
+> 2. Enable WebAuthn or Authenticator App MFA across enterprise user flows (Essentials — Pro MFA Factors)
+> 3. Configure an email provider and branded email templates (Essentials — Email Workflow)
+> 4. Stream logs to your observability platform (Essentials — 1 log stream)
+> 5. Switch Breached Password Detection to blocking + Enhanced Password Protection (Professional)
+> 6. Implement Token Vault / CIBA for AI agent OAuth token management (A4AA add-on)
+
+### Key Documentation
+
+| | |
+|---|---|
+| [B2B Best Practices](https://auth0.com/docs/manage-users/organizations) | [Auth0 Organizations](https://auth0.com/docs/manage-users/organizations) |
+| [Custom Domains](https://auth0.com/docs/customize/custom-domains) | [Enterprise Connections](https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers) |
+| [Configure WebAuthn as MFA](https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/webauthn) | [Log Streaming](https://auth0.com/docs/customize/log-streams) |
+| [Token Vault (A4AA)](https://auth0.com/ai/docs/get-tokens-for-tools) | [CIBA (A4AA)](https://auth0.com/ai/docs/asynchronous-authorization) |
+| [Authorization Code + PKCE](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) | |
+
+> Include only the rows whose corresponding Section 3 row is included.
+
+---
+
+*Confidential · Auth0 tenant configuration review for {{customer_name}} · {{review_month_year}}*
diff --git a/main/.mintlify/skills/auth0/references/feature-acul/index.md b/main/.mintlify/skills/auth0/references/feature-acul/index.md
new file mode 100644
index 0000000000..4df243592a
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/feature-acul/index.md
@@ -0,0 +1,1786 @@
+
+# ACUL Screen Generator
+
+Generates production-ready, fully themed Auth0 ACUL screen components. Follows a strict 9-phase workflow (Phases 0–8): CLI authentication → intent detection → project setup → screen requirements → tech stack and design → theme extraction → structured code generation → build validation & iterative fix → dev mode wiring.
+
+## Reference Hierarchy
+
+Always resolve the correct reference for a screen using this priority order. **Before running the CLI**, check if the screen exists in auth0-acul-samples — if it does not, the CLI will fail.
+
+```text
+1. Check auth0-acul-samples availability first  (gate for CLI usage)
+   → Check the Screen Catalog section in this file for the Samples column
+   → Verify the screen directory exists at:
+     React:    https://github.com/auth0-samples/auth0-acul-samples/tree/main/react/src/screens/<screen-name>
+     React-JS: https://github.com/auth0-samples/auth0-acul-samples/tree/main/react-js/src/screens/<screen-name>
+   → If the screen IS in samples → proceed to CLI (step 2)
+   → If the screen is NOT in samples → skip CLI entirely, go to step 3
+
+2. Auth0 CLI scaffolded code  (only for screens confirmed in auth0-acul-samples)
+   → Use `auth0 acul screen add` or `auth0 acul init` to generate screen code locally
+   → The CLI produces the correct project structure, SDK imports, and hook patterns
+   → If the CLI succeeds, use the scaffolded code as-is — do NOT fetch from GitHub
+
+3. SDK examples  (for screens NOT in auth0-acul-samples — do NOT attempt CLI for these)
+   → Code snippets showing SDK imports, hooks, and action functions
+   → React: https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-react/examples/<screen-name>.md
+   → JS:    https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-js/examples/<screen-name>.md
+   → Determine if the example is React or JS, then adapt to match the project's framework
+
+4. assets/acul/react-templates/ or assets/acul/js-templates/
+   → Structural component pattern only — never use their hooks/actions for other screens
+```
+
+For which screens are in auth0-acul-samples → see the Screen Catalog section in this file.
+
+
+## auth0-acul-samples Architecture
+
+When a screen is available in auth0-acul-samples, generate code using this modular pattern — not a monolithic component.
+
+**Directory structure per screen:**
+```
+<screen-name>/
+├── index.tsx                        thin entry: wires manager hook + applies theme + renders layout
+├── components/
+│   ├── Header.tsx                   logo, title, subtitle from screen.texts
+│   ├── <ScreenName>Form.tsx         form fields, submit, captcha, passkey button
+│   ├── Footer.tsx                   signup link, forgot password, back link
+│   └── AlternativeLogins.tsx        social login buttons (if screen has social)
+├── hooks/
+│   └── use<ScreenName>Manager.ts    wraps SDK hooks, exposes clean handlers + feature flags
+└── locales/
+    └── en.json                      fallback text strings
+```
+
+**index.tsx pattern:**
+```tsx
+import { ULThemeCard, ULThemePageLayout } from '@/components'
+import { applyAuth0Theme } from '@/utils/theme/themeEngine'
+import Header from './components/Header'
+import <ScreenName>Form from './components/<ScreenName>Form'
+import Footer from './components/Footer'
+import { use<ScreenName>Manager } from './hooks/use<ScreenName>Manager'
+
+const <ScreenName>Screen = () => {
+  const { sdkInstance, texts, locales } = use<ScreenName>Manager()
+  applyAuth0Theme(sdkInstance)
+  document.title = texts?.pageTitle ?? locales.pageTitle
+
+  return (
+    <ULThemePageLayout>
+      <ULThemeCard>
+        <Header texts={texts} />
+        <AlternativeLogins alignment="top" />    {/* conditional */}
+        <<ScreenName>Form />
+        <Footer texts={texts} links={links} />
+        <AlternativeLogins alignment="bottom" />  {/* conditional */}
+      </ULThemeCard>
+    </ULThemePageLayout>
+  )
+}
+
+export default <ScreenName>Screen   // REQUIRED: screenLoader registers via lazy(), which needs a default export
+```
+
+> **`index.tsx` must have a `export default`.** The project's screen registry (`src/utils/screen/screenLoader.ts`) loads each screen with `lazy(() => import('@/screens/<screen-name>'))`, and `React.lazy` resolves the module's **default** export. A named-only export (`export const <ScreenName>Screen`) compiles fine but renders blank / "screen not implemented" at runtime. See "Screen Registration" in Phase 6.
+
+**hooks/use\<ScreenName\>Manager.ts pattern:**
+```ts
+import { useLoginId, useScreen, useTransaction } from '@auth0/auth0-acul-react/<screen-name>'
+import { executeSafely } from '@/utils/helpers/executeSafely'
+import locales from '../locales/en.json'
+
+export const use<ScreenName>Manager = () => {
+  const sdkInstance = useLoginId()       // screen-specific SDK hook
+  const screen = useScreen()
+  const { alternateConnections } = useTransaction()
+
+  const handleSubmit = async (data) => executeSafely(() => login(data))
+  const handleFederatedLogin = async (conn) => executeSafely(() => federatedLogin({ connection: conn }))
+
+  return {
+    sdkInstance,
+    texts: screen.texts,
+    locales,
+    alternateConnections,
+    handleSubmit,
+    handleFederatedLogin,
+    isPasskeyEnabled: screen.isPasskeyEnabled,
+    isCaptchaAvailable: screen.isCaptchaAvailable,
+  }
+}
+```
+
+When a screen is **not** in auth0-acul-samples and the CLI doesn't support it, fall back to a single-file component based on the SDK example.
+
+## Prerequisites
+
+- Auth0 CLI installed: `brew install auth0`
+- Custom domain configured on the Auth0 tenant (hard ACUL requirement)
+- Node.js **≥ 22** (required by Auth0 CLI-generated ACUL projects)
+
+
+## Phase 0: Environment Validation & CLI Authentication
+
+### Step 1 — Verify Node.js version
+
+```bash
+node --version 2>&1
+```
+
+Parse the output and verify the major version is **≥ 22**. If Node.js is not installed or the version is below 22:
+- **Not installed:** Stop and instruct the customer to install Node.js 22+ (e.g., `nvm install 22` or download from nodejs.org).
+- **Version < 22:** Stop and instruct the customer to upgrade. Example: `nvm install 22 && nvm use 22`. The Auth0 CLI-generated ACUL projects require Node.js 22+ and will fail to build or run on older versions.
+
+Do NOT proceed to any subsequent phase until Node.js ≥ 22 is confirmed.
+
+### Step 2 — CLI Authentication & Tenant Check
+
+```bash
+auth0 login
+auth0 acul config list --rendering-mode advanced
+```
+
+If `auth0 acul config list` returns an error about custom domain: stop and inform the customer they must configure a custom domain on their tenant before ACUL is available.
+
+For full CLI flag reference → see the CLI Commands section in this file.
+
+> **Tooling note.** ACUL is CLI-driven by design: the CLI scaffolds and previews
+> the screen *code*, which neither Terraform nor the MCP server can do — so this
+> workflow uses the Auth0 CLI regardless of the project's other tooling. The one
+> piece that *is* declarative is the tenant-side toggle that turns a screen's
+> rendering mode to `advanced`: an infrastructure-as-code project can manage that
+> with the Terraform `auth0_prompt_screen_renderer` resource (`rendering_mode`)
+> instead of the CLI. The Auth0 MCP server exposes **no** ACUL/prompt-screen tool.
+
+
+## Phase 1: Intent Detection
+
+Ask the customer which mode they need:
+
+- **A) Build from scratch** — new project, select screens, full setup
+- **B) Add a screen** — existing project, add one or more new screens
+- **C) Modify a screen** — existing project, change an existing screen's code or styling
+
+This choice gates Phases 2A / 2B / 2C.
+
+
+## Phase 2A: Scratch — Project Init
+
+Gather: app name, framework (`react` or `js`), initial screen list.
+
+```bash
+auth0 acul init <app_name> -t react -s login-id,login-password,signup
+auth0 acul config generate <screen-name>    # repeat per screen
+```
+
+Verify `acul_config.json` is created in the project directory.
+
+**The CLI-scaffolded code is your primary source.** Read the generated screen files to understand the project structure, SDK imports, hook patterns, and component layout. Do NOT fetch from GitHub — the CLI output is the canonical starting point. Only customize or extend the generated code based on the customer's requirements (branding, extra components, etc.).
+
+Proceed to Phase 3.
+
+
+## Phase 2B: Add Screen — Check Samples Availability First
+
+1. Verify `acul_config.json` exists in the project directory.
+   - If missing → stop. Instruct customer to run `auth0 acul init` first.
+
+2. **Check if the screen exists in auth0-acul-samples before attempting CLI.**
+
+   Check the Screen Catalog section in this file for the `Samples (React)` or `Samples (React-JS)` column for the requested screen. Then fetch the GitHub directory listing to **confirm** the screen actually exists at the expected path:
+
+   ```text
+   React:    https://github.com/auth0-samples/auth0-acul-samples/tree/main/react/src/screens/<screen-name>
+   React-JS: https://github.com/auth0-samples/auth0-acul-samples/tree/main/react-js/src/screens/<screen-name>
+   ```
+
+   This check determines whether the CLI can scaffold the screen. If the screen is NOT present in auth0-acul-samples, the CLI `auth0 acul screen add` command will fail — so skip it entirely and go straight to Step 4.
+
+3. **Screen IS in auth0-acul-samples → try the CLI:**
+   ```bash
+   auth0 acul screen add <screen-name> -d <project-dir>
+   ```
+   - **If CLI succeeds → use the scaffolded code directly.** Read the generated files to understand the structure, SDK imports, and hook patterns. Do NOT fetch from GitHub. Customize the CLI-generated code based on the customer's requirements (branding, components, etc.). Proceed to Phase 3.
+   - **If CLI errors despite the screen being in samples** (e.g., auth issues, version mismatch) → fall through to Step 4 as a recovery path.
+
+4. **Screen is NOT in auth0-acul-samples (or CLI failed) → skip CLI, fetch reference directly.**
+
+   Since the CLI does not support this screen, do NOT attempt `auth0 acul screen add` — it will error. Instead, build the screen from reference code.
+
+   **Step 4a — Capture project structure (if not already known):**
+   If this is the first screen being added manually (i.e., you don't already have a reference for the project's directory layout, config wiring, and build setup from a previous CLI-generated screen), create a dummy page:
+   ```bash
+   auth0 acul screen add login-id -d <project-dir>
+   ```
+   - Read the generated dummy screen files to capture the project structure, directory layout, config wiring, and build setup
+   - Then remove the dummy screen files (delete the `login-id/` screen directory)
+
+   If you already have the project structure from a previous CLI-generated or manually-created screen, skip this step.
+
+   **Step 4b — Fetch the screen reference code:**
+   Determine the tech stack of the existing project (React or JS/Vanilla) by inspecting the project files. Then fetch the reference:
+
+   - **React project → check SDK examples in universal-login repo:**
+     - Fetch: `https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-react/examples/<screen-name>.md`
+     - Parse for: exact import path, hook pattern (Pattern A or B), action function names, and payload shapes
+   - **JS/Vanilla project → check JS SDK examples:**
+     - Fetch: `https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-js/examples/<screen-name>.md`
+     - Parse for: manager class name, method names, and payload shapes
+
+   Determine whether the example is React (JSX/TSX, hooks) or plain JS (class-based manager) and match it to the project's framework. If the project is React but only a JS example exists (or vice versa), adapt the patterns accordingly using the appropriate SDK reference (the React SDK section or JS SDK section in this file).
+
+   **Step 4c — Generate the screen files using the project structure**, populated with the SDK reference data from step 4b. This ensures correct directory layout, config integration, and build compatibility. Follow the modular architecture pattern from the "auth0-acul-samples Architecture" section if React, or a single-file component if the example is simple enough.
+
+   **Step 4d — Register the screen so local dev mode can resolve it (REQUIRED).**
+   The CLI auto-registers screens it scaffolds, but **manually generated screens are not registered** — so `auth0 acul dev` (local mode) renders **"Screen '<screen-name>' is not implemented"** even though the files exist and the build passes. (Connected mode reads screens from the tenant, so it works without this step — which is why the bug only shows in local dev.) The screen resolves through a `SCREEN_COMPONENTS` map in `src/utils/screen/screenLoader.ts`.
+
+   **First determine how the project maintains that map — do NOT assume it is hand-edited:**
+
+   1. Check whether `screenLoader.ts` is auto-generated. Open it and look for a banner like `// Auto-generated file`, and check `package.json` scripts for a generator (e.g. `generate:screenLoader`) and `scripts/generate-screen-loader.js`.
+      - **If a generator exists (the common case for CLI-scaffolded projects):** the loader is regenerated by scanning `src/screens/*/index.tsx` against an allowlist (e.g. `src/constants/validScreens.js`). **Do NOT hand-edit `screenLoader.ts` — your edit will be overwritten.** Instead:
+        - Confirm `<screen-name>` is present in the allowlist (`VALID_SCREENS`). If missing, add it there.
+        - Run the generator: `npm run generate:screenLoader` (use the actual script name from `package.json`).
+        - Verify the new entry now appears in `screenLoader.ts`.
+      - **If there is no generator:** hand-edit the `SCREEN_COMPONENTS` map directly:
+        ```ts
+        "<screen-name>": lazy(() => import("@/screens/<screen-name>")),
+        ```
+   2. Either way, confirm the screen's `index.tsx` has a **default export** (`export default <ScreenName>Screen`) — `lazy()` resolves the default export. A named-only export compiles but loads as blank / "not implemented".
+
+   For all screen names and their availability → see the Screen Catalog section in this file.
+
+
+## Phase 2C: Modify Screen — Fetch Current State
+
+1. Verify `acul_config.json` exists.
+
+2. Fetch current rendering configuration:
+   ```bash
+   auth0 acul config get <screen-name> -f <screen-name>.json
+   auth0 acul config list --rendering-mode advanced
+   ```
+
+3. Read the existing screen file from the customer's codebase. **The local code is your primary reference.** Understand its current structure, SDK imports, and hook patterns before making any changes.
+
+4. Only fetch from GitHub references if the local code is missing critical SDK patterns (e.g., wrong hook pattern, missing action functions) and you cannot determine the correct pattern from the existing codebase. Use the Reference Hierarchy (samples availability → CLI scaffolded code when supported → SDK examples) to validate.
+
+
+## Phase 3: Screen Requirements
+
+Gather from the customer:
+
+- **Screen type** — for full list of available screens → see the Screen Catalog section in this file
+- **Components needed:**
+  - Social providers: Google, GitHub, Apple, Microsoft, Facebook
+  - Form fields: email, username, phone, password, confirm-password
+  - MFA type (if applicable): OTP, SMS, push, WebAuthn
+  - Optional extras: captcha, passkey button, remember-me, terms checkbox
+- **For modify mode:** what specifically to change (layout, colors, add/remove a component)
+
+
+## Phase 4: Tech Stack Detection
+
+Confirm or detect:
+
+- **Framework:** React (`@auth0/auth0-acul-react`) or JS (`@auth0/auth0-acul-js`)
+- **Styling library:** Tailwind CSS / CSS Modules / styled-components / plain CSS
+- **Existing theme file?** Check for `tailwind.config.ts`, `styles/tokens.css`, `theme/index.ts`
+
+Load the appropriate SDK reference:
+- React → see the React SDK section in this file
+- JS → see the JS SDK section in this file
+
+For social button implementation → see the Social Providers section in this file.
+
+
+## Phase 5: Theme Extraction & Scope
+
+### Design input — detect which the customer has provided:
+
+**Option A — Image or mockup (jpeg / png / screenshot):**
+Analyze the image and extract:
+- Primary, secondary, accent colors (as hex)
+- Background and card/surface colors
+- Font family and weights
+- Border radius style (sharp / slight / rounded / pill)
+- Spacing rhythm (compact / normal / spacious)
+- Layout type: centered card / full-bleed / split-panel / floating card
+
+**Option B — Brand colors only (no image):**
+Derive the full token set from the provided hex values:
+```
+primary        → button bg, links, focus ring
+primary-hover  → primary darkened ~10%
+primary-text   → white if primary is dark, else #111827
+background     → page background
+surface        → card/panel background
+text-primary   → headings (#111827 light / #F1F5F9 dark)
+text-secondary → labels, placeholders
+border         → input borders
+error          → #EF4444 (unless specified)
+success        → #22C55E (unless specified)
+```
+
+### Theme scope — ask the customer:
+
+- **Single screen:** apply tokens inline to just this component's styles
+- **All screens:** generate a shared theme file first, then apply consistently across every screen
+
+For theme file patterns per styling library → see the Theming Patterns section in this file.
+
+**Theme file to generate per styling library (all-screens scope):**
+
+| Styling library | Template to use | Output file |
+|----------------|-----------------|-------------|
+| Tailwind | `assets/acul/theme-templates/tailwind.config.ts` | `tailwind.config.ts` |
+| CSS Modules | `assets/acul/theme-templates/tokens.css` | `styles/tokens.css` |
+| styled-components | `assets/acul/theme-templates/theme-provider.ts` | `theme/index.ts` |
+| Plain CSS | `assets/acul/theme-templates/globals.css` | `styles/globals.css` |
+
+Replace all `{{TOKEN}}` placeholders with extracted token values.
+
+
+## Phase 6: Structured Code Generation
+
+Generation approach depends on the source of the screen code.
+
+### Path A — CLI-scaffolded screen (preferred)
+
+When the CLI successfully generates the screen (via `auth0 acul init` or `auth0 acul screen add`), use the CLI output as the base. Read the generated files and customise them based on the customer's requirements:
+
+- Apply design tokens from Phase 5 to the generated component styling
+- Add/remove components as specified (social buttons, captcha, passkey, etc.)
+- Adjust layout and structure per the customer's design input
+- Preserve the CLI's SDK imports, hook patterns, and action functions — they are correct
+
+Do NOT discard CLI-generated code to re-generate from a GitHub reference.
+
+### Path B — Screen from auth0-acul-samples (only when CLI doesn't support the screen)
+
+Use the project structure captured from the CLI dummy-page strategy (Phase 2B, Step 4a) as the foundation. Generate the screen directory using the samples pattern (see "auth0-acul-samples Architecture" above), matching the directory layout and config wiring from the dummy page:
+
+```
+<screen-name>/
+├── index.tsx
+├── components/
+│   ├── Header.tsx
+│   ├── <ScreenName>Form.tsx
+│   ├── Footer.tsx
+│   └── AlternativeLogins.tsx       (only if screen has social login)
+├── hooks/
+│   └── use<ScreenName>Manager.ts
+└── locales/
+    └── en.json
+```
+
+- `index.tsx` — thin: calls `use<ScreenName>Manager()`, calls `applyAuth0Theme()`, renders `ULThemePageLayout` → `ULThemeCard` → sub-components
+- `use<ScreenName>Manager.ts` — wraps SDK hooks from the samples reference, exposes typed handlers and feature flags
+- Form component — uses react-hook-form, reads from manager hook, no direct SDK calls
+- Header/Footer — stateless, receive texts as props
+- `en.json` — fallback strings matching keys used in `screen.texts.*`
+
+Apply design tokens from Phase 5 to the layout components and form component styling.
+
+### Path C — Screen is NOT in auth0-acul-samples (single-file component)
+
+Generate a single `<screen-name>.tsx` (React) or `<screen-name>.js` (JS) using the structure from `assets/acul/react-templates/` or `assets/acul/js-templates/` as a pattern, with hooks and actions sourced entirely from the SDK example fetched in Phase 2.
+
+JSX structure order:
+```
+Outer layout wrapper → Card/panel → Logo slot → Title (screen.texts) →
+Error banner (conditional) → Form fields → Captcha (conditional) →
+Submit button → Passkey button (conditional) → Social divider + buttons
+(conditional on alternateConnections) → Footer links
+```
+
+### Screen Registration (Path B and Path C only)
+
+The CLI auto-registers any screen it scaffolds (Path A). **Manually generated screens (Path B, Path C) must be registered**, or local `auth0 acul dev` renders **"Screen '<screen-name>' is not implemented"** — even though the files exist and the build succeeds. (Connected mode resolves screens from the tenant, so it works without this step — which is why the bug only shows in local dev.) Screens resolve through a `SCREEN_COMPONENTS` map in `src/utils/screen/screenLoader.ts`.
+
+For each manually generated screen:
+
+1. **Determine how `screenLoader.ts` is maintained — do not assume it's hand-edited.** If it carries an `// Auto-generated file` banner or `package.json` has a generator script (e.g. `generate:screenLoader` backed by `scripts/generate-screen-loader.js`), it is regenerated by scanning `src/screens/*/index.tsx` against an allowlist:
+   - Ensure `<screen-name>` is in the allowlist (e.g. `src/constants/validScreens.js`), then run `npm run generate:screenLoader`. **Do not hand-edit the generated file** — it will be overwritten.
+   - Only if no generator exists, add the entry manually: `"<screen-name>": lazy(() => import("@/screens/<screen-name>")),`
+2. Ensure the screen's `index.tsx` (or single-file component) has a `export default` — `React.lazy` resolves the **default** export, not a named one.
+
+### Validation before outputting any code
+
+- SDK import path exactly matches the screen name (e.g., `@auth0/auth0-acul-react/mfa-otp-challenge`)
+- Hook pattern (generic `useScreen()` vs screen-specific hook) sourced from the CLI-generated code or reference, not assumed
+- Action function names and payload shapes sourced from the CLI-generated code or reference
+- Error state uses SDK source (`hasErrors` / `getErrors()`) — never local-only error state
+- No hardcoded UI strings — use `screen.texts.*` with locale fallback
+- `applyAuth0Theme()` called in index.tsx when using modular architecture (Path A, Path B)
+- **Manually generated screens (Path B, Path C) registered in `src/utils/screen/screenLoader.ts` with a matching `export default`** — required for local `auth0 acul dev`
+
+**All-screens scope:** repeat Path A, B, or C (whichever applies per screen) for every screen in the project, all importing from the shared theme file. Consistent component structure within each path.
+
+
+## Phase 7: Build Validation & Iterative Fix
+
+After generating or modifying screen code, **always** validate the output before moving on. Generated code may contain incorrect import paths, wrong import styles (default vs named), invalid component props, or references to non-existent exports. This phase catches and fixes those issues automatically.
+
+### Step 1 — Install new dependencies (if any)
+
+If the generated or modified code introduced **new dependencies** in `package.json` (entries under `dependencies` / `devDependencies` that aren't already installed in `node_modules`), run `npm install` from the project root before linting/building. Skip this step if no new packages were added.
+
+```bash
+# Run from the project root
+npm install
+```
+
+If install fails (peer-dependency conflict, registry error, version mismatch), surface the error to the customer and stop — do not proceed to lint/build until resolved.
+
+### Step 2 — Run lint
+
+Run the project's linter to surface import errors, type mismatches, and invalid props:
+
+```bash
+# Detect the lint command from package.json scripts
+npm run lint 2>&1 || npx eslint src/screens/<screen-name>/ --ext .ts,.tsx,.js,.jsx 2>&1
+```
+
+If the project uses TypeScript, also run the type checker:
+
+```bash
+npx tsc --noEmit 2>&1
+```
+
+### Step 3 — Run build
+
+```bash
+npm run build 2>&1
+```
+
+### Step 4 — Parse errors and fix iteratively
+
+If lint or build produces errors, parse each error and apply the appropriate fix:
+
+| Error pattern | Root cause | Fix |
+|---------------|-----------|-----|
+| `does not have a default export` | Using `import X` on a named export | Change to `import { X }` |
+| `has no exported member` | Importing a symbol that doesn't exist in the module | Read the source module to find the correct export name |
+| `Module not found` / `Cannot find module` | Wrong import path | Verify the correct path from `node_modules` or the project's own source tree |
+| `Property 'X' does not exist on type` | Invalid prop passed to a component | Read the component's type definition or source to find valid props |
+| `is not assignable to type` | Prop type mismatch | Cast or transform the value to match the expected type |
+| `JSX element type 'X' does not have any construct or call signatures` | Component imported incorrectly or doesn't exist | Verify the component exists and is exported correctly from its module |
+
+**Fix workflow:**
+1. Read the error output — identify the file, line, and error code.
+2. Read the source file at the error location to understand context.
+3. If the error involves an import — read the target module (from `node_modules` or project source) to find the correct export names and paths.
+4. Apply the fix.
+5. Re-run `npm run build 2>&1`.
+6. Repeat from step 1 until the build succeeds.
+
+**Iteration cap:** Use a hard cap of **5 iterations**. If errors plateau (same count or same errors across 2 consecutive iterations), stop immediately before the cap. When the cap is reached and errors remain, present the remaining errors to the customer and ask for guidance rather than continuing to modify code.
+
+### Common pitfalls this phase catches
+
+- `import Component from './Component'` when the file uses `export const Component` (named export) — fix: `import { Component } from './Component'`
+- `import { useLoginId } from '@auth0/auth0-acul-react'` instead of the screen-specific path `@auth0/auth0-acul-react/login-id` — fix: use the correct sub-path import
+- Using `<ULThemeCard title={...}>` when `ULThemeCard` doesn't accept a `title` prop — fix: remove the invalid prop and use a `<Header>` child component instead
+- Importing a theme utility from a path that doesn't exist in the project — fix: verify the actual path in the project tree
+- Using `applyAuth0Theme` as a named import when it's a default export (or vice versa) — fix: match the module's actual export style
+
+### Runtime check the build CANNOT catch: unregistered screens
+
+A clean `npm run build` does **not** guarantee a manually added screen renders in local dev. The build passes, but `auth0 acul dev` shows **"Screen '<screen-name>' is not implemented"** when:
+
+- The screen is missing from the `SCREEN_COMPONENTS` map in `src/utils/screen/screenLoader.ts`, OR
+- The screen's `index.tsx` has no `export default` (so `lazy()` can't resolve the component).
+
+For every screen generated via Path B or Path C, verify both before finishing. This is a runtime/registry gap, not a compile error — lint and `tsc` will not flag it. If the project auto-generates `screenLoader.ts`, register via its generator (`npm run generate:screenLoader`) rather than hand-editing. (See "Screen Registration" in Phase 6.)
+
+### Successful validation
+
+Once the build completes with **exit code 0** and no lint errors, **and every manually added screen is registered in `screenLoader.ts` with a `export default`**, proceed to Phase 8.
+
+
+## Phase 8: Dev Mode Wiring
+
+Provide the customer with ready-to-run commands:
+
+```bash
+# Local preview — no tenant connection needed
+auth0 acul dev -p 3000 -d <project-dir>
+
+# Connected mode — syncs assets to tenant (stage/dev only)
+auth0 acul dev --connected -s <screen-name> -d <project-dir>
+```
+
+⚠️ Always include this warning when connected mode is suggested:
+> Connected mode updates your Auth0 tenant in real time. Only use this on a stage or development tenant — never on production.
+
+
+## Reference Files
+
+| File | Load when |
+|------|-----------|
+| React SDK section (in this file) | Framework is React |
+| JS SDK section (in this file) | Framework is JS / Vanilla |
+| Screen Catalog section (in this file) | Selecting screen type or triggering CLI fallback |
+| Social Providers section (in this file) | Social login buttons are needed |
+| Theming Patterns section (in this file) | Generating or applying a shared theme file |
+| CLI Commands section (in this file) | Need full CLI flag details |
+
+## Asset Templates
+
+| File | Use when |
+|------|----------|
+| `assets/acul/theme-templates/tailwind.config.ts` | Tailwind, all-screens scope |
+| `assets/acul/theme-templates/tokens.css` | CSS Modules, all-screens scope |
+| `assets/acul/theme-templates/theme-provider.ts` | styled-components |
+| `assets/acul/theme-templates/globals.css` | Plain CSS, all-screens scope |
+| `assets/acul/react-templates/<screen>.tsx` | React component boilerplate base |
+| `assets/acul/js-templates/<screen>.js` | JS component boilerplate base |
+
+---
+
+# Auth0 ACUL React SDK Reference
+
+Package: `@auth0/auth0-acul-react`
+
+Each screen has its own import path. Import hooks and action functions from the screen-specific path.
+
+---
+
+## Import Pattern
+
+```tsx
+import {
+  useScreen,
+  useTransaction,
+  useErrors,
+  useLoginIdentifiers,
+  login,
+  federatedLogin,
+  passkeyLogin,
+} from '@auth0/auth0-acul-react/login-id'
+```
+
+Replace `login-id` with the screen name (e.g., `signup`, `login-password`, `mfa-otp-challenge`).
+
+---
+
+## Common Hooks
+
+### `useScreen()`
+Returns screen configuration and localised text strings.
+```tsx
+const screen = useScreen()
+screen.texts?.title          // screen heading text
+screen.texts?.description    // subheading/description
+screen.name                  // current screen name
+screen.links?.signUp         // navigation link to signup
+screen.links?.resetPassword  // navigation link to password reset
+screen.links?.login          // navigation link to login
+```
+
+### `useTransaction()`
+Returns transaction state and available connections.
+```tsx
+const { hasErrors, alternateConnections, connection } = useTransaction()
+alternateConnections   // array of social/enterprise connections
+connection.name        // primary connection name
+```
+
+### `useErrors()`
+Returns error state from the current transaction.
+```tsx
+const { hasErrors, errors } = useErrors()
+// errors: array of { code, message }
+```
+
+### `useLoginIdentifiers()`
+Returns active identifier types for dynamic label generation.
+```tsx
+const identifiers = useLoginIdentifiers()
+// ['email', 'username'] → "Enter your email or username"
+```
+
+---
+
+## Action Functions
+
+Action functions are imported alongside hooks and called from event handlers.
+
+### Authentication actions
+```tsx
+login({ username, password, captcha })         // login-id, login-password
+federatedLogin({ connection: 'google-oauth2' }) // social login
+passkeyLogin()                                  // passkey prompt (native dialog)
+pickCountryCode()                               // phone country code picker
+```
+
+### Signup actions
+```tsx
+signup({ email, password, username })
+```
+
+### MFA actions
+```tsx
+continueWithMfaOtp({ code })
+continueWithMfaSms({ code })
+continueWithEmail({ code })
+enrollWithTotp({ code })
+```
+
+### Password reset actions
+```tsx
+requestPasswordReset({ email })
+resetPassword({ password, confirmPassword })
+```
+
+### Session actions
+```tsx
+logout()
+```
+
+---
+
+## Standard Component Structure
+
+```tsx
+import React, { useState } from 'react'
+import {
+  useScreen, useTransaction, useErrors,
+  login, federatedLogin, passkeyLogin,
+} from '@auth0/auth0-acul-react/login-id'
+
+export const LoginIdScreen: React.FC = () => {
+  // 1. SDK hooks
+  const screen = useScreen()
+  const { alternateConnections } = useTransaction()
+  const { hasErrors, errors } = useErrors()
+
+  // 2. Local state
+  const [username, setUsername] = useState('')
+  const [loading, setLoading] = useState(false)
+  const [captcha, setCaptcha] = useState('')
+
+  // 3. Event handlers
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setLoading(true)
+    await login({ username, captcha })
+    setLoading(false)
+  }
+
+  const handleSocial = async (connectionName: string) => {
+    await federatedLogin({ connection: connectionName })
+  }
+
+  // 4. JSX
+  return (
+    <div className="page-wrapper">
+      <div className="card">
+        {/* Logo slot */}
+        <div className="logo-slot" />
+
+        {/* Title from screen config */}
+        <h1>{screen.texts?.title ?? 'Log in'}</h1>
+
+        {/* Error banner */}
+        {hasErrors && (
+          <div className="error-banner">
+            {errors.map(e => <p key={e.code}>{e.message}</p>)}
+          </div>
+        )}
+
+        {/* Form */}
+        <form onSubmit={handleSubmit}>
+          <label htmlFor="username">
+            {screen.texts?.usernameLabel ?? 'Email or username'}
+          </label>
+          <input
+            id="username"
+            type="text"
+            value={username}
+            onChange={e => setUsername(e.target.value)}
+          />
+          <button type="submit" disabled={loading}>
+            {loading ? 'Logging in...' : (screen.texts?.buttonText ?? 'Continue')}
+          </button>
+        </form>
+
+        {/* Social login */}
+        {alternateConnections?.length > 0 && (
+          <>
+            <div className="divider"><span>Or</span></div>
+            {alternateConnections.map(conn => (
+              <button
+                key={conn.name}
+                onClick={() => handleSocial(conn.name)}
+                className="social-btn"
+              >
+                Continue with {conn.displayName}
+              </button>
+            ))}
+          </>
+        )}
+
+        {/* Footer links */}
+        <div className="footer-links">
+          <a href="#">Sign up</a>
+          <a href="#">Forgot password?</a>
+        </div>
+      </div>
+    </div>
+  )
+}
+```
+
+---
+
+## Conditional Features
+
+```tsx
+// Captcha (check if configured)
+{screen.isCaptchaAvailable && (
+  <input value={captcha} onChange={e => setCaptcha(e.target.value)} />
+)}
+
+// Passkey button
+{screen.isPasskeyEnabled && (
+  <button onClick={() => passkeyLogin()}>Use passkey</button>
+)}
+
+// Country code for phone flows
+{screen.isPhoneFlow && (
+  <button onClick={() => pickCountryCode()}>+1</button>
+)}
+```
+
+---
+
+## Screen-Specific Imports Quick Reference
+
+| Screen | Import path |
+|--------|-------------|
+| login-id | `@auth0/auth0-acul-react/login-id` |
+| login-password | `@auth0/auth0-acul-react/login-password` |
+| signup | `@auth0/auth0-acul-react/signup` |
+| signup-id | `@auth0/auth0-acul-react/signup-id` |
+| signup-password | `@auth0/auth0-acul-react/signup-password` |
+| mfa-otp-challenge | `@auth0/auth0-acul-react/mfa-otp-challenge` |
+| mfa-email-challenge | `@auth0/auth0-acul-react/mfa-email-challenge` |
+| mfa-sms-challenge | `@auth0/auth0-acul-react/mfa-sms-challenge` |
+| reset-password-request | `@auth0/auth0-acul-react/reset-password-request` |
+| reset-password | `@auth0/auth0-acul-react/reset-password` |
+| passkey-enrollment | `@auth0/auth0-acul-react/passkey-enrollment` |
+
+For full screen list and fallback URLs → see the Screen Catalog section in this file.
+
+---
+
+# Auth0 ACUL JS SDK Reference
+
+Package: `@auth0/auth0-acul-js`
+
+Uses a manager class pattern. Each screen exports a default class with methods matching available actions.
+
+---
+
+## Import Pattern
+
+```typescript
+import LoginId from '@auth0/auth0-acul-js/login-id'
+
+const manager = new LoginId()
+```
+
+Replace `login-id` with the screen name. Class name is PascalCase of the screen name.
+
+---
+
+## Manager Instance Properties
+
+```typescript
+manager.transaction.hasErrors          // boolean
+manager.transaction.alternateConnections  // social/enterprise connections array
+manager.transaction.connection         // primary connection
+manager.getErrors()                    // returns array of { code, message }
+manager.screen.texts                   // localised text strings
+manager.screen.name                    // current screen name
+manager.screen.isCaptchaAvailable      // boolean
+manager.screen.isPasskeyEnabled        // boolean
+```
+
+---
+
+## Common Methods by Screen
+
+### Login screens
+```typescript
+// login-id
+const manager = new LoginId()
+await manager.login({ username: 'user@example.com', captcha: '...' })
+await manager.federatedLogin({ connection: 'google-oauth2' })
+await manager.passkeyLogin()
+await manager.pickCountryCode()
+
+// login-password
+const manager = new LoginPassword()
+await manager.login({ password: 'secret', captcha: '...' })
+await manager.federatedLogin({ connection: 'google-oauth2' })
+await manager.passkeyLogin()
+```
+
+### Signup screens
+```typescript
+const manager = new Signup()
+await manager.signup({ email: 'user@example.com', password: 'secret' })
+await manager.federatedLogin({ connection: 'google-oauth2' })
+```
+
+### MFA screens
+```typescript
+// mfa-otp-challenge
+const manager = new MfaOtpChallenge()
+await manager.continueWithMfaOtp({ code: '123456' })
+
+// mfa-sms-challenge
+const manager = new MfaSmsChallenge()
+await manager.continueWithMfaSms({ code: '123456' })
+
+// mfa-email-challenge
+const manager = new MfaEmailChallenge()
+await manager.continueWithEmail({ code: '123456' })
+```
+
+### Password reset screens
+```typescript
+const manager = new ResetPasswordRequest()
+await manager.requestPasswordReset({ email: 'user@example.com' })
+
+const manager = new ResetPassword()
+await manager.resetPassword({ password: 'newpass', confirmPassword: 'newpass' })
+```
+
+---
+
+## Standard Component Structure (Vanilla JS)
+
+```javascript
+import LoginId from '@auth0/auth0-acul-js/login-id'
+
+const manager = new LoginId()
+
+function render() {
+  const container = document.getElementById('app')
+  container.innerHTML = `
+    <div class="page-wrapper">
+      <div class="card">
+        <div class="logo-slot"></div>
+        <h1>${manager.screen.texts?.title ?? 'Log in'}</h1>
+
+        ${manager.transaction.hasErrors ? `
+          <div class="error-banner">
+            ${manager.getErrors().map(e => `<p>${e.message}</p>`).join('')}
+          </div>
+        ` : ''}
+
+        <form id="login-form">
+          <label for="username">
+            ${manager.screen.texts?.usernameLabel ?? 'Email or username'}
+          </label>
+          <input id="username" type="text" name="username" />
+
+          ${manager.screen.isCaptchaAvailable ? `
+            <input id="captcha" type="text" placeholder="Enter captcha" />
+          ` : ''}
+
+          <button type="submit">
+            ${manager.screen.texts?.buttonText ?? 'Continue'}
+          </button>
+        </form>
+
+        ${manager.transaction.alternateConnections?.length ? `
+          <div class="divider"><span>Or</span></div>
+          ${manager.transaction.alternateConnections.map(conn => `
+            <button class="social-btn" data-connection="${conn.name}">
+              Continue with ${conn.displayName}
+            </button>
+          `).join('')}
+        ` : ''}
+
+        <div class="footer-links">
+          <a href="#">Sign up</a>
+          <a href="#">Forgot password?</a>
+        </div>
+      </div>
+    </div>
+  `
+
+  // Attach event listeners after render
+  document.getElementById('login-form').addEventListener('submit', async (e) => {
+    e.preventDefault()
+    const username = document.getElementById('username').value
+    const captcha = document.getElementById('captcha')?.value
+    await manager.login({ username, captcha })
+  })
+
+  document.querySelectorAll('.social-btn').forEach(btn => {
+    btn.addEventListener('click', async () => {
+      const connection = btn.dataset.connection
+      await manager.federatedLogin({ connection })
+    })
+  })
+
+  if (manager.screen.isPasskeyEnabled) {
+    // Passkey button handler
+    document.getElementById('passkey-btn')?.addEventListener('click', async () => {
+      await manager.passkeyLogin()
+    })
+  }
+}
+
+render()
+```
+
+---
+
+## Manager Class Name Reference
+
+| Screen | Import path | Class name |
+|--------|-------------|------------|
+| login-id | `@auth0/auth0-acul-js/login-id` | `LoginId` |
+| login-password | `@auth0/auth0-acul-js/login-password` | `LoginPassword` |
+| signup | `@auth0/auth0-acul-js/signup` | `Signup` |
+| signup-id | `@auth0/auth0-acul-js/signup-id` | `SignupId` |
+| signup-password | `@auth0/auth0-acul-js/signup-password` | `SignupPassword` |
+| mfa-otp-challenge | `@auth0/auth0-acul-js/mfa-otp-challenge` | `MfaOtpChallenge` |
+| mfa-email-challenge | `@auth0/auth0-acul-js/mfa-email-challenge` | `MfaEmailChallenge` |
+| mfa-sms-challenge | `@auth0/auth0-acul-js/mfa-sms-challenge` | `MfaSmsChallenge` |
+| reset-password-request | `@auth0/auth0-acul-js/reset-password-request` | `ResetPasswordRequest` |
+| reset-password | `@auth0/auth0-acul-js/reset-password` | `ResetPassword` |
+| passkey-enrollment | `@auth0/auth0-acul-js/passkey-enrollment` | `PasskeyEnrollment` |
+
+For full screen list and fallback URLs → see the Screen Catalog section in this file.
+
+---
+
+# Auth0 ACUL CLI Commands Reference
+
+Full reference for `auth0 acul` commands. Requires Auth0 CLI installed (`brew install auth0`).
+
+---
+
+## Authentication
+
+```bash
+auth0 login                        # authenticate with Auth0 tenant
+auth0 login --tenant <tenant>      # authenticate to a specific tenant
+```
+
+---
+
+## auth0 acul init
+
+Generates a new ACUL project from a template.
+
+```bash
+auth0 acul init <app_name>
+auth0 acul init <app_name> -t react -s login,signup
+auth0 acul init <app_name> -t react -s login,login-id,login-password,signup,reset-password
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--template` | `-t` | Framework template: `react` or `js` |
+| `--screens` | `-s` | Comma-separated screen list |
+| `--tenant` | | Target a specific tenant |
+| `--no-input` | | Disable interactive prompts |
+
+Creates `acul_config.json` in the project directory — required for all subsequent commands.
+
+---
+
+## auth0 acul screen add
+
+Adds screens to an existing ACUL project. Project must already be initialized.
+
+```bash
+auth0 acul screen add <screen-name> -d <project-dir>
+auth0 acul screen add login-id login-password -d ./acul_app
+auth0 acul screen add mfa-otp-challenge -d ./my-project
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--dir` | `-d` | Path to project directory (must contain `acul_config.json`) |
+| `--tenant` | | Target a specific tenant |
+
+**ON ERROR:** Fall back to SDK examples — see the Screen Catalog section in this file for URLs.
+
+---
+
+## auth0 acul config
+
+### List configurations
+
+```bash
+auth0 acul config list
+auth0 acul config list --rendering-mode advanced
+auth0 acul config list --screen login-id
+auth0 acul config list --prompt login --rendering-mode advanced --fields head_tags,context_configuration
+```
+
+| Flag | Description |
+|------|-------------|
+| `--prompt` | Filter by Universal Login prompt |
+| `--rendering-mode` | Filter by mode: `advanced` or `standard` |
+| `--screen` | Filter by screen name |
+| `--fields` | Comma-separated fields to include |
+| `--json` | Output as JSON |
+| `--page` | Page index (starts at 0) |
+| `--per-page` | Results per page (default 50, max 100) |
+
+### Get screen config
+
+```bash
+auth0 acul config get <screen-name>
+auth0 acul config get login-id -f ./acul_config/login-id.json
+auth0 acul config get signup-id --file settings.json
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--file` | `-f` | Save config to file path |
+
+### Set screen config
+
+```bash
+auth0 acul config set <screen-name>
+auth0 acul config set login-id --file settings.json
+```
+
+### Generate config stub
+
+```bash
+auth0 acul config generate <screen-name>
+auth0 acul config generate login-id --file login-settings.json
+```
+
+Generates a stub `.json` config file for a screen. Use after `screen add` or during scratch setup.
+
+---
+
+## auth0 acul dev
+
+Starts development mode with automatic build watching.
+
+```bash
+# Local preview (no tenant connection)
+auth0 acul dev -p 3000
+auth0 acul dev -p 3000 -d ./my-project
+
+# Connected mode — updates rendering settings on tenant (stage/dev only)
+auth0 acul dev --connected -s login-id
+auth0 acul dev -c -s login-id,signup -d ./my-project
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--port` | `-p` | Local dev server port (required) |
+| `--dir` | `-d` | ACUL project directory path |
+| `--connected` | `-c` | Connected mode: syncs to tenant |
+| `--screens` | `-s` | Specific screens to develop |
+
+⚠️ **Connected mode warning:** only use on stage/dev tenants, never production.
+
+---
+
+## Typical Workflows
+
+### Scratch setup
+```bash
+auth0 login
+auth0 acul init my-app -t react -s login-id,login-password,signup
+cd my-app
+auth0 acul config generate login-id
+auth0 acul dev -p 3000
+```
+
+### Add a screen to existing project
+```bash
+auth0 acul screen add mfa-otp-challenge -d ./my-app
+auth0 acul config generate mfa-otp-challenge -f ./my-app/acul_config/mfa-otp-challenge.json
+auth0 acul dev -p 3000 -d ./my-app
+```
+
+### Inspect current tenant ACUL state
+```bash
+auth0 acul config list --rendering-mode advanced --json
+auth0 acul config get login-id -f login-id-current.json
+```
+
+---
+
+# ACUL Screen Catalog
+
+Complete reference for all 68 React + 71 JS ACUL screens with their reference sources, SDK callbacks, and URLs.
+
+**Reference priority per screen:**
+1. **auth0-acul-samples** if `Samples` column = ✅ → fetch full modular implementation
+2. **SDK examples** if `Samples` column = ❌ → fetch the markdown example for SDK usage
+3. **assets/templates** — structural pattern only, never for hooks/actions
+
+The `Samples` column marks which screens have a complete implementation in `auth0-acul-samples`.
+
+> **Note:** `continueMethod()` in the tables below is a placeholder — the actual method name is screen-specific (e.g., `continueWithMfaOtp()`, `continueWithMfaSms()`). Always fetch the SDK example to get the exact method name and payload shape.
+
+## Table of Contents
+1. [URL Patterns](#url-patterns)
+2. [Hook Patterns](#hook-patterns)
+3. [Login & Authentication](#login--authentication)
+4. [Signup & Registration](#signup--registration)
+5. [Password Reset](#password-reset)
+6. [Password Reset + MFA Challenges](#password-reset--mfa-challenges)
+7. [MFA — Enrollment & Options](#mfa--enrollment--options)
+8. [MFA — Email](#mfa--email)
+9. [MFA — SMS / Voice / Phone](#mfa--sms--voice--phone)
+10. [MFA — OTP (TOTP)](#mfa--otp-totp)
+11. [MFA — Push Notifications](#mfa--push-notifications)
+12. [MFA — WebAuthn](#mfa--webauthn)
+13. [MFA — Recovery Codes](#mfa--recovery-codes)
+14. [Passkeys](#passkeys)
+15. [Identifier Challenges](#identifier-challenges)
+16. [Device Authorization](#device-authorization)
+17. [Organization Management](#organization-management)
+18. [Consent & Security](#consent--security)
+19. [Session / Logout](#session--logout)
+20. [Email Verification](#email-verification)
+21. [JS-Only Screens](#js-only-screens)
+
+---
+
+## URL Patterns
+
+### auth0-acul-samples (Priority 1)
+```
+React:
+  directory: https://github.com/auth0-samples/auth0-acul-samples/tree/main/react/src/screens/<screen-name>
+  index.tsx:  https://github.com/auth0-samples/auth0-acul-samples/blob/main/react/src/screens/<screen-name>/index.tsx
+  manager:    https://github.com/auth0-samples/auth0-acul-samples/blob/main/react/src/screens/<screen-name>/hooks/use<ScreenName>Manager.ts
+
+React-JS:
+  directory: https://github.com/auth0-samples/auth0-acul-samples/tree/main/react-js/src/screens/<screen-name>
+  index.tsx:  https://github.com/auth0-samples/auth0-acul-samples/blob/main/react-js/src/screens/<screen-name>/index.tsx
+```
+
+### SDK examples (Priority 2)
+```
+React: https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-react/examples/<screen-name>.md
+JS:    https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-js/examples/<screen-name>.md
+```
+
+---
+
+## Hook Patterns
+
+ACUL screens use two patterns. The reference fetch tells you which applies.
+
+**Pattern A — Generic hooks** (most login/signup screens):
+```tsx
+import { useScreen, useTransaction, useErrors, login } from '@auth0/auth0-acul-react/<screen>'
+const screen = useScreen()
+const { alternateConnections } = useTransaction()
+```
+
+**Pattern B — Screen-specific hook** (most MFA, reset-password-mfa, recovery screens):
+```tsx
+import { useScreenName, continueMethod } from '@auth0/auth0-acul-react/<screen>'
+const screen = useScreenName()   // e.g., useMfaRecoveryCodeEnrollment()
+await continueMethod({ ...payload })
+```
+
+**JS — Manager class** (both patterns map to this):
+```js
+import ScreenClass from '@auth0/auth0-acul-js/<screen>'
+const manager = new ScreenClass()
+await manager.continueMethod({ ...payload })
+```
+
+---
+
+## Login & Authentication
+
+| Screen | Samples (React) | Samples (React-JS) | SDK React | SDK JS | Primary Action | Notes |
+|--------|-----------------|--------------------|-----------|--------|----------------|-------|
+| `login` | ✅ | ✅ | ✅ | ✅ | `login()`, `federatedLogin()` | All-identifier login |
+| `login-id` | ✅ | ✅ | ✅ | ✅ | `login()`, `federatedLogin()`, `passkeyLogin()` | Identifier-first step |
+| `login-password` | ✅ | ✅ | ✅ | ✅ | `login()`, `federatedLogin()`, `passkeyLogin()` | Password entry step |
+| `login-passwordless-email-code` | ✅ | ❌ | ✅ | ✅ | `continueMethod()` | Email OTP |
+| `login-passwordless-sms-otp` | ✅ | ❌ | ✅ | ✅ | `continueMethod()` | SMS OTP |
+| `login-email-verification` | ❌ | ❌ | ✅ | ✅ | — | Gate screen, no action |
+
+---
+
+## Signup & Registration
+
+| Screen | Samples (React) | Samples (React-JS) | SDK React | SDK JS | Primary Action | Notes |
+|--------|-----------------|--------------------|-----------|--------|----------------|-------|
+| `signup` | ✅ | ❌ | ✅ | ✅ | `signup()`, `federatedLogin()` | Combined signup |
+| `signup-id` | ✅ | ❌ | ✅ | ✅ | `signup()`, `federatedLogin()` | Identifier-first |
+| `signup-password` | ✅ | ❌ | ✅ | ✅ | `signup()` | Password entry |
+| `accept-invitation` | ❌ | ❌ | ✅ | ✅ | `signup()` | Org invite |
+| `redeem-ticket` | ❌ | ❌ | ✅ | ✅ | — | Ticket-based access |
+
+---
+
+## Password Reset
+
+| Screen | Samples (React) | Samples (React-JS) | SDK React | SDK JS | Primary Action | Notes |
+|--------|-----------------|--------------------|-----------|--------|----------------|-------|
+| `reset-password-request` | ✅ | ❌ | ✅ | ✅ | `requestPasswordReset()` | Sends reset email |
+| `reset-password-email` | ✅ | ❌ | ✅ | ✅ | — | Email sent confirmation |
+| `reset-password` | ✅ | ❌ | ✅ | ✅ | `continueMethod()` | Enter new password |
+| `reset-password-success` | ✅ | ❌ | ✅ | ✅ | — | Success state |
+| `reset-password-error` | ✅ | ❌ | ✅ | ✅ | — | Error state |
+
+---
+
+## Password Reset + MFA Challenges
+
+All screens: Pattern B (screen-specific hook + `continueMethod()`). Not in samples — use SDK examples.
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action |
+|--------|-----------------|-----------|--------|----------------|
+| `reset-password-mfa-email-challenge` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `reset-password-mfa-otp-challenge` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `reset-password-mfa-phone-challenge` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `reset-password-mfa-push-challenge-push` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `reset-password-mfa-recovery-code-challenge` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `reset-password-mfa-sms-challenge` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `reset-password-mfa-voice-challenge` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `reset-password-mfa-webauthn-platform-challenge` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `reset-password-mfa-webauthn-roaming-challenge` | ❌ | ✅ | ✅ | `continueMethod()` |
+
+---
+
+## MFA — Enrollment & Options
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action | Notes |
+|--------|-----------------|-----------|--------|----------------|-------|
+| `mfa-begin-enroll-options` | ✅ | ✅ | ✅ | — | Options list |
+| `mfa-login-options` | ✅ | ✅ | ✅ | — | Login method picker |
+| `mfa-detect-browser-capabilities` | ❌ | ✅ | ✅ | — | Capability check |
+| `mfa-enroll-result` | ✅ | ✅ | ✅ | — | Enrollment confirmation |
+| `mfa-country-codes` | ✅ | ✅ | ✅ | `continueMethod()` | Phone country picker |
+
+---
+
+## MFA — Email
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action |
+|--------|-----------------|-----------|--------|----------------|
+| `mfa-email-challenge` | ✅ | ✅ | ✅ | `continueMethod()` |
+| `mfa-email-list` | ✅ | ✅ | ✅ | — |
+
+---
+
+## MFA — SMS / Voice / Phone
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action |
+|--------|-----------------|-----------|--------|----------------|
+| `mfa-sms-challenge` | ✅ | ✅ | ✅ | `continueMethod()` |
+| `mfa-sms-enrollment` | ✅ | ✅ | ✅ | `continueMethod()` |
+| `mfa-sms-list` | ✅ | ✅ | ✅ | — |
+| `mfa-voice-challenge` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `mfa-voice-enrollment` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `mfa-phone-challenge` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `mfa-phone-enrollment` | ❌ | ✅ | ✅ | `continueMethod()` |
+
+---
+
+## MFA — OTP (TOTP)
+
+Not in samples — use SDK examples.
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action |
+|--------|-----------------|-----------|--------|----------------|
+| `mfa-otp-challenge` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `mfa-otp-enrollment-qr` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `mfa-otp-enrollment-code` | ❌ | ✅ | ✅ | `continueMethod()` |
+
+---
+
+## MFA — Push Notifications
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action |
+|--------|-----------------|-----------|--------|----------------|
+| `mfa-push-welcome` | ✅ | ✅ | ✅ | — |
+| `mfa-push-enrollment-qr` | ✅ | ✅ | ✅ | `continueMethod()` |
+| `mfa-push-challenge-push` | ✅ | ✅ | ✅ | `continueMethod()` |
+| `mfa-push-list` | ✅ | ✅ | ✅ | — |
+
+---
+
+## MFA — WebAuthn
+
+Not in samples — use SDK examples.
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action | Notes |
+|--------|-----------------|-----------|--------|----------------|-------|
+| `mfa-webauthn-platform-enrollment` | ❌ | ✅ | ✅ | `submitPasskeyCredential()`, `snoozeEnrollment()`, `refuseEnrollmentOnThisDevice()` | 3 actions |
+| `mfa-webauthn-platform-challenge` | ❌ | ✅ | ✅ | `continueMethod()` | |
+| `mfa-webauthn-roaming-enrollment` | ❌ | ✅ | ✅ | `continueMethod()` | |
+| `mfa-webauthn-roaming-challenge` | ❌ | ✅ | ✅ | `continueMethod()` | |
+| `mfa-webauthn-change-key-nickname` | ❌ | ✅ | ✅ | `continueMethod()` | |
+| `mfa-webauthn-enrollment-success` | ❌ | ✅ | ✅ | — | Success state |
+| `mfa-webauthn-error` | ❌ | ✅ | ✅ | — | Error state |
+| `mfa-webauthn-not-available-error` | ❌ | ✅ | ✅ | — | Capability error |
+
+---
+
+## MFA — Recovery Codes
+
+Not in samples — use SDK examples.
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action | Notes |
+|--------|-----------------|-----------|--------|----------------|-------|
+| `mfa-recovery-code-enrollment` | ❌ | ✅ | ✅ | `continueMethod({ isCodeCopied })` | Screen-specific hook |
+| `mfa-recovery-code-challenge` | ❌ | ✅ | ✅ | `continueMethod()` | |
+| `mfa-recovery-code-challenge-new-code` | ❌ | ✅ | ✅ | `continueMethod()` | |
+
+---
+
+## Passkeys
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action | Notes |
+|--------|-----------------|-----------|--------|----------------|-------|
+| `passkey-enrollment` | ✅ | ✅ | ✅ | `submitPasskeyCredential()` | Native dialog |
+| `passkey-enrollment-local` | ✅ | ✅ | ✅ | `continueMethod()` | Local device |
+
+---
+
+## Identifier Challenges
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action |
+|--------|-----------------|-----------|--------|----------------|
+| `email-identifier-challenge` | ✅ | ✅ | ✅ | `continueMethod()` |
+| `phone-identifier-challenge` | ✅ | ✅ | ✅ | `continueMethod()` |
+| `phone-identifier-enrollment` | ✅ | ✅ | ✅ | `continueMethod()` |
+| `email-otp-challenge` | ❌ | ✅ | ✅ | `continueMethod()` |
+
+---
+
+## Device Authorization
+
+Not in samples — use SDK examples.
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action |
+|--------|-----------------|-----------|--------|----------------|
+| `device-code-activation` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `device-code-confirmation` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `device-code-activation-allowed` | ❌ | ✅ | ✅ | — |
+| `device-code-activation-denied` | ❌ | ✅ | ✅ | — |
+
+---
+
+## Organization Management
+
+Not in samples — use SDK examples.
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action |
+|--------|-----------------|-----------|--------|----------------|
+| `organization-picker` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `organization-selection` | ❌ | ✅ | ✅ | `continueMethod()` |
+
+---
+
+## Consent & Security
+
+Not in samples — use SDK examples.
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action |
+|--------|-----------------|-----------|--------|----------------|
+| `consent` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `customized-consent` | ❌ | ✅ | ✅ | `continueMethod()` |
+| `interstitial-captcha` | ❌ | ✅ | ✅ | `continueMethod()` |
+
+---
+
+## Session / Logout
+
+Not in samples — use SDK examples.
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action |
+|--------|-----------------|-----------|--------|----------------|
+| `logout` | ❌ | ✅ | ✅ | `logout()` |
+| `logout-aborted` | ❌ | ✅ | ✅ | — |
+| `logout-complete` | ❌ | ✅ | ✅ | — |
+
+---
+
+## Email Verification
+
+| Screen | Samples (React) | SDK React | SDK JS | Primary Action |
+|--------|-----------------|-----------|--------|----------------|
+| `email-verification-result` | ❌ | ✅ | ✅ | — |
+
+---
+
+## JS-Only Screens
+
+Only in `@auth0/auth0-acul-js`. No React SDK or samples equivalent. Use JS SDK examples.
+
+| Screen | Primary Action | Notes |
+|--------|----------------|-------|
+| `brute-force-protection-unblock` | `unblockAccount()` | Account unblock |
+| `brute-force-protection-unblock-success` | — | Success state |
+| `brute-force-protection-unblock-failure` | — | Failure state |
+| `get-current-screen-options` | — | Utility: read screen config |
+| `get-current-theme-options` | — | Utility: read theme config |
+
+JS SDK example URL:
+```
+https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-js/examples/<screen-name>.md
+```
+
+---
+
+# Social Login Provider Patterns
+
+Patterns for rendering social login buttons in ACUL screens. Social connections come from `alternateConnections` on the transaction object — never hardcode connection names.
+
+---
+
+## Data Shape
+
+```typescript
+// From useTransaction() (React) or manager.transaction (JS)
+alternateConnections: Array<{
+  name: string          // e.g., "google-oauth2", "github", "apple"
+  displayName: string   // e.g., "Google", "GitHub", "Apple"
+  iconUrl?: string      // provider icon URL if available
+  strategy: string      // e.g., "google-oauth2", "github", "apple"
+}>
+```
+
+---
+
+## React Pattern
+
+```tsx
+import { useTransaction, federatedLogin } from '@auth0/auth0-acul-react/login-id'
+
+const { alternateConnections } = useTransaction()
+
+// In JSX
+{alternateConnections?.length > 0 && (
+  <div className="social-section">
+    <div className="divider">
+      <span>Or continue with</span>
+    </div>
+    <div className="social-buttons">
+      {alternateConnections.map(conn => (
+        <SocialButton key={conn.name} connection={conn} />
+      ))}
+    </div>
+  </div>
+)}
+```
+
+```tsx
+const SocialButton: React.FC<{ connection: AlternateConnection }> = ({ connection }) => {
+  const [loading, setLoading] = useState(false)
+
+  const handleClick = async () => {
+    setLoading(true)
+    await federatedLogin({ connection: connection.name })
+    setLoading(false)
+  }
+
+  return (
+    <button
+      onClick={handleClick}
+      disabled={loading}
+      className="social-btn"
+      aria-label={`Continue with ${connection.displayName}`}
+    >
+      {connection.iconUrl && (
+        <img src={connection.iconUrl} alt="" width={20} height={20} />
+      )}
+      <span>Continue with {connection.displayName}</span>
+    </button>
+  )
+}
+```
+
+---
+
+## JS Pattern
+
+```javascript
+import LoginId from '@auth0/auth0-acul-js/login-id'
+const manager = new LoginId()
+
+function renderSocialButtons() {
+  const connections = manager.transaction.alternateConnections ?? []
+  if (!connections.length) return ''
+
+  return `
+    <div class="social-section">
+      <div class="divider"><span>Or continue with</span></div>
+      <div class="social-buttons">
+        ${connections.map(conn => `
+          <button
+            class="social-btn"
+            data-connection="${conn.name}"
+            aria-label="Continue with ${conn.displayName}"
+          >
+            ${conn.iconUrl ? `<img src="${conn.iconUrl}" alt="" width="20" height="20" />` : ''}
+            <span>Continue with ${conn.displayName}</span>
+          </button>
+        `).join('')}
+      </div>
+    </div>
+  `
+}
+
+// Attach handlers after render
+document.querySelectorAll('.social-btn').forEach(btn => {
+  btn.addEventListener('click', async () => {
+    await manager.federatedLogin({ connection: btn.dataset.connection })
+  })
+})
+```
+
+---
+
+## Provider-Specific Icon SVGs
+
+Use these inline SVGs when `iconUrl` is unavailable or for consistent brand rendering.
+
+### Google
+```html
+<svg width="20" height="20" viewBox="0 0 24 24" fill="none">
+  <path d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z" fill="#4285F4"/>
+  <path d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z" fill="#34A853"/>
+  <path d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l3.66-2.84z" fill="#FBBC05"/>
+  <path d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z" fill="#EA4335"/>
+</svg>
+```
+
+### GitHub
+```html
+<svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor">
+  <path d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z"/>
+</svg>
+```
+
+### Apple
+```html
+<svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor">
+  <path d="M18.71 19.5c-.83 1.24-1.71 2.45-3.05 2.47-1.34.03-1.77-.79-3.29-.79-1.53 0-2 .77-3.27.82-1.31.05-2.3-1.32-3.14-2.53C4.25 17 2.94 12.45 4.7 9.39c.87-1.52 2.43-2.48 4.12-2.51 1.28-.02 2.5.87 3.29.87.78 0 2.26-1.07 3.8-.91.65.03 2.47.26 3.64 1.98-.09.06-2.17 1.28-2.15 3.81.03 3.02 2.65 4.03 2.68 4.04-.03.07-.42 1.44-1.38 2.83M13 3.5c.73-.83 1.94-1.46 2.94-1.5.13 1.17-.34 2.35-1.04 3.19-.69.85-1.83 1.51-2.95 1.42-.15-1.15.41-2.35 1.05-3.11z"/>
+</svg>
+```
+
+### Microsoft
+```html
+<svg width="20" height="20" viewBox="0 0 24 24" fill="none">
+  <rect x="1" y="1" width="10" height="10" fill="#F25022"/>
+  <rect x="13" y="1" width="10" height="10" fill="#7FBA00"/>
+  <rect x="1" y="13" width="10" height="10" fill="#00A4EF"/>
+  <rect x="13" y="13" width="10" height="10" fill="#FFB900"/>
+</svg>
+```
+
+---
+
+## Styling the Divider
+
+```css
+.divider {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin: 16px 0;
+}
+.divider::before,
+.divider::after {
+  content: '';
+  flex: 1;
+  height: 1px;
+  background: var(--color-border);
+}
+.divider span {
+  color: var(--color-text-secondary);
+  font-size: 0.875rem;
+  white-space: nowrap;
+}
+```
+
+---
+
+# Theming Patterns for ACUL Screens
+
+---
+
+## Design Token Derivation
+
+When only brand colors are provided (no image), derive the full token set:
+
+```
+Input: primary color (e.g., #4F46E5)
+
+Derived tokens:
+  --color-primary          = input hex
+  --color-primary-hover    = primary darkened ~10%  (hsl lightness -10)
+  --color-primary-text     = white if primary is dark, else #111827
+
+  --color-background       = #FFFFFF (light) or #0F172A (dark, if brand is dark)
+  --color-surface          = #F9FAFB (light) or #1E293B (dark)
+  --color-surface-raised   = #FFFFFF (light) or #293548 (dark)
+
+  --color-text-primary     = #111827 (light) or #F1F5F9 (dark)
+  --color-text-secondary   = #6B7280 (light) or #94A3B8 (dark)
+  --color-text-placeholder = #9CA3AF
+
+  --color-border           = #E5E7EB (light) or #334155 (dark)
+  --color-border-focus     = primary color
+
+  --color-error            = #EF4444
+  --color-error-bg         = #FEF2F2
+  --color-success          = #22C55E
+  --color-success-bg       = #F0FDF4
+
+  --radius-sm              = 4px
+  --radius-md              = 8px
+  --radius-lg              = 12px
+  --radius-full            = 9999px
+
+  --shadow-card            = 0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06)
+  --shadow-input-focus     = 0 0 0 3px <primary at 20% opacity>
+```
+
+---
+
+## Image/Mockup Analysis
+
+When a screenshot or design mockup is provided, extract:
+
+1. **Colors** — sample from key areas:
+   - Page background color
+   - Card/panel background
+   - Primary button color
+   - Input border color
+   - Text colors (heading, body, placeholder)
+   - Error state color
+
+2. **Typography** — identify:
+   - Font family (match to Google Fonts or system font stack if custom)
+   - Heading size and weight
+   - Body text size
+   - Button text style
+
+3. **Spatial rhythm** — measure approximate:
+   - Card padding (compact ~16px / normal ~24px / spacious ~32px)
+   - Input height (small ~36px / medium ~40px / large ~48px)
+   - Button border radius (sharp 0px / slight 4px / rounded 8px / pill 9999px)
+
+4. **Layout type:**
+   - Centered card (card centered on solid background)
+   - Full-bleed (edge-to-edge, no visible card)
+   - Split panel (image/brand on left, form on right)
+   - Floating card (card with shadow on gradient/image background)
+
+---
+
+## Theme File Patterns by Styling Library
+
+### Tailwind CSS — `tailwind.config.ts`
+
+Use `assets/acul/theme-templates/tailwind.config.ts` as base.
+
+Key pattern:
+```typescript
+theme: {
+  extend: {
+    colors: {
+      brand: {
+        primary: tokens.primary,
+        'primary-hover': tokens.primaryHover,
+        surface: tokens.surface,
+        background: tokens.background,
+        error: tokens.error,
+      }
+    },
+    borderRadius: {
+      card: tokens.radiusLg,
+      input: tokens.radiusMd,
+      btn: tokens.radiusMd,
+    }
+  }
+}
+```
+
+Usage in components: `bg-brand-primary`, `hover:bg-brand-primary-hover`, `rounded-card`.
+
+### CSS Modules — `styles/tokens.css`
+
+Use `assets/acul/theme-templates/tokens.css` as base.
+
+Pattern: define all tokens as `:root` CSS custom properties.
+```css
+:root {
+  --color-primary: #4F46E5;
+  --color-primary-hover: #4338CA;
+  /* ... */
+}
+```
+
+Usage: `background: var(--color-primary)`.
+
+### styled-components — `theme/index.ts`
+
+Use `assets/acul/theme-templates/theme-provider.ts` as base.
+
+Pattern:
+```typescript
+export const theme = {
+  colors: { primary: '#4F46E5', ... },
+  radii: { card: '12px', ... }
+}
+
+// Wrap app
+<ThemeProvider theme={theme}><App /></ThemeProvider>
+```
+
+Usage in styled components: `background: ${({ theme }) => theme.colors.primary}`.
+
+### Plain CSS — `styles/globals.css`
+
+Use `assets/acul/theme-templates/globals.css` as base. Same as CSS Modules pattern but applied globally.
+
+---
+
+## Single Screen vs All Screens
+
+### Single screen (inline)
+Apply tokens directly in the component's style file. No shared theme file.
+```css
+/* LoginId.module.css */
+.card { background: #FFFFFF; border-radius: 12px; }
+.submitBtn { background: #4F46E5; }
+```
+
+### All screens (shared theme file)
+1. Generate the shared theme file first (`tailwind.config.ts` / `tokens.css` / etc.)
+2. All screen components import from that single source of truth
+3. Consistency is enforced — changing one variable updates all screens
+
+**File to generate per styling library:**
+
+| Library | File to create | Import in components |
+|---------|---------------|----------------------|
+| Tailwind | `tailwind.config.ts` | Classes only (no import needed) |
+| CSS Modules | `styles/tokens.css` | `@import '../styles/tokens.css'` |
+| styled-components | `theme/index.ts` | `import { theme } from '../theme'` |
+| Plain CSS | `styles/globals.css` | Import once in entry point |
diff --git a/main/.mintlify/skills/auth0/references/feature-audit-pricing/index.md b/main/.mintlify/skills/auth0/references/feature-audit-pricing/index.md
new file mode 100644
index 0000000000..547c9ffe3c
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/feature-audit-pricing/index.md
@@ -0,0 +1,371 @@
+# Auth0 Pricing
+
+`https://auth0.com/pricing.md` holds the up-to-date prices — retrieve it before quoting any
+figure. The feature→plan matrix below is local; read it from here.
+
+Auth0 offers flexible authentication and authorization plans for both B2C (consumer-facing) and B2B (business-facing) applications. The Free plan is identical regardless of use case. Paid plans are priced by Monthly Active Users (MAUs) and differ between B2C and B2B.
+
+---
+
+## How to Use This Document
+
+To quote pricing for a customer, follow these steps in order:
+
+1. **Fetch `https://auth0.com/pricing.md` first.** Do this before quoting any figure. It carries
+   the B2C and B2B base-price tables (monthly and yearly), every add-on table (Auth for AI
+   Agents, M2M tokens, Enterprise SSO connections, Enterprise MFA), and the current MAU tiers.
+   If it can't be fetched, give the plan name without a figure — never a price from memory.
+2. **Determine use case:** B2C (consumer-facing) or B2B (business-facing).
+3. **Identify their MAU tier:** Find the tier that meets or exceeds their expected monthly active users. If usage falls between tiers, use the next tier up.
+4. **Select the plan:** Match required features against the Feature Comparison tables below to determine the minimum plan (Free, Essentials, Professional, or Enterprise).
+5. **Look up the base price** in the fetched page, using the appropriate B2C or B2B table.
+6. **Add any add-ons:** Check whether the customer needs AI Agents, additional M2M tokens, Enterprise SSO connections, or Enterprise MFA, and take each add-on price from the fetched page.
+7. **Calculate total cost:** Total = Base Price + sum of all applicable add-on prices.
+8. **"Contact us" or "Not available" components:** If any component reads "Contact us", direct the customer to Auth0 sales for a custom quote. If it reads "Not available", that plan or add-on does not exist at their MAU tier — do not recommend it and do not total it; move up a plan or send them to sales.
+
+---
+
+## Key Definitions
+
+- **Monthly Active Users (MAUs):** Any non-internal (non-employee) user that authenticated during a given month for a given tenant.
+- **Organizations:** Represent their business customers and partners in Auth0 and manage their membership.
+- **Enterprise Connections:** Enterprise IdPs supporting protocols like AD, LDAP, or SAML to authenticate your users.
+
+---
+
+## Plans Overview
+
+Auth0 has four tiers: **Free**, **Essentials**, **Professional**, and **Enterprise**. Free is
+identical for B2C and B2B; the paid tiers are priced separately for each. Starting prices, the
+MAU tier they apply at, and how Enterprise is sold are in the fetched pricing page — read
+Enterprise off that page rather than assuming, and never quote or estimate an Enterprise price
+yourself.
+
+---
+
+## Free Plan
+
+**Free** (same for B2C and B2B)
+
+No credit card needed to sign up.
+
+- Up to 25,000 monthly active users
+- 1 Custom Domain*
+- Secure Agentic AI workflows
+- Passwordless Authentication
+- Unlimited Social Connections**
+- 5 Organizations
+- Brand Customization
+- Basic Attack Protection
+- Community Support
+- 1 Enterprise Connection (NEW)
+- Self-Service SSO (NEW)
+- SCIM (NEW)
+
+---
+
+## B2C Pricing
+
+### Plan Highlights
+
+**Essentials**
+- Everything in Free, plus:
+- Higher Auth, API limits, and feature limits
+- Pro Multi-Factor Authentication
+- Role-based Access Control Per Organization
+- 10 Organizations (How we model your customers)
+- Stream Auth0 Audit Logs to Datadog, Splunk, AWS, Azure, etc.
+- Separate Production & Development Environments
+- Standard Support
+- Add-ons: Enterprise MFA, Enterprise SSO Connections, M2M Tokens
+
+**Professional**
+- Everything in Essentials, plus:
+- Enhanced Attack Protection
+- Use your existing User Database for Logins
+- Enterprise Multi-Factor Authentication
+- Add-ons: M2M Tokens
+
+**Enterprise — Contact us**
+- Everything in Professional, plus:
+- Custom User & SSO Tiers
+- 99.99% SLA
+- Enterprise Rate Limits
+- Enterprise Administration & Support
+- Add-ons: Advanced Security Features, Private Deployment
+
+*Pricing is available only at the listed MAU tiers. If your usage falls between tiers, you are billed at the next tier up.*
+
+### B2C Prices
+
+Base prices (monthly and yearly) by MAU tier, and every B2C add-on — Auth0 for AI Agents
+(adds 50% to base, rounded up to the dollar; unlimited Token Vault, all forms of CIBA) and
+M2M tokens — are in the **B2C section of the fetched pricing page**. Read them there; which
+plans each add-on is available on is in the B2C Feature Comparison below.
+
+---
+
+## B2B Pricing
+
+### Plan Highlights
+
+**Essentials**
+- Everything in Free, plus:
+- Unlimited** Organizations
+- 3 SSO Enterprise Connections
+- Role-based Access Control
+- Higher Auth and API limits
+- Pro Multi-Factor Authentication
+- Stream Auth0 Audit Logs
+- Dev & Prod tenant configuration
+- Standard Support
+- Add-ons: Enterprise MFA, Enterprise SSO Connections, M2M Tokens
+
+**Professional**
+- Everything in Essentials, plus:
+- Enhanced Attack Protection
+- Use your existing User Database for Logins
+- Enterprise Multi-Factor Authentication
+- Custom Token Exchange
+- Security Center
+- Additional Enterprise Connections
+- Add-ons: Enterprise SSO Connections, M2M Tokens
+
+**Enterprise — Contact us**
+- Everything in Professional, plus:
+- Custom User & SSO Tiers
+- 99.99% SLA
+- Enterprise Rate Limits
+- Enterprise Administration & Support
+- Add-ons: Advanced Security Features, Private Deployment
+
+### B2B Prices
+
+Base prices (monthly and yearly) by MAU tier, and every B2B add-on — Auth0 for AI Agents,
+M2M tokens, additional Enterprise SSO connections, and Enterprise MFA — are in the **B2B
+section of the fetched pricing page**. Read them there; which plans each add-on is available
+on, and how many Enterprise Connections each plan includes, are in the B2B Feature Comparison
+below.
+
+---
+
+## Feature Comparison
+
+> ADD-ON = available as paid add-on
+> * credit card verification required for custom domains
+> ** subject to system limitations
+> The Free column is identical for B2C and B2B.
+
+### B2C Feature Comparison
+
+#### Authentication
+
+| Feature | Free | Essentials | Professional | Enterprise |
+|---|---|---|---|---|
+| External Active Users | Up to 25,000 | Custom Tiers | Custom Tiers | Custom Tiers |
+| Machine-to-Machine Authentication | 1,000 | 1,000 | 5,000 | 5,000 |
+| M2M Add-on | No | No | Yes | Yes |
+| Passwordless | Included | Included | Included | Included |
+| Social Connections | Unlimited** | Unlimited** | Unlimited** | Unlimited** |
+| Custom Social Connections | Included | Included | Included | Included |
+| Passkeys | Included | Included | Included | Included |
+| Auth0 Database Connection | Included | Included | Included | Included |
+| Custom Database Connections | Not available | Not available | Included | Included |
+| Cross APP SSO | Not available | Not available | Included | Included |
+| Enterprise Connections | 1 | Not available | Not available | Custom Tiers |
+| Inbound SCIM | Included | Included | Included | Included |
+| Okta Connections | Unlimited** | Unlimited** | Unlimited** | Unlimited** |
+| Express Configuration | Included | Included | Included | Included |
+| Organizations | 5 | 10 | 10 | Custom Tiers |
+| Self-Service SSO | Included | Not available | Not available | Select Enterprise Plans |
+| M2M Access for Organizations | Not available | Not available | Not available | Select Enterprise Plans |
+| Home Realm Discovery | Not available | Not available | Not available | Included |
+| Long Lived Sessions | Not available | Not available | Not available | Included |
+
+#### AI
+
+| Feature | Free | Essentials | Professional | Enterprise |
+|---|---|---|---|---|
+| CIBA | Not available | ADD-ON | ADD-ON | Included + ADD-ON |
+| Token Vault | 2 | 3 + ADD-ON | 3 + ADD-ON | 4 + ADD-ON |
+
+#### Branding
+
+| Feature | Free | Essentials | Professional | Enterprise |
+|---|---|---|---|---|
+| Configurable Login Experience | Included | Included | Included | Included |
+| Accessibility | Included | Included | Included | Included |
+| Custom Domains* | 1 | Included | Included | Included |
+| Email Workflow | Not available | Included | Included | Included |
+| Customize Signup & Login | Not available | Included | Included | Included |
+
+#### Extensibility
+
+| Feature | Free | Essentials | Professional | Enterprise |
+|---|---|---|---|---|
+| Actions + Forms | 5 | 10 | 15 | 30 + ADD-ON |
+| The Actions Library | Included | Included | Included | Included |
+| Marketplace | Included | Included | Included | Included |
+| Pro Forms | Not available | Not available | Included | Included |
+
+#### Security & Compliance
+
+| Feature | Free | Essentials | Professional | Enterprise |
+|---|---|---|---|---|
+| Brute Force Protection | Included | Included | Included | Included |
+| Suspicious IP Throttling | Included | Included | Included | Included |
+| Enhanced Password Protection | Not available | Not available | Included | Included |
+| Basic Breached Password Detection | Not available | Not available | Included | Included |
+| Credential Guard | Not available | Not available | Not available | ADD-ON |
+| Bot Detection | Not available | Not available | Not available | ADD-ON |
+| Tenant Access Control List (ACL) | Not available | Not available | Not available | 1 + ADD-ON |
+| Integration with Okta Universal Logout | Included | Included | Included | Included |
+| Pro MFA Factors | Not available | Included | Included | Included |
+| Enterprise MFA Factors | Not available | Included | Included | Included |
+| Adaptive MFA | Not available | Not available | Not available | ADD-ON |
+| Security Center | Not available | Not available | Included | Included |
+| Continuous Session Protection | Not available | Not available | Not available | Included |
+| FAPI certified Security Profile | Not available | Not available | Not available | ADD-ON |
+| Compliance Certifications | Included | Included | Included | Included |
+| HIPAA/BAA | Not available | Not available | Not available | ADD-ON |
+| Prioritized Security Log Streams | Not available | Not available | Not available | Included |
+| Private Key JWT | Not available | Not available | Not available | Included |
+| OIDC Back-Channel Logout | Not available | Not available | Not available | Included |
+
+#### User Management
+
+| Feature | Free | Essentials | Professional | Enterprise |
+|---|---|---|---|---|
+| User Import | Included | Included | Included | Included |
+| Custom Attributes | Included | Included | Included | Included |
+| Role Management | Not available | Included | Included | Included |
+| Account Linking | Not available | Included | Included | Included |
+
+#### Platform
+
+| Feature | Free | Essentials | Professional | Enterprise |
+|---|---|---|---|---|
+| Number of Tenants Included | 1 | 3 | 12 | Unlimited** |
+| Number of Admin/Contributors | 3 | Unlimited** | Unlimited** | Unlimited** |
+| Admin Access Controls | Admin | Admin and Viewer | Admin, Viewer and Editor | Admin, Viewer and Editor |
+| Auth0 Dashboard SSO | Not available | Not available | Not available | Included |
+| Log Retention | 1 Day | 5 Days | 10 Days | 30 Days |
+| Log Streaming | Not available | 1 Log Stream | 2 Log Streams | 2 Log Streams |
+| Private Deployment | Not available | Not available | Not available | ADD-ON |
+| SLA | Not available | Not available | Not available | 99.99% |
+| Community Support | Included | Included | Included | Included |
+| Standard Support | Not available | Included | Included | Included |
+| Premier Support | Not available | Not available | Not available | Premier Success Options |
+
+---
+
+### B2B Feature Comparison
+
+#### Authentication
+
+| Feature | Free | Essentials | Professional | Enterprise |
+|---|---|---|---|---|
+| External Active Users | Up to 25,000 | Custom Tiers | Custom Tiers | Custom Tiers |
+| Machine-to-Machine Authentication | 1,000 | 1,000 | 5,000 | 5,000 |
+| M2M Add-on | No | No | Yes | Yes |
+| Passwordless | Included | Included | Included | Included |
+| Social Connections | Unlimited** | Unlimited** | Unlimited** | Unlimited** |
+| Custom Social Connections | Included | Included | Included | Included |
+| Passkeys | Included | Included | Included | Included |
+| Auth0 Database Connection | Included | Included | Included | Included |
+| Custom Database Connections | Not available | Not available | Included | Included |
+| Cross APP SSO | Not available | Not available | Included | Included |
+| Enterprise Connections | 1 | 3 + ADD-ON | 5 + ADD-ON | Custom Tiers |
+| Inbound SCIM | Included | Included | Included | Included |
+| Okta Connections | Unlimited** | Unlimited** | Unlimited** | Unlimited** |
+| Express Configuration | Included | Included | Included | Included |
+| Organizations | 5 | Unlimited** | Unlimited** | Custom Tiers |
+| Self-Service SSO | Included | Included | Included | Select Enterprise Plans |
+| M2M Access for Organizations | Not available | Not available | Included | Select Enterprise Plans |
+| Home Realm Discovery | Not available | Included | Included | Included |
+| Long Lived Sessions | Not available | Not available | Not available | Included |
+
+#### AI
+
+| Feature | Free | Essentials | Professional | Enterprise |
+|---|---|---|---|---|
+| CIBA | Not available | ADD-ON | ADD-ON | Included + ADD-ON |
+| Token Vault | 2 | 3 + ADD-ON | 3 + ADD-ON | 4 + ADD-ON |
+
+#### Branding
+
+| Feature | Free | Essentials | Professional | Enterprise |
+|---|---|---|---|---|
+| Configurable Login Experience | Included | Included | Included | Included |
+| Accessibility | Included | Included | Included | Included |
+| Custom Domains* | 1 | Included | Included | Included |
+| Email Workflow | Not available | Included | Included | Included |
+| Customize Signup & Login | Not available | Included | Included | Included |
+
+#### Extensibility
+
+| Feature | Free | Essentials | Professional | Enterprise |
+|---|---|---|---|---|
+| Actions + Forms | 5 | 10 | 15 | 30 + ADD-ON |
+| The Actions Library | Included | Included | Included | Included |
+| Marketplace | Included | Included | Included | Included |
+| Pro Forms | Not available | Not available | Included | Included |
+
+#### Security & Compliance
+
+| Feature | Free | Essentials | Professional | Enterprise |
+|---|---|---|---|---|
+| Brute Force Protection | Included | Included | Included | Included |
+| Suspicious IP Throttling | Included | Included | Included | Included |
+| Enhanced Password Protection | Not available | Not available | Included | Included |
+| Basic Breached Password Detection | Not available | Not available | Included | Included |
+| Credential Guard | Not available | Not available | Not available | ADD-ON |
+| Bot Detection | Not available | Not available | Not available | ADD-ON |
+| Tenant Access Control List (ACL) | Not available | Not available | Not available | 1 + ADD-ON |
+| Integration with Okta Universal Logout | Included | Included | Included | Included |
+| Pro MFA Factors | Not available | Included | Included | Included |
+| Enterprise MFA Factors | Not available | ADD-ON | Included | Included |
+| Adaptive MFA | Not available | Not available | Not available | ADD-ON |
+| Security Center | Not available | Not available | Not available | Included |
+| Continuous Session Protection | Not available | Not available | Not available | Included |
+| FAPI certified Security Profile | Not available | Not available | Not available | ADD-ON |
+| Compliance Certifications | Included | Included | Included | Included |
+| HIPAA/BAA | Not available | Not available | Not available | ADD-ON |
+| Prioritized Security Log Streams | Not available | Not available | Not available | Included |
+| Private Key JWT | Not available | Not available | Not available | Included |
+| OIDC Back-Channel Logout | Not available | Not available | Not available | Included |
+
+#### User Management
+
+| Feature | Free | Essentials | Professional | Enterprise |
+|---|---|---|---|---|
+| User Import | Included | Included | Included | Included |
+| Custom Attributes | Included | Included | Included | Included |
+| Role Management | Not available | Included | Included | Included |
+| Account Linking | Not available | Included | Included | Included |
+
+#### Platform
+
+| Feature | Free | Essentials | Professional | Enterprise |
+|---|---|---|---|---|
+| Number of Tenants Included | 1 | 3 | 12 | Unlimited** |
+| Number of Admin/Contributors | 3 | Unlimited** | Unlimited** | Unlimited** |
+| Admin Access Controls | Admin | Admin and Viewer | Admin, Viewer and Editor | Admin, Viewer and Editor |
+| Auth0 Dashboard SSO | Not available | Not available | Not available | Included |
+| Log Retention | 1 Day | 5 Days | 10 Days | 30 Days |
+| Log Streaming | Not available | 1 Log Stream | 2 Log Streams | 2 Log Streams |
+| Private Deployment | Not available | Not available | Not available | ADD-ON |
+| SLA | Not available | Not available | Not available | 99.99% |
+| Community Support | Included | Included | Included | Included |
+| Standard Support | Not available | Included | Included | Included |
+| Premier Support | Not available | Not available | Not available | Premier Success Options |
+
+---
+
+## Notes
+
+- Yearly billing = 11× the monthly price (equivalent to 1 month free)
+- * Custom domains require credit card verification
+- ** Subject to system limitations
+- Enterprise plan pricing is custom; contact Auth0 sales
+- The Free plan is identical for B2C and B2B: up to 25,000 MAUs, no credit card required
diff --git a/main/.mintlify/skills/auth0/references/feature-audit-remediation/index.md b/main/.mintlify/skills/auth0/references/feature-audit-remediation/index.md
new file mode 100644
index 0000000000..308e122dab
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/feature-audit-remediation/index.md
@@ -0,0 +1,98 @@
+# Auth0 tenant audit — remediation reference
+
+This reference covers how to apply approved fixes from an Auth0 tenant configuration audit: the command-shape mapping, the per-item guided flow, the express-mode batch flow, and the commands that are never run without explicit user confirmation. It assumes an audit report already exists (with "Immediate Actions" and "After Upgrading" lists) and the user has chosen a remediation mode — Express or Guided — for applying fixes via the Auth0 CLI.
+
+Fixes are applied as two ordered loops: **Loop A — Immediate Actions** (fixes available on the tenant's current plan) and **Loop B — After Upgrading** (fixes gated behind a plan upgrade). Loop A runs first; after it completes, ask whether the customer has upgraded before starting Loop B.
+
+## Command-shape mapping
+
+For each item, build the command. **Use a first-class subcommand when one exists; fall back to `auth0 api <method>` with an explicit JSON payload when there isn't.** Run `auth0 <cmd> --help` first if uncertain about flag names.
+
+| Category | First-class command (if available) | Fallback `auth0 api` path |
+|---|---|---|
+| Tenant settings | `auth0 tenants settings update` | `PATCH /api/v2/tenants/settings` |
+| Brute-force protection | `auth0 protection brute-force-protection update` | `PATCH /api/v2/attack-protection/brute-force-protection` |
+| Breached password detection | `auth0 protection breached-password-detection update` | `PATCH /api/v2/attack-protection/breached-password-detection` |
+| Suspicious IP throttling | `auth0 protection suspicious-ip-throttling update` | `PATCH /api/v2/attack-protection/suspicious-ip-throttling` |
+| Branding (universal login, colors, logo) | `auth0 branding update` / `auth0 universal-login update` | `PATCH /api/v2/branding` |
+| Custom domains | `auth0 domains create` / `update` | `POST/PATCH /api/v2/custom-domains` |
+| Connections (DB, social, enterprise) | `auth0 connections update <id>` | `PATCH /api/v2/connections/{id}` (full options blob) |
+| APIs / resource servers | `auth0 apis update` | `PATCH /api/v2/resource-servers/{id}` |
+| Apps / clients (callbacks, origins, grant types, refresh tokens) | `auth0 apps update` | `PATCH /api/v2/clients/{id}` |
+| Roles | `auth0 roles update` | `PATCH /api/v2/roles/{id}` |
+| Actions | `auth0 actions create/update/deploy` | `POST/PATCH /api/v2/actions/actions` |
+| Log streams | `auth0 logs streams create/update` | `POST/PATCH /api/v2/log-streams` |
+| Email provider/templates | `auth0 email provider update` / `auth0 email templates update` | `PATCH /api/v2/emails/provider` / `/api/v2/email-templates/{name}` |
+| MFA factor toggles | (none) | `PUT /api/v2/guardian/factors/{factor}` |
+| MFA policies | (none) | `PUT /api/v2/mfa/policies` |
+| Prompts customization | (none) | `PUT /api/v2/prompts/{prompt}/custom-text/{lang}` |
+| Network ACLs | (none) | `POST/PATCH /api/v2/network-acls` |
+| Auth0 Organizations | `auth0 orgs create/update` | `POST/PATCH /api/v2/organizations` |
+
+The fallback is `auth0 api <method> <path> --data '<json>'` — pick the method from the
+table's path column: `patch` for most resources, `put` for MFA factor toggles, MFA
+policies, and Prompts customization, and `post` when creating a resource. `patch` is not
+universal. Note that `auth0 api` defaults to `GET` without `--data` and `POST` with
+`--data`, so always state the method explicitly.
+
+## Per-item flow (Guided mode)
+
+For each item, when in **Guided** mode:
+1. **Build the CLI command(s).** Multiple commands are fine — e.g. updating callbacks + origins + grant types on an app may need 1-3 calls.
+2. **Show the diff.** Print the current value (fetch with `auth0 api get ...`) and the proposed change side-by-side. Never show only the proposed payload.
+3. **Print the exact command(s)** about to run, including JSON payloads.
+4. **Ask via `AskUserQuestion`**: Implement now / Queue / Skip. Only proceed on Implement now.
+5. **Execute via Bash**, capture stdout/stderr.
+6. **Verify** by re-fetching the same resource and confirming the field changed. Never claim success on exit code alone.
+7. If a command fails, **don't retry destructively** — surface the error and ask the user how to proceed.
+
+## Batch flow (Express mode, Immediate Actions only)
+
+For Loop A in **Express** mode:
+1. **Build all CLI commands up front** for every Immediate Action.
+2. **Render one consolidated preview** to chat — a numbered list, each entry showing: action title · target app/resource · the exact command(s) it'll run. Mark anything mutating connections, deleting data, or rotating secrets as `[risky]` and exclude from the batch (handle individually after).
+3. **Ask via `AskUserQuestion`** with three options:
+   - **Apply all** — execute every non-risky item in order, one progress line per item (`✓ #1 callbacks updated`, `⚠ #3 failed: ...`).
+   - **Select a subset** — fall back to the per-item Guided flow above for the user to pick.
+   - **Skip remediation** — write all items to `state/queue.json` with `status: "skipped"`, exit remediation.
+4. After Apply all, re-fetch each touched resource to verify (same as the Guided flow's verify step). Surface failures inline; don't abort the batch on a single error.
+5. Any `[risky]` items pulled out of the batch get the Guided per-item flow afterwards.
+
+For Loop B (After Upgrading) in **Express** mode: still use the Guided per-item flow. Plan-gated changes are higher-stakes and individually consequential — never batch.
+
+### Loop A — Immediate Actions
+
+Iterate the "Immediate Actions — Available Today (Free)" items from the audit report.
+
+- **Express** → use the batch flow above.
+- **Guided** → use the per-item flow above.
+
+### Plan upgrade gate
+
+After Loop A, ask via `AskUserQuestion`:
+> "Has `<Customer>` upgraded to `<recommended_plan>`?"
+
+Options:
+- **Yes — proceed** → Loop B
+- **Not yet — queue for after upgrade** → write all After Upgrading items to `state/queue.json` with `status: "pending_upgrade"`, print the upgrade link `https://manage.auth0.com/dashboard/<region>/<tenant>/billing`, end
+- **Skip remaining** → write items with `status: "skipped"` (with optional rationale), end
+
+### Loop B — After Upgrading
+
+Always uses the Guided per-item flow regardless of mode (plan-gated changes are too consequential to batch). If any command fails with a plan-feature error, surface it and ask whether to queue.
+
+## Never-without-confirmation list (applies to all modes)
+
+Even in Express mode, these commands are blocked unless the user explicitly types the action verbatim:
+- `auth0 logout`
+- `auth0 tenants delete`
+- `auth0 apps delete` (any app, especially the CheckMate app)
+- `auth0 connections delete`
+- `auth0 api delete <anything>`
+
+## Closing the run
+
+After Loop B (or gate exit) completes:
+- Update state: `last_run_at`, append applied + queued + skipped findings to `state/history.jsonl`
+- Print: tenant, report path, applied count, queued count, skipped count
+- If anything was applied, suggest re-running the audit to confirm the fixes show clean
diff --git a/main/.mintlify/skills/auth0/references/feature-audit/index.md b/main/.mintlify/skills/auth0/references/feature-audit/index.md
new file mode 100644
index 0000000000..eb769e7124
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/feature-audit/index.md
@@ -0,0 +1,486 @@
+# Auth0 tenant audit (CheckMate) — full workflow
+
+Use this reference when the user wants to run an Auth0 tenant configuration / security audit and produce a tenant configuration report (Auth0 Platform Development Review format — markdown + styled PDF) tailored to their product context, or wants to apply the audit's recommendations. It bootstraps the Auth0 CLI and a dedicated audit M2M application if needed, gathers lightweight public company context so findings read in the customer's own terms, and implements approved fixes via the Auth0 CLI with per-command confirmation.
+
+You produce a personalized tenant audit as a **markdown brief plus styled PDF**, walk the user through the recommendations as two ordered loops (free-now vs after-upgrading), and apply approved fixes via the Auth0 CLI with per-command confirmation.
+
+The audit is run with CheckMate (`@auth0/auth0-checkmate`), a Node CLI that calls the Auth0 Management API and emits a JSON (and optionally PDF) report. The Auth0 CLI (`auth0`) is what you use both to bootstrap CheckMate's M2M app and to apply the recommendations.
+
+For the feature→plan matrix (Free/Essentials/Professional/Enterprise, B2C + B2B) that is the source of truth for triaging findings into Immediate vs After-Upgrading, use the co-loaded pricing reference. For the step-by-step remediation flows (command-shape mapping, guided/batch flows, the never-without-confirmation list), use the co-loaded remediation reference — it is what the two apply loops (Phase 6) hand off to. The markdown report skeleton this audit's brief MUST follow lives at `assets/audit/report-template.md`; the matching HTML skeleton (CSS-styled, used to render the PDF) lives at `assets/audit/report-template.html`. The PDF is rendered from the HTML by the script at the skill's `scripts/render_pdf.sh` (invoke it as `${CLAUDE_SKILL_DIR}/scripts/render_pdf.sh`). Company context is gathered inline in Phase 3 — no external skill required. Tenant-configuration CLI usage beyond what's inlined below (full command reference, flags, output formatting) is covered by the tooling reference loaded alongside this one.
+
+## Chat output rules (terse mode)
+
+This workflow runs many phases. Keep chat tight to make the run feel fast:
+- **One status line per phase max** — e.g. `Phase 1 ✓ CLI ready · tenant: acme.us.auth0.com`. No paragraph narration of what you're about to do.
+- Use `✓` for success, `⚠` for warnings (will fix automatically), `✗` for errors that need user input.
+- Show full detail only when (a) something fails, (b) the user must answer a question, or (c) Phase 5 chat summary at end.
+- Don't restate what's in the report files — point to the file path and stop.
+- Final-run summary may be 3-5 lines (top findings, applied count, queued count, file paths).
+
+## Tool-aware execution (agent portability)
+
+This workflow targets Claude Code first but works on any agent that can run shell commands and read files. It references several tools by their Claude Code names; map each to your agent's equivalent:
+
+| Reference in this workflow | Claude Code | Other agents (Codex, Cursor, Aider, Continue, Cline, etc.) |
+|---|---|---|
+| `AskUserQuestion` (mode selector, per-finding triage, confirmations) | Native multi-choice button UI | Ask the user as plain text with explicit options — e.g. "Reply: `express` / `guided` / `audit`" or "Apply this fix? `y`es / `q`ueue / `s`kip". Same content, plain prompt. |
+| `TodoWrite` (progress tracking) | Native todo list tool | Use your agent's progress mechanism, or skip — progress tracking is optional. |
+| `${CLAUDE_SKILL_DIR}` env var (path to skill folder) | Auto-set by Claude Code | Substitute the absolute path to wherever the customer extracted the skill. |
+
+State files for this workflow live at `~/.auth0-checkmate/state/` regardless of agent (vendor-neutral).
+
+## Phase 0 — Pre-flight + mode
+
+State cache lives at `~/.auth0-checkmate/state/setup.json` (create dir on first write):
+```json
+{
+  "schema_version": 1,
+  "tenant_domain": "tenant.region.auth0.com",
+  "checkmate_client_id": "...",
+  "company_domain": "example.com",
+  "mode": "guided",
+  "last_run_at": "2026-06-01T12:34:56Z"
+}
+```
+`mode` is `"express"`, `"guided"`, or `"audit"` (set in Phase 0.3, gates Phases 6-7).
+**Treat the state file as a cache, not source of truth.** Re-validate each field (Phase 1.1, Phase 2.1) before trusting it. Secrets (the M2M client_secret) live in `~/.auth0-checkmate.env` (mode 600) — never write secrets to the state file.
+
+### 0.1 Pre-flight diagnostic (silent → one-line status table)
+
+Run all checks **without prompting**, then render a single compact status block. Keep it under 8 lines.
+
+Checks to run in parallel (no chat output during checks):
+| Check | Command | Result |
+|---|---|---|
+| CLI installed | `auth0 --version` | version or missing |
+| Tenant session | `auth0 tenants list --json` | first tenant or none |
+| CheckMate app | `auth0 apps list --json \| jq '.[]\|select(.name\|test("CheckMate";"i"))'` | client_id or none |
+| M2M scopes | `auth0 api get client-grants?client_id=<id>` | scope count or none |
+| CheckMate npm | `command -v a0checkmate` | path or missing |
+| Node version | `node -v` | version or missing |
+| Reviewer | read `state/operator.json` | name or missing |
+| Company domain | read `state/setup.json.company_domain` | domain or missing |
+| Enrichment cache | newest `state/enrichment_*.json` | age or missing |
+
+Render to chat:
+```
+auth0-checkmate pre-flight:
+  ✓ Auth0 CLI v1.8.2
+  ✓ Logged in to acme.us.auth0.com
+  ✓ CheckMate M2M app present (cm_xxxxxx · 26/26 scopes)
+  ⚠ a0checkmate npm package not installed (will install)
+  ⚠ Company domain not cached (will ask)
+  → Estimated setup: ~30s
+```
+
+Use `✓` (ready), `⚠` (will fix automatically), `✗` (blocking — needs user input). If any `✗`, surface the action needed and pause for input.
+
+### 0.2 Capture missing inputs
+
+If reviewer or company domain is missing, ask in **one** combined `AskUserQuestion` (don't split into separate prompts). Save reviewer to `state/operator.json` (`reviewer_name`, optional `reviewer_org` for the report subtitle), company domain to `state/setup.json.company_domain`.
+
+Skip this step entirely when both are cached.
+
+### 0.3 Mode selector
+
+Single `AskUserQuestion`:
+
+> **How do you want to handle the recommendations?**
+> - **Express** — produce the report, then apply Immediate Actions in one batch confirmation; per-command confirm only for After-Upgrading items. Fastest.
+> - **Guided** — produce the report, then walk through each recommendation with per-command confirmation. Safest. (default)
+> - **Audit only** — produce the report and stop. No fixes applied.
+
+Save the chosen mode to `state/setup.json.mode`. The choice gates Phases 6 + 7 below.
+
+## Phase 1 — Auth0 CLI bootstrap
+
+### 1.1 Verify
+```bash
+auth0 --version              # CLI installed?
+auth0 tenants list --json    # session active? returns tenants array
+```
+
+If `--version` fails, install per platform:
+- macOS — `brew tap auth0/auth0-cli && brew install auth0`
+- Linux / macOS (curl) — download the binary with `curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b .` (it lands in `./auth0`; move it onto `$PATH` with `sudo mv ./auth0 /usr/local/bin` if you want to run it from any directory)
+- Windows — `scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git && scoop install auth0`, or via PowerShell: fetch the latest release tag from the GitHub releases API, download `auth0-cli_<version>_Windows_x86_64.zip`, expand it, and add it to `$PATH`
+- Any platform with Go ≥ 1.21 — `go install github.com/auth0/auth0-cli/cmd/auth0@latest` (ensure `$GOPATH/bin` is on `$PATH`)
+- Manual — download the release archive for your OS/architecture from the auth0-cli GitHub releases page and extract it; make sure `PATH` and `HOME` include the extraction folder
+
+Autocompletion instructions for supported shells are available by running `auth0 completion -h`.
+
+If `tenants list` returns empty / 401, authenticate. There are two ways:
+- **As a user** (recommended for personal/interactive machines) — device authorization flow, run `auth0 login`. **Cannot** be used for private cloud tenants.
+- **As a machine** (recommended for servers, CI, or private cloud tenants) — client credentials flow:
+  ```bash
+  auth0 login --domain <domain> --client-id <client-id> --client-secret <client-secret>
+  # or, with a private key instead of a secret:
+  auth0 login --domain <domain> --client-id <client-id> --client-assertion-private-key <path-to-private-key> --client-assertion-signing-alg <signing-algorithm>
+  ```
+
+**Critical:** the session must carry `create:client_grants` and `read:client_grants` so Phase 2's grant call doesn't 403:
+
+```bash
+auth0 login --scopes "create:client_grants,read:client_grants"
+```
+
+For non-interactive shells (CI, agent without TTY), or private cloud tenants, use the client-credentials login above. Detect TTY before invoking the device flow:
+```bash
+[ -t 0 ] && auth0 login --scopes "create:client_grants,read:client_grants" || echo "Non-interactive: use client-credentials login"
+```
+
+When an access token expires, the CLI prompts to confirm the default tenant (`Continue login with default tenant 'your-tenant.auth0.com'? [y/N]`) or lets you pick a different one — select `y` to proceed with the default, `N` to choose another. Note that CLI usage consumes Management API rate limits according to the subscription plan.
+
+### 1.2 Pin tenant
+Save the tenant domain returned by `auth0 tenants list --json` (`.[0].domain` if only one, otherwise ask the user to pick) into `state/setup.json.tenant_domain`. **Don't parse region from the domain suffix** — use the value the CLI returns. Custom domains (private cloud) are valid here.
+
+**This pinned `tenant_domain` is the canonical Auth0-hosted URL.** Every report reference to the tenant URL — header right rail, "authentication is served from `<tenant_domain>`" narrative, CLI commands — reads from `state/setup.json.tenant_domain`. Never derive it from the company context, never parse it from the company domain. The company context provides company-level fields (name, products, business model, integrations) — never the tenant URL.
+
+## Phase 2 — Dedicated CheckMate M2M app
+
+### 2.1 Detect existing
+```bash
+auth0 apps list --json | jq -r '.[] | select(.name|test("CheckMate";"i")) | {client_id, name}'
+```
+
+If a match exists, fetch its current client grant for the Management API audience and **diff scopes** against the required list (Phase 2.3). Missing scopes → `PATCH` the existing grant; **never delete + recreate** (rotates secret silently).
+
+### 2.2 Create if missing
+```bash
+auth0 apps create --name "Auth0 CheckMate" --type m2m \
+  --description "CheckMate tenant audit (managed by this workflow)" \
+  --json
+```
+
+The JSON response carries `client_id` and `client_secret`. **Never echo the secret outside the user's chat or write it to disk** other than `~/.auth0-checkmate.env` (Phase 2.4).
+
+> Free-plan tenants are limited to 1 free M2M app for the Management API. If create fails with a quota error, list existing M2M apps with Management API grants and ask the user which to reuse.
+
+### 2.3 Authorize Management API scopes (26 read scopes)
+
+```
+read:tenant_settings read:custom_domains read:prompts read:clients
+read:connections read:connections_options read:resource_servers
+read:client_grants read:roles read:branding read:email_provider
+read:email_templates read:phone_providers read:phone_templates
+read:shields read:attack_protection read:self_service_profiles
+read:guardian_factors read:mfa_policies read:actions read:log_streams
+read:logs read:network_acls read:event_streams read:hooks read:rules
+```
+
+Grant via the Management API (the CLI `auth0 api` is a raw wrapper):
+```bash
+auth0 api post "client-grants" --data '{
+  "client_id":"<id>",
+  "audience":"https://<tenant_domain>/api/v2/",
+  "scope":["read:tenant_settings","read:custom_domains","read:prompts","read:clients","read:connections","read:connections_options","read:resource_servers","read:client_grants","read:roles","read:branding","read:email_provider","read:email_templates","read:phone_providers","read:phone_templates","read:shields","read:attack_protection","read:self_service_profiles","read:guardian_factors","read:mfa_policies","read:actions","read:log_streams","read:logs","read:network_acls","read:event_streams","read:hooks","read:rules"]
+}'
+```
+
+Some tenants reject `read:hooks` / `read:rules` (deprecated). On 400, retry without those two and proceed.
+
+If the grant call returns 403, the login session is missing `create:client_grants` — go back to Phase 1.1 and re-login with that scope.
+
+### 2.4 Persist creds to a portable env file
+
+Write a dedicated env file at `~/.auth0-checkmate.env` and lock its permissions. This works the same way on macOS, Linux, WSL, and Git Bash — no shell-rc surgery required. Fish users: see the Portability section below.
+
+```bash
+ENV_FILE="$HOME/.auth0-checkmate.env"
+cat > "$ENV_FILE" <<'EOF'
+# Auth0 CheckMate credentials — managed by this workflow.
+# Treat as secret. Restrict permissions and exclude from dotfile repos / backups.
+export AUTH0CHECKMATE_DOMAIN="<tenant_domain>"
+export AUTH0CHECKMATE_CLIENT_ID="<client_id>"
+export AUTH0CHECKMATE_CLIENT_SECRET="<client_secret>"
+EOF
+chmod 600 "$ENV_FILE"
+```
+
+**Replace `<tenant_domain>`, `<client_id>`, and `<client_secret>` with the values from Phase 2 before writing this file.** The heredoc is single-quoted to prevent shell expansion — substitute inline, e.g. `sed -i "s/<tenant_domain>/$DOMAIN/" ~/.auth0-checkmate.env`, or open the file in an editor. The workflow reloads this file in Phase 4 via `source`. The user does NOT need to add anything to their shell rc — but they can, for convenience: `echo 'source ~/.auth0-checkmate.env' >> ~/.zshrc` (or `~/.bashrc`).
+
+Save `client_id` (NOT the secret) to the state file.
+
+### About the CheckMate CLI itself
+
+CheckMate for Auth0 (`@auth0/auth0-checkmate`) is a command-line utility that performs configuration checks on your Auth0 tenant, validating key settings and generating a detailed audit report. It requires Node.js v20.18.3 or higher and a valid Auth0 tenant.
+
+It makes use of the Auth0 Management API, which consumes the tenant's rate limits — use it thoughtfully to avoid throttling. Its usage is visible in the tenant's log events in several ways: the `User-Agent` HTTP header (`${packageName}/${packageVersion}`, e.g. `@auth0/auth0-checkmate/1.4.0`, unless the client modifies it), the `client_name` and `scopes` assigned when configuring initial access, and `seccft` events (successful exchange of an access token for a client-credentials grant) in Auth0 logs.
+
+Install it globally with `npm install -g @auth0/auth0-checkmate`, then run it with `a0checkmate` and follow the interactive prompts. Update with `npm update -g @auth0/auth0-checkmate`. Alternatively, run from source: clone `auth0/auth0-checkmate`, `cd` into it, `npm install`, then `npm start`.
+
+The dedicated M2M application this phase creates authorizes calls to the Management API and needs exactly the 26 read scopes listed in 2.3 — no more. CheckMate also accepts these environment variables for a CI-friendly, non-interactive configuration (used directly in Phase 4.2):
+```text
+AUTH0CHECKMATE_DISABLE_PDF_REPORTING=true|false
+AUTH0CHECKMATE_DOMAIN=your_domain
+AUTH0CHECKMATE_CLIENT_ID=your_client_id
+AUTH0CHECKMATE_CLIENT_SECRET=your_client_secret
+AUTH0CHECKMATE_FILE_PATH="./reports"
+AUTH0CHECKMATE_SHOW_VALIDATORS=false
+```
+
+## Phase 3 — Company context (lightweight, parallel)
+
+Kick this off **before** running CheckMate — it's network-bound and independent. The goal is narrow: make the audit *relevant to the customer's product* — what they build, who logs in, and what they integrate with — so each finding reads in their own terms. This is **not** a sales-qualification step: do **not** produce fit scores, a "plan fit" verdict, or firmographics (funding, valuation, investors, headcount). The plan suggestion in Phase 5 is derived from the customer's use case + this tenant's actual findings + the pricing reference — never from a company fit score.
+
+Given the company domain, gather public context with whatever web fetch / search tools the agent has. Treat live data as the primary source of truth; use training knowledge only to supplement.
+
+**Pages to read (best-effort, cap ~3000 chars each):** `/` (value prop, products, target market), `/about` (what they do), `/login` `/signin` (auth surfaces + current-provider signals), `/pricing` (B2B vs B2C, tiers), `/security` `/trust` (posture, compliance), `/docs` `/developers` (auth standards, API patterns), `/integrations` `/partners` (third-party APIs — relevant to Token Vault / A4AA), `/careers` (auth tech named in job posts).
+
+**Current auth-provider detection (optional, best-effort):** scan the homepage + login-page HTML and job posts. A login redirect to a provider domain is the strongest signal. Patterns: Auth0 (`.auth0.com`, `auth0-spa-js`), Clerk (`clerk.com`, `@clerk/`, `pk_live_`), WorkOS (`workos.com`, `authkit`), AWS Cognito (`cognito-idp`, `amazoncognito.com`), Firebase Auth (`firebaseapp.com`, `identitytoolkit.googleapis.com`), Okta / Keycloak / FusionAuth / Frontegg / Supabase (provider domain or SDK name). Record provider + confidence (high = redirect match, medium = single SDK signal, low = inference) + the exact evidence.
+
+**Classify (best-effort; use `null` when unsure — never invent):**
+- `company_name`, `product_summary` — name the product(s) and what they do, who the end users are.
+- `business_model` — B2C / B2B / B2B SaaS / Marketplace / Platform / Fintech / Other.
+- `ai_use_case` — AI-Native / AI-Differentiated / AI-Enhanced / None / Unknown, with a one-line description.
+- `login_portal_assessment` — the distinct login surfaces and who uses each (consumers / business customers / developers / partners / internal staff).
+- `user_types`, `auth_standards_detected` (OIDC / OAuth2 / SAML / JWT / WebAuthn), `notable_auth_features` (MFA, SSO, passwordless, social, magic links, API keys, bot protection).
+- `integrations` — third-party APIs the product or its agents touch (Gmail, Slack, Salesforce, Stripe, GitHub, Jira, HubSpot, …). Used **only** to judge whether Token Vault / CIBA recommendations are relevant.
+
+Save the resulting JSON to `~/.auth0-checkmate/state/enrichment_<domain>_<timestamp>.json` (`company_context_*.json` is also fine).
+
+If context gathering fails (no internet, web tool errors), **don't block** — continue with CheckMate. The Phase 5 report degrades gracefully: findings stay accurate, they just won't be framed in product-specific language.
+
+## Phase 4 — Run CheckMate + gather tenant facts
+
+### 4.1 Prereqs
+- Node ≥ 20.18.3 (`node -v`). CheckMate ships Puppeteer which downloads Chromium (~150 MB) on install — flag this to the user before installing.
+- Install if missing: `npm install -g @auth0/auth0-checkmate`
+
+### 4.2 Run with env-var config
+
+Use an absolute report path (relative paths resolve to cwd which may be wrong) and disable PDF generation — the JSON is what Phase 5 consumes, and skipping PDF avoids the Chromium dependency:
+
+```bash
+REPORT_DIR="$HOME/Documents/auth0_checkmate_reports"
+mkdir -p "$REPORT_DIR"
+source ~/.auth0-checkmate.env 2>/dev/null  # ensure env vars are available
+AUTH0CHECKMATE_DOMAIN="$AUTH0CHECKMATE_DOMAIN" \
+AUTH0CHECKMATE_CLIENT_ID="$AUTH0CHECKMATE_CLIENT_ID" \
+AUTH0CHECKMATE_CLIENT_SECRET="$AUTH0CHECKMATE_CLIENT_SECRET" \
+AUTH0CHECKMATE_FILE_PATH="$REPORT_DIR" \
+AUTH0CHECKMATE_DISABLE_PDF_REPORTING=true \
+AUTH0CHECKMATE_SHOW_VALIDATORS=false \
+a0checkmate
+```
+
+### 4.3 Locate output
+CheckMate writes `<tenant>_<locale>_<YYYYMMDD_HHMMSS>_report.json` (and a `.pdf` unless disabled) into `FILE_PATH`. Pick the newest:
+```bash
+ls -t "$REPORT_DIR"/*_report.json | head -1
+```
+
+The JSON's main array lives at `data.report.summary[]` with fields like `severity` (info/warning/critical), `title`, `severity_message`, `detailsLength`, plus per-finding details. Confirm the exact shape before parsing — versions may evolve.
+
+### 4.4 Gather extra tenant facts (for the report template)
+
+The Phase 5 report needs more than CheckMate alone provides. Run these in parallel and capture each output:
+
+```bash
+auth0 apps list --json                   # apps_list — count + names for Section 1, 3, 4
+auth0 logs list --number 50 --json       # logs_sample — to flag "Active" login activity
+auth0 api get tenants/settings           # tenant_settings — for "Current Auth0 Tier" detection (look for plan/subscription hints; fallback "Free Plan"). Map detected features against the pricing reference to infer the tier when no explicit plan field is present.
+auth0 api get custom-domains             # custom_domains — empty array → triggers "Branding Gap"
+auth0 api get connections                # connections — for enterprise-connection check
+auth0 api get log-streams                # log_streams — empty array → triggers "Observability Gap"
+auth0 api get attack-protection/breached-password-detection  # for "Account Security" section
+```
+
+These outputs feed directly into the Phase 5 fusion.
+
+## Phase 5 — Produce the personalized report (markdown + PDF)
+
+Read all inputs:
+- CheckMate JSON (`*_report.json`) — severities, finding titles, details
+- Enrichment JSON (`state/enrichment_<domain>_<ts>.json`, may be missing if Phase 3 failed)
+- Tenant facts from Phase 4.4
+- `state/operator.json` — reviewer name
+- `state/setup.json.tenant_domain` — canonical tenant URL
+
+**Produce three files** following the locked report skeleton:
+1. A **markdown brief** following the markdown report template in `assets/audit/`
+2. A **styled HTML brief** following `assets/audit/report-template.html` — same data, render-ready
+3. A **PDF** rendered from the HTML by `${CLAUDE_SKILL_DIR}/scripts/render_pdf.sh`
+
+Key rules below.
+
+### Source-of-truth rule
+Every `<tenant_domain>` reference (header right rail, "authentication is served from..." narrative, CLI commands) reads from `state/setup.json.tenant_domain`. Never from the company context. The company context provides company-level fields (name, products, business model, integrations).
+
+### Header
+- Title: **Auth0 Platform Development Review**
+- Subtitle: `Prepared by <reviewer_org>` — **omit the line entirely if `reviewer_org` is blank** (most self-audit cases)
+- Right rail: `<plan_tag>` · `<Customer Name>` · `<tenant_domain>` · `<Month DD, YYYY>`
+- Metadata table:
+  - **Prepared by:** `state/operator.json.reviewer_name`
+  - **Date of Review:** today
+  - **Customer Account:** `<Customer Name> (<tenant_domain>)`
+  - **Current Auth0 Tier:** plan from `tenant_settings`, fallback "Free Plan"
+  - **Use Case Diagnosis:** `<business_model> — <product_summary_short>` from the company context
+  - **Recommended Plan:** `<recommended_plan>` — the plan that fits the customer's use case and unlocks this tenant's *After Upgrading* findings (derived from the use case + findings + the pricing reference; plan name only, no price) ` · Auth for AI Agents: <Yes|No>` (Yes only when Phase 3 found concrete agent / third-party integrations Token Vault or CIBA would serve). Example: `B2B Essentials · Auth for AI Agents: Yes`
+
+### Section 1 — Account Health
+- Metrics table:
+  - Applications Registered: count from `apps_list`
+  - Login Activity: "Active (detected on canonical domain)" / "Inactive" — derived from `logs_sample`
+  - Security Findings: `<N> High`, `<N> Moderate`, `<N> Low / Info`, `<N> Passing` from CheckMate severity breakdown
+- 2-4 personalized **Gap callouts** — bold name + 1-2 sentence narrative naming customer products / portals / users from enrichment. Standard candidates (include only when CheckMate evidence + enrichment context support it):
+  - **The Branding Gap** — empty `custom_domains` → name canonical `tenant_domain`, name 2-3 affected products
+  - **The Security Gap** — no MFA configured → reference customer's user types / data sensitivity
+  - **The Production Readiness Gap** — dev URLs in prod, implicit grant types → name offending apps from `apps_list`
+  - **The Compliance Gap** — empty `log_streams` + regulated industry / EU tenant
+  - **The Observability Gap** — empty `log_streams` (generic version)
+
+### Section 2 — Executive Summary
+- Opening paragraph: name customer products from enrichment, apps count from `apps_list`, "graduating from working setup to production-grade enterprise-ready" framing, then state CheckMate finding counts (`<N> High` and `<N> Moderate`).
+- **Configuration Posture at a Glance** table: Severity / Count / Key Examples (top 3-5 finding titles per row, dot-separated).
+
+### Section 3 — Strategic Opportunities & Action Plan
+Four-column table: **Feature Area · The Enterprise Challenge · The Solution · Strategic Impact**. Standard rows when applicable:
+
+- **Brand Trust & UX → Custom Domains** (no `custom_domains`)
+- **Per-Organization Management → Auth0 Organizations** (B2B + multi-customer apps)
+- **Enterprise SSO → Enterprise Connections (SAML / OIDC)** (B2B + no enterprise connections)
+- **Account Security → MFA (WebAuthn / Authenticator App)** (no MFA)
+- **Observability → Log Streaming** (no `log_streams`)
+- **AI Agent Security → Token Vault (A4AA)** (`ai_use_case` ∈ AI-Native/AI-Differentiated + integrations)
+- **Human-in-the-Loop AI → CIBA (A4AA)** (autonomous-action workflows in enrichment)
+
+Every row weaves enrichment data — name products, customer types, business model, integrations, region.
+
+### Section 4 — Recommended Roadmap & Next Steps
+- **Recommended Plan banner:** `<recommended_plan>` — the plan that fits the customer's use case and unlocks the *After Upgrading* fixes (from the use case + the triage table + the pricing reference). Append " + Auth for AI Agents (A4AA)" only when Phase 3 found concrete agent / third-party integrations Token Vault or CIBA would serve. **Never quote or estimate an Enterprise price;** if Enterprise-only findings exist, note they require Auth0 sales.
+- 1-paragraph rationale tying plan to enrichment (name customer products, business model)
+- **Immediate Actions — Available Today (Free):** numbered list of CheckMate findings actionable on the **current** plan. Name affected apps/connections explicitly. Feeds the remediation reference's Loop A.
+- **After Upgrading:** numbered list of fixes requiring the recommended plan. Feeds the remediation reference's Loop B.
+- **Key Documentation:** 2-column grid of doc links matched to Section 3 rows.
+- Footer: `Confidential · Auth0 tenant configuration review for <Customer Name> · <Month YYYY>`
+
+### Triage rule (Immediate vs After Upgrading)
+
+**The source of truth for which plan a feature requires is the co-loaded pricing reference** — the full Auth0 feature→plan matrix (B2C + B2B). Read it before triaging; do NOT guess from feature names or memory. A finding goes into **Immediate Actions** only if its fix is achievable on the tenant's **current** plan (detected in Phase 4.4, fallback Free). Everything else goes into **After Upgrading**, labeled with the minimum plan that unlocks it.
+
+Common misconception to avoid: **Custom Domains is NOT an upgrade feature** — the Free plan includes 1 custom domain (credit-card verification required). Never place it under "After Upgrading."
+
+Quick reference for the findings CheckMate emits (verify against the pricing reference — it wins on any conflict):
+
+| CheckMate finding | Minimum plan | Loop |
+|---|---|---|
+| Application Grant Types (remove `implicit`, Auth Code + PKCE) | **Free** (app config) | Immediate |
+| Cross Origin Authentication (disable) | **Free** | Immediate |
+| Refresh Tokens (enable rotating) | **Free** | Immediate |
+| PKCE Enforcement / Token Sender-Constraining | **Free** | Immediate |
+| Databases – Password Complexity / Email Attribute Verification | **Free** (connection config) | Immediate |
+| Brute Force Protection / Suspicious IP Throttling | **Free** (all plans) | Immediate |
+| Session Management / Tenant Login URI / Allowed Logout URLs | **Free** (tenant settings) | Immediate |
+| Management API Access Control (M2M scopes) | **Free** | Immediate |
+| **Custom Domains** | **Free** (1, CC verification) | **Immediate** |
+| Email Providers / Email Templates (Email Workflow) | **Essentials** | After Upgrading |
+| Log Streams | **Essentials** (1 stream) | After Upgrading |
+| MFA factors / Multifactor Policy / MFA for Password Reset† | **Essentials** (Pro MFA Factors) | After Upgrading |
+| Breached Password Detection (blocking) / Enhanced Password Protection | **Professional** | After Upgrading |
+| Security Center | **Professional** (B2C) | After Upgrading |
+| Tenant Access Control List (ACL) | **Enterprise** (add-on) | After Upgrading |
+| OIDC Back-Channel Logout | **Enterprise** | After Upgrading |
+| Private Key JWT / JAR / PAR | **Enterprise** | After Upgrading |
+| CIBA (A4AA) | Essentials + **A4AA add-on** | After Upgrading |
+| Token Vault (A4AA) | Free gets 2; more via **A4AA add-on** | After Upgrading (scale) |
+
+† The Password Reset *Action* itself deploys on Free (5 Actions included), but it can only **challenge** MFA once MFA factors are enabled, which requires Essentials+. Treat the end-to-end "MFA on password reset" outcome as Essentials.
+
+Enterprise-only findings (Tenant ACL, Back-Channel Logout, Private Key JWT) are out of self-service scope — list them under After Upgrading but note they require an Enterprise plan / Auth0 sales, not a self-service upgrade.
+
+### Fusion checklist (verify before saving — every item is mandatory)
+
+The point of this workflow is to fuse enrichment intelligence into the audit so the customer sees **why each recommendation matters for their specific business**, not generic best-practice. Before saving the files, walk this checklist. If any item fails, regenerate that section.
+
+1. **Header metadata** uses the customer's actual `company_name`, `business_model`, `product_summary_short`, and the derived `<recommended_plan>` — no template placeholders.
+2. **Section 1 metrics** show real `apps_count` from `auth0 apps list`, real CheckMate severity counts, real login activity derived from `auth0 logs list`.
+3. **Section 1 Gap callouts** each name at least one specific product, app, or user segment from enrichment / `apps_list`. If a callout reads generically ("enterprise clients...", "the affected apps..."), rewrite it with concrete names or omit it.
+4. **Section 2 opening paragraph** lists the customer's products by name (e.g. "Customer Portal, Admin Console, Mobile App") — never "the customer's apps".
+5. **Section 3 — every row's `Enterprise Challenge` cell** references concrete enrichment data: product names, business model, user types, integrations, region, AI workflows, or industry. **If you cannot fill any cell with company-specific content, OMIT the row entirely.** A generic row is worse than no row.
+6. **Section 4 plan rationale** names the customer's products and ties them to the recommended plan's specific features.
+7. **Section 4 action lists** name affected apps/connections explicitly (e.g. "Disable implicit grant on `Default App, Admin Console Web`" — never "Disable implicit grant on the affected apps").
+8. **No `{{placeholder}}` strings** remain in either rendered file.
+
+Final lint:
+```bash
+grep -nE '\{\{|enterprise clients[^A-Za-z]|the customer[^A-Za-z]|the affected apps' "$MD_PATH" "$HTML_PATH"
+```
+Output must be empty. If non-empty, rewrite the flagged passages with company-specific content.
+
+### Output paths
+Write all three to `~/Documents/`, with the same timestamped basename:
+```
+auth0_checkmate_<sanitized_tenant>_<YYYYMMDD_HHMMSS>.md
+auth0_checkmate_<sanitized_tenant>_<YYYYMMDD_HHMMSS>.html
+auth0_checkmate_<sanitized_tenant>_<YYYYMMDD_HHMMSS>.pdf
+```
+(Date-time, not just date — same-day re-runs must not collide. Sanitize `tenant_domain` by replacing `.` with `_`.)
+
+### Render the PDF
+```bash
+"${CLAUDE_SKILL_DIR}/scripts/render_pdf.sh" "$HTML_PATH" "$PDF_PATH"
+# ${CLAUDE_SKILL_DIR} is the absolute path to this skill folder (auto-set by Claude Code).
+# Other agents: substitute the absolute path to wherever this skill folder was extracted.
+```
+
+If the script exits non-zero, surface the renderer's error message — the markdown and HTML are already saved, so the user has fallback artifacts. Common cause: no Chrome / Chromium / Edge / Brave / Arc app installed and no `wkhtmltopdf` / `weasyprint`. The script's stderr message tells the user how to fix.
+
+### Chat summary
+Render a short chat summary: top 3-5 findings by severity, each with a one-line personalized "why this matters for `<Company>`" framed in the customer's product/business terms. End with the three file paths.
+
+## Phase 6 — Walk the user through the report
+
+Branch on `state/setup.json.mode` (set in Phase 0.3):
+
+- **Audit only** → render the chat summary, print the three file paths (md / html / pdf), END the run. Do NOT proceed to remediation.
+- **Express** or **Guided** → render the chat summary, print file paths, then continue to remediation using the co-loaded remediation reference. The report's "Immediate Actions" and "After Upgrading" lists are the canonical work queues.
+
+Remediation itself — the command-shape mapping, the per-item guided flow, the express-mode batch flow, the plan-upgrade gate, and the never-without-confirmation list — is covered in full by the remediation reference loaded alongside this one; every applied fix still requires per-command confirmation, every change is verified by re-fetching the resource, and a failed command is never retried destructively.
+
+## State files
+
+Located under `~/.auth0-checkmate/state/` (created lazily):
+
+| File | Purpose |
+|---|---|
+| `setup.json` | cache: tenant_domain, checkmate_client_id, company_domain, last_run_at — secrets excluded |
+| `operator.json` | reviewer name + optional org/role for the report header |
+| `enrichment_<domain>_<ts>.json` | one per enrichment run |
+| `queue.json` | queued / skipped / pending_upgrade items across runs |
+| `history.jsonl` | append-only log of applied/queued/skipped findings per run |
+
+## Pitfalls to remember
+
+- `read:hooks` / `read:rules` are deprecated; some tenants 400 on grant. Retry without them.
+- Free-plan tenants: 1 M2M app quota for Management API. Reuse if name match.
+- `AUTH0CHECKMATE_FILE_PATH` is relative-to-cwd by default — always pass an absolute path.
+- Tenant region: trust `auth0 tenants list --json`, don't parse the domain.
+- State file is a cache — re-validate each field every run; never act on it without verification.
+- `~/.auth0-checkmate.env` is not auto-sourced. The workflow does it in Phase 4; outside the workflow, the user has to either `source` it manually each session or chain it into their shell rc.
+
+## Portability notes (cross-OS / cross-shell)
+
+This workflow is designed to work for any Auth0 customer, not just the author's machine.
+
+**Operating systems**
+- macOS, Linux, and Windows-WSL are first-class. Native Windows (PowerShell / cmd) is not supported by this workflow's bash steps; users on native Windows should run inside WSL or Git Bash.
+- `~/Documents` exists by default on macOS and Windows; on Linux it depends on user setup. If `~/Documents` doesn't exist, fall back to `~/auth0-checkmate-reports` (create it on first write).
+
+**Shells**
+- `~/.auth0-checkmate.env` uses POSIX `export` syntax — works for bash, zsh, dash, ksh, and Git Bash.
+- Fish shell users: the env file syntax differs (`set -gx` instead of `export`). The workflow writes the POSIX form by default; a fish-specific file at `~/.config/fish/conf.d/auth0-checkmate.fish` can be added by the user. Phase 4's `source ~/.auth0-checkmate.env` won't work in fish — pass env vars inline instead.
+
+**PDF renderer**
+- `scripts/render_pdf.sh` searches Chrome / Chromium / Edge / Brave / Arc on macOS, Linux, and WSL paths automatically. Falls back to `wkhtmltopdf` and then `weasyprint` if no browser is found.
+- If none are available, the markdown and HTML files still get written — the PDF step is skipped with a clear error message telling the user how to install one renderer. The workflow should NOT fail the whole run on PDF render failure.
+
+**Auth0 CLI install**
+- See Phase 1.1 for per-platform install commands. The CLI itself is a single Go binary, so any OS with Go ≥ 1.21 can use `go install` as the universal fallback.
+
+**Self-audit vs CS-audit modes**
+- `reviewer_org` blank → the report subtitle is omitted (clean self-audit look).
+- `reviewer_org` populated → the report subtitle reads "Prepared by `<reviewer_org>`" (CS / consulting / partner mode).
+- Either way, the report content is identical — the only difference is the header subtitle.
+- Enrichment provides company-level fields only — never the tenant URL. Tenant URL always comes from `state/setup.json.tenant_domain`.
diff --git a/main/.mintlify/skills/auth0/references/feature-branding/index.md b/main/.mintlify/skills/auth0/references/feature-branding/index.md
new file mode 100644
index 0000000000..a51d013edc
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/feature-branding/index.md
@@ -0,0 +1,1701 @@
+
+# Auth0 Branding
+
+Style Auth0 Universal Login to match a brand. Covers the theme (colors, typography, borders, widget layout), tenant-level branding settings (logo, favicon, primary color), page templates (Liquid HTML that wraps the widget), and custom text per screen.
+
+## Capabilities
+
+When this skill is invoked **with a specific intent** in the opening message (e.g., "brand my tenant from ferrari.com", "reset the theme", "check if Universal Login is on"), parse the intent and route directly to the matching capability below. Do not show a picker.
+
+When this skill is invoked **without intent** (bare `/auth0-branding`, or a vague "help me with branding"), show the table below and ask in one line: "Pick a number, name one, or describe what you want." Parse the reply — accept `1`, `"brand my tenant"`, or `"make it look like acme.com"` equivalently.
+
+| # | Capability | What it does |
+|---|---|---|
+| 1 | **Brand my tenant** | Style Universal Login end-to-end from a website I own, brand assets I have, or manual input. Colors, logo, typography, page layout, and (optionally) login text voice, applied together |
+| 2 | **Change specific settings** | Update individual pieces directly: a logo, color, font, corner radius, background, button label, or the page template. No URL extraction or asset parsing needed |
+| 3 | **Match my brand voice** | Rewrite Universal Login text to sound like a source I provide: my website, sample copy, or a voice descriptor. Text only; doesn't touch colors or layout |
+| 4 | **Rollback to Auth0 defaults** | Pick what to clear: tenant branding settings, the theme, the page template, or custom text on specific prompts |
+| 5 | **Check my setup** | Verify that login, signup, password reset, and MFA are actually running Universal Login on my tenant and not Classic. Safe read-only starter |
+
+The **Prerequisites** section applies to all capabilities.
+
+## Prompt style
+
+Prefer free-text prompts. The skill should parse natural replies, not force clicks. Use `AskUserQuestion` **only** when one of these applies:
+
+1. **Multi-select of non-obvious options** where seeing the full list helps the user (e.g., Capability 3's flow categories — user won't remember the full set off the top of their head).
+2. **Destructive-path safety gate** (e.g., Capability 4's "save a backup before reset?" yes/no).
+3. **Disambiguation between 3+ distinct paths with meaningful trade-offs** the user wouldn't know by heart.
+
+Everything else is free text. Specifically:
+
+- **Review prompts** ("proceed? apply / edit / cancel, or tell me what to change") are free text. Parse the reply. If the reply names specific changes, apply them inline and re-render the proposal; don't make the user click through an edit submenu.
+- **"Paste a value"** asks (hex code, URL, font name) are free text. Don't wrap single-field input in a picker.
+- **Capability routing at entry** is free text. See the paragraph above the capabilities table.
+
+Discoverability cue: every proposal must list the editable knobs inline, including **"off by default"** ones (voice rewriting, page template, layout override). Users can't ask to edit what they don't know exists. The "Also available" block under the main proposal in Capability 1 is the canonical pattern.
+
+Don't auto-run optional steps (e.g., voice-flow detection, Brandfetch lookup on an unverified domain). Ask first whether the user wants to list, detect, or pick.
+
+## Plan mode
+
+When Claude Code is in plan mode, the skill's writes — PATCH/PUT/DELETE/POST against the Management API, plus local file writes (backup JSON, Brandfetch key) — are held until the plan is approved.
+
+**What's allowed:**
+- GETs against the Management API (loading current theme, branding, custom text, prompts, connections, tenant settings). These drive the proposal and diagnostics.
+- LLM-only work: voice classification, translation generation, proposal rendering.
+- Capability 5 runs unchanged; it's already read-only.
+
+**What's deferred:**
+- All Management API writes (no PATCH/PUT/DELETE/POST).
+- Local file writes: Capability 4 backup JSON, Capability 1 Brandfetch-key save.
+- `auth0 test login` (it starts an auth flow in a browser — not a tenant mutation, but a side effect; defer it along with the writes).
+
+**Still do the interactive asks.** The Brandfetch-key prompt in Capability 1, the source/screens/locale prompts in Capability 3, the surface/backup prompts in Capability 4 — all still happen. Plan mode defers *execution*, not *intent gathering*. For any ask whose answer triggers a write (e.g., "paste a Brandfetch key"), collect the answer and note in the plan "will save to `${XDG_CONFIG_HOME:-$HOME/.config}/auth0-branding/brandfetch.key` on approval."
+
+**Plan contents.** Produce a complete plan covering:
+- Target tenant (from `auth0 tenants list`) and the active-tenant confirmation.
+- Every concrete API call the skill will make, in order: method, path, and a summary of the body (full payloads for small objects like `PATCH /branding`; key names + change counts for large ones like the merged theme object or custom-text PUTs).
+- Every local file write, with absolute path.
+- Scope pre-check outcome for Capability 4, so scope failures surface before approval.
+- The post-apply `auth0 test login` step, if applicable.
+
+Then call `ExitPlanMode`.
+
+**After approval.** Normal execution resumes. All existing gates still apply: active-tenant confirmation, production-write confirmation, WCAG contrast warnings, template-tag validation, merge-before-PUT for custom text, scope checks for destructive operations.
+
+## Verify in browser (post-apply)
+
+After **any capability writes to the tenant** (capabilities 1–4), offer to open the live Universal Login page so the user can see the result immediately. Free-text prompt, not a picker:
+
+> Open the login page in a browser to verify? (yes / no)
+
+If **yes**: run `auth0 test login` on the active tenant. The CLI starts an authorization code flow against the default app and opens the browser. If the environment is headless or the browser fails to open, the CLI prints the authorize URL to stdout — capture it and pass it to the user to open manually.
+
+If **no**: end with the summary of what was written.
+
+Notes:
+- This applies to Capability 1 (Brand my tenant), Capability 2 (Change specific settings), Capability 3 (Match my brand voice), and Capability 4 (Rollback to Auth0 defaults). In the rollback case, the browser page should render Auth0's built-in defaults — that's the verification.
+- Capability 5 (Check my setup) is read-only; skip this step.
+- If the user has a preferred client they test against, they'll mention it; `auth0 test login --client-id <id>` targets a specific app. Otherwise use the default.
+
+## Key Concepts
+
+| Concept | Description |
+|---|---|
+| Theme | Visual settings (colors, fonts, borders, widget layout, backgrounds) applied to Universal Login. Auth0 currently renders only the default theme; additional themes can be created via the API but are not used by Universal Login |
+| Branding Settings | Tenant-level logo, favicon, primary color, and page background color |
+| Page Template | Custom HTML using Liquid syntax that wraps the login widget; requires a custom domain |
+| Text Customization | Per-prompt, per-screen, per-language text overrides on Universal Login pages |
+| Custom Text Variables | Customer-defined keys (prefixed `var-`) in the Custom Text API, referenced from templates and partials as camelCase |
+| Custom Domain | Required for page templates; maps your domain to Auth0's login pages |
+| Universal Login vs Classic | Tenants can render each flow (login/signup, password reset, MFA) in either experience. Theme, template, and no-code editor only apply to flows running Universal Login |
+
+## Prerequisites
+
+These apply to any capability that writes to the tenant. "Check my setup" is read-only and can be run first to verify these are in place.
+
+### CLI Tenant Context (if using the `auth0` CLI)
+
+The Auth0 CLI is authenticated to **one tenant at a time**. All `auth0 ...` commands run against whichever tenant the CLI is currently logged into:
+
+```bash
+auth0 tenants list       # shows all tenants; the active one is marked with →
+auth0 tenants use <name> # switch active tenant; prompts for browser login if not already authenticated
+```
+
+**Before any write operation in any capability, run `auth0 tenants list`, show the active tenant to the user, and get explicit confirmation to proceed.** If it's the wrong tenant, stop. Tell the user to run `auth0 tenants use <name>` (or `auth0 login` if the target isn't in the list) themselves and re-invoke the skill. Do not try to switch tenants on the user's behalf.
+
+For non-interactive or multi-tenant automation, skip the CLI and call the **Management API** directly with an explicit domain + bearer token per call. (see the cURL examples section below)
+
+**Tooling note.** The `auth0 ul` commands below are one way to write branding settings. The loaded tooling reference has the equivalent for infrastructure-as-code projects: the Terraform `auth0_branding` resource (`logo_url`, `favicon_url`, `colors` block). The Auth0 MCP server exposes **no** branding/Universal Login tool — for an MCP-only session, fall back to the CLI, Terraform, or the Management API directly. This interactive branding workflow (extract → propose → apply) stays CLI/API-driven regardless, because it is a guided flow rather than a static config write.
+
+### Universal Login Active for the Flows You Want to Brand
+
+Themes and templates only apply to flows actually running in Universal Login. Tenants can run in hybrid mode where some flows are Classic. Run Capability 5 ("Check my setup") to diagnose which flows will and won't be affected. (see the Check Setup section below for the Classic-toggle mechanics)
+
+### Custom Domain (only if working with page templates)
+
+Page templates require a custom domain on the tenant. Branding settings, theme, and text customization do not. If the task involves page templates and no custom domain is configured, set up a custom domain first (custom domains, feature:custom-domains).
+
+## Capability 1: Brand my tenant
+
+End-to-end branding from a website URL, inline brand values, or a short ask — fills primary color, logo, font, and page background, shows one proposal, and applies the theme.
+
+**See the Brand My Tenant section below.**
+
+## Capability 2: Change specific settings
+
+Manual branding update driven by the user's natural-language intent — the skill resolves the phrase to specific fields, stages changes, and applies as a batch.
+
+**See the Change Specific Settings section below.**
+
+## Capability 3: Match my brand voice
+
+Rewrite Universal Login text to match a source the user provides (website, sample copy, or voice descriptor); doesn't touch colors, layout, or logo.
+
+**See the Match Brand Voice section below.**
+
+## Capability 4: Rollback to Auth0 defaults
+
+Clear one or more branding surfaces and restore Auth0's defaults, per-surface. Destructive; always confirms before writing.
+
+**See the Rollback section below.**
+
+## Capability 5: Check my setup
+
+Read-only diagnosis. Answers "will theme changes actually show up on the flows I care about?" Safe to run first when diagnosing "why doesn't my theme show up?"
+
+**See the Check Setup section below.**
+
+## Common Mistakes
+
+| Mistake | What to Do Instead |
+|---|---|
+| Creating additional themes via `POST /branding/themes` (Universal Login only renders the default theme; POSTed themes exist but never apply) | Always update the default theme: `GET /branding/themes/default`, then PATCH by its `themeId` |
+| Sending a partial PATCH on a theme (PATCH requires all top-level sections) | GET the theme, apply your changes, then PATCH with the full object |
+| Theme or page template changes do not appear on login/reset/MFA (a tenant-wide toggle is forcing that flow into Classic) | Run "Check my setup". Fix the offending tenant toggle: `universal_login_experience: classic` (login/signup), `change_password.enabled: true` (reset), or `guardian_mfa_page.enabled: true` (MFA) |
+| Missing `auth0:head` or `auth0:widget` in templates (both are required; the page will not render without them) | Always include both; refuse the PUT otherwise |
+| Using PUT for custom text without merging (PUT replaces all text for that prompt/language) | GET current text first, merge, then PUT the full object |
+
+For the extended list (theme field requirements, Brandfetch ToS, homepage-only extraction gaps, CSS class names, CLI tenant context), see the API Reference section below.
+
+## References
+
+This file contains all branding guidance inline. Sections: Brand My Tenant · Change Specific Settings · Match Brand Voice · Rollback · Check Setup · API Reference · Examples.
+
+Related capabilities:
+
+- Custom domains, required for page templates (custom domains, feature:custom-domains)
+- Organization-specific branding for B2B multi-tenancy (Organizations, feature:organizations)
+- Custom login-flow logic via Auth0 Actions
+- Advanced Customizations for Universal Login (ACUL) — build fully custom screens beyond what theme + template can do (ACUL, feature:acul)
+
+External:
+
+- [Customize Universal Login](https://auth0.com/docs/customize/login-pages/universal-login)
+- [Customize Themes](https://auth0.com/docs/customize/login-pages/universal-login/customize-themes)
+- [Customize Page Templates](https://auth0.com/docs/customize/login-pages/universal-login/customize-templates)
+- [Customize Text Elements](https://auth0.com/docs/customize/login-pages/universal-login/customize-text-elements)
+- [Branding API Reference](https://auth0.com/docs/api/management/v2/branding)
+- [Brandfetch Brand API](https://docs.brandfetch.com/brand-api/overview)
+- [Brandfetch Logo API Guidelines](https://docs.brandfetch.com/logo-api/guidelines)
+
+---
+
+# Auth0 Branding: API Reference
+
+Complete Management API endpoints, CLI commands, configuration options, and error handling for Auth0 Branding.
+
+## Management API Endpoints
+
+### Branding Settings
+
+| Method | Path | Description | Scopes |
+|--------|------|-------------|--------|
+| GET | `/api/v2/branding` | Get branding settings (logo, colors, favicon, font) | `read:branding` |
+| PATCH | `/api/v2/branding` | Update branding settings | `update:branding` |
+
+### Branding Themes
+
+| Method | Path | Description | Scopes |
+|--------|------|-------------|--------|
+| POST | `/api/v2/branding/themes` | Create a new theme | `create:branding` |
+| GET | `/api/v2/branding/themes/default` | Get the default theme | `read:branding` |
+| GET | `/api/v2/branding/themes/{themeId}` | Get a specific theme | `read:branding` |
+| PATCH | `/api/v2/branding/themes/{themeId}` | Update a theme | `update:branding` |
+| DELETE | `/api/v2/branding/themes/{themeId}` | Delete a theme | `delete:branding` |
+
+**Theme behavior notes:**
+- `GET /branding/themes/default` returns 404 if no theme has been created yet. Create one with POST first.
+- PATCH requires all top-level sections (`colors`, `fonts`, `borders`, `widget`, `page_background`). To update one field, GET the current theme, merge your change, then PATCH the full object.
+- Each theme has a `displayName` string field (optional, used for identification).
+- The response includes a `themeId` string used in subsequent PATCH/DELETE calls.
+
+### Universal Login Templates
+
+| Method | Path | Description | Scopes |
+|--------|------|-------------|--------|
+| GET | `/api/v2/branding/templates/universal-login` | Get page template | `read:branding` |
+| PUT | `/api/v2/branding/templates/universal-login` | Set page template | `update:branding` |
+| DELETE | `/api/v2/branding/templates/universal-login` | Delete page template | `delete:branding` |
+
+### Custom Text (Prompts)
+
+| Method | Path | Description | Scopes |
+|--------|------|-------------|--------|
+| GET | `/api/v2/prompts/<prompt>/custom-text/<language>` | Get custom text | `read:prompts` |
+| PUT | `/api/v2/prompts/<prompt>/custom-text/<language>` | Set custom text (replaces all) | `update:prompts` |
+
+## CLI Commands
+
+### Branding Settings
+
+```bash
+# View current branding configuration
+auth0 ul show
+auth0 ul show --json
+
+# Update branding (interactive)
+auth0 ul update
+
+# Update branding (non-interactive)
+auth0 ul update --accent "#0059DB" --background "#FFFFFF" \
+  --logo "https://example.com/logo.svg" \
+  --favicon "https://example.com/favicon.ico" \
+  --font "https://cdn.example.com/fonts/custom.woff"
+```
+
+### Page Templates
+
+```bash
+# View current page template
+auth0 ul templates show
+
+# Update page template from file
+auth0 ul templates update --file login.liquid
+
+# Update page template (interactive)
+auth0 ul templates update
+```
+
+### Custom Text
+
+```bash
+# View custom text for a prompt
+auth0 ul prompts show login
+auth0 ul prompts show signup -l es
+
+# Update custom text (interactive)
+auth0 ul prompts update login
+auth0 ul prompts update signup -l es
+```
+
+### Customization Editor
+
+```bash
+# Open the browser-based customization editor
+auth0 ul customize
+
+# Switch between standard and advanced rendering modes
+auth0 ul switch
+```
+
+### Testing
+
+```bash
+# Test your login flow in a browser
+auth0 test login
+
+# Test with specific client
+auth0 test login --client-id "{appClientId}"
+
+# Test with organization context
+auth0 test login --organization org_abc123
+```
+
+## Branding Settings Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `colors.primary` | string | Primary accent color (hex, e.g., `#0059DB`) |
+| `colors.page_background` | string | Page background color (hex) |
+| `logo_url` | string | URL to brand logo (HTTPS required; SVG recommended) |
+| `favicon_url` | string | URL to favicon (HTTPS required) |
+| `font.url` | string | URL to custom WOFF font file (HTTPS, CORS-enabled host required) |
+
+## Theme Configuration Properties
+
+### Colors (20+ elements)
+
+| Property | Description |
+|----------|-------------|
+| `primary_button` | Primary button fill color |
+| `primary_button_label` | Primary button text color |
+| `secondary_button_border` | Secondary button / input field border |
+| `secondary_button_label` | Secondary button text color |
+| `links_focused_components` | Link and focus indicator color |
+| `base_focus_color` | Hover state color |
+| `base_hover_color` | Click state color |
+| `header` | Header text color |
+| `body_text` | Body text color |
+| `widget_background` | Widget background color |
+| `widget_border` | Widget border color |
+| `input_labels_placeholders` | Input label and placeholder text color |
+| `input_filled_text` | Typed input text color |
+| `input_border` | Input field border color |
+| `input_background` | Input field background color |
+| `icons` | Input field icon color |
+| `error` | Error message color |
+| `success` | Success message color |
+
+### Fonts
+
+`font_url` and `links_style` are required. Each font-size object (`title`, `subtitle`, `body_text`, `buttons_text`, `input_labels`, `links`) requires both `size` and `bold`.
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `font_url` | string | Yes | WOFF file URL (CORS-enabled host); use `""` for system font |
+| `links_style` | string | Yes | Link style: `"normal"` or `"italic"` |
+| `reference_text_size` | number | Yes | Base text size in pixels |
+| `title.size` | number | Yes | Title size (% of reference) |
+| `title.bold` | boolean | Yes | Whether title is bold |
+| `subtitle.size` | number | Yes | Subtitle size (% of reference) |
+| `subtitle.bold` | boolean | Yes | Whether subtitle is bold |
+| `body_text.size` | number | Yes | Body text size (% of reference) |
+| `body_text.bold` | boolean | Yes | Whether body text is bold |
+| `buttons_text.size` | number | Yes | Button text size (% of reference) |
+| `buttons_text.bold` | boolean | Yes | Whether button text is bold |
+| `input_labels.size` | number | Yes | Input label size (% of reference) |
+| `input_labels.bold` | boolean | Yes | Whether input labels are bold |
+| `links.size` | number | Yes | Link text size (% of reference) |
+| `links.bold` | boolean | Yes | Whether links are bold |
+
+### Borders
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `button_border_weight` | number | Button border width (px) |
+| `buttons_style` | string | `"sharp"`, `"rounded"`, or `"pill"` |
+| `button_border_radius` | number | Button corner radius (rounded only) |
+| `input_border_weight` | number | Input border width (px) |
+| `inputs_style` | string | `"sharp"`, `"rounded"`, or `"pill"` |
+| `input_border_radius` | number | Input corner radius (rounded only) |
+| `widget_corner_radius` | number | Widget corner radius (px) |
+| `widget_border_weight` | number | Widget border width (px) |
+| `show_widget_shadow` | boolean | Enable widget shadow |
+
+### Widget
+
+`logo_url` is required (use `""` if no logo).
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `logo_position` | string | Yes | `"left"`, `"right"`, `"center"`, or `"none"` |
+| `logo_url` | string | Yes | Logo URL (SVG recommended); use `""` for no logo |
+| `logo_height` | number | Yes | Logo height in pixels |
+| `header_text_alignment` | string | Yes | `"left"`, `"right"`, or `"center"` |
+| `social_buttons_layout` | string | Yes | `"top"` or `"bottom"` |
+
+### Page Background
+
+`background_image_url` is required (use `""` if no background image).
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `background_color` | string | Yes | Background color (hex) |
+| `background_image_url` | string | Yes | Background image URL (JPEG, min 2000px wide recommended); use `""` for no image |
+| `page_layout` | string | Yes | Widget position: `"left"`, `"right"`, or `"center"` |
+
+## Error Handling
+
+| HTTP Status | Cause | Resolution |
+|-------------|-------|------------|
+| 400 | Invalid request body (bad hex color, invalid URL, missing required field) | Check request body against schema |
+| 401 | Missing or expired access token | Refresh your Management API token |
+| 403 | Token lacks required scope | Add the required scope to your token (e.g., `update:branding`) |
+| 404 | Theme not found (invalid themeId) or no template set | Verify the themeId exists; use GET first |
+| 409 | Template requires custom domain but none configured | Configure a custom domain before setting templates |
+| 429 | Rate limited | Back off and retry; Management API has per-endpoint rate limits |
+
+## URL Validation
+
+Before writing any URL-valued branding field to the tenant, verify the URL resolves. Use a HEAD request so no content is downloaded:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" --max-time 5 -I "<url>"
+```
+
+**Pass**: 2xx or 3xx response → proceed with the write.
+**Fail**: 4xx, 5xx, or connection timeout → block the write and tell the user which URL failed and what status was returned.
+
+**Fields this applies to:**
+
+| Field | API location |
+|---|---|
+| `logo_url` | `PATCH /branding` |
+| `favicon_url` | `PATCH /branding` |
+| `font.url` | `PATCH /branding` |
+| `widget.logo_url` | theme PATCH |
+| `fonts.font_url` | theme PATCH |
+| `page_background.background_image_url` | theme PATCH |
+
+**Exception — Brandfetch CDN URLs** (`cdn.brandfetch.io`): skip validation. These are browser hotlinks that may reject server-side HEAD requests even when valid. They are always written as-is.
+
+## Extended gotchas
+
+These complement the top-5 table in SKILL.md with longer-tail edge cases that tend to surface during real work.
+
+| Gotcha | What to do |
+|---|---|
+| `GET /branding/themes/default` returns 404, or 200 with all fields null | 404 means the tenant has never had a theme. 200-with-nulls means a theme existed and was deleted. Treat either as "no theme applied." Inspect the response body; don't trust the status alone. Create or restore via `POST /branding/themes`, or PATCH the default once one exists |
+| Omitting required fields on theme create (`fonts.font_url`, `fonts.links_style`, each font element's `bold`, `widget.logo_url`, `page_background.background_image_url`) | Use `""` for URL fields when no custom value is needed; set `bold: false` on each font element. All top-level sections (colors, fonts, borders, widget, page_background) must be present |
+| Targeting CSS class names in page templates | Auth0 regenerates class names on each build; custom CSS keyed off internal classes will break. Use the theme API or no-code editor for styling, and page templates only for structure around the widget |
+| Assuming there is a per-client toggle for Classic login | There isn't. Classic vs Universal is tenant-wide for every flow. Login/signup is driven by `GET /prompts` → `universal_login_experience` (new/classic); password reset by `change_password.enabled` on tenant settings; MFA by `guardian_mfa_page.enabled`. All three apply to every client in the tenant |
+| Extracting brand only from the homepage in Capability 1 | Homepage gives brand identity; the login page gives layout. Follow the login link before capturing layout; see the Brand My Tenant section (Stage 1) |
+| Fetching Brandfetch logos server-side | Violates Brandfetch ToS. Use the hotlink pattern `https://cdn.brandfetch.io/<domain>?c=<client-id>` in `widget.logo_url`; the browser fetches at render time |
+| `PUT` template uses key `template`; `GET` template returns key `body` | Expected API asymmetry. When round-tripping (GET → edit → PUT), remap before the PUT |
+
+---
+
+# Auth0 Branding: Page Templates and Text Customization
+
+Advanced branding customization using Liquid page templates and per-screen text overrides.
+
+## Page Templates
+
+Page templates let you control the HTML structure around the Universal Login widget. They use the [Liquid template language](https://shopify.github.io/liquid/).
+
+### Requirements
+
+- A **custom domain** must be configured on your tenant
+- Templates can only be set via the **Management API** or **CLI** (not the Dashboard)
+- Every template must include `auth0:head` and `auth0:widget` tags
+
+**API key asymmetry:** `PUT` uses the `template` key in the request body. `GET` returns the template under the `body` key. This is expected API behavior.
+
+### Minimal Template
+
+```html
+<!DOCTYPE html>
+{% assign resolved_dir = dir | default: "auto" %}
+<html lang="{{locale}}" dir="{{resolved_dir}}">
+  <head>
+    {%- auth0:head -%}
+  </head>
+  <body class="_widget-auto-layout">
+    {%- auth0:widget -%}
+  </body>
+</html>
+```
+
+Add `class="_widget-auto-layout"` on `<body>` to center the widget. Omit it to position the widget manually.
+
+### Template with Custom Layout
+
+```html
+<!DOCTYPE html>
+{% assign resolved_dir = dir | default: "auto" %}
+<html lang="{{locale}}" dir="{{resolved_dir}}">
+  <head>
+    {%- auth0:head -%}
+    <style>
+      .custom-container {
+        display: flex;
+        min-height: 100vh;
+      }
+      .brand-panel {
+        flex: 1;
+        background: {{ branding.colors.primary }};
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        color: white;
+        padding: 2rem;
+      }
+      .login-panel {
+        flex: 1;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="custom-container">
+      <div class="brand-panel">
+        <div>
+          <img src="{{ branding.logo_url }}" alt="{{ tenant.friendly_name }}" />
+          <h1>Welcome to {{ tenant.friendly_name }}</h1>
+          {% if organization.display_name %}
+            <p>Signing in as {{ organization.display_name }}</p>
+          {% endif %}
+        </div>
+      </div>
+      <div class="login-panel">
+        {%- auth0:widget -%}
+      </div>
+    </div>
+  </body>
+</html>
+```
+
+### Available Template Variables
+
+#### Application
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `application.id` | Client ID | `XXXXXXXXXXXXXXXXX` |
+| `application.name` | Application name | `My Application` |
+| `application.logo_url` | Application logo URL | `https://example.com/logo.png` |
+| `application.metadata` | Application metadata object | `{"key": "value"}` |
+
+#### Branding
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `branding.logo_url` | Tenant logo URL | `https://example.com/logo.png` |
+| `branding.colors.primary` | Primary branding color | `#0059DB` |
+| `branding.colors.page_background` | Page background color | `#FFFFFF` |
+
+#### Tenant
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `tenant.friendly_name` | Tenant display name | `My Tenant` |
+| `tenant.support_email` | Support email | `support@example.com` |
+| `tenant.support_url` | Support page URL | `https://example.com/support` |
+| `tenant.enabled_locales` | Enabled locale codes | `en, es` |
+
+#### Organization (B2B)
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `organization.id` | Organization ID | `org_XXXXXXX` |
+| `organization.display_name` | Display name | `Acme Corp` |
+| `organization.name` | Internal name | `acme-corp` |
+| `organization.branding.logo_url` | Org-specific logo | `https://acme.com/logo.png` |
+| `organization.branding.colors.primary` | Org primary color | `#FF0000` |
+| `organization.branding.colors.page_background` | Org background | `#FAFAFA` |
+
+#### Current User (post-authentication screens only)
+
+| Variable | Description |
+|----------|-------------|
+| `user.user_id` | User profile ID |
+| `user.email` | Email address |
+| `user.name` | Full name |
+| `user.picture` | Profile picture URL |
+| `user.email_verified` | Boolean verification status |
+
+#### Screen Context
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `locale` | Current locale | `en-US` |
+| `dir` | Text direction | `auto`, `rtl`, `ltr` |
+| `prompt.name` | Current prompt | `login`, `mfa` |
+| `prompt.screen.name` | Current screen | `login`, `mfa-login-options` |
+| `prompt.screen.texts` | Localized screen text | `{"pageTitle": "Log In"}` |
+
+### Template Limitations
+
+- **CSS class names change on each Auth0 build.** Do not target internal class names; they will break.
+- **HTML structure may change.** Avoid customizations that depend on the widget's internal DOM.
+- **Storybook rendering**: `<script>` tags break Storybook. Workaround: `<scr` + `ipt>code</scr` + `ipt>`
+
+## Text Customization
+
+### Supported Prompts
+
+Common prompts you can customize (not a complete list; Auth0 supports additional prompts for MFA methods, passkeys, and other flows):
+
+| Prompt | Screens |
+|--------|---------|
+| `login` | `login` |
+| `login-id` | `login-id` |
+| `login-password` | `login-password` |
+| `signup` | `signup` |
+| `signup-id` | `signup-id` |
+| `signup-password` | `signup-password` |
+| `consent` | `consent` |
+| `mfa` | `mfa-enroll-options`, `mfa-login-options`, `mfa-otp-challenge` |
+| `reset-password` | `reset-password-request`, `reset-password-email` |
+| `device-flow` | `device-code-activation`, `device-code-confirmation` |
+
+### API Behavior
+
+The `PUT /api/v2/prompts/<prompt>/custom-text/<language>` endpoint **replaces** all custom text for that prompt and language. To update one screen without losing others, first GET the current text, merge your changes, then PUT the full object back.
+
+`GET` returns only the keys you have explicitly set, not the full set of Auth0 default strings. An empty object (`{}`) means no custom text is set and Auth0's defaults are used.
+
+```bash
+# Get current text, modify, then set
+CURRENT=$(auth0 api get "prompts/login/custom-text/en")
+# Merge changes into $CURRENT
+auth0 api put "prompts/login/custom-text/en" --data "$UPDATED"
+```
+
+### Delete Custom Text
+
+Send an empty object to remove all custom text for a prompt:
+
+```bash
+auth0 api put "prompts/login/custom-text/en" --data '{}'
+```
+
+---
+
+# Universal Login screens, by category
+
+Canonical category map used by "Match my brand voice" to expand user-selected categories into concrete (prompt, screen) pairs for custom-text rewrites. Source: Auth0 internal data.
+
+**This list is a starting point, not complete.** Auth0 adds new screens over time. When the skill encounters a screen name it doesn't recognize (the user mentions one, or a new flow lights up), it should fall back to probing `GET /api/v2/prompts/{prompt}/custom-text/{lang}` for the candidate prompt/locale: the response indicates whether the prompt accepts that screen's keys. If the user knows the new screen name but the skill doesn't, accept what they give and proceed. The skill should treat this map as current-as-of-last-update, not as the authoritative registry.
+
+The custom-text API is **per-prompt, not per-screen**. Multiple screens under the same prompt share one PUT call with a single merged body keyed by screen name. When applying rewrites, batch screens by prompt.
+
+**Single-screen prompts:** Many prompts have exactly one screen, where the screen name matches the prompt name (e.g., prompt `login-id`, screen `login-id`). These still require their own individual PUT call — batching doesn't apply, but the structure is the same. Do not attempt to nest them under a parent prompt.
+
+**Currency of this list:** The tables below reflect the known screen inventory as of last update. Auth0 adds screens over time — new screens may appear under existing prompts, or entirely new prompts may be introduced. Treat this list as a reliable baseline, not a closed registry. If the API accepts a screen or prompt not listed here, that is expected; follow the "Learn new screens" flow in the Match Brand Voice section to record it.
+
+**Important: `GET /prompts/{prompt}/custom-text/{lang}` returns only keys the tenant has explicitly customized**, not Auth0's default built-in text. For a screen the tenant has never customized, GET returns an empty object (or the key is absent) and the skill cannot read the default copy via the API. See the Match Brand Voice section "Generate and apply" for how to handle this.
+
+## Login
+
+**Identifier-first note:** `login-id` and `login-password` are each their own prompt, not screens nested under the `login` prompt. Each takes a separate `PUT /prompts/{prompt}/custom-text/{lang}` call with a body keyed by the screen name matching the prompt name (e.g., `{ "login-id": { ... } }`). Do not batch them under `login`.
+
+| Prompt | Screen |
+|---|---|
+| login | login |
+| login-id | login-id |
+| login-password | login-password |
+| email-identifier-challenge | email-identifier-challenge |
+| phone-identifier-challenge | phone-identifier-challenge |
+| phone-identifier-enrollment | phone-identifier-enrollment |
+| login-email-verification | login-email-verification |
+
+## Signup
+
+**Same pattern as Login:** `signup-id` and `signup-password` are separate prompts, not screens under `signup`. Each requires its own PUT call.
+
+| Prompt | Screen |
+|---|---|
+| signup | signup |
+| signup-id | signup-id |
+| signup-password | signup-password |
+
+## Passwordless
+
+| Prompt | Screen |
+|---|---|
+| login-passwordless | login-passwordless-email-code |
+| login-passwordless | login-passwordless-email-link |
+| login-passwordless | login-passwordless-sms-otp |
+| email-otp-challenge | email-otp-challenge |
+
+## Password reset
+
+Includes reset-time MFA challenge screens because they're part of the reset flow Auth0-side.
+
+| Prompt | Screen |
+|---|---|
+| reset-password | reset-password |
+| reset-password | reset-password-request |
+| reset-password | reset-password-email |
+| reset-password | reset-password-success |
+| reset-password | reset-password-error |
+| reset-password | reset-password-mfa-email-challenge |
+| reset-password | reset-password-mfa-otp-challenge |
+| reset-password | reset-password-mfa-push-challenge-push |
+| reset-password | reset-password-mfa-sms-challenge |
+| reset-password | reset-password-mfa-phone-challenge |
+| reset-password | reset-password-mfa-voice-challenge |
+| reset-password | reset-password-mfa-recovery-code-challenge |
+| reset-password | reset-password-mfa-webauthn-platform-challenge |
+| reset-password | reset-password-mfa-webauthn-roaming-challenge |
+
+## Passkeys
+
+| Prompt | Screen |
+|---|---|
+| passkeys | passkey-enrollment |
+| passkeys | passkey-enrollment-local |
+
+## MFA
+
+Grouped by factor. When the user picks MFA, show a sub-picker so they can scope to the factors they've actually enabled on the tenant.
+
+**Key restrictions on `mfa` prompt screens:** `mfa-begin-enroll-options` and `mfa-login-options` only accept `title` — `description` is not a valid key and the API will reject it with a 400. Do not include `description` in rewrites for these screens.
+
+| Prompt | Screen |
+|---|---|
+| mfa | mfa-begin-enroll-options |
+| mfa | mfa-detect-browser-capabilities |
+| mfa | mfa-enroll-result |
+| mfa | mfa-login-options |
+| mfa-email | mfa-email-challenge |
+| mfa-email | mfa-email-list |
+| mfa-otp | mfa-otp-challenge |
+| mfa-otp | mfa-otp-enrollment-code |
+| mfa-otp | mfa-otp-enrollment-qr |
+| mfa-push | mfa-push-challenge-push |
+| mfa-push | mfa-push-enrollment-code |
+| mfa-push | mfa-push-enrollment-qr |
+| mfa-push | mfa-push-list |
+| mfa-push | mfa-push-success |
+| mfa-push | mfa-push-welcome |
+| mfa-sms | mfa-country-codes |
+| mfa-sms | mfa-sms-challenge |
+| mfa-sms | mfa-sms-enrollment |
+| mfa-sms | mfa-sms-list |
+| mfa-phone | mfa-phone-challenge |
+| mfa-phone | mfa-phone-enrollment |
+| mfa-voice | mfa-voice-challenge |
+| mfa-voice | mfa-voice-enrollment |
+| mfa-recovery-code | mfa-recovery-code-challenge |
+| mfa-recovery-code | mfa-recovery-code-enrollment |
+| mfa-recovery-code | mfa-recovery-code-challenge-new-code |
+| mfa-webauthn | mfa-webauthn-change-key-nickname |
+| mfa-webauthn | mfa-webauthn-enrollment-success |
+| mfa-webauthn | mfa-webauthn-error |
+| mfa-webauthn | mfa-webauthn-platform-challenge |
+| mfa-webauthn | mfa-webauthn-platform-enrollment |
+| mfa-webauthn | mfa-webauthn-roaming-challenge |
+| mfa-webauthn | mfa-webauthn-roaming-enrollment |
+| mfa-webauthn | mfa-webauthn-not-available-error |
+
+## Organizations (B2B)
+
+| Prompt | Screen |
+|---|---|
+| organizations | organization-picker |
+| organizations | organization-selection |
+| invitation | accept-invitation |
+
+## Other
+
+Long-tail screens rarely targeted for voice rewrites. Available if the user explicitly picks the Other category, where they can then choose individual screens.
+
+| Prompt | Screen |
+|---|---|
+| consent | consent |
+| customized-consent | customized-consent |
+| logout | logout |
+| logout | logout-aborted |
+| logout | logout-complete |
+| device-flow | device-code-activation |
+| device-flow | device-code-activation-allowed |
+| device-flow | device-code-activation-denied |
+| device-flow | device-code-confirmation |
+| email-verification | email-verification-result |
+| captcha | interstitial-captcha |
+| brute-force-protection | brute-force-protection-unblock |
+| brute-force-protection | brute-force-protection-unblock-failure |
+| brute-force-protection | brute-force-protection-unblock-success |
+| common | redeem-ticket |
+| status | status |
+| custom-form | custom-form |
+
+---
+
+# Auth0 Branding: API Examples
+
+Management API examples for configuring branding, themes, page templates, and text customization, plus patterns for CI/CD deployment and tenant migration. Auth0 Branding has no SDK-side code; all configuration is through the Management API.
+
+## Prerequisites
+
+- Management API access token with appropriate scopes (see the Management API Endpoints section above for per-endpoint scopes)
+- For page templates: a custom domain configured on your tenant
+
+## cURL examples
+
+### Get branding settings
+
+```bash
+curl --request GET \
+  --url 'https://{yourDomain}/api/v2/branding' \
+  --header 'authorization: Bearer {yourMgmtApiAccessToken}'
+```
+
+### Update branding settings
+
+```bash
+curl --request PATCH \
+  --url 'https://{yourDomain}/api/v2/branding' \
+  --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
+  --header 'content-type: application/json' \
+  --data '{
+    "colors": {
+      "primary": "#0059DB",
+      "page_background": "#FFFFFF"
+    },
+    "logo_url": "https://example.com/logo.svg",
+    "favicon_url": "https://example.com/favicon.ico",
+    "font": {
+      "url": "https://cdn.example.com/fonts/custom.woff"
+    }
+  }'
+```
+
+### Get default theme
+
+```bash
+curl --request GET \
+  --url 'https://{yourDomain}/api/v2/branding/themes/default' \
+  --header 'authorization: Bearer {yourMgmtApiAccessToken}'
+```
+
+### Create a theme
+
+All top-level sections are required. Within `fonts`, `font_url` and `links_style` are required, and each font-size object requires a `bold` boolean. Within `widget`, `logo_url` is required (use `""` if no logo). Within `page_background`, `background_image_url` is required (use `""` if no image).
+
+```bash
+curl --request POST \
+  --url 'https://{yourDomain}/api/v2/branding/themes' \
+  --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
+  --header 'content-type: application/json' \
+  --data '{
+    "displayName": "My Theme",
+    "colors": {
+      "primary_button": "#0059DB",
+      "primary_button_label": "#FFFFFF",
+      "secondary_button_border": "#C9CACE",
+      "secondary_button_label": "#1E212A",
+      "base_focus_color": "#0059DB",
+      "base_hover_color": "#004DB7",
+      "links_focused_components": "#0059DB",
+      "header": "#1E212A",
+      "body_text": "#1E212A",
+      "widget_background": "#FFFFFF",
+      "widget_border": "#C9CACE",
+      "input_labels_placeholders": "#65676E",
+      "input_filled_text": "#1E212A",
+      "input_border": "#C9CACE",
+      "input_background": "#FFFFFF",
+      "icons": "#65676E",
+      "error": "#D03C38",
+      "success": "#13A688"
+    },
+    "fonts": {
+      "font_url": "",
+      "links_style": "normal",
+      "reference_text_size": 16,
+      "title": { "size": 150, "bold": false },
+      "subtitle": { "size": 87.5, "bold": false },
+      "body_text": { "size": 87.5, "bold": false },
+      "buttons_text": { "size": 100, "bold": false },
+      "input_labels": { "size": 100, "bold": false },
+      "links": { "size": 87.5, "bold": false }
+    },
+    "borders": {
+      "button_border_weight": 1,
+      "buttons_style": "rounded",
+      "button_border_radius": 3,
+      "input_border_weight": 1,
+      "inputs_style": "rounded",
+      "input_border_radius": 3,
+      "widget_corner_radius": 5,
+      "widget_border_weight": 0,
+      "show_widget_shadow": true
+    },
+    "widget": {
+      "logo_position": "center",
+      "logo_url": "https://example.com/logo.svg",
+      "logo_height": 52,
+      "header_text_alignment": "center",
+      "social_buttons_layout": "bottom"
+    },
+    "page_background": {
+      "background_color": "#000000",
+      "background_image_url": "",
+      "page_layout": "center"
+    }
+  }'
+```
+
+### Update a theme
+
+PATCH requires all top-level sections (colors, fonts, borders, widget, page_background). To change only colors, GET the current theme first, merge your changes, then PATCH the full object.
+
+```bash
+# Get current theme, then patch with full body
+THEME=$(curl --request GET \
+  --url 'https://{yourDomain}/api/v2/branding/themes/default' \
+  --header 'authorization: Bearer {yourMgmtApiAccessToken}')
+
+# Merge your color change into $THEME, then:
+curl --request PATCH \
+  --url 'https://{yourDomain}/api/v2/branding/themes/{themeId}' \
+  --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
+  --header 'content-type: application/json' \
+  --data '{
+    "colors": { "primary_button": "#FF4F40", ...all other color fields... },
+    "fonts": { ...all font fields... },
+    "borders": { ...all border fields... },
+    "widget": { ...all widget fields... },
+    "page_background": { ...all page_background fields... }
+  }'
+```
+
+### Set page template
+
+```bash
+curl --request PUT \
+  --url 'https://{yourDomain}/api/v2/branding/templates/universal-login' \
+  --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
+  --header 'content-type: application/json' \
+  --data '{
+    "template": "<!DOCTYPE html>{% assign resolved_dir = dir | default: \"auto\" %}<html lang=\"{{locale}}\" dir=\"{{resolved_dir}}\"><head>{%- auth0:head -%}</head><body class=\"_widget-auto-layout\">{%- auth0:widget -%}</body></html>"
+  }'
+```
+
+### Set custom text
+
+```bash
+curl --request PUT \
+  --url 'https://{yourDomain}/api/v2/prompts/login/custom-text/en' \
+  --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
+  --header 'content-type: application/json' \
+  --data '{
+    "login": {
+      "title": "Welcome back",
+      "description": "Log in to continue to My App"
+    }
+  }'
+```
+
+## Deployment and migration patterns
+
+### Export and version control
+
+Store branding configuration in version control and deploy as part of your release pipeline.
+
+```bash
+# Export current branding settings
+auth0 ul show --json > branding-settings.json
+
+# Export current page template
+auth0 ul templates show > login-template.liquid
+
+# Export custom text for prompts you've customized
+auth0 api get "prompts/login/custom-text/en" > text-login-en.json
+auth0 api get "prompts/signup/custom-text/en" > text-signup-en.json
+```
+
+### Deploy branding in a pipeline
+
+```bash
+#!/bin/bash
+# deploy-branding.sh
+# Requires: AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET
+
+auth0 login --client-id "$AUTH0_CLIENT_ID" \
+  --client-secret "$AUTH0_CLIENT_SECRET" \
+  --domain "$AUTH0_DOMAIN" --no-input
+
+auth0 ul update \
+  --logo "https://cdn.example.com/logo.svg" \
+  --accent "#0059DB" \
+  --background "#FFFFFF" \
+  --favicon "https://cdn.example.com/favicon.ico" \
+  --no-input
+
+auth0 ul templates update --file ./branding/login-template.liquid --no-input
+
+auth0 api put "prompts/login/custom-text/en" --data @./branding/text-login-en.json
+auth0 api put "prompts/signup/custom-text/en" --data @./branding/text-signup-en.json
+```
+
+### Multi-environment layout
+
+Keep environment-specific branding in separate config files:
+
+```text
+branding/
+  base/
+    theme.json          # shared theme structure
+    login-template.liquid
+  environments/
+    dev/
+      settings.json
+      text-login-en.json
+    staging/
+      settings.json
+      text-login-en.json
+    production/
+      settings.json
+      text-login-en.json
+```
+
+### Copy branding between tenants
+
+```bash
+# Export from source tenant
+AUTH0_TENANT=source-tenant.auth0.com
+
+BRANDING=$(auth0 api get "branding" --json)
+THEME=$(auth0 api get "branding/themes/default" --json 2>/dev/null)
+TEMPLATE=$(auth0 api get "branding/templates/universal-login" --json 2>/dev/null)
+LOGIN_TEXT=$(auth0 api get "prompts/login/custom-text/en" --json 2>/dev/null)
+
+# Import to target tenant
+AUTH0_TENANT=target-tenant.auth0.com
+
+echo "$BRANDING" | auth0 api patch "branding" --data @-
+
+if [ -n "$THEME" ]; then
+  echo "$THEME" | auth0 api post "branding/themes" --data @-
+fi
+
+if [ -n "$TEMPLATE" ]; then
+  echo "$TEMPLATE" | auth0 api put "branding/templates/universal-login" --data @-
+fi
+
+if [ -n "$LOGIN_TEXT" ]; then
+  echo "$LOGIN_TEXT" | auth0 api put "prompts/login/custom-text/en" --data @-
+fi
+```
+
+### Verify branding changes
+
+```bash
+# Open a test login flow in your browser
+auth0 test login
+
+# Test with a specific application
+auth0 test login --client-id "{yourAppClientId}"
+
+# Test with organization context (for B2B branding)
+auth0 test login --organization org_abc123
+
+# Verify via API
+auth0 api get "branding" --json | jq '.colors'
+auth0 api get "branding/themes/default" --json | jq '.colors.primary_button'
+auth0 api get "branding/templates/universal-login" --json | jq '.template' | head -1
+```
+
+---
+
+# Capability 1: Brand my tenant
+
+End-to-end branding. The tenant's theme, logo, and typography are updated to match a single source. Invoked from SKILL.md when the user asks to brand a tenant from a website or brand assets.
+
+Scope is intentionally narrow: **four brand values** (primary color, logo URL, font family, page background) plus the target tenant. Layout, voice rewriting, and locale handling are out of the default path; users opt in to them via `[edit]` on the review.
+
+## Start: parse input, prompt only for what's missing
+
+Parse the user's opening message first. Only ask when the skill needs something it can't infer.
+
+Look for:
+- **A URL** (http/https, non-Figma) → use Brandfetch; see "Extract brand tokens".
+- **Inline brand values** (hex codes, logo URL, font URL, design tokens, Tailwind/CSS snippets, palette) → use directly.
+- **A Figma URL** → see "Figma".
+- **Nothing** → one prompt:
+  ```text
+  Paste a website URL, or drop your brand values (primary color, logo URL,
+  font). I'll propose a branding you can review before anything changes.
+  ```
+
+Tool detection is silent. The only external dependency in the default path is Brandfetch (optional). There is no Playwright/browser step; if the user wants layout fidelity, they upload a screenshot via `[edit]`.
+
+## Extract brand tokens
+
+Four slots to fill: **primary color, logo URL, font family, page background**. Background defaults to white; the other three come from Brandfetch when available, from the user's inline values, or from a short ask.
+
+### Source: URL
+
+1. Check for a stored Brandfetch key at `${XDG_CONFIG_HOME:-$HOME/.config}/auth0-branding/brandfetch.key`. This follows the XDG Base Directory spec: honor `$XDG_CONFIG_HOME` when it's set, otherwise fall back to `~/.config/`. Saves and reads use the same resolved path.
+2. If no key, one-time ask:
+   ```text
+   One-time setup: Brandfetch gives the cleanest colors, fonts, and logos
+   for URL-based branding. Free tier covers 100 lookups/month.
+     [paste key]  [sign up, ~30s]  [skip]
+   (Saved locally; won't ask again.)
+   ```
+   If skipped, persist the decision so future runs don't re-ask. The user can paste a key later with "use this Brandfetch key: <key>".
+3. If a key is available: `GET https://api.brandfetch.io/v2/brands/<domain>` with `Authorization: Bearer <key>`. Map the response:
+   - **Primary color**: first `colors[].type == "accent"`, else `"dark"`.
+   - **Logo URL**: light-theme SVG from `logos[]` (hotlink; don't fetch server-side per Brandfetch ToS).
+   - **Font family**: `fonts[].type == "body"` or `"title"`, combined with Auth0's standard fallback stack (e.g. `"<brand font>", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif`).
+4. If Brandfetch was skipped, unreachable, or returned an incomplete response, fall through to "ask for missing values".
+
+### Source: inline values
+
+Parse whatever the user pasted. Any of these is fine:
+- Raw hex codes (`#0051BA` → primary color)
+- A palette list (map first hex to primary)
+- CSS variable snippet (`--primary: #0051BA`)
+- Design tokens JSON (W3C or Figma export)
+- Tailwind config fragment
+- Logo URL
+- Font URL (Google Fonts stylesheet or a WOFF file) or CSS font name
+
+User-supplied values always override Brandfetch.
+
+### Figma
+
+Figma pages don't render server-side; a URL alone can't be scraped. If the user pastes a Figma URL:
+
+1. **Figma MCP detected silently** (Claude Code has the server connected) → read tokens, variables, and styles directly.
+2. **No Figma MCP** → one prompt:
+   ```text
+   I need the Figma MCP server to read a Figma file. Set it up here:
+   https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server
+
+   Or paste the brand values directly:
+     primary color hex
+     logo URL (hosted)
+     font name
+   ```
+
+Figma typically covers colors and typography; it does not cover a hostable logo URL. The user supplies that separately.
+
+### Ask for missing values
+
+After all available sources have been tried, if any of the four slots is still empty, ask once in a consolidated prompt:
+
+```text
+I need a few brand values to finish the proposal (paste hex codes / URLs,
+or type "skip" for any to use the Auth0 default):
+
+  Primary color     (hex, e.g. #0051BA)
+  Logo URL          (must be hosted; Auth0 does not host uploaded files)
+  Font family       (CSS name, e.g. "Inter", or a Google Fonts URL)
+```
+
+Omit rows for slots that are already filled. Parse the reply in any reasonable format.
+
+## Defaults (not extracted; not asked)
+
+These are held constant unless the user opts in to changing them via `[edit]`:
+
+- **Layout**: Auth0's centered single-column widget.
+- **Secondary colors** (border, link, muted text): derived from the primary using standard contrast rules, or left at Auth0 defaults.
+- **Voice / text**: not rewritten. Users who want text to match their brand voice run Capability 3 ("Match my brand voice") as a separate step.
+- **Locales**: existing enabled locales are unaffected.
+
+## Propose
+
+Single proposal, single free-text review prompt. Always include the "Also available" block so users can see what else is editable.
+
+```text
+Proposed branding for ikea.com:
+
+  Primary color      #0051BA      (from Brandfetch)
+  Button label       #FFFFFF      (derived from primary contrast)
+  Page background    #FFFFFF
+  Body text          #111111      (Auth0 default)
+  Typography         Noto IKEA, Noto Sans, system-ui
+                                  (from Brandfetch; browser loads
+                                   Noto Sans as the hostable fallback)
+  Logo               https://cdn.brandfetch.io/...
+
+  Layout             centered single-column  (Auth0 default)
+
+Also available (off unless you ask):
+  Page template      off           (paste HTML/Liquid; needs a custom domain)
+  Layout override    off           (upload a screenshot for a vision-based pass)
+  Voice rewriting    off           (rewrite login text in the brand's voice after apply)
+
+Target tenant: acme-prod (active in Auth0 CLI)
+```
+> Proceed? (apply / edit / cancel, or tell me what to change.)
+
+Show provenance inline (`(from Brandfetch)`, `(you supplied)`, `(Auth0 default)`) so the user can tell at a glance what came from where.
+
+### Parsing the review reply
+
+The review reply is free text. Handle these cases:
+
+- **Clear apply** (`"apply"`, `"y"`, `"yes"`, `"go"`, `"ship it"`) → jump to "Confirm target tenant".
+- **Clear cancel** (`"cancel"`, `"n"`, `"no"`, `"stop"`) → abort; no writes.
+- **Bare "edit"** with no specifics → print the list of editable knobs (everything in the proposal plus the "Also available" items) and wait for the next reply.
+- **Named edits** (`"change primary to #181818"`, `"enable voice rewriting"`, `"use Inter as the font and dark background"`, `"paste this template: ..."`) → update the relevant slots, re-render the proposal, ask `Proceed?` again.
+- **Ambiguous** ("make it darker", "looks fine but the logo is wrong") → ask one short clarifying question in free text; don't kick back to a picker.
+
+Editable knobs and what each reply means:
+
+| Reply pattern | Slot to update |
+|---|---|
+| `primary color <hex>`, `brand color <hex>`, `make the primary <hex>` | `colors.primary_button` (theme) and `colors.primary` (tenant branding) |
+| `logo <url>`, `use this logo <url>` | `widget.logo_url` (theme) and `logo_url` (tenant branding) |
+| `font <name>` or `font <google-fonts-url>` | `fonts.font_url` (theme) after resolving family |
+| `background <hex>` | `colors.page_background` (tenant branding) and `page_background.background_color` (theme) |
+| Uploaded screenshot + "match this layout" | Layout override: run vision pass, map to theme knobs (widget position, page background, border style) |
+| Pasted HTML/Liquid block | Page template override: verify `auth0:head` and `auth0:widget` are present, stage for apply. Requires a custom domain — warn if none is configured. |
+| `enable voice rewriting`, `rewrite the copy too`, `also match the voice` | Set voice flag on. After apply, chain into the "Match my brand voice" section below. If the tenant has more than one enabled locale, that flow asks whether to rewrite all locales or English only. |
+
+## Confirm target tenant
+
+Before any write, run `auth0 tenants list` and present the active tenant:
+
+```text
+Target tenant: acme-prod  (active in the Auth0 CLI)
+
+  [y] apply to acme-prod
+  [n] cancel
+```
+
+If it's the wrong tenant, cancel. Tell the user to run `auth0 tenants use <name>` (or `auth0 login`) themselves and re-invoke the skill. Do not try to switch tenants on the user's behalf.
+
+For non-interactive / multi-tenant workflows, accept an explicit tenant domain + bearer token inline instead of the CLI; see the cURL examples section below.
+
+## Apply
+
+Execute based on what the user approved in the review:
+
+Before writing, validate any URL-valued fields (logo, favicon, font, background image) using the HEAD request check in the API Reference section below (URL Validation). Block writes for URLs that fail. Skip validation for `cdn.brandfetch.io` URLs.
+
+1. **Tenant branding settings** (logo, favicon, primary color, page background): `PATCH /api/v2/branding`.
+2. **Theme** (colors, fonts, widget): `GET /branding/themes/default` → merge → `PATCH /branding/themes/{themeId}` with the full object. Partial PATCH is not supported; always send the full theme.
+3. **Page template** (only if the user pasted one via `[edit]` AND the tenant has a custom domain): `PUT /api/v2/branding/templates/universal-login`. Refuse the PUT if the template is missing `auth0:head` or `auth0:widget`.
+4. **Voice rewrites** (only if `[edit] → voice rewriting` was enabled): hand off to the Match Brand Voice section with the primary-color/font context so it doesn't re-ask.
+
+Before writing, diff the proposed changes against current tenant state. In production environments, require explicit confirmation. Auth0 does not retain prior theme/template/text versions; if the user wants a backup, suggest exporting current state locally before applying (see the backup flow in the Rollback section below).
+
+Report what was written and what was skipped (for example, "page template skipped — no custom domain configured"). If voice rewriting was opted in, chain into Capability 3 after the theme write succeeds.
+
+After reporting (and after voice rewriting chains complete, if enabled), run the "Verify in browser (post-apply)" step from SKILL.md.
+
+---
+
+# Capability 5: Check my setup
+
+Read-only diagnosis. Answers "will theme changes actually show up on the flows I care about?"
+
+Safe to run first; a good starter when diagnosing "why doesn't my theme show up?" before running Capability 1 ("Brand my tenant").
+
+## Background: Universal Login vs Classic
+
+Themes and templates only apply to flows actually running in Universal Login. Tenants can run in hybrid mode where some flows are Classic. Branding in this skill does not affect Classic flows.
+
+All three Classic toggles are **tenant-wide**. There is no per-client override; if a flow is set to Classic, every client in the tenant uses Classic for that flow.
+
+- **Login and signup**: `GET /api/v2/prompts` → `universal_login_experience`. `"classic"` means every client's login and signup runs Classic; `"new"` means Universal Login.
+- **Password reset**: `PATCH /api/v2/tenants/settings`; the `change_password` object (`{ enabled, html }`). When `enabled: true`, the tenant renders Classic for password reset.
+- **MFA**: same endpoint; the `guardian_mfa_page` object (`{ enabled, html }`). When `enabled: true`, the tenant renders Classic for MFA.
+
+To restore Universal Login for a flow, set the relevant toggle to false. The checks below flag any toggles in the Classic state.
+
+If a flow is intentionally kept in Classic, "Brand my tenant" can still apply tenant-wide branding settings (logo, favicon, primary color); those show up on Classic pages too. But the theme and page template will not affect that flow.
+
+## Checks (run in parallel)
+
+1. **Universal Login enabled at tenant level**: `GET /api/v2/tenants/settings` → `flags.universal_login === true`.
+2. **Login and signup experience**: `GET /api/v2/prompts` → `universal_login_experience`. `"new"` means every client gets Universal Login for login/signup; `"classic"` means every client runs Classic.
+3. **Password reset and MFA Classic toggles**: from the tenant settings call, `change_password.enabled` and `guardian_mfa_page.enabled`. Flag if true (that flow is running Classic for the whole tenant).
+4. **Custom domain**: `GET /api/v2/custom-domains`. Flag if empty (page templates cannot apply).
+5. **Theme present**: `GET /api/v2/branding/themes/default`. Flag if 404 (no theme has been applied yet).
+6. **Active flows**: `GET /api/v2/connections`. Determines which login flows actually matter.
+
+## Output format
+
+Structured checklist with pass/fail/warn and a summary of what the theme *will* and *won't* affect:
+
+```text
+Tenant: acme-prod (environment: production)
+
+Universal Login at tenant level              ✓
+New Universal Login experience               ✓
+Current default theme                        ✓ (themeId abc123...)
+Custom domain                                ✓ login.acme.com
+
+Tenant-wide flow toggles:
+  ✓ Login/signup            universal_login_experience: new  → Universal
+  ✓ Password reset          change_password.enabled: false   → Universal
+  ✗ MFA                     guardian_mfa_page.enabled: true  → Classic
+
+Active flows (from connections):
+  ✓ Username-password database: login + signup + password reset enabled
+  ✓ Google social
+  — Enterprise: none
+
+Summary:
+  Theme will apply to login/signup (tenant set to new) and password reset.
+  Theme will NOT apply to MFA (tenant has guardian_mfa_page.enabled: true, so MFA runs Classic for every client).
+  Fix (if desired):
+    PATCH /tenants/settings --data '{"guardian_mfa_page": {"enabled": false}}'
+```
+
+This capability is read-only and does not write to the tenant; skip the "Verify in browser (post-apply)" step from SKILL.md.
+
+---
+
+# Capability 2: Change specific settings
+
+Manual branding update driven by the user's natural-language intent. The user says what they want to change ("make the primary button orange", "change the signup headline to 'Welcome in'", "bump the corner radius to 8px", "use Inter as the font"); the skill resolves that to specific fields across theme / tenant branding settings / page template / custom text, asks a targeted disambiguation question only when the target is genuinely ambiguous, stages the change, and applies once the user is done. No URL extraction or asset parsing.
+
+The user never needs to know the API field names or which surface a setting lives on.
+
+## Flow
+
+1. Load current tenant state once at the start of the session: theme (`GET /branding/themes/default`), tenant branding (`GET /branding`), and (lazily) current page template + custom text when the request targets them. Cache for the session so disambiguation prompts can show current values.
+2. Ask: **"What do you want to change?"**
+3. Parse the user's request and resolve it to one or more specific fields using the **Intent mapping** table below.
+4. Disambiguate only when needed. If the mapped target is unique, skip ahead. If multiple fields are plausible, ask one question and show current values so the user can see what they'd be changing:
+   > "'button color'; which one?
+   > [a] Primary button fill (currently `#533AFD`)
+   > [b] Primary button label/text (currently `#FFFFFF`)
+   > [c] Secondary button border (currently `#CCCCCC`)"
+5. Restate the concrete change in plain language ("change primary button fill from `#533AFD` to `#FF5733`") and confirm.
+6. Stage the change in an in-memory bundle. Do not write to the tenant yet.
+7. Ask **"anything else?"**; loop to step 2 if yes.
+8. Show the consolidated diff of all staged changes vs current tenant state.
+9. Apply as a batch; see **Apply** below.
+
+## Intent mapping
+
+Map freeform phrasing to the underlying surface + field. This is a starting table; cover these cases, then fall back to asking "can you describe what you see today and what you want it to look like?" if nothing matches.
+
+| User says | Likely target |
+|---|---|
+| "logo" | `widget.logo_url` (theme) and `logo_url` (tenant branding). If both are set, ask which; if only one, update that one. Offer to set both if only one is set today |
+| "favicon" | `favicon_url` (tenant branding) |
+| "primary color" / "brand color" | Ask: theme primary button fill, tenant `colors.primary` (used on Classic pages), or both? Default to updating both if the user says "everywhere" |
+| "button color" | Disambiguate fill vs label/text. If the user means a specific button (secondary, tertiary), map to the matching theme field |
+| "page background" / "background color" | `colors.page_background` (solid) or `page_background.background_image_url` (image). Ask if ambiguous |
+| "widget background" / "card background" | `colors.widget_background` |
+| "text color" / "body text" | `colors.body_text`; disambiguate from widget title / input label if needed |
+| "corner radius" / "rounded corners" / "sharper corners" | Ask which element: buttons (`borders.button_border_radius`), inputs (`borders.input_border_radius`), widget (`borders.widget_corner_radius`). If the user says "everywhere", update all three |
+| "font" | `fonts.font_url` + `fonts.reference_text_size` family. Resolve the family name to a Google Fonts URL if possible (see per-surface mechanics) |
+| "headline" / "title on the [login/signup/reset/...] screen" | Custom text: `{prompt}.title` on the specified screen. Confirm the prompt + screen + language |
+| "description" / "subtitle on [screen]" | Custom text: `{prompt}.description` |
+| "button label on [screen]" | Custom text: `{prompt}.buttonText` (or the screen-specific label key) |
+| "error message for X" | Custom text: the specific error key on the relevant prompt. GET the current custom text to find the exact key name |
+| "the template" / "the HTML" / "the Liquid" | Page template (`PUT /branding/templates/universal-login`) |
+
+When the phrasing is close but not exact (e.g., "accent color", "link color", "highlight"), pick the best candidate and restate it in the confirmation step so the user can correct.
+
+## Discoverability
+
+If the user asks "what can I change?" or doesn't know where to start, show the surface list as a prompt, not as a required picker:
+
+- Logo / favicon
+- Colors (buttons, text, backgrounds, links)
+- Fonts
+- Corner radius / border style
+- Page background (color or image)
+- Text on a specific screen (title, description, button labels, error messages)
+- Page template (HTML/Liquid)
+
+The user can still respond in natural language from there.
+
+## Per-surface write mechanics
+
+Once the target is resolved, these are the mechanics for writing each surface. The user does not see these details; they're for this skill's execution.
+
+Before staging any URL-valued field (`logo_url`, `favicon_url`, `font.url`, `widget.logo_url`, `fonts.font_url`, `page_background.background_image_url`), validate the URL resolves using the HEAD request check in the API Reference section below (URL Validation). Block staging for URLs that fail. Skip validation for `cdn.brandfetch.io` URLs.
+
+- **Logo**: Auth0 does not host uploaded assets. Ask the user for an HTTPS URL where the logo is already hosted. For theme logo: GET default theme, replace `widget.logo_url`, PATCH back. For tenant logo: `PATCH /branding` with `logo_url`. If the user only has a file, pause and ask them to host it first (their CDN, an S3 bucket, GitHub raw content, etc.).
+- **Favicon**: URL only, same constraint as logo. `PATCH /branding` with `favicon_url`.
+- **Color**: validate hex. Run a WCAG AA contrast check against the natural counterpart (button vs button-label, body text vs widget background, etc.). If it fails, surface the warning clearly and ask for confirmation before staging. Never block the change; accessibility is the customer's choice.
+- **Font**: URL only. Resolve the family name to a Google Fonts URL if possible. If the family isn't on Google Fonts, ask the user for a reachable WOFF URL; do not silently fall back to a default.
+- **Border radius / style**: plain numeric or enum update on the relevant `borders.*` field.
+- **Page background**: solid color → `colors.page_background`; image → `page_background.background_image_url` (URL only, same asset-hosting constraint as logo). Clear the other if switching modes.
+- **Text on a screen**: GET existing custom text for that prompt + language, merge the user's edit, PUT. Never PUT without merging; PUT replaces the full object for that prompt/language.
+- **Page template**: GET current template, apply the edit, validate `auth0:head` and `auth0:widget` are still present, PUT. Refuse the write if either tag is missing.
+- **Tenant branding setting**: `PATCH /branding` with just the changed keys.
+
+## Apply
+
+After the user finishes staging changes, batch the writes by surface:
+
+1. All theme field changes → one `GET /branding/themes/default` + one `PATCH /branding/themes/{themeId}` with the merged full object.
+2. All tenant-level branding setting changes → one `PATCH /api/v2/branding` with the merged body.
+3. Page template change (if any) → one `PUT /api/v2/branding/templates/universal-login` after verifying `auth0:head` and `auth0:widget` are present.
+4. Per-screen text changes → one `PUT /api/v2/prompts/{prompt}/custom-text/{lang}` per affected prompt/language (GET-merge-PUT; do not overwrite other screens in that prompt).
+
+Before writing, show the consolidated diff **and the target tenant name** (per the "CLI Tenant Context" prerequisite in SKILL.md). Require explicit confirmation for the whole batch. Auth0 does not retain prior versions, so there is no automatic rollback; suggest the user export current state locally first if they want a backup.
+
+After the batch completes, run the "Verify in browser (post-apply)" step from SKILL.md.
+
+## Guardrails
+
+- WCAG AA contrast check for any color change with a visible counterpart. Always fail-warn (never fail-block), including in production. If the color fails the contrast check, show the warning and require confirmation before staging; do not override the user's choice.
+- Warn if the new font isn't on a known CDN.
+- Validate page template still has `auth0:head` and `auth0:widget` after edit; refuse the PUT if either is missing. (Page-template validity IS a fail-block because the page won't render otherwise; WCAG is not.)
+
+---
+
+# Capability 4: Rollback to Auth0 defaults
+
+Clear one or more branding surfaces and restore Auth0's defaults. Reset is per-surface, not all-or-nothing. Destructive; always confirm before writing.
+
+## Scope pre-check (before asking anything)
+
+If the user selected **Theme** or **Page template** to reset, those operations require the `delete:branding` scope. Check for it immediately — before backup, before confirm — by attempting a benign scoped call:
+
+```bash
+auth0 api get "branding/themes/default"
+```
+
+- If the call returns a theme: a `DELETE` will be needed. Verify scope by making a deliberate no-op `DELETE` attempt on a known-nonexistent themeId (e.g., `branding/themes/scope-check-probe`) — a `403` with `"access token lacks scope: delete:branding"` confirms the scope is missing; a `404` ("not found") confirms the scope is present.
+- If the call returns 404: no theme to delete; scope check is moot for theme. Repeat the same probe for page template if that surface was selected.
+
+> **Why probe instead of decoding the JWT:** Management API tokens issued to the CLI aren't always JWTs the skill can decode locally (opaque tokens are valid too), and scope claims in a decoded JWT can lag the tenant's actual grants. The probe tests the live gate. Caveats: the 403 check matches on error message text; if Auth0 ever changes the wording, update the substring here. The probe id (`scope-check-probe`) is reserved-looking on purpose, but if a real theme with that id ever exists the probe will succeed and the scope check will falsely report "present" — swap to a random UUID if that becomes a concern.
+
+**If the scope is missing**, surface a clear warning before doing anything else:
+
+> "Your current token is missing the `delete:branding` scope, which is required to delete the theme/page template. To avoid a mid-run failure, re-authenticate first:
+>
+> `auth0 login --scopes delete:branding`
+>
+> Run that command (prefix with `!` in Claude Code), then re-invoke this capability."
+
+Stop and do not proceed until the scope issue is resolved. Do not fall through to backup or confirm steps with a known-failing scope.
+
+## Ask what to reset
+
+Use two sequential `AskUserQuestion` calls. Do not render a text checklist.
+
+**Call 1 — surfaces to reset** (`multiSelect: true`):
+- `question`: "Which pieces should I reset to Auth0 defaults?"
+- `header`: "Reset"
+- options:
+
+| label | description |
+|---|---|
+| Tenant branding settings | logo, favicon, primary color, page background |
+| Theme | colors, fonts, borders, widget layout, page backgrounds |
+| Page template | HTML/Liquid |
+| Custom text on prompts | I'll ask which prompts to clear after you confirm |
+
+**Call 2 — backup** (single select):
+- `question`: "Save a backup of the selected surfaces before resetting?"
+- `header`: "Backup"
+- options:
+
+| label | description |
+|---|---|
+| Yes, save a backup first (Recommended) | I'll write current state to a local JSON file you can restore from manually |
+| No, reset without a backup | One-way; Auth0 does not retain prior versions |
+
+For custom text, after the user picks the surfaces, list prompts that currently have overrides and ask which to clear (or "all"). Show the locales those overrides cover so the user knows the scope.
+
+Reset is destructive and one-way. Auth0 does not maintain prior versions of themes, templates, or custom text, so the "save to a file" option is the only way to keep a copy of current state before reset.
+
+## Confirm
+
+Show the concrete plan, including the target tenant (per the "CLI Tenant Context" prerequisite in SKILL.md):
+
+```text
+Target tenant: acme-prod  (active in the Auth0 CLI)
+
+I'll reset the following:
+  • Theme (current themeId abc123 → deleted; Universal Login will fall back to Auth0's defaults)
+  • Custom text on prompts: login, signup-id (locales: en, fr)
+
+Tenant branding settings, page template, and other prompts will be left alone.
+
+Backup: I'll save the current state of the selected surfaces to:
+  ~/auth0-branding-backup-<tenant>-<YYYY-MM-DD_HHMMSS>.json
+(Override the path or cancel the backup?)
+
+Proceed?
+  [y] Yes
+  [n] Cancel
+```
+
+If the user opted in to save-to-file, ask for a path or accept the default (`~/auth0-branding-backup-<tenant>-<timestamp>.json`). Confirm the path is writable before proceeding. If the user skipped the backup option, omit that block and surface a brief warning that this is one-way.
+
+In production environments, require explicit confirmation before any write.
+
+## Execute (only for surfaces the user selected)
+
+0. **Save backup (if opted in)**: before any writes, fetch the current state of every selected surface and serialize to a single JSON file at the path the user confirmed.
+   - Theme: `GET /branding/themes/default` (full theme object)
+   - Page template: `GET /branding/templates/universal-login`
+   - Custom text: for each selected prompt + locale, `GET /prompts/{prompt}/custom-text/{lang}`
+   - Tenant branding: `GET /branding`
+   - Write the combined object as pretty-printed JSON with a top-level `tenant`, `timestamp`, and `surfaces` map. Refuse to proceed with reset if the write fails.
+1. **Theme**: `DELETE /api/v2/branding/themes/{themeId}`. After delete, `GET /branding/themes/default` returns 404 and Universal Login renders Auth0's built-in defaults.
+2. **Page template**: `DELETE /api/v2/branding/templates/universal-login`.
+3. **Custom text**: for each selected prompt + locale, `PUT /api/v2/prompts/{prompt}/custom-text/{lang}` with `{}` (empty object) to clear overrides.
+4. **Tenant branding settings**: `PATCH /api/v2/branding` with nulls/defaults for only the fields reset (don't clobber anything the user didn't select).
+
+Report what was reset, what was left alone, and (if saved) the full path to the backup file so the user can find it later.
+
+After the report, run the "Verify in browser (post-apply)" step from SKILL.md. In the rollback case, the browser should render Auth0 built-in defaults; that's the verification.
+
+---
+
+# Capability 3: Match my brand voice
+
+Rewrite Universal Login text to match a source's voice. Does not touch colors, layout, or logo.
+
+## Ask for the source
+
+Free-text prompt. Accept whatever the user gives and route based on what it is:
+
+> What should the voice match? Paste a website URL, sample copy, or describe the voice (e.g., "casual and direct", "formal and corporate").
+
+Parse the reply:
+
+- **URL** (http/https) → sample the copy and classify the voice. Run Stage 4 of the "Brand my tenant" pipeline (voice extraction) without the rest; see the Brand My Tenant section.
+- **Pasted sample text** → classify directly.
+- **A voice descriptor** (short phrase, no URL, no paragraph of sample copy) → use as-is.
+- **Ambiguous** (e.g., a URL plus a descriptor, or text that could be either a sample or a descriptor) → ask one short clarifying question in free text; don't kick back to a picker.
+
+## Pick which screens to rewrite
+
+Universal Login has 80+ screens. Most tenants use under 10. Ask the user in one free-text line how they want to choose:
+
+> Which prompts do you want rewritten?
+>   - **List them yourself** (e.g. `"login and signup"`, or specific prompt names like `login-id`, `reset-password`)
+>   - **"detect"** — I'll make 4–5 API calls to infer active flows from connections, prompts, MFA, and organizations settings
+>   - **"pick"** — I'll show a multi-select with categories (Login, Signup, Passwordless, Password reset, Passkeys, MFA, Organizations, Other)
+
+Parse the reply:
+
+- **Listed explicitly** (`"login and signup"`, `login-id, signup-password`, category names) → map to (prompt, screen) pairs via the screens map below and skip straight to locale handling. Only fall back to the picker if the listing is ambiguous.
+- **"detect"** → run detection (next section), then render the pre-filled picker for confirmation.
+- **"pick"** → render `AskUserQuestion` with `multiSelect: true` and no pre-checks. This is the only path that forces the picker.
+
+Category list when the picker is rendered (`AskUserQuestion` options):
+
+| label | description |
+|---|---|
+| Login | login, identifier-first entry, identifier challenges |
+| Signup | signup, signup-id, signup-password |
+| Passwordless | email code/link, SMS OTP, email OTP challenge |
+| Password reset | request, reset, confirmation, and reset-time MFA challenges |
+| Passkeys | enrollment screens |
+| MFA | I'll ask which factors you use after you select this |
+| Organizations (B2B) | org picker, org selection, invitation accept |
+| Other | consent, logout, device flow, CAPTCHA, brute force, etc. |
+
+Expansion rules (apply after picker submit, or when parsing a listed reply):
+
+- If **MFA** is selected, show a sub-picker for factors: OTP (authenticator apps), SMS, push, email, phone, voice, WebAuthn, recovery code. Also include the MFA "landing" screens (`mfa-begin-enroll-options`, `mfa-login-options`, etc.) as a default. Only rewrite sub-screens for factors the user confirms are enabled.
+- If **Other** is selected, show the full list of long-tail screens from the screens map below so they can tick specific ones.
+- For each selected category, expand to the set of (prompt, screen) pairs via the screens map below.
+
+**New screens:** The screens catalog below is a canonical starting point, not an authoritative registry. Auth0 adds screens over time. If the user mentions a screen name the skill doesn't recognize, accept it: probe `GET /api/v2/prompts/{prompt}/custom-text/{lang}` for the prompt they expect it under, or ask the user to confirm the prompt name. The skill should not refuse a rewrite because the screen isn't in the catalog. After a successful rewrite of an unknown screen, offer to add it to the screens catalog so the user doesn't have to re-enter it next time; see "Learn new screens" below.
+
+## Help me figure it out (optional detection)
+
+Only run when the user said `"detect"` in reply to the "list / detect / pick" ask above. Slower (4–5 API calls) and still surfaces the picker for confirmation. The goal is to pre-fill the picker, not to bypass it.
+
+**What to fetch:**
+
+1. `GET /api/v2/connections` — enabled connections and their `strategy` + `options.authentication_methods`.
+2. `GET /api/v2/prompts` — tenant-wide login settings (`universal_login_experience`, `identifier_first`, `webauthn_platform_first_factor`).
+3. `GET /api/v2/guardian/factors` — which MFA factors are enabled.
+4. `GET /api/v2/organizations` — does the tenant use organizations.
+
+**How to map to the categories above:**
+
+- **Login**: always pre-check. Everyone hits login screens. For `auth0` (database) connections, check `options.authentication_methods.password.enabled`. Social strategies (`google-oauth2`, `facebook`, `apple`, etc.) and enterprise strategies (`samlp`, `oidc`, `waad`, `okta`, etc.) also land on the login screen via social/enterprise buttons. If `/prompts.identifier_first === true`, prefer the split `login-id` + `login-password` screens over the combined `login`.
+- **Signup**: pre-check if `options.authentication_methods.password.signup_behavior !== "disallow"` and `options.disable_signup !== true` on at least one `auth0` connection.
+- **Passwordless**: pre-check if any `email` or `sms` strategy connection is enabled, OR if an `auth0` (database) connection has passwordless entries in `options.authentication_methods`. Auth0 is rolling out passwordless on database connections, so read the `authentication_methods` object directly (don't hardcode expected field names); the skill should pick up email-OTP and SMS-OTP variants as they appear.
+- **Password reset**: pre-check if `options.authentication_methods.password.enabled === true` on any database connection and password reset isn't explicitly disabled.
+- **Passkeys**: pre-check if `options.authentication_methods.passkey.enabled === true` on any database connection.
+- **MFA**: pre-check if `GET /guardian/factors` shows any factor with `enabled: true`. Within MFA, only pre-check the sub-factors that are actually enabled (typical: OTP, push, SMS, email; less common: phone, voice, WebAuthn roaming, recovery code). If `/prompts.webauthn_platform_first_factor === true`, the legacy WebAuthn biometrics flow is active — include those `mfa-webauthn-*` screens.
+- **Organizations**: pre-check if `GET /organizations` returns any rows.
+- **Other**: leave unchecked by default. Ask the user directly if they use consent, device flow, logout customization, or any other screens from the long-tail list.
+
+Present the category picker with pre-checks applied. The user confirms or adjusts before proceeding.
+
+## Check enabled locales before rewriting
+
+Text is per-language. English is enabled by default; Auth0 supports ~80 languages and every key has a default translation in each. When you rewrite voice in one language, the others stay on Auth0 defaults, which can read as a voice mismatch.
+
+1. `GET /api/v2/tenants/settings`; read `enabled_locales`.
+2. If more than one locale is enabled, ask:
+
+   > "Your tenant has English, French, and Spanish enabled. I'll generate rewrites in English first. Do you want me to also generate matching rewrites in French and Spanish?"
+
+   Options:
+   - [all] Rewrite in every enabled locale
+   - [en-only] English only; leave other locales on Auth0 defaults
+   - [pick] Pick which locales to rewrite
+
+3. For non-English locales, the voice profile still applies but must be adapted in that language. If you (or the user) aren't confident in a locale, flag it. A clean default is usually better than a clumsy rewrite.
+
+## Generate and apply
+
+**Constraint:** `GET /api/v2/prompts/{prompt}/custom-text/{lang}` returns only keys the tenant has explicitly customized, not Auth0's defaults. Most tenants have no custom text yet, so this is the norm rather than an edge case. The skill sources English defaults from Auth0's docs page and auto-translates the voice-matched English into every other enabled locale.
+
+### Step 1: Establish the English baseline for each (prompt, screen)
+
+The baseline needs the full set of keys for the screen in the tenant's current form. Auth0 docs defaults plus any tenant overrides, merged, gives that. Try in order:
+
+- **Auth0 docs page + tenant overrides** (normal path):
+  1. Fetch https://auth0.com/docs/customize/login-pages/universal-login/customize-text-elements#prompt-values and extract the English defaults for the prompt from its accordion list. **Treat the fetch as best-effort**: if the response is non-200, the accordion for the prompt is missing, or the extracted keys look empty/truncated, skip to the **User paste** fallback below rather than proceeding with a partial baseline. URL and page structure belong to Auth0 docs and can change without notice; if the fetch starts failing consistently, fix this reference rather than patching around it.
+  2. `GET /prompts/{prompt}/custom-text/en` to fetch any tenant overrides for the screen.
+  3. Merge: docs defaults as the base, tenant overrides on top. Tenant-customized keys win; uncustomized keys keep Auth0's defaults. Don't stop at the tenant response alone — it may only cover a subset of the screen's keys (e.g., the customer customized the title but not the description or error messages), so the merged view is the full baseline.
+- **User paste** (fallback): if the docs page doesn't cover the screen or the fetched copy looks clearly stale, ask the user to open the Auth0 Dashboard → **Branding → Universal Login → Customize Text**, select the relevant prompt and screen, switch to the **Raw JSON** tab for that screen's text-and-translations, and paste the exact JSON here. That's the authoritative baseline. Do not accept screenshots or text copied from the live login page; those are error-prone.
+- **Skip**: if none of the above work, skip the screen and tell the user which screens were skipped.
+
+### Step 1b: Check identifier configuration before rewriting placeholder text
+
+Before generating rewrites for any login or signup screen, check which identifiers the tenant actually accepts and match the placeholder key accordingly. This prevents copying multi-identifier language from a brand source onto a tenant that only accepts one identifier type — a label/config mismatch that would mislead users.
+
+**How to check:** inspect `GET /api/v2/connections` results already fetched in detection (or fetch now). For each `auth0` (database) connection, read two separate fields — they answer different questions:
+
+- **Identifier type** (what the user types to identify themselves): read `options.attributes`. The three possible keys are `email`, `phone_number`, and `username` — check which have `identifier.active: true`. If `options.attributes` is absent or null, the connection is a **legacy connection**: its default identifier is email, and `options.requires_username: true` adds username as a second identifier on top of email (it does not replace email).
+- **Passkey enablement** (used during detection, not placeholder selection): read `options.authentication_methods.passkey.enabled`.
+
+Do not use `authentication_methods` to determine identifier type — instead, use `options.attributes` (or, for legacy connections, the email default plus `options.requires_username`) to determine what the user enters. `authentication_methods` only describes authentication methods (password, passkey), not what the user enters as their identifier.
+
+**Key selection rules — modern connections** (`options.attributes` is present):
+
+| Active identifiers (`identifier.active: true`) | Correct placeholder key | Default text |
+|---|---|---|
+| `email` only | `emailPlaceholder` | "Email address" |
+| `phone_number` only | `phonePlaceholder` | "Phone number" |
+| `username` only | `usernameOnlyPlaceholder` | "Username" |
+| `email` + `phone_number` | `phoneOrEmailPlaceholder` | "Phone number or Email address" |
+| `email` + `username` | `usernameOrEmailPlaceholder` | "Username or Email address" |
+| `phone_number` + `username` | `phoneOrUsernamePlaceholder` | "Phone Number or Username" |
+| `email` + `phone_number` + `username` | `phoneOrUsernameOrEmailPlaceholder` | "Phone or Username or Email" |
+
+**Key selection rules — legacy connections** (`options.attributes` is absent or null):
+
+| `options.requires_username` | Active identifiers | Correct placeholder key | Default text |
+|---|---|---|---|
+| `false` or null | email only | `emailPlaceholder` | "Email address" |
+| `true` | email + username | `usernamePlaceholder` | "Username or email address" |
+
+**When the source brand uses multi-identifier language but the tenant doesn't:** flag it explicitly before showing the rewrite proposal. Example:
+
+> "{brand} uses 'Email or mobile number' because they accept both identifiers. Your tenant only has email enabled, so I'll keep the email placeholder as-is. If you enable phone as an identifier later, set `emailPhonePlaceholder` at that point — don't change `emailPlaceholder` to reference phone now."
+
+Do not silently copy multi-identifier phrasing into a single-identifier placeholder key. The label would be misleading even if the key accepts it.
+
+### Step 2: Generate the English rewrite
+
+Produce voice-matched English copy for every key in the baseline. For each key, compare the proposed rewrite against the Auth0 default value from the docs page (`https://auth0.com/docs/customize/login-pages/universal-login/customize-text-elements`) — the per-screen tables on that page list the default text for every key. If the proposed rewrite is identical to the Auth0 default, mark it as **no change** and exclude it from the PUT. There is no point overwriting a key with the value it already has.
+
+Show side-by-side with the baseline; the user approves, edits inline, or skips. The user can also correct a baseline that looked off (by pasting current text) at any point.
+
+### Step 3: Translate into every other selected locale
+
+For each non-English locale the user selected:
+
+- **Tenant override**: if `GET /prompts/{prompt}/custom-text/<locale>` returns keys for this screen, use those as the baseline and rewrite in-voice in that language.
+- **Otherwise**: translate the approved English voice-matched rewrite into the locale. Preserve the voice intent from the English rewrite rather than falling back to Auth0's neutral default for that language.
+
+Show each locale's proposed text so the user can spot-check and edit any translation that looks off. Don't require the user to paste non-English source copy; translation from the voice-matched English is the default path.
+
+### Step 4: Apply
+
+Before writing, show the target tenant name and the prompt/locale pairs about to be updated, and get explicit confirmation (per the "CLI Tenant Context" prerequisite in SKILL.md).
+
+Batch by prompt: one `PUT /api/v2/prompts/{prompt}/custom-text/{lang}` per prompt-locale pair, with approved new keys merged across all screens under that prompt and any existing overrides preserved.
+
+Before writing, strip any key whose approved value is identical to the Auth0 default for that key. Comparison is an **exact byte-for-byte string match** after trimming trailing whitespace/newlines — no case folding, no HTML-entity decoding, no whitespace collapsing inside the string. If the approved value differs only in a trailing newline or leading/trailing spaces, treat it as identical and strip it. Any other difference (casing, punctuation, HTML entities, internal whitespace) is a genuine override and must be written. Only include keys that are genuinely different from the default — sending a default value creates a stored override that has no effect but adds noise and makes future resets less clean.
+
+Never PUT without merging; PUT replaces the full object for that prompt/lang. The custom-text API is per-prompt, not per-screen, so screens under the same prompt share one PUT call.
+
+**Rate limits.** A multi-prompt, multi-locale rewrite can produce 20+ PUTs in quick succession. The Management API's default per-tenant write budget is a few hundred requests per minute, but concurrent writes are the real risk: run PUTs **sequentially**, not in parallel. If the API returns **429 Too Many Requests**, back off and retry the failed PUT only — don't re-run the batch. Use exponential backoff: wait 5s, 10s, 20s, 30s, 60s; stop after five attempts and surface the failed prompt/locale pair to the user. Honor the `Retry-After` response header if present (seconds to wait before the next attempt). Successful PUTs don't need to be retried; the per-prompt design means each PUT is independent.
+
+After all PUTs succeed, run the "Verify in browser (post-apply)" step from SKILL.md.
+
+## Learn new screens
+
+If the run included a screen that was not in the screens catalog below (because Auth0 shipped a new one, or the user named a screen the catalog didn't cover) AND the PUT succeeded, offer to persist it so the user doesn't have to re-enter it next time:
+
+```text
+I rewrote `<screen-name>` under the `<prompt-name>` prompt. It wasn't in my
+reference list. Add it to screens.md so I'll remember it next time?
+
+  [y] Yes, add it under <inferred-category>
+  [c] Yes, but put it under a different category (I'll pick)
+  [n] Skip; don't save
+```
+
+Infer the default category from the prompt name where possible:
+- `mfa-*` → **MFA**
+- `reset-password*` → **Password reset**
+- `login-passwordless*`, `*-otp-challenge` → **Passwordless**
+- `organizations`, `invitation` → **Organizations (B2B)**
+- `passkey*` → **Passkeys**
+- `login*`, `*identifier-challenge`, `*identifier-enrollment` → **Login**
+- `signup*` → **Signup**
+- anything else → **Other**
+
+If the user accepts, append a new row to the matching category's table in the screens catalog below with the `(prompt, screen)` pair. Only persist after a successful PUT so a failed or canceled rewrite doesn't pollute the catalog. If multiple new screens came up in the same run, batch the confirmations into one question listing all of them.
+
+The reference map grows with real usage this way; users only name a new screen once.
diff --git a/main/.mintlify/skills/auth0/references/feature-custom-domains/index.md b/main/.mintlify/skills/auth0/references/feature-custom-domains/index.md
new file mode 100644
index 0000000000..33abc26767
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/feature-custom-domains/index.md
@@ -0,0 +1,2056 @@
+
+# Auth0 Custom Domains
+
+Drive Auth0 custom-domain work end-to-end: Auth0 Management API, DNS provider, verification polling, and the configuration that stitches everything together. Detects the user's DNS provider (Cloudflare, Route 53, Azure DNS, or other) and automates record creation when the provider supports it.
+
+## Overview
+
+This skill is **capability-based**, not step-based. It groups the work a user might want to do into five distinct capabilities (setup, troubleshoot, manage, remove, health check), each with its own flow in a dedicated reference file. The main SKILL.md acts as a lobby: it holds the capabilities table, key concepts, prerequisites, and common mistakes that apply across all flows. When a user invokes the skill, pick the matching capability from the table, load its reference file, and follow that flow.
+
+The capability design matches how users actually come to Auth0 custom domain work: "set one up," "mine is broken," "change something," "remove one," or "is my setup still working?" Each intent maps to a distinct flow with its own safety checks and hand-offs.
+
+## Interaction style
+
+Ask questions as plain conversational text. Never use structured UI widgets (e.g., AskUserQuestion) — instead, ask as plain conversational text — except for a single yes/no confirmation immediately before a destructive or irreversible action (create, PATCH, delete). For everything else:
+
+- **Capability routing**: present a numbered list and wait for the user to reply
+- **Input gathering**: ask one focused question at a time; wait for a response before asking the next
+- **Free-form values** (hostnames, domain names, etc.): just ask directly — don't wrap them in a widget that forces a click before typing
+
+Example of the right pattern for capability routing:
+
+```text
+What do you want to do?
+
+1. Set up a custom domain
+2. Troubleshoot verification
+3. Manage an existing domain
+4. Remove a domain
+5. Check domain health (read-only, safe starting point)
+```
+
+Example of the right pattern for a single input:
+
+```text
+What's the hostname you want to set up? (e.g., login.example.com)
+```
+
+## Error-code triage — CHECK THIS FIRST
+
+If the user's message is primarily about an HTTP error code from the Management API (e.g., "I got a 403", "why is this returning 409?", a pasted error body, a log entry with a status code), **answer from this table first.** Do not default to general Auth0 knowledge — it leads to wrong advice on the Free-tier 403 case in particular. Only after the error-code answer, offer to route into the matching capability if the user wants to continue (e.g., "want me to walk through Set up with that fix in place?").
+
+| Status and context | Correct diagnosis and fix |
+|---|---|
+| **403** on `POST /custom-domains` (Free tier) | **Not a plan-tier problem.** Custom domains are available on **all plans including Free** (confirmed in Auth0 docs: *"To set up a free custom domain, Auth0 tenants must have a valid credit card on file for verification purposes and fraud prevention. The credit card will not be charged."*). Fix at **Dashboard → Tenant Settings → Billing** by adding a card. **Do NOT suggest a plan upgrade.** |
+| **403** on `POST /custom-domains` with `type: self_managed_certs` | This *is* a plan issue. Self-managed certs are Enterprise-only. Either downgrade to `type: auth0_managed_certs` (works on all plans) or upgrade to Enterprise. |
+| **409** on `POST /custom-domains` | Domain already exists on this tenant or another. Run `auth0 domains list` to check; if on another tenant the user owns, delete it there first. Do not retry a fresh create. |
+| **400** on `PATCH /custom-domains/{id}` with `type` in body | `type` is fixed at create time and rejected by PATCH. Route to delete (capability 4) + recreate (capability 1). Warn about auth downtime during the cutover. |
+| **400** with `operation_not_supported` on `relying_party_identifier` | Feature-flag gate on the tenant. Retry without `relying_party_identifier` and ask Auth0 support to enable the flag. |
+| **404** on any custom-domain endpoint | Wrong `custom_domain_id`, or wrong tenant. Verify with `auth0 tenants list` + `auth0 domains list`. |
+| **429** | Rate limited. Back off; the skill's verify-poll backoff pattern (5s, 10s, 20s, 30s, 60s) avoids this. |
+
+Full error-code reference with all cases and resolutions: see the API Reference section below (Error Codes).
+
+## Capabilities
+
+When this skill is invoked and the user is NOT asking about an error code, ask the user which capability they want using a plain numbered list (see Interaction style above). Route to **Check domain health** first when the user reports a problem without a specific known cause, or when they're unsure which capability they need; it's the safe, read-only starter that will point them to the right follow-up.
+
+| # | Capability | What it does |
+|---|---|---|
+| 1 | **Set up a custom domain** | End-to-end: create the domain in Auth0, detect the DNS provider, write the CNAME record (automated on Cloudflare / Route 53 / Azure; guided on other providers), verify ownership, and report what to update in the user's apps. Handles first-time setup and adding to MCD. (guidance inline below) |
+| 2 | **Troubleshoot verification** | Domain stuck in `pending_verification` or verification failing. Diagnostic ladder: compare DNS to expected, check for proxies / CNAME flattening / conflicting records / propagation / private-zone issues, then retry. (guidance inline below) |
+| 3 | **Manage existing domains** | Surgical edits on already-configured domains: set or change the default (for MCD), update TLS policy, configure the custom client IP header, set the relying party identifier for passkeys, manage per-domain metadata (up to 10 key-value pairs readable from Actions), list domains and show status. Intent-driven. Certificate type is fixed at create time; PATCH rejects `type` changes. (guidance inline below) |
+| 4 | **Remove a custom domain** | Delete a domain safely: warn if it's the default, surface dependent applications, delete in Auth0, clean up the CNAME in DNS. (guidance inline below) |
+| 5 | **Check domain health** | Read-only: list all custom domains, check DNS records match expected values, surface default-domain config, flag anything needing attention. Safe starter capability. (guidance inline below) |
+
+Pick a capability, then follow the flow in its reference file. The **Prerequisites** and **Key Concepts** sections below apply across all capabilities.
+
+## Key Concepts
+
+| Concept | Description |
+|---|---|
+| CNAME Record | DNS record pointing your custom domain to Auth0's edge (e.g., `{tenant}.edge.tenants.auth0.com`). Must stay in DNS permanently for certificate renewal |
+| Auth0-Managed Certificate | Auth0 provisions and auto-renews TLS certs every ~3 months. Default and recommended. Type is fixed at create time and cannot be changed via PATCH |
+| Self-Managed Certificate | TLS terminates at a reverse proxy (Cloudflare, CloudFront, Azure Front Door, or GCP LB). Enterprise only; verification uses TXT instead of CNAME. Type is fixed at create time and cannot be changed via PATCH; to change, delete and recreate the domain |
+| NS Detection | Looking up the root domain's nameservers to identify the DNS provider and route to the correct automation tier |
+| Multiple Custom Domains (MCD) | Enterprise feature; up to 20 domains per tenant for multi-brand or multi-region |
+| Default Custom Domain | When MCD is configured, the domain used when a Management API call doesn't send the `auth0-custom-domain` header |
+| Relying Party Identifier (RPID) | Per-domain `relying_party_identifier` that decouples the custom domain hostname from the passkey `rpId`. Set at create or via PATCH. Lets you serve auth at `login.example.com` while passkeys bind to `example.com` for cross-surface reuse |
+| TLS Policy | `tls_policy` on the domain controls minimum TLS version / cipher posture for Auth0-managed certs. Default `recommended`. Set at create or via PATCH |
+| Custom Client IP Header | `custom_client_ip_header` tells Auth0 which request header carries the real client IP when traffic passes through a reverse proxy. Valid values: `true-client-ip`, `cf-connecting-ip`, `x-forwarded-for`, `x-azure-clientip`. Set at create or via PATCH |
+| Domain Metadata | Up to 10 custom key-value pairs attached to a custom domain (keys and values ≤ 255 chars). Read from Actions via `event.custom_domain.domain_metadata` for per-domain logic (region, brand, env tagging) |
+
+Full schema and token / `iss` behavior live in the Advanced Topics section below.
+
+## Prerequisites
+
+These apply to any capability that writes to the tenant. **Check domain health** is read-only and can be run first to verify these.
+
+### Auth0 Management API access
+
+All capabilities use the Management API. Either:
+- The Auth0 CLI (`auth0 ...`) authenticated to the target tenant (`auth0 tenants use <name>`), or
+- A Machine-to-Machine application with the scopes in the API Reference section below.
+
+**Check the active tenant immediately before the first Auth0 CLI command in a capability, not at skill invocation.** Do not check the tenant before the user has chosen a capability. If a capability uses only non-CLI tools (e.g., DNS lookups, Cloudflare MCP, direct Management API calls via curl), skip the tenant check entirely.
+
+When the chosen capability does use the Auth0 CLI, run this before the first CLI command:
+
+```bash
+auth0 tenants list
+```
+
+Look for the row marked as active (or check the `active` field in the JSON output). Show the active tenant to the user and ask them to confirm it is the intended target. If it's wrong, stop and have the user run:
+
+```bash
+auth0 tenants use <tenant-name>
+```
+
+Then re-confirm before proceeding. For mutating calls (create, PATCH, delete), require explicit confirmation. For read-only CLI flows, surfacing the tenant name (and naming it in the output report) is enough — still never assume the active tenant is correct based on conversational context alone.
+
+### DNS provider access (for Set up, Troubleshoot, and Remove)
+
+**Set up a custom domain** writes a CNAME. **Remove a custom domain** deletes one. **Troubleshoot verification** may suggest a fix that requires a DNS edit. What the skill needs depends on the provider tier:
+
+- **Tier 1 Cloudflare**: Cloudflare MCP connected. If not, skill prompts the user to run `claude mcp add --transport http cloudflare https://mcp.cloudflare.com/mcp` and authorize in the browser.
+- **Tier 2 AWS Route 53**: AWS credentials configured (env vars, shared config, or SSO session). Verified with `aws sts get-caller-identity`.
+- **Tier 3 Azure DNS**: Azure CLI signed in. Verified with `az account show`.
+- **Tier 4 other**: no programmatic access; user manually adds the record in their provider's dashboard.
+
+**Plan requirements for automation**: None of the three automated tiers require a paid plan on the DNS provider side. Cloudflare DNS record CRUD via the MCP works on the Free plan (Free zones created after Sept 2024 cap at 200 DNS records per zone; Auth0's CNAME counts as one). Route 53 is pay-per-use (~$0.50/hosted zone/month + query costs, not in AWS free tier). Azure DNS is subscription-based with no tier gating; the signed-in identity needs the DNS Zone Contributor role. Full detail per tier in the DNS Provider Playbook section below.
+
+### Credit card on file (Free-tier tenants)
+
+Custom domains are available on **all plan tiers including Free**. Free tenants need a credit card on file for identity verification (card is not charged). Without one, `POST /custom-domains` returns 403. Fix at **Dashboard → Tenant Settings → Billing** (or the Teams section for Teams-managed tenants).
+
+Surface this as the likely cause on any 403 rather than suggesting a plan upgrade.
+
+## Common Mistakes
+
+Quick index; each entry references the canonical treatment in the relevant section below.
+
+| Mistake | See |
+|---|---|
+| Assuming a 403 on create means plan upgrade | API Reference section: Error Codes |
+| Removing the CNAME after verification (breaks cert renewal) | Check Domain Health section: interpreting results |
+| Using a subdomain with passkeys without setting `relying_party_identifier` | Manage Existing Domains section: Set the relying party identifier |
+| Trying to change certificate type via PATCH | Manage Existing Domains section: scope note |
+| Enabling DNS proxy on the CNAME (Cloudflare orange cloud) | Troubleshoot section: proxy check |
+| Enabling CNAME flattening on the zone | Troubleshoot section: flattening check |
+| Deleting and recreating to "unstick" verification | Troubleshoot section: what not to do |
+| Not updating SDK `domain` / `issuerBaseURL` after verification | Set Up section: report next steps |
+| Calling Management API via tenant domain under MCD | Advanced Topics section: the auth0-custom-domain header |
+
+## Related capabilities
+
+- Customizing Universal Login appearance → branding (feature:branding); page templates require a verified custom domain
+- Organization-specific branding for B2B multi-tenancy → Organizations (feature:organizations)
+
+## References
+
+This file contains all custom domain guidance inline. Sections: Setup · Troubleshoot · Manage · Remove · Health Check · DNS Providers (Cloudflare, Route 53, Azure, Manual) · API Reference · Examples.
+
+## External Docs
+
+- [Custom Domains Overview](https://auth0.com/docs/customize/custom-domains)
+- [Auth0-Managed Certificates](https://auth0.com/docs/customize/custom-domains/auth0-managed-certificates)
+- [Self-Managed Certificates](https://auth0.com/docs/customize/custom-domains/self-managed-certificates)
+- [Multiple Custom Domains](https://auth0.com/docs/customize/custom-domains/multiple-custom-domains)
+- [Default Custom Domain](https://auth0.com/docs/customize/custom-domains/multiple-custom-domains/default-domain)
+- [Configure Features to Use Custom Domains](https://auth0.com/docs/customize/custom-domains/configure-features-to-use-custom-domains)
+- [Troubleshoot Custom Domains](https://auth0.com/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains)
+- [Cloudflare MCP Server](https://developers.cloudflare.com/agents/model-context-protocol/mcp-servers-for-cloudflare/)
+
+---
+
+# Auth0 Custom Domains: API Reference
+
+## Management API Endpoints
+
+| Method | Path | Description | Scopes |
+|--------|------|-------------|--------|
+| POST | `/api/v2/custom-domains` | Create a new custom domain | `create:custom_domains` |
+| GET | `/api/v2/custom-domains` | List all custom domains on the tenant | `read:custom_domains` |
+| GET | `/api/v2/custom-domains/<domainId>` | Get a single domain's configuration and status | `read:custom_domains` |
+| PATCH | `/api/v2/custom-domains/<domainId>` | Update `tls_policy`, `custom_client_ip_header`, `relying_party_identifier`, or `domain_metadata`. `type` is NOT patchable | `update:custom_domains` |
+| DELETE | `/api/v2/custom-domains/<domainId>` | Delete a custom domain | `delete:custom_domains` |
+| POST | `/api/v2/custom-domains/<domainId>/verify` | Trigger the verification process | `create:custom_domains` |
+| GET | `/api/v2/custom-domains/default` | Get the current default custom domain | `read:custom_domains` |
+| PATCH | `/api/v2/custom-domains/default` | Set the default custom domain; body: `{"domain": "login.example.com"}` | `update:custom_domains` |
+
+## CLI Commands
+
+```bash
+# Create custom domain (interactive)
+auth0 domains create
+
+# List all custom domains
+auth0 domains list
+
+# Show domain details
+auth0 domains show <domainId>
+
+# Verify domain ownership
+auth0 domains verify <domainId>
+
+# Update domain configuration
+auth0 domains update <domainId>
+
+# Delete a custom domain (use --force to skip the CLI's interactive prompt)
+auth0 domains delete <domainId> --force
+
+# Set the default custom domain (no dedicated CLI subcommand; use API passthrough)
+auth0 api patch "custom-domains/default" --data '{"domain": "<domain>"}'
+
+# Get the current default
+auth0 api get "custom-domains/default"
+```
+
+### CLI vs API value conventions
+
+The dedicated `auth0 domains` subcommands and the `auth0 api` passthrough use different value vocabularies for some fields. When translating between them, watch for:
+
+| Concept | Dedicated CLI flag | API body field |
+|---|---|---|
+| Certificate type (Auth0-managed) | `--type auth0` | `"type": "auth0_managed_certs"` |
+| Certificate type (self-managed) | `--type self` | `"type": "self_managed_certs"` |
+| Relying party identifier | **not supported on the CLI** (no `--rpid` flag); use API passthrough | `"relying_party_identifier"` |
+| Default domain | **not supported on the CLI** (no `default` subcommand); use API passthrough | `PATCH /custom-domains/default` with `{"domain": "..."}` |
+
+## Domain Object Properties
+
+| Property | Type | Description | Writable |
+|----------|------|-------------|----------|
+| `custom_domain_id` | string | Unique identifier (e.g., `cd_abc123`) | read-only |
+| `domain` | string | The custom domain hostname (e.g., `login.example.com`) | create only |
+| `type` | string | `auth0_managed_certs` or `self_managed_certs` | **create only; PATCH rejects `type`** |
+| `verification_method` | string | `cname` or `txt`; default derives from `type` | create only |
+| `tls_policy` | string | TLS posture for Auth0-managed certs. Default `recommended` | create + PATCH |
+| `custom_client_ip_header` | string | Header carrying real client IP. One of `true-client-ip`, `cf-connecting-ip`, `x-forwarded-for`, `x-azure-clientip`. `null` to clear | create + PATCH |
+| `relying_party_identifier` | string | Per-domain passkey `rpId`. Must be a registrable suffix of `domain`. `null` to clear (defaults to domain hostname) | create + PATCH |
+| `domain_metadata` | object | Up to 10 key-value pairs (≤ 255 chars each). To remove a key, PATCH the full merged object without it (GET → merge client-side → PATCH). See Manage Existing Domains section below. | create + PATCH |
+| `primary` | boolean | Whether this is the default domain (set via `PATCH /tenants/settings`, not here) | read-only here |
+| `status` | string | `disabled`, `pending`, `pending_verification`, `ready` | read-only |
+| `verification.methods` | array | DNS records needed to prove ownership | read-only |
+| `verification.methods[].name` | string | The record type (`cname` or `txt`) | read-only |
+| `verification.methods[].record` | string | The value to write into DNS | read-only |
+| `verification.methods[].domain` | string | The name where the record goes | read-only |
+| `origin_domain_name` | string | The Auth0 edge hostname (usually the same as the CNAME value) | read-only |
+
+## PATCH body reference
+
+Only these fields are accepted on `PATCH /custom-domains/{id}`. Omit fields you don't want to change.
+
+```json
+{
+  "tls_policy": "recommended",
+  "custom_client_ip_header": "cf-connecting-ip",
+  "relying_party_identifier": "example.com",
+  "domain_metadata": {
+    "region": "us-east",
+    "brand": "acme"
+  }
+}
+```
+
+Scalar fields (`tls_policy`, `custom_client_ip_header`, `relying_party_identifier`) can be cleared by PATCHing with `null`. For `domain_metadata`, use the GET → merge client-side → PATCH pattern and submit the full post-merge object (see the Manage Existing Domains section below).
+
+## POST body reference
+
+`POST /custom-domains` accepts `domain` (required), `type`, and optionally the same fields PATCH accepts:
+
+```json
+{
+  "domain": "login.example.com",
+  "type": "auth0_managed_certs",
+  "verification_method": "txt",
+  "tls_policy": "recommended",
+  "custom_client_ip_header": "cf-connecting-ip",
+  "relying_party_identifier": "example.com",
+  "domain_metadata": {
+    "region": "us-east"
+  }
+}
+```
+
+## Status Lifecycle
+
+```text
+[create] -> pending_verification -> [verify + DNS propagates] -> ready
+                ^                                                   |
+                |                                                   |
+                +-- [DNS record removed or changed] <---------------+
+```
+
+A domain can go from `ready` back to `pending_verification` if the CNAME record is removed or changed in DNS. This breaks certificate renewal over time.
+
+## Error Codes
+
+| HTTP Status | Cause | Resolution |
+|-------------|-------|------------|
+| 400 | Invalid domain format or unsupported TLD | Verify the domain is a well-formed hostname. Some TLDs are not supported; see docs |
+| 400 | PATCH body contains `type` | `type` is not PATCHable. Remove it from the body. To change cert type, delete and recreate |
+| 403 | Free-tier tenant without credit card on file. **Custom domains ARE available on Free** — per Auth0 docs: *"To set up a free custom domain, Auth0 tenants must have a valid credit card on file for verification purposes and fraud prevention. The credit card will not be charged."* Do NOT suggest a plan upgrade as the fix | Add card at **Dashboard > Tenant Settings > Billing** (card is not charged). For Teams-managed tenants, the billing UI lives in the Teams section |
+| 403 | Self-managed certs requested at create time but tenant lacks Enterprise | Use `auth0_managed_certs` or upgrade |
+| 404 | Domain ID not found | Verify with `auth0 domains list` |
+| 409 | Domain already configured on this or another tenant | List existing domains. If on another tenant, remove from there first or use a different domain |
+| 429 | Rate limited | Back off and retry |
+
+## Configuration Options
+
+### Certificate types
+
+| Value | When to use | Requirements |
+|-------|-------------|--------------|
+| `auth0_managed_certs` | Default. Auth0 provisions and renews TLS certs | None (all plans) |
+| `self_managed_certs` | Terminating TLS at your own reverse proxy | Enterprise plan |
+
+**`type` is fixed at create time.** The API rejects `type` on PATCH. To change between Auth0-managed and self-managed, delete the domain and recreate it with the new `type`. Coordinate the DNS and reverse-proxy cutover to avoid auth downtime.
+
+### TLS policies
+
+Set via the `tls_policy` field at create or PATCH. Default is `recommended`. Auth0-managed cert domains honor this directly. For self-managed cert domains, the TLS policy is enforced at the user's reverse proxy and `tls_policy` has no runtime effect.
+
+### Custom client IP header
+
+Set via `custom_client_ip_header` at create or PATCH when Auth0 sits behind a reverse proxy. Tells Auth0 which header to trust for the real client IP. Valid values:
+
+| Value | Typical proxy |
+|-------|---------------|
+| `true-client-ip` | Akamai, generic |
+| `cf-connecting-ip` | Cloudflare |
+| `x-forwarded-for` | Generic load balancers, most proxies |
+| `x-azure-clientip` | Azure Front Door |
+
+Set only when a trusted proxy is actually in front of Auth0 and strips external instances of the header. Otherwise clients can spoof the header to bypass rate limiting / anomaly detection.
+
+### Relying party identifier (passkeys)
+
+Set via `relying_party_identifier` at create or PATCH. Default (unset) binds passkeys to the custom domain hostname. Set to a registrable suffix of the domain (e.g., `example.com` for `login.example.com`) to make passkeys usable across surfaces on the same eTLD+1. Changing this invalidates previously registered passkeys for the old RPID.
+
+## Related Endpoints
+
+These endpoints interact with custom domains via the `auth0-custom-domain` header to route notifications through a specific domain (not through the tenant domain):
+
+| Endpoint | Purpose |
+|----------|---------|
+| `POST /api/v2/tickets/password-change` | Password reset ticket (email) |
+| `POST /api/v2/tickets/email-verification` | Email verification ticket |
+| `POST /api/v2/jobs/verification-email` | Resend verification email |
+| `POST /api/v2/users` (with `verify_email: true`) | New user email verification |
+
+When a default domain is set on the tenant, omitting the header uses the default. Without a default, omitting the header uses the tenant domain.
+
+## Management API Token Scopes
+
+For a Machine-to-Machine app to run the full skill flow, grant these scopes on the Management API:
+
+```text
+create:custom_domains
+read:custom_domains
+update:custom_domains
+delete:custom_domains
+update:tenant_settings  # only needed for setting default in MCD
+```
+
+---
+
+# Auth0 Custom Domains: Advanced Topics
+
+Covers Multiple Custom Domains (MCD), default domain selection, the `auth0-custom-domain` header, self-managed certificates, token `iss` behavior, and verification troubleshooting.
+
+## Multiple Custom Domains (MCD)
+
+MCD lets a single Auth0 tenant host multiple custom domains for multi-brand or multi-region deployments. Enterprise customers get up to 20 domains per tenant out of the box; more are available via add-on SKU.
+
+### When to use MCD
+
+- Multi-brand: `login.brand-a.com` and `login.brand-b.com` serve different customer segments
+- Multi-region: `login-us.example.com`, `login-eu.example.com` for regional isolation
+- Tenant consolidation: previously running multiple tenants per brand, collapsing into one
+
+### Adding additional domains
+
+The skill's primary flow creates one domain. To add another, invoke the skill again with the new domain. Each domain gets its own `custom_domain_id`, its own CNAME verification record, and its own TLS certificate lifecycle.
+
+### Default custom domain
+
+When multiple domains are configured, one is designated the **default**. The default is used when a Management API call that triggers a notification (password reset email, verification email, etc.) is made **without** an `auth0-custom-domain` header.
+
+Set the default. Two endpoints exist; **prefer `PATCH /custom-domains/default`** — it accepts the human-readable domain name and is the endpoint the skill uses in the Manage capability. The `tenants/settings` form is the older path, still supported, and handy when you already have the `custom_domain_id` (e.g., from a list response). Both are idempotent and produce the same result; pick whichever keeps the surrounding code simpler.
+
+```bash
+# Preferred: PATCH /custom-domains/default (pass domain name, not ID):
+auth0 api patch "custom-domains/default" --data '{"domain": "login.example.com"}'
+
+# Alternative: tenant settings endpoint (pass the custom_domain_id):
+auth0 api patch "tenants/settings" --data '{"default_custom_domain_id": "cd_abc123"}'
+```
+
+The Auth0 CLI does not have a dedicated `auth0 domains default` subcommand; the API passthrough is the only way.
+
+### The `auth0-custom-domain` header
+
+For any Management API endpoint that triggers user-facing notifications, include the header to route through a specific custom domain:
+
+```bash
+curl --request POST \
+  --url 'https://your-tenant.auth0.com/api/v2/tickets/password-change' \
+  --header 'authorization: Bearer TOKEN' \
+  --header 'auth0-custom-domain: login.brand-a.com' \
+  --header 'content-type: application/json' \
+  --data '{ "email": "user@brand-a.com" }'
+```
+
+If the header is omitted and a default domain is set, the default is used. If no default is set and no header is provided, the notification uses the tenant domain (`your-tenant.auth0.com`), which is usually not what you want.
+
+### Migrating from single to MCD
+
+Users with a single custom domain don't need to migrate; the domain continues to work as-is. When adding a second, consider setting an explicit default before adding it so behavior is predictable.
+
+See [Auth0's MCD migration guide](https://auth0.com/docs/customize/custom-domains/multiple-custom-domains/migration-guide) for the full upgrade path.
+
+## Self-Managed Certificates
+
+Auth0-managed certificates are the default and recommended. Self-managed certificates are for enterprise customers who need to terminate TLS at their own reverse proxy.
+
+### When self-managed is needed
+
+- Corporate TLS policy requires specific cipher suites or cert authorities
+- mTLS or pinned certificates must be used
+- Integration with a specific CDN for performance or compliance
+
+### Supported reverse proxy providers
+
+- Cloudflare
+- AWS CloudFront
+- Azure CDN (Front Door)
+- Google Cloud Platform Load Balancing
+
+### Verification difference
+
+Self-managed domains use **TXT record verification** instead of CNAME. The skill's provider playbook handles CNAME creation; for TXT records, the same tier logic applies, with the record type swapped. The provider-specific instructions in the DNS Provider Playbook section below are identical except for the record type field.
+
+See [Auth0-managed](https://auth0.com/docs/customize/custom-domains/auth0-managed-certificates) and [Self-managed](https://auth0.com/docs/customize/custom-domains/self-managed-certificates) for full configuration.
+
+## Token `iss` Claim Behavior
+
+Auth0 sets the `iss` claim on issued tokens based on the domain the token request came from:
+
+| Request domain | `iss` value |
+|----------------|-------------|
+| `your-tenant.auth0.com` | `https://your-tenant.auth0.com/` |
+| `login.example.com` | `https://login.example.com/` |
+
+### Implications
+
+- If you request a Management API token via the custom domain, you must use the custom domain for subsequent Management API calls. Using `tenant.auth0.com` with a `custom-domain` `iss` token produces `401 invalid issuer`.
+- SDK configurations must use one consistent domain. Don't mix `tenant.auth0.com` in one place and `login.example.com` in another.
+- JWT validation in backend APIs needs to accept the correct issuer. If you switch SDKs to a custom domain, update backend validators to match.
+
+## Verification Troubleshooting
+
+Custom domain verification can get stuck for several reasons. Work through these in order.
+
+### Check the CNAME with `dig`
+
+```bash
+dig +short CNAME login.example.com
+```
+
+The output should be the exact value Auth0 returned in `verification.methods[0].record`. If the value differs, the record was added incorrectly. Compare character-by-character, watching for trailing dots, extra whitespace, or typos.
+
+### Check for proxied records (Cloudflare orange cloud)
+
+On Cloudflare, the record must be DNS-only (grey cloud), not proxied (orange cloud). Other proxy providers (AWS CloudFront, Fastly) can cause similar issues when placed in front of the CNAME.
+
+### Check for CNAME flattening
+
+Some DNS providers flatten CNAMEs at the apex or across zones. This rewrites the record Auth0 sees and breaks verification. Disable flattening for this specific record if possible.
+
+### Check for conflicting records
+
+Some providers won't allow a CNAME alongside other record types at the same name (per DNS RFC). If the target name has an A, AAAA, MX, or TXT record, the CNAME may be silently rejected or not propagated.
+
+### Wait for DNS propagation
+
+Fresh records can take 5-60 minutes to propagate across resolvers. If `dig +short @8.8.8.8 CNAME login.example.com` returns the correct value but `dig +short CNAME login.example.com` (using your local resolver) doesn't, propagation is still in progress.
+
+### Last resort: wait 4 hours, then retry
+
+If the record is correct in DNS but Auth0 still reports `pending_verification`:
+1. Do not delete and recreate the domain. This can cause a service interruption.
+2. Wait at least 4 hours.
+3. Retry verification with `auth0 api post "custom-domains/<domainId>/verify"`.
+
+### When to open a support ticket
+
+- The CNAME is correct in DNS from multiple resolvers, not proxied, not flattened, and verification has been failing for 24+ hours
+- Multiple create/delete cycles have been performed (this can put the domain in a state only support can resolve)
+- The tenant shows a `disabled` status rather than `pending_verification`
+
+## Rate Limits and Quotas
+
+- Custom domain creates/deletes are low-frequency. No published rate limit beyond Management API defaults.
+- The verify polling loop uses exponential backoff (5s, 10s, 20s, 30s, 60s...) and will not hit the 50 req/s Management API limit.
+- MCD has a base entitlement of 20 domains per tenant on Enterprise. Additional capacity via add-on SKU.
+
+---
+
+# Auth0 Custom Domains: Management API Examples
+
+cURL patterns for the Auth0 API calls the skill makes (create the custom domain, trigger verification, poll status until `ready`), plus end-to-end CI/CD automation that stitches Auth0 together with a DNS provider. DNS-provider-specific calls live in the DNS Provider Playbook section below (Cloudflare, Route 53, Azure DNS, Manual); the router there picks the right provider based on the root domain's NS records.
+
+## cURL
+
+### Create custom domain
+
+```bash
+curl --request POST \
+  --url 'https://your-tenant.auth0.com/api/v2/custom-domains' \
+  --header 'authorization: Bearer YOUR_MGMT_API_TOKEN' \
+  --header 'content-type: application/json' \
+  --data '{
+    "domain": "login.example.com",
+    "type": "auth0_managed_certs"
+  }'
+```
+
+Response includes `custom_domain_id`, `status` (starts `pending_verification`), and `verification.methods[0].record` (the CNAME value to put in DNS).
+
+### Trigger verification
+
+```bash
+curl --request POST \
+  --url 'https://your-tenant.auth0.com/api/v2/custom-domains/cd_abc123/verify' \
+  --header 'authorization: Bearer YOUR_MGMT_API_TOKEN'
+```
+
+### Poll status
+
+```bash
+curl --request GET \
+  --url 'https://your-tenant.auth0.com/api/v2/custom-domains/cd_abc123' \
+  --header 'authorization: Bearer YOUR_MGMT_API_TOKEN'
+```
+
+Stop polling when `status` is `ready`. Suggested backoff: 5, 10, 20, 30s, then 60s intervals up to ~10 minutes total.
+
+### Set default domain (MCD only)
+
+```bash
+curl --request PATCH \
+  --url 'https://your-tenant.auth0.com/api/v2/tenants/settings' \
+  --header 'authorization: Bearer YOUR_MGMT_API_TOKEN' \
+  --header 'content-type: application/json' \
+  --data '{"default_custom_domain_id": "cd_abc123"}'
+```
+
+### Handling 403 on create (credit card required)
+
+On Free-tier tenants without a credit card on file, `POST /custom-domains` returns 403. Inspect the status:
+
+```bash
+HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" --request POST \
+  --url "https://${AUTH0_TENANT}/api/v2/custom-domains" \
+  --header "authorization: Bearer ${AUTH0_TOKEN}" \
+  --header "content-type: application/json" \
+  --data '{"domain": "login.example.com", "type": "auth0_managed_certs"}')
+
+if [ "$HTTP_STATUS" = "403" ]; then
+  echo "Custom domains require a credit card on file for identity verification."
+  echo "The card is not charged. Add one at Dashboard → Tenant Settings → Billing."
+  exit 1
+fi
+```
+
+Do not suggest a plan upgrade on 403; the fix is adding a card.
+
+## CI/CD automation
+
+End-to-end patterns that stitch Auth0 domain creation, DNS record provisioning, and verification polling. Useful for multi-environment setups and infrastructure-as-code pipelines.
+
+### End-to-end script: Auth0 + Route 53
+
+Creates the custom domain, writes the CNAME to Route 53, polls Route 53 until `INSYNC`, triggers Auth0 verification, and polls Auth0 until `ready`.
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+# Required env vars:
+#   AUTH0_TENANT (e.g., acme-prod.us.auth0.com)
+#   AUTH0_TOKEN (Management API token with create:custom_domains + read:custom_domains)
+#   CUSTOM_DOMAIN (e.g., login.example.com)
+#   ROUTE53_HOSTED_ZONE_ID (e.g., Z1234567890ABC)
+
+# 1. Create custom domain in Auth0
+CREATE_RESPONSE=$(curl -sf --request POST \
+  --url "https://${AUTH0_TENANT}/api/v2/custom-domains" \
+  --header "authorization: Bearer ${AUTH0_TOKEN}" \
+  --header "content-type: application/json" \
+  --data "{
+    \"domain\": \"${CUSTOM_DOMAIN}\",
+    \"type\": \"auth0_managed_certs\"
+  }")
+
+DOMAIN_ID=$(echo "$CREATE_RESPONSE" | jq -r '.custom_domain_id')
+CNAME_VALUE=$(echo "$CREATE_RESPONSE" | jq -r '.verification.methods[0].record')
+
+echo "Auth0 custom domain created: ${DOMAIN_ID}"
+echo "CNAME ${CUSTOM_DOMAIN} -> ${CNAME_VALUE}"
+
+# 2. Create CNAME in Route 53
+CHANGE_RESPONSE=$(aws route53 change-resource-record-sets \
+  --hosted-zone-id "${ROUTE53_HOSTED_ZONE_ID}" \
+  --change-batch "{
+    \"Changes\": [{
+      \"Action\": \"UPSERT\",
+      \"ResourceRecordSet\": {
+        \"Name\": \"${CUSTOM_DOMAIN}\",
+        \"Type\": \"CNAME\",
+        \"TTL\": 300,
+        \"ResourceRecords\": [{\"Value\": \"${CNAME_VALUE}\"}]
+      }
+    }]
+  }" --output json)
+
+CHANGE_ID=$(echo "$CHANGE_RESPONSE" | jq -r '.ChangeInfo.Id')
+echo "Route 53 change submitted: ${CHANGE_ID}"
+
+# 3. Wait for Route 53 to propagate
+while true; do
+  STATUS=$(aws route53 get-change --id "${CHANGE_ID}" --output json | jq -r '.ChangeInfo.Status')
+  echo "Route 53 change status: ${STATUS}"
+  [ "$STATUS" = "INSYNC" ] && break
+  sleep 10
+done
+
+# 4. Trigger Auth0 verification
+curl -sf --request POST \
+  --url "https://${AUTH0_TENANT}/api/v2/custom-domains/${DOMAIN_ID}/verify" \
+  --header "authorization: Bearer ${AUTH0_TOKEN}" > /dev/null
+
+# 5. Poll Auth0 status with backoff
+DELAYS=(5 10 20 30 60 60 60 60 60 60)
+for delay in "${DELAYS[@]}"; do
+  sleep "$delay"
+  STATUS=$(curl -sf --request GET \
+    --url "https://${AUTH0_TENANT}/api/v2/custom-domains/${DOMAIN_ID}" \
+    --header "authorization: Bearer ${AUTH0_TOKEN}" | jq -r '.status')
+  echo "Auth0 domain status: ${STATUS}"
+  if [ "$STATUS" = "ready" ]; then
+    echo "Custom domain ${CUSTOM_DOMAIN} is ready"
+    exit 0
+  fi
+done
+
+echo "Timed out waiting for custom domain to become ready"
+exit 1
+```
+
+### Multi-environment pattern
+
+Each environment gets its own custom domain. Script once, parametrize:
+
+```text
+environments/
+  dev/
+    AUTH0_TENANT=acme-dev.us.auth0.com
+    CUSTOM_DOMAIN=login-dev.example.com
+    ROUTE53_HOSTED_ZONE_ID=Z111
+  staging/
+    AUTH0_TENANT=acme-staging.us.auth0.com
+    CUSTOM_DOMAIN=login-staging.example.com
+    ROUTE53_HOSTED_ZONE_ID=Z222
+  prod/
+    AUTH0_TENANT=acme-prod.us.auth0.com
+    CUSTOM_DOMAIN=login.example.com
+    ROUTE53_HOSTED_ZONE_ID=Z333
+```
+
+Invoke the script once per environment, either sequentially in CI or via a matrix build.
+
+### Idempotency
+
+The script above is idempotent **for Route 53** (`UPSERT` creates or updates). For Auth0, creating a custom domain that already exists returns 409. To make the Auth0 step idempotent:
+
+```bash
+# Check if the domain already exists
+EXISTING=$(curl -sf --request GET \
+  --url "https://${AUTH0_TENANT}/api/v2/custom-domains" \
+  --header "authorization: Bearer ${AUTH0_TOKEN}" | \
+  jq -r ".[] | select(.domain == \"${CUSTOM_DOMAIN}\") | .custom_domain_id")
+
+if [ -n "$EXISTING" ]; then
+  DOMAIN_ID="$EXISTING"
+  echo "Custom domain already exists: ${DOMAIN_ID}"
+  # Fetch CNAME value from existing domain
+  CNAME_VALUE=$(curl -sf --request GET \
+    --url "https://${AUTH0_TENANT}/api/v2/custom-domains/${DOMAIN_ID}" \
+    --header "authorization: Bearer ${AUTH0_TOKEN}" | \
+    jq -r '.verification.methods[0].record')
+else
+  # ... create as above
+fi
+```
+
+### Certificate renewal monitoring
+
+Auth0-managed certs auto-renew every ~3 months. Renewal requires the CNAME to still be in DNS. For periodic monitoring, alert on:
+
+- The domain's `status` field changing from `ready` to anything else (poll `GET /api/v2/custom-domains/{id}`)
+- The CNAME disappearing from DNS (check with `dig +short CNAME {domain}`)
+
+The **Check domain health** capability covers both for a one-off check.
+
+---
+
+# Auth0 Custom Domains: DNS Provider Playbook (Router)
+
+Entry point for writing the Auth0 CNAME verification record into the user's DNS provider. This file is a **router**: detect the provider from the root domain's NS records, then open only the matching tier file. Do not load every tier up-front — each tier file is self-contained.
+
+## Provider Detection
+
+### Lookup command
+
+```bash
+dig +short NS example.com
+```
+
+### NS pattern to provider mapping
+
+| NS pattern | Provider | Tier | Reference |
+|------------|----------|------|-----------|
+| `*.ns.cloudflare.com` | Cloudflare | 1: Full automation (Cloudflare MCP) | Cloudflare section below |
+| `*.awsdns-*.com`, `*.awsdns-*.net`, `*.awsdns-*.org`, `*.awsdns-*.co.uk` | AWS Route 53 | 2: Assisted (AWS CLI) | Route 53 section below |
+| `*.azure-dns.com`, `*.azure-dns.net`, `*.azure-dns.org`, `*.azure-dns.info` | Azure DNS | 3: Assisted (Azure CLI) | Azure DNS section below |
+| `ns*.domaincontrol.com` | GoDaddy | 4: Manual | Manual Guided section below |
+| `dns*.registrar-servers.com` | Namecheap | 4: Manual | Manual Guided section below |
+| `ns*.hover.com` | Hover | 4: Manual | Manual Guided section below |
+| `ns*.squarespacedns.com` | Squarespace Domains | 4: Manual | Manual Guided section below |
+| `curitiba.ns.porkbun.com`, `fortaleza.ns.porkbun.com`, etc. | Porkbun | 4: Manual | Manual Guided section below |
+| `ns*.name.com` | Name.com | 4: Manual | Manual Guided section below |
+| `*.gandi.net` | Gandi | 4: Manual | Manual Guided section below |
+| `ns*.worldnic.com` | Network Solutions | 4: Manual | Manual Guided section below |
+| `ns*.ui-dns.*` | IONOS | 4: Manual | Manual Guided section below |
+| `ns*.dreamhost.com` | DreamHost | 4: Manual | Manual Guided section below |
+| `ns*.googledomains.com` | Google Domains (legacy, migrated to Squarespace) | 4: Manual | Manual Guided section below |
+| Anything else | Unknown | 4: Generic manual | Manual Guided section below |
+
+When the NS pattern is unrecognized, fall back to generic Tier 4 instructions in the Manual Guided section below and surface the NS records to the user so they can identify the provider themselves.
+
+## Tier summary
+
+- **Tier 1 — Cloudflare**: fully automated via the Cloudflare MCP. OAuth, no plan tier required, `proxied: false` is critical. See Cloudflare section below.
+- **Tier 2 — Route 53**: AWS CLI if credentials are configured. `UPSERT` for create, exact-match DELETE (Name, Type, TTL, Value). Poll `get-change` until `INSYNC`. See Route 53 section below.
+- **Tier 3 — Azure DNS**: Azure CLI if signed in. `az network dns record-set cname set-record`. Propagates in <30s. See Azure DNS section below.
+- **Tier 4 — Manual**: copy-pasteable record block plus per-registrar dashboard URLs and UI-label cheat sheet. See Manual Guided section below.
+
+## How to use this router
+
+1. Run `dig +short NS <root-domain>` and match against the table above.
+2. Find the matching tier section below (Cloudflare / Route 53 / Azure DNS / Manual Guided). Each section is self-contained — it covers plan requirements, pre-flight, create, (if applicable) delete, error handling, and fallback for that one provider.
+3. If the automated tier's pre-flight fails (missing MCP, unconfigured CLI, private zone, etc.), each tier section tells you to drop to the Manual Guided section below with a provider-specific deep-link.
+
+If you are handling the **Remove a custom domain** flow, the delete mechanics for Route 53 (exact-match requirement) live in the Route 53 section below. The other tiers delete via the same commands/UIs they create with; no special rules.
+
+---
+
+# Cloudflare (Tier 1: Full Automation)
+
+Cloudflare publishes an official MCP server at `https://mcp.cloudflare.com/mcp` with OAuth browser auth. The server exposes two tools (`search()` and `execute()`) and runs generated JavaScript against a sandboxed Cloudflare API client.
+
+## Plan requirements
+
+DNS management on Cloudflare is **available on every plan including Free**. The `https://mcp.cloudflare.com/mcp` server wraps the same Cloudflare API and needs no paid Cloudflare plan for DNS CRUD. Cloudflare's GitHub README hedges that "some features may require a paid Workers plan"; that applies to MCP features tied to paid products (Workers deploys, Containers, AI Gateway), not DNS.
+
+Free-plan caveats to surface to the user:
+- Zones created after September 2024 cap at **200 DNS records per zone**. Auth0's CNAME counts as one; most hobby zones are nowhere near this.
+- Free plan minimum TTL is 60 seconds (30 on Enterprise). `ttl: 1` uses Cloudflare's automatic TTL and works on Free.
+- Free plan does not allow API tokens with Client IP Address Filtering. The MCP's OAuth flow avoids this.
+
+## Pre-flight check
+
+Confirm the Cloudflare MCP is connected to the user's Claude Code session. If not:
+
+```text
+The Cloudflare MCP server isn't connected. Add it with:
+
+  claude mcp add --transport http cloudflare https://mcp.cloudflare.com/mcp
+
+Then authorize in the browser when Claude prompts you.
+```
+
+## Creating the CNAME record
+
+Because Cloudflare's MCP exposes only `search()` and `execute()`, the skill prompts the LLM to generate a small script rather than calling a named tool. The pattern:
+
+1. `search("dns records")` to locate the endpoint
+2. `execute()` to run a script that finds the zone ID then creates the record
+
+Script pattern for `execute()`. **Before passing to `execute()`, substitute the three placeholders with real values**: `ROOT_DOMAIN` (e.g., `example.com`), `CUSTOM_DOMAIN` (e.g., `login.example.com`), and `CNAME_TARGET` (the `verification.methods[0].record` value returned by `POST /custom-domains`, NOT the literal string below).
+
+```javascript
+// Find the zone ID for the root domain
+const zones = await cf.zones.list({ name: "ROOT_DOMAIN" });
+if (zones.result.length === 0) {
+  throw new Error("Zone ROOT_DOMAIN not found in this Cloudflare account");
+}
+const zoneId = zones.result[0].id;
+
+// Check for existing record at the target name
+const existing = await cf.dns.records.list({
+  zone_id: zoneId,
+  name: "CUSTOM_DOMAIN",
+  type: "CNAME",
+});
+
+// Create the CNAME (or update if one already exists; confirm with user first)
+if (existing.result.length === 0) {
+  return await cf.dns.records.create({
+    zone_id: zoneId,
+    type: "CNAME",
+    name: "CUSTOM_DOMAIN",
+    content: "CNAME_TARGET",  // must match verification.methods[0].record exactly
+    proxied: false,  // critical: Auth0 verification fails on proxied records
+    ttl: 1,  // 1 = automatic, Cloudflare default
+  });
+} else {
+  // Present the existing value and confirm overwrite before calling update()
+}
+```
+
+## Key constraints
+
+- `proxied` must be `false`. A proxied (orange-cloud) CNAME breaks Auth0 verification and Auth0-managed certificates.
+- Minimum TTL is 60s on standard zones, 30s on Enterprise. `ttl: 1` uses Cloudflare's automatic TTL.
+- The authenticated token needs `DNS:Edit` scope on the target zone. OAuth flow grants this by default when the user authorizes.
+- API tokens with Client IP Address Filtering are not supported by the MCP.
+
+## Fallback
+
+If the Cloudflare MCP can't be used (auth failure, zone not in account, unexpected error), drop to the Manual Guided section below with Cloudflare dashboard deep-link:
+`https://dash.cloudflare.com/?to=/:account/:zone/dns/records` (the user needs to know their account and zone; a simpler fallback is `https://dash.cloudflare.com/` and instruct them to navigate).
+
+---
+
+# AWS Route 53 (Tier 2: Assisted Automation)
+
+Uses the AWS CLI. If the user already has AWS credentials configured (env vars, shared config, or SSO session), this tier handles the CNAME creation automatically. Otherwise it falls back to the Manual Guided section below.
+
+## Plan requirements
+
+Route 53 has **no plan tiers**. It's pay-per-use:
+- ~$0.50/hosted zone/month for the first 25 zones (lower per-zone after).
+- $0.40 per million queries for the first billion (lower after).
+- Route 53 is **not included in the AWS free tier**, even on new accounts.
+- Default API rate limit is 5 requests/second per account; the skill's verify-poll backoff stays well under this.
+
+What the calling identity needs:
+- `route53:ListHostedZonesByName` (read)
+- `route53:ListResourceRecordSets` (read)
+- `route53:ChangeResourceRecordSets` (write, for create and delete)
+- `route53:GetChange` (read, for INSYNC polling)
+
+The `AmazonRoute53FullAccess` managed policy covers all of these; a least-privilege custom policy scoped to the hosted zone ARN is cleaner for production.
+
+## Pre-flight check
+
+```bash
+aws sts get-caller-identity
+```
+
+If this returns identity info, proceed. If it errors with credentials/expired token, drop to the Manual Guided section below with a Route 53 console deep-link.
+
+## Find the hosted zone
+
+```bash
+aws route53 list-hosted-zones-by-name \
+  --dns-name example.com \
+  --max-items 1
+```
+
+Extract the hosted zone ID (strip the `/hostedzone/` prefix). Watch for private vs public zones; Auth0 needs a public zone. If the result is a private hosted zone, fall back to manual with an explanation.
+
+## Create the CNAME record
+
+```bash
+aws route53 change-resource-record-sets \
+  --hosted-zone-id Z1234567890ABC \
+  --change-batch '{
+    "Changes": [{
+      "Action": "UPSERT",
+      "ResourceRecordSet": {
+        "Name": "login.example.com",
+        "Type": "CNAME",
+        "TTL": 300,
+        "ResourceRecords": [{"Value": "tenant.edge.tenants.auth0.com"}]
+      }
+    }]
+  }'
+```
+
+`UPSERT` creates the record if it doesn't exist and updates it if it does. Before calling, list existing records at the target name and confirm overwrite with the user if one is present with a different value:
+
+```bash
+aws route53 list-resource-record-sets \
+  --hosted-zone-id Z1234567890ABC \
+  --start-record-name login.example.com \
+  --start-record-type CNAME \
+  --max-items 1
+```
+
+## Poll until `INSYNC`
+
+The `change-resource-record-sets` response contains a `ChangeInfo.Id`. Poll it:
+
+```bash
+aws route53 get-change --id /change/C1234567890ABC
+```
+
+The `Status` field returns `PENDING` then `INSYNC`. Wait for `INSYNC` (usually ~60s) before triggering Auth0 verification.
+
+## Delete the CNAME record (the Remove a custom domain flow)
+
+DELETE on Route 53 is stricter than UPSERT: the submitted record must **exactly match** the live record on `Name`, `Type`, `TTL`, and every `Value` in `ResourceRecords`. A mismatched TTL silently fails with `InvalidChangeBatch: Tried to delete resource record set ... but it was not found`. Always fetch the current record first and copy its exact values into the DELETE batch.
+
+```bash
+# 1. Read the current record's exact values
+aws route53 list-resource-record-sets \
+  --hosted-zone-id Z1234567890ABC \
+  --start-record-name login.example.com \
+  --start-record-type CNAME \
+  --max-items 1
+```
+
+```bash
+# 2. Submit the DELETE with exact-match values (substitute TTL and Value from step 1)
+aws route53 change-resource-record-sets \
+  --hosted-zone-id Z1234567890ABC \
+  --change-batch '{
+    "Changes": [{
+      "Action": "DELETE",
+      "ResourceRecordSet": {
+        "Name": "login.example.com",
+        "Type": "CNAME",
+        "TTL": 300,
+        "ResourceRecords": [{"Value": "tenant.edge.tenants.auth0.com"}]
+      }
+    }]
+  }'
+```
+
+Poll `get-change` until `INSYNC` to confirm propagation before reporting success.
+
+## Error handling
+
+- `PriorRequestNotComplete`: another change on the same zone is still propagating. Back off and retry (5s, 10s, 20s).
+- `InvalidChangeBatch` on DELETE: the submitted record doesn't exactly match the live record. Re-run the list step above and copy the TTL and Value precisely.
+- Rate limit: Route 53 allows 5 req/s per account. With the skill's backoff on verify polling, this is not usually a concern.
+
+## Fallback deep-link
+
+If pre-flight fails:
+```text
+https://console.aws.amazon.com/route53/v2/hostedzones
+```
+Instruct the user to click their zone, then "Create record".
+
+---
+
+# Azure DNS (Tier 3: Assisted Automation)
+
+Uses the Azure CLI. If the user is signed in, this tier handles the CNAME creation automatically. Otherwise it falls back to the Manual Guided section below.
+
+## Plan requirements
+
+Azure DNS has **no plan tiers**. Any active Azure subscription (pay-as-you-go, EA, CSP, Visual Studio credit, free trial) can host public DNS zones. Pricing is $0.50/zone/month for the first 25 zones (lower after) plus $0.40 per million queries.
+
+What the signed-in identity needs:
+- The **DNS Zone Contributor** role on the resource group containing the zone, or
+- The broader **Contributor** / **Owner** role on the resource group or subscription.
+
+The `Reader` role alone is insufficient; record-set writes return 403. Default subscription limit is **250 public DNS zones per subscription**, raisable via support.
+
+## Pre-flight check
+
+```bash
+az account show
+```
+
+If this returns an active subscription, proceed. Otherwise drop to the Manual Guided section below with the Azure portal deep-link.
+
+## Find the DNS zone
+
+```bash
+az network dns zone list \
+  --query "[?name=='example.com'].{name:name, rg:resourceGroup}" \
+  -o json
+```
+
+Extract the resource group. If the zone is in a subscription different from the current default, the user may need to run `az account set --subscription <id>` first.
+
+## Create the CNAME record
+
+Azure CLI's record-set create and set-record are separate commands. Use `set-record` which handles both cases:
+
+```bash
+az network dns record-set cname set-record \
+  --resource-group my-rg \
+  --zone-name example.com \
+  --record-set-name login \
+  --cname tenant.edge.tenants.auth0.com \
+  --ttl 300
+```
+
+Notes:
+- `--record-set-name` is the relative name (`login`), not the full FQDN.
+- Azure DNS CNAME record sets can only contain a single record. If one already exists with a different value, you must delete the existing record-set first (confirm with user):
+
+```bash
+az network dns record-set cname delete \
+  --resource-group my-rg \
+  --zone-name example.com \
+  --name login \
+  --yes
+```
+
+## Propagation
+
+Azure DNS propagates quickly (typically <30s). No polling equivalent to Route 53's `INSYNC` check is needed. Proceed directly to Auth0 verification.
+
+## Fallback deep-link
+
+```text
+https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.Network%2FdnsZones
+```
+Instruct the user to select their zone, then **+ Record set**.
+
+---
+
+# Manual Guided (Tier 4: Everyone Else)
+
+For all other providers, the skill outputs a copy-pasteable record block and provider-specific instructions.
+
+## Record block to output
+
+Show exactly (substitute the Host and Value with the actual values returned by `POST /api/v2/custom-domains` — the block below uses `login` and `tenant.edge.tenants.auth0.com` only as placeholders):
+
+```text
+Record type: CNAME
+Host / Name: login              (the subdomain portion only, not the full FQDN)
+Value / Points to: tenant.edge.tenants.auth0.com
+TTL: 300 (or provider default)
+Proxy / Orange cloud: OFF / DNS-only
+```
+
+Note the "Host" formatting: most providers expect just the subdomain (`login`), but a few expect the full FQDN (`login.example.com`). Call this out in the per-provider instructions below.
+
+## Per-provider cheat sheet
+
+All providers below use the same record values (type CNAME, host is the subdomain only, value is the Auth0-provided CNAME target). Differences are dashboard URL, label naming, and navigation path.
+
+| Provider | Dashboard URL (substitute the root domain) | UI labels (host, value) | Navigation hint |
+|---|---|---|---|
+| GoDaddy | `https://dcc.godaddy.com/manage/{domain}/dns` | Name, Value | My Products → DNS → Add New Record |
+| Namecheap | `https://ap.www.namecheap.com/domains/domaincontrolpanel/{domain}/advancedns` | Host, Value | Domain List → Manage → Advanced DNS → Add New Record |
+| Hover | `https://www.hover.com/control_panel/domain/{domain}/dns` | Hostname, Target Host | Account → domain → DNS → Add a Record |
+| Squarespace Domains (was Google Domains) | `https://account.squarespace.com/domains/managed/{domain}/dns/dns-settings` | Host, Data | Domains → domain → DNS → DNS settings → Add record |
+| Porkbun | `https://porkbun.com/account/domainsSpeedy` | Host, Answer | Domain Management → DNS Records |
+| Name.com | `https://www.name.com/account/domain/details/{domain}#dns` | Host, Answer | My Domains → domain → Manage DNS Records |
+| Gandi | `https://admin.gandi.net/domain/{domain}/records` | Name, Hostname | Domain → DNS Records → Add |
+| Network Solutions | `https://www.networksolutions.com/my-account/` | Alias, Other Host | Manage → domain → Change Where Domain Points / Advanced DNS |
+| IONOS | `https://my.ionos.com/dns` | Host name, Points to | Domains & SSL → domain → DNS |
+| DreamHost | `https://panel.dreamhost.com/index.cgi?tree=domain.manage` | Name, Value | Manage Domains → DNS (for the domain) |
+
+Common gotchas across providers:
+- Host field is the subdomain only (`login`), never the full FQDN, unless the provider explicitly shows "@" or the full domain as the default.
+- Some dashboards default TTL to 1 hour; 300 seconds is fine, longer is fine.
+- No provider above requires a proxy toggle, but if one exists (e.g., proxied CDN), it must be off.
+
+### Unknown provider
+
+If NS records don't match any known pattern, output:
+
+```text
+Your DNS appears to be hosted at {nameserver domain}. Log in to that provider's
+dashboard and look for "DNS", "DNS Records", "Advanced DNS", or "Zone Editor".
+Add a new CNAME record with the values above.
+```
+
+## After the user confirms
+
+Ask: "Reply 'done' when you've added the record, or 'skip' to give up for now."
+
+On "done", proceed to Auth0 verification in SKILL.md Step 3. On "skip", save the CNAME target value and `custom_domain_id` to the conversation so they can resume later.
+
+If verification fails, first suggest `dig CNAME login.example.com` and compare the result to the expected target.
+
+---
+
+# Set Up a Custom Domain
+
+End-to-end provisioning: create the domain in Auth0, write the CNAME into the user's DNS provider, verify ownership, and report what to update in their apps. Handles both the first custom domain on a tenant and adding another one to a tenant with MCD already enabled.
+
+## Gather inputs
+
+Ask questions one at a time as plain conversational text. Do not present all inputs at once or use structured UI widgets. Sequence:
+
+1. **Domain hostname**: Ask directly — "What hostname do you want to set up? (e.g., `login.example.com`)" — and wait for the reply.
+
+2. **Certificate type**: Default to `auth0_managed_certs` silently. Only ask if the user has given a signal they need self-managed (Enterprise reverse-proxy setup). Mention once that type is fixed at create time.
+
+3. **Passkey / RPID plan**: Skip this question entirely. For subdomains, include `relying_party_identifier` (eTLD+1) speculatively in the create call — it's almost always the right default and there is no probe endpoint to check the feature flag in advance. If the create returns `operation_not_supported`, retry without it and tell the user: "The `relying_party_identifier` feature isn't enabled on this tenant. The domain was created without it. Contact Auth0 support to enable the flag; RPID can be set via PATCH once it's on." For root-domain custom domains, omit `relying_party_identifier` entirely — passkeys bind to the root automatically.
+
+4. **Reverse proxy**: Ask only if there's a signal the tenant is behind a proxy. "Is Auth0 behind a reverse proxy (Cloudflare, CloudFront, Azure Front Door)? If so, I'll set the client IP header so rate limiting sees the real IP." Default to no header.
+
+5. **TLS policy**: Do not ask. Default to `recommended` silently unless the user raises a compliance requirement.
+
+6. **Tenant confirmation**: Run `auth0 tenants list`, show the active tenant, and ask for confirmation before creating. This is the one place a yes/no confirmation is required.
+
+## Create the domain in Auth0
+
+Minimal create (Auth0-managed certs, defaults everywhere):
+
+```bash
+auth0 api post "custom-domains" --data '{
+  "domain": "login.example.com",
+  "type": "auth0_managed_certs"
+}'
+```
+
+Full-featured create with optional fields (omit any that don't apply):
+
+```bash
+auth0 api post "custom-domains" --data '{
+  "domain": "login.example.com",
+  "type": "auth0_managed_certs",
+  "verification_method": "txt",
+  "tls_policy": "recommended",
+  "custom_client_ip_header": "cf-connecting-ip",
+  "relying_party_identifier": "example.com",
+  "domain_metadata": {
+    "region": "us-east",
+    "brand": "acme"
+  }
+}'
+```
+
+Notes on the optional fields:
+- `verification_method`: default is derived from `type` (CNAME for Auth0-managed, TXT for self-managed). Only set it if explicitly overriding.
+- `tls_policy`: default `recommended`; no reason to set unless compliance requires.
+- `custom_client_ip_header`: one of `true-client-ip`, `cf-connecting-ip`, `x-forwarded-for`, `x-azure-clientip`. Match the header the proxy in front of Auth0 emits.
+- `relying_party_identifier`: set when the custom domain is a subdomain but passkeys should bind to the parent domain.
+- `domain_metadata`: up to 10 key-value pairs (keys and values ≤ 255 chars); surfaces in Actions.
+
+The response contains `custom_domain_id`, `status: "pending_verification"`, and `verification.methods[0].record`: the CNAME value to put in DNS. Save these.
+
+**If the API returns 400 with `operation_not_supported` on `relying_party_identifier`**: the feature flag is not enabled on this tenant. Retry the create without `relying_party_identifier`, then tell the user: "The `relying_party_identifier` feature isn't enabled on this tenant. Domain created without it. Contact Auth0 support to enable the flag; RPID can be set via PATCH once it's on."
+
+**If the API returns 403**: the tenant is a Free tenant without a credit card on file. Direct the user to **Dashboard → Tenant Settings → Billing** (or the Teams section for Teams-managed tenants) to add a card, then retry. The card is not charged. This is the correct diagnosis on Free tier; do not suggest a plan upgrade.
+
+**If the API returns 409**: the domain already exists on this or another tenant. `auth0 api get "custom-domains"` to list existing. If it's already on this tenant and just needs verification, skip to the verify step below with the existing `custom_domain_id`.
+
+See the Examples section below for curl, node-auth0, and auth0-python code patterns.
+
+## Detect the DNS provider and route to a tier
+
+```bash
+dig +short NS example.com
+```
+
+Match the NS pattern against the table in the DNS Provider Playbook section below to select a tier, then follow the matching provider section:
+
+- **Tier 1 Cloudflare** → Cloudflare section below (full automation via Cloudflare MCP)
+- **Tier 2 AWS Route 53** → Route 53 section below (assisted via AWS CLI)
+- **Tier 3 Azure DNS** → Azure DNS section below (assisted via Azure CLI)
+- **Tier 4 other** → Manual Guided section below (guided manual record entry)
+
+Each sub-file is self-contained (plan requirements, pre-flight, create, error handling, fallback). Don't load every tier — load only the one that matches the detected NS pattern. Return here for the verify step once the record is written.
+
+## Check for an existing record at the target name
+
+Before writing, check what's already there:
+
+```bash
+dig +short CNAME login.example.com
+```
+
+Three outcomes:
+1. **No record**: proceed with the write.
+2. **Record matches the expected value**: skip the write, go straight to verify.
+3. **Record exists with a different value**: confirm with the user before overwriting. Show both values. On Tier 2 (Route 53) the `UPSERT` action will overwrite silently, so the confirmation has to happen in the skill, not the CLI.
+
+## Write the CNAME record
+
+Execute the tier-specific flow from the sub-file you opened above. For Tiers 2 and 3, wait for the provider to report propagation complete (Route 53: `INSYNC`; Azure: proceed after ~30s) before triggering Auth0 verification. For Tier 4, wait for the user to reply "done."
+
+## Trigger Auth0 verification
+
+```bash
+auth0 api post "custom-domains/<domainId>/verify"
+```
+
+## Poll until ready
+
+Poll `GET /api/v2/custom-domains/<domainId>` with backoff: 5s, 10s, 20s, 30s, 60s, 60s... up to ~10 minutes total. Stop when `status` becomes `ready`.
+
+If the polling window expires with status still `pending_verification`: route to the **Troubleshoot verification** flow rather than retrying blindly.
+
+## Report next steps
+
+On success, tell the user what they need to update in their applications:
+
+```text
+Custom domain login.example.com is verified and ready.
+
+Next steps (outside this skill's scope):
+  • SDK config: change the `domain` / `issuerBaseURL` value to login.example.com
+    in every application SDK
+  • Application callback URLs: update any URLs that reference the old tenant
+    domain
+  • Passkey rpId: if using passkeys, confirm rpId matches the eTLD+1 of the
+    custom domain
+  • SAML / WS-Fed metadata URLs: regenerate and redistribute
+
+Full guide: https://auth0.com/docs/customize/custom-domains/configure-features-to-use-custom-domains
+```
+
+If the tenant now has multiple custom domains for the first time, mention that they may want to set a default via the Manage existing domains flow.
+
+## MCD: adding a domain to a tenant that already has one
+
+The flow above is identical whether this is the tenant's first custom domain or the Nth. A few things to mention when MCD is in play:
+
+- The new domain gets its own `custom_domain_id`, CNAME verification record, and certificate lifecycle.
+- Consider setting a default custom domain after adding the second domain (the Manage existing domains flow). Without a default, notification-triggering Management API calls route through the tenant domain unless the caller sends the `auth0-custom-domain` header. See the Advanced Topics section below.
+- MCD is Enterprise-only with a base of 20 domains per tenant. If the user is on a non-Enterprise plan, creating a second domain returns a 403 with a different error than the Free-tier CC case; surface the full error body so the user knows which limit they hit.
+
+## Edge cases to handle during setup
+
+- **Private hosted zone (Route 53)**: if `list-hosted-zones-by-name` returns a private zone, fall back to Tier 4; Auth0 verification needs a public zone.
+- **Apex vs subdomain**: the CNAME always goes into the zone of the root domain, at the subdomain name. If the user asked for a custom domain at the apex (e.g., `example.com` itself), DNS doesn't permit a real CNAME at the apex; suggest a subdomain instead or use ALIAS/ANAME records where supported.
+- **Shared parent zone with delegation**: if the apex is delegated to a different provider than the subdomain, check the NS records for the subdomain specifically, not just the root.
+
+---
+
+# Manage Existing Domains
+
+Surgical edits on custom domains that already exist: list them, set or change the default, update TLS policy, configure the custom client IP header, set the relying party identifier for passkeys, and manage per-domain metadata. Intent-driven: the user says what they want in natural language and the skill maps it to the right API call.
+
+**Not in scope here: changing certificate type.** The Management API rejects `type` on PATCH. `type` is fixed at create time. If the user wants to switch between `auth0_managed_certs` and `self_managed_certs`, route them to delete (**Remove a custom domain**) and recreate (**Set up a custom domain**). Coordinate the DNS and reverse-proxy cutover to avoid auth downtime.
+
+## Pre-flight: confirm the active tenant
+
+Before any PATCH or tenant-settings write, confirm the active Auth0 CLI tenant matches the one the user intends to modify. The Auth0 CLI is single-tenant; an unnoticed mismatch writes to the wrong tenant.
+
+```bash
+auth0 tenants list
+```
+
+Surface the active tenant to the user and require explicit confirmation ("the active tenant is `acme-prod`; proceed?"). If it's wrong, stop and have the user run `auth0 tenants use <tenant-name>`, then re-confirm before continuing.
+
+## Load current state
+
+After tenant confirmation, fetch the current custom domain list once. Cache it for the session so disambiguation prompts can show current values.
+
+```bash
+auth0 api get "custom-domains"
+```
+
+Also fetch tenant settings for the current default:
+
+```bash
+auth0 api get "tenants/settings"
+```
+
+Look at the `default_custom_domain_id` field.
+
+## Intent mapping
+
+Common user phrasings and what they map to:
+
+| User says | Target |
+|---|---|
+| "list my custom domains" / "what domains do I have?" | Show the cached list: domain, status, cert type, default flag |
+| "make {domain} the default" / "set default to {domain}" | `PATCH /tenants/settings` with `default_custom_domain_id` |
+| "which one is the default?" | Read from cached tenant settings |
+| "switch {domain} to self-managed" / "switch {domain} back to Auth0-managed" / "change cert type on {domain}" | Not supported via PATCH. Explain that `type` is fixed at create, and route to **Remove a custom domain** + **Set up a custom domain** to do a delete + recreate. Warn about downtime |
+| "set the rpId on {domain} to example.com" / "bind passkeys at the root" / "change the passkey rpId" | See **Set the relying party identifier (passkeys)** below |
+| "what's the rpId for {domain}?" / "where do passkeys bind for {domain}?" | Read `relying_party_identifier` from cached state; if unset, explain default is the domain hostname |
+| "set the TLS policy to recommended" / "change TLS policy on {domain}" | See **Update TLS policy** below |
+| "set the client IP header to cf-connecting-ip" / "Auth0 is behind Cloudflare, use the right IP header" | See **Configure the custom client IP header** below |
+| "show me the CNAME value for {domain}" | Read `verification.methods[0].record` from cached state |
+| "what's the status of {domain}?" | Read `status` from cached state |
+| "add metadata to {domain}" / "tag {domain} with {key}={value}" | See **Manage domain metadata** below |
+| "what metadata is on {domain}?" / "show metadata for {domain}" | Read `domain_metadata` from cached state |
+| "remove the {key} metadata from {domain}" | See **Manage domain metadata** below |
+
+For intents that don't match, ask the user to restate more specifically and list the supported operations.
+
+## What PATCH accepts
+
+The Management API accepts these fields on `PATCH /custom-domains/{id}`:
+
+- `tls_policy`
+- `custom_client_ip_header`
+- `relying_party_identifier`
+- `domain_metadata`
+
+The API **rejects** `type`, `domain`, `verification_method`. To change any of those, delete and recreate.
+
+## Set or change the default
+
+```bash
+auth0 api patch "custom-domains/default" --data '{"domain": "login.example.com"}'
+```
+
+The Auth0 CLI does not have a dedicated `auth0 domains default` subcommand; use the API passthrough above.
+
+Effects to explain to the user:
+- Notification-triggering Management API calls (password reset tickets, verification emails) will route through this domain when no `auth0-custom-domain` header is sent.
+- Email template links will use this domain by default.
+- Does not affect the `iss` claim on tokens issued for other custom domains on the same tenant; that's still determined per-request.
+
+Before applying, show the diff: `current default: {value or "(none)"}` → `new default: {new value}`.
+
+## Set the relying party identifier (passkeys)
+
+`relying_party_identifier` controls what domain passkeys bind to. Default (when unset) is the custom domain hostname itself. Set it explicitly when the custom domain is a subdomain but you want passkeys usable at the parent domain.
+
+### When users want this
+
+- Custom domain is `login.example.com`, but the app also runs at `www.example.com` and a native iOS app with Associated Domains. Setting `relying_party_identifier: "example.com"` lets a passkey created during login work across all three surfaces.
+- A B2B tenant serves multiple subdomains per customer and wants passkeys bound to the shared parent zone.
+
+The RPID must be a registrable suffix of the custom domain (you can't set `google.com` as the RPID of `login.example.com`). WebAuthn / passkey clients enforce this at registration time.
+
+### Execute the PATCH
+
+```bash
+auth0 api patch "custom-domains/<domainId>" --data '{
+  "relying_party_identifier": "example.com"
+}'
+```
+
+Before sending, show the diff: `current rpId: {value or "(default: domain hostname)"}` → `new rpId: {new value}`.
+
+### Consequences to explain
+
+- **Passkeys already registered against the old RPID stop working.** WebAuthn credentials are bound to the RPID at registration and cannot be re-mapped. Users with existing passkeys will need to register new ones on next login. Mention this before executing.
+- No DNS changes required. No re-verification needed. The change takes effect on the next authentication.
+
+### Clearing the RPID
+
+To revert to the default (RPID = custom domain hostname), PATCH with `null`:
+
+```bash
+auth0 api patch "custom-domains/<domainId>" --data '{
+  "relying_party_identifier": null
+}'
+```
+
+## Update TLS policy
+
+`tls_policy` governs the TLS posture for Auth0-managed certificate domains. Default and recommended value is `"recommended"`. Only set explicitly when a compliance mandate requires a specific policy.
+
+```bash
+auth0 api patch "custom-domains/<domainId>" --data '{
+  "tls_policy": "recommended"
+}'
+```
+
+No DNS change, no re-verification. Takes effect on the next handshake.
+
+## Configure the custom client IP header
+
+`custom_client_ip_header` tells Auth0 which request header carries the real client IP when traffic reaches Auth0 through a reverse proxy. Without this set, rate limiting and anomaly detection see the proxy's IP, not the end user's.
+
+### Valid values
+
+- `true-client-ip` — generic reverse proxy; Akamai uses this
+- `cf-connecting-ip` — Cloudflare
+- `x-forwarded-for` — most generic proxies, load balancers
+- `x-azure-clientip` — Azure Front Door
+
+Pick the value that matches what the proxy in front of Auth0 emits. Only one value at a time. If unsure, check the proxy's documentation for which header it populates with the original client IP.
+
+### Execute the PATCH
+
+```bash
+auth0 api patch "custom-domains/<domainId>" --data '{
+  "custom_client_ip_header": "cf-connecting-ip"
+}'
+```
+
+To clear, PATCH with `null`:
+
+```bash
+auth0 api patch "custom-domains/<domainId>" --data '{
+  "custom_client_ip_header": null
+}'
+```
+
+No DNS change, no re-verification. Takes effect on the next request.
+
+### Safety note
+
+Only set this when there really is a trusted proxy in front of Auth0. If no proxy is injecting the header, an attacker can spoof the configured header to forge client IPs for rate-limit / anomaly bypass. The correct pattern: the proxy strips any incoming instance of the header from the public internet and re-emits it with the true source IP.
+
+## Manage domain metadata
+
+Each custom domain can carry up to **10 key-value pairs** as `domain_metadata`, with keys and values limited to **255 characters each** (Auth0's standard metadata convention, matching user `app_metadata` / application metadata / session metadata).
+
+### Why users set domain metadata
+
+The primary use case is feeding context to Auth0 Actions. Actions triggers expose `event.custom_domain.domain_metadata` on several flows (post-login, credentials-exchange, send-phone-message, custom email providers). Common patterns:
+
+- Region tagging (`region: us-east`, `region: eu-west`) for routing in Actions
+- Brand tagging (`brand: acme`, `brand: widgetco`) for multi-brand MCD tenants
+- Environment tagging (`env: prod`, `env: staging`) for per-env behavior
+- Partner / customer identifiers for B2B flows
+
+Set the tag once on the domain; every authentication that hits that domain surfaces the tag to Actions without needing an extra lookup.
+
+### Read current metadata
+
+Metadata is returned as `domain_metadata` on the domain object. Load once at the start of the Manage existing domains flow (see top of this file); no extra call needed.
+
+```bash
+auth0 api get "custom-domains/<domainId>"
+```
+
+### Add or update metadata (canonical pattern: GET → merge → PATCH)
+
+Always read current metadata, merge the user's changes into it locally, and PATCH the full merged object. This is correct under any PATCH semantics (shallow-merge or full-replace) and is the pattern to use every time:
+
+1. GET current `domain_metadata` from the domain object (already cached from the start of this flow).
+2. Merge the user's changes into the existing object client-side.
+3. PATCH the full merged object.
+
+```bash
+auth0 api patch "custom-domains/<domainId>" --data '{
+  "domain_metadata": {
+    "region": "us-east",
+    "brand": "acme"
+  }
+}'
+```
+
+The body above should contain the full post-merge object, not just the changed keys.
+
+### Remove a key
+
+Omit the key from the merged object and PATCH the full result. Don't rely on `null`-as-delete — submit only the keys that should remain.
+
+```bash
+# Current: { "region": "us-east", "brand": "acme" }
+# User wants to drop "brand":
+auth0 api patch "custom-domains/<domainId>" --data '{
+  "domain_metadata": {
+    "region": "us-east"
+  }
+}'
+```
+
+To clear all metadata, PATCH with an empty object:
+
+```bash
+auth0 api patch "custom-domains/<domainId>" --data '{
+  "domain_metadata": {}
+}'
+```
+
+### Constraints to enforce in the skill
+
+Before any PATCH that writes metadata, check:
+- Total keys after the write must be **≤ 10**. If the user tries to add an 11th, refuse and list the current keys so they can choose which to drop.
+- Each key must be **≤ 255 characters**.
+- Each value must be **≤ 255 characters**.
+- Keys cannot contain UTF-8 private-use characters (Auth0 metadata convention).
+
+If any constraint would be violated, block the write and surface the specific violation; don't rely on the API error message.
+
+### Display format
+
+When the user asks to see metadata:
+
+```text
+Metadata on login.example.com (2/10 keys used):
+
+  region   us-east
+  brand    acme
+```
+
+If no metadata is set, say that explicitly rather than showing an empty block.
+
+## List output format
+
+When the user asks "list" or "show my domains":
+
+```text
+Custom domains on this tenant (3):
+
+  login.example.com         ready                 Auth0-managed  DEFAULT
+  login-eu.example.com      ready                 Auth0-managed
+  login-legacy.example.com  pending_verification  Self-managed
+
+  (run the Troubleshoot verification flow to troubleshoot login-legacy.example.com)
+```
+
+## Batch multiple changes
+
+If the user requests several changes in one session ("set the rpId on A to example.com, make B the default, add metadata to C"), stage them and apply as a batch. Show the consolidated diff before executing. Per-domain fields (`tls_policy`, `custom_client_ip_header`, `relying_party_identifier`, `domain_metadata`) can all be merged into a single PATCH per domain to avoid multiple round-trips.
+
+For deletes, route to the Remove a custom domain flow rather than handling here. For cert-type changes, the API rejects `type` on PATCH; route to delete + recreate.
+
+## Scope note
+
+Changes made here don't write to DNS. None of the supported PATCH fields (`tls_policy`, `custom_client_ip_header`, `relying_party_identifier`, `domain_metadata`) change the CNAME or TXT verification record, so no re-verification is needed after any operation here.
+
+---
+
+# Check Domain Health
+
+Read-only diagnosis of the tenant's custom domain configuration. No writes. Answers: "is my setup still working?" and "what would block me from doing X?"
+
+This is the safe starter capability. Run it before other capabilities when the user isn't sure what's wrong or just wants a status check.
+
+## Pre-flight: surface the active tenant
+
+Even though this capability is read-only, the data the user sees depends entirely on which tenant the Auth0 CLI is pointed at. Show it explicitly so the report header is unambiguous.
+
+```bash
+auth0 tenants list
+```
+
+Surface the active tenant to the user and confirm it's the one they want checked. If it's wrong, have them run `auth0 tenants use <tenant-name>`, then proceed. Include the tenant name in the final health report so the output is self-describing.
+
+## Checks (run in parallel)
+
+### 1. List custom domains on the tenant
+
+```bash
+auth0 api get "custom-domains"
+```
+
+Pull for each: `domain`, `custom_domain_id`, `status`, `type`, `primary`.
+
+### 2. Fetch the tenant default
+
+```bash
+auth0 api get "tenants/settings"
+```
+
+Read `default_custom_domain_id`. Cross-reference against the domain list from check 1.
+
+### 3. For each domain, compare DNS to expected
+
+For each domain in the list, dig the CNAME and compare to the expected verification record. The expected value is in `verification.methods[0].record` on each domain object.
+
+```bash
+dig +short CNAME login.example.com
+```
+
+For self-managed domains, the expected record is a TXT, not a CNAME:
+
+```bash
+dig +short TXT login.example.com
+```
+
+### 4. Check NS resolution from an external resolver
+
+Cross-check the user's local resolver against a public resolver to catch propagation lag:
+
+```bash
+dig +short @8.8.8.8 CNAME login.example.com
+```
+
+Mismatch between local and external means propagation is in progress; the domain may show `ready` in Auth0 but some clients won't yet see the right record.
+
+### 5. Reachability and TLS certificate probe
+
+`status: ready` in Auth0 confirms Auth0's side is wired up, but it doesn't confirm the domain is reachable from the public internet right now, or that the TLS handshake succeeds. A proxy/CDN misconfiguration, a firewall rule, or an expired cert on a self-managed setup will all pass check 3 and still be broken for end users.
+
+For each `ready` domain, probe HTTPS:
+
+```bash
+curl -sS -o /dev/null -w "%{http_code} %{ssl_verify_result}\n" \
+  --max-time 10 "https://login.example.com/"
+```
+
+Expected: a `200`, `302`, or `404` with `ssl_verify_result: 0`. Any of these confirms TLS handshake succeeded and Auth0 responded. Problem signals:
+- **Timeout** or connection refused: a proxy/firewall is blocking, or the DNS points somewhere Auth0 no longer serves.
+- **`ssl_verify_result` non-zero, or curl returns SSL error**: cert is expired, mismatched, or self-signed. On Auth0-managed, this usually means renewal has failed — check 6 below.
+- **Response from a non-Auth0 origin** (e.g., a WAF block page, a "site not found" page from a CDN): the CNAME is correct but an in-path proxy is intercepting.
+
+Also fetch the cert's expiry so the report can surface upcoming renewals or detect failed renewals:
+
+```bash
+echo | openssl s_client -connect login.example.com:443 -servername login.example.com 2>/dev/null \
+  | openssl x509 -noout -dates
+```
+
+Report `notAfter`. For Auth0-managed certs, normal lifecycle is ~90 days; a `notAfter` within 14 days on a `ready` domain that looks DNS-healthy is normal (renewal is imminent). A `notAfter` in the past or within 48 hours with no sign of a new cert is a renewal failure — flag it.
+
+### 6. Flag silent renewal-breakers on `ready` domains
+
+A domain that's `ready` today can still fail certificate renewal in the next ~3-month cycle if DNS was touched after initial verification. The signals for this are already captured in checks 3 and 5; promote them to a distinct renewal-risk line in the report when present:
+
+- DNS mismatch on a `ready` domain (check 3 ✗): the record was removed or changed post-verification. Renewal will fail at the next cycle.
+- Proxied / orange-cloud CNAME on a `ready` domain: the live record looks like a CDN hostname instead of `edge.tenants.auth0.com`. Detect by inspecting the CNAME resolution chain.
+- Cert `notAfter` in the past on a `ready` domain (check 5): renewal has already failed.
+
+These cases are not reachable-today failures but they will page someone in a future on-call shift; the health check is the right place to surface them early.
+
+### 7. Credit-card-on-file note (Free tier only)
+
+Do not probe speculatively by attempting a create. If the tenant has zero custom domains and the user is asking whether adding one will work, mention the Free-tier requirement in the output report:
+
+```text
+Note: Free-tier tenants need a credit card on file at
+Dashboard → Tenant Settings → Billing to create custom domains. The card is
+not charged. If custom domain creation returns 403, this is usually the cause.
+```
+
+## Output format
+
+Structured checklist with pass/fail/warn per item. Lean on visual contrast (✓, ✗, ⚠) and keep the output scannable:
+
+```text
+Tenant: acme-prod
+
+Custom domains (3):
+
+  login.example.com                 ✓ ready
+    DNS match                       ✓ CNAME → tenant.edge.tenants.auth0.com
+    Reachability (HTTPS)            ✓ 302, TLS valid
+    Cert expires                    2026-08-03 (90 days)
+    Certificate type                Auth0-managed
+    Default for tenant              ✓ YES
+
+  login-eu.example.com              ⚠ ready, but renewal at risk
+    DNS match                       ✗ CNAME now points to a Cloudflare proxy
+    Reachability (HTTPS)            ✓ 302, TLS valid
+    Cert expires                    2026-06-10 (36 days)
+    Certificate type                Auth0-managed
+    Default for tenant              no
+    ⚠ DNS was changed after verification; next renewal will fail
+
+  login-legacy.example.com          ⚠ pending_verification
+    DNS match                       ✗ no CNAME found at login-legacy.example.com
+    Reachability (HTTPS)            ✗ connection refused
+    Certificate type                Self-managed
+    Default for tenant              no
+
+Tenant settings:
+  Default custom domain             ✓ login.example.com
+
+Summary:
+  • 1 of 3 domains fully healthy
+  • login-eu.example.com: DNS change will break the next cert renewal → run Troubleshoot verification to restore the record
+  • login-legacy.example.com: never finished verifying → run Troubleshoot verification
+```
+
+## Interpreting results
+
+- **`ready` + DNS ✓ + reachable ✓ + cert valid**: healthy. Auth0-managed renewal will happen on schedule.
+- **`ready` + DNS ✗ (any reason: missing, proxied, flattened)**: reachable today, but Auth0 can't re-validate at the next renewal cycle (~90 days). Flag as renewal-at-risk; route to Troubleshoot verification to restore the record now.
+- **`ready` + DNS ✓ + reachable ✗**: Auth0's side is correct but something in-path is blocking (firewall, WAF, proxy misroute). Look at the curl error and the CNAME resolution chain to pinpoint.
+- **`ready` + cert `notAfter` in the past**: renewal has already failed. This is an active outage for TLS clients, even if `status` still reads `ready`. Route to Troubleshoot verification; contact support if the record is correct and cert still won't renew.
+- **`pending_verification` + DNS ✓**: record is correct but Auth0 hasn't finished verifying, or verification was never triggered. If it's been more than a few minutes, route to Troubleshoot verification.
+- **`pending_verification` + DNS ✗**: record is missing. Route to Set up a custom domain (from the "write the record" step) to put it back, then verify.
+- **`disabled`**: rare; indicates an internal state mismatch. Usually requires support.
+
+## When to recommend other capabilities
+
+Use the health check output to point the user to the next capability:
+
+- DNS mismatch or verification failure → the Troubleshoot verification flow
+- `ready` domain flagged renewal-at-risk (DNS changed post-verification, proxied CNAME, cert nearing/past expiry) → the Troubleshoot verification flow, now rather than later
+- Reachability ✗ despite correct DNS → the Troubleshoot verification flow; start from in-path proxies and firewalls
+- No default set and multiple domains → the Manage existing domains flow
+- Domains in `pending_verification` past normal window → the Troubleshoot verification flow
+- User wants to add another domain or clean up an unused one → the Set up a custom domain flow or the Remove a custom domain flow
+
+---
+
+# Troubleshoot Verification
+
+A custom domain that's stuck in `pending_verification`, or verification that keeps failing. Walks a diagnostic ladder; fixes what's fixable; falls back to waiting or opening a support ticket when nothing else works.
+
+## Inputs
+
+- The `custom_domain_id` or the domain name (look up the ID via `auth0 api get "custom-domains"` if only the name is known).
+- Confirmation that the user has already gone through the Set up a custom domain flow at some point (if not, route them to the Set up a custom domain flow first).
+
+## Pre-flight: surface the active tenant
+
+Before reading domain state or retrying verification, show the active Auth0 CLI tenant to the user. The CLI is single-tenant, and troubleshooting a domain on the wrong tenant will produce confusing results (404 on the ID, or a different domain's verification state).
+
+```bash
+auth0 tenants list
+```
+
+Surface the active tenant and ask the user to confirm it is the one hosting the broken domain. If it's wrong, stop and have them run `auth0 tenants use <tenant-name>`, then re-confirm before loading state. This applies even for read-only diagnostic calls — wrong-tenant reads waste time and mislead; the retry-verify call at the end is an actual write that must hit the right tenant.
+
+## Get the current state from Auth0
+
+```bash
+auth0 api get "custom-domains/<domainId>"
+```
+
+From the response, pull:
+- `status` (should say `pending_verification` or `disabled`)
+- `verification.methods[0].record` (the expected CNAME value)
+- `verification.methods[0].domain` (the name the record should sit at, typically the custom domain itself)
+- `type` (Auth0-managed vs self-managed; if self-managed, the verification is TXT not CNAME)
+
+## Diagnostic ladder
+
+Run these checks in order. Stop at the first one that identifies a problem; fix it; retry verification; if still stuck, continue to the next check.
+
+### 1. Compare actual DNS to expected
+
+```bash
+dig +short CNAME login.example.com
+```
+
+Compare the result to `verification.methods[0].record`. Common mismatches:
+
+- **Typo**: one character off. Fix in the DNS provider and wait for propagation.
+- **Trailing dot difference**: `tenant.edge.tenants.auth0.com.` vs `tenant.edge.tenants.auth0.com`. Both are technically valid in DNS but some registrars are picky. Try removing the trailing dot if present.
+- **Empty result**: no CNAME exists at the target name. The record was never added or was deleted. Route back to the Set up a custom domain flow from the "write the CNAME" step.
+- **Completely different value**: another record exists at that name (maybe pointing to a previous provider or an internal service). Confirm with user before replacing.
+
+### 2. Check for DNS proxy
+
+If the result of `dig` looks like a generic CDN hostname (Cloudflare, Fastly, Akamai) rather than the `edge.tenants.auth0.com` pattern, the record is likely behind a proxy:
+
+- **Cloudflare orange cloud**: In the Cloudflare dashboard, the record must be DNS-only (grey cloud), not proxied (orange). Tell the user to toggle it off. Or, if Cloudflare MCP is connected, update `proxied: false` directly.
+- **Other proxies**: Any CDN or reverse proxy layered on the CNAME will break Auth0 verification and certificate renewal. The record needs a direct DNS CNAME pointing at the Auth0 edge hostname.
+
+### 3. Check for CNAME flattening
+
+Some providers (Cloudflare, Gandi LiveDNS, others) optionally flatten CNAMEs at the apex or across records. Flattening rewrites the CNAME to A/AAAA records at resolution time, which breaks what Auth0 sees.
+
+- Ask the user to check their zone settings for any "CNAME flattening" or "CNAME at apex" option.
+- This is zone-level, not per-record, so the user has to toggle it at the zone.
+
+### 4. Check for conflicting record types
+
+Per DNS RFC, a CNAME cannot coexist with other record types at the same name. If there's an A, AAAA, MX, or TXT record at the target name, the CNAME may be silently dropped or fail to create:
+
+```bash
+dig login.example.com ANY
+```
+
+If other records are present, either delete them (if not in use) or pick a different subdomain for the custom domain.
+
+### 5. Check propagation state
+
+Fresh records can take 5-60 minutes to propagate. Cross-check with a non-local resolver:
+
+```bash
+dig +short @8.8.8.8 CNAME login.example.com
+dig +short @1.1.1.1 CNAME login.example.com
+```
+
+If these return the correct value but the user's local resolver doesn't, propagation is still in progress. Wait 15-30 minutes and retry verification.
+
+### 6. Check for private-zone issue (Route 53)
+
+On AWS Route 53, private hosted zones are resolvable only from within a VPC. If the user's root domain is managed in a private hosted zone, Auth0 can't see the record from the public internet:
+
+```bash
+aws route53 list-hosted-zones-by-name --dns-name example.com --max-items 5
+```
+
+Look for a `PrivateZone: true` entry. If that's the zone the record went into, the fix is to move the record to a public zone or delegate the subdomain to a public zone.
+
+### 7. Retry verification
+
+After applying a fix, trigger verification:
+
+```bash
+auth0 api post "custom-domains/<domainId>/verify"
+```
+
+Then poll for up to ~5 minutes:
+
+```bash
+auth0 api get "custom-domains/<domainId>"
+```
+
+## What not to do
+
+- **Do not delete and recreate the domain.** This resets the provisioning state and can cause a service interruption for tokens already issued. If the user mentions they've already done this once or twice, ask them to stop and wait.
+- **Do not retry verification in a tight loop.** Auth0 rate-limits verification attempts. The 5-10-20-30-60 second backoff is the right pattern.
+
+## When to open a support ticket
+
+Recommend the user file a support ticket if:
+- The CNAME is correct in DNS from multiple external resolvers, not proxied, not flattened, and verification has been failing for 24+ hours
+- Multiple create/delete cycles have been performed (the domain may be in a state only support can resolve)
+- The domain status is `disabled` rather than `pending_verification` (rare; indicates an internal state mismatch)
+
+For general guidance beyond this ladder, see the Verification Troubleshooting section in Advanced Topics below.
+
+---
+
+# Remove a Custom Domain
+
+Delete a custom domain from Auth0 and clean up the CNAME record in the user's DNS. Destructive; always confirm before executing and warn about dependent systems.
+
+## Inputs
+
+- The domain name or `custom_domain_id` to remove.
+- Tenant context.
+
+## Pre-flight: confirm the active tenant
+
+Delete is irreversible. Before anything else, confirm the Auth0 CLI is pointed at the intended tenant.
+
+```bash
+auth0 tenants list
+```
+
+Show the active tenant to the user and require explicit confirmation ("about to delete from `acme-prod`; confirm?"). If wrong, stop and have the user run `auth0 tenants use <tenant-name>`, then re-confirm. Deleting from the wrong tenant is not recoverable; the domain and its certificate state are gone.
+
+## Safety checks before deleting
+
+Run these in parallel. Report every flag that comes up; let the user confirm with full awareness.
+
+### 1. Is this the default custom domain?
+
+```bash
+auth0 api get "tenants/settings"
+```
+
+If `default_custom_domain_id` matches the domain being deleted, warn:
+
+```text
+login.example.com is the default custom domain for this tenant. Deleting it
+means notification-triggering Management API calls will route through
+your-tenant.auth0.com until you set a new default via the Manage existing domains flow.
+```
+
+The user can proceed anyway, but they should plan to set a new default right after.
+
+### 2. Is this the only custom domain?
+
+```bash
+auth0 api get "custom-domains"
+```
+
+If the list has only this one domain, warn:
+
+```text
+This is the only custom domain on the tenant. After deletion, all traffic will
+use your-tenant.auth0.com. Apps and SDKs currently pointing at
+login.example.com will start failing with iss claim mismatches.
+```
+
+### 3. Are applications or tenant settings referencing this domain?
+
+There is no single Management API call that surfaces "everything that references this domain." What we can scan is partial; what we can't scan has to be hand-checked. Default behavior: **do not scan**. Show the user the full list of places a reference could live, and let them choose.
+
+#### Show the reference-sites list and ask
+
+Output a complete inventory of surfaces the domain could appear on, grouped by whether the scan can reach them. Then ask which scan tier to run.
+
+```text
+Before deleting login.example.com, here's where a reference to it could live:
+
+Reachable via Auth0 Management API:
+  • Application client configurations (callbacks, logout URLs, web origins, allowed origins, initiate_login_uri, client_metadata)
+  • Tenant settings (support_url, default_redirection_uri, change_password.html, guardian_mfa_page.html, error_page.url)
+  • Email provider default "from" address
+  • Email template "from" and "body" fields (per-template overrides)
+  • Actions code
+  • Rules code (legacy)
+  • Hooks code (legacy)
+  • Branding page templates (Liquid)
+  • Organizations (branding logo URLs)
+  • Connections (options: login URLs, custom scripts, enterprise IdP URLs)
+  • Resource server identifiers
+  • Log stream webhook URLs
+  • Prompt / ACUL custom text
+
+Not reachable by the skill (you'll need to check these yourself):
+  • SDK configurations in your applications (domain / issuerBaseURL)
+  • JWT validators in backend APIs (iss claim allowlist)
+  • SAML SP metadata saved at any service provider that federates here
+  • Terraform / IaC / CI-CD config
+  • External tools (monitoring, Zapier, Slack bots, scripts)
+  • Email DNS records (SPF / DKIM / DMARC) if the from address embeds the custom domain
+
+Three options:
+  1. Skip the scan (I've already checked; proceed to confirm)
+  2. Quick scan (clients, tenant settings, email provider + templates — ~1-3s on typical tenants, ~5-10s on large enterprise tenants)
+  3. Deep scan (everything in the Reachable list above — slower, noisier, more false positives)
+
+Which one?
+```
+
+Wait for the user to choose. Default posture: assume option 1 unless the user asks for a scan — it's their audit to run.
+
+#### Option 1: skip
+
+Proceed to **Confirm**.
+
+#### Option 2: quick scan (tier 1)
+
+Fire these in parallel. Stop and report as soon as they all return.
+
+| Call | Field(s) to grep for the custom domain |
+|---|---|
+| `GET /clients` (paginated, fan out across pages in parallel once page 1 reveals total) | `callbacks`, `allowed_logout_urls`, `web_origins`, `allowed_origins`, `initiate_login_uri`, JSON-stringified `client_metadata` |
+| `GET /tenants/settings` | `support_url`, `default_redirection_uri`, `change_password.html`, `guardian_mfa_page.html`, `error_page.url` |
+| `GET /emails/provider` | `default_from_address` |
+| `GET /email-templates/{name}` × 11 (`verify_email`, `verify_email_by_code`, `reset_email`, `reset_email_by_code`, `welcome_email`, `blocked_account`, `stolen_credentials`, `enrollment_email`, `mfa_oob_code`, `user_invitation`, `async_approval`) | On responses that return 200 AND `enabled: true`: grep `from` and `body`. Drop 404s (never customized) and `enabled: false` (won't send). |
+
+**Parallelism is required.** Sequential, this is 15+ calls and noticeably slow. With parallel fan-out (e.g., `xargs -P`, shell `&` + `wait`, or the agent firing tool calls in one turn) the total is bounded by the slowest single call.
+
+After the scan, report hits with specific locations, then always append the reminder:
+
+```text
+Quick scan found {N} references:
+  • Client "Web App"                      callbacks[2]
+  • Client "Mobile App"                   allowed_logout_urls[0]
+  • Email template "reset_email"          from: "no-reply@login.example.com"
+  • Tenant setting                        support_url
+
+Note: this was the quick scan. Still unchecked in Auth0:
+  Actions, Rules, Hooks, Branding templates, Organizations, Connection options,
+  Resource server identifiers, Log stream webhooks, Prompt / ACUL custom text.
+Run the deep scan if you want me to check those, or proceed if you've already audited them.
+
+And regardless of scan depth, check these yourself (not reachable via API):
+  • SDK configs (domain / issuerBaseURL)
+  • Backend JWT validators
+  • SAML SP metadata
+  • Terraform / IaC / CI-CD
+  • Third-party integrations
+  • Email DNS (SPF / DKIM / DMARC if from address embeds this domain)
+```
+
+#### Option 3: deep scan (tier 2)
+
+Fire everything in the Reachable list above in parallel, in addition to tier 1:
+
+| Call | Field(s) to grep |
+|---|---|
+| `GET /actions/actions` (paginated) | `code` |
+| `GET /rules` (legacy; skip cleanly if empty) | `script` |
+| `GET /hooks` (legacy; skip cleanly if empty) | `script` |
+| `GET /branding/templates/universal-login` | `template` (Liquid HTML) |
+| `GET /organizations` (paginated) + `GET /organizations/{id}/branding` per org | `logo_url`, `colors`, `branding.logo_url` |
+| `GET /connections` (paginated) | `options` JSON stringified |
+| `GET /resource-servers` (paginated) | `identifier` |
+| `GET /log-streams` | sink URLs (`sink.httpEndpoint`, webhook URLs) |
+| `GET /prompts/{prompt}/custom-text/{lang}` for configured prompts | body text fields |
+
+Time budget the deep scan to ~30s; if it's still running past that, surface partial results with a note that scanning timed out on {list of pending endpoints}.
+
+Expect false positives — string matches inside unrelated JSON fields (user-chosen connection names, org slugs, etc.). Report the hit with the containing JSON path so the user can judge.
+
+After the deep scan, always append the "not reachable via API" reminder from option 2. The scan is never complete; the user still has to check the external surfaces themselves.
+
+## Confirm
+
+Show the full impact and ask for explicit yes. Include the current CNAME target value (pulled from `verification.methods[0].record`) so the user can confirm they're deleting the right record. Reflect the scan tier they chose in step 3:
+
+```text
+Ready to delete login.example.com from tenant acme-prod.
+
+Current record:
+  CNAME login.example.com → tenant.edge.tenants.auth0.com
+
+This will:
+  • Remove the custom domain from Auth0 (irreversible)
+  • Invalidate the Auth0-managed certificate
+  • Delete the CNAME from DNS (via Route 53 / Cloudflare / etc.; see below)
+  • [if default] unset the tenant's default custom domain
+
+Flags:
+  • This is the tenant's default custom domain
+  • {one of}
+      — No scan was run; you confirmed you've already audited.
+      — Quick scan found 3 references: [list]. Deeper surfaces and external
+        systems not checked.
+      — Deep scan found 5 references: [list]. External systems not checked.
+
+Proceed? [yes / no]
+```
+
+If the scan found references, pause here and let the user decide whether to fix them first or accept the breakage. A "yes" after seeing scan hits is explicit acknowledgement; do not nag further.
+
+## Delete in Auth0
+
+```bash
+auth0 api delete "custom-domains/<domainId>" --force
+```
+
+`--force` is important: without it the CLI prints its own confirmation prompt, which duplicates the skill's confirmation and hangs in non-interactive contexts. The skill has already obtained explicit yes from the user, so pass `--force`.
+
+Note the current CNAME target value before deletion; after deletion, the Management API no longer returns it, so if the user wants to recreate later they'd need the new value from a fresh create.
+
+## Clean up the DNS record
+
+**Always attempt automated cleanup first.** Detect the provider from the root domain's NS records and route by tier, same as the Set up a custom domain flow. The skill should do the cleanup for the user, not ask the user to do it manually, whenever the provider tier supports automation and the required credentials are present.
+
+### Automated path (preferred)
+
+- **Tier 1 Cloudflare (via MCP)**: If the Cloudflare MCP is connected, `search("dns records")` then `execute()` a script that calls `cf.dns.records.delete(record_id)` for the CNAME at the target name. No user action needed. Full mechanics: see Cloudflare section below.
+- **Tier 2 Route 53**: If AWS credentials are configured (`aws sts get-caller-identity` succeeds), run `aws route53 change-resource-record-sets` with action `DELETE` (requires the full record set to match). Use `list-resource-record-sets` first to get the exact current value, then poll `get-change` until `INSYNC`. No user action needed. Full mechanics including the exact-match DELETE gotcha: see Route 53 section below.
+- **Tier 3 Azure DNS**: If the Azure CLI is signed in (`az account show` succeeds), run `az network dns record-set cname delete --resource-group my-rg --zone-name example.com --name login --yes`. No user action needed. Full mechanics: see Azure DNS section below.
+
+Open only the sub-file matching the detected provider; don't load all three.
+
+### Manual fallback
+
+Drop to manual guidance only when automation isn't possible — Tier 4 providers (GoDaddy, Namecheap, Hover, etc.), or Tiers 1-3 where the required credentials / MCP aren't available and the user can't authorize them right now. In that case, give clear step-by-step directions:
+
+```text
+Couldn't remove the DNS CNAME automatically ({reason: no Cloudflare MCP connection /
+no AWS credentials / etc.}). Remove it manually:
+
+1. Go to: {dashboard deep-link for the detected provider}
+2. Find the CNAME record:
+     Name:  login.example.com
+     Value: tenant.edge.tenants.auth0.com
+3. Delete it.
+
+Reply 'done' when removed so I can confirm the DNS record is gone, or 'skip' if
+you want to leave it in place (harmless but clutters your zone).
+```
+
+Use the provider cheat-sheet in the Manual Guided section below for the right deep-link and UI labels. On "done", run `dig +short CNAME login.example.com` to verify the record is gone; warn the user if it still resolves (propagation can take a few minutes).
+
+### Why automate by default
+
+The CNAME is now orphaned: it points at an Auth0 edge hostname that no longer serves the user's domain. Leaving it in place is harmless but clutters the zone and can cause confusion later. Auto-cleanup is the right default; manual is an exception path.
+
+## If the user is keeping the domain but switching tenants
+
+Different flow; don't run this capability. They should:
+1. Delete from the original tenant (Auth0 won't let the same domain live on two tenants).
+2. Leave the DNS record in place.
+3. Create the domain on the new tenant (the Set up a custom domain flow). The CNAME target value will change; they'll need to update the existing DNS record rather than add a new one.
+
+## Post-delete reminder
+
+After successful deletion, tell the user:
+
+```text
+Deleted login.example.com from Auth0.
+DNS CNAME removed via {provider}.
+
+Next steps (outside this skill's scope):
+  • Update SDK `domain` / `issuerBaseURL` config back to your-tenant.auth0.com
+    in any app that was pointing at login.example.com
+  • Update application callback URLs that reference the old custom domain
+  • [if was default] set a new default custom domain via the Manage existing domains flow
+```
diff --git a/main/.mintlify/skills/auth0/references/feature-dpop/index.md b/main/.mintlify/skills/auth0/references/feature-dpop/index.md
new file mode 100644
index 0000000000..52925eb240
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/feature-dpop/index.md
@@ -0,0 +1,544 @@
+# Auth0 DPoP (Device-Bound Tokens)
+
+Bind access tokens to the client's cryptographic key so stolen tokens cannot be replayed.
+
+---
+
+## Overview
+
+### What is DPoP?
+
+DPoP (Demonstrating Proof-of-Possession) is an OAuth 2.0 mechanism defined in
+[RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449) that cryptographically
+binds access tokens to a client-held key pair. Each API request includes a
+short-lived signed JWT (the DPoP proof) that proves the sender holds the private
+key — a stolen token alone cannot be replayed by an attacker.
+
+### When to Use DPoP
+
+- Protecting high-value API calls against token theft and replay attacks
+- Meeting security or compliance requirements that mandate sender-constrained tokens
+- Any SPA or Vanilla JS app calling a protected Auth0 API with elevated security needs
+
+### When NOT to Use DPoP
+
+- **SSR / server-side environments** — DPoP relies on a private key held in the browser; it cannot be safely used server-side (Next.js, Nuxt, etc.)
+- **APIs that don't support DPoP** — the resource server must be configured to accept DPoP token dialect; Bearer-only APIs will reject DPoP proofs
+- **Flows requiring token sharing** — DPoP tokens are bound to a single key pair and cannot be forwarded to or reused by another client
+
+### Requirements
+
+- Auth0 tenant with DPoP-capable authorization server
+- API resource server with DPoP token dialect enabled
+- A browser SPA using one of: `@auth0/auth0-vue`, `@auth0/auth0-react`,
+  `@auth0/auth0-angular`, or `@auth0/auth0-spa-js`
+- HTTPS in production (required by Auth0 for DPoP)
+
+### Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| DPoP Proof | A short-lived signed JWT attached to each request proving key possession |
+| DPoP Nonce | A server-issued value that must be included in the proof to prevent replay |
+| `useDpop: true` | SDK option that enables automatic DPoP proof generation |
+| `createFetcher()` | SDK helper that returns a `fetch`-compatible function handling proofs automatically |
+| `UseDpopNonceError` | Error thrown when the server rotates its nonce mid-flight; retry with the new nonce |
+
+---
+
+## Step 1: Enable DPoP on Your API
+
+### Via Auth0 Dashboard
+
+1. Go to **Applications → APIs**
+2. Select the API your SPA calls
+3. Under the **Settings** tab, confirm the API identifier matches your `audience`
+4. No additional toggle is needed in the dashboard — DPoP is enabled per-request
+   by the client when the API resource server is configured to accept DPoP tokens
+
+### Via Auth0 CLI
+
+```bash
+# Inspect current resource server settings
+auth0 api get "resource-servers" | jq '.[] | select(.identifier == "https://your-api-identifier")'
+
+# Enable DPoP token dialect on the API
+auth0 api patch "resource-servers/{API_ID}" \
+  --data '{"token_dialect": "access_token_authz"}'
+```
+
+> Replace `{API_ID}` with the ID returned from the GET call above.
+
+### Same configuration in Terraform / MCP
+
+Sender-constraining is set on the resource server (via a `proof_of_possession`
+setting with `mechanism: "dpop"`) and, for a mandatory client, on the client.
+There is no tenant-wide DPoP toggle. The loaded tooling reference has the exact
+syntax:
+- CLI: `auth0 api patch resource-servers/{API_ID}` with the `proof_of_possession` payload
+- Terraform: `auth0_resource_server` `proof_of_possession` block + `auth0_client` `require_proof_of_possession`
+- MCP: `auth0_update_resource_server` accepts `proof_of_possession`; the client-side toggle is **not** exposed by MCP — set it via CLI or Terraform.
+
+---
+
+## Step 2: Configure Your Application
+
+### Common pattern across all frameworks
+
+1. Add `useDpop: true` to your Auth0 client/provider configuration alongside your `audience`
+2. Use `createFetcher()` instead of attaching tokens manually — the SDK handles
+   proof generation, nonce management, and header injection for you
+3. Handle `UseDpopNonceError` in cases where the server rotates its nonce
+
+### Environment variables
+
+Ensure your `.env` includes the API audience:
+
+```bash
+# Vite
+VITE_AUTH0_DOMAIN=your-tenant.auth0.com
+VITE_AUTH0_CLIENT_ID=your-client-id
+VITE_AUTH0_AUDIENCE=https://your-api-identifier
+```
+
+---
+
+## Framework Examples
+
+### Vue.js
+
+Uses `@auth0/auth0-vue`.
+
+#### 1. Enable DPoP in plugin config
+
+```typescript
+// src/main.ts
+import { createApp } from 'vue';
+import { createAuth0 } from '@auth0/auth0-vue';
+import App from './App.vue';
+
+const app = createApp(App);
+
+app.use(
+  createAuth0({
+    domain: import.meta.env.VITE_AUTH0_DOMAIN,
+    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+    authorizationParams: {
+      redirect_uri: window.location.origin,
+      audience: import.meta.env.VITE_AUTH0_AUDIENCE
+    },
+    useDpop: true
+  })
+);
+
+app.mount('#app');
+```
+
+#### 2. Make DPoP-protected API calls
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useAuth0, UseDpopNonceError } from '@auth0/auth0-vue';
+
+const { createFetcher } = useAuth0();
+const data = ref(null);
+const error = ref<string | null>(null);
+
+// Create a DPoP-aware fetcher bound to your API base URL
+const apiFetch = createFetcher({
+  baseUrl: 'https://your-api.example.com'
+});
+
+const fetchData = async () => {
+  error.value = null;
+  try {
+    const response = await apiFetch('/data');
+    data.value = await response.json();
+  } catch (err) {
+    if (err instanceof UseDpopNonceError) {
+      // Server rotated its nonce — retry once
+      const response = await apiFetch('/data');
+      data.value = await response.json();
+    } else {
+      error.value = (err as Error).message;
+    }
+  }
+};
+</script>
+
+<template>
+  <div>
+    <button @click="fetchData">Fetch Data</button>
+    <div v-if="error" class="error">{{ error }}</div>
+    <pre v-if="data">{{ JSON.stringify(data, null, 2) }}</pre>
+  </div>
+</template>
+```
+
+#### 3. POST / PUT / DELETE requests
+
+```typescript
+// Pass standard fetch options as the second argument
+const response = await apiFetch('/items', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ name: 'example' })
+});
+```
+
+#### 4. Multiple APIs with separate fetchers
+
+```typescript
+const { createFetcher } = useAuth0();
+
+const ordersApi = createFetcher({ baseUrl: 'https://orders.example.com' });
+const inventoryApi = createFetcher({ baseUrl: 'https://inventory.example.com' });
+```
+
+#### 5. Manual DPoP management (advanced)
+
+```typescript
+import { useAuth0 } from '@auth0/auth0-vue';
+
+const { generateDpopProof, getDpopNonce, setDpopNonce } = useAuth0();
+
+// Generate a proof manually (e.g. for a custom fetch wrapper)
+const proof = await generateDpopProof({
+  url: 'https://your-api.example.com/data',
+  method: 'GET',
+  nonce: getDpopNonce()
+});
+
+const response = await fetch('https://your-api.example.com/data', {
+  headers: {
+    Authorization: `DPoP ${accessToken}`,
+    DPoP: proof
+  }
+});
+
+// Store a server-issued nonce for subsequent requests
+const newNonce = response.headers.get('DPoP-Nonce');
+if (newNonce) setDpopNonce(newNonce);
+```
+
+---
+
+### React
+
+Uses `@auth0/auth0-react`.
+
+#### 1. Enable DPoP in provider config
+
+```tsx
+// src/main.tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { Auth0Provider } from '@auth0/auth0-react';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <Auth0Provider
+      domain={import.meta.env.VITE_AUTH0_DOMAIN}
+      clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
+      authorizationParams={{
+        redirect_uri: window.location.origin,
+        audience: import.meta.env.VITE_AUTH0_AUDIENCE
+      }}
+      useDpop={true}
+    >
+      <App />
+    </Auth0Provider>
+  </React.StrictMode>
+);
+```
+
+#### 2. Make DPoP-protected API calls
+
+```tsx
+import { useAuth0, UseDpopNonceError } from '@auth0/auth0-react';
+import { useState, useMemo } from 'react';
+
+export function DataFetcher() {
+  const { createFetcher } = useAuth0();
+  const [data, setData] = useState(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const apiFetch = useMemo(
+    () => createFetcher({ baseUrl: 'https://your-api.example.com' }),
+    [createFetcher]
+  );
+
+  const fetchData = async () => {
+    setError(null);
+    try {
+      const response = await apiFetch('/data');
+      setData(await response.json());
+    } catch (err) {
+      if (err instanceof UseDpopNonceError) {
+        // Server rotated its nonce — retry once
+        const response = await apiFetch('/data');
+        setData(await response.json());
+      } else {
+        setError((err as Error).message);
+      }
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={fetchData}>Fetch Data</button>
+      {error && <div className="error">{error}</div>}
+      {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
+    </div>
+  );
+}
+```
+
+#### 3. Memoize the fetcher to avoid re-creation
+
+```tsx
+import { useAuth0 } from '@auth0/auth0-react';
+import { useMemo } from 'react';
+
+export function useApiClient() {
+  const { createFetcher } = useAuth0();
+
+  return useMemo(
+    () => createFetcher({ baseUrl: 'https://your-api.example.com' }),
+    [createFetcher]
+  );
+}
+```
+
+#### 4. POST / PUT / DELETE requests
+
+```typescript
+const response = await apiFetch('/items', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ name: 'example' })
+});
+```
+
+---
+
+### Angular
+
+Uses `@auth0/auth0-angular`.
+
+#### 1. Enable DPoP in provider config
+
+**Standalone components (Angular 14+):**
+
+```typescript
+// src/app/app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideAuth0 } from '@auth0/auth0-angular';
+import { environment } from '../environments/environment';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAuth0({
+      domain: environment.auth0.domain,
+      clientId: environment.auth0.clientId,
+      authorizationParams: {
+        redirect_uri: window.location.origin,
+        audience: environment.auth0.audience
+      },
+      useDpop: true
+    })
+  ]
+};
+```
+
+**NgModule-based apps:**
+
+```typescript
+// src/app/app.module.ts
+import { AuthModule } from '@auth0/auth0-angular';
+
+@NgModule({
+  imports: [
+    AuthModule.forRoot({
+      domain: environment.auth0.domain,
+      clientId: environment.auth0.clientId,
+      authorizationParams: {
+        redirect_uri: window.location.origin,
+        audience: environment.auth0.audience
+      },
+      useDpop: true
+    })
+  ]
+})
+export class AppModule {}
+```
+
+#### 2. Make DPoP-protected API calls
+
+```typescript
+import { Component, inject, signal } from '@angular/core';
+import { AuthService, UseDpopNonceError } from '@auth0/auth0-angular';
+
+@Component({
+  selector: 'app-data',
+  template: `
+    <button (click)="fetchData()">Fetch Data</button>
+    <div *ngIf="error()">{{ error() }}</div>
+    <pre *ngIf="data()">{{ data() | json }}</pre>
+  `
+})
+export class DataComponent {
+  private auth = inject(AuthService);
+  data = signal<unknown>(null);
+  error = signal<string | null>(null);
+
+  // Created once — reused across all fetchData() calls so nonce state is preserved
+  private apiFetch = this.auth.createFetcher({
+    baseUrl: 'https://your-api.example.com'
+  });
+
+  async fetchData() {
+    this.error.set(null);
+    try {
+      const response = await this.apiFetch('/data');
+      this.data.set(await response.json());
+    } catch (err) {
+      if (err instanceof UseDpopNonceError) {
+        // Server rotated its nonce — retry once
+        const response = await this.apiFetch('/data');
+        this.data.set(await response.json());
+      } else {
+        this.error.set((err as Error).message);
+      }
+    }
+  }
+}
+```
+
+#### 3. POST / PUT / DELETE requests
+
+```typescript
+// Uses the same class-field fetcher — pass standard fetch options as the second argument
+const response = await this.apiFetch('/items', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ name: 'example' })
+});
+```
+
+---
+
+### auth0-spa-js (Vanilla JS)
+
+Uses `@auth0/auth0-spa-js` directly — suitable for Vanilla JS, Svelte, SolidJS,
+or any SPA not using a framework wrapper.
+
+#### 1. Initialize client with DPoP enabled
+
+```typescript
+import { createAuth0Client, UseDpopNonceError } from '@auth0/auth0-spa-js';
+
+const auth0 = await createAuth0Client({
+  domain: import.meta.env.VITE_AUTH0_DOMAIN,
+  clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+  authorizationParams: {
+    redirect_uri: window.location.origin,
+    audience: import.meta.env.VITE_AUTH0_AUDIENCE
+  },
+  useDpop: true
+});
+
+// Handle redirect callback after login
+const query = new URLSearchParams(window.location.search);
+if ((query.has('code') || query.has('error')) && query.has('state')) {
+  await auth0.handleRedirectCallback();
+  window.history.replaceState({}, document.title, window.location.pathname);
+}
+```
+
+#### 2. Make DPoP-protected API calls
+
+```typescript
+// Create a DPoP-aware fetcher
+const apiFetch = auth0.createFetcher({
+  baseUrl: 'https://your-api.example.com'
+});
+
+async function fetchData() {
+  try {
+    const response = await apiFetch('/data');
+    return await response.json();
+  } catch (err) {
+    if (err instanceof UseDpopNonceError) {
+      // Server rotated its nonce — retry once
+      const response = await apiFetch('/data');
+      return await response.json();
+    }
+    throw err;
+  }
+}
+```
+
+#### 3. POST / PUT / DELETE requests
+
+```typescript
+const response = await apiFetch('/items', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ name: 'example' })
+});
+```
+
+#### 4. Multiple APIs with separate fetchers
+
+```typescript
+const ordersApi = auth0.createFetcher({ baseUrl: 'https://orders.example.com' });
+const inventoryApi = auth0.createFetcher({ baseUrl: 'https://inventory.example.com' });
+
+const [orders, inventory] = await Promise.all([
+  ordersApi('/list').then(r => r.json()),
+  inventoryApi('/stock').then(r => r.json())
+]);
+```
+
+---
+
+## Error Handling
+
+### `UseDpopNonceError`
+
+Servers may rotate their DPoP nonce. When this happens the SDK throws
+`UseDpopNonceError`. Retry the request once — the SDK will have updated the
+stored nonce automatically:
+
+```typescript
+// Import from your framework SDK:
+// @auth0/auth0-vue | @auth0/auth0-react | @auth0/auth0-angular | @auth0/auth0-spa-js
+import { UseDpopNonceError } from '@auth0/auth0-vue';
+
+try {
+  const response = await apiFetch('/data');
+  const data = await response.json();
+} catch (err) {
+  if (err instanceof UseDpopNonceError) {
+    // Nonce was stale — retry once; SDK has already stored the new nonce
+    const response = await apiFetch('/data');
+    const data = await response.json();
+  } else {
+    throw err;
+  }
+}
+```
+
+---
+
+## Common Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| API returns `401` with `error: use_dpop_nonce` | Server issued a new nonce | Catch `UseDpopNonceError` and retry |
+| API returns `401` with `invalid_dpop_proof` | Clock skew or wrong `htm`/`htu` values | Ensure system clock is accurate; verify `baseUrl` matches API URL exactly |
+| Token still issued as Bearer instead of DPoP | `useDpop: true` missing or `audience` not set | Confirm both options are present in client config |
+| `createFetcher` is undefined | SDK version too old | Upgrade to `@auth0/auth0-spa-js` ≥ 2.1 (or framework SDK wrapping it) |
diff --git a/main/.mintlify/skills/auth0/references/feature-mfa/index.md b/main/.mintlify/skills/auth0/references/feature-mfa/index.md
new file mode 100644
index 0000000000..63091b5829
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/feature-mfa/index.md
@@ -0,0 +1,905 @@
+
+# Auth0 MFA Guide
+
+Add Multi-Factor Authentication to protect user accounts and require additional verification for sensitive operations.
+
+
+## Overview
+
+### What is MFA?
+
+Multi-Factor Authentication (MFA) requires users to provide two or more verification factors to access their accounts. Auth0 supports multiple MFA factors and enables step-up authentication for sensitive operations.
+
+### When to Use This Skill
+
+- Adding MFA to protect user accounts
+- Requiring additional verification for sensitive actions (payments, settings changes)
+- Implementing adaptive/risk-based authentication
+- Meeting compliance requirements (PCI-DSS, SOC2, HIPAA)
+
+### MFA Factors Supported
+
+| Factor | Type | Description |
+|--------|------|-------------|
+| TOTP | Something you have | Time-based one-time passwords (Google Authenticator, Authy) |
+| SMS | Something you have | One-time codes via text message |
+| Email | Something you have | One-time codes via email |
+| Push | Something you have | Push notifications via Auth0 Guardian app |
+| WebAuthn | Something you have/are | Security keys, biometrics, passkeys |
+| Voice | Something you have | One-time codes via phone call |
+| Recovery Code | Backup | One-time use recovery codes |
+
+### Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| `acr_values` | Request MFA during authentication |
+| `amr` claim | Authentication Methods Reference - indicates how user authenticated |
+| Step-up auth | Require MFA for specific actions after initial login |
+| Adaptive MFA | Conditionally require MFA based on risk signals |
+
+
+## Step 1: Enable MFA in Tenant
+
+### Via Auth0 Dashboard
+
+1. Go to **Security → Multi-factor Auth**
+2. Enable desired factors (TOTP, SMS, etc.)
+3. Configure **Policies**:
+   - **Always** - Require MFA for all logins
+   - **Adaptive** - Risk-based MFA
+   - **Never** - Disable MFA (use step-up instead)
+
+### Via Auth0 CLI
+
+```bash
+# View current MFA configuration
+auth0 api get "guardian/factors"
+
+# Enable TOTP (One-time Password)
+auth0 api put "guardian/factors/otp" --data '{"enabled": true}'
+
+# Enable SMS
+auth0 api put "guardian/factors/sms" --data '{"enabled": true}'
+
+# Enable Push notifications
+auth0 api put "guardian/factors/push-notification" --data '{"enabled": true}'
+
+# Enable WebAuthn (Roaming - Security Keys)
+auth0 api put "guardian/factors/webauthn-roaming" --data '{"enabled": true}'
+
+# Enable WebAuthn (Platform - Biometrics)
+auth0 api put "guardian/factors/webauthn-platform" --data '{"enabled": true}'
+
+# Enable Email
+auth0 api put "guardian/factors/email" --data '{"enabled": true}'
+```
+
+### Configure MFA Policy
+
+```bash
+# Set MFA policy: "all-applications" or "confidence-score"
+auth0 api patch "guardian/policies" --data '["all-applications"]'
+```
+
+### Same configuration in Terraform
+
+The CLI commands above are one way to enable factors and set the policy. If the
+project is infrastructure-as-code, the loaded tooling reference gives the
+equivalent:
+- CLI: `auth0 api put guardian/factors/...` + `auth0 api patch guardian/policies`
+- Terraform: `auth0_guardian` resource (`policy` + per-factor blocks)
+- MCP: not available — the Auth0 MCP server exposes no Guardian/MFA tool; use the CLI or Terraform.
+
+
+## Step 2: Implement Step-Up Authentication
+
+Step-up auth requires MFA for sensitive operations without requiring it for every login.
+
+### The `acr_values` Parameter
+
+Request MFA by including `acr_values` in your authorization request:
+
+```
+acr_values=http://schemas.openid.net/pape/policies/2007/06/multi-factor
+```
+
+### Implementation Pattern
+
+The general pattern for all frameworks:
+
+1. Check if user has already completed MFA (inspect `amr` claim)
+2. If not, request MFA via `acr_values` parameter
+3. Proceed with sensitive action once MFA is verified
+
+**For complete framework-specific examples, see the sections below:**
+- React (basic and custom hook)
+- Next.js (App Router)
+- Vue.js
+- Angular
+
+
+## Additional Resources
+
+This skill is split into multiple files for better organization:
+
+### Step-Up Examples
+Complete code examples for all frameworks:
+- React (basic and custom hook patterns)
+- Next.js (App Router with API routes)
+- Vue.js (composition API)
+- Angular (services and components)
+
+### Backend Validation
+Learn how to validate MFA status on your backend:
+- Node.js / Express JWT validation
+- Python / Flask validation
+- Middleware examples
+
+### Advanced Topics
+Advanced MFA implementation patterns:
+- Adaptive MFA with Auth0 Actions
+- Conditional MFA based on risk signals
+- MFA Enrollment API
+
+### Reference Guide
+Common patterns and troubleshooting:
+- Remember MFA for 30 days
+- MFA for high-value transactions
+- MFA status display
+- Error handling
+- AMR claim values
+- Testing strategies
+- Security considerations
+
+
+## Related Capabilities
+
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Passkeys / WebAuthn — ask for MFA (feature:mfa)
+- Auth0 Actions — custom login-flow logic for adaptive/conditional authentication
+
+
+## References
+
+- [Auth0 MFA Documentation](https://auth0.com/docs/secure/multi-factor-authentication)
+- [Step-Up Authentication](https://auth0.com/docs/secure/multi-factor-authentication/step-up-authentication)
+- [MFA API](https://auth0.com/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis)
+- [acr_values Parameter](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow#request-parameters)
+
+---
+
+## Common Patterns
+
+### Pattern 1: Remember MFA for 30 Days
+
+```typescript
+// React: Check MFA age before requiring
+const requireMFAIfStale = async (maxAgeSeconds = 30 * 24 * 60 * 60) => {
+  const claims = await getIdTokenClaims();
+  const authTime = claims?.auth_time;
+
+  if (!authTime) return requireMFA();
+
+  const authAge = Math.floor(Date.now() / 1000) - authTime;
+
+  if (authAge > maxAgeSeconds) {
+    return requireMFA({ maxAge: 0 });
+  }
+
+  return hasMFA();
+};
+```
+
+### Pattern 2: MFA Challenge for High-Value Transactions
+
+```typescript
+// Frontend
+const transferFunds = async (amount: number) => {
+  // Require MFA for transfers over $1000
+  if (amount > 1000) {
+    const verified = await requireMFA();
+    if (!verified) return;
+  }
+
+  await api.post('/transfer', { amount });
+};
+
+// Backend middleware
+const requireMFAForHighValue = (threshold: number) => {
+  return (req, res, next) => {
+    const amount = req.body?.amount || 0;
+
+    if (amount > threshold) {
+      const amr = req.auth?.amr || [];
+      if (!amr.includes('mfa')) {
+        return res.status(403).json({
+          error: 'MFA required for high-value transactions',
+          code: 'mfa_required',
+        });
+      }
+    }
+
+    next();
+  };
+};
+
+app.post('/transfer', validateJwt, requireMFAForHighValue(1000), handleTransfer);
+```
+
+### Pattern 3: MFA Status Display
+
+```typescript
+// React component showing MFA status
+function MFAStatus() {
+  const { getIdTokenClaims } = useAuth0();
+  const [mfaStatus, setMfaStatus] = useState<string[]>([]);
+
+  useEffect(() => {
+    getIdTokenClaims().then(claims => {
+      setMfaStatus(claims?.amr || []);
+    });
+  }, []);
+
+  const getMFALabel = (method: string) => {
+    const labels: Record<string, string> = {
+      'mfa': 'Multi-Factor Auth',
+      'otp': 'Authenticator App',
+      'sms': 'SMS Code',
+      'email': 'Email Code',
+      'pwd': 'Password',
+      'hwk': 'Security Key',
+    };
+    return labels[method] || method;
+  };
+
+  return (
+    <div>
+      <h3>Authentication Methods Used:</h3>
+      <ul>
+        {mfaStatus.map(method => (
+          <li key={method}>{getMFALabel(method)}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+---
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `mfa_required` | User hasn't completed MFA | Redirect with `acr_values` parameter |
+| `mfa_registration_required` | User has no MFA enrolled | Direct to enrollment or enable self-enrollment |
+| `mfa_invalid_code` | Wrong OTP code entered | Prompt user to retry |
+| `too_many_attempts` | Too many failed MFA attempts | Wait or contact support |
+| `unsupported_challenge_type` | MFA factor not enabled | Enable the factor in dashboard |
+
+---
+
+## AMR Claim Values
+
+The `amr` (Authentication Methods Reference) claim indicates how the user authenticated:
+
+| Value | Meaning |
+|-------|---------|
+| `pwd` | Password authentication |
+| `mfa` | Multi-factor authentication completed |
+| `otp` | One-time password (TOTP) |
+| `sms` | SMS verification |
+| `email` | Email verification |
+| `hwk` | Hardware key (WebAuthn) |
+| `swk` | Software key |
+| `pop` | Proof of possession |
+| `fed` | Federated authentication (social/enterprise) |
+
+---
+
+## Testing
+
+### Verify MFA is Working
+
+1. **Enable MFA** in Auth0 Dashboard
+2. **Login** and complete MFA enrollment
+3. **Check ID token** for `amr` claim containing `mfa`
+4. **Test step-up** by calling endpoint requiring MFA
+5. **Verify backend** rejects requests without MFA
+
+### Test Commands
+
+```bash
+# Check if MFA is enabled
+auth0 api get "guardian/factors"
+
+# List user's enrollments
+auth0 api get "users/USER_ID/authenticators"
+
+# Check MFA policy
+auth0 api get "guardian/policies"
+```
+
+---
+
+## Security Considerations
+
+- **Always validate MFA on the backend** - Never trust frontend-only checks
+- **Use `max_age=0`** for sensitive operations to force fresh authentication
+- **Prefer TOTP/WebAuthn** over SMS (SIM swapping risk)
+- **Enable recovery codes** so users don't get locked out
+- **Log MFA events** for security auditing
+- **Consider adaptive MFA** to balance security and UX
+
+---
+
+## Related Capabilities
+
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Passkeys / WebAuthn — ask for MFA (feature:mfa)
+- Auth0 Actions — custom login-flow logic for adaptive/conditional authentication
+
+---
+
+## References
+
+- [Auth0 MFA Documentation](https://auth0.com/docs/secure/multi-factor-authentication)
+- [Step-Up Authentication](https://auth0.com/docs/secure/multi-factor-authentication/step-up-authentication)
+- [MFA API](https://auth0.com/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis)
+- [acr_values Parameter](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow#request-parameters)
+
+---
+
+## Step 3: Validate MFA on Backend
+
+Always validate MFA status on the backend for sensitive operations.
+
+### Node.js / Express
+
+```typescript
+import { expressjwt, GetVerificationKey } from 'express-jwt';
+import { expressJwtSecret } from 'jwks-rsa';
+import { Request, Response, NextFunction } from 'express';
+
+// Extend Request type
+interface AuthRequest extends Request {
+  auth?: {
+    sub: string;
+    amr?: string[];
+    acr?: string;
+    [key: string]: any;
+  };
+}
+
+// JWT validation middleware
+const validateJwt = expressjwt({
+  secret: expressJwtSecret({
+    cache: true,
+    rateLimit: true,
+    jwksUri: `https://${process.env.AUTH0_DOMAIN}/.well-known/jwks.json`,
+  }) as GetVerificationKey,
+  audience: process.env.AUTH0_AUDIENCE,
+  issuer: `https://${process.env.AUTH0_DOMAIN}/`,
+  algorithms: ['RS256'],
+});
+
+// MFA requirement middleware
+const requireMFA = (req: AuthRequest, res: Response, next: NextFunction) => {
+  const amr = req.auth?.amr || [];
+
+  if (!amr.includes('mfa')) {
+    return res.status(403).json({
+      error: 'MFA required',
+      code: 'mfa_required',
+      message: 'This action requires multi-factor authentication',
+    });
+  }
+
+  next();
+};
+
+// Usage
+app.post('/api/transfer', validateJwt, requireMFA, (req, res) => {
+  // User has completed MFA
+  res.json({ success: true });
+});
+
+// Optional: Check specific MFA methods
+const requireTOTP = (req: AuthRequest, res: Response, next: NextFunction) => {
+  const amr = req.auth?.amr || [];
+
+  // Check for OTP-based MFA (TOTP)
+  if (!amr.includes('otp') && !amr.includes('mfa')) {
+    return res.status(403).json({
+      error: 'TOTP required',
+      code: 'totp_required',
+    });
+  }
+
+  next();
+};
+```
+
+### Python (Flask)
+
+```python
+from functools import wraps
+from flask import request, jsonify, g
+import jwt
+from jwt import PyJWKClient
+
+AUTH0_DOMAIN = os.environ.get('AUTH0_DOMAIN')
+AUTH0_AUDIENCE = os.environ.get('AUTH0_AUDIENCE')
+
+def require_auth(f):
+    @wraps(f)
+    def decorated(*args, **kwargs):
+        auth_header = request.headers.get('Authorization', '')
+        if not auth_header.startswith('Bearer '):
+            return jsonify({'error': 'Missing token'}), 401
+
+        token = auth_header.split(' ')[1]
+
+        try:
+            jwks_url = f'https://{AUTH0_DOMAIN}/.well-known/jwks.json'
+            jwks_client = PyJWKClient(jwks_url)
+            signing_key = jwks_client.get_signing_key_from_jwt(token)
+
+            payload = jwt.decode(
+                token,
+                signing_key.key,
+                algorithms=['RS256'],
+                audience=AUTH0_AUDIENCE,
+                issuer=f'https://{AUTH0_DOMAIN}/'
+            )
+            g.user = payload
+        except jwt.exceptions.PyJWTError as e:
+            return jsonify({'error': f'Invalid token: {str(e)}'}), 401
+
+        return f(*args, **kwargs)
+    return decorated
+
+def require_mfa(f):
+    @wraps(f)
+    def decorated(*args, **kwargs):
+        amr = g.user.get('amr', [])
+
+        if 'mfa' not in amr:
+            return jsonify({
+                'error': 'MFA required',
+                'code': 'mfa_required',
+                'message': 'This action requires multi-factor authentication'
+            }), 403
+
+        return f(*args, **kwargs)
+    return decorated
+
+# Usage
+@app.route('/api/transfer', methods=['POST'])
+@require_auth
+@require_mfa
+def transfer():
+    # User has completed MFA
+    return jsonify({'success': True})
+```
+
+---
+
+---
+
+## Step 4: Adaptive MFA with Actions
+
+Use Auth0 Actions to require MFA based on conditions.
+
+### Create Action: Conditional MFA
+
+```javascript
+// Action: Require MFA for Sensitive Operations
+// Trigger: Login / Post Login
+
+exports.onExecutePostLogin = async (event, api) => {
+  // Always require MFA for admins
+  const roles = event.authorization?.roles || [];
+  if (roles.includes('admin')) {
+    if (event.authentication?.methods?.find(m => m.name === 'mfa')) {
+      return; // MFA already completed
+    }
+    api.multifactor.enable('any', { allowRememberBrowser: false });
+    return;
+  }
+
+  // Require MFA for new devices
+  const isNewDevice = !event.authentication?.methods?.find(
+    m => m.name === 'pwd' && m.timestamp
+  );
+
+  if (isNewDevice) {
+    api.multifactor.enable('any', { allowRememberBrowser: true });
+    return;
+  }
+
+  // Require MFA for suspicious locations
+  const riskAssessment = event.request?.geoip;
+  const userCountry = event.user?.user_metadata?.country;
+
+  if (riskAssessment?.countryCode !== userCountry) {
+    api.multifactor.enable('any', { allowRememberBrowser: false });
+    return;
+  }
+};
+```
+
+### Create Action: MFA Based on Requested Scopes
+
+```javascript
+// Action: MFA for Sensitive Scopes
+// Trigger: Login / Post Login
+
+exports.onExecutePostLogin = async (event, api) => {
+  const requestedScopes = event.request?.query?.scope?.split(' ') || [];
+  const sensitiveScopes = ['transfer:funds', 'admin:write', 'delete:users'];
+
+  const requiresMFA = requestedScopes.some(scope =>
+    sensitiveScopes.includes(scope)
+  );
+
+  if (requiresMFA) {
+    const hasMFA = event.authentication?.methods?.find(m => m.name === 'mfa');
+    if (!hasMFA) {
+      api.multifactor.enable('any');
+    }
+  }
+};
+```
+
+### Deploy Action via CLI
+
+```bash
+# Create the action
+auth0 actions create \
+  --name "Conditional MFA" \
+  --trigger post-login \
+  --code "$(cat conditional-mfa.js)"
+
+# Deploy the action
+auth0 actions deploy ACTION_ID
+
+# Attach to login flow
+auth0 api patch "actions/triggers/post-login/bindings" --data '{
+  "bindings": [{"ref": {"type": "action_id", "value": "ACTION_ID"}}]
+}'
+```
+
+---
+
+## Step 5: MFA Enrollment API
+
+For custom enrollment experiences, use the MFA API.
+
+### List User's MFA Enrollments
+
+```bash
+# Get user's enrolled authenticators
+curl -X GET "https://YOUR_DOMAIN/api/v2/users/USER_ID/authenticators" \
+  -H "Authorization: Bearer MGMT_TOKEN"
+```
+
+### Delete an Enrollment
+
+```bash
+# Remove an authenticator
+curl -X DELETE "https://YOUR_DOMAIN/api/v2/users/USER_ID/authenticators/AUTHENTICATOR_ID" \
+  -H "Authorization: Bearer MGMT_TOKEN"
+```
+
+### Trigger Enrollment Email
+
+```bash
+# Send enrollment email to user
+curl -X POST "https://YOUR_DOMAIN/api/v2/guardian/enrollments/ticket" \
+  -H "Authorization: Bearer MGMT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": "USER_ID",
+    "send_mail": true
+  }'
+```
+
+---
+
+---
+
+# MFA Step-Up Authentication Examples
+
+Framework-specific code examples for implementing step-up authentication.
+
+---
+
+## React
+
+### Basic Example
+
+```typescript
+import { useAuth0 } from '@auth0/auth0-react';
+
+function SensitiveAction() {
+  const { getAccessTokenSilently, getIdTokenClaims } = useAuth0();
+
+  const requireMFA = async () => {
+    // Check if user already completed MFA
+    const claims = await getIdTokenClaims();
+    const amr = claims?.amr || [];
+
+    if (!amr.includes('mfa')) {
+      // Request MFA via step-up authentication
+      await getAccessTokenSilently({
+        authorizationParams: {
+          acr_values: 'http://schemas.openid.net/pape/policies/2007/06/multi-factor',
+          max_age: 0, // Force re-authentication
+        },
+      });
+    }
+
+    // User has completed MFA, proceed with sensitive action
+    return performSensitiveAction();
+  };
+
+  return (
+    <button onClick={requireMFA}>
+      Transfer Funds (Requires MFA)
+    </button>
+  );
+}
+```
+
+### Custom Hook
+
+```typescript
+import { useAuth0 } from '@auth0/auth0-react';
+import { useCallback, useState } from 'react';
+
+interface StepUpOptions {
+  maxAge?: number;
+}
+
+export function useStepUpAuth() {
+  const { getAccessTokenSilently, getIdTokenClaims, loginWithRedirect } = useAuth0();
+  const [isVerifying, setIsVerifying] = useState(false);
+
+  const hasMFA = useCallback(async (): Promise<boolean> => {
+    const claims = await getIdTokenClaims();
+    const amr = claims?.amr || [];
+    return amr.includes('mfa');
+  }, [getIdTokenClaims]);
+
+  const requireMFA = useCallback(async (options: StepUpOptions = {}) => {
+    setIsVerifying(true);
+    try {
+      const mfaCompleted = await hasMFA();
+
+      if (!mfaCompleted) {
+        // Try silent step-up first
+        try {
+          await getAccessTokenSilently({
+            authorizationParams: {
+              acr_values: 'http://schemas.openid.net/pape/policies/2007/06/multi-factor',
+              max_age: options.maxAge ?? 0,
+            },
+            cacheMode: 'off',
+          });
+        } catch {
+          // Silent failed, redirect to MFA
+          await loginWithRedirect({
+            authorizationParams: {
+              acr_values: 'http://schemas.openid.net/pape/policies/2007/06/multi-factor',
+              max_age: options.maxAge ?? 0,
+            },
+          });
+          return false;
+        }
+      }
+
+      return true;
+    } finally {
+      setIsVerifying(false);
+    }
+  }, [getAccessTokenSilently, loginWithRedirect, hasMFA]);
+
+  return { requireMFA, hasMFA, isVerifying };
+}
+
+// Usage
+function TransferFunds() {
+  const { requireMFA, isVerifying } = useStepUpAuth();
+
+  const handleTransfer = async () => {
+    const verified = await requireMFA();
+    if (verified) {
+      // Proceed with transfer
+    }
+  };
+
+  return (
+    <button onClick={handleTransfer} disabled={isVerifying}>
+      {isVerifying ? 'Verifying...' : 'Transfer Funds'}
+    </button>
+  );
+}
+```
+
+---
+
+## Next.js (App Router)
+
+### API Route
+
+```typescript
+// app/api/sensitive/route.ts
+// v4 removed withApiAuthRequired — guard the route by reading the session directly.
+import { auth0 } from '@/lib/auth0';
+import { NextResponse } from 'next/server';
+
+export async function POST(req: Request) {
+  const session = await auth0.getSession();
+
+  if (!session) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  // Check if MFA was completed
+  const amr = session.user?.amr || [];
+
+  if (!amr.includes('mfa')) {
+    return NextResponse.json(
+      { error: 'MFA required', code: 'mfa_required' },
+      { status: 403 }
+    );
+  }
+
+  // Proceed with sensitive operation
+  return NextResponse.json({ success: true });
+}
+```
+
+### Client Component
+
+```typescript
+// app/transfer/page.tsx
+'use client';
+
+import { useUser } from '@auth0/nextjs-auth0/client';
+import { useRouter } from 'next/navigation';
+
+export default function TransferPage() {
+  const { user } = useUser();
+  const router = useRouter();
+
+  const handleTransfer = async () => {
+    const response = await fetch('/api/sensitive', { method: 'POST' });
+
+    if (response.status === 403) {
+      const { code } = await response.json();
+      if (code === 'mfa_required') {
+        // Redirect to login with MFA required (v4 mounts auth routes at /auth/*, not /api/auth/*)
+        router.push('/auth/login?acr_values=http://schemas.openid.net/pape/policies/2007/06/multi-factor');
+        return;
+      }
+    }
+
+    // Success
+  };
+
+  return <button onClick={handleTransfer}>Transfer Funds</button>;
+}
+```
+
+---
+
+## Vue.js
+
+`idTokenClaims` is a reactive ref from `useAuth0()` — read it as `idTokenClaims.value?.amr`, not via `getIdTokenClaims()`.
+
+```typescript
+<script setup lang="ts">
+import { useAuth0 } from '@auth0/auth0-vue';
+import { ref } from 'vue';
+
+const { getAccessTokenSilently, idTokenClaims, loginWithRedirect } = useAuth0();
+const isVerifying = ref(false);
+
+const hasMFA = (): boolean => {
+  const amr = idTokenClaims.value?.amr || [];
+  return amr.includes('mfa');
+};
+
+const requireMFA = async () => {
+  isVerifying.value = true;
+  try {
+    if (!(await hasMFA())) {
+      try {
+        await getAccessTokenSilently({
+          authorizationParams: {
+            acr_values: 'http://schemas.openid.net/pape/policies/2007/06/multi-factor',
+            max_age: 0,
+          },
+        });
+      } catch {
+        await loginWithRedirect({
+          authorizationParams: {
+            acr_values: 'http://schemas.openid.net/pape/policies/2007/06/multi-factor',
+          },
+        });
+        return false;
+      }
+    }
+    return true;
+  } finally {
+    isVerifying.value = false;
+  }
+};
+
+const handleSensitiveAction = async () => {
+  if (await requireMFA()) {
+    // Proceed with sensitive action
+    console.log('MFA verified, proceeding...');
+  }
+};
+</script>
+
+<template>
+  <button @click="handleSensitiveAction" :disabled="isVerifying">
+    {{ isVerifying ? 'Verifying...' : 'Transfer Funds' }}
+  </button>
+</template>
+```
+
+---
+
+## Angular
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+import { firstValueFrom } from 'rxjs';
+
+@Component({
+  selector: 'app-sensitive-action',
+  template: `
+    <button (click)="handleSensitiveAction()" [disabled]="isVerifying">
+      {{ isVerifying ? 'Verifying...' : 'Transfer Funds' }}
+    </button>
+  `
+})
+export class SensitiveActionComponent {
+  private auth = inject(AuthService);
+  isVerifying = false;
+
+  private async hasMFA(): Promise<boolean> {
+    const claims = await firstValueFrom(this.auth.idTokenClaims$);
+    const amr = (claims as any)?.amr || [];
+    return amr.includes('mfa');
+  }
+
+  async handleSensitiveAction() {
+    this.isVerifying = true;
+    try {
+      if (!(await this.hasMFA())) {
+        // Request MFA
+        this.auth.loginWithRedirect({
+          authorizationParams: {
+            acr_values: 'http://schemas.openid.net/pape/policies/2007/06/multi-factor',
+            max_age: 0,
+          },
+        });
+        return;
+      }
+
+      // MFA verified, proceed
+      console.log('MFA verified, proceeding...');
+    } finally {
+      this.isVerifying = false;
+    }
+  }
+}
+```
diff --git a/main/.mintlify/skills/auth0/references/feature-migration/index.md b/main/.mintlify/skills/auth0/references/feature-migration/index.md
new file mode 100644
index 0000000000..4aee9bc252
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/feature-migration/index.md
@@ -0,0 +1,1536 @@
+
+# Auth0 Migration Guide
+
+Migrate users and authentication flows from existing auth providers to Auth0.
+
+
+## Overview
+
+### When to Use This Skill
+
+- Migrating from another auth provider to Auth0
+- Bulk importing existing users
+- Gradually transitioning active user bases
+- Updating JWT validation in APIs
+
+## When NOT to Use
+
+- **Starting fresh with Auth0** - For new projects without existing users, set up Auth0 first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- **Already using Auth0** - This is for migrating TO Auth0, not between Auth0 tenants
+- **Only adding MFA or features** - Use feature-specific skills if just adding capabilities
+
+### Migration Approaches
+
+- **Bulk Migration:** One-time user import (recommended for small/inactive bases)
+- **Gradual Migration:** Lazy migration over time (recommended for large active bases)
+- **Hybrid:** Import inactive users, lazy-migrate active users
+
+
+## Step 0: Detect Existing Auth Provider
+
+**Check if the project already has authentication:**
+
+Search for common auth-related patterns in the codebase:
+
+| Pattern | Indicates |
+|---------|-----------|
+| `signInWithEmailAndPassword`, `onAuthStateChanged` | Firebase Auth |
+| `useUser`, `useSession`, `isSignedIn` | Existing auth hooks |
+| `passport.authenticate`, `LocalStrategy` | Passport.js |
+| `authorize`, `getAccessToken`, `oauth` | OAuth/OIDC |
+| `JWT`, `jwt.verify`, `jsonwebtoken` | Token-based auth |
+| `/api/auth/`, `/login`, `/callback` | Auth routes |
+
+**If existing auth detected, ask:**
+
+> I detected existing authentication in your project. Are you:
+> 1. **Migrating to Auth0** (replace existing auth)
+> 2. **Adding Auth0 alongside** (keep both temporarily)
+> 3. **Starting fresh** (remove old auth, new Auth0 setup)
+
+
+## Migration Workflow
+
+### Step 1: Export Existing Users
+
+Export users from your current provider. See the User Import section below for detailed instructions:
+- Exporting from Firebase
+- Exporting from AWS Cognito
+- Exporting from Supabase
+- Exporting from Custom Database
+
+**Required data per user:**
+- Email address
+- Email verified status
+- Password hash (if available)
+- User metadata/profile data
+- Creation timestamp
+
+
+### Step 2: Import Users to Auth0
+
+Import users via Dashboard, CLI, or Management API.
+
+**Quick start:**
+```bash
+# Via Auth0 CLI
+auth0 api post "jobs/users-imports" \
+  --data "connection_id=con_ABC123" \
+  --data "users=@users.json"
+```
+
+**For detailed instructions, see the sections below:**
+- User JSON Format
+- Password Hash Algorithms
+- Import Methods
+- Monitoring Import Progress
+- Common Import Errors
+
+
+### Step 3: Migrate Application Code
+
+Update your application code to use Auth0 SDKs.
+
+**See the Code Migration Patterns section below for detailed before/after examples:**
+
+**Frontend:**
+- React Migration
+- Next.js Migration
+- Vue.js Migration
+- Angular Migration
+- React Native Migration
+
+**Backend:**
+- Express.js Migration
+- API JWT Validation
+
+**Provider-Specific:**
+- Firebase to Auth0
+- Supabase to Auth0
+- Clerk to Auth0
+
+**After migrating code, follow the Auth0 integration workflow for your framework** (React, Next.js, Vue.js, Angular, Express.js, or React Native/Expo).
+
+
+### Step 4: Update API JWT Validation
+
+If your API validates JWTs, update to validate Auth0 tokens.
+
+**Key differences:**
+- **Algorithm:** HS256 (symmetric) → RS256 (asymmetric)
+- **Issuer:** Custom → `https://YOUR_TENANT.auth0.com/`
+- **JWKS URL:** `https://YOUR_TENANT.auth0.com/.well-known/jwks.json`
+
+**See the Backend API JWT Validation section below for:**
+- Node.js / Express implementation
+- Python / Flask implementation
+- Key differences and migration checklist
+
+
+## Gradual Migration Strategy
+
+For production applications with active users, use a phased approach:
+
+### Phase 1: Parallel Auth
+
+Support both Auth0 and legacy provider simultaneously:
+
+```typescript
+// Support both providers during migration
+const getUser = async () => {
+  // Try Auth0 first
+  const auth0User = await getAuth0User();
+  if (auth0User) return auth0User;
+
+  // Fall back to legacy provider
+  return await getLegacyUser();
+};
+```
+
+### Phase 2: New Users on Auth0
+
+- All new signups go to Auth0
+- Existing users continue on legacy provider
+- Migrate users on next login (lazy migration)
+
+### Phase 3: Forced Migration
+
+- Prompt remaining users to "update account"
+- Send password reset emails via Auth0
+- Set deadline for legacy system shutdown
+
+### Phase 4: Cleanup
+
+- Remove legacy auth code
+- Archive user export for compliance
+- Update documentation
+
+
+## Common Migration Issues
+
+| Issue | Solution |
+|-------|----------|
+| Password hashes incompatible | Use Auth0 custom DB connection with lazy migration |
+| Social logins don't link | Configure same social connection, users auto-link by email |
+| Custom claims missing | Add claims via Auth0 Actions |
+| Token format different | Update API to validate RS256 JWTs with Auth0 issuer |
+| Session persistence | Auth0 uses rotating refresh tokens; update token storage |
+| Users must re-login | Expected for redirect-based auth; communicate to users |
+
+
+## Reference Documentation
+
+### User Import
+Complete guide to exporting and importing users:
+- Exporting from Common Providers
+- User JSON Format
+- Password Hash Algorithms
+- Import Methods
+- Monitoring & Troubleshooting
+
+### Code Migration
+Before/after examples for all major frameworks:
+- React Patterns
+- Next.js Patterns
+- Express Patterns
+- Vue.js Patterns
+- Angular Patterns
+- React Native Patterns
+- API JWT Validation
+
+
+All of this lives in the one `auth0` skill — just describe what you need (e.g. "add MFA", "protect my API").
+
+
+## References
+
+- [Auth0 User Migration Documentation](https://auth0.com/docs/manage-users/user-migration)
+- [Bulk User Import](https://auth0.com/docs/manage-users/user-migration/bulk-user-imports)
+- [Password Hash Algorithms](https://auth0.com/docs/manage-users/user-migration/bulk-user-imports#password-hashing-algorithms)
+- [Management API - User Import](https://auth0.com/docs/api/management/v2/jobs/post-users-imports)
+
+---
+
+# Code Migration Patterns
+
+Before/after code examples for migrating from common auth providers to Auth0 across different frameworks.
+
+---
+
+## React Migration
+
+### Email/Password Authentication
+
+**Before (typical pattern):**
+```typescript
+// Old provider pattern
+await signIn(email, password);
+await signOut();
+const user = getCurrentUser();
+```
+
+**After (Auth0):**
+```typescript
+import { useAuth0 } from '@auth0/auth0-react';
+
+const { loginWithRedirect, logout, user, isAuthenticated } = useAuth0();
+
+// Login triggers redirect to Auth0 Universal Login
+loginWithRedirect();
+
+// Logout with redirect
+logout({ logoutParams: { returnTo: window.location.origin } });
+
+// User available when authenticated
+if (isAuthenticated) {
+  console.log(user.email);
+}
+```
+
+---
+
+### Auth State Listener
+
+**Before (typical pattern):**
+```typescript
+// Old provider pattern
+onAuthStateChange((user) => {
+  if (user) { /* authenticated */ }
+  else { /* not authenticated */ }
+});
+```
+
+**After (Auth0):**
+```typescript
+import { useAuth0 } from '@auth0/auth0-react';
+
+function App() {
+  const { isAuthenticated, isLoading, user } = useAuth0();
+
+  if (isLoading) return <Loading />;
+
+  return isAuthenticated ? (
+    <AuthenticatedApp user={user} />
+  ) : (
+    <LoginPage />
+  );
+}
+```
+
+---
+
+### Protected Routes
+
+**Before (typical pattern):**
+```typescript
+// Old provider pattern
+function ProtectedRoute({ children }) {
+  const user = useCurrentUser();
+  return user ? children : <Redirect to="/login" />;
+}
+```
+
+**After (Auth0):**
+```typescript
+import { useAuth0 } from '@auth0/auth0-react';
+
+function ProtectedRoute({ children }) {
+  const { isAuthenticated, isLoading, loginWithRedirect } = useAuth0();
+
+  if (isLoading) return <Loading />;
+
+  if (!isAuthenticated) {
+    loginWithRedirect();
+    return null;
+  }
+
+  return children;
+}
+```
+
+---
+
+### API Token Retrieval
+
+**Before (typical pattern):**
+```typescript
+// Old provider pattern
+const token = await user.getIdToken();
+fetch('/api/data', { headers: { Authorization: `Bearer ${token}` } });
+```
+
+**After (Auth0):**
+```typescript
+import { useAuth0 } from '@auth0/auth0-react';
+
+function ApiComponent() {
+  const { getAccessTokenSilently } = useAuth0();
+
+  const callApi = async () => {
+    const token = await getAccessTokenSilently();
+    const response = await fetch('/api/data', {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    return response.json();
+  };
+}
+```
+
+---
+
+## Next.js Migration
+
+### Middleware Protection
+
+**Before (typical pattern):**
+```typescript
+// Old provider middleware pattern
+export function middleware(request) {
+  const session = getSession(request);
+  if (!session) return redirect('/login');
+}
+```
+
+**After (Auth0):**
+```typescript
+// middleware.ts
+import { withMiddlewareAuthRequired } from '@auth0/nextjs-auth0/edge';
+
+export default withMiddlewareAuthRequired();
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/protected/:path*']
+};
+```
+
+---
+
+### Server Components (App Router)
+
+**Before (typical pattern):**
+```typescript
+// Old provider pattern
+async function DashboardPage() {
+  const session = await getServerSession();
+  if (!session) redirect('/login');
+
+  return <div>Welcome {session.user.name}</div>;
+}
+```
+
+**After (Auth0):**
+```typescript
+import { getSession } from '@auth0/nextjs-auth0';
+
+async function DashboardPage() {
+  const session = await getSession();
+  if (!session) redirect('/api/auth/login');
+
+  return <div>Welcome {session.user.name}</div>;
+}
+```
+
+---
+
+### API Routes
+
+**Before (typical pattern):**
+```typescript
+// Old provider pattern
+export async function GET(request) {
+  const session = await getSession(request);
+  if (!session) return new Response('Unauthorized', { status: 401 });
+
+  return Response.json({ data: 'protected' });
+}
+```
+
+**After (Auth0):**
+```typescript
+import { withApiAuthRequired, getSession } from '@auth0/nextjs-auth0';
+
+export const GET = withApiAuthRequired(async function handler(req) {
+  const session = await getSession();
+  return Response.json({ data: 'protected' });
+});
+```
+
+---
+
+## Express.js Migration
+
+### Server-Side Session Auth
+
+**Before (typical pattern):**
+```typescript
+// Old provider pattern with manual session
+app.post('/login', async (req, res) => {
+  const user = await validateCredentials(req.body);
+  req.session.user = user;
+  res.redirect('/dashboard');
+});
+
+app.get('/dashboard', (req, res) => {
+  if (!req.session.user) return res.redirect('/login');
+  // ...
+});
+```
+
+**After (Auth0):**
+```typescript
+const { auth, requiresAuth } = require('express-openid-connect');
+
+app.use(auth({
+  authRequired: false,
+  auth0Logout: true,
+  secret: process.env.AUTH0_SECRET,
+  baseURL: process.env.AUTH0_BASE_URL,
+  clientID: process.env.AUTH0_CLIENT_ID,
+  issuerBaseURL: process.env.AUTH0_ISSUER_BASE_URL
+}));
+
+// Auth0 handles /login, /logout, /callback automatically
+app.get('/dashboard', requiresAuth(), (req, res) => {
+  // req.oidc.user contains the authenticated user
+  res.render('dashboard', { user: req.oidc.user });
+});
+```
+
+---
+
+### Express API Route Protection
+
+**Before (typical pattern):**
+```typescript
+// Old provider pattern
+app.get('/api/data', async (req, res) => {
+  const token = req.headers.authorization?.split(' ')[1];
+  const user = await verifyToken(token);
+
+  if (!user) return res.status(401).json({ error: 'Unauthorized' });
+
+  res.json({ data: 'protected' });
+});
+```
+
+**After (Auth0):**
+```typescript
+const { auth } = require('express-oauth2-jwt-bearer');
+
+const checkJwt = auth({
+  audience: process.env.AUTH0_AUDIENCE,
+  issuerBaseURL: process.env.AUTH0_ISSUER_BASE_URL
+});
+
+app.get('/api/data', checkJwt, (req, res) => {
+  // req.auth contains verified token claims
+  res.json({ data: 'protected' });
+});
+```
+
+---
+
+## Vue.js Migration
+
+### Authentication
+
+**Before (typical pattern):**
+```vue
+<script setup>
+import { onMounted, ref } from 'vue';
+
+const user = ref(null);
+
+onMounted(async () => {
+  user.value = await getCurrentUser();
+});
+
+const login = async () => {
+  await signIn();
+};
+
+const logout = async () => {
+  await signOut();
+};
+</script>
+```
+
+**After (Auth0):**
+```vue
+<script setup>
+import { useAuth0 } from '@auth0/auth0-vue';
+
+const { user, isAuthenticated, isLoading, loginWithRedirect, logout } = useAuth0();
+</script>
+
+<template>
+  <div v-if="isLoading">Loading...</div>
+  <div v-else-if="isAuthenticated">
+    <p>Welcome {{ user.name }}</p>
+    <button @click="logout({ logoutParams: { returnTo: window.location.origin }})">
+      Logout
+    </button>
+  </div>
+  <button v-else @click="loginWithRedirect()">Login</button>
+</template>
+```
+
+---
+
+### Vue Router Guards
+
+**Before (typical pattern):**
+```typescript
+// Old provider pattern
+router.beforeEach(async (to, from, next) => {
+  const user = await getCurrentUser();
+
+  if (to.meta.requiresAuth && !user) {
+    next('/login');
+  } else {
+    next();
+  }
+});
+```
+
+**After (Auth0):**
+```typescript
+import { createAuthGuard } from '@auth0/auth0-vue';
+
+router.beforeEach(createAuthGuard((to) => {
+  if (to.meta.requiresAuth) {
+    return true; // Requires authentication
+  }
+  return false; // Public route
+}));
+```
+
+---
+
+## Angular Migration
+
+### Authentication Service
+
+**Before (typical pattern):**
+```typescript
+// Old provider pattern
+@Injectable({ providedIn: 'root' })
+export class AuthService {
+  async login() {
+    return await signIn();
+  }
+
+  async logout() {
+    return await signOut();
+  }
+
+  getCurrentUser() {
+    return this.currentUser$;
+  }
+}
+```
+
+**After (Auth0):**
+```typescript
+import { AuthService } from '@auth0/auth0-angular';
+import { inject } from '@angular/core';
+
+@Component({
+  selector: 'app-auth',
+  template: `
+    <div *ngIf="auth.isAuthenticated$ | async; else loggedOut">
+      <p>Welcome {{ (auth.user$ | async)?.name }}</p>
+      <button (click)="logout()">Logout</button>
+    </div>
+    <ng-template #loggedOut>
+      <button (click)="login()">Login</button>
+    </ng-template>
+  `
+})
+export class AuthComponent {
+  auth = inject(AuthService);
+
+  login() {
+    this.auth.loginWithRedirect();
+  }
+
+  logout() {
+    this.auth.logout({ logoutParams: { returnTo: window.location.origin } });
+  }
+}
+```
+
+---
+
+### Route Guards
+
+**Before (typical pattern):**
+```typescript
+// Old provider pattern
+@Injectable({ providedIn: 'root' })
+export class AuthGuard implements CanActivate {
+  canActivate(): boolean {
+    const user = this.authService.currentUser;
+    if (!user) {
+      this.router.navigate(['/login']);
+      return false;
+    }
+    return true;
+  }
+}
+```
+
+**After (Auth0):**
+```typescript
+import { inject } from '@angular/core';
+import { AuthGuard } from '@auth0/auth0-angular';
+
+const routes: Routes = [
+  {
+    path: 'dashboard',
+    component: DashboardComponent,
+    canActivate: [AuthGuard]
+  }
+];
+```
+
+---
+
+### HTTP Interceptor
+
+**Before (typical pattern):**
+```typescript
+// Old provider pattern
+@Injectable()
+export class AuthInterceptor implements HttpInterceptor {
+  intercept(req: HttpRequest<any>, next: HttpHandler) {
+    const token = this.authService.getToken();
+
+    if (token) {
+      req = req.clone({
+        setHeaders: { Authorization: `Bearer ${token}` }
+      });
+    }
+
+    return next.handle(req);
+  }
+}
+```
+
+**After (Auth0):**
+```typescript
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { authHttpInterceptorFn } from '@auth0/auth0-angular';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(
+      withInterceptors([authHttpInterceptorFn])
+    )
+  ]
+};
+```
+
+---
+
+## React Native Migration
+
+### Authentication
+
+**Before (typical pattern):**
+```typescript
+// Old provider pattern
+const [user, setUser] = useState(null);
+
+const login = async () => {
+  const result = await signIn();
+  setUser(result.user);
+};
+
+const logout = async () => {
+  await signOut();
+  setUser(null);
+};
+```
+
+**After (Auth0):**
+```typescript
+import Auth0 from 'react-native-auth0';
+
+const auth0 = new Auth0({
+  domain: process.env.AUTH0_DOMAIN,
+  clientId: process.env.AUTH0_CLIENT_ID
+});
+
+const [user, setUser] = useState(null);
+
+const login = async () => {
+  try {
+    const credentials = await auth0.webAuth.authorize({
+      scope: 'openid profile email'
+    });
+    setUser(credentials.idTokenPayload);
+  } catch (error) {
+    console.error('Login error:', error);
+  }
+};
+
+const logout = async () => {
+  try {
+    await auth0.webAuth.clearSession();
+    setUser(null);
+  } catch (error) {
+    console.error('Logout error:', error);
+  }
+};
+```
+
+---
+
+## Backend API JWT Validation
+
+### Node.js / Express
+
+**Before (typical pattern):**
+```typescript
+// Old provider pattern
+import jwt from 'jsonwebtoken';
+
+const verifyToken = (token) => {
+  return jwt.verify(token, process.env.JWT_SECRET, {
+    algorithms: ['HS256']
+  });
+};
+
+app.get('/api/protected', async (req, res) => {
+  const token = req.headers.authorization?.split(' ')[1];
+  const user = verifyToken(token);
+  res.json({ data: 'protected' });
+});
+```
+
+**After (Auth0):**
+```typescript
+import jwt from 'jsonwebtoken';
+import { JwksClient } from 'jwks-rsa';
+
+const client = new JwksClient({
+  jwksUri: `https://${process.env.AUTH0_DOMAIN}/.well-known/jwks.json`
+});
+
+async function validateToken(token) {
+  const decoded = jwt.decode(token, { complete: true });
+  const key = await client.getSigningKey(decoded.header.kid);
+
+  return jwt.verify(token, key.getPublicKey(), {
+    algorithms: ['RS256'],
+    audience: process.env.AUTH0_AUDIENCE,
+    issuer: `https://${process.env.AUTH0_DOMAIN}/`
+  });
+}
+
+app.get('/api/protected', async (req, res) => {
+  const token = req.headers.authorization?.split(' ')[1];
+  const user = await validateToken(token);
+  res.json({ data: 'protected' });
+});
+```
+
+**Key Differences:**
+- **Algorithm:** HS256 (symmetric) → RS256 (asymmetric)
+- **Secret:** Shared secret → Public key from JWKS endpoint
+- **Issuer:** Custom → Auth0 tenant URL
+- **Audience:** Optional → Required for API validation
+
+---
+
+### Python / Flask
+
+**Before (typical pattern):**
+```python
+# Old provider pattern
+import jwt
+
+def verify_token(token):
+    return jwt.decode(token, SECRET_KEY, algorithms=['HS256'])
+
+@app.route('/api/protected')
+def protected():
+    token = request.headers.get('Authorization').split(' ')[1]
+    user = verify_token(token)
+    return {'data': 'protected'}
+```
+
+**After (Auth0):**
+```python
+from jose import jwt
+import requests
+
+def get_jwks():
+    jwks_url = f"https://{AUTH0_DOMAIN}/.well-known/jwks.json"
+    return requests.get(jwks_url).json()
+
+def verify_token(token):
+    jwks = get_jwks()
+    unverified_header = jwt.get_unverified_header(token)
+
+    # Find the key
+    rsa_key = {}
+    for key in jwks['keys']:
+        if key['kid'] == unverified_header['kid']:
+            rsa_key = {
+                'kty': key['kty'],
+                'kid': key['kid'],
+                'use': key['use'],
+                'n': key['n'],
+                'e': key['e']
+            }
+
+    return jwt.decode(
+        token,
+        rsa_key,
+        algorithms=['RS256'],
+        audience=AUTH0_AUDIENCE,
+        issuer=f"https://{AUTH0_DOMAIN}/"
+    )
+
+@app.route('/api/protected')
+def protected():
+    token = request.headers.get('Authorization').split(' ')[1]
+    user = verify_token(token)
+    return {'data': 'protected'}
+```
+
+---
+
+## Provider-Specific Patterns
+
+### Firebase to Auth0
+
+**Common Firebase patterns:**
+```typescript
+// Firebase
+import { getAuth, signInWithEmailAndPassword } from 'firebase/auth';
+
+const auth = getAuth();
+const userCredential = await signInWithEmailAndPassword(auth, email, password);
+const user = userCredential.user;
+```
+
+**Auth0 equivalent:**
+```typescript
+// Auth0 - uses redirect flow, not direct credentials
+import { useAuth0 } from '@auth0/auth0-react';
+
+const { loginWithRedirect } = useAuth0();
+await loginWithRedirect();
+```
+
+**Note:** Auth0 uses Universal Login (redirect), not direct email/password submission for better security.
+
+---
+
+### Supabase to Auth0
+
+**Common Supabase patterns:**
+```typescript
+// Supabase
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(url, key);
+const { data, error } = await supabase.auth.signInWithPassword({ email, password });
+```
+
+**Auth0 equivalent:**
+```typescript
+// Auth0
+import { useAuth0 } from '@auth0/auth0-react';
+
+const { loginWithRedirect } = useAuth0();
+await loginWithRedirect();
+```
+
+---
+
+### Clerk to Auth0
+
+**Common Clerk patterns:**
+```typescript
+// Clerk
+import { useUser, useSignIn } from '@clerk/nextjs';
+
+const { isSignedIn, user } = useUser();
+const { signIn } = useSignIn();
+```
+
+**Auth0 equivalent:**
+```typescript
+// Auth0
+import { useUser } from '@auth0/nextjs-auth0/client';
+
+const { user, error, isLoading } = useUser();
+const login = () => window.location.href = '/api/auth/login';
+```
+
+---
+
+## References
+
+- [Auth0 React SDK](https://auth0.com/docs/libraries/auth0-react)
+- [Auth0 Next.js SDK](https://auth0.com/docs/libraries/nextjs)
+- [Auth0 Vue SDK](https://auth0.com/docs/libraries/auth0-vue)
+- [Auth0 Angular SDK](https://auth0.com/docs/libraries/auth0-angular)
+- [Auth0 React Native SDK](https://auth0.com/docs/libraries/react-native-auth0)
+- [Express OpenID Connect](https://auth0.com/docs/libraries/express-openid-connect)
+
+---
+
+# User Export and Import Guide
+
+Detailed guide for exporting users from existing auth providers and importing them to Auth0.
+
+---
+
+## Exporting Users from Common Providers
+
+**Caution:** These export files contain password hashes and PII. Never commit them (add to `.gitignore`), keep them out of shared/CI logs, and delete them once the import succeeds.
+
+### Firebase
+
+**Via Firebase Console:**
+1. Go to Authentication → Users
+2. Click "..." menu → Export users
+3. Downloads JSON file
+
+**Via Firebase CLI:**
+```bash
+firebase auth:export users.json --format=JSON
+```
+
+**Firebase user format:**
+```json
+{
+  "users": [
+    {
+      "localId": "user123",
+      "email": "user@example.com",
+      "emailVerified": true,
+      "passwordHash": "base64-encoded-hash",
+      "salt": "base64-encoded-salt",
+      "createdAt": "1234567890000"
+    }
+  ]
+}
+```
+
+---
+
+### AWS Cognito
+
+**Via AWS CLI:**
+```bash
+aws cognito-idp list-users \
+  --user-pool-id us-east-1_ABC123 \
+  --output json > users.json
+```
+
+**Via Node.js Script:**
+```javascript
+const AWS = require('aws-sdk');
+const cognito = new AWS.CognitoIdentityServiceProvider();
+
+async function exportUsers() {
+  let users = [];
+  let paginationToken;
+
+  do {
+    const response = await cognito.listUsers({
+      UserPoolId: 'us-east-1_ABC123',
+      PaginationToken: paginationToken
+    }).promise();
+
+    users = users.concat(response.Users);
+    paginationToken = response.PaginationToken;
+  } while (paginationToken);
+
+  return users;
+}
+```
+
+---
+
+### Supabase
+
+**Via Supabase SQL:**
+```sql
+-- Connect to Supabase database
+SELECT
+  id,
+  email,
+  email_confirmed_at IS NOT NULL as email_verified,
+  encrypted_password,
+  created_at,
+  raw_user_meta_data
+FROM auth.users;
+```
+
+**Export to JSON:**
+```bash
+psql $DATABASE_URL -c "COPY (SELECT row_to_json(t) FROM (
+  SELECT id, email, encrypted_password, created_at
+  FROM auth.users
+) t) TO STDOUT" > users.json
+```
+
+---
+
+### Custom Database
+
+**Example SQL query:**
+```sql
+SELECT
+  id,
+  email,
+  email_verified,
+  password_hash,
+  created_at,
+  last_login,
+  metadata
+FROM users
+WHERE active = true;
+```
+
+**Export script (Node.js):**
+```javascript
+const { Pool } = require('pg');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+async function exportUsers() {
+  const result = await pool.query(`
+    SELECT
+      id,
+      email,
+      email_verified,
+      password_hash,
+      created_at
+    FROM users
+  `);
+
+  return result.rows.map(row => ({
+    email: row.email,
+    email_verified: row.email_verified,
+    user_id: row.id,
+    created_at: row.created_at.toISOString()
+  }));
+}
+```
+
+---
+
+## Required User Data
+
+### Minimum Required Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `email` | ✅ Yes | User's email address |
+| `email_verified` | ✅ Yes | Whether email is verified (true/false) |
+| `user_id` | No | Original user ID (preserved for reference) |
+| `password` | No* | Only if using password hash |
+| `custom_password_hash` | No* | Password hash with algorithm |
+
+*Either `password` (plain text, not recommended) or `custom_password_hash` required for password-based users.
+
+### Optional Fields
+
+| Field | Description |
+|-------|-------------|
+| `given_name` | First name |
+| `family_name` | Last name |
+| `name` | Full name |
+| `nickname` | Display name |
+| `picture` | Profile picture URL |
+| `created_at` | Account creation timestamp |
+| `user_metadata` | Custom user data (editable by user) |
+| `app_metadata` | Custom app data (not editable by user) |
+
+---
+
+## Auth0 User Import Format
+
+### JSON Structure
+
+```json
+[
+  {
+    "email": "user@example.com",
+    "email_verified": true,
+    "user_id": "original-id-from-old-system",
+    "custom_password_hash": {
+      "algorithm": "bcrypt",
+      "hash": "$2a$10$abcdefghijklmnopqrstuv"
+    },
+    "given_name": "John",
+    "family_name": "Doe",
+    "name": "John Doe",
+    "nickname": "johnd",
+    "picture": "https://example.com/avatar.jpg",
+    "user_metadata": {
+      "hobby": "reading",
+      "plan": "premium",
+      "migrated_from": "firebase"
+    },
+    "app_metadata": {
+      "roles": ["admin"],
+      "permissions": ["read:users", "write:posts"]
+    }
+  }
+]
+```
+
+---
+
+## Password Hash Algorithms
+
+### Supported Algorithms
+
+Auth0 supports these password hashing algorithms:
+
+| Algorithm | Common Usage | Example |
+|-----------|--------------|---------|
+| `bcrypt` | Node.js, Ruby, PHP, Python | `$2a$10$...` |
+| `argon2` | Modern apps, security-focused | `$argon2id$v=19$m=65536...` |
+| `pbkdf2` | Python, Java | Requires iterations, key length |
+| `sha256` | Legacy systems | Not recommended (weak) |
+| `sha512` | Legacy systems | Not recommended (weak) |
+| `md5` | Very old systems | Not recommended (very weak) |
+
+### bcrypt Format
+
+```json
+{
+  "custom_password_hash": {
+    "algorithm": "bcrypt",
+    "hash": "$2a$10$abcdefghijklmnopqrstuv"
+  }
+}
+```
+
+**The hash includes:**
+- `$2a$` - bcrypt identifier
+- `10` - cost factor
+- Rest - salt + hash
+
+---
+
+### argon2 Format
+
+```json
+{
+  "custom_password_hash": {
+    "algorithm": "argon2",
+    "hash": {
+      "encoded": "$argon2id$v=19$m=65536,t=3,p=4$salt$hash"
+    }
+  }
+}
+```
+
+---
+
+### PBKDF2 Format
+
+```json
+{
+  "custom_password_hash": {
+    "algorithm": "pbkdf2",
+    "hash": {
+      "value": "base64-encoded-hash",
+      "encoding": "base64",
+      "key_length": 32,
+      "iterations": 10000,
+      "digest": "sha256"
+    }
+  }
+}
+```
+
+---
+
+### SHA-256/SHA-512 Format
+
+```json
+{
+  "custom_password_hash": {
+    "algorithm": "sha256",
+    "hash": {
+      "value": "hex-encoded-hash",
+      "encoding": "hex"
+    }
+  }
+}
+```
+
+**Note:** Add salt if your system used salted hashes:
+```json
+{
+  "custom_password_hash": {
+    "algorithm": "sha256",
+    "hash": {
+      "value": "hex-encoded-hash",
+      "encoding": "hex"
+    },
+    "salt": {
+      "value": "hex-encoded-salt",
+      "encoding": "hex",
+      "position": "prefix"
+    }
+  }
+}
+```
+
+---
+
+## Importing to Auth0
+
+### Method 1: Auth0 Dashboard
+
+**Steps:**
+1. Go to Auth0 Dashboard
+2. Navigate to **Authentication → Database → [Your Connection]**
+3. Click **Users** tab
+4. Click **Import Users** button
+5. Upload your JSON file
+6. Review and confirm
+
+**Limitations:**
+- File size: Max 500KB per upload
+- Users per file: Recommended max 10,000
+
+---
+
+### Method 2: Auth0 CLI
+
+**Prerequisites:**
+```bash
+# Install Auth0 CLI
+brew install auth0/auth0-cli/auth0
+
+# Login
+auth0 login
+```
+
+**Import users:**
+```bash
+# Get connection ID
+auth0 connections list
+
+# Import users
+auth0 api post "jobs/users-imports" \
+  --data "connection_id=con_ABC123" \
+  --data "users=@users.json"
+```
+
+**Check import status:**
+```bash
+auth0 api get "jobs/{job-id}"
+```
+
+---
+
+### Method 3: Management API
+
+**Using curl:**
+```bash
+curl -X POST "https://YOUR_DOMAIN.auth0.com/api/v2/jobs/users-imports" \
+  -H "Authorization: Bearer YOUR_MGMT_API_TOKEN" \
+  -H "Content-Type: multipart/form-data" \
+  -F "users=@users.json" \
+  -F "connection_id=con_ABC123" \
+  -F "upsert=false" \
+  -F "send_completion_email=true"
+```
+
+**Using Node.js:**
+```javascript
+const { ManagementClient } = require('auth0');
+const fs = require('fs');
+
+const management = new ManagementClient({
+  domain: process.env.AUTH0_DOMAIN,
+  clientId: process.env.AUTH0_CLIENT_ID,
+  clientSecret: process.env.AUTH0_CLIENT_SECRET
+});
+
+async function importUsers() {
+  const users = fs.readFileSync('users.json');
+
+  const job = await management.importUsers({
+    connection_id: 'con_ABC123',
+    users: users,
+    upsert: false,
+    send_completion_email: true
+  });
+
+  console.log(`Import job created: ${job.id}`);
+  return job;
+}
+```
+
+---
+
+## Import Options
+
+### upsert
+
+- `true`: Update existing users, create new ones
+- `false` (default): Only create new users, skip existing
+
+**When to use:**
+- `upsert=true`: Re-running imports with updated data
+- `upsert=false`: Initial migration, avoid accidental overwrites
+
+---
+
+### send_completion_email
+
+- `true`: Email you when import completes
+- `false`: No email notification
+
+**Useful for:** Large imports that take time
+
+---
+
+### external_id
+
+Add to track which users were imported:
+
+```json
+{
+  "email": "user@example.com",
+  "external_id": "firebase:user123"
+}
+```
+
+---
+
+## Monitoring Import Progress
+
+### Check Job Status
+
+```bash
+# Via CLI
+auth0 api get "jobs/{job-id}"
+
+# Via Management API
+curl "https://YOUR_DOMAIN.auth0.com/api/v2/jobs/{job-id}" \
+  -H "Authorization: Bearer YOUR_MGMT_API_TOKEN"
+```
+
+**Response:**
+```json
+{
+  "id": "job_abc123",
+  "type": "users_import",
+  "status": "processing",
+  "created_at": "2025-01-20T10:00:00.000Z",
+  "connection_id": "con_ABC123",
+  "summary": {
+    "total": 1000,
+    "inserted": 950,
+    "updated": 0,
+    "failed": 50
+  }
+}
+```
+
+**Status values:**
+- `pending`: Job queued
+- `processing`: Import in progress
+- `completed`: Import finished successfully
+- `failed`: Import failed
+
+---
+
+### Download Error Report
+
+If import has failures:
+
+```bash
+# Get errors file URL
+auth0 api get "jobs/{job-id}/errors"
+
+# Download errors
+curl "https://YOUR_DOMAIN.auth0.com/api/v2/jobs/{job-id}/errors" \
+  -H "Authorization: Bearer YOUR_MGMT_API_TOKEN" \
+  -o import-errors.json
+```
+
+**Error format:**
+```json
+[
+  {
+    "user": {
+      "email": "invalid@example"
+    },
+    "errors": [
+      {
+        "code": "INVALID_EMAIL",
+        "message": "Email format is invalid"
+      }
+    ]
+  }
+]
+```
+
+---
+
+## Common Import Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `INVALID_EMAIL` | Email format invalid | Validate and fix email format |
+| `DUPLICATE_USER` | User already exists | Use `upsert=true` or skip |
+| `INVALID_PASSWORD_HASH` | Hash format incorrect | Check algorithm and format |
+| `MISSING_REQUIRED_FIELD` | Required field missing | Add email and email_verified |
+| `CONNECTION_NOT_FOUND` | Invalid connection ID | Verify connection ID |
+| `FILE_TOO_LARGE` | File exceeds limit | Split into smaller files |
+| `INVALID_JSON` | JSON syntax error | Validate JSON format |
+
+---
+
+## Best Practices
+
+### Prepare Your Data
+
+1. **Validate emails:** Remove invalid/duplicate emails
+2. **Verify JSON:** Use JSON validator before upload
+3. **Test with small batch:** Import 10-100 users first
+4. **Backup original data:** Keep copy of export
+
+### Split Large Imports
+
+```bash
+# Split into 5000-user chunks
+split -l 5000 users.json users-chunk-
+
+# Import each chunk
+for file in users-chunk-*; do
+  auth0 api post "jobs/users-imports" \
+    --data "connection_id=con_ABC123" \
+    --data "users=@$file"
+done
+```
+
+### Add Migration Metadata
+
+Track migration for each user:
+
+```json
+{
+  "email": "user@example.com",
+  "user_metadata": {
+    "migrated": true,
+    "migrated_at": "2025-01-20T10:00:00.000Z",
+    "migrated_from": "firebase",
+    "original_id": "firebase-user-123"
+  }
+}
+```
+
+---
+
+## Post-Import Verification
+
+### Check User Count
+
+```bash
+# Get total users in Auth0
+auth0 users list --number 1
+
+# Or via API
+curl "https://YOUR_DOMAIN.auth0.com/api/v2/users?per_page=1" \
+  -H "Authorization: Bearer YOUR_MGMT_API_TOKEN" \
+  | jq '.total'
+```
+
+### Test Login
+
+```bash
+# Test user can login
+auth0 test login --client-id YOUR_CLIENT_ID
+```
+
+### Verify Password Hashes Work
+
+Pick random users and attempt login to verify password hashes imported correctly.
+
+---
+
+## References
+
+- [Auth0 Bulk User Import](https://auth0.com/docs/manage-users/user-migration/bulk-user-imports)
+- [Password Hash Algorithms](https://auth0.com/docs/manage-users/user-migration/bulk-user-imports#password-hashing-algorithms)
+- [Management API - User Import Job](https://auth0.com/docs/api/management/v2/jobs/post-users-imports)
+- [User Import Best Practices](https://auth0.com/docs/manage-users/user-migration/bulk-user-imports#best-practices)
diff --git a/main/.mintlify/skills/auth0/references/feature-organizations/index.md b/main/.mintlify/skills/auth0/references/feature-organizations/index.md
new file mode 100644
index 0000000000..13e7d026da
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/feature-organizations/index.md
@@ -0,0 +1,138 @@
+# Auth0 Organizations
+
+Multi-tenant B2B authentication. Organizations let each of your customers have their own isolated user pool, roles, and connections — all within one Auth0 tenant.
+
+---
+
+## When to use Organizations
+
+Use Organizations when you need:
+- Multiple business customers (tenants), each with their own users and SSO
+- Per-org user roles and permissions
+- Different login connections per customer (e.g., Okta SSO for CustomerA, Google Workspace for CustomerB)
+- Organization-scoped invitations and member management
+
+Do NOT use Organizations for consumer apps (B2C). Organizations is a B2B construct — instead, use plain Auth0 connections within a single tenant for B2C, and reserve Organizations for B2B multi-tenant scenarios.
+
+---
+
+## Concepts
+
+| Concept | Description |
+|---|---|
+| **Organization** | An isolated tenant within your Auth0 tenant. Has an `id` (org_xxx) and `name` (slug). |
+| **Member** | A user belonging to an organization. A user can belong to multiple orgs. |
+| **Org-level role** | A role granted to a user within a specific org (not globally). |
+| **Connection** | A login method enabled for an org (database, enterprise SSO, social). |
+| **Invitation** | A time-limited invite to join an org, sent by email. |
+
+---
+
+## SDK Integration
+
+### Pass organization at login
+
+All Auth0 SDKs support passing `organization` in `authorizationParams` (or equivalent):
+
+**React:**
+```javascript
+loginWithRedirect({
+  authorizationParams: { organization: 'org_xxxxx' }
+});
+```
+
+**Next.js (nextjs-auth0 v4):**
+```javascript
+// Pass org via URL param: /auth/login?organization=org_xxx
+// The nextjs-auth0 handler forwards it automatically
+```
+
+**Vue:**
+```javascript
+loginWithRedirect({
+  authorizationParams: { organization: 'org_xxxxx' }
+});
+```
+
+**Express:**
+```javascript
+app.get('/login/:orgId', (req, res) => {
+  res.oidc.login({ authorizationParams: { organization: req.params.orgId } });
+});
+```
+
+### Read org from access token
+
+After login, the access token includes `org_id` and `org_name` claims:
+
+```javascript
+const { org_id, org_name } = tokenPayload;
+```
+
+### Validate org on the backend
+
+Validate `org_id` on your API to prevent cross-tenant access:
+
+```javascript
+// Express example
+app.get('/api/data', checkJwt, (req, res) => {
+  const orgId = req.auth.payload.org_id;
+  if (orgId !== expectedOrgId) {
+    return res.status(403).json({ error: 'Wrong organization' });
+  }
+});
+```
+
+---
+
+## Tenant Configuration (via chosen tooling)
+
+See your tooling reference file for the full command syntax. The Auth0 MCP server
+exposes **no** organizations tool, so for an MCP-only session fall back to the CLI
+or Terraform. The operations are:
+
+**Create an organization:**
+- CLI: `auth0 orgs create`
+- Terraform: `auth0_organization` resource
+
+**Add a member:**
+- CLI: `auth0 orgs members add`
+- Terraform: `auth0_organization_member` resource
+
+**Enable a connection for an org:**
+- CLI: `auth0 orgs connections add`
+- Terraform: `auth0_organization_connections` resource
+
+**Assign a role within an org:**
+- CLI: `auth0 orgs roles assign`
+- Management API: `POST /api/v2/organizations/{id}/members/{user_id}/roles`
+
+---
+
+## Invitation flow
+
+```bash
+# Create an invitation (user doesn't need an Auth0 account yet)
+auth0 api post /api/v2/organizations/{org_id}/invitations \
+  --data '{"invitee":{"email":"user@company.com"},"inviter":{"name":"Admin"},"client_id":"YOUR_CLIENT_ID"}'
+```
+
+The invitee receives an email. When they click the link, they authenticate and are added as a member.
+
+---
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Forgetting `organization` in `authorizationParams` | Always pass the org identifier at login time |
+| Using `org_id` from ID token on backend | Validate from the access token, not ID token |
+| Mixing up org `id` (org_xxx) and `name` (slug) | `id` for API calls, `name` for display |
+| Granting global roles instead of org-level roles | Use the org member roles endpoint, not the user roles endpoint |
+| Not enabling a connection for the org | Dashboard → Organization → Connections → enable the connection |
+
+---
+
+## Multi-tenant architecture
+
+For broader B2B SaaS architecture guidance (tenant isolation models, when to use one Auth0 organization per customer vs. shared connections), the router loads the multi-tenant pattern guidance alongside this file for architecture questions.
diff --git a/main/.mintlify/skills/auth0/references/framework-android/index.md b/main/.mintlify/skills/auth0/references/framework-android/index.md
new file mode 100644
index 0000000000..c508a7824f
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-android/index.md
@@ -0,0 +1,1900 @@
+
+# Auth0 Android Integration
+
+Add authentication to Android applications using `com.auth0.android:auth0`.
+
+> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
+> ```
+> gh api repos/auth0/Auth0.Android/releases/latest --jq '.tag_name'
+> ```
+> Use the returned version in all `implementation` dependency lines instead of any hardcoded version below. If the command fails, fall back to checking https://github.com/auth0/Auth0.Android/releases.
+
+## Critical rules
+
+- Before running any part of the automatic setup that writes to `strings.xml`, you MUST ask the user for explicit confirmation before proceeding.
+- After either automatic or manual Auth0 configuration, you MUST apply the required Post-Setup changes to the project (manifest placeholders in `app/build.gradle` for `auth0Domain` and `auth0Scheme`, etc.) before treating the integration as complete.
+
+## Prerequisites
+
+- Android API 21 or higher
+- Kotlin or Java project
+- Auth0 account with a Native application configured
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **React Native apps**: Use the Auth0 React Native integration
+- **Flutter apps**: Use the native Flutter Auth0 SDK
+- **Web SPAs** (React, Angular, Vue): Use the Auth0 React, Angular, or Vue integration
+- **Node.js/Express servers**: Use the Auth0 Express integration
+- **iOS/macOS apps**: Use the Auth0 Swift integration
+
+## Quick Start Workflow
+
+1. **Install SDK**: Add the Auth0 Android SDK dependency to your `build.gradle`:
+   ```gradle
+   implementation 'com.auth0.android:auth0:{LATEST_VERSION}'
+   ```
+
+2. **Configure Auth0**:
+
+   > **Agent instruction:** Check whether the user prompt already includes both Auth0 **Client ID** and **Domain**.
+   > - If both are provided, proceed directly to **Manual Setup** in the Setup Guide section below using those values.
+   > - If either is missing, you MUST ask the user BEFORE writing any code or files:
+   >   - Question: "How would you like to configure Auth0 for this project?"
+   >   - Options: "Automatic setup (Recommended) — Auth0 CLI creates the app and writes credentials to strings.xml" / "Manual setup — I'll provide my Client ID and Domain"
+   >
+   > Then follow the Setup Guide section below for the chosen path.
+   > **Do NOT proceed to step 3 until Auth0 credentials are confirmed.**
+
+3. **Initialize**: Create an Auth0 account instance:
+   ```kotlin
+   import com.auth0.android.Auth0
+
+   val account = Auth0.getInstance(context)
+   ```
+   > **IMPORTANT:** `Auth0.getInstance(context)` auto-reads `com_auth0_client_id` and `com_auth0_domain` from `strings.xml`. **Never** pass `clientId` or `domain` as arguments (e.g. `Auth0.getInstance(clientId, domain)`) — that hardcodes credentials in source.
+
+4. **Add Auth UI**: Implement login and logout with Web Auth:
+
+   > **Agent instruction:** Before adding new UI elements, search the project for existing click handlers for login, logout, sign-in, or sign-out buttons (e.g., `loginButton`, `signInButton`, `logoutButton`, `signOutButton`, or `setOnClickListener` with auth-related naming). If existing handlers are found, hook the Auth0 code into them without modifying the existing UI. Only create new buttons if no existing handlers are found.
+
+   **Login:**
+   ```kotlin
+   import com.auth0.android.Auth0
+   import com.auth0.android.authentication.AuthenticationAPIClient
+   import com.auth0.android.authentication.storage.SecureCredentialsManager
+   import com.auth0.android.authentication.storage.SharedPreferencesStorage
+   import com.auth0.android.callback.Callback
+   import com.auth0.android.authentication.AuthenticationException
+   import com.auth0.android.provider.WebAuthProvider
+   import com.auth0.android.result.Credentials
+
+   val account = Auth0.getInstance(context)
+   val authentication = AuthenticationAPIClient(account)
+   val storage = SharedPreferencesStorage(context)
+   val credentialsManager = SecureCredentialsManager(context, authentication, storage)
+
+   WebAuthProvider.login(account)
+       .withScheme(getString(R.string.com_auth0_scheme))
+       .withScope("openid profile email offline_access")
+       .start(this, object : Callback<Credentials, AuthenticationException> {
+           override fun onSuccess(result: Credentials) {
+               // User authenticated
+               val idToken = result.idToken
+               val accessToken = result.accessToken
+               // Store credentials securely
+               credentialsManager.saveCredentials(result)
+           }
+           override fun onFailure(error: AuthenticationException) {
+               // Handle authentication failure
+               Log.e("Auth0", "Authentication failed", error)
+           }
+       })
+   ```
+
+   **Logout:**
+   ```kotlin
+   WebAuthProvider.logout(account)
+       .withScheme(getString(R.string.com_auth0_scheme))
+       .start(this, object : Callback<Void?, AuthenticationException> {
+           override fun onSuccess(result: Void?) {
+               // User logged out
+           }
+           override fun onFailure(error: AuthenticationException) {
+               Log.e("Auth0", "Logout failed", error)
+           }
+       })
+   ```
+
+5. **Build & Verify**:
+
+   > **Agent instruction:** After completing the integration, build the project to verify it compiles successfully:
+   > ```bash
+   > ./gradlew assembleDebug
+   > ```
+   > If the build fails, analyze the error output and fix the issues. Common integration build failures include:
+   > - **Unresolved reference**: Missing import statements — add the required `import com.auth0.android.*` imports
+   > - **Cannot resolve symbol `R.string.com_auth0_scheme`**: `strings.xml` not updated — verify `com_auth0_scheme`, `com_auth0_client_id`, and `com_auth0_domain` entries exist
+   > - **Incompatible types in callback**: Callback type parameters don't match — ensure `Callback<Credentials, AuthenticationException>` for login and `Callback<Void?, AuthenticationException>` for logout
+   > - **Unresolved `lifecycleScope`**: Missing dependency — add `implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.6.+'` or move code out of coroutine scope
+   > - **minSdk too low**: SDK requires API 21+ — update `minSdkVersion` to at least 21
+   > - **Java version mismatch**: SDK requires Java 8 — add `compileOptions` with `JavaVersion.VERSION_1_8`
+   >
+   > Re-run the build after each fix. Track the number of build-fix iterations.
+   >
+   > **Failcheck:** If the build still fails after 5–6 fix attempts, stop and ask the user:
+   > - Question: "The build is still failing after several fix attempts. How would you like to proceed?"
+   > - Options: "Let the agent continue fixing iteratively" / "I'll fix it manually — show me the errors" / "Skip build verification and proceed"
+   >
+   > Repeat this check after every 5–6 iterations if errors persist. Do not leave the project in a non-compiling state without the user's explicit consent.
+
+   The callback URL must match your Auth0 application settings: `{SCHEME}://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback`
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Hardcoding credentials via `Auth0.getInstance(clientId, domain)` | Use `Auth0.getInstance(context)` — it auto-reads `com_auth0_client_id` and `com_auth0_domain` from `strings.xml`. Never pass the client ID or domain as arguments or string literals in source. |
+| App type not set to Native in Auth0 Dashboard | Create a Native application type in your Auth0 tenant. The Android SDK requires Native app configuration, not Machine-to-Machine or other types. |
+| Missing callback URL in Allowed Callback URLs | Add `{SCHEME}://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback` to your Auth0 application's Allowed Callback URLs setting, where `{SCHEME}` matches `com_auth0_scheme` in `strings.xml` (e.g., `demo` by default). |
+| Missing `<uses-permission android:name="android.permission.INTERNET" />` | Add the INTERNET permission to `AndroidManifest.xml`. The SDK requires network access for authentication. |
+| Custom scheme in lowercase | Android requires scheme names to be lowercase. Use `https` (recommended) or lowercase custom scheme like `myapp://callback`. |
+| Forgetting `.validateClaims()` on direct auth calls | Always call `.validateClaims()` when using `AuthenticationAPIClient` directly (for database, passwordless, or API login). Web Auth validates automatically. |
+| Storing tokens in SharedPreferences without encryption | Use `SecureCredentialsManager` to store credentials. Never store tokens manually in plain text. The manager encrypts tokens at rest. |
+| Missing manifest placeholders | Add `manifestPlaceholders = [auth0Domain: "@string/com_auth0_domain", auth0Scheme: "@string/com_auth0_scheme"]` to your `build.gradle` `defaultConfig` block. |
+
+## Related Capabilities
+
+- Auth0 setup — set it up with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- iOS/macOS authentication → use the Auth0 Swift integration
+- Manage Auth0 resources from the terminal → use the Auth0 CLI (`tooling-cli`)
+
+## Quick Reference
+
+### Core Classes
+
+| Class | Purpose |
+|-------|---------|
+| `Auth0` | Entry point for SDK, holds app credentials |
+| `WebAuthProvider` | OAuth 2.0 login/logout via browser |
+| `AuthenticationAPIClient` | Direct API calls (database login, passwordless, MFA) |
+| `SecureCredentialsManager` | Secure storage and retrieval of credentials |
+| `Credentials` | User tokens and expiration |
+
+### Common Use Cases
+
+- Log in with Web Auth (see the Web Auth Login section below)
+- Log out (see the Web Auth Logout section below)
+- Store credentials securely (see the Credential Storage section below)
+- Require biometric authentication (see the Biometric-Protected Credentials section below)
+- Database login (see the Database Login section below)
+- Passwordless authentication (see the Passwordless Authentication section below)
+- Handle MFA (see the MFA Handling section below)
+- Call protected APIs (see the Calling Protected APIs section below)
+
+## References
+
+- [Auth0 Android SDK Documentation](https://auth0.com/docs/libraries/auth0-android)
+- [Auth0 Android GitHub Repository](https://github.com/auth0/auth0-android)
+- [Android SDK Javadoc](https://auth0.com/docs/references/android)
+- [Auth0 Android Quickstart](https://auth0.com/docs/quickstart/native/android)
+- [Sample App](https://github.com/auth0-samples/auth0-android-sample)
+
+---
+
+# Auth0 Android Testing & Reference
+
+## Testing Checklist
+
+Before deploying your Auth0 Android integration, verify:
+
+- [ ] **Emulator Testing**
+  - [ ] Login flow completes end-to-end
+  - [ ] Logout clears credentials
+  - [ ] Credentials persist after app restart
+  - [ ] Token refresh works when token expires
+  - [ ] Error messages display correctly
+
+- [ ] **Physical Device Testing**
+  - [ ] Login flow works on actual device
+  - [ ] Custom Tabs browser opens correctly
+  - [ ] Deep link callback works (https:// or custom scheme)
+  - [ ] Biometric authentication prompts appear (if implemented)
+  - [ ] App Links work with https:// scheme
+
+- [ ] **Auth0 Configuration**
+  - [ ] Callback URL matches exactly in Auth0 Dashboard
+  - [ ] Logout URL configured in Auth0 Dashboard
+  - [ ] Application type is "Native" (not SPA or Machine-to-Machine)
+  - [ ] Client ID and domain are correct
+
+- [ ] **Security**
+  - [ ] Credentials stored via SecureCredentialsManager
+  - [ ] No tokens logged to console
+  - [ ] INTERNET permission added to manifest
+  - [ ] ProGuard rules not stripping Auth0 classes
+
+- [ ] **Edge Cases**
+  - [ ] User cancels login mid-flow
+  - [ ] Network timeout during login
+  - [ ] Device goes to sleep during login
+  - [ ] Token refresh fails gracefully
+  - [ ] MFA challenges work (if enabled)
+
+## Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Deep link not working after login | Callback URL mismatch or manifest placeholders not set | Verify callback URL format: `https://{DOMAIN}/android/{PACKAGE}/callback`. Ensure `auth0Domain` and `auth0Scheme` in manifest placeholders. Rebuild and reinstall app. |
+| "Invalid state" error on redirect | Authentication session timed out or was invalidated | This can happen after long delays or device sleep. Redirect user to login again. For testing, keep login window active. |
+| Custom Tabs browser not opening | No browser available on device or Custom Tabs disabled | Check `error.isBrowserAppNotAvailable`. Ensure device has Chrome or compatible browser. Fallback to system browser if needed. |
+| Biometric prompt not showing | Min API < 21, biometric not enrolled, or options not set | Set min SDK to 21+. Enroll fingerprint/face on device. Verify `LocalAuthenticationOptions` and `BiometricPolicy` configuration. Check `setDeviceCredentialFallback(true)` for PIN/password fallback. |
+| Token refresh fails and user can't access APIs | Refresh token expired (typically after 30 days of inactivity) | Catch `CredentialsManagerException` with code `REFRESH_FAILED`. Trigger `WebAuthProvider.login()` to re-authenticate. Inform user they need to log in again. |
+| ProGuard/R8 strips Auth0 classes and crashes | ProGuard rules not applied | Auth0 rules are bundled automatically. If issues occur, add `-keep class com.auth0.** { *; }` to your `proguard-rules.pro` or disable minification for testing. |
+| Login works on emulator but fails on physical device | Certificate pinning or network differences | Ensure device has valid time/date. Check network connectivity. For HTTPS scheme, verify Digital Asset Links are set up for your domain. |
+| Credentials lost after app update | Shared storage encrypted with device key that changed | This is expected behavior after major system updates. Gracefully handle `NO_CREDENTIALS` and redirect to login. |
+
+## Security Considerations
+
+### PKCE Enabled by Default
+
+The Auth0 Android SDK automatically enables PKCE (Proof Key for Code Exchange) for all authorization flows. PKCE provides an extra layer of security for native apps and is always used by `WebAuthProvider`.
+
+### Secure Credential Storage
+
+Always use `SecureCredentialsManager` for token storage:
+
+```kotlin
+val authentication = AuthenticationAPIClient(account)
+val storage = SharedPreferencesStorage(context)
+val manager = SecureCredentialsManager(context, authentication, storage)
+manager.saveCredentials(credentials)  // Encrypted at rest
+```
+
+Never store tokens in:
+- Plain `SharedPreferences` — Not encrypted
+- `DataStore` without encryption — Unencrypted
+- App-level files — Accessible to other apps
+
+### HTTPS Scheme Recommended
+
+Prefer `https://` scheme over custom schemes:
+
+```gradle
+manifestPlaceholders = [
+    auth0Domain: "@string/com_auth0_domain",
+    auth0Scheme: "@string/com_auth0_scheme"
+]
+```
+
+Benefits:
+- Leverages Android App Links for secure deep linking
+- Requires Digital Asset Links verification
+- No prompt when opening links
+- More difficult to intercept
+
+Custom schemes are lower security but work if HTTPS is not feasible.
+
+### Never Log Tokens
+
+Do not log access tokens, ID tokens, or refresh tokens:
+
+```kotlin
+// BAD
+Log.d("Auth0", "Token: ${credentials.accessToken}")
+
+// GOOD
+Log.d("Auth0", "Authentication successful")
+```
+
+Logs may be accessible via `adb logcat` or included in crash reports.
+
+### Validate Tokens
+
+Always call `.validateClaims()` when using direct API calls:
+
+```kotlin
+authentication.login(...)
+    .validateClaims()  // Validates ID token claims
+    .start(callback)
+```
+
+This verifies:
+- Token signature
+- Token expiration
+- Audience (aud) claim
+- Issuer (iss) claim
+
+`WebAuthProvider` validates automatically, but direct API calls do not.
+
+### Biometric Protection
+
+When storing credentials with biometric protection, use strong authentication:
+
+```kotlin
+val options = LocalAuthenticationOptions.Builder()
+    .setAuthenticationLevel(AuthenticationLevel.STRONG)
+    .setPolicy(BiometricPolicy.Always)
+    .build()
+```
+
+Avoid:
+- `AuthenticationLevel.WEAK` for sensitive operations
+- `BiometricPolicy.Never` when protecting credentials
+- `setDeviceCredentialFallback(true)` with WEAK level
+
+## API Reference
+
+### Auth0
+
+Entry point for SDK initialization:
+
+```kotlin
+// Always initialize from strings.xml — never pass the client ID or domain as
+// string literals in Kotlin/Java source.
+val account = Auth0.getInstance(context)
+```
+
+> The `com_auth0_client_id` and `com_auth0_domain` values live in `strings.xml`
+> (`res/values/strings.xml`), and `Auth0.getInstance(context)` reads them from
+> there. Do NOT hardcode credentials in `.kt`/`.java` source — keep
+> configuration in `strings.xml` so it stays in one place and matches the SDK's
+> expected setup.
+
+### WebAuthProvider
+
+Browser-based OAuth 2.0 flow:
+
+```kotlin
+WebAuthProvider.login(account)
+    .withScheme(getString(R.string.com_auth0_scheme))
+    .withScope("openid profile email")
+    .withAudience("https://api.example.com")
+    .withConnection("google-oauth2")
+    .withOrganization("org_id")
+    .withInvitation("invitation_id")
+    .withPrompt("login")  // "login" or "none"
+    .withCustomTabsOptions(customTabs)
+    .start(context, callback)
+
+WebAuthProvider.logout(account)
+    .withScheme(getString(R.string.com_auth0_scheme))
+    .start(context, callback)
+```
+
+### AuthenticationAPIClient
+
+Direct API calls:
+
+```kotlin
+val authentication = AuthenticationAPIClient(account)
+
+authentication.login(email, password, realm)
+authentication.signUp(email, password, username, connection)
+authentication.passwordlessWithEmail(email, type)
+authentication.loginWithEmail(email, code)
+authentication.mfaClient(mfaToken)
+```
+
+### SecureCredentialsManager
+
+Secure credential storage:
+
+```kotlin
+val authentication = AuthenticationAPIClient(account)
+val storage = SharedPreferencesStorage(context)
+val manager = SecureCredentialsManager(context, authentication, storage)
+
+manager.saveCredentials(credentials)
+manager.hasValidCredentials(): Boolean
+manager.getCredentials(callback)
+manager.clearCredentials()
+```
+
+### Credentials
+
+User tokens and metadata:
+
+```kotlin
+val accessToken = credentials.accessToken      // OAuth 2.0 access token
+val idToken = credentials.idToken              // OpenID Connect ID token
+val refreshToken = credentials.refreshToken    // Refresh token
+val expiresAt = credentials.expiresAt          // Expiration timestamp
+val scope = credentials.scope                  // Granted scopes
+val type = credentials.type                    // "Bearer"
+
+// ID token claims
+val sub = credentials.claims["sub"]            // Subject (user ID)
+val name = credentials.claims["name"]
+val email = credentials.claims["email"]
+val emailVerified = credentials.claims["email_verified"]
+```
+
+### LocalAuthenticationOptions
+
+Biometric authentication configuration:
+
+```kotlin
+LocalAuthenticationOptions.Builder()
+    .setTitle("Authenticate")
+    .setDescription("Verify your identity")
+    .setAuthenticationLevel(AuthenticationLevel.STRONG)
+    .setNegativeButtonText("Cancel")
+    .setDeviceCredentialFallback(true)
+    .setPolicy(BiometricPolicy.Session(300))
+    .build()
+```
+
+### Exception Handling
+
+```kotlin
+// AuthenticationException
+error.isMultifactorRequired: Boolean
+error.isBrowserAppNotAvailable: Boolean
+error.isAuthenticationCanceled: Boolean
+error.statusCode: Int
+error.message: String?
+
+// CredentialsManagerException
+error.code: String  // "NO_CREDENTIALS", "CREDENTIALS_EXPIRED", "REFRESH_FAILED"
+error.message: String?
+```
+
+## Related Capabilities
+
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- Auth0 setup — set it up with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- iOS/macOS authentication → use the Auth0 Swift integration
+- React Native authentication → use the Auth0 React Native integration
+
+## References
+
+- [Auth0 Android SDK Documentation](https://auth0.com/docs/libraries/auth0-android)
+- [Auth0 Android Quickstart](https://auth0.com/docs/quickstart/native/android)
+- [Auth0 Android GitHub Repository](https://github.com/auth0/auth0-android)
+- [Android SDK Javadoc](https://auth0.com/docs/references/android)
+- [Sample App](https://github.com/auth0-samples/auth0-android-sample)
+- [Android Security Best Practices](https://developer.android.com/privacy-and-security)
+
+---
+
+# Auth0 Android Integration Patterns
+
+> **Agent instruction:** Before creating new UI elements (buttons, click handlers), search the user's project for existing login/logout/sign-in/sign-out click handlers. If found, hook Auth0 code into the existing handlers without modifying the UI. Only create new buttons if no existing handlers are found.
+
+## Web Auth Login
+
+Use the browser-based Web Auth flow for the most secure login experience:
+
+```kotlin
+import com.auth0.android.Auth0
+import com.auth0.android.provider.WebAuthProvider
+import com.auth0.android.callback.Callback
+import com.auth0.android.result.Credentials
+import com.auth0.android.authentication.AuthenticationException
+
+val account = Auth0.getInstance(context)
+
+WebAuthProvider.login(account)
+    .withScheme(getString(R.string.com_auth0_scheme))
+    .withScope("openid profile email offline_access")
+    .withAudience("https://api.example.com")  // Optional: your API audience
+    .withOrganization("org_abc123")  // Optional: for organization login
+    .start(context, object : Callback<Credentials, AuthenticationException> {
+        override fun onSuccess(result: Credentials) {
+            // User authenticated successfully
+            val idToken = result.idToken
+            val accessToken = result.accessToken
+            val refreshToken = result.refreshToken
+            val expiresAt = result.expiresAt
+
+            // Store credentials securely (see Credential Storage section)
+        }
+
+        override fun onFailure(error: AuthenticationException) {
+            // Handle authentication failure
+            when {
+                error.isBrowserAppNotAvailable -> {
+                    // No browser available on device
+                }
+                error.isAuthenticationCanceled -> {
+                    // User canceled the login
+                }
+                else -> {
+                    // Other authentication error
+                    Log.e("Auth0", error.message.orEmpty())
+                }
+            }
+        }
+    })
+```
+
+**Options**:
+- `.withScheme()` — URL scheme matching `com_auth0_scheme` in strings.xml (required)
+- `.withScope()` — Requested scopes (space-separated)
+- `.withAudience()` — Your API identifier for the access token
+- `.withOrganization()` — Organization ID or name for SSO
+- `.withConnection()` — Force a specific connection (e.g., "google-oauth2")
+- `.withPrompt()` — Force login prompt: `"login"` or `"none"`
+
+## Web Auth Logout
+
+Log out the user and clear their session:
+
+```kotlin
+WebAuthProvider.logout(account)
+    .withScheme(getString(R.string.com_auth0_scheme))  // Match your configured scheme
+    .start(this, object : Callback<Void?, AuthenticationException> {
+        override fun onSuccess(result: Void?) {
+            // User logged out successfully
+            // Clear your app's local state
+        }
+
+        override fun onFailure(error: AuthenticationException) {
+            // Logout failed
+            Log.e("Auth0", "Logout error: ${error.message}")
+        }
+    })
+```
+
+After logout, clear stored credentials:
+
+```kotlin
+val authentication = AuthenticationAPIClient(account)
+val storage = SharedPreferencesStorage(this)
+val manager = SecureCredentialsManager(this, authentication, storage)
+manager.clearCredentials()
+```
+
+## Credential Storage
+
+Store and retrieve credentials securely using `SecureCredentialsManager`:
+
+```kotlin
+import com.auth0.android.authentication.AuthenticationAPIClient
+import com.auth0.android.authentication.storage.CredentialsManagerException
+import com.auth0.android.authentication.storage.SecureCredentialsManager
+import com.auth0.android.authentication.storage.SharedPreferencesStorage
+import com.auth0.android.callback.Callback
+import com.auth0.android.result.Credentials
+
+val authentication = AuthenticationAPIClient(account)
+val storage = SharedPreferencesStorage(context)
+val manager = SecureCredentialsManager(context, authentication, storage)
+
+// Save credentials after login
+manager.saveCredentials(credentials)
+
+// Check if valid credentials exist
+if (manager.hasValidCredentials()) {
+    // Valid credentials stored
+}
+
+// Retrieve credentials (auto-refreshes if needed)
+manager.getCredentials(object : Callback<Credentials, CredentialsManagerException> {
+    override fun onSuccess(result: Credentials) {
+        val accessToken = result.accessToken
+        val idToken = result.idToken
+        // Use tokens for API calls
+    }
+
+    override fun onFailure(error: CredentialsManagerException) {
+        when (error.code) {
+            "NO_CREDENTIALS" -> {
+                // No credentials stored
+            }
+            "CREDENTIALS_EXPIRED" -> {
+                // Credentials expired, user needs to login again
+            }
+            "REFRESH_FAILED" -> {
+                // Refresh token expired, trigger re-authentication
+            }
+            else -> Log.e("CredentialsManager", error.message.orEmpty())
+        }
+    }
+})
+
+// Clear credentials (logout)
+manager.clearCredentials()
+```
+
+**Key Features**:
+- Credentials are encrypted at rest
+- Automatic token refresh when credentials expire
+- Handles refresh token expiration gracefully
+
+## Biometric-Protected Credentials
+
+Protect stored credentials with biometric authentication:
+
+```kotlin
+import com.auth0.android.authentication.AuthenticationAPIClient
+import com.auth0.android.authentication.storage.SecureCredentialsManager
+import com.auth0.android.authentication.storage.SharedPreferencesStorage
+import com.auth0.android.authentication.storage.LocalAuthenticationOptions
+import com.auth0.android.authentication.storage.AuthenticationLevel
+import com.auth0.android.authentication.storage.BiometricPolicy
+import androidx.fragment.app.FragmentActivity
+
+val localAuthOptions = LocalAuthenticationOptions.Builder()
+    .setTitle("Authenticate")
+    .setDescription("Verify your fingerprint to access your account")
+    .setAuthenticationLevel(AuthenticationLevel.STRONG)  // Fingerprint or face recognition
+    .setNegativeButtonText("Cancel")
+    .setDeviceCredentialFallback(true)  // Allow PIN/password fallback
+    .setPolicy(BiometricPolicy.Session(300))  // Require biometric every 5 minutes
+    .build()
+
+val fragmentActivity: FragmentActivity = this  // Your Activity
+val authentication = AuthenticationAPIClient(account)
+val storage = SharedPreferencesStorage(context)
+val manager = SecureCredentialsManager(
+    context,
+    authentication,
+    storage,
+    fragmentActivity,
+    localAuthOptions
+)
+
+// Credentials are now biometric-protected
+manager.saveCredentials(credentials)
+
+// User must authenticate with biometric/device credential to retrieve
+manager.getCredentials(callback)
+```
+
+**Authentication Levels**:
+- `AuthenticationLevel.STRONG` — Biometric authentication required
+- `AuthenticationLevel.WEAK` — Biometric or device credential (PIN/password)
+- `AuthenticationLevel.DEVICE_CREDENTIAL` — PIN/password only
+
+**Biometric Policies**:
+- `BiometricPolicy.Never` — Never require biometric for retrieval
+- `BiometricPolicy.Always` — Always require biometric
+- `BiometricPolicy.Session(seconds)` — Require biometric every N seconds
+- `BiometricPolicy.AppLifecycle` — Require biometric on app resume
+
+## Database Login
+
+Authenticate using username and password (requires `.validateClaims()`):
+
+```kotlin
+import com.auth0.android.authentication.AuthenticationAPIClient
+import com.auth0.android.callback.Callback
+import com.auth0.android.authentication.AuthenticationException
+import com.auth0.android.result.Credentials
+
+val authentication = AuthenticationAPIClient(account)
+
+authentication.login(
+    email = "user@example.com",
+    password = "securePassword123",
+    realm = "Username-Password-Authentication"
+)
+    .validateClaims()  // Critical: validate ID token claims
+    .setScope("openid profile email offline_access")
+    .start(object : Callback<Credentials, AuthenticationException> {
+        override fun onSuccess(result: Credentials) {
+            // User authenticated
+            manager.saveCredentials(result)
+        }
+
+        override fun onFailure(error: AuthenticationException) {
+            when {
+                error.isMultifactorRequired -> {
+                    // MFA required - see MFA Handling section
+                }
+                error.statusCode == 403 -> {
+                    // Invalid credentials
+                }
+                else -> Log.e("Auth0", error.message.orEmpty())
+            }
+        }
+    })
+```
+
+**Important**: Always call `.validateClaims()` when using `AuthenticationAPIClient` directly.
+
+## Passwordless Authentication
+
+Two-step passwordless flow using email codes:
+
+### Step 1: Request Passwordless Code
+
+```kotlin
+import com.auth0.android.authentication.AuthenticationAPIClient
+import com.auth0.android.authentication.PasswordlessType
+import com.auth0.android.callback.Callback
+import com.auth0.android.authentication.AuthenticationException
+
+val authentication = AuthenticationAPIClient(account)
+
+authentication.passwordlessWithEmail(
+    email = "user@example.com",
+    type = PasswordlessType.CODE
+)
+    .start(object : Callback<Void?, AuthenticationException> {
+        override fun onSuccess(result: Void?) {
+            // Code sent to email - show user a screen to enter code
+        }
+
+        override fun onFailure(error: AuthenticationException) {
+            Log.e("Auth0", error.message.orEmpty())
+        }
+    })
+```
+
+### Step 2: Log In with Code
+
+```kotlin
+authentication.loginWithEmail(
+    email = "user@example.com",
+    code = "123456"  // Code from email
+)
+    .validateClaims()
+    .start(object : Callback<Credentials, AuthenticationException> {
+        override fun onSuccess(result: Credentials) {
+            // User authenticated
+            manager.saveCredentials(result)
+        }
+
+        override fun onFailure(error: AuthenticationException) {
+            // Invalid or expired code
+            Log.e("Auth0", error.message.orEmpty())
+        }
+    })
+```
+
+## Sign Up
+
+Create a new account using the database connection:
+
+```kotlin
+val authentication = AuthenticationAPIClient(account)
+
+authentication.signUp(
+    email = "newuser@example.com",
+    password = "securePassword123",
+    username = "newuser",
+    connection = "Username-Password-Authentication"
+)
+    .start(object : Callback<Void?, AuthenticationException> {
+        override fun onSuccess(result: Void?) {
+            // Account created successfully - user should now log in
+        }
+
+        override fun onFailure(error: AuthenticationException) {
+            when {
+                error.statusCode == 400 -> {
+                    // User already exists or validation error
+                }
+                else -> Log.e("Auth0", error.message.orEmpty())
+            }
+        }
+    })
+```
+
+After successful sign up, direct the user to log in using the database login flow.
+
+## Calling Protected APIs
+
+Attach the access token to your API requests:
+
+```kotlin
+import com.auth0.android.authentication.AuthenticationAPIClient
+import com.auth0.android.authentication.storage.CredentialsManagerException
+import com.auth0.android.authentication.storage.SecureCredentialsManager
+import com.auth0.android.authentication.storage.SharedPreferencesStorage
+import com.auth0.android.callback.Callback
+import com.auth0.android.result.Credentials
+import okhttp3.OkHttpClient
+import okhttp3.Interceptor
+
+val authentication = AuthenticationAPIClient(account)
+val storage = SharedPreferencesStorage(context)
+val manager = SecureCredentialsManager(context, authentication, storage)
+
+manager.getCredentials(object : Callback<Credentials, CredentialsManagerException> {
+    override fun onSuccess(result: Credentials) {
+        val accessToken = result.accessToken
+
+        // Use with OkHttp
+        val httpClient = OkHttpClient.Builder()
+            .addInterceptor(Interceptor { chain ->
+                val request = chain.request().newBuilder()
+                    .header("Authorization", "Bearer $accessToken")
+                    .build()
+                chain.proceed(request)
+            })
+            .build()
+
+        // Or manually for other HTTP libraries
+        val headers = mapOf("Authorization" to "Bearer $accessToken")
+        // Use headers in your API request
+    }
+
+    override fun onFailure(error: CredentialsManagerException) {
+        // Handle error - may need to re-authenticate
+    }
+})
+```
+
+If the API returns 401 Unauthorized, refresh the credentials and retry:
+
+```kotlin
+manager.getCredentials(object : Callback<Credentials, CredentialsManagerException> {
+    override fun onSuccess(result: Credentials) {
+        // Credentials were auto-refreshed by the manager
+        val newAccessToken = result.accessToken
+        retryApiCall(newAccessToken)
+    }
+
+    override fun onFailure(error: CredentialsManagerException) {
+        if (error.code == "REFRESH_FAILED") {
+            // Refresh token expired - trigger login again
+        }
+    }
+})
+```
+
+## MFA Handling
+
+Handle multi-factor authentication challenges:
+
+### Detect MFA Required
+
+```kotlin
+authentication.login(...)
+    .validateClaims()
+    .start(object : Callback<Credentials, AuthenticationException> {
+        override fun onFailure(error: AuthenticationException) {
+            if (error.isMultifactorRequired) {
+                val mfaToken = error.mfaRequiredErrorPayload?.mfaToken
+                // Proceed to enrollment or challenge screen
+            }
+        }
+    })
+```
+
+### Enroll in MFA
+
+```kotlin
+val mfaToken = error.mfaRequiredErrorPayload?.mfaToken ?: return
+val mfaClient = authentication.mfaClient(mfaToken)
+
+// Enroll in OTP
+mfaClient.enroll(MfaEnrollmentType.Otp)
+    .start(object : Callback<MfaEnrollment, AuthenticationException> {
+        override fun onSuccess(enrollment: MfaEnrollment) {
+            val recoveryCode = enrollment.recoveryCode
+            val secret = enrollment.secret  // For OTP app
+            // Show QR code to user
+        }
+
+        override fun onFailure(error: AuthenticationException) {
+            Log.e("MFA", error.message.orEmpty())
+        }
+    })
+```
+
+### Challenge MFA
+
+```kotlin
+mfaClient.challenge(
+    authenticatorId = "dev_abc123",  // From enrollments list
+    challengeType = MfaChallengeType.OTP
+)
+    .start(object : Callback<MfaChallenge, AuthenticationException> {
+        override fun onSuccess(challenge: MfaChallenge) {
+            val challengeId = challenge.challengeId
+            // Show user OTP input screen
+        }
+
+        override fun onFailure(error: AuthenticationException) {
+            Log.e("MFA", error.message.orEmpty())
+        }
+    })
+```
+
+### Verify Challenge
+
+```kotlin
+mfaClient.verifyChallenge(
+    challengeId = "Fe26...session_id",
+    otp = "123456"  // User's one-time password
+)
+    .validateClaims()
+    .start(object : Callback<Credentials, AuthenticationException> {
+        override fun onSuccess(result: Credentials) {
+            // MFA verified - user now authenticated
+            manager.saveCredentials(result)
+        }
+
+        override fun onFailure(error: AuthenticationException) {
+            // Invalid OTP or expired challenge
+            Log.e("MFA", error.message.orEmpty())
+        }
+    })
+```
+
+## Organizations
+
+Use Organizations for enterprise SSO and multi-tenancy:
+
+```kotlin
+// Log in with organization
+WebAuthProvider.login(account)
+    .withScheme(getString(R.string.com_auth0_scheme))
+    .withOrganization("org_abc123")  // Organization ID
+    .withScope("openid profile email")
+    .start(this, object : Callback<Credentials, AuthenticationException> {
+        override fun onSuccess(result: Credentials) {
+            // User authenticated to organization
+            val orgId = result.claims["org_id"]
+        }
+
+        override fun onFailure(error: AuthenticationException) {
+            // Handle error
+        }
+    })
+
+// Handle organization invitation link
+val uri = intent.data  // From deep link
+val organizationId = uri?.getQueryParameter("organization")
+val invitation = uri?.getQueryParameter("invitation")
+
+if (invitation != null) {
+    WebAuthProvider.login(account)
+        .withScheme(getString(R.string.com_auth0_scheme))
+        .withInvitation(invitation)
+        .start(this, callback)
+}
+```
+
+## Error Handling
+
+Handle authentication errors gracefully:
+
+```kotlin
+authentication.login(...)
+    .start(object : Callback<Credentials, AuthenticationException> {
+        override fun onFailure(error: AuthenticationException) {
+            when {
+                error.isMultifactorRequired -> {
+                    // MFA enrollment or challenge required
+                }
+                error.isBrowserAppNotAvailable -> {
+                    // No browser available
+                    // Fallback to in-app WebView (not recommended)
+                }
+                error.isAuthenticationCanceled -> {
+                    // User canceled the login flow
+                }
+                error.statusCode == 429 -> {
+                    // Rate limited - too many login attempts
+                }
+                error.statusCode == 403 -> {
+                    // Invalid credentials or user blocked
+                }
+                error.statusCode == 500 -> {
+                    // Server error - retry later
+                }
+                else -> {
+                    // Generic error
+                    Log.e("Auth0", "Error: ${error.message}")
+                }
+            }
+        }
+    })
+```
+
+**CredentialsManagerException codes**:
+- `NO_CREDENTIALS` — No credentials stored
+- `CREDENTIALS_EXPIRED` — Stored credentials expired
+- `REFRESH_FAILED` — Refresh token expired or invalid
+- `INVALID_SECURITY` — Biometric authentication failed
+
+## Custom Tabs
+
+Customize the browser appearance:
+
+```kotlin
+import com.auth0.android.provider.CustomTabsOptions
+import com.auth0.android.provider.WebAuthProvider
+
+val customTabs = CustomTabsOptions.newBuilder()
+    .withToolbarColor(R.color.toolbar_blue)
+    .withShowTitle(true)
+    .build()
+
+WebAuthProvider.login(account)
+    .withScheme(getString(R.string.com_auth0_scheme))
+    .withCustomTabsOptions(customTabs)
+    .start(this, callback)
+```
+
+**Options**:
+- `.withToolbarColor()` — Toolbar color resource
+- `.withShowTitle()` — Show the page title
+- `.withStartAnimations()` — Entrance animation
+- `.withExitAnimations()` — Exit animation
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Deep link callback not working | Verify callback URL matches exactly: `https://{DOMAIN}/android/{PACKAGE}/callback`. Check manifest placeholders in `build.gradle`. |
+| "Invalid state" error on callback | The auth session timed out or was invalidated. This can happen if the device went to sleep. Redirect user to login again. |
+| Custom Tabs not opening | User may have disabled Custom Tabs. The SDK falls back to Chrome or system browser. If no browser available, `isBrowserAppNotAvailable` is true. |
+| Biometric prompt not showing | Min SDK must be 21+ for biometric. Device must have fingerprint/face sensor registered. `setDeviceCredentialFallback(true)` allows PIN/password. |
+| Token refresh fails | Refresh token may have expired (typically after 30 days). Trigger re-authentication with `WebAuthProvider.login()`. |
+| ProGuard obfuscation breaks Auth0 | Auth0 rules are included automatically. If issues occur, add `-keep class com.auth0.** { *; }` to your `proguard-rules.pro`. |
+
+---
+
+# Auth0 Android Setup Guide
+
+> **Agent instruction:** Before providing version numbers, fetch the latest release:
+> `gh api repos/auth0/Auth0.Android/releases/latest --jq '.tag_name'`
+> Replace `{LATEST_VERSION}` in all dependency lines with the result.
+
+## Setup Overview
+
+1. Add SDK dependency to `build.gradle`
+2. Configure Auth0 (automatic inline script or manual credentials)
+3. Add manifest placeholders and INTERNET permission (post-setup)
+
+## Auth0 Configuration
+
+> **Agent instruction:** First, check whether the user prompt already includes both Auth0 **Client ID** and **Domain**.
+> - If both are provided, skip the setup-choice question and proceed directly to **Manual Setup (User-Provided Credentials)** using those values.
+> - If either value is missing, ask the user:
+>   - Question: "How would you like to configure Auth0 for this project?"
+>   - Options: "Automatic setup (Recommended) — Auth0 CLI creates the app and writes credentials to strings.xml" / "Manual setup — I'll provide my Client ID and Domain"
+>
+> Follow the matching section below based on their choice.
+
+### Automatic Setup
+
+Below automates the setup. Inform the user that Auth0 credentials will be written to `strings.xml`.
+
+**Before running any part of this setup that writes to `strings.xml`, you must ask the user for explicit confirmation.** Follow the steps below precisely.
+
+#### Step 1: Check for existing strings.xml and confirm with user
+
+Before writing credentials, check whether a `strings.xml` already exists:
+
+```bash
+test -f app/src/main/res/values/strings.xml && echo "STRINGS_EXISTS" || echo "STRINGS_NOT_FOUND"
+```
+
+Then ask the user for explicit confirmation before proceeding — do not continue until the user confirms:
+
+- If `strings.xml` exists, ask:
+  - Question: "A `strings.xml` file already exists. This setup will add or update the Auth0 credential entries (`com_auth0_client_id`, `com_auth0_domain`, `com_auth0_scheme`) without modifying other entries. Do you want to proceed?"
+  - Options: "Yes, update existing strings.xml" / "No, I'll update it manually"
+
+- If `strings.xml` does **not** exist, ask:
+  - Question: "This setup will create `app/src/main/res/values/strings.xml` with Auth0 credentials (`com_auth0_client_id`, `com_auth0_domain`, `com_auth0_scheme`). Do you want to proceed?"
+  - Options: "Yes, create strings.xml" / "No, I'll configure it manually"
+
+**Do not proceed with writing to strings.xml unless the user selects the confirmation option.**
+
+#### Step 2: Run automated setup (only after confirmation)
+
+```bash
+#!/bin/bash
+
+PROJECT_PATH="${1:-$PWD}"
+SCHEME="demo"
+
+# Install Auth0 CLI
+if ! command -v auth0 &> /dev/null; then
+  [[ "$OSTYPE" == "darwin"* ]] && brew install auth0/auth0-cli/auth0 || \
+  curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b /usr/local/bin
+fi
+
+# Login
+auth0 login 2>/dev/null || auth0 login
+
+# Find build.gradle / build.gradle.kts
+if [ -f "$PROJECT_PATH/app/build.gradle" ]; then
+  GRADLE_FILE="$PROJECT_PATH/app/build.gradle"
+elif [ -f "$PROJECT_PATH/app/build.gradle.kts" ]; then
+  GRADLE_FILE="$PROJECT_PATH/app/build.gradle.kts"
+else
+  echo "❌ No app/build.gradle or app/build.gradle.kts found in $PROJECT_PATH"
+  exit 1
+fi
+
+# Extract applicationId
+PACKAGE_NAME=$(grep -E 'applicationId\s*=?\s*"[^"]*"' "$GRADLE_FILE" | grep -oE '"[^"]*"' | tr -d '"' | head -1)
+if [ -z "$PACKAGE_NAME" ]; then
+  echo "❌ Could not find applicationId in $GRADLE_FILE"
+  exit 1
+fi
+
+# List existing apps and prompt to pick or create
+auth0 apps list
+read -p "Enter app ID (or press Enter to create a new one): " APP_ID
+
+if [ -z "$APP_ID" ]; then
+  DOMAIN=$(auth0 tenants list --csv --no-input 2>/dev/null | grep '→' | cut -d',' -f2 | tr -d ' ')
+  CALLBACK_URL="${SCHEME}://${DOMAIN}/android/${PACKAGE_NAME}/callback"
+  CLIENT_JSON=$(auth0 apps create \
+    --name "${PACKAGE_NAME}-android" \
+    --type native \
+    --auth-method none \
+    --callbacks "$CALLBACK_URL" \
+    --logout-urls "$CALLBACK_URL" \
+    --json \
+    --no-input)
+  CLIENT_ID=$(echo "$CLIENT_JSON" | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+else
+  CLIENT_ID=$(auth0 apps show "$APP_ID" --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+  DOMAIN=$(auth0 apps show "$APP_ID" --json | grep -o '"domain":"[^"]*' | cut -d'"' -f4)
+  CALLBACK_URL="${SCHEME}://${DOMAIN}/android/${PACKAGE_NAME}/callback"
+fi
+
+# Check / create database connection
+CONNECTIONS_JSON=$(auth0 api get connections --no-input 2>/dev/null || echo "[]")
+CONNECTION_ID=$(echo "$CONNECTIONS_JSON" | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+for c in data:
+    if c.get('name') == 'Username-Password-Authentication':
+        print(c['id'])
+        break
+" 2>/dev/null)
+ENABLED_CLIENTS=$(echo "$CONNECTIONS_JSON" | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+for c in data:
+    if c.get('name') == 'Username-Password-Authentication':
+        print(json.dumps(c.get('enabled_clients', [])))
+        break
+" 2>/dev/null)
+
+if [ -z "$CONNECTION_ID" ]; then
+  auth0 api post connections \
+    --data "{\"strategy\":\"auth0\",\"name\":\"Username-Password-Authentication\",\"enabled_clients\":[\"$CLIENT_ID\"]}" \
+    --no-input > /dev/null
+else
+  UPDATED_CLIENTS=$(echo "$ENABLED_CLIENTS" | python3 -c "
+import sys, json
+clients = json.load(sys.stdin)
+if '$CLIENT_ID' not in clients:
+    clients.append('$CLIENT_ID')
+print(json.dumps(clients))
+")
+  auth0 api patch "connections/$CONNECTION_ID" \
+    --data "{\"enabled_clients\":$UPDATED_CLIENTS}" \
+    --no-input > /dev/null
+fi
+
+# Write / update strings.xml
+STRINGS_FILE="$PROJECT_PATH/app/src/main/res/values/strings.xml"
+mkdir -p "$(dirname "$STRINGS_FILE")"
+
+python3 << PYEOF
+import re, os
+
+path = "$STRINGS_FILE"
+entries = {
+    'com_auth0_client_id': '$CLIENT_ID',
+    'com_auth0_domain': '$DOMAIN',
+    'com_auth0_scheme': '$SCHEME',
+}
+
+content = open(path).read() if os.path.exists(path) else ''
+
+if '<resources' in content:
+    for key, value in entries.items():
+        pattern = re.compile(r'<string\s+name="' + re.escape(key) + r'"[^>]*>[\s\S]*?</string>')
+        replacement = f'<string name="{key}">{value}</string>'
+        if pattern.search(content):
+            content = pattern.sub(replacement, content)
+        else:
+            content = content.replace('</resources>', f'    <string name="{key}">{value}</string>\n</resources>')
+else:
+    lines = ['    <string name="app_name">My App</string>']
+    lines += [f'    <string name="{k}">{v}</string>' for k, v in entries.items()]
+    content = '<?xml version="1.0" encoding="utf-8"?>\n<resources>\n' + '\n'.join(lines) + '\n</resources>\n'
+
+with open(path, 'w') as f:
+    f.write(content)
+PYEOF
+
+echo "✅ Auth0 credentials written to $STRINGS_FILE"
+echo "   Domain:       $DOMAIN"
+echo "   Client ID:    $CLIENT_ID"
+echo "   Package:      $PACKAGE_NAME"
+echo "   Callback URL: $CALLBACK_URL"
+```
+
+After the script runs, proceed to **Post-Setup Steps** below.
+
+### Manual Setup (User-Provided Credentials)
+
+> **Agent instruction:** Ask the user for their Auth0 **Client ID** and **Domain**. Then update `strings.xml` with the values they provide:
+> ```xml
+> <string name="com_auth0_client_id">USER_PROVIDED_CLIENT_ID</string>
+> <string name="com_auth0_domain">USER_PROVIDED_DOMAIN</string>
+> <string name="com_auth0_scheme">demo</string>
+> ```
+> Remind the user to configure callback URLs in the Auth0 Dashboard:
+> `demo://{DOMAIN}/android/{APPLICATION_ID}/callback`
+> (add to both **Allowed Callback URLs** and **Allowed Logout URLs**).
+>
+> After updating strings.xml, proceed to **Post-Setup Steps** below.
+
+### Post-Setup Steps (Required for Both Paths)
+
+> **Agent instruction:** After either automatic or manual Auth0 configuration, the agent must apply the following changes to the project:
+>
+> 1. **Add manifest placeholders** to `app/build.gradle` (or `app/build.gradle.kts`) inside the `defaultConfig` block, if not already present:
+>    - Groovy (`build.gradle`):
+>      ```gradle
+>      manifestPlaceholders = [
+>          auth0Domain: "@string/com_auth0_domain",
+>          auth0Scheme: "@string/com_auth0_scheme"
+>      ]
+>      ```
+>    - Kotlin DSL (`build.gradle.kts`):
+>      ```kotlin
+>      manifestPlaceholders += mapOf(
+>          "auth0Domain" to "@string/com_auth0_domain",
+>          "auth0Scheme" to "@string/com_auth0_scheme"
+>      )
+>      ```
+>
+> 2. **Add INTERNET permission** to `AndroidManifest.xml` if not already present:
+>    ```xml
+>    <uses-permission android:name="android.permission.INTERNET" />
+>    ```
+>
+> 3. **Build the project** to confirm everything compiles:
+>    ```bash
+>    ./gradlew assembleDebug
+>    ```
+
+## SDK Installation
+
+Add the dependency to your module's `build.gradle`:
+
+```gradle
+dependencies {
+    implementation 'com.auth0.android:auth0:{LATEST_VERSION}'
+}
+```
+
+Ensure Java 8 compatibility in your `build.gradle`:
+
+```gradle
+android {
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+
+    kotlinOptions {
+        jvmTarget = '1.8'
+    }
+}
+```
+
+## Android App Links (Recommended for Production)
+
+> **Note:** The automatic setup script and manual setup default to a custom scheme (`demo://`) for simplicity. App Links with `https://` are recommended for production apps. To switch, update `com_auth0_scheme` to `https` in `strings.xml` and update your callback URL in the Auth0 Dashboard to `https://YOUR_AUTH0_DOMAIN/android/YOUR_APP_PACKAGE_NAME/callback`.
+
+For the `https://` scheme, Android uses App Links for deeper integration:
+
+1. **Digital Asset Links**: Create a `assetlinks.json` file on your Auth0 domain
+   - Auth0 manages this automatically for you
+   - Enables deep link routing without user prompts
+
+2. **Auto-Verify**: Add to `build.gradle`:
+   ```gradle
+   android {
+       defaultConfig {
+           // The android:autoVerify attribute is added automatically for https schemes
+       }
+   }
+   ```
+
+The SDK automatically uses App Links when `com_auth0_scheme` is set to `https` in `strings.xml`.
+
+## Custom Scheme (Alternative)
+
+If you need a custom scheme instead of `https://`:
+
+1. Update `strings.xml` with your custom scheme:
+   ```xml
+   <string name="com_auth0_scheme">myapp</string>
+   ```
+
+   The manifest placeholder already references this via `@string/com_auth0_scheme`.
+
+2. Update callback URL in Auth0 Dashboard:
+   ```
+   myapp://YOUR_AUTH0_DOMAIN/android/YOUR_APP_PACKAGE_NAME/callback
+   ```
+
+3. In your code when logging out, use the same scheme:
+   ```kotlin
+   WebAuthProvider.logout(account)
+       .withScheme(getString(R.string.com_auth0_scheme))
+       .start(this, callback)
+   ```
+
+**Important**: Android requires scheme names to be lowercase.
+
+## ProGuard/R8
+
+The Auth0 Android SDK includes ProGuard/R8 rules automatically. You don't need to add any manual configuration. The library's `proguard-rules.pro` is included in the AAR file and will be merged into your app's build.
+
+If you encounter obfuscation issues:
+
+1. Disable obfuscation for Auth0 classes (in `proguard-rules.pro`):
+   ```
+   -keep class com.auth0.** { *; }
+   ```
+
+2. Or rebuild with debugging enabled temporarily:
+   ```gradle
+   buildTypes {
+       debug {
+           debuggable true
+           minifyEnabled false
+       }
+   }
+   ```
+
+---
+
+
+---
+
+## Major Version Migration
+
+
+# Auth0.Android v4 Migration
+
+Migrates an existing Auth0.Android (`com.auth0.android:auth0`) v3 integration to v4. Every code change is gated on a search that confirms the project actually calls the affected API — if the project never uses `SecureCredentialsManager`, no `SecureCredentialsManager` code is touched. Changes follow the project's existing architecture (Kotlin or Java, callback or coroutine) and Android conventions.
+
+## Target version is argument-based
+
+This skill accepts an optional target version argument:
+
+- **`/auth0-android-major-migration 4.0.0`** — migrate to the exact tag `4.0.0` (validated before use).
+- **`/auth0-android-major-migration`** (no argument) — auto-resolve the **latest release within the next major (v4.x)**, including pre-releases.
+
+`$ARGUMENTS`, when present, is the requested target tag. Step 2 validates it and resolves the final `<TARGET_TAG>` used for the rest of the migration.
+
+## When NOT to Use
+
+- **New Auth0 integration** (no existing Auth0.Android SDK): Use the Auth0 Android integration workflow (above)
+- **Minor/patch update** (e.g., 3.18 → 3.19): Bump the `com.auth0.android:auth0` version in Gradle — no migration needed
+- **iOS / macOS apps**: Use the Auth0 Swift major-version migration
+- **React Native / Expo**: Use the Auth0 React Native or Expo integration
+- **Flutter**: Use the native Flutter Auth0 SDK
+
+## Prerequisites
+
+- Existing Auth0.Android v3 integration (`com.auth0.android:auth0:3.x`)
+- Android SDK / Gradle toolchain installed; project builds cleanly on the current version
+- Project under git version control with a clean working tree
+
+---
+
+## Migration Workflow
+
+> **Agent instruction:** Execute every step in order. The goal is a green build with the smallest correct changeset. Each code-change step is gated by the Step 5 file-reading audit — if the API was not found in the project's source files, skip the entire step for that area. Never add code the project doesn't already call. v4 also raises platform requirements (Step 3) that can **block** the migration until satisfied — handle those before touching any Auth0 API call site.
+
+---
+
+### Step 1 — Pre-flight & Safety Backup
+
+```bash
+# 1a. Verify clean working tree — stop if there are uncommitted changes
+git status --porcelain
+```
+
+If the output is non-empty, ask the user:
+> *"You have uncommitted changes. Should I stash them before proceeding (`git stash`), or would you like to commit first?"*
+
+```bash
+# 1b. Create a safety branch the user can reset to at any time
+git checkout -b auth0-v4-migration-backup
+git checkout -
+```
+
+```bash
+# 1c. Confirm the project builds on the current version before touching anything
+./gradlew assembleDebug 2>&1 | tail -15
+```
+
+If the build fails, stop. Ask the user to fix the existing issues first — do not migrate a project that does not build.
+
+---
+
+### Step 2 — Detect Current & Resolve Target Version
+
+**Detect the current Auth0.Android version** (check each location that applies):
+
+```bash
+# Inline dependency in a module build file (Groovy or Kotlin DSL)
+grep -rEn "com\.auth0\.android:auth0:[0-9]" --include=build.gradle --include=build.gradle.kts .
+
+# Gradle version catalog
+grep -rEn "auth0" --include=libs.versions.toml .
+
+# Resolved lockfile (most reliable if present)
+grep -rEn "com\.auth0\.android:auth0:[0-9]" --include=gradle.lockfile .
+```
+
+**Resolve the target version.** There are two paths:
+
+**Path A — the user passed a target version argument (`$ARGUMENTS`):**
+
+Validate it against the published releases before using it. It must pass **all three** checks:
+
+```bash
+# List all published Auth0.Android release tags
+gh api repos/auth0/Auth0.Android/releases --paginate \
+  --jq '.[] | select(.draft==false) | .tag_name'
+```
+
+1. **Exists** — the requested tag appears in the published release list above.
+2. **Next major** — the tag is within the **v4** major line (`tag_name` starts with `4`). A `3.x` or lower tag is *not* the next major; reject it.
+3. **Not a downgrade** — the tag is newer than the version detected in the project.
+
+> **On any check failing, STOP and ask the user.** Do not silently fall back. For example:
+> - *"`4.9.9` isn't a published Auth0.Android release. Published v4 releases are: `4.0.0-beta.1`, … . Please pass a valid v4 tag, or omit the argument to auto-resolve the latest v4 release."*
+> - *"`3.19.0` is a v3 release, not the next major. This skill migrates to v4. Pass a v4 tag (e.g. `4.0.0`) or omit the argument."*
+> - *"`4.0.0-beta.0` is older than the `4.0.0-beta.1` already in your project — that's a downgrade. Pass a newer v4 tag or omit the argument."*
+
+**Path B — no argument: auto-resolve the latest v4 release (including pre-releases):**
+
+```bash
+# Newest v4.x release tag (stable or pre-release), most recent first
+gh api repos/auth0/Auth0.Android/releases --paginate \
+  --jq '[.[] | select(.draft==false) | select(.tag_name|startswith("4"))] | .[0].tag_name'
+```
+
+Record the result as `<TARGET_TAG>` and use it in every subsequent step.
+
+> **If `<TARGET_TAG>` is a pre-release** (contains `-beta`, `-rc`, etc.), tell the user before continuing:
+> *"v4 is not yet generally available — the latest v4 release is `<TARGET_TAG>` (a pre-release). I'll migrate to that. You can pin a different tag by passing it as an argument."*
+>
+> **If no v4 release exists yet** (the resolver returns empty), stop and tell the user there is no published v4 release to migrate to.
+
+---
+
+### Step 3 — Prerequisite Gate (Requirements Changes)
+
+v4 raises the build toolchain and platform floor. Check each requirement **before** migrating any API. If a requirement is unmet, prompt the user and apply the build-file change (or block until they confirm) — a project that doesn't meet these will not build against v4 regardless of API changes.
+
+> Confirm the exact required versions for `<TARGET_TAG>` from the SDK's own `build.gradle` / `gradle-wrapper.properties` fetched in Step 4 if they differ from the values below (these reflect the v4 baseline).
+
+| Requirement | v3 | v4 | Where to check / change |
+|---|---|---|---|
+| **minSdk** | 21 | **26** (Android 8.0) | `android { defaultConfig { minSdk } }` |
+| **Java** | 8+ | **17** | `compileOptions { sourceCompatibility/targetCompatibility }`, `kotlinOptions { jvmTarget }` |
+| **Gradle** | — | **8.11.1+** | `gradle/wrapper/gradle-wrapper.properties` (`distributionUrl`) |
+| **AGP** | — | **8.10.1+** | root `build.gradle` `com.android.tools.build:gradle` classpath / `plugins` block |
+| **Kotlin** | — | **2.0.21** | `ext.kotlin_version` / version catalog (only if the project uses Kotlin) |
+
+```bash
+# Inspect current values
+grep -rEn "minSdk(Version)?\s*[ =]" --include=build.gradle --include=build.gradle.kts .
+grep -rEn "sourceCompatibility|targetCompatibility|jvmTarget" --include=build.gradle --include=build.gradle.kts .
+grep -En "distributionUrl" gradle/wrapper/gradle-wrapper.properties
+grep -rEn "com\.android\.tools\.build:gradle|kotlin_version|kotlin(\"|-)" --include=build.gradle --include=build.gradle.kts --include=libs.versions.toml .
+```
+
+**`minSdk` below 26 is a hard block.** If the project targets API 25 or lower, tell the user this raises the minimum supported Android version (devices on Android 7.1 and below will no longer be supported) and ask them to confirm before bumping `minSdk` to 26 — or to stay on v3.
+
+Apply the required bumps (example shapes — match the project's DSL):
+
+```groovy
+android {
+    defaultConfig { minSdk 26 }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+    kotlinOptions { jvmTarget = '17' }
+}
+```
+
+See the Migration Process section below for Kotlin DSL, version-catalog, and Gradle/AGP wrapper edge cases.
+
+---
+
+### Step 4 — Fetch & Read the v4 SDK Source
+
+Fetch the actual Kotlin source for `<TARGET_TAG>`. The signatures here are the authoritative reference for every change made in Step 7. **Do not migrate from memory or from the guide alone — confirm each signature in the fetched source.**
+
+```bash
+TAG=<TARGET_TAG>   # the version resolved in Step 2, e.g. 4.0.0-beta.1
+BASE="https://raw.githubusercontent.com/auth0/Auth0.Android/${TAG}/auth0/src/main/java/com/auth0/android"
+
+# List all public Kotlin files in the SDK (confirm paths for this tag)
+gh api "repos/auth0/Auth0.Android/git/trees/${TAG}?recursive=1" \
+  --jq '.tree[].path | select(startswith("auth0/src/main/") and endswith(".kt"))'
+
+# Fetch the files that back the breaking changes
+for FILE in \
+  provider/WebAuthProvider.kt \
+  authentication/AuthenticationAPIClient.kt \
+  authentication/mfa/MfaApiClient.kt \
+  authentication/storage/SecureCredentialsManager.kt \
+  authentication/storage/CredentialsManager.kt \
+  authentication/storage/BaseCredentialsManager.kt \
+  authentication/storage/Storage.kt \
+  dpop/DPoPException.kt \
+  result/SSOCredentials.kt \
+  request/DefaultClient.kt ; do
+    CONTENT=$(curl -sf "${BASE}/${FILE}")
+    [ -n "$CONTENT" ] && echo "=== ${FILE} ===" && echo "$CONTENT"
+done
+```
+
+> **If a release tag has no source yet** (e.g. during the v4 development phase, before the first tag carries the full tree), fall back to the `v4_development` branch for signature confirmation: replace `${TAG}` with `v4_development` in the URLs above. Always prefer the chosen tag when it has source.
+
+Read the fetched source and note, for each file:
+- Public method signatures that changed (parameters, return type, `@Throws`)
+- Constructors that were removed
+- Types/classes that were removed or renamed
+- Default parameter values that changed (e.g. `minTtl`)
+
+This is the ground truth. Every change in Step 7 must match a real signature in these files.
+
+---
+
+### Step 5 — Audit Which Auth0 APIs the Project Uses
+
+**Find all source files that import the Auth0 SDK — these are the scope of the migration:**
+
+```bash
+grep -rlE "import com\.auth0\.android" --include="*.kt" --include="*.java" .
+```
+
+**Read every file from that list.** Do not grep for individual API patterns and stop there — read the full source so you can see exactly how `Auth0`, `WebAuthProvider`, `AuthenticationAPIClient`, `SecureCredentialsManager`/`CredentialsManager`, and any Auth0 types are used, including multi-line builder chains and any custom `Storage` conformances.
+
+For each file, identify:
+
+| What to look for | Section |
+|---|---|
+| `PasskeyAuthProvider` usage | §7.1 — class removed |
+| `UsersAPIClient`, `ManagementException`, `ManagementCallback` | §7.2 — Management API removed |
+| `loginWithOTP(`, `loginWithOOB(`, `loginWithRecoveryCode(`, `multifactorChallenge(` on `AuthenticationAPIClient` | §7.3 — deprecated MFA methods removed |
+| `WebAuthProvider.useDPoP(` called on the object *before* `.login(` | §7.4 — `useDPoP` moved to the login builder |
+| `DPoPException.UNSUPPORTED_ERROR` | §7.5 — constant removed |
+| `.expiresIn` accessed on an `SSOCredentials` value | §7.6 — renamed to `expiresAt` (now a `Date`) |
+| `SecureCredentialsManager(` with an `Auth0` instance as the first argument | §7.7 — `Auth0`-based constructors removed |
+| `getCredentials(` / `awaitCredentials(` without an explicit `minTtl`, or `hasValidCredentials()` | §9.1 — default `minTtl` 0 → 60s (behavioral) |
+| `clearCredentials(` | §9.3 — now clears **all** storage |
+| A class implementing the `Storage` interface | §9.4 — new `removeAll()` (default impl provided) |
+
+Build a checklist: **"This project uses: [list]"** and **"This project does NOT use: [list]"**. Only work through the §7.x / §9.x sections that appear in the "uses" list. Skip the rest entirely.
+
+---
+
+### Step 6 — Update the SDK Dependency
+
+Apply the matching declaration style. Use `<TARGET_TAG>` from Step 2.
+
+**Inline — Groovy DSL (`build.gradle`):**
+
+```groovy
+implementation 'com.auth0.android:auth0:<TARGET_TAG>'
+```
+
+**Inline — Kotlin DSL (`build.gradle.kts`):**
+
+```kotlin
+implementation("com.auth0.android:auth0:<TARGET_TAG>")
+```
+
+**Version catalog (`gradle/libs.versions.toml`):**
+
+```toml
+[versions]
+auth0 = "<TARGET_TAG>"
+```
+
+> **Pre-release tags** (e.g. `4.0.0-beta.1`) must be pinned **exactly** — do not use a dynamic range like `4.+` or `[4.0,5.0)`, which Gradle may resolve to a different artifact. For stable v4 releases an exact version is still recommended for reproducibility.
+
+Do **not** build yet — apply all known code changes first (Step 7), then build (Step 8) to surface any remainders.
+
+---
+
+### Step 7 — Apply Breaking Changes
+
+> **Agent instruction:** Work through only the §7.x sections that matched during the Step 5 audit. Skip every section whose API the project does not use — do not touch those files. Apply each change exactly as shown, confirmed against the source fetched in Step 4. Do not rename variables, reformat, or modernise code that isn't being migrated. Match the project's existing style: callback → callback, coroutine `await` → coroutine `await`, Kotlin → Kotlin, Java → Java.
+
+---
+
+#### 7.1 — `PasskeyAuthProvider` removed
+
+**Applies if:** Step 5 found `PasskeyAuthProvider` in the project's source files.
+
+The `com.auth0.android.provider.PasskeyAuthProvider` class was removed. Passkey operations now live on `AuthenticationAPIClient`: `passkeyChallenge()`, `signupWithPasskey()`, and `signinWithPasskey()`. Confirm the exact signatures in the `AuthenticationAPIClient.kt` fetched in Step 4, then migrate each call site to the corresponding client method. If a passkey flow cannot be migrated confidently from the source, add a `// TODO:` and list it in the Step 10 summary rather than guessing.
+
+---
+
+#### 7.2 — Management API removed (`UsersAPIClient`)
+
+**Applies if:** Step 5 found `UsersAPIClient`, `ManagementException`, or `ManagementCallback` in the project's source files.
+
+The entire Management API client was removed from the SDK in v4. Calling the Management API directly from a mobile app was never recommended — it requires a privileged token on the device. **Do not silently delete the call sites.** Add a `// TODO:` that preserves the intent and surface this in the Step 10 summary as required backend work.
+
+```kotlin
+// v3 — direct Management API call from the app (e.g. updating user_metadata)
+val users = UsersAPIClient(account, accessToken)
+users.updateMetadata(userId, metadata)
+    .start(object : Callback<UserProfile, ManagementException> { /* ... */ })
+
+// v4 — Management client removed; preserve intent, move to a backend
+// TODO: Auth0.Android v4 removed the Management API client (UsersAPIClient).
+// Expose an endpoint on your own backend (e.g. PATCH /me/metadata) that performs
+// this operation. Call it from the app with the user's access token as a Bearer
+// token. On the backend, obtain a machine-to-machine token via Client Credentials
+// and call the Management API with the minimum required scopes.
+// NEVER embed a Management API token in the app.
+// See: https://auth0.com/docs/manage-users/user-accounts/manage-user-metadata
+```
+
+This **requires backend work** — record it in the Step 10 summary.
+
+---
+
+#### 7.3 — Deprecated MFA methods removed from `AuthenticationAPIClient` → `MfaApiClient`
+
+**Applies if:** Step 5 found `loginWithOTP(`, `loginWithOOB(`, `loginWithRecoveryCode(`, or `multifactorChallenge(` called on an `AuthenticationAPIClient` in the project's source files.
+
+These four methods were deprecated in v3 and removed in v4. Obtain an `MfaApiClient` via `AuthenticationAPIClient.mfaClient(mfaToken)` and use its APIs. Confirm the exact `MfaApiClient` method signatures in the `MfaApiClient.kt` fetched in Step 4 before applying changes.
+
+```kotlin
+// v3 — removed methods on AuthenticationAPIClient
+authentication
+    .loginWithOTP(mfaToken, otp)
+    .start(object : Callback<Credentials, AuthenticationException> { /* ... */ })
+
+// v4 — obtain an MfaApiClient and use its verify API (confirm signature in MfaApiClient.kt)
+val mfaClient = authentication.mfaClient(mfaToken)
+// e.g. mfaClient.verifyWithOTP(otp) — use the exact method/parameters from the fetched source
+```
+
+The `mfaToken` still comes from the same place — an `AuthenticationException` where the challenge is required. List every migrated MFA flow in the Step 10 summary and ask the user to **re-test each MFA flow end-to-end** against their tenant. See the Migration Process section below (MFA migration) for the full method map.
+
+---
+
+#### 7.4 — `WebAuthProvider.useDPoP(context)` moved to the login builder
+
+**Applies if:** Step 5 found `WebAuthProvider.useDPoP(` called on the `WebAuthProvider` object **before** `.login(`. Read the actual call chain — it may span multiple lines.
+
+In v4, `useDPoP(context)` is configured per-request on the login builder rather than globally on the `WebAuthProvider` object. Move the `.useDPoP(context)` call so it chains **after** `.login(account)`.
+
+```kotlin
+// v3 — global configuration (no longer compiles)
+WebAuthProvider
+    .useDPoP(context)
+    .login(account)
+    .start(context, callback)
+
+// v4 — builder-based, per-request
+WebAuthProvider
+    .login(account)
+    .useDPoP(context)
+    .start(context, callback)
+```
+
+---
+
+#### 7.5 — `DPoPException.UNSUPPORTED_ERROR` removed
+
+**Applies if:** Step 5 found `DPoPException.UNSUPPORTED_ERROR` in the project's source files.
+
+With the minimum SDK raised to API 26, DPoP is supported on every API level v4 targets, so this constant was removed. Remove any reference to it — for example, a `when`/`if` branch or comparison that checked for `UNSUPPORTED_ERROR`. No replacement is needed; the unsupported-version case can no longer occur.
+
+```kotlin
+// v3 — guarding against the unsupported case
+if (error == DPoPException.UNSUPPORTED_ERROR) {   // ❌ no longer exists in v4
+    showDeviceUnsupported()
+} else {
+    handle(error)
+}
+
+// v4 — the guard is no longer applicable; handle the remaining cases
+handle(error)
+```
+
+---
+
+#### 7.6 — `SSOCredentials.expiresIn` → `expiresAt` (`Int` → `Date`)
+
+**Applies if:** Step 5 found `.expiresIn` accessed on an `SSOCredentials` value in the project's source files.
+
+`SSOCredentials.expiresIn` (raw seconds, `Int`) was renamed to `expiresAt` and is now an absolute `Date` (computed during deserialization, consistent with `Credentials.expiresAt`). Rename the property **and** update any arithmetic that assumed a duration in seconds.
+
+> The JSON wire format is unchanged — the field is still `@field:SerializedName("expires_in")` in the SDK. Only the Kotlin property name and type changed (`expiresIn: Int` → `expiresAt: Date`); don't expect a renamed `expires_at` key if you grep the raw JSON.
+
+```kotlin
+// v3 — seconds until expiry (Int)
+val secondsUntilExpiry: Int = ssoCredentials.expiresIn
+
+// v4 — absolute expiration Date
+val expirationDate: Date = ssoCredentials.expiresAt
+// If you previously did `now + expiresIn` to get an absolute time, use expiresAt directly.
+```
+
+---
+
+#### 7.7 — `SecureCredentialsManager` `Auth0`-based constructors removed
+
+**Applies if:** Step 5 found `SecureCredentialsManager(` constructed with an `Auth0` instance as the first argument in the project's source files.
+
+The two constructors that accepted an `Auth0` instance were removed. Both remaining constructors take an `AuthenticationAPIClient` first. Build the client from the `Auth0` account, then pass the **same** client into `SecureCredentialsManager`.
+
+```kotlin
+// v3 — Auth0-based constructors (removed in v4)
+val manager = SecureCredentialsManager(auth0, context, storage)
+val manager = SecureCredentialsManager(auth0, context, storage, fragmentActivity, localAuthenticationOptions)
+
+// v4 — build an AuthenticationAPIClient first, pass it in
+val apiClient = AuthenticationAPIClient(auth0)
+val manager = SecureCredentialsManager(apiClient, context, storage)
+
+// v4 — biometric variant
+val apiClient = AuthenticationAPIClient(auth0)
+val manager = SecureCredentialsManager(
+    apiClient,
+    context,
+    storage,
+    fragmentActivity,
+    localAuthenticationOptions
+)
+```
+
+```java
+// Java — same change; there is no Java-specific overload
+AuthenticationAPIClient apiClient = new AuthenticationAPIClient(auth0);
+SecureCredentialsManager manager = new SecureCredentialsManager(apiClient, context, storage);
+```
+
+> If the project enables DPoP, configure it on the client before passing it in: `AuthenticationAPIClient(auth0).useDPoP(context)`. Confirm the constructor signatures in the `SecureCredentialsManager.kt` fetched in Step 4.
+
+---
+
+### Step 8 — Build Until Green
+
+```bash
+./gradlew assembleDebug 2>&1 | tail -40
+```
+
+For each error: read it, locate the source line, match it to a Step 7 section, verify the fix against the signature fetched in Step 4, apply it in the project's existing style, then rebuild.
+
+**Common error → cause mapping:**
+
+| Build error | Likely cause |
+|---|---|
+| `unresolved reference: PasskeyAuthProvider` | §7.1 — class removed; use `AuthenticationAPIClient` passkey APIs |
+| `unresolved reference: UsersAPIClient` / `ManagementException` / `ManagementCallback` | §7.2 — Management API removed; add `// TODO:` + backend follow-up |
+| `unresolved reference: loginWithOTP` / `loginWithOOB` / `loginWithRecoveryCode` / `multifactorChallenge` | §7.3 — use `mfaClient(mfaToken)` / `MfaApiClient` |
+| `unresolved reference: useDPoP` on `WebAuthProvider` | §7.4 — move `.useDPoP(context)` after `.login(account)` |
+| `unresolved reference: UNSUPPORTED_ERROR` | §7.5 — remove the reference |
+| `unresolved reference: expiresIn` on `SSOCredentials`, or `Int`/`Date` type mismatch | §7.6 — rename to `expiresAt` (now a `Date`) |
+| `none of the following functions can be called` / `too many arguments` on `SecureCredentialsManager(` | §7.7 — build `AuthenticationAPIClient(auth0)` first, pass it in |
+| `class … must override removeAll` (custom `Storage`) | §9.4 — the interface has a default impl; override only if needed |
+
+**Limit:** Up to **10 build-fix cycles**. If the build still fails after 10 attempts, stop and show the remaining errors with context — do not guess.
+
+---
+
+### Step 9 — Behavior & Default-Value Changes (Review, Usually No Code Change)
+
+These changes compile without edits but alter runtime behavior. Surface each in the Step 10 summary. Only change code if the project depends on the old behavior.
+
+#### 9.1 — Credentials Manager default `minTtl` 0 → 60s
+
+**Applies if:** the project calls `getCredentials(...)` / `awaitCredentials(...)` without an explicit `minTtl`, or calls `hasValidCredentials()`.
+
+v4 renews credentials that expire within 60 seconds instead of only when already expired. This is the recommended behavior (avoids handing out tokens that expire mid-request). To restore v3 behavior explicitly, pass `minTtl = 0`:
+
+```kotlin
+// v4 — restore v3 behavior explicitly if required
+credentialsManager.getCredentials(scope = null, minTtl = 0, callback = callback)
+```
+
+#### 9.2 — `CredentialsManager` now uses the global executor
+
+Runtime-only. Renewals across managers backed by the same `Auth0` object are now serialized, eliminating duplicate refresh-token exchanges. **No code change required.**
+
+#### 9.3 — `clearCredentials()` now clears all storage
+
+**Applies if:** the project calls `clearCredentials()`.
+
+v4 calls `Storage.removeAll()`, clearing **all** values in the storage — including API credentials stored for specific audiences. If the project needs to preserve other data in the same `Storage`, recommend a separate `Storage` instance for API credentials, or consider the new `clearAll()` (Step 10 optional improvements).
+
+#### 9.4 — `Storage` interface gains `removeAll()`
+
+**Applies if:** the project has a class implementing the `Storage` interface.
+
+`removeAll()` ships with a default empty implementation, so existing custom `Storage` implementations still compile. **Override `removeAll()`** to actually clear storage if that custom storage is used with `clearCredentials()` — otherwise `clearCredentials()` becomes a no-op for it.
+
+---
+
+### Step 10 — Migration Summary
+
+Present a concise summary covering:
+
+**1. Prerequisites changed** — `minSdk` / Java / Gradle / AGP / Kotlin bumps applied, and that `minSdk 26` drops support for Android 7.1 and below.
+
+**2. Changes applied** — grouped by API area (§7.x), with the files touched per area.
+
+**3. Needs manual review**
+- §7.1 Passkey / §7.3 MFA flows migrated to the new clients — **re-test end-to-end** against the tenant.
+- Any `// TODO:` left for §7.2 (Management API) — backend work required.
+
+**4. Behavioral changes (no code change, verify acceptable)**
+- §9.1 `minTtl` now defaults to 60s — tokens renew 60s before expiry.
+- §9.3 `clearCredentials()` now clears **all** storage (including API credentials).
+- §9.2 `CredentialsManager` now uses the global executor (renewals serialized).
+
+**5. Backend / configuration follow-up**
+- §7.2 Management API removal — list the operations stubbed with `TODO` and what must move to a secure backend (M2M token, never on-device).
+
+**6. Optional improvements not applied** (list briefly; never auto-apply)
+- `clearAll()` — full credential **and** cryptographic key cleanup on logout/account removal.
+- `WebAuthProvider.registerCallbacks()` in `onCreate()` — prevents lost callbacks / memory leaks on configuration change or process death during authentication.
+- `DefaultClient.Builder` — the constructor is deprecated (not removed); the builder adds write/call timeouts, custom interceptors, and loggers.
+- Gson 2.8.9 → 2.11.0 (transitive) — stricter `TypeToken` / type coercion; see the Migration Process section below (Gson transitive dependency).
+
+**7. Ask the user** whether to commit the migration, explore an optional improvement, or step through specific files together.
+
+> **Security reminder:** Never include tokens, secrets, client credentials, or stored credential values in the summary or any build log.
+
+---
+
+## Detailed References
+
+- **Migration Process** (see below) — version-argument validation, prerequisite/toolchain handling, build-system edge cases (Groovy DSL, Kotlin DSL, version catalogs), MFA method map, Management-API backend pattern, Gson transitive notes, rollback, and "deprecated ≠ removed" guidance.
+- **Security Checklist** (see below) — invariants that must hold before and after migration.
+
+## Common Mistakes
+
+| Mistake | Correct approach |
+|---|---|
+| Applying a §7.x section when Step 5 didn't find that API in the project | Step 5 file-reading is the gate. Not found = skip the section entirely |
+| Using grep alone to decide if an API is used | Grep misses multi-line builder chains (e.g. `useDPoP` before `login`) and aliased variables. Read the actual files |
+| Migrating API call sites before meeting the Step 3 prerequisites | A project below `minSdk 26` / Java 17 won't build against v4. Handle prerequisites first |
+| Accepting a target-version argument without validating it | Validate exists / next-major / not-a-downgrade, then **stop and ask** on failure |
+| Using a dynamic range (`4.+`) for a pre-release tag | Pin pre-releases exactly — ranges may resolve to a different artifact |
+| Silently deleting Management API or removed-MFA call sites | Add `// TODO:` and surface in the summary — deletion breaks functionality |
+| Applying changes from the migration guide without confirming the SDK source | Every fix must trace to a signature in the files fetched in Step 4 |
+| Treating `DefaultClient(...)` constructor as a breaking change | It is **deprecated, not removed** — leave it; note the Builder as optional |
+| Starting on a dirty working tree | Always verify `git status --porcelain` is empty first |
+| Continuing past 10 failed build cycles | Stop and show the user the remaining errors |
+| Skipping the migration summary | Always produce the full summary — the user needs it |
+
+## Related Capabilities
+
+- New Auth0.Android integration from scratch → use the Auth0 Android integration workflow (above)
+- Auth0.swift major version upgrades → use the Auth0 Swift major-version migration
+- Multi-factor authentication → ask for MFA (feature:mfa)
+
+---
+
+## References
+
+- [Auth0.Android GitHub](https://github.com/auth0/Auth0.Android)
+- [Auth0.Android Releases](https://github.com/auth0/Auth0.Android/releases)
+- [V4 Migration Guide](https://github.com/auth0/Auth0.Android/blob/v4_development/V4_MIGRATION_GUIDE.md)
+- [Auth0 Android SDK Documentation](https://auth0.com/docs/libraries/auth0-android)
+
+> **Security:** Never echo tokens, client secrets, or credentials in build logs or terminal output. Never commit secrets to version control.
diff --git a/main/.mintlify/skills/auth0/references/framework-angular/index.md b/main/.mintlify/skills/auth0/references/framework-angular/index.md
new file mode 100644
index 0000000000..1c84d4f293
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-angular/index.md
@@ -0,0 +1,918 @@
+
+# Auth0 Angular Integration
+
+Add authentication to Angular applications using @auth0/auth0-angular.
+
+## Prerequisites
+
+- Angular 13+ application
+- Auth0 account and application configured
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **AngularJS (1.x)** - This SDK requires Angular 13+, use legacy solutions for AngularJS
+- **Mobile applications** - Use the Auth0 integration workflow for React Native, or native SDKs for Ionic
+- **Backend APIs** - Use JWT validation middleware for your server language
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+npm install @auth0/auth0-angular
+```
+
+### 2. Configure Environment
+
+**For automated setup with Auth0 CLI**, see the Setup Guide section below for complete scripts.
+
+**For manual setup:**
+
+Update `src/environments/environment.ts`:
+
+```typescript
+export const environment = {
+  production: false,
+  auth0: {
+    domain: 'your-tenant.auth0.com',
+    clientId: 'your-client-id',
+    authorizationParams: {
+      redirect_uri: window.location.origin
+    }
+  }
+};
+```
+
+### 3. Configure Auth Module
+
+**For standalone components (Angular 14+):**
+
+Update `src/app/app.config.ts`:
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideAuth0 } from '@auth0/auth0-angular';
+import { environment } from '../environments/environment';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAuth0({
+      domain: environment.auth0.domain,
+      clientId: environment.auth0.clientId,
+      authorizationParams: environment.auth0.authorizationParams
+    })
+  ]
+};
+```
+
+**For NgModule-based apps:**
+
+Update `src/app/app.module.ts`:
+
+```typescript
+import { AuthModule } from '@auth0/auth0-angular';
+import { environment } from '../environments/environment';
+
+@NgModule({
+  imports: [
+    AuthModule.forRoot({
+      domain: environment.auth0.domain,
+      clientId: environment.auth0.clientId,
+      authorizationParams: environment.auth0.authorizationParams
+    })
+  ]
+})
+export class AppModule {}
+```
+
+### 4. Add Authentication UI
+
+Update `src/app/app.component.ts`:
+
+```typescript
+import { Component } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+
+@Component({
+  selector: 'app-root',
+  template: `
+    <div *ngIf="auth.isLoading$ | async; else loaded">
+      <p>Loading...</p>
+    </div>
+
+    <ng-template #loaded>
+      <ng-container *ngIf="auth.isAuthenticated$ | async; else loggedOut">
+        <div *ngIf="auth.user$ | async as user">
+          <img [src]="user.picture" [alt]="user.name" />
+          <h2>Welcome, {{ user.name }}!</h2>
+          <button (click)="logout()">Logout</button>
+        </div>
+      </ng-container>
+
+      <ng-template #loggedOut">
+        <button (click)="login()">Login</button>
+      </ng-template>
+    </ng-template>
+  `
+})
+export class AppComponent {
+  constructor(public auth: AuthService) {}
+
+  login(): void {
+    this.auth.loginWithRedirect();
+  }
+
+  logout(): void {
+    this.auth.logout({ logoutParams: { returnTo: window.location.origin } });
+  }
+}
+```
+
+### 5. Test Authentication
+
+Start your dev server and test the login flow:
+
+```bash
+ng serve
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Forgot to add redirect URI in Auth0 Dashboard | Add your application URL (e.g., `http://localhost:4200`, `https://app.example.com`) to Allowed Callback URLs in Auth0 Dashboard |
+| Not configuring AuthModule properly | Must call `AuthModule.forRoot()` in NgModule or `provideAuth0()` in standalone config |
+| Accessing auth before initialization | Use `isLoading$` observable to wait for SDK initialization |
+| Storing tokens manually | Never manually store tokens - SDK handles secure storage automatically |
+| No token sent to API | Use either `authHttpInterceptorFn` for automatic token attachment, or `getAccessTokenSilently()` for manual control — see the Calling a Protected API section below |
+| Route guard not protecting routes | Apply `AuthGuard` (or `authGuardFn`) to protected routes in routing config |
+
+## Related Capabilities
+
+- Auth0 setup — run the CLI (`auth0 login`, then `auth0 apps create`)
+- Migrating from another auth provider → ask for migration (migrate)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- Managing Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+
+## Quick Reference
+
+**Core Services:**
+- `AuthService` - Main authentication service
+- `isAuthenticated$` - Observable check if user is logged in
+- `user$` - Observable user profile information
+- `loginWithRedirect()` - Initiate login
+- `logout()` - Log out user
+- `getAccessTokenSilently()` - Get access token manually (alternative to HTTP interceptor)
+
+**Common Use Cases:**
+- Login/Logout buttons → See Step 4 above
+- Protected routes with guards → see the Protected Routes section below
+- Calling a protected API → see the Calling a Protected API section below
+- Error handling → see the Error Handling section below
+
+## References
+
+- [Auth0 Angular SDK Documentation](https://auth0.com/docs/libraries/auth0-angular)
+- [Auth0 Angular Quickstart](https://auth0.com/docs/quickstart/spa/angular)
+- [SDK GitHub Repository](https://github.com/auth0/auth0-angular)
+
+---
+
+## Common Patterns
+
+### Protected Route with Auth Guard
+
+Create an auth guard (`src/app/auth.guard.ts`):
+
+```typescript
+import { inject } from '@angular/core';
+import { Router } from '@angular/router';
+import { AuthService } from '@auth0/auth0-angular';
+import { map, take } from 'rxjs/operators';
+
+export const authGuard = () => {
+  const auth = inject(AuthService);
+  const router = inject(Router);
+
+  return auth.isAuthenticated$.pipe(
+    take(1),
+    map(isAuthenticated => {
+      if (!isAuthenticated) {
+        auth.loginWithRedirect();
+        return false;
+      }
+      return true;
+    })
+  );
+};
+```
+
+**Configure routes** (`src/app/app.routes.ts`):
+
+```typescript
+import { Routes } from '@angular/router';
+import { authGuard } from './auth.guard';
+import { HomeComponent } from './home/home.component';
+import { ProfileComponent } from './profile/profile.component';
+
+export const routes: Routes = [
+  { path: '', component: HomeComponent },
+  {
+    path: 'profile',
+    component: ProfileComponent,
+    canActivate: [authGuard]  // Protect this route
+  }
+];
+```
+
+---
+
+### Get User Profile Component
+
+Create `src/app/profile/profile.component.ts`:
+
+```typescript
+import { Component } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-profile',
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <div *ngIf="auth.user$ | async as user">
+      <h1>Profile</h1>
+      <img [src]="user.picture" [alt]="user.name" />
+      <p>Name: {{ user.name }}</p>
+      <p>Email: {{ user.email }}</p>
+      <p>User ID: {{ user.sub }}</p>
+    </div>
+  `
+})
+export class ProfileComponent {
+  constructor(public auth: AuthService) {}
+}
+```
+
+---
+
+### Call Protected API (Manual Token Approach)
+
+This example uses `getAccessTokenSilently()` to manually obtain and attach tokens. This is an alternative to using the built-in HTTP interceptor — see the Calling a Protected API section for both approaches.
+
+Create `src/app/api-test/api-test.component.ts`:
+
+```typescript
+import { Component } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+import { HttpClient } from '@angular/common/http';
+import { switchMap } from 'rxjs/operators';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-api-test',
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <div>
+      <button (click)="callApi()">Call API</button>
+      <div *ngIf="error">Error: {{ error }}</div>
+      <pre *ngIf="data">{{ data | json }}</pre>
+    </div>
+  `
+})
+export class ApiTestComponent {
+  data: any = null;
+  error: string | null = null;
+
+  constructor(
+    private auth: AuthService,
+    private http: HttpClient
+  ) {}
+
+  callApi(): void {
+    this.auth.getAccessTokenSilently({
+      authorizationParams: {
+        audience: 'https://your-api-identifier'
+      }
+    }).pipe(
+      switchMap(token =>
+        this.http.get('https://api.example.com/data', {
+          headers: {
+            Authorization: `Bearer ${token}`
+          }
+        })
+      )
+    ).subscribe({
+      next: (response) => {
+        this.data = response;
+      },
+      error: (err) => {
+        this.error = err.message;
+      }
+    });
+  }
+}
+```
+
+**Note:** If calling APIs, add `audience` to your Auth module configuration:
+
+```typescript
+AuthModule.forRoot({
+  domain: environment.auth0.domain,
+  clientId: environment.auth0.clientId,
+  authorizationParams: {
+    redirect_uri: window.location.origin,
+    audience: 'https://your-api-identifier'  // Add this
+  }
+})
+```
+
+---
+
+### Custom HTTP Interceptor for API Calls
+
+This shows how to build a custom interceptor from scratch. In most cases, you should use the SDK's built-in `authHttpInterceptorFn` instead — see the Calling a Protected API section. A custom interceptor is only needed when you require logic beyond what `allowedList` provides.
+
+Create `src/app/auth.interceptor.ts`:
+
+```typescript
+import { HttpInterceptorFn } from '@angular/common/http';
+import { inject } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+import { switchMap } from 'rxjs/operators';
+
+export const authInterceptor: HttpInterceptorFn = (req, next) => {
+  const auth = inject(AuthService);
+
+  // Only add token to API calls
+  if (req.url.startsWith('https://api.example.com')) {
+    return auth.getAccessTokenSilently().pipe(
+      switchMap(token => {
+        const clonedReq = req.clone({
+          setHeaders: {
+            Authorization: `Bearer ${token}`
+          }
+        });
+        return next(clonedReq);
+      })
+    );
+  }
+
+  return next(req);
+};
+```
+
+**Register interceptor** (`src/app/app.config.ts`):
+
+```typescript
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { authInterceptor } from './auth.interceptor';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAuth0({...}),
+    provideHttpClient(
+      withInterceptors([authInterceptor])
+    )
+  ]
+};
+```
+
+---
+
+## Configuration Options
+
+### Complete Auth Configuration
+
+```typescript
+AuthModule.forRoot({
+  domain: 'your-tenant.auth0.com',
+  clientId: 'your-client-id',
+  authorizationParams: {
+    redirect_uri: window.location.origin,
+    audience: 'https://your-api-identifier',  // For API calls
+    scope: 'openid profile email',  // Default scopes
+  },
+  cacheLocation: 'localstorage',  // or 'memory'
+  useRefreshTokens: true,  // Enable refresh tokens
+  skipRedirectCallback: false,  // Skip automatic callback handling
+  errorPath: '/error',  // Path to redirect on auth errors (default: '/')
+  httpInterceptor: {
+    allowedList: [
+      'https://api.example.com/*'  // Automatically add tokens to these URLs
+    ]
+  }
+})
+```
+
+---
+
+## Testing
+
+1. Start your dev server: `ng serve`
+2. Navigate to `http://localhost:4200`
+3. Click "Login" button
+4. Complete Auth0 Universal Login
+5. Verify redirect back with user authenticated
+6. Test protected routes
+7. Click "Logout" and verify user is logged out
+
+---
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "Invalid state" error | Clear browser storage. Ensure `redirect_uri` matches configured callback URL |
+| User stuck on loading | Check Auth0 application has `http://localhost:4200` in callback URLs |
+| API calls fail with 401 | Ensure `audience` is configured and matches your API identifier |
+| Logout doesn't work | Include `returnTo` URL and configure in Auth0 "Allowed Logout URLs" |
+| HTTP interceptor not working | Check `allowedList` includes your API URLs |
+
+---
+
+## Security Considerations
+
+- **Never expose client secret** - Angular is client-side, use only public client credentials
+- **Use PKCE** - Enabled by default with @auth0/auth0-angular
+- **Validate tokens on backend** - Never trust client-side token validation
+- **Use HTTPS in production** - Auth0 requires HTTPS for production redirect URLs
+- **Implement proper CORS** - Configure allowed origins in Auth0 application settings
+
+---
+
+## Advanced Methods
+
+### getAccessTokenWithPopup
+
+Gets an access token via popup window. Useful when silent authentication fails (e.g., third-party cookies blocked).
+
+```typescript
+// Try silent, fall back to popup
+this.auth.getAccessTokenSilently().subscribe({
+  next: (token) => {
+    // Use the token (e.g., attach to API requests)
+  },
+  error: () => {
+    // Silent auth failed, try popup
+    this.auth.getAccessTokenWithPopup().subscribe(token => {
+      // Use the token (e.g., attach to API requests)
+    });
+  }
+});
+```
+
+### connectAccountWithRedirect
+
+Redirects to connect an additional account to the logged-in user. Allows users to link multiple identity providers.
+
+```typescript
+// Link a Google account to existing user
+this.auth.connectAccountWithRedirect({
+  connection: 'google-oauth2',
+  scopes: ['openid', 'profile', 'email'],
+  authorizationParams: {
+    // additional params
+  }
+}).subscribe();
+```
+
+After the redirect callback, `handleRedirectCallback` will be called with the details of the connected account.
+
+---
+
+## Related Capabilities
+
+- Auth0 setup — run the CLI (`auth0 login`, then `auth0 apps create`)
+- Migrating from another auth provider → ask for migration (migrate)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- B2B multi-tenancy → ask for Organizations (feature:organizations)
+- Passkey authentication → ask for MFA (feature:mfa)
+
+---
+
+## References
+
+- [Auth0 Angular SDK Documentation](https://auth0.com/docs/libraries/auth0-angular)
+- [Auth0 Angular SDK GitHub](https://github.com/auth0/auth0-angular)
+- [Auth0 Angular Quickstart](https://auth0.com/docs/quickstart/spa/angular)
+- [Angular Router Documentation](https://angular.io/guide/router)
+
+---
+
+# Auth0 Angular Integration Patterns
+
+Angular-specific implementation patterns with route guards, HTTP interceptors, and RxJS.
+
+---
+
+## Protected Routes
+
+### Auth Guard
+
+Create `src/app/guards/auth.guard.ts`:
+
+```typescript
+import { inject } from '@angular/core';
+import { Router } from '@angular/router';
+import { AuthService } from '@auth0/auth0-angular';
+import { map } from 'rxjs/operators';
+
+export const authGuard = () => {
+  const authService = inject(AuthService);
+  const router = inject(Router);
+
+  return authService.isAuthenticated$.pipe(
+    map(isAuthenticated => {
+      if (!isAuthenticated) {
+        authService.loginWithRedirect();
+        return false;
+      }
+      return true;
+    })
+  );
+};
+```
+
+### Apply Guard to Routes
+
+```typescript
+// app.routes.ts (standalone)
+import { Routes } from '@angular/router';
+import { authGuard } from './guards/auth.guard';
+
+export const routes: Routes = [
+  { path: '', component: HomeComponent },
+  {
+    path: 'profile',
+    component: ProfileComponent,
+    canActivate: [authGuard]
+  }
+];
+```
+
+---
+
+## Calling a Protected API
+
+There are two alternative approaches to attach access tokens to API requests. Choose the one that best fits your needs — you do not need both:
+
+- **HTTP Interceptor (recommended)** — Automatically attaches tokens to outgoing requests matching a configured URL list. This is the simplest, most centralized approach and works well for most applications.
+- **Manual token retrieval** — Call `getAccessTokenSilently()` to obtain a token and attach it to requests yourself. Use this when you need explicit, per-request control over token handling.
+
+### Option 1: HTTP Interceptor
+
+Configure the built-in HTTP interceptor in app config:
+
+```typescript
+// app.config.ts
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { authHttpInterceptorFn } from '@auth0/auth0-angular';
+import { environment } from '../environments/environment'; // Adjust path as needed
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAuth0({
+      domain: environment.auth0.domain,
+      clientId: environment.auth0.clientId,
+      authorizationParams: {
+        audience: 'https://your-api-identifier',
+        redirect_uri: window.location.origin
+      },
+      httpInterceptor: {
+        allowedList: [
+          '/api/*',
+          'https://api.example.com/*'
+        ]
+      }
+    }),
+    provideHttpClient(
+      withInterceptors([authHttpInterceptorFn])
+    )
+  ]
+};
+```
+
+With this in place, any `HttpClient` request to a URL matching `allowedList` will automatically include the access token:
+
+```typescript
+// data.service.ts
+import { Injectable } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+
+@Injectable({ providedIn: 'root' })
+export class DataService {
+  constructor(private http: HttpClient) {}
+
+  getData() {
+    return this.http.get('https://api.example.com/data');
+    // Access token automatically added by interceptor
+  }
+}
+```
+
+### Option 2: Manual Token Retrieval
+
+If you prefer explicit control instead of using the interceptor, call `getAccessTokenSilently()` to obtain a token and attach it yourself:
+
+```typescript
+import { AuthService } from '@auth0/auth0-angular';
+import { HttpClient } from '@angular/common/http';
+import { switchMap } from 'rxjs/operators';
+
+constructor(private auth: AuthService, private http: HttpClient) {}
+
+callApi() {
+  this.auth.getAccessTokenSilently({
+    authorizationParams: {
+      audience: 'https://your-api-identifier'
+    }
+  }).pipe(
+    switchMap(token =>
+      this.http.get('https://api.example.com/data', {
+        headers: { Authorization: `Bearer ${token}` }
+      })
+    )
+  ).subscribe({
+    next: (response) => console.log(response),
+    error: (err) => console.error(err)
+  });
+}
+```
+
+---
+
+## User Profile Component
+
+```typescript
+import { Component } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-profile',
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <div *ngIf="auth.user$ | async as user">
+      <img [src]="user.picture" [alt]="user.name" />
+      <h2>{{ user.name }}</h2>
+      <p>{{ user.email }}</p>
+      <pre>{{ user | json }}</pre>
+    </div>
+  `
+})
+export class ProfileComponent {
+  constructor(public auth: AuthService) {}
+}
+```
+
+---
+
+## Error Handling
+
+### Handle Auth Errors
+
+```typescript
+import { Component, OnInit } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+
+@Component({
+  template: `
+    <div *ngIf="error$ | async as error" class="error">
+      <h3>Authentication Error</h3>
+      <p>{{ error.message }}</p>
+    </div>
+  `
+})
+export class AppComponent implements OnInit {
+  error$ = this.auth.error$;
+
+  constructor(private auth: AuthService) {}
+
+  ngOnInit() {
+    this.error$.subscribe(error => {
+      if (error) {
+        console.error('Auth error:', error);
+      }
+    });
+  }
+}
+```
+
+---
+
+## Common Patterns
+
+### Login with Options
+
+```typescript
+login() {
+  this.auth.loginWithRedirect({
+    authorizationParams: {
+      connection: 'google-oauth2',
+      screen_hint: 'signup'
+    }
+  });
+}
+```
+
+## Testing
+
+### Mock AuthService
+
+```typescript
+// auth.service.mock.ts
+import { of } from 'rxjs';
+
+export const mockAuthService = {
+  isAuthenticated$: of(true),
+  user$: of({ name: 'Test User', email: 'test@example.com' }),
+  loginWithRedirect: jasmine.createSpy('loginWithRedirect'),
+  logout: jasmine.createSpy('logout'),
+  getAccessTokenSilently: jasmine.createSpy('getAccessTokenSilently').and.returnValue(of('mock-token'))
+};
+```
+
+### Use in Tests
+
+```typescript
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { AuthService } from '@auth0/auth0-angular';
+import { mockAuthService } from './auth.service.mock';
+
+describe('AppComponent', () => {
+  let fixture: ComponentFixture<AppComponent>;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [
+        { provide: AuthService, useValue: mockAuthService }
+      ]
+    });
+    fixture = TestBed.createComponent(AppComponent);
+  });
+
+  it('should display user name', () => {
+    fixture.detectChanges();
+    expect(fixture.nativeElement.textContent).toContain('Test User');
+  });
+});
+```
+
+---
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| CORS errors | Add URLs to "Allowed Web Origins" in Auth0 Dashboard |
+| Interceptor not adding tokens | Verify `allowedList` in httpInterceptor config |
+| Guard not redirecting | Ensure AuthService is provided in root |
+| Observables not updating | Use `async` pipe or subscribe properly |
+
+---
+
+---
+
+# Auth0 Angular Setup Guide
+
+Complete setup instructions for Angular applications.
+
+---
+
+## Quick Setup (Automated)
+
+### Bash Script
+
+```bash
+#!/bin/bash
+
+# Install Auth0 CLI
+if ! command -v auth0 &> /dev/null; then
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    brew install auth0/auth0-cli/auth0
+  elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    # Download and review the install script before executing
+    curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh -o /tmp/auth0-install.sh
+    echo "⚠️  Review the install script at /tmp/auth0-install.sh before running"
+    sh /tmp/auth0-install.sh -b /usr/local/bin
+    rm /tmp/auth0-install.sh
+  fi
+fi
+
+# Login to Auth0
+if ! auth0 tenants list &> /dev/null; then
+  echo "Auth0 Login Required"
+  read -p "Do you have an Auth0 account? (y/n): " HAS_ACCOUNT
+  if [[ "$HAS_ACCOUNT" != "y" ]]; then
+    echo "Visit https://auth0.com/signup to create an account"
+    read -p "Press Enter when ready..."
+  fi
+  auth0 login
+fi
+
+# Create or select app
+auth0 apps list
+read -p "Enter your Auth0 app ID (or press Enter to create new): " APP_ID
+
+if [ -z "$APP_ID" ]; then
+  APP_NAME="${PWD##*/}-angular-app"
+  APP_ID=$(auth0 apps create \
+    --name "$APP_NAME" \
+    --type spa \
+    --auth-method None \
+    --callbacks "http://localhost:4200" \
+    --logout-urls "http://localhost:4200" \
+    --origins "http://localhost:4200" \
+    --web-origins "http://localhost:4200" \
+    --metadata "created_by=agent_skills" \
+    --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+fi
+
+# Get credentials
+AUTH0_DOMAIN=$(auth0 apps show "$APP_ID" --json | grep -o '"domain":"[^"]*' | cut -d'"' -f4)
+AUTH0_CLIENT_ID=$(auth0 apps show "$APP_ID" --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+
+echo "✅ Configuration complete!"
+echo "Update src/environments/environment.ts with:"
+echo "  domain: '$AUTH0_DOMAIN'"
+echo "  clientId: '$AUTH0_CLIENT_ID'"
+```
+
+---
+
+## Manual Setup
+
+### Step 1: Install SDK
+
+```bash
+npm install @auth0/auth0-angular
+```
+
+### Step 2: Configure Environment
+
+Create or update `src/environments/environment.ts`:
+
+```typescript
+export const environment = {
+  production: false,
+  auth0: {
+    domain: 'your-tenant.auth0.com',
+    clientId: 'your-client-id',
+    authorizationParams: {
+      redirect_uri: window.location.origin
+    }
+  }
+};
+```
+
+For production (`src/environments/environment.prod.ts`):
+
+```typescript
+export const environment = {
+  production: true,
+  auth0: {
+    domain: 'your-tenant.auth0.com',
+    clientId: 'your-client-id',
+    authorizationParams: {
+      redirect_uri: 'https://app.example.com'
+    }
+  }
+};
+```
+
+### Step 3: Get Auth0 Credentials
+
+Using Auth0 CLI:
+
+```bash
+auth0 login
+auth0 apps list
+auth0 apps show <app-id>
+```
+
+Or via [Auth0 Dashboard](https://manage.auth0.com):
+1. Create Single Page Application
+2. Configure callback URLs: `http://localhost:4200`
+3. Copy domain and client ID
+
+---
+
+## Troubleshooting
+
+**Module not found errors:**
+- Ensure @auth0/auth0-angular is in package.json
+- Run `npm install`
+
+**CORS errors:**
+- Add `http://localhost:4200` to "Allowed Web Origins" in Auth0 Dashboard
+
+**Environment variables not working:**
+- Angular uses environment files, not .env
+- Rebuild app after changing environment files
+
+---
diff --git a/main/.mintlify/skills/auth0/references/framework-aspnetcore-api/index.md b/main/.mintlify/skills/auth0/references/framework-aspnetcore-api/index.md
new file mode 100644
index 0000000000..e41a37b771
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-aspnetcore-api/index.md
@@ -0,0 +1,887 @@
+
+# Auth0 ASP.NET Core Web API Integration
+
+Protect ASP.NET Core Web API endpoints with JWT access token validation using Auth0.AspNetCore.Authentication.Api.
+
+## Prerequisites
+
+- .NET 8.0 SDK or higher
+- Auth0 API configured (not Application - must be API resource)
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **Server-rendered web applications** - Use session-based auth (Auth0.AspNetCore.Authentication) for MVC/Razor Pages apps
+- **Single Page Applications** - Use the Auth0 React, Vue, or Angular integration workflow for client-side auth
+- **Mobile applications** - Use the Auth0 React Native integration workflow for React Native/Expo
+- **Blazor WebAssembly** - Requires different auth approach (OIDC client-side)
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+dotnet add package Auth0.AspNetCore.Authentication.Api
+```
+
+### 2. Create Auth0 API
+
+You need an **API** (not Application) in Auth0.
+
+> **STOP — ask the user before proceeding.**
+>
+> Ask exactly this question and wait for their answer before doing anything else:
+>
+> > "How would you like to create the Auth0 API resource?
+> > 1. **Automated** — I'll run Auth0 CLI scripts that create the resource and write the exact values to your appsettings.json automatically.
+> > 2. **Manual** — You create the API yourself in the Auth0 Dashboard (or via `auth0 apis create`) and provide me the Domain and Audience.
+> >
+> > Which do you prefer? (1 = Automated / 2 = Manual)"
+>
+> Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.
+
+**If the user chose Automated**, follow the Setup Guide section below for complete CLI scripts. The automated path writes `appsettings.json` for you — skip Step 3 below and proceed directly to Step 4.
+
+**If the user chose Manual**, follow the Setup Guide section below (Manual Setup) for full instructions including User Secrets and environment variable options. Then continue with Step 3 below.
+
+Quick reference for manual API creation:
+
+```bash
+# Using Auth0 CLI
+auth0 apis create \
+  --name "My ASP.NET Core API" \
+  --identifier https://my-api.example.com
+```
+
+Or create manually in Auth0 Dashboard → Applications → APIs
+
+### 3. Configure appsettings.json
+
+```json
+{
+  "Auth0": {
+    "Domain": "your-tenant.auth0.com",
+    "Audience": "https://my-api.example.com"
+  }
+}
+```
+
+**Important:** Domain must NOT include `https://`. The library constructs the authority URL automatically.
+
+### 4. Configure Program.cs
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+// Register Auth0 JWT validation
+builder.Services.AddAuth0ApiAuthentication(options =>
+{
+    options.Domain = builder.Configuration["Auth0:Domain"];
+    options.JwtBearerOptions = new JwtBearerOptions
+    {
+        Audience = builder.Configuration["Auth0:Audience"]
+    };
+});
+
+builder.Services.AddAuthorization();
+
+var app = builder.Build();
+
+// Middleware order matters: authentication before authorization
+app.UseAuthentication();
+app.UseAuthorization();
+
+// Add your endpoints here (see Step 5)
+app.MapGet("/api/public", () => Results.Ok(new { message = "Public" }));
+
+app.Run();
+```
+
+### 5. Protect Endpoints
+
+**Minimal API:**
+
+```csharp
+// Public endpoint - no authentication
+app.MapGet("/api/public", () => Results.Ok(new { message = "Hello from a public endpoint!" }));
+
+// Protected endpoint - requires valid JWT
+app.MapGet("/api/private", (HttpContext ctx) =>
+{
+    var userId = ctx.User.FindFirst("sub")?.Value;
+    return Results.Ok(new { message = "Hello from a protected endpoint!", userId });
+}).RequireAuthorization();
+```
+
+**Controller-based:**
+
+```csharp
+[ApiController]
+[Route("api")]
+public class MessagesController : ControllerBase
+{
+    [HttpGet("public")]
+    public IActionResult Public() =>
+        Ok(new { message = "Hello from a public endpoint!" });
+
+    [Authorize]
+    [HttpGet("private")]
+    public IActionResult Private() =>
+        Ok(new { message = "Hello from a protected endpoint!", userId = User.FindFirst("sub")?.Value });
+}
+```
+
+### 6. Test API
+
+Test public endpoint:
+
+```bash
+curl http://localhost:5000/api/public
+```
+
+Test protected endpoint (requires access token):
+
+```bash
+curl http://localhost:5000/api/private \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+Get a test token via Client Credentials flow or Auth0 Dashboard → APIs → Test tab.
+Capture the token into a shell variable (`TOKEN=$(...)`) and reference `$TOKEN`
+rather than pasting the raw token inline — inline token values leak into shell
+history and terminal scrollback.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Domain includes `https://` | Use `your-tenant.auth0.com` format only - no scheme prefix |
+| Audience doesn't match API Identifier | Must exactly match the API Identifier set in Auth0 Dashboard |
+| Created Application instead of API in Auth0 | Must create API resource in Auth0 Dashboard → Applications → APIs |
+| Wrong middleware order | `UseAuthentication()` must come before `UseAuthorization()` |
+| Using ID token instead of access token | Must use **access token** for API auth, not ID token |
+| HTTPS certificate errors locally | Run `dotnet dev-certs https --trust` |
+
+## Scope-Based Authorization
+
+See the Scope-Based Authorization section below for defining and enforcing scope policies.
+
+## DPoP Support
+
+Built-in proof-of-possession token binding per RFC 9449. See the DPoP Support section below for configuration.
+
+## Related Capabilities
+
+- Basic Auth0 setup → set up Auth0 with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- Manage Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+
+## Quick Reference
+
+**Configuration Options:**
+- `options.Domain` - Auth0 tenant domain, no `https://` prefix (required)
+- `options.JwtBearerOptions.Audience` - API Identifier from Auth0 API settings (required)
+- `options.JwtBearerOptions` - Full access to underlying Microsoft JWT Bearer options
+
+**User Claims:**
+- `ctx.User.FindFirst("sub")?.Value` - User ID (subject)
+- `ctx.User.FindFirst("scope")?.Value` - Space-separated scopes
+- `ctx.User.FindAll("scope")` - All scope claims
+
+**Common Use Cases:**
+- Protect Minimal API routes → `.RequireAuthorization()` (see Step 5)
+- Protect controller actions → `[Authorize]` attribute (see Step 5)
+- Scope enforcement → see the Scope-Based Authorization section below
+- DPoP token binding → see the DPoP Support section below
+- Advanced JWT Bearer config → see the API Reference section below
+
+## References
+
+- [Auth0 ASP.NET Core Web API Quickstart](https://auth0.com/docs/quickstart/backend/aspnet-core-webapi)
+- [SDK GitHub Repository](https://github.com/auth0/aspnetcore-api)
+- [API Documentation](https://auth0.github.io/aspnetcore-api)
+- [Access Tokens Guide](https://auth0.com/docs/secure/tokens/access-tokens)
+
+---
+
+# Auth0 ASP.NET Core Web API - API Reference
+
+Complete reference for Auth0.AspNetCore.Authentication.Api configuration options and extension methods.
+
+---
+
+## Extension Methods
+
+### `AddAuth0ApiAuthentication`
+
+Registers Auth0 JWT Bearer authentication with the dependency injection container.
+
+```csharp
+builder.Services.AddAuth0ApiAuthentication(options =>
+{
+    options.Domain = "your-tenant.auth0.com";
+    options.JwtBearerOptions = new JwtBearerOptions
+    {
+        Audience = "https://my-api.example.com"
+    };
+});
+```
+
+---
+
+## Auth0ApiAuthenticationOptions
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `Domain` | `string` | Yes | Auth0 tenant domain. Format: `your-tenant.auth0.com` (no `https://` prefix) |
+| `JwtBearerOptions` | `JwtBearerOptions` | Yes | Microsoft JWT Bearer options. Set `Audience` here. |
+
+### `Domain`
+
+Your Auth0 tenant domain. The library constructs the authority URL as `https://{Domain}/`.
+
+```csharp
+options.Domain = builder.Configuration["Auth0:Domain"];
+// e.g., "dev-abc123.us.auth0.com"
+```
+
+### `JwtBearerOptions`
+
+Full access to the underlying [Microsoft.AspNetCore.Authentication.JwtBearer.JwtBearerOptions](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.jwtbearer.jwtbeareroptions).
+
+Key sub-properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Audience` | `string` | API Identifier from Auth0. Must exactly match. |
+| `TokenValidationParameters` | `TokenValidationParameters` | Additional token validation rules |
+| `Events` | `JwtBearerEvents` | Hooks into authentication lifecycle |
+| `SaveToken` | `bool` | Whether to save the raw token in the auth properties |
+| `RequireHttpsMetadata` | `bool` | Defaults to `true` in production |
+| `IncludeErrorDetails` | `bool` | Include error details in 401/403 responses |
+
+---
+
+## Auth0ApiAuthenticationBuilder
+
+Returned by `AddAuth0ApiAuthentication`. Fluent builder for additional configuration.
+
+### `.WithDPoP()`
+
+Enables DPoP token validation with default settings (Allowed mode).
+
+```csharp
+builder.Services.AddAuth0ApiAuthentication(options => { ... })
+    .WithDPoP();
+```
+
+### `.WithDPoP(Action<DPoPOptions> configureDPoP)`
+
+Enables DPoP with custom configuration.
+
+```csharp
+builder.Services.AddAuth0ApiAuthentication(options => { ... })
+    .WithDPoP(dpop =>
+    {
+        dpop.Mode = DPoPModes.Required;
+        dpop.IatOffset = 300;
+        dpop.Leeway = 30;
+    });
+```
+
+---
+
+## DPoPOptions
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `Mode` | `DPoPModes` | `Allowed` | Controls which token types are accepted |
+| `IatOffset` | `int` | `0` | Allowed clock skew in seconds for the `iat` claim |
+| `Leeway` | `int` | `0` | Additional leeway in seconds for token time validation |
+
+### DPoPModes Enum
+
+| Value | Description |
+|-------|-------------|
+| `DPoPModes.Allowed` | Accept both DPoP-bound and standard Bearer tokens |
+| `DPoPModes.Required` | Only accept DPoP-bound tokens; reject standard Bearer |
+| `DPoPModes.Disabled` | Disable DPoP; standard JWT Bearer only |
+
+---
+
+## ASP.NET Core Authorization
+
+Auth0 does not provide custom authorization attributes. Use standard ASP.NET Core authorization:
+
+### Policy-Based Authorization
+
+```csharp
+// Register policies
+builder.Services.AddAuthorization(options =>
+{
+    options.AddPolicy("read:messages", policy =>
+        policy.RequireClaim("scope", "read:messages"));
+});
+
+// Apply to Minimal API
+app.MapGet("/endpoint", handler).RequireAuthorization("read:messages");
+
+// Apply to controller action
+[Authorize(Policy = "read:messages")]
+public IActionResult GetMessages() { ... }
+```
+
+### Attribute-Based Authorization
+
+```csharp
+// Require any authenticated user
+[Authorize]
+public IActionResult Private() { ... }
+
+// Require specific policy
+[Authorize(Policy = "read:messages")]
+public IActionResult Messages() { ... }
+
+// Allow anonymous on an otherwise protected controller
+[AllowAnonymous]
+public IActionResult Public() { ... }
+```
+
+---
+
+## JwtBearerEvents Hooks
+
+Configure callbacks for authentication lifecycle events:
+
+| Event | When | Common Use |
+|-------|------|------------|
+| `OnTokenValidated` | After token is validated | Extract custom claims, enrich identity |
+| `OnAuthenticationFailed` | Token validation fails | Custom logging, error responses |
+| `OnChallenge` | 401 response about to be sent | Customize 401 response body |
+| `OnForbidden` | 403 response about to be sent | Customize 403 response body |
+| `OnMessageReceived` | Before token extraction | Extract token from non-standard location |
+
+**Example - Custom 401 response:**
+
+```csharp
+options.JwtBearerOptions = new JwtBearerOptions
+{
+    Audience = "...",
+    Events = new JwtBearerEvents
+    {
+        OnChallenge = context =>
+        {
+            context.HandleResponse();
+            context.Response.StatusCode = 401;
+            context.Response.ContentType = "application/json";
+            return context.Response.WriteAsJsonAsync(new
+            {
+                error = "unauthorized",
+                error_description = "A valid access token is required."
+            });
+        }
+    }
+};
+```
+
+---
+
+## References
+
+- [Auth0 ASP.NET Core Web API Quickstart](https://auth0.com/docs/quickstart/backend/aspnet-core-webapi)
+- [SDK GitHub Repository](https://github.com/auth0/aspnetcore-api)
+- [Microsoft JWT Bearer Documentation](https://learn.microsoft.com/en-us/aspnet/core/security/authentication/jwtbearer)
+
+---
+
+# Auth0 ASP.NET Core Web API Integration Patterns
+
+Advanced integration patterns for ASP.NET Core Web API applications.
+
+---
+
+## Scope-Based Authorization
+
+### Define Authorization Policies
+
+In `Program.cs`, add policies that map to Auth0 API permissions:
+
+```csharp
+builder.Services.AddAuthorization(options =>
+{
+    options.AddPolicy("read:messages", policy =>
+        policy.RequireClaim("scope", "read:messages"));
+
+    options.AddPolicy("write:messages", policy =>
+        policy.RequireClaim("scope", "write:messages"));
+
+    options.AddPolicy("manage:orders", policy =>
+    {
+        policy.RequireClaim("scope", "read:orders");
+        policy.RequireClaim("scope", "write:orders");
+    });
+});
+```
+
+### Apply Policies to Endpoints
+
+**Minimal API:**
+
+```csharp
+app.MapGet("/api/messages", (HttpContext ctx) =>
+{
+    return Results.Ok(new { messages = new[] { "Hello", "World" } });
+}).RequireAuthorization("read:messages");
+
+app.MapPost("/api/messages", (HttpContext ctx) =>
+{
+    return Results.Created("/api/messages/1", new { id = 1 });
+}).RequireAuthorization("write:messages");
+```
+
+**Controller-based:**
+
+```csharp
+[ApiController]
+[Route("api/messages")]
+public class MessagesController : ControllerBase
+{
+    [HttpGet]
+    [Authorize(Policy = "read:messages")]
+    public IActionResult GetMessages() =>
+        Ok(new { messages = new[] { "Hello", "World" } });
+
+    [HttpPost]
+    [Authorize(Policy = "write:messages")]
+    public IActionResult CreateMessage() =>
+        Created("/api/messages/1", new { id = 1 });
+}
+```
+
+### Define Permissions in Auth0
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Select your API
+3. Click the **Permissions** tab
+4. Add permissions matching your policy names (e.g., `read:messages`, `write:messages`)
+
+### Request Tokens with Scopes
+
+Clients must request tokens that include the required scopes:
+
+```bash
+# Client Credentials with specific scopes
+curl -X POST https://your-tenant.auth0.com/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_id": "YOUR_CLIENT_ID",
+    "client_secret": "YOUR_CLIENT_SECRET",
+    "audience": "https://my-api.example.com",
+    "grant_type": "client_credentials",
+    "scope": "read:messages write:messages"
+  }'
+```
+
+---
+
+## DPoP Support
+
+DPoP (Demonstrating Proof of Possession, RFC 9449) binds tokens to a specific client key pair, preventing token theft.
+
+### Enable DPoP
+
+```csharp
+builder.Services.AddAuth0ApiAuthentication(options =>
+{
+    options.Domain = builder.Configuration["Auth0:Domain"];
+    options.JwtBearerOptions = new JwtBearerOptions
+    {
+        Audience = builder.Configuration["Auth0:Audience"]
+    };
+})
+.WithDPoP(); // Accept both DPoP and Bearer tokens (Allowed mode)
+```
+
+### DPoP Required Mode
+
+To reject standard Bearer tokens and accept only DPoP-bound tokens:
+
+```csharp
+.WithDPoP(dpopOptions =>
+{
+    dpopOptions.Mode = DPoPModes.Required;
+});
+```
+
+Optionally configure clock skew tolerance:
+
+```csharp
+.WithDPoP(dpopOptions =>
+{
+    dpopOptions.Mode = DPoPModes.Required;
+    dpopOptions.IatOffset = 300;  // Allow 5-minute clock skew for iat claim
+    dpopOptions.Leeway = 30;      // 30-second leeway for token validation
+});
+```
+
+### DPoP Modes
+
+| Mode | Behavior |
+|------|----------|
+| `DPoPModes.Allowed` (default) | Accept both DPoP-bound and standard Bearer tokens |
+| `DPoPModes.Required` | Only accept DPoP-bound tokens; reject standard Bearer |
+| `DPoPModes.Disabled` | Standard JWT Bearer only, DPoP disabled |
+
+### Enable DPoP on Auth0 API
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Select your API
+3. Enable **Allow Skipping User Consent** and enable DPoP binding requirement
+
+---
+
+## Accessing User Claims
+
+### From HttpContext in Minimal API
+
+```csharp
+app.MapGet("/api/profile", (HttpContext ctx) =>
+{
+    var userId = ctx.User.FindFirst("sub")?.Value;
+    var email = ctx.User.FindFirst("https://example.com/email")?.Value; // custom claim
+    var scopes = ctx.User.FindFirst("scope")?.Value?.Split(' ') ?? [];
+
+    return Results.Ok(new { userId, scopes });
+}).RequireAuthorization();
+```
+
+### From Controller
+
+```csharp
+[Authorize]
+[HttpGet("profile")]
+public IActionResult GetProfile()
+{
+    var userId = User.FindFirst("sub")?.Value;
+    var scopes = User.FindFirst("scope")?.Value?.Split(' ') ?? [];
+
+    return Ok(new { userId, scopes });
+}
+```
+
+### Common JWT Claims
+
+| Claim | Description |
+|-------|-------------|
+| `sub` | User ID (subject) |
+| `scope` | Space-separated list of granted scopes |
+| `aud` | Audience (your API identifier) |
+| `iss` | Issuer (your Auth0 tenant URL) |
+| `exp` | Expiration timestamp |
+| `iat` | Issued-at timestamp |
+
+Custom claims added via Auth0 Actions use namespaced keys, e.g., `https://example.com/role`.
+
+---
+
+## Error Handling
+
+### Return Problem Details for Auth Errors
+
+```csharp
+builder.Services.AddProblemDetails();
+
+// Customize auth error responses
+builder.Services.AddAuth0ApiAuthentication(options =>
+{
+    options.Domain = builder.Configuration["Auth0:Domain"];
+    options.JwtBearerOptions = new JwtBearerOptions
+    {
+        Audience = builder.Configuration["Auth0:Audience"],
+        Events = new JwtBearerEvents
+        {
+            OnChallenge = context =>
+            {
+                context.HandleResponse();
+                context.Response.StatusCode = 401;
+                context.Response.ContentType = "application/json";
+                return context.Response.WriteAsJsonAsync(new
+                {
+                    error = "unauthorized",
+                    error_description = "A valid access token is required."
+                });
+            },
+            OnForbidden = context =>
+            {
+                context.Response.StatusCode = 403;
+                context.Response.ContentType = "application/json";
+                return context.Response.WriteAsJsonAsync(new
+                {
+                    error = "insufficient_scope",
+                    error_description = "The access token does not have the required scopes."
+                });
+            }
+        }
+    };
+});
+```
+
+### Standard Error Responses
+
+| Status | Cause | Fix |
+|--------|-------|-----|
+| 401 | Missing or invalid token | Include valid `Authorization: Bearer <token>` header |
+| 401 | Expired token | Request a fresh access token |
+| 401 | Wrong audience | Token's `aud` claim must match your API Identifier |
+| 403 | Insufficient scope | Token must include required scopes |
+
+---
+
+## Mixed Public and Protected Endpoints
+
+```csharp
+// Public - no auth needed
+app.MapGet("/api/public", () =>
+    Results.Ok(new { message = "Public endpoint" }));
+
+// Protected - requires valid JWT
+app.MapGet("/api/private", (HttpContext ctx) =>
+    Results.Ok(new { message = "Private endpoint", userId = ctx.User.FindFirst("sub")?.Value }))
+    .RequireAuthorization();
+
+// Protected with scope
+app.MapGet("/api/messages", (HttpContext ctx) =>
+    Results.Ok(new { messages = Array.Empty<string>() }))
+    .RequireAuthorization("read:messages");
+```
+
+---
+
+## Custom Token Validation
+
+For advanced scenarios, configure additional JWT validation parameters:
+
+```csharp
+builder.Services.AddAuth0ApiAuthentication(options =>
+{
+    options.Domain = builder.Configuration["Auth0:Domain"];
+    options.JwtBearerOptions = new JwtBearerOptions
+    {
+        Audience = builder.Configuration["Auth0:Audience"],
+        TokenValidationParameters = new TokenValidationParameters
+        {
+            NameClaimType = "sub",  // Map sub claim to User.Identity.Name
+            ClockSkew = TimeSpan.FromSeconds(30)
+        }
+    };
+});
+```
+
+---
+
+## Testing
+
+### Integration Testing with WebApplicationFactory
+
+```csharp
+public class ApiTests : IClassFixture<WebApplicationFactory<Program>>
+{
+    private readonly WebApplicationFactory<Program> _factory;
+
+    public ApiTests(WebApplicationFactory<Program> factory) =>
+        _factory = factory;
+
+    [Fact]
+    public async Task PublicEndpoint_Returns200()
+    {
+        var client = _factory.CreateClient();
+        var response = await client.GetAsync("/api/public");
+        response.EnsureSuccessStatusCode();
+    }
+
+    [Fact]
+    public async Task ProtectedEndpoint_WithoutToken_Returns401()
+    {
+        var client = _factory.CreateClient();
+        var response = await client.GetAsync("/api/private");
+        Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
+    }
+
+    [Fact]
+    public async Task ProtectedEndpoint_WithValidToken_Returns200()
+    {
+        // Option 1: Real token from Auth0 CLI (requires network, good for integration tests)
+        //   auth0 test token --audience https://my-api.example.com
+        //
+        // Option 2: Mock JWT for fast unit tests — override auth in WebApplicationFactory:
+        //   _factory.WithWebHostBuilder(b => b.ConfigureTestServices(services =>
+        //   {
+        //       services.PostConfigure<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme, o =>
+        //       {
+        //           o.TokenValidationParameters = new TokenValidationParameters
+        //           {
+        //               ValidateIssuer = false,
+        //               ValidateAudience = false,
+        //               ValidateLifetime = false,
+        //               SignatureValidator = (token, _) => new JwtSecurityToken(token)
+        //           };
+        //       });
+        //   }));
+        //   Then generate a token with: new JwtSecurityTokenHandler().WriteToken(new JwtSecurityToken(...))
+        var client = _factory.CreateClient();
+        client.DefaultRequestHeaders.Authorization =
+            new AuthenticationHeaderValue("Bearer", "YOUR_TEST_TOKEN");
+
+        var response = await client.GetAsync("/api/private");
+        response.EnsureSuccessStatusCode();
+    }
+}
+```
+
+---
+
+## Security Considerations
+
+- **Never hardcode Domain or Audience** - Always use configuration (appsettings, User Secrets, environment variables)
+- **Use HTTPS in production** - Auth0 requires HTTPS for token validation
+- **Use minimal scopes** - Only request and enforce scopes your API actually needs
+- **Keep packages updated** - Regularly update `Auth0.AspNetCore.Authentication.Api` for security patches
+
+---
+
+---
+
+# Auth0 ASP.NET Core Web API Setup Guide
+
+Setup instructions for ASP.NET Core Web API applications.
+
+---
+
+## Quick Setup (Automated)
+
+Below uses the Auth0 CLI to create an Auth0 API resource and retrieve your credentials.
+
+### Step 1: Install Auth0 CLI and create API resource
+
+```bash
+# Install Auth0 CLI (macOS)
+brew install auth0/auth0-cli/auth0
+
+# Login
+auth0 login --no-input
+
+# Create an Auth0 API resource
+auth0 apis create \
+  --name "My ASP.NET Core API" \
+  --identifier https://my-api.example.com \
+  --json
+```
+
+Note the `identifier` value - this is your Audience.
+
+### Step 2: Add configuration
+
+Once you have your Domain and Audience, add the following to `appsettings.json`:
+
+```json
+{
+  "Auth0": {
+    "Domain": "your-tenant.auth0.com",
+    "Audience": "https://my-api.example.com"
+  }
+}
+```
+
+Replace `your-tenant.auth0.com` with your Auth0 tenant domain and `https://my-api.example.com` with the identifier you used when creating the API resource.
+
+---
+
+## Manual Setup
+
+### Install Package
+
+```bash
+dotnet add package Auth0.AspNetCore.Authentication.Api
+```
+
+### Create Auth0 API Resource
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Click **Create API**
+3. Set a **Name** and an **Identifier** (e.g., `https://my-api.example.com`)
+4. Note the Identifier - this is your `Audience`
+
+### Configure appsettings.json
+
+```json
+{
+  "Auth0": {
+    "Domain": "your-tenant.auth0.com",
+    "Audience": "https://my-api.example.com"
+  }
+}
+```
+
+**Important:** Domain format is `your-tenant.auth0.com` - do NOT include `https://`.
+
+### Get Auth0 Configuration
+
+- **Domain:** Auth0 Dashboard → Settings → Domain (or `auth0 tenants list`)
+- **Audience:** The identifier you set when creating the API resource
+
+### Using Environment Variables
+
+For production/containers, set environment variables (these override appsettings.json):
+
+```bash
+export Auth0__Domain=your-tenant.auth0.com
+export Auth0__Audience=https://my-api.example.com
+```
+
+Note the double underscore `__` separator for nested config in environment variables.
+
+---
+
+## Getting a Test Token
+
+### Via Auth0 Dashboard
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Select your API
+3. Click the **Test** tab
+4. Click **Copy Token** to get a test access token
+
+### Via Auth0 CLI (Client Credentials)
+
+```bash
+# Get access token for testing
+auth0 test token \
+  --audience https://my-api.example.com
+```
+
+### Via curl (Client Credentials Flow)
+
+```bash
+curl -X POST https://your-tenant.auth0.com/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_id": "YOUR_CLIENT_ID",
+    "client_secret": "YOUR_CLIENT_SECRET",
+    "audience": "https://my-api.example.com",
+    "grant_type": "client_credentials"
+  }'
+```
+
+---
+
+## Troubleshooting
+
+**401 Unauthorized - "invalid_token":** Verify that the `Audience` in config exactly matches your API Identifier in Auth0 Dashboard.
+
+**401 Unauthorized - "invalid_issuer":** Ensure `Domain` does not include `https://` - use `your-tenant.auth0.com` format only.
+
+**HTTPS certificate errors locally:** Run `dotnet dev-certs https --trust` to trust the development certificate.
+
+**Token expired:** Test tokens from the Dashboard are short-lived. Request a fresh token.
+
+---
diff --git a/main/.mintlify/skills/auth0/references/framework-aspnetcore-auth/index.md b/main/.mintlify/skills/auth0/references/framework-aspnetcore-auth/index.md
new file mode 100644
index 0000000000..c06610cd7b
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-aspnetcore-auth/index.md
@@ -0,0 +1,1245 @@
+
+# Auth0 ASP.NET Core Web App Integration
+
+Add login, logout, and user profile to an ASP.NET Core MVC, Razor Pages, or Blazor Server application using `Auth0.AspNetCore.Authentication`.
+
+## Prerequisites
+
+- ASP.NET Core application (.NET 8 or higher)
+- Auth0 Regular Web Application configured (not an API - must be an Application)
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **ASP.NET Core Web APIs with JWT Bearer validation** - Use the ASP.NET Core Web API integration workflow for JWT-protected REST APIs
+- **Blazor WebAssembly** - Requires OIDC client-side auth; see the Auth0 Blazor WebAssembly quickstart
+- **Single Page Applications** - Use the Auth0 integration workflow for React, Vue, or Angular for client-side auth
+- **Next.js applications** - Use the Auth0 integration workflow for Next.js, which handles both client and server
+- **Python web apps** - Use the Auth0 integration workflow for Flask or see the Django quickstart
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+dotnet add package Auth0.AspNetCore.Authentication
+```
+
+### 2. Configure Credentials
+
+Add Auth0 settings to `appsettings.json`:
+
+```json
+{
+  "Auth0": {
+    "Domain": "your-tenant.us.auth0.com",
+    "ClientId": "your_client_id",
+    "ClientSecret": "your_client_secret"
+  }
+}
+```
+
+**For local development**, keep secrets out of source control - use `dotnet user-secrets` to avoid committing `ClientSecret`:
+
+```bash
+dotnet user-secrets set "Auth0:Domain" "your-tenant.us.auth0.com"
+dotnet user-secrets set "Auth0:ClientId" "your_client_id"
+dotnet user-secrets set "Auth0:ClientSecret" "your_client_secret"
+```
+
+`Auth0:Domain` is your tenant domain (without `https://`). `Auth0:ClientId` and `Auth0:ClientSecret` come from your Auth0 Application settings.
+
+### 3. Configure Auth0 Dashboard
+
+In your Auth0 Application settings:
+- **Allowed Callback URLs**: `http://localhost:5000/callback`
+- **Allowed Logout URLs**: `http://localhost:5000`
+- **Allowed Web Origins**: `http://localhost:5000`
+
+### 4. Register Auth0 in Program.cs
+
+```csharp
+using Auth0.AspNetCore.Authentication;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddAuth0WebAppAuthentication(options =>
+{
+    options.Domain = builder.Configuration["Auth0:Domain"];
+    options.ClientId = builder.Configuration["Auth0:ClientId"];
+    options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
+});
+
+builder.Services.AddControllersWithViews();
+
+var app = builder.Build();
+
+// Standard middleware...
+app.UseHttpsRedirection();
+app.UseStaticFiles();
+app.UseRouting();
+
+app.UseAuthentication();    // Must come before UseAuthorization
+app.UseAuthorization();     // Critical: order matters
+
+app.MapControllerRoute(
+    name: "default",
+    pattern: "{controller=Home}/{action=Index}/{id?}");
+
+app.Run();
+```
+
+**Critical:** `UseAuthentication()` must come before `UseAuthorization()`. Reversing these causes silent auth failures where protected routes are never challenged.
+
+### 5. Create AccountController
+
+```csharp
+using Auth0.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Authentication.Cookies;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+public class AccountController : Controller
+{
+    public async Task Login(string returnUrl = "/")
+    {
+        var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
+            .WithRedirectUri(returnUrl)
+            .Build();
+
+        await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
+    }
+
+    [Authorize]
+    public async Task Logout()
+    {
+        var authenticationProperties = new LogoutAuthenticationPropertiesBuilder()
+            .WithRedirectUri(Url.Action("Index", "Home"))
+            .Build();
+
+        await HttpContext.SignOutAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
+        await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
+    }
+
+    [Authorize]
+    public IActionResult Profile()
+    {
+        return View();
+    }
+}
+```
+
+`Login` does not need `[Authorize]` - it is the entry point for unauthenticated users. `Logout` requires `[Authorize]` to ensure the sign-out only fires for authenticated sessions. **Always call both `SignOutAsync` methods** - signing out of only the Auth0 scheme leaves a local cookie; signing out of only the cookie scheme skips the Auth0 logout URL.
+
+### 6. Create Profile View
+
+Create `Views/Account/Profile.cshtml`:
+
+```html
+@{
+    ViewData["Title"] = "User Profile";
+}
+
+<div class="row">
+    <div class="col-md-2">
+        <img src="@User.FindFirst(c => c.Type == "picture")?.Value"
+             alt="Profile picture" class="img-fluid rounded-circle" />
+    </div>
+    <div class="col-md-10">
+        <h3>@User.Identity.Name</h3>
+        <p><strong>Email:</strong>
+           @User.FindFirst(c => c.Type == System.Security.Claims.ClaimTypes.Email)?.Value</p>
+        <p><strong>User ID:</strong>
+           @User.FindFirst(c => c.Type == System.Security.Claims.ClaimTypes.NameIdentifier)?.Value</p>
+    </div>
+</div>
+
+<h4 class="mt-4">Claims</h4>
+<table class="table">
+    <thead><tr><th>Claim Type</th><th>Claim Value</th></tr></thead>
+    <tbody>
+        @foreach (var claim in User.Claims)
+        {
+            <tr><td>@claim.Type</td><td>@claim.Value</td></tr>
+        }
+    </tbody>
+</table>
+```
+
+### 7. Update Navigation (_Layout.cshtml)
+
+Add login/logout/profile links to your nav bar inside `_Layout.cshtml`:
+
+```html
+@if (User.Identity.IsAuthenticated)
+{
+    <li class="nav-item">
+        <a class="nav-link text-dark" asp-controller="Account" asp-action="Profile">@User.Identity.Name</a>
+    </li>
+    <li class="nav-item">
+        <a class="nav-link text-dark" asp-controller="Account" asp-action="Logout">Logout</a>
+    </li>
+}
+else
+{
+    <li class="nav-item">
+        <a class="nav-link text-dark" asp-controller="Account" asp-action="Login">Login</a>
+    </li>
+}
+```
+
+### 8. Test the App
+
+```bash
+dotnet run
+```
+
+Visit `http://localhost:5000` and click Login to start the Auth0 login flow.
+
+## Blazor Server Variant
+
+For Blazor Server apps, use Razor Pages as auth endpoints - Blazor components cannot perform the HTTP redirects required by OAuth challenges.
+
+### Additional Program.cs Setup
+
+```csharp
+using Auth0.AspNetCore.Authentication;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddAuth0WebAppAuthentication(options =>
+{
+    options.Domain = builder.Configuration["Auth0:Domain"];
+    options.ClientId = builder.Configuration["Auth0:ClientId"];
+    options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
+});
+
+builder.Services.AddRazorComponents()
+    .AddInteractiveServerComponents();
+
+builder.Services.AddCascadingAuthenticationState();  // Required for Blazor auth state
+builder.Services.AddRazorPages();                     // Required for auth endpoints
+
+var app = builder.Build();
+
+app.UseAuthentication();
+app.UseAuthorization();
+
+app.MapRazorPages();
+app.MapRazorComponents<App>()
+    .AddInteractiveServerRenderMode();
+
+app.Run();
+```
+
+### Login Razor Page (Pages/Login.cshtml.cs)
+
+```csharp
+using Auth0.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.RazorPages;
+
+public class LoginModel : PageModel
+{
+    public async Task OnGet(string returnUrl = "/")
+    {
+        var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
+            .WithRedirectUri(returnUrl)
+            .Build();
+
+        await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
+    }
+}
+```
+
+### Logout Razor Page (Pages/Logout.cshtml.cs)
+
+```csharp
+using Auth0.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Authentication.Cookies;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.RazorPages;
+
+public class LogoutModel : PageModel
+{
+    public async Task OnGet()
+    {
+        var authenticationProperties = new LogoutAuthenticationPropertiesBuilder()
+            .WithRedirectUri(Url.Content("~/"))
+            .Build();
+
+        await HttpContext.SignOutAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
+        await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
+    }
+}
+```
+
+### Profile Component (Components/Pages/Profile.razor)
+
+```razor
+@page "/profile"
+@attribute [Authorize]
+@using System.Security.Claims
+
+<h1>Profile</h1>
+
+<AuthorizeView>
+    <Authorized>
+        <div class="row">
+            <div class="col-2">
+                <img src="@context.User.FindFirst("picture")?.Value"
+                     alt="Profile" class="img-fluid rounded-circle" />
+            </div>
+            <div class="col-10">
+                <h3>@context.User.Identity?.Name</h3>
+                <p><strong>Email:</strong> @context.User.FindFirst(ClaimTypes.Email)?.Value</p>
+            </div>
+        </div>
+
+        <h4 class="mt-4">Claims</h4>
+        <table class="table">
+            <thead><tr><th>Type</th><th>Value</th></tr></thead>
+            <tbody>
+                @foreach (var claim in context.User.Claims)
+                {
+                    <tr><td>@claim.Type</td><td>@claim.Value</td></tr>
+                }
+            </tbody>
+        </table>
+    </Authorized>
+</AuthorizeView>
+```
+
+### Update MainLayout.razor Navigation
+
+```razor
+@using Microsoft.AspNetCore.Components.Authorization
+
+<AuthorizeView>
+    <Authorized>
+        <a href="/profile">@context.User.Identity?.Name</a>
+        <a href="/Logout">Logout</a>
+    </Authorized>
+    <NotAuthorized>
+        <a href="/Login">Login</a>
+    </NotAuthorized>
+</AuthorizeView>
+```
+
+### Routes.razor
+
+Wrap the `Router` in `CascadingAuthenticationState` to enable authorization throughout the component tree:
+
+```razor
+<CascadingAuthenticationState>
+    <Router AppAssembly="typeof(Program).Assembly">
+        <Found Context="routeData">
+            <AuthorizeRouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)" />
+            <FocusOnNavigate RouteData="routeData" Selector="h1" />
+        </Found>
+    </Router>
+</CascadingAuthenticationState>
+```
+
+## Razor Pages Variant
+
+For Razor Pages apps (without Blazor), use `AddRazorPages()` instead of `AddControllersWithViews()` in `Program.cs`. Auth endpoints are the same Login/Logout page models shown in the Blazor Server section. Replace navigation in `_Layout.cshtml` using the same `User.Identity.IsAuthenticated` check shown in the MVC section.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Hardcoding `Domain`, `ClientId`, or `ClientSecret` in source | Read from configuration - use `builder.Configuration["Auth0:Domain"]`; never embed credentials |
+| Committing `ClientSecret` to source control | Use `dotnet user-secrets` or environment variables for the client secret - never commit it |
+| `UseAuthorization()` before `UseAuthentication()` | Must call `UseAuthentication()` first - wrong order causes auth to never fire |
+| Signing out of only one scheme | Always call both `SignOutAsync(Auth0Constants.AuthenticationScheme)` and `SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme)` |
+| Adding `[Authorize]` to the `Login` action | `Login` must be accessible to unauthenticated users - only apply `[Authorize]` to `Logout` and `Profile` |
+| Not configuring Callback URLs in Auth0 Dashboard | Must add `http://localhost:5000/callback` to Allowed Callback URLs |
+| Passing `Domain` with `https://` prefix | `Domain` should be the bare domain, e.g., `my-tenant.us.auth0.com`, not `https://my-tenant.us.auth0.com` |
+| Not adding `AddCascadingAuthenticationState()` in Blazor | Required for Blazor Server - without it, `AuthorizeView` and `[Authorize]` attributes have no auth context |
+| Using Blazor components for login/logout redirects | Blazor components cannot perform HTTP redirects - use Razor Pages (`/Login`, `/Logout`) for auth endpoints |
+| Not adding `AddRazorPages()` and `MapRazorPages()` in Blazor | Login and Logout Razor Pages won't be routed without these registrations |
+| Using `Auth0.AspNetCore.Authentication.Api` for web apps | That package is for JWT-protected APIs - use `Auth0.AspNetCore.Authentication` for session-based web apps |
+| Using `AddJwtBearer` instead of `AddAuth0WebAppAuthentication` | `AddJwtBearer` is for stateless API auth - session-based web apps require `AddAuth0WebAppAuthentication` |
+| Not creating `Views/Account/` directory for Profile view | MVC requires the directory to exist before creating the view |
+
+## Key SDK Methods
+
+| Method/Property | Usage | Purpose |
+|-----------------|-------|---------|
+| `AddAuth0WebAppAuthentication` | `builder.Services.AddAuth0WebAppAuthentication(options => { ... })` | Registers Auth0 cookie-based authentication |
+| `LoginAuthenticationPropertiesBuilder` | `new LoginAuthenticationPropertiesBuilder().WithRedirectUri(url).Build()` | Builds properties for the login challenge |
+| `LogoutAuthenticationPropertiesBuilder` | `new LogoutAuthenticationPropertiesBuilder().WithRedirectUri(url).Build()` | Builds properties for the logout redirect |
+| `ChallengeAsync` | `await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, props)` | Initiates the Auth0 Universal Login redirect |
+| `SignOutAsync` (Auth0) | `await HttpContext.SignOutAsync(Auth0Constants.AuthenticationScheme, props)` | Signs out of Auth0 and redirects to logout URL |
+| `SignOutAsync` (Cookie) | `await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme)` | Clears the local session cookie |
+| `User.FindFirst` | `User.FindFirst(c => c.Type == "picture")?.Value` | Accesses individual user claims in controllers/views |
+| `User.Identity.IsAuthenticated` | `@if (User.Identity.IsAuthenticated)` | Checks authentication state in views/layouts |
+| `[Authorize]` | `[Authorize]` attribute on controller action or Razor component | Protects routes requiring authentication |
+| `AddCascadingAuthenticationState` | `builder.Services.AddCascadingAuthenticationState()` | Required for Blazor Server auth state propagation |
+
+## Related Workflows
+
+- ASP.NET Core Web APIs with JWT Bearer token validation → ask for the ASP.NET Core Web API integration
+- Server-rendered Express web apps with login/logout sessions → ask for the Express integration
+- Flask web applications with session-based auth → ask for the Flask integration
+
+## Quick Reference
+
+**SDK registration:**
+```csharp
+builder.Services.AddAuth0WebAppAuthentication(options =>
+{
+    options.Domain = builder.Configuration["Auth0:Domain"];        // required
+    options.ClientId = builder.Configuration["Auth0:ClientId"];    // required
+    options.ClientSecret = builder.Configuration["Auth0:ClientSecret"]; // required
+});
+```
+
+**Login action:**
+```csharp
+var props = new LoginAuthenticationPropertiesBuilder().WithRedirectUri(returnUrl).Build();
+await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, props);
+```
+
+**Logout action (always call both):**
+```csharp
+var props = new LogoutAuthenticationPropertiesBuilder().WithRedirectUri(Url.Action("Index", "Home")).Build();
+await HttpContext.SignOutAsync(Auth0Constants.AuthenticationScheme, props);
+await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
+```
+
+**Route protection:**
+```csharp
+[Authorize]
+public IActionResult Profile() { return View(); }
+```
+
+**appsettings.json configuration keys:**
+- `Auth0:Domain` - Auth0 tenant domain (e.g., `tenant.us.auth0.com`)
+- `Auth0:ClientId` - Application client ID
+- `Auth0:ClientSecret` - Application client secret (use user-secrets in development)
+
+## References
+
+- [Auth0.AspNetCore.Authentication on NuGet](https://www.nuget.org/packages/Auth0.AspNetCore.Authentication)
+- [Auth0 ASP.NET Core MVC Quickstart](https://auth0.com/docs/quickstart/webapp/aspnet-core)
+- [Auth0 ASP.NET Core Blazor Server Quickstart](https://auth0.com/docs/quickstart/webapp/aspnet-core-blazor-server)
+- [ASP.NET Core Documentation](https://learn.microsoft.com/en-us/aspnet/core)
+
+---
+
+# Auth0 ASP.NET Core Authentication API Reference
+
+Complete configuration and API reference for ASP.NET Core web application authentication.
+
+---
+
+## AddAuth0WebAppAuthentication Configuration
+
+### Complete Configuration Options
+
+```csharp
+using Auth0.AspNetCore.Authentication;
+
+builder.Services.AddAuth0WebAppAuthentication(options =>
+{
+    options.Domain = builder.Configuration["Auth0:Domain"];         // required: tenant domain (without https://)
+    options.ClientId = builder.Configuration["Auth0:ClientId"];     // required: app client ID
+    options.ClientSecret = builder.Configuration["Auth0:ClientSecret"]; // required: app client secret
+    options.CallbackPath = "/callback";                             // optional: defaults to /callback
+    options.Backchannel = null;                                     // optional: custom HttpClient
+    options.MaxAge = TimeSpan.FromDays(1);                          // optional: max auth age
+    options.LoginParameters = new Dictionary<string, string>        // optional: extra OIDC params
+    {
+        { "audience", "https://your-api-identifier" }
+    };
+    options.Scope = "openid profile email";                         // optional: scopes to request
+    options.ResponseType = "code";                                  // optional: default is "code"
+    options.UsePkce = true;                                         // optional: default is true
+    options.SkipCookieMiddleware = false;                           // optional: skip automatic cookie middleware
+})
+.WithAccessToken(tokenOptions =>
+{
+    tokenOptions.Audience = "https://your-api-identifier";          // required for API calls
+    tokenOptions.UseRefreshTokens = true;                           // optional: enable refresh tokens
+});
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `Domain` | Yes | Auth0 tenant domain (e.g., `tenant.us.auth0.com`) - without `https://` |
+| `ClientId` | Yes | Application client ID from Auth0 Dashboard |
+| `ClientSecret` | Yes | Application client secret from Auth0 Dashboard |
+| `CallbackPath` | No | OAuth callback path - defaults to `/callback` |
+| `Scope` | No | OIDC scopes - defaults to `openid profile email` |
+| `LoginParameters` | No | Additional OIDC authorization parameters |
+| `UsePkce` | No | PKCE code challenge - defaults to `true` (recommended) |
+
+---
+
+## LoginAuthenticationPropertiesBuilder
+
+Fluent builder for constructing authentication properties used in the login challenge.
+
+```csharp
+var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
+    .WithRedirectUri("/dashboard")                 // redirect after login
+    .WithParameter("screen_hint", "signup")        // Auth0 Universal Login hint
+    .WithParameter("connection", "google-oauth2")  // force specific connection
+    .WithParameter("ui_locales", "es")             // locale
+    .Build();
+
+await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
+```
+
+| Method | Description |
+|--------|-------------|
+| `.WithRedirectUri(uri)` | Post-login redirect URL |
+| `.WithParameter(key, value)` | Arbitrary OIDC authorization parameter |
+| `.WithOrganization(orgId)` | Auth0 Organizations support |
+| `.WithInvitation(invitationId)` | Organization invitation flow |
+| `.Build()` | Returns the configured `AuthenticationProperties` |
+
+---
+
+## LogoutAuthenticationPropertiesBuilder
+
+Fluent builder for constructing authentication properties used in the logout flow.
+
+```csharp
+var authenticationProperties = new LogoutAuthenticationPropertiesBuilder()
+    .WithRedirectUri(Url.Action("Index", "Home"))  // post-logout redirect
+    .Build();
+
+await HttpContext.SignOutAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
+await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
+```
+
+| Method | Description |
+|--------|-------------|
+| `.WithRedirectUri(uri)` | Post-logout redirect URL |
+| `.Build()` | Returns the configured `AuthenticationProperties` |
+
+**Always call both `SignOutAsync` methods.** Calling only `Auth0Constants.AuthenticationScheme` signs out of Auth0 but leaves the local cookie intact. Calling only `CookieAuthenticationDefaults.AuthenticationScheme` clears the cookie but skips the Auth0 logout endpoint.
+
+---
+
+## WithAccessToken Options
+
+Configure token storage for API calls via the `.WithAccessToken()` extension:
+
+```csharp
+builder.Services.AddAuth0WebAppAuthentication(options =>
+{
+    options.Domain = builder.Configuration["Auth0:Domain"];
+    options.ClientId = builder.Configuration["Auth0:ClientId"];
+    options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
+})
+.WithAccessToken(tokenOptions =>
+{
+    tokenOptions.Audience = builder.Configuration["Auth0:Audience"]; // required for API calls
+    tokenOptions.UseRefreshTokens = true;                            // enable refresh token rotation
+    tokenOptions.Events = new Auth0WebAppWithAccessTokenEvents       // optional event hooks
+    {
+        OnMissingRefreshToken = async (context) =>
+        {
+            await context.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
+            context.Response.Redirect("/login");
+        }
+    };
+});
+```
+
+Retrieve the access token in controllers:
+
+```csharp
+var accessToken = await HttpContext.GetTokenAsync("access_token");
+```
+
+---
+
+## Claims Reference
+
+After login, user claims are available via `User.FindFirst()` or `HttpContext.User.FindFirst()`.
+
+| Claim Type | Value | Access Pattern |
+|------------|-------|----------------|
+| `sub` | Auth0 user ID (e.g., `google-oauth2\|123456`) | `User.FindFirst(ClaimTypes.NameIdentifier)?.Value` |
+| `name` | Display name | `User.Identity.Name` |
+| `email` | Email address | `User.FindFirst(ClaimTypes.Email)?.Value` |
+| `picture` | Avatar URL | `User.FindFirst(c => c.Type == "picture")?.Value` |
+| `email_verified` | Boolean string | `User.FindFirst(c => c.Type == "email_verified")?.Value` |
+| `nickname` | Username/nickname | `User.FindFirst(c => c.Type == "nickname")?.Value` |
+| `updated_at` | Last profile update | `User.FindFirst(c => c.Type == "updated_at")?.Value` |
+
+**Note:** Standard claims like `email` are mapped to `ClaimTypes.Email` by ASP.NET Core's OIDC middleware. Custom claims added via Auth0 Rules or Actions are available by their exact type string.
+
+---
+
+## Cookie Configuration
+
+The SDK uses ASP.NET Core's cookie authentication middleware by default. Cookie behavior is configurable:
+
+```csharp
+builder.Services.AddAuth0WebAppAuthentication(options =>
+{
+    options.Domain = builder.Configuration["Auth0:Domain"];
+    options.ClientId = builder.Configuration["Auth0:ClientId"];
+    options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
+    options.SkipCookieMiddleware = true; // take control of cookie middleware yourself
+});
+
+// Configure cookie manually when SkipCookieMiddleware = true
+builder.Services.AddAuthentication()
+    .AddCookie(options =>
+    {
+        options.Cookie.SecurePolicy = CookieSecurePolicy.Always;     // HTTPS only in production
+        options.Cookie.HttpOnly = true;                               // no JS access
+        options.Cookie.SameSite = SameSiteMode.Lax;                  // CSRF protection
+        options.SlidingExpiration = true;
+        options.ExpireTimeSpan = TimeSpan.FromHours(1);
+    });
+```
+
+---
+
+## Middleware Configuration
+
+```csharp
+var app = builder.Build();
+
+app.UseHttpsRedirection();
+app.UseStaticFiles();
+app.UseRouting();
+
+app.UseAuthentication();    // MUST come before UseAuthorization
+app.UseAuthorization();     // Checks [Authorize] attributes
+
+app.MapControllerRoute(
+    name: "default",
+    pattern: "{controller=Home}/{action=Index}/{id?}");
+
+app.Run();
+```
+
+Middleware order is critical:
+1. `UseRouting()` - before auth middleware so route information is available
+2. `UseAuthentication()` - reads the cookie and sets `HttpContext.User`
+3. `UseAuthorization()` - enforces `[Authorize]` policies using the populated `HttpContext.User`
+
+---
+
+## Auth0Constants
+
+```csharp
+Auth0Constants.AuthenticationScheme  // = "Auth0"
+```
+
+Use this constant instead of the string `"Auth0"` to avoid typos.
+
+---
+
+## Testing
+
+### Local Testing
+
+1. Configure `appsettings.json` or user-secrets with your Auth0 credentials
+2. Start your app: `dotnet run`
+3. Visit `http://localhost:5000/Account/Login`
+4. Complete the Auth0 Universal Login flow
+5. Verify redirect back to app and claims accessible on profile page
+6. Click logout and verify both cookies are cleared
+
+---
+
+## References
+
+- [Auth0.AspNetCore.Authentication on NuGet](https://www.nuget.org/packages/Auth0.AspNetCore.Authentication)
+- [Auth0.AspNetCore.Authentication GitHub](https://github.com/auth0/auth0-aspnetcore-authentication)
+- [ASP.NET Core Authentication Documentation](https://learn.microsoft.com/en-us/aspnet/core/security/authentication)
+
+---
+
+---
+
+# Auth0 ASP.NET Core Integration Patterns
+
+Server-side authentication patterns for ASP.NET Core MVC, Razor Pages, and Blazor Server.
+
+---
+
+## Protected Routes
+
+### Using [Authorize] Attribute on Controller Actions
+
+```csharp
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+public class DashboardController : Controller
+{
+    [Authorize]
+    public IActionResult Index()
+    {
+        var userName = User.Identity.Name;
+        return View("Index", userName);
+    }
+}
+```
+
+### Using [Authorize] on an Entire Controller
+
+```csharp
+[Authorize]
+public class AdminController : Controller
+{
+    public IActionResult Dashboard()
+    {
+        return View();
+    }
+
+    public IActionResult Settings()
+    {
+        return View();
+    }
+}
+```
+
+### Manual Check in Action
+
+```csharp
+public IActionResult Dashboard()
+{
+    if (!User.Identity.IsAuthenticated)
+    {
+        return RedirectToAction("Login", "Account");
+    }
+    return View();
+}
+```
+
+### Policy-Based Authorization
+
+```csharp
+// Register policy in Program.cs
+builder.Services.AddAuthorization(options =>
+{
+    options.AddPolicy("RequireEmail", policy =>
+        policy.RequireClaim(System.Security.Claims.ClaimTypes.Email));
+});
+
+// Apply to action
+[Authorize(Policy = "RequireEmail")]
+public IActionResult AdminOnly()
+{
+    return View();
+}
+```
+
+### Razor Pages Protection
+
+```csharp
+// Program.cs - protect all Razor Pages under /Admin
+builder.Services.AddRazorPages(options =>
+{
+    options.Conventions.AuthorizeFolder("/Admin");
+    options.Conventions.AllowAnonymousToPage("/Admin/Login");
+});
+```
+
+---
+
+## Calling External APIs
+
+### Get Access Token in Controller
+
+```csharp
+using Microsoft.AspNetCore.Authentication;
+
+public class ApiController : Controller
+{
+    private readonly IHttpClientFactory _httpClientFactory;
+
+    public ApiController(IHttpClientFactory httpClientFactory)
+    {
+        _httpClientFactory = httpClientFactory;
+    }
+
+    [Authorize]
+    public async Task<IActionResult> CallApi()
+    {
+        var accessToken = await HttpContext.GetTokenAsync("access_token");
+        if (string.IsNullOrEmpty(accessToken))
+        {
+            return Unauthorized("No access token available");
+        }
+
+        var client = _httpClientFactory.CreateClient();
+        client.DefaultRequestHeaders.Authorization =
+            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);
+
+        var response = await client.GetAsync("https://api.example.com/data");
+        var content = await response.Content.ReadAsStringAsync();
+
+        return Ok(content);
+    }
+}
+```
+
+### Configure Audience for API Calls
+
+Update `Program.cs` to request an access token for a specific audience:
+
+```csharp
+builder.Services.AddAuth0WebAppAuthentication(options =>
+{
+    options.Domain = builder.Configuration["Auth0:Domain"];
+    options.ClientId = builder.Configuration["Auth0:ClientId"];
+    options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
+})
+.WithAccessToken(options =>
+{
+    options.Audience = builder.Configuration["Auth0:Audience"]; // e.g., https://your-api-identifier
+    options.UseRefreshTokens = true;
+});
+```
+
+Add the audience to `appsettings.json`:
+
+```json
+{
+  "Auth0": {
+    "Domain": "your-tenant.us.auth0.com",
+    "ClientId": "your_client_id",
+    "Audience": "https://your-api-identifier"
+  }
+}
+```
+
+> Store `ClientSecret` in user-secrets (`dotnet user-secrets set "Auth0:ClientSecret" "your_client_secret"`) or environment variables — never commit secrets to source control.
+
+---
+
+## Custom Login Options
+
+### Force a Specific Connection
+
+```csharp
+public async Task LoginWithGoogle(string returnUrl = "/")
+{
+    var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
+        .WithRedirectUri(returnUrl)
+        .WithParameter("connection", "google-oauth2")
+        .Build();
+
+    await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
+}
+```
+
+### Prompt for Signup
+
+```csharp
+public async Task Signup(string returnUrl = "/")
+{
+    var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
+        .WithRedirectUri(returnUrl)
+        .WithParameter("screen_hint", "signup")
+        .Build();
+
+    await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
+}
+```
+
+### Custom Logout Return URL
+
+```csharp
+[Authorize]
+public async Task LogoutToGoodbye()
+{
+    var authenticationProperties = new LogoutAuthenticationPropertiesBuilder()
+        .WithRedirectUri(Url.Action("Goodbye", "Home"))
+        .Build();
+
+    await HttpContext.SignOutAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
+    await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
+}
+```
+
+---
+
+## Accessing User Information
+
+### In Controllers
+
+```csharp
+[Authorize]
+public IActionResult Profile()
+{
+    var name = User.Identity.Name;
+    var email = User.FindFirst(System.Security.Claims.ClaimTypes.Email)?.Value;
+    var picture = User.FindFirst(c => c.Type == "picture")?.Value;
+    var userId = User.FindFirst(System.Security.Claims.ClaimTypes.NameIdentifier)?.Value;
+
+    var model = new ProfileViewModel
+    {
+        Name = name,
+        Email = email,
+        Picture = picture,
+        UserId = userId,
+        Claims = User.Claims.ToList()
+    };
+
+    return View(model);
+}
+```
+
+### In Views (Razor)
+
+```html
+@if (User.Identity.IsAuthenticated)
+{
+    <p>Welcome, @User.Identity.Name!</p>
+    <img src='@User.FindFirst(c => c.Type == "picture")?.Value' alt="Profile" />
+}
+```
+
+### In Blazor Components
+
+```razor
+@using Microsoft.AspNetCore.Components.Authorization
+@inject AuthenticationStateProvider AuthStateProvider
+
+<AuthorizeView>
+    <Authorized>
+        <p>Welcome, @context.User.Identity?.Name!</p>
+        <img src='@context.User.FindFirst("picture")?.Value' alt="Profile" />
+    </Authorized>
+    <NotAuthorized>
+        <p>Please <a href="/Login">log in</a>.</p>
+    </NotAuthorized>
+</AuthorizeView>
+```
+
+---
+
+## Injecting User into All Views
+
+Use a base controller or view imports to make the user available everywhere:
+
+```csharp
+// BaseController.cs
+public abstract class BaseController : Controller
+{
+    protected string CurrentUserName => User.Identity.Name ?? "Guest";
+    protected bool IsAuthenticated => User.Identity.IsAuthenticated;
+}
+
+// DashboardController.cs
+public class DashboardController : BaseController
+{
+    [Authorize]
+    public IActionResult Index()
+    {
+        ViewBag.UserName = CurrentUserName;
+        return View();
+    }
+}
+```
+
+Or use `ViewData` in `_ViewStart.cshtml` via a filter:
+
+```csharp
+// AuthUserFilter.cs - inject user into all views automatically
+public class AuthUserFilter : IActionFilter
+{
+    public void OnActionExecuting(ActionExecutingContext context)
+    {
+        if (context.Controller is Controller controller)
+        {
+            controller.ViewData["CurrentUser"] = controller.User.Identity.Name;
+        }
+    }
+
+    public void OnActionExecuted(ActionExecutedContext context) { }
+}
+
+// Program.cs
+builder.Services.AddControllersWithViews(options =>
+{
+    options.Filters.Add<AuthUserFilter>();
+});
+```
+
+---
+
+## Error Handling
+
+### Global Unauthorized Redirect
+
+```csharp
+// Program.cs - redirect 401/403 to login page
+app.UseStatusCodePages(async statusCodeContext =>
+{
+    var response = statusCodeContext.HttpContext.Response;
+    if (response.StatusCode == 401)
+    {
+        response.Redirect("/Account/Login");
+    }
+    else if (response.StatusCode == 403)
+    {
+        response.Redirect("/Home/AccessDenied");
+    }
+});
+```
+
+### Handling Token Expiry (with .WithAccessToken)
+
+```csharp
+.WithAccessToken(options =>
+{
+    options.Audience = builder.Configuration["Auth0:Audience"];
+    options.UseRefreshTokens = true;
+    options.Events = new Auth0WebAppWithAccessTokenEvents
+    {
+        OnMissingRefreshToken = async (context) =>
+        {
+            // Refresh token missing - force re-login
+            await context.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
+            context.Response.Redirect("/Account/Login");
+        }
+    };
+});
+```
+
+---
+
+## Blazor Server: Auth in Components
+
+### AuthorizeView Component
+
+```razor
+<AuthorizeView>
+    <Authorized>
+        <!-- Only shown to authenticated users -->
+        <p>Welcome, @context.User.Identity?.Name!</p>
+    </Authorized>
+    <NotAuthorized>
+        <!-- Only shown to unauthenticated users -->
+        <a href="/Login">Please log in</a>
+    </NotAuthorized>
+    <Authorizing>
+        <!-- Shown while auth state is loading -->
+        <p>Loading...</p>
+    </Authorizing>
+</AuthorizeView>
+```
+
+### Programmatic Auth State in Blazor
+
+```razor
+@inject AuthenticationStateProvider AuthStateProvider
+
+@code {
+    private bool isAuthenticated;
+    private string userName = "";
+
+    protected override async Task OnInitializedAsync()
+    {
+        var authState = await AuthStateProvider.GetAuthenticationStateAsync();
+        var user = authState.User;
+        isAuthenticated = user.Identity?.IsAuthenticated ?? false;
+        userName = user.Identity?.Name ?? "";
+    }
+}
+```
+
+---
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "Callback URL mismatch" | Ensure the callback URL in Auth0 Dashboard matches exactly (include both `http://localhost:5000/callback` and `https://localhost:{HTTPS_PORT}/callback` — check `Properties/launchSettings.json` for the actual port) |
+| User not authenticated after login | Verify `UseAuthentication()` is before `UseAuthorization()` in `Program.cs` |
+| Claims are `null` or missing | Check `Scope` includes `openid profile email` in configuration |
+| Access token is empty | Configure `.WithAccessToken()` with `Audience` in `Program.cs` |
+| Blazor `[Authorize]` not working | Add `AddCascadingAuthenticationState()` and `AddRazorPages()` to `Program.cs` |
+| Redirect loop on login | Verify `Login` action does not have `[Authorize]` attribute |
+| Logout does not end Auth0 session | Must call `SignOutAsync(Auth0Constants.AuthenticationScheme)` - calling only the cookie scheme skips Auth0 |
+
+---
+
+---
+
+# Auth0 ASP.NET Core Setup Guide
+
+Setup instructions for ASP.NET Core MVC, Razor Pages, and Blazor Server applications.
+
+---
+
+## Quick Setup (Automated)
+
+Below automates the setup, except for the `ClientSecret`. Inform the user that they have to fill in the value for `ClientSecret` themselves.
+
+**Never read the contents of `appsettings.json`, `appsettings.Development.json`, or user-secrets at any point during setup.** These files may contain sensitive secrets that should not be exposed in the LLM context. If you determine you need to read the file for any reason, ask the user for explicit permission before doing so — do not proceed until the user confirms.
+
+**Before running any part of this setup that writes to a config file, you MUST ask the user for explicit confirmation.** Follow the steps below precisely.
+
+### Step 1: Check for existing config files and confirm with user
+
+Before writing credentials, check which config files exist:
+
+```bash
+test -f appsettings.Development.json && echo "DEV_SETTINGS_EXISTS" || echo "DEV_SETTINGS_NOT_FOUND"
+test -f appsettings.json && echo "SETTINGS_EXISTS" || echo "SETTINGS_NOT_FOUND"
+```
+
+Then ask the user for explicit confirmation before proceeding — do not continue until the user confirms:
+
+- If `appsettings.Development.json` exists, ask:
+  - Question: "An `appsettings.Development.json` file already exists and may contain settings unrelated to Auth0. This setup will append Auth0 credentials to it without modifying existing content. Do you want to proceed?"
+  - Options: "Yes, append to existing appsettings.Development.json" / "No, I'll update it manually"
+
+- If `appsettings.Development.json` does **not** exist but `appsettings.json` exists, ask:
+  - Question: "An `appsettings.json` file already exists. This setup will add the Auth0 section to it. Would you prefer to use `dotnet user-secrets` to keep the ClientSecret out of source control?"
+  - Options: "Yes, use user-secrets" / "Yes, write to appsettings.json" / "No, I'll configure it manually"
+
+- If neither exists, ask:
+  - Question: "This setup will create an `appsettings.json` file containing Auth0 settings (Domain, ClientId) and a placeholder for ClientSecret. Do you want to proceed?"
+  - Options: "Yes, create appsettings.json" / "No, I'll configure it manually"
+
+**Do not proceed with writing to any config file unless the user selects the confirmation option.**
+
+### Step 2: Run automated setup (only after confirmation)
+
+```bash
+#!/bin/bash
+
+# Install Auth0 CLI
+if ! command -v auth0 &> /dev/null; then
+  [[ "$OSTYPE" == "darwin"* ]] && brew install auth0/auth0-cli/auth0 || \
+  curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b /usr/local/bin
+fi
+
+# Login
+auth0 login 2>/dev/null || auth0 login
+
+# Create/select app
+auth0 apps list
+read -p "Enter app ID (or Enter to create): " APP_ID
+
+if [ -z "$APP_ID" ]; then
+  APP_ID=$(auth0 apps create --name "${PWD##*/}-aspnetcore" --type regular \
+    --callbacks "http://localhost:5000/callback,https://localhost:7000/callback" \
+    --logout-urls "http://localhost:5000,https://localhost:7000" \
+    --metadata "created_by=agent_skills" \
+    --json-compact | jq -r '.client_id')
+fi
+
+# Get credentials
+DOMAIN=$(auth0 apps show "$APP_ID" --json-compact | jq -r '.domain')
+CLIENT_ID=$(auth0 apps show "$APP_ID" --json-compact | jq -r '.client_id')
+
+echo "Auth0 Domain: $DOMAIN"
+echo "Auth0 Client ID: $CLIENT_ID"
+echo ""
+echo "Add these to your appsettings.json or use dotnet user-secrets:"
+echo ""
+echo "  dotnet user-secrets set \"Auth0:Domain\" \"$DOMAIN\""
+echo "  dotnet user-secrets set \"Auth0:ClientId\" \"$CLIENT_ID\""
+echo "  dotnet user-secrets set \"Auth0:ClientSecret\" \"YOUR_CLIENT_SECRET\""
+```
+
+After the script runs, remind the user to:
+1. Replace `YOUR_CLIENT_SECRET` with the actual client secret from Auth0.
+2. For production, use environment variables or a secrets manager — never commit the client secret to source control.
+3. Verify the HTTPS port in `Properties/launchSettings.json` and update the Auth0 callback/logout URLs if needed (ASP.NET Core assigns random HTTPS ports in the 7000-7300 range).
+
+---
+
+## Manual Setup
+
+### Install Package
+
+```bash
+dotnet add package Auth0.AspNetCore.Authentication
+```
+
+### Configure appsettings.json
+
+Add the `Auth0` section:
+
+```json
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*",
+  "Auth0": {
+    "Domain": "your-tenant.us.auth0.com",
+    "ClientId": "your-client-id",
+    "ClientSecret": "your-client-secret"
+  }
+}
+```
+
+**For local development**, use `dotnet user-secrets` to keep the client secret out of source control:
+
+```bash
+dotnet user-secrets init
+dotnet user-secrets set "Auth0:Domain" "your-tenant.us.auth0.com"
+dotnet user-secrets set "Auth0:ClientId" "your-client-id"
+dotnet user-secrets set "Auth0:ClientSecret" "your-client-secret"
+```
+
+User secrets override `appsettings.json` in the Development environment. In production, use environment variables:
+
+```bash
+export Auth0__Domain="your-tenant.us.auth0.com"
+export Auth0__ClientId="your-client-id"
+export Auth0__ClientSecret="your-client-secret"
+```
+
+Note: Environment variable names use double underscores (`__`) to represent the `:` separator in .NET configuration keys.
+
+### Get Auth0 Credentials
+
+CLI: `auth0 apps show <app-id> --reveal-secrets`
+
+Dashboard: Create a Regular Web Application, then copy Domain, Client ID, and Client Secret from the Settings tab.
+
+### Configure Auth0 Dashboard
+
+In your Auth0 Application settings:
+- **Allowed Callback URLs**: `http://localhost:5000/callback, https://localhost:{HTTPS_PORT}/callback`
+- **Allowed Logout URLs**: `http://localhost:5000, https://localhost:{HTTPS_PORT}`
+- **Allowed Web Origins**: `http://localhost:5000, https://localhost:{HTTPS_PORT}`
+
+> Check `Properties/launchSettings.json` for your project's actual HTTPS port (ASP.NET Core assigns a random port in the 7000-7300 range).
+
+Application type must be **Regular Web Application** (not SPA or Native).
+
+---
+
+## Troubleshooting
+
+**"IDX20803: Unable to obtain configuration" error:** Verify `Auth0:Domain` is the bare domain (e.g., `your-tenant.us.auth0.com`) without `https://`. The SDK prepends the protocol automatically.
+
+**"Callback URL mismatch" error:** The Allowed Callback URLs in Auth0 Dashboard must exactly match your app's callback URL. Check for trailing slashes or http vs https mismatches.
+
+**Client secret required:** ASP.NET Core apps use Regular Web Application type — ensure the app was created as regular, not SPA or Native. SPA apps do not have client secrets.
+
+**Middleware order error (auth not working):** Ensure `app.UseAuthentication()` is called before `app.UseAuthorization()` in `Program.cs`.
+
+**User-secrets not loading:** User secrets only load in the `Development` environment (`ASPNETCORE_ENVIRONMENT=Development`). Verify the environment variable is set correctly.
+
+**SignOut not clearing session:** Ensure both `SignOutAsync(Auth0Constants.AuthenticationScheme)` and `SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme)` are called in the `Logout` action.
+
+---
diff --git a/main/.mintlify/skills/auth0/references/framework-expo/index.md b/main/.mintlify/skills/auth0/references/framework-expo/index.md
new file mode 100644
index 0000000000..8c1e3ad715
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-expo/index.md
@@ -0,0 +1,1247 @@
+
+# Auth0 Expo Integration
+
+Add authentication to Expo (React Native) applications using `react-native-auth0` with the Expo Config Plugin.
+
+## Prerequisites
+
+- Expo SDK 53 or higher (react-native-auth0 v5.x requires Expo 53+)
+- React 19 and React Native 0.78.0 or higher
+- Auth0 account with a **Native** application configured
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- **Not compatible with Expo Go** — requires custom development client or EAS Build
+
+## When NOT to Use
+
+| Use Case | Use Instead |
+|----------|------------------|
+| Bare React Native CLI project (no Expo) | the Auth0 integration workflow for React Native |
+| React web SPA (Vite/CRA) | the Auth0 integration workflow for React |
+| Next.js application | the Auth0 integration workflow for Next.js |
+| Vue.js SPA | the Auth0 integration workflow for Vue.js |
+| Angular SPA | the Auth0 integration workflow for Angular |
+| Express.js backend | the Auth0 integration workflow for Express.js |
+| Native Android (Kotlin/Java) | the Auth0 integration workflow for Android |
+| Backend API (JWT validation) | the Auth0 integration workflow for Fastify or Express.js |
+
+## Quick Start Workflow
+
+### 1. Configure Auth0
+
+**For automated setup with Auth0 CLI**, see the Setup Guide section (below) for complete scripts.
+
+**For manual setup**, configure a **Native** application in the [Auth0 Dashboard](https://manage.auth0.com/) and note your Domain and Client ID.
+
+### 2. Verify Expo Dev Client
+
+> **Agent instruction:** Before installing the Auth0 SDK, check if the project has `expo-dev-client` installed. Read the project's `package.json` and look for `expo-dev-client` in `dependencies` or `devDependencies`.
+>
+> - **If `expo-dev-client` is found:** Proceed to step 3.
+> - **If `expo-dev-client` is NOT found:** Use `AskUserQuestion` with the following message:
+>
+>   "The `react-native-auth0` SDK requires a custom Expo development client — it does **not** work with Expo Go. Your project does not have `expo-dev-client` installed.
+>
+>   How would you like to proceed?
+>   1. **Install it for me** — I'll run `npx expo install expo-dev-client` and continue setup
+>   2. **I'll set it up myself** — skip this step and continue to Auth0 SDK installation"
+>
+>   If the user picks option 1, run:
+>   ```bash
+>   npx expo install expo-dev-client
+>   ```
+>   Then proceed to step 3. If option 2, proceed to step 3 directly.
+
+### 3. Install SDK
+
+```bash
+npx expo install react-native-auth0
+```
+
+### 4. Configure Expo Config Plugin
+
+Add the react-native-auth0 plugin to `app.json` (or `app.config.js`) with your Auth0 domain and a custom scheme. Also ensure `bundleIdentifier` (iOS) and `package` (Android) are set:
+
+```json
+{
+  "expo": {
+    "ios": { "bundleIdentifier": "com.yourcompany.yourapp" },
+    "android": { "package": "com.yourcompany.yourapp" },
+    "plugins": [
+      ["react-native-auth0", {
+        "domain": "YOUR_AUTH0_DOMAIN",
+        "customScheme": "YOUR_CUSTOM_SCHEME"
+      }]
+    ]
+  }
+}
+```
+
+The `customScheme` must be all lowercase with no special characters (e.g., `auth0sample`). See the **Setup Guide** section (below) for HTTPS callbacks, multiple domains, EAS Build, and secret management.
+
+### 5. Configure Callback URLs
+
+Add to **Allowed Callback URLs** and **Allowed Logout URLs** in the [Auth0 Dashboard](https://manage.auth0.com/):
+
+```text
+YOUR_CUSTOM_SCHEME://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_ID/callback,
+YOUR_CUSTOM_SCHEME://YOUR_AUTH0_DOMAIN/android/YOUR_PACKAGE/callback
+```
+
+All values must be **lowercase** with **no trailing slash**. For HTTPS callback URLs (App Links / Universal Links), see the Setup Guide — Using HTTPS Callback URLs section (below).
+
+### 6. Add Authentication with Auth0Provider
+
+Wrap your app with `Auth0Provider` and use the `useAuth0` hook:
+
+> **Agent instruction:** Before adding new UI elements, search the project for existing click handlers for login, logout, sign-in, or sign-out buttons. If existing handlers are found, hook the Auth0 code into them. Only create new buttons if no existing handlers are found.
+
+```typescript
+import React from 'react';
+import { Auth0Provider, useAuth0 } from 'react-native-auth0';
+import { View, Button, Text, ActivityIndicator } from 'react-native';
+
+function HomeScreen() {
+  const { authorize, clearSession, user, isLoading, error } = useAuth0();
+
+  const login = async () => {
+    try {
+      await authorize(
+        { scope: 'openid profile email' },
+        { customScheme: 'YOUR_CUSTOM_SCHEME' }
+      );
+    } catch (e) {
+      console.error('Login error:', e);
+    }
+  };
+
+  const logout = async () => {
+    try {
+      await clearSession({ customScheme: 'YOUR_CUSTOM_SCHEME' });
+    } catch (e) {
+      console.error('Logout error:', e);
+    }
+  };
+
+  if (isLoading) {
+    return <ActivityIndicator size="large" />;
+  }
+
+  return (
+    <View>
+      {user ? (
+        <>
+          <Text>Welcome, {user.name}!</Text>
+          <Text>{user.email}</Text>
+          <Button title="Log Out" onPress={logout} />
+        </>
+      ) : (
+        <Button title="Log In" onPress={login} />
+      )}
+      {error && <Text>{error.message}</Text>}
+    </View>
+  );
+}
+
+export default function App() {
+  return (
+    <Auth0Provider
+      domain="YOUR_AUTH0_DOMAIN"
+      clientId="YOUR_AUTH0_CLIENT_ID"
+    >
+      <HomeScreen />
+    </Auth0Provider>
+  );
+}
+```
+
+### 7. Build & Verify
+
+> **Agent instruction:** After completing the integration, build the project to verify it compiles:
+> ```bash
+> npx expo prebuild --clean
+> npx expo run:ios
+> # or
+> npx expo run:android
+> ```
+> If the build fails, analyze the error output. Common integration build failures include:
+> - **"Invariant Violation: Native module cannot be null"**: Using Expo Go instead of a development build — run `npx expo run:ios` or `npx expo run:android` instead of `npx expo start`
+> - **Plugin not applied**: Missing `react-native-auth0` in app.json plugins array — verify the plugin configuration
+> - **Pod install fails (iOS)**: Run `npx expo prebuild --clean` to regenerate native projects
+> - **Manifest merge failure (Android)**: Conflicting auth0Domain placeholder — ensure only the config plugin sets the domain
+>
+> Re-run the build after each fix. Track the number of build-fix iterations.
+>
+> **Failcheck:** If the build still fails after 5–6 fix attempts, stop and ask the user using `AskUserQuestion`:
+> _"The build is still failing after several fix attempts. How would you like to proceed?"_
+> - **Let the skill continue fixing iteratively**
+> - **Fix it manually** — show the remaining errors
+> - **Skip build verification** — proceed without a successful build
+
+## Detailed Documentation
+
+- **Setup Guide** (see the Setup Guide section below) — Dev client requirement, automated setup, Expo config plugin, callback URLs, EAS Build, secret management
+- **Integration Patterns** (see the Integration Patterns section below) — Login/logout, credential management, biometric auth, token refresh, organizations, DPoP, error handling
+- **API Reference & Testing** (see the API Reference & Testing section below) — Configuration options, useAuth0 hook API, testing checklist, common issues, security
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using Expo Go instead of development build | react-native-auth0 requires native code. Use `npx expo run:ios` / `npx expo run:android` or create a development build with EAS. |
+| Missing `customScheme` in authorize/clearSession calls | Pass `{ customScheme: 'your-scheme' }` as the second argument to `authorize()` and `clearSession()`. Must match the value in app.json plugin config. |
+| Callback URL mismatch | Ensure callback URL is all lowercase, no trailing slash, and matches Auth0 Dashboard exactly: `{customScheme}://{domain}/ios/{bundleId}/callback` |
+| App type not set to Native | The Auth0 application must be type **Native** in the Dashboard, not SPA or Regular Web. |
+| Missing bundleIdentifier or package in app.json | Both `expo.ios.bundleIdentifier` and `expo.android.package` must be set in app.json for callback URLs to work. |
+| Forgot to wrap app with Auth0Provider | All components using `useAuth0()` must be children of `Auth0Provider`. |
+| Using react-native-auth0 v5.x with Expo < 53 | Version 5.x requires Expo 53+. Use v4.x for older Expo versions. |
+| Not testing on physical device | Biometric authentication (Face ID, fingerprint) only works on a physical device, not simulators. Always test the full auth flow on a real device before release. |
+
+## Related Capabilities
+
+- Auth0 setup — set up an account and application with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Bare React Native CLI projects → the Auth0 integration workflow for React Native
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- Managing Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+
+## References
+
+- [Auth0 Expo Quickstart](https://auth0.com/docs/quickstart/native/react-native-expo/interactive)
+- [react-native-auth0 GitHub Repository](https://github.com/auth0/react-native-auth0)
+- [react-native-auth0 API Documentation](https://auth0.github.io/react-native-auth0/)
+- [Expo Sample App](https://github.com/auth0-samples/auth0-react-native-sample/tree/master/00-Login-Expo)
+- [EXAMPLES.md](https://github.com/auth0/react-native-auth0/blob/master/EXAMPLES.md)
+
+---
+
+# auth0-expo API Reference & Testing
+
+## Table of Contents
+
+- [Configuration Reference](#configuration-reference) — Auth0Provider props, authorize/clearSession/getCredentials options
+- [Expo Config Plugin Reference](#expo-config-plugin-reference) — app.json plugin fields and auto-configuration
+- [User Profile Claims](#user-profile-claims) — Standard OIDC claims
+- [Credentials Object](#credentials-object) — Token properties
+- [Testing Checklist](#testing-checklist) — Dev build, platform-specific, Auth0 config, EAS
+- [Common Issues](#common-issues) — Error table with causes and solutions
+- [Security Considerations](#security-considerations) — PKCE, secure storage, custom scheme, tokens, network
+
+## Configuration Reference
+
+### Auth0Provider Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `domain` | `string` | Yes | Auth0 tenant domain (e.g., `your-tenant.auth0.com`) |
+| `clientId` | `string` | Yes | Auth0 application Client ID |
+| `localAuthenticationOptions` | `LocalAuthenticationOptions` | No | Biometric authentication configuration |
+| `maxRetries` | `number` | No | Credential renewal retry count (iOS only, default: 0) |
+| `useDPoP` | `boolean` | No | Enable DPoP token binding (default: true) |
+| `headers` | `Record<string, string>` | No | Custom headers for all API requests |
+
+### authorize() Options
+
+**First argument (parameters):**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `scope` | `string` | OAuth scopes (default: `openid profile email`) |
+| `audience` | `string` | API identifier for access token |
+| `organization` | `string` | Organization ID for enterprise login |
+| `invitationUrl` | `string` | Organization invitation URL |
+| `connection` | `string` | Force a specific connection (e.g., `google-oauth2`) |
+| `additionalParameters` | `object` | Extra parameters for the /authorize endpoint |
+
+**Second argument (options):**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `customScheme` | `string` | **Required for Expo.** URL scheme matching app.json plugin config. |
+
+### clearSession() Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `customScheme` | `string` | **Required for Expo.** Must match the scheme used in authorize(). |
+| `federated` | `boolean` | If true, also logs out from the identity provider |
+
+### getCredentials() Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `scope` | `string` | Minimum required scope |
+| `minTtl` | `number` | Minimum time-to-live in seconds for the access token |
+| `parameters` | `object` | Additional parameters |
+| `forceRefresh` | `boolean` | Force token refresh even if not expired |
+
+## Expo Config Plugin Reference
+
+### app.json Plugin Configuration
+
+```json
+["react-native-auth0", {
+  "domain": "your-tenant.auth0.com",
+  "customScheme": "auth0sample"
+}]
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `domain` | `string` | Yes | Auth0 tenant domain |
+| `customScheme` | `string` | No | Custom URL scheme (lowercase, no special chars). If `"https"`, enables Android App Links with `autoVerify`. |
+
+**What the plugin configures automatically:**
+- **iOS**: Adds URL scheme to Info.plist (`CFBundleURLSchemes`), adds deep linking handler to AppDelegate
+- **Android**: Sets `manifestPlaceholders` (`auth0Domain`, `auth0Scheme`) in build.gradle
+
+## User Profile Claims
+
+| Claim | Type | Description |
+|-------|------|-------------|
+| `sub` | `string` | Unique user identifier |
+| `name` | `string` | Full name |
+| `nickname` | `string` | Display name |
+| `email` | `string` | Email address |
+| `email_verified` | `boolean` | Whether email is verified |
+| `picture` | `string` | Profile picture URL |
+| `updated_at` | `string` | Last profile update timestamp |
+| `org_id` | `string` | Organization ID (if using Organizations) |
+
+## Credentials Object
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `accessToken` | `string` | Access token for API calls |
+| `idToken` | `string` | ID token with user claims |
+| `refreshToken` | `string` | Refresh token (if `offline_access` requested) |
+| `tokenType` | `string` | Token type (`Bearer` or `DPoP`) |
+| `expiresAt` | `number` | Token expiration timestamp |
+| `scope` | `string` | Granted scopes |
+
+## Testing Checklist
+
+### Development Build Testing
+
+- [ ] Login flow: Tap login → browser opens → complete login → app shows user info
+- [ ] Logout flow: Tap logout → session cleared → app shows login button
+- [ ] Credential persistence: Close app → reopen → user remains logged in
+- [ ] Token refresh: Wait for token expiry → `getCredentials()` returns fresh token
+- [ ] Error handling: Cancel login → app handles USER_CANCELLED gracefully
+- [ ] Loading state: `isLoading` is true until auth state is determined
+
+### Platform-Specific Testing
+
+- [ ] **iOS Simulator**: Login/logout works, URL scheme redirects correctly
+- [ ] **Android Emulator**: Login/logout works, custom scheme callback received
+- [ ] **Physical iOS Device**: Test on a real physical device — Face ID / Touch ID prompts work (if biometrics enabled). Note: biometric authentication is not available on simulators.
+- [ ] **Physical Android Device**: Test on a real physical device — fingerprint / PIN prompts work (if biometrics enabled). Test deep link redirection from browser back to app.
+
+### Auth0 Configuration Testing
+
+- [ ] Callback URL matches exactly (lowercase, no trailing slash)
+- [ ] Application type is **Native** in Auth0 Dashboard
+- [ ] Allowed Callback URLs include both iOS and Android URLs
+- [ ] Allowed Logout URLs include both iOS and Android URLs
+- [ ] OIDC Conformant toggle is enabled in Advanced OAuth settings
+
+### EAS Build Testing
+
+- [ ] Development build: `eas build --profile development` succeeds
+- [ ] Config plugin applied: Native files contain Auth0 configuration after prebuild
+- [ ] Production build: `eas build --profile production` succeeds
+
+## Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| "Invariant Violation: Native module cannot be null" | Using Expo Go instead of development build | Run `npx expo run:ios` or `npx expo run:android`, or create a development build with EAS |
+| App hangs after login | Callback URL mismatch | Verify callback URL is lowercase, no trailing slash, and matches Auth0 Dashboard exactly |
+| Login opens but redirects fail | Missing customScheme in authorize call | Pass `{ customScheme: 'your-scheme' }` as second argument to `authorize()` |
+| "PKCE not allowed" error | App type is not Native | Change application type to **Native** in Auth0 Dashboard |
+| Blank screen after authentication | React Navigation interference | Ensure Auth0Provider wraps the entire navigation container |
+| Android build fails with manifest errors | Conflicting auth0Domain placeholders | Remove manual manifest changes — let the Expo config plugin handle it |
+| iOS build fails with pod errors | Stale native projects | Run `npx expo prebuild --clean` to regenerate native code |
+| Token refresh fails silently | Missing `offline_access` scope | Include `offline_access` in the scope parameter during login |
+| Biometric prompt not showing | Simulator limitation | Test biometrics on a physical device — simulators have limited biometric support |
+
+## Security Considerations
+
+### PKCE (Proof Key for Code Exchange)
+
+The SDK uses PKCE by default for all Web Auth flows. PKCE protects against authorization code interception attacks. No additional configuration is needed.
+
+### Secure Credential Storage
+
+Credentials are stored securely:
+- **iOS**: Encrypted in the Keychain
+- **Android**: Encrypted in SharedPreferences via SecureCredentialsManager
+
+Never store tokens manually in AsyncStorage, MMKV, or other unencrypted storage.
+
+### Custom Scheme Security
+
+Custom URL schemes can be subject to [client impersonation attacks](https://datatracker.ietf.org/doc/html/rfc8252#section-8.6). For production apps, consider using:
+- **Android App Links** (`customScheme: "https"`) — requires SHA256 fingerprint configuration
+- **iOS Universal Links** — requires Associated Domains and Apple Developer account
+
+### Token Handling Best Practices
+
+- Never log tokens to the console in production builds
+- Use `getCredentials()` to access tokens — it auto-refreshes expired tokens
+- Request `offline_access` scope for refresh token support
+- Do not store tokens in React state — use `getCredentials()` on demand
+- Enable DPoP for enhanced token security (enabled by default)
+
+### Network Security
+
+- All Auth0 API communication uses HTTPS
+- The SDK validates ID token signatures, issuer, audience, and nonce
+- Enable certificate pinning for additional security in high-security environments
+
+## Related Capabilities
+
+- Auth0 setup — set up an account and application with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Bare React Native CLI projects → the Auth0 integration workflow for React Native
+- Multi-factor authentication → ask for MFA (feature:mfa)
+
+## References
+
+- [react-native-auth0 API Docs](https://auth0.github.io/react-native-auth0/)
+- [Auth0 Expo Quickstart](https://auth0.com/docs/quickstart/native/react-native-expo/interactive)
+- [Expo Config Plugins Guide](https://docs.expo.dev/guides/config-plugins/)
+- [Auth0 Universal Login](https://auth0.com/docs/authenticate/login/auth0-universal-login)
+- [PKCE RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)
+
+---
+
+# auth0-expo Integration Patterns
+
+## Table of Contents
+
+- [Web Auth Login](#web-auth-login) — Basic login with hooks, Auth0 class, audience, organizations
+- [Web Auth Logout](#web-auth-logout) — Hook and class-based logout
+- [Credential Management](#credential-management) — Retrieve, check, auto-refresh, Auth0 class
+- [Biometric Authentication](#biometric-authentication) — Auth0Provider config, policies, Auth0 class
+- [DPoP](#dpop-demonstrating-proof-of-possession) — Enable, API calls, token migration
+- [Multi-Resource Refresh Tokens](#multi-resource-refresh-tokens-mrrt) — Multiple API access
+- [Custom Token Exchange](#custom-token-exchange-rfc-8693) — External provider tokens
+- [Native to Web SSO](#native-to-web-sso) — Session transfer to web apps
+- [Organization Invitations](#organization-invitations) — Deep link handling
+- [Error Handling](#error-handling) — WebAuth errors, Credentials Manager errors
+- [Credential Renewal Retry](#credential-renewal-retry-ios) — iOS retry with backoff
+- [Using Custom Headers](#using-custom-headers) — Custom API request headers
+
+## Web Auth Login
+
+The primary authentication method uses Auth0 Universal Login via the system browser. The `useAuth0` hook provides the `authorize` method.
+
+### Basic Login with Hooks
+
+```typescript
+import { useAuth0 } from 'react-native-auth0';
+
+function LoginScreen() {
+  const { authorize, user, isLoading, error } = useAuth0();
+
+  const login = async () => {
+    try {
+      await authorize(
+        { scope: 'openid profile email' },
+        { customScheme: 'auth0sample' }
+      );
+    } catch (e) {
+      console.error('Login error:', e);
+    }
+  };
+
+  if (isLoading) return <ActivityIndicator />;
+
+  return (
+    <View>
+      {!user && <Button title="Log In" onPress={login} />}
+      {user && <Text>Welcome, {user.name}!</Text>}
+      {error && <Text style={{ color: 'red' }}>{error.message}</Text>}
+    </View>
+  );
+}
+```
+
+### Login with Auth0 Class (Non-Hook)
+
+```typescript
+import Auth0 from 'react-native-auth0';
+
+const auth0 = new Auth0({
+  domain: 'YOUR_AUTH0_DOMAIN',
+  clientId: 'YOUR_AUTH0_CLIENT_ID',
+});
+
+const credentials = await auth0.webAuth.authorize(
+  { scope: 'openid profile email' },
+  { customScheme: 'auth0sample' }
+);
+// Access token available at credentials.accessToken
+```
+
+### Login with Audience (API Access)
+
+To get an access token for a specific API:
+
+```typescript
+await authorize(
+  {
+    scope: 'openid profile email offline_access',
+    audience: 'https://your-api.example.com',
+  },
+  { customScheme: 'auth0sample' }
+);
+```
+
+### Login with Organization
+
+```typescript
+await authorize(
+  {
+    scope: 'openid profile email',
+    organization: 'org_abc123',
+  },
+  { customScheme: 'auth0sample' }
+);
+```
+
+## Web Auth Logout
+
+```typescript
+import { useAuth0 } from 'react-native-auth0';
+
+function LogoutButton() {
+  const { clearSession } = useAuth0();
+
+  const logout = async () => {
+    try {
+      await clearSession({ customScheme: 'auth0sample' });
+    } catch (e) {
+      console.error('Logout error:', e);
+    }
+  };
+
+  return <Button title="Log Out" onPress={logout} />;
+}
+```
+
+### Logout with Auth0 Class
+
+```typescript
+await auth0.webAuth.clearSession({}, { customScheme: 'auth0sample' });
+await auth0.credentialsManager.clearCredentials();
+```
+
+## Credential Management
+
+The `Auth0Provider` automatically stores and manages credentials. When using hooks, credentials are saved after login and cleared after logout automatically.
+
+### Retrieve Stored Credentials
+
+```typescript
+const { getCredentials } = useAuth0();
+
+const fetchData = async () => {
+  try {
+    const credentials = await getCredentials();
+    const response = await fetch('https://your-api.example.com/data', {
+      headers: {
+        Authorization: `Bearer ${credentials.accessToken}`,
+      },
+    });
+    const data = await response.json();
+  } catch (e) {
+    console.error('Failed to get credentials:', e);
+  }
+};
+```
+
+### Check for Valid Credentials
+
+```typescript
+const { hasValidCredentials } = useAuth0();
+
+useEffect(() => {
+  const checkAuth = async () => {
+    const isLoggedIn = await hasValidCredentials();
+    if (isLoggedIn) {
+      // User has valid stored credentials
+      navigation.navigate('Home');
+    } else {
+      navigation.navigate('Login');
+    }
+  };
+  checkAuth();
+}, []);
+```
+
+### Credential Auto-Refresh
+
+The credentials manager automatically refreshes expired access tokens using the refresh token. Ensure you request the `offline_access` scope during login:
+
+```typescript
+await authorize(
+  { scope: 'openid profile email offline_access' },
+  { customScheme: 'auth0sample' }
+);
+```
+
+### Credentials with Auth0 Class
+
+```typescript
+// Check for credentials
+const isLoggedIn = await auth0.credentialsManager.hasValidCredentials();
+
+// Get credentials (auto-refreshes if expired)
+const credentials = await auth0.credentialsManager.getCredentials();
+
+// Save credentials manually (not needed with hooks — auto-managed)
+await auth0.credentialsManager.saveCredentials(credentials);
+
+// Clear credentials
+await auth0.credentialsManager.clearCredentials();
+```
+
+## Biometric Authentication
+
+Protect credential access with biometric authentication (Face ID, Touch ID, fingerprint).
+
+### With Auth0Provider (Hooks)
+
+```typescript
+import {
+  Auth0Provider,
+  BiometricPolicy,
+  LocalAuthenticationStrategy,
+  LocalAuthenticationLevel,
+} from 'react-native-auth0';
+
+export default function App() {
+  return (
+    <Auth0Provider
+      domain="YOUR_AUTH0_DOMAIN"
+      clientId="YOUR_AUTH0_CLIENT_ID"
+      localAuthenticationOptions={{
+        title: 'Authenticate to access credentials',
+        subtitle: 'Please verify your identity',
+        cancelTitle: 'Cancel',
+        evaluationPolicy: LocalAuthenticationStrategy.deviceOwnerWithBiometrics,
+        fallbackTitle: 'Use Passcode',
+        authenticationLevel: LocalAuthenticationLevel.strong,
+        deviceCredentialFallback: true,
+        biometricPolicy: BiometricPolicy.session,
+        biometricTimeout: 300, // 5 minutes
+      }}
+    >
+      <HomeScreen />
+    </Auth0Provider>
+  );
+}
+```
+
+### Biometric Policy Types
+
+| Policy | Behavior |
+|--------|----------|
+| `BiometricPolicy.default` | System-managed. May skip prompt if recently authenticated. |
+| `BiometricPolicy.always` | Always prompts for biometric on every credential access. |
+| `BiometricPolicy.session` | Prompts once per session; reuses for the specified timeout. |
+| `BiometricPolicy.appLifecycle` | Prompts once until app restarts or credentials are cleared. |
+
+### With Auth0 Class
+
+```typescript
+import Auth0, {
+  BiometricPolicy,
+  LocalAuthenticationStrategy,
+  LocalAuthenticationLevel,
+} from 'react-native-auth0';
+
+const auth0 = new Auth0({
+  domain: 'YOUR_AUTH0_DOMAIN',
+  clientId: 'YOUR_AUTH0_CLIENT_ID',
+  localAuthenticationOptions: {
+    title: 'Authenticate to access credentials',
+    evaluationPolicy: LocalAuthenticationStrategy.deviceOwnerWithBiometrics,
+    authenticationLevel: LocalAuthenticationLevel.strong,
+    biometricPolicy: BiometricPolicy.always,
+  },
+});
+```
+
+## DPoP (Demonstrating Proof-of-Possession)
+
+DPoP cryptographically binds tokens to a client-specific key pair, preventing token theft.
+
+### Enable DPoP
+
+DPoP is enabled by default in react-native-auth0:
+
+```typescript
+<Auth0Provider
+  domain="YOUR_AUTH0_DOMAIN"
+  clientId="YOUR_AUTH0_CLIENT_ID"
+  // DPoP is enabled by default (useDPoP: true)
+>
+  <App />
+</Auth0Provider>
+```
+
+### Make API Calls with DPoP
+
+```typescript
+const { getCredentials, getDPoPHeaders } = useAuth0();
+
+const callApi = async () => {
+  const credentials = await getCredentials();
+  const headers = await getDPoPHeaders({
+    url: 'https://api.example.com/data',
+    method: 'GET',
+    accessToken: credentials.accessToken,
+    tokenType: credentials.tokenType,
+  });
+
+  const response = await fetch('https://api.example.com/data', {
+    method: 'GET',
+    headers: { ...headers, 'Content-Type': 'application/json' },
+  });
+};
+```
+
+### Handle DPoP Token Migration
+
+```typescript
+const { getCredentials, clearSession, authorize } = useAuth0();
+
+const ensureDPoP = async () => {
+  const credentials = await getCredentials();
+  if (credentials.tokenType !== 'DPoP') {
+    await clearSession({ customScheme: 'auth0sample' });
+    await authorize(
+      { scope: 'openid profile email' },
+      { customScheme: 'auth0sample' }
+    );
+  }
+};
+```
+
+## Multi-Resource Refresh Tokens (MRRT)
+
+Access tokens for multiple APIs using a single refresh token:
+
+```typescript
+const { authorize, getApiCredentials, clearApiCredentials } = useAuth0();
+
+// Login with offline_access
+await authorize(
+  {
+    scope: 'openid profile email offline_access',
+    audience: 'https://primary-api.example.com',
+  },
+  { customScheme: 'auth0sample' }
+);
+
+// Get token for a different API
+const apiCredentials = await getApiCredentials(
+  'https://second-api.example.com',
+  'read:data write:data'
+);
+// Access token available at apiCredentials.accessToken
+```
+
+## Custom Token Exchange (RFC 8693)
+
+Exchange external provider tokens for Auth0 tokens:
+
+```typescript
+import { useAuth0, AuthenticationException, AuthenticationErrorCodes } from 'react-native-auth0';
+
+const { customTokenExchange } = useAuth0();
+
+try {
+  const credentials = await customTokenExchange({
+    subjectToken: 'token-from-external-provider',
+    subjectTokenType: 'urn:acme:legacy-system-token',
+    scope: 'openid profile email',
+  });
+} catch (e) {
+  if (e instanceof AuthenticationException) {
+    if (e.type === AuthenticationErrorCodes.INVALID_SUBJECT_TOKEN) {
+      console.error('External token is invalid or expired');
+    }
+  }
+}
+```
+
+## Native to Web SSO
+
+Transfer authenticated sessions from the Expo app to a web application:
+
+```typescript
+import { useAuth0 } from 'react-native-auth0';
+import { Linking } from 'react-native';
+
+const { getSSOCredentials } = useAuth0();
+
+const openWebApp = async () => {
+  const ssoCredentials = await getSSOCredentials();
+  const webAppUrl = `https://webapp.example.com/login?session_transfer_token=${ssoCredentials.sessionTransferToken}`;
+  await Linking.openURL(webAppUrl);
+};
+```
+
+## Organization Invitations
+
+Handle organization invitation links:
+
+```typescript
+import { Linking } from 'react-native';
+
+const handleInvitation = async (url: string) => {
+  await auth0.webAuth.authorize(
+    { invitationUrl: url },
+    { customScheme: 'auth0sample' }
+  );
+};
+
+// Listen for deep links
+Linking.addEventListener('url', ({ url }) => {
+  if (url.includes('invitation=')) {
+    handleInvitation(url);
+  }
+});
+```
+
+## Error Handling
+
+### WebAuth Errors
+
+```typescript
+import { WebAuthError, WebAuthErrorCodes } from 'react-native-auth0';
+
+try {
+  await authorize(
+    { scope: 'openid profile email' },
+    { customScheme: 'auth0sample' }
+  );
+} catch (e) {
+  if (e instanceof WebAuthError) {
+    switch (e.type) {
+      case WebAuthErrorCodes.USER_CANCELLED:
+        console.log('User cancelled login');
+        break;
+      case WebAuthErrorCodes.BROWSER_NOT_AVAILABLE:
+        console.log('No browser available on device');
+        break;
+      case WebAuthErrorCodes.PKCE_NOT_ALLOWED:
+        console.log('PKCE not enabled — set app type to Native in Auth0 Dashboard');
+        break;
+      case WebAuthErrorCodes.NETWORK_ERROR:
+        console.log('Network error — check connectivity');
+        break;
+      default:
+        console.error('Auth error:', e.message);
+    }
+  }
+}
+```
+
+### Credentials Manager Errors
+
+```typescript
+import {
+  CredentialsManagerError,
+  CredentialsManagerErrorCodes,
+} from 'react-native-auth0';
+
+try {
+  const credentials = await getCredentials();
+} catch (e) {
+  if (e instanceof CredentialsManagerError) {
+    switch (e.type) {
+      case CredentialsManagerErrorCodes.NO_CREDENTIALS:
+        console.log('No credentials stored — user needs to log in');
+        break;
+      case CredentialsManagerErrorCodes.NO_REFRESH_TOKEN:
+        console.log('No refresh token — request offline_access scope');
+        break;
+      case CredentialsManagerErrorCodes.RENEW_FAILED:
+        console.log('Token refresh failed — re-authentication required');
+        break;
+      case CredentialsManagerErrorCodes.BIOMETRICS_FAILED:
+        console.log('Biometric authentication failed');
+        break;
+      default:
+        console.error('Credentials error:', e.message);
+    }
+  }
+}
+```
+
+## Credential Renewal Retry (iOS)
+
+For unstable network conditions, configure automatic retry for credential renewal:
+
+```typescript
+<Auth0Provider
+  domain="YOUR_AUTH0_DOMAIN"
+  clientId="YOUR_AUTH0_CLIENT_ID"
+  maxRetries={2}
+>
+  <App />
+</Auth0Provider>
+```
+
+This retries on network errors, HTTP 429, and HTTP 5xx responses with exponential backoff. iOS only — the parameter is ignored on Android.
+
+If using refresh token rotation, configure a token overlap period of at least **180 seconds** in your Auth0 tenant settings.
+
+## Using Custom Headers
+
+```typescript
+<Auth0Provider
+  domain="YOUR_AUTH0_DOMAIN"
+  clientId="YOUR_AUTH0_CLIENT_ID"
+  headers={{
+    'Accept-Language': 'fr-CA',
+    'X-App-Version': '1.0.0',
+  }}
+>
+  <App />
+</Auth0Provider>
+```
+
+---
+
+# auth0-expo Setup Guide
+
+## Table of Contents
+
+- [Auth0 Configuration](#auth0-configuration) — Credential check, automatic vs manual setup
+- [Expo Dev Client Requirement](#expo-dev-client-requirement) — Why Expo Go doesn't work, install steps
+- [Post-Setup Steps](#post-setup-steps) — Verify plugin config, callback URLs, regenerate native projects
+- [SDK Installation](#sdk-installation) — Version compatibility
+- [Using HTTPS Callback URLs](#using-https-callback-urls-android-app-links) — Android App Links
+- [Multiple Domain Support](#multiple-domain-support) — Staging/production configs
+- [Secret Management](#secret-management) — What to store, what not to store, dynamic config
+- [EAS Build Configuration](#eas-build-configuration) — Development and production builds
+- [Verification](#verification) — Plugin, build, and auth flow checks
+
+## Auth0 Configuration
+
+> **Agent instruction:**
+>
+> **Important:** Never echo Auth0 credentials (domain, client ID) in your response text. Write them directly into config files using the Write or Edit tool.
+>
+> **Credential check (always first):**
+> If the user's prompt already provides Auth0 credentials (domain, client ID), use them directly — do NOT call `AskUserQuestion` to re-confirm. Go straight to writing the app.json config and proceeding with integration.
+>
+> **If credentials are NOT provided**, use `AskUserQuestion` to ask:
+> "How would you like to configure Auth0 for this Expo project?"
+> - Option A: "Automatic setup (recommended)" — uses the Auth0 CLI to create your app
+> - Option B: "Manual setup" — provide Auth0 credentials manually
+>
+> **If Automatic Setup (Option A):**
+>
+> 1. **Pre-flight checks:**
+>    - Verify Auth0 CLI is installed: `command -v auth0`
+>    - Verify logged in: `auth0 tenants list --csv --no-input`
+>    - If any check fails, guide user to install/login, or fall back to manual setup
+>
+> 2. **Read the project's app.json** to extract:
+>    - `expo.name` (for the Auth0 app name)
+>    - `expo.scheme` (custom scheme — if missing, derive one from app name, lowercase, no special chars)
+>    - `expo.ios.bundleIdentifier` (for iOS callback URL)
+>    - `expo.android.package` (for Android callback URL)
+>
+> 3. **Create the Auth0 Native application:**
+>    ```bash
+>    auth0 apps create \
+>      --name "APP_NAME-expo" \
+>      --type native \
+>      --auth-method none \
+>      --callbacks "SCHEME://DOMAIN/ios/BUNDLE_ID/callback,SCHEME://DOMAIN/android/PACKAGE/callback" \
+>      --logout-urls "SCHEME://DOMAIN/ios/BUNDLE_ID/callback,SCHEME://DOMAIN/android/PACKAGE/callback" \
+>      --json --no-input
+>    ```
+>    Parse the JSON output to extract `client_id` and `domain`.
+>
+> 4. **Enable database connection** for the new client:
+>    ```bash
+>    auth0 api get "connections" --query "name=Username-Password-Authentication" --no-input
+>    ```
+>    Parse the response to extract the connection `id` and its current `enabled_clients` array. Append the new client_id to the existing array and patch:
+>    ```bash
+>    auth0 api patch "connections/CONNECTION_ID" --data '{"enabled_clients":["EXISTING_IDS...", "NEW_CLIENT_ID"]}' --no-input
+>    ```
+>    If it doesn't exist, create it:
+>    ```bash
+>    auth0 api post "connections" --data '{"strategy":"auth0","name":"Username-Password-Authentication","enabled_clients":["CLIENT_ID"]}' --no-input
+>    ```
+>
+> 5. **Write the plugin config to app.json** using the Edit tool — add `react-native-auth0` to the plugins array with the domain and custom scheme. Do not echo credentials in your response.
+>
+> **If Manual Setup (Option B):**
+>
+> Ask the user for their Auth0 credentials:
+> - Auth0 Domain (e.g., `your-tenant.auth0.com`)
+> - Client ID (32-character alphanumeric string)
+>
+> Then write the configuration to app.json using the Edit tool and proceed with integration.
+
+## Expo Dev Client Requirement
+
+The `react-native-auth0` SDK uses native modules and **does not work with Expo Go**. A custom Expo development client is required.
+
+> **Agent instruction:** Before proceeding with Auth0 SDK installation, check the project's `package.json` for `expo-dev-client` in `dependencies` or `devDependencies`. If not found, ask the user how they'd like to proceed (install automatically or set it up themselves). See SKILL.md step 1 for the full agent instruction.
+
+### Check for expo-dev-client
+
+```bash
+# Check if expo-dev-client is in the project
+cat package.json | grep expo-dev-client
+```
+
+### Install expo-dev-client (if missing)
+
+```bash
+npx expo install expo-dev-client
+```
+
+After installing, the development workflow changes from `npx expo start` (Expo Go) to:
+
+```bash
+npx expo run:ios
+# or
+npx expo run:android
+```
+
+For cloud builds, use EAS Build with a development profile:
+
+```bash
+eas build --profile development --platform ios
+eas build --profile development --platform android
+```
+
+## Post-Setup Steps
+
+After Auth0 is configured (via automatic or manual setup), complete these steps:
+
+### 1. Verify app.json Plugin Configuration
+
+Ensure `app.json` contains the react-native-auth0 plugin:
+
+```json
+{
+  "expo": {
+    "ios": {
+      "bundleIdentifier": "com.yourcompany.yourapp"
+    },
+    "android": {
+      "package": "com.yourcompany.yourapp"
+    },
+    "plugins": [
+      [
+        "react-native-auth0",
+        {
+          "domain": "your-tenant.auth0.com",
+          "customScheme": "auth0sample"
+        }
+      ]
+    ]
+  }
+}
+```
+
+The `customScheme` must be:
+- All lowercase
+- No special characters
+- Unique to your application
+- Passed to `authorize()` and `clearSession()` calls
+
+### 2. Configure Callback URLs in Auth0 Dashboard
+
+Go to [Auth0 Dashboard > Applications](https://manage.auth0.com/#/applications), select your application, and add the following:
+
+**Allowed Callback URLs:**
+```text
+auth0sample://your-tenant.auth0.com/ios/com.yourcompany.yourapp/callback,
+auth0sample://your-tenant.auth0.com/android/com.yourcompany.yourapp/callback
+```
+
+**Allowed Logout URLs:**
+```text
+auth0sample://your-tenant.auth0.com/ios/com.yourcompany.yourapp/callback,
+auth0sample://your-tenant.auth0.com/android/com.yourcompany.yourapp/callback
+```
+
+Replace `auth0sample` with your `customScheme`, `your-tenant.auth0.com` with your domain, and `com.yourcompany.yourapp` with your bundle ID / package name.
+
+All values must be **lowercase** with **no trailing slash**.
+
+### 3. Regenerate Native Projects
+
+After modifying app.json, regenerate the native projects:
+
+```bash
+npx expo prebuild --clean
+```
+
+This applies the Auth0 config plugin, which configures:
+- **iOS**: URL scheme in Info.plist and AppDelegate linking handler
+- **Android**: manifest placeholders for auth0Domain and auth0Scheme in build.gradle
+
+## SDK Installation
+
+```bash
+npx expo install react-native-auth0
+```
+
+This installs the SDK with the correct version for your Expo SDK.
+
+For older Expo versions:
+- Expo 53+: Use react-native-auth0 v5.x
+- Expo < 53: Use react-native-auth0 v4.x (`npx expo install react-native-auth0@4`)
+
+## Using HTTPS Callback URLs (Android App Links)
+
+For enhanced security, you can use HTTPS callback URLs with Android App Links:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "react-native-auth0",
+        {
+          "domain": "your-tenant.auth0.com",
+          "customScheme": "https"
+        }
+      ]
+    ]
+  }
+}
+```
+
+When using `customScheme: "https"`, the plugin automatically adds `android:autoVerify="true"` to the Android manifest intent-filter.
+
+You must also configure Android App Links in the Auth0 Dashboard:
+1. Go to **Applications > your app > Show Advanced Settings > Device Settings**
+2. Add your Android Package Name and SHA256 fingerprint
+
+## Multiple Domain Support
+
+To support multiple Auth0 domains (e.g., for staging/production), pass an array to the plugin:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "react-native-auth0",
+        [
+          {
+            "domain": "staging.auth0.com",
+            "customScheme": "auth0staging"
+          },
+          {
+            "domain": "production.auth0.com",
+            "customScheme": "auth0prod"
+          }
+        ]
+      ]
+    ]
+  }
+}
+```
+
+## Secret Management
+
+Expo / React Native mobile apps do **not** use a Client Secret. The Auth0 Native application type uses PKCE (Proof Key for Code Exchange) for secure authentication without exposing secrets.
+
+**What to store in code / config:**
+- Auth0 Domain — in `app.json` plugin config and `Auth0Provider` props
+- Auth0 Client ID — in `Auth0Provider` props only (not in app.json)
+- Custom Scheme — in `app.json` plugin config and `authorize`/`clearSession` options
+
+**What NOT to store:**
+- Never include Client Secret in mobile apps
+- Never commit sensitive tokens to source control
+
+For environment-specific configuration, use `app.config.js` (dynamic config):
+
+```javascript
+export default ({ config }) => ({
+  ...config,
+  plugins: [
+    [
+      'react-native-auth0',
+      {
+        domain: process.env.AUTH0_DOMAIN || 'dev.auth0.com',
+        customScheme: process.env.AUTH0_SCHEME || 'auth0dev',
+      },
+    ],
+  ],
+});
+```
+
+## EAS Build Configuration
+
+For production builds with EAS:
+
+```bash
+npm install -g eas-cli
+eas build --platform all
+```
+
+Create `eas.json` if it doesn't exist:
+
+```json
+{
+  "cli": {
+    "version": ">= 3.0.0"
+  },
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal"
+    },
+    "preview": {
+      "distribution": "internal"
+    },
+    "production": {}
+  }
+}
+```
+
+For development builds (used instead of Expo Go):
+
+```bash
+eas build --profile development --platform ios
+eas build --profile development --platform android
+```
+
+## Verification
+
+After setup, verify the integration:
+
+1. **Plugin applied correctly:**
+   ```bash
+   npx expo prebuild --clean
+   ```
+   Check that `ios/{AppName}/Info.plist` contains the URL scheme and `android/app/build.gradle` contains `manifestPlaceholders`.
+
+2. **Build succeeds:**
+   ```bash
+   npx expo run:ios
+   # or
+   npx expo run:android
+   ```
+
+3. **Auth flow works:**
+   - Tap Login — browser opens with Auth0 Universal Login
+   - Complete login — app receives credentials and shows user info
+   - Tap Logout — session is cleared
diff --git a/main/.mintlify/skills/auth0/references/framework-express-jwt/index.md b/main/.mintlify/skills/auth0/references/framework-express-jwt/index.md
new file mode 100644
index 0000000000..89d68f9c31
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-express-jwt/index.md
@@ -0,0 +1,932 @@
+
+# Node OAuth2 JWT Bearer Integration
+
+The `express-oauth2-jwt-bearer` package provides Express middleware for validating Auth0 JWT Bearer access tokens. It handles token extraction, signature verification, audience and issuer validation, and expiry checks per RFC 6750 — letting you focus on business logic rather than JWT parsing.
+
+> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
+> ```bash
+> gh api repos/auth0/node-oauth2-jwt-bearer/releases/latest --jq '.tag_name'
+> ```
+> Use the returned version in all `package.json` dependency lines instead of any hardcoded version below.
+
+## Prerequisites
+
+- **Node.js** 18+ (20+ recommended)
+- **Express** 4.x or 5.x
+- **npm** or **yarn**
+- An **Auth0 account** with a configured API (Resource Server)
+- **Auth0 CLI** (for automatic setup): `npm install -g @auth0/auth0-cli`
+
+## When NOT to Use
+
+| Use Case | Use Instead |
+|----------|-------------|
+| Building a server-side web app with login UI (Express sessions) | the Auth0 integration workflow for Express (web app) |
+| Building a Next.js app with server-side auth | the Auth0 integration workflow for Next.js |
+| Building a React/Angular/Vue SPA | the Auth0 integration workflow for React, Angular, or Vue |
+| Building a React Native or mobile app | the Auth0 integration workflow for React Native, Android, or Swift |
+| ASP.NET Core Web API | the Auth0 integration workflow for ASP.NET Core (API) |
+| Go API with JWT middleware | the Auth0 integration workflow for Go |
+| Python API (Flask/FastAPI) | the Auth0 integration workflow for Flask or FastAPI |
+
+## Quick Start Workflow
+
+> **Agent instruction:** Follow these steps to integrate `express-oauth2-jwt-bearer` into the user's Node.js API project.
+>
+> 1. **Fetch latest version** (see instruction above).
+>
+> 2. **Install the SDK:**
+>    ```bash
+>    npm install express-oauth2-jwt-bearer
+>    ```
+>
+> 3. **Configure Auth0** — follow the Setup Guide section below. If the user already provided their Auth0 Domain and API Audience in the prompt, write them to a `.env` file as `ISSUER_BASE_URL` (the full issuer URL, including `https://`) and `AUDIENCE` — the SDK reads these automatically. Skip automatic setup and do NOT call `AskUserQuestion` to re-confirm. **Never hardcode the domain or audience as literal strings (or `||` fallback defaults) in `server.js` / `app.js`** — they belong in `.env` only. Otherwise, offer automatic setup via the Auth0 CLI or manual setup.
+>
+> 4. **Set up middleware** — first create a `.env` file with the Auth0 values, then load it and add the middleware. `express-oauth2-jwt-bearer` reads `ISSUER_BASE_URL` and `AUDIENCE` from the environment automatically, so `auth()` needs no arguments:
+>    ```bash
+>    # .env
+>    ISSUER_BASE_URL=https://your-tenant.us.auth0.com
+>    AUDIENCE=https://your-api-identifier
+>    ```
+>    ```javascript
+>    import 'dotenv/config'; // load .env before the SDK reads process.env
+>    import { auth } from 'express-oauth2-jwt-bearer';
+>
+>    // Reads ISSUER_BASE_URL and AUDIENCE from the environment — no config needed
+>    const checkJwt = auth();
+>
+>    app.use(checkJwt); // apply globally, or per-route
+>    ```
+>    Keep the issuer and audience in `.env` — do not inline literal values or pass them as arguments here.
+>
+> 5. **Protect endpoints** — apply middleware globally or to specific routes:
+>    ```javascript
+>    // Global protection
+>    app.use(checkJwt);
+>
+>    // Or per-route
+>    app.get('/api/private', checkJwt, (req, res) => {
+>      res.json({ sub: req.auth.payload.sub });
+>    });
+>    ```
+>
+> 6. **Add RBAC** (optional) — use `requiredScopes()` or `claimIncludes()` for permission-based access:
+>    ```javascript
+>    import { auth, requiredScopes, claimIncludes } from 'express-oauth2-jwt-bearer';
+>
+>    app.get('/api/messages', checkJwt, requiredScopes('read:messages'), (req, res) => {
+>      res.json({ messages: [] });
+>    });
+>    ```
+>    > **Important:** `requiredScopes` accepts a single argument — a space-separated string or an array. Do NOT pass multiple string arguments: `requiredScopes('read:msg', 'write:msg')` silently ignores everything after the first. Use `requiredScopes('read:msg write:msg')` or `requiredScopes(['read:msg', 'write:msg'])` instead.
+>
+> 7. **Verify the integration** — build and test:
+>    ```bash
+>    node server.js
+>    curl http://localhost:3000/api/private         # should return 401
+>    curl -H "Authorization: Bearer <token>" http://localhost:3000/api/private  # should return 200
+>    ```
+>
+> 8. **Failcheck:** If the server fails to start or tokens are rejected unexpectedly, check the Common Issues section below for common issues. After 5-6 failed iterations, use `AskUserQuestion` to ask the user for more details about their environment.
+
+## Detailed Documentation
+
+- **Setup Guide** (see the Setup Guide section below) — Auth0 API registration, .env configuration, Auth0 CLI for automated setup, and secret management
+- **Integration Patterns** (see the Integration Patterns section below) — Protected endpoints, RBAC with scopes and claims, DPoP, CORS setup, error handling, and testing with curl
+- **API Reference & Testing** (see the API Reference & Testing section below) — Full configuration options, claims reference, complete code example, testing checklist, and common issues
+
+## Common Mistakes
+
+| Mistake | Symptom | Fix |
+|---------|---------|-----|
+| Created an **Application** instead of an **API** in Auth0 Dashboard | Token validation fails; wrong audience | Create a new **API** (Resource Server) in Auth0 Dashboard → APIs |
+| Audience doesn't match API identifier exactly | `401 Unauthorized` — "Audience mismatch" | Copy the exact API Identifier string from Auth0 Dashboard → APIs |
+| `ISSUER_BASE_URL` missing the `https://` scheme | `Error: Invalid URL` at startup | `ISSUER_BASE_URL` must be the full issuer URL: `https://your-tenant.us.auth0.com` |
+| Checking `scope` claim instead of `permissions` for RBAC | 403 always returned or permissions ignored | Use `requiredScopes()` for scope-based RBAC; use `claimIncludes('permissions', 'read:data')` for Auth0 RBAC permission claims |
+| CORS not configured before auth middleware | Preflight OPTIONS requests return 401 | Add `cors()` middleware before `auth()` in the middleware chain |
+| `.env` file not loaded | `undefined` for domain/audience | Add `import 'dotenv/config'` at the top of the entry file |
+| Hardcoded domain/audience in source (incl. `process.env.X \|\| 'literal'` fallbacks) | Secrets committed to source; fails security review | Put values in `.env` (`ISSUER_BASE_URL` / `AUDIENCE`) and let `auth()` read them automatically — no literal fallbacks |
+| `req.auth` is undefined | `TypeError: Cannot read properties of undefined` | Verify `checkJwt` middleware runs before the handler |
+
+## Related Skills
+
+- Express web apps with login UI (sessions, cookies) → the Auth0 integration workflow for Express
+- Next.js server-side web apps → the Auth0 integration workflow for Next.js
+- .NET Web API (BACKEND_API reference implementation) → the Auth0 integration workflow for ASP.NET Core
+- JWT middleware for Go APIs → the Auth0 integration workflow for Go
+- JWT validation for Python APIs (Flask/FastAPI) → the Auth0 integration workflow for FastAPI or Flask
+- Manage Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+
+## Quick Reference
+
+### Core Middleware
+
+| Function | Description | Returns |
+|----------|-------------|---------|
+| `auth(options?)` | JWT Bearer validation middleware | `Handler` — 401 if token invalid/missing |
+| `requiredScopes(scopes)` | Validates token has all required scopes | `Handler` — 403 if scopes missing |
+| `scopeIncludesAny(scopes)` | Validates token has at least one scope | `Handler` — 403 if no match |
+| `claimEquals(claim, value)` | Validates a claim equals a value | `Handler` — 401 if mismatch |
+| `claimIncludes(claim, ...values)` | Validates claim includes all values | `Handler` — 401 if incomplete |
+| `claimCheck(fn, desc?)` | Custom claim validation function | `Handler` — 401 if fn returns false |
+
+### Configuration Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `issuerBaseURL` | `string` | Full issuer URL with `https://`. Optional — defaults to the `ISSUER_BASE_URL` env var |
+| `audience` | `string` | API Identifier from Auth0 Dashboard. Optional — defaults to the `AUDIENCE` env var |
+| `tokenSigningAlg` | `string` | Signing algorithm (default: `RS256`; use `HS256` for symmetric) |
+| `authRequired` | `boolean` | Set `false` to make authentication optional (default: `true`) |
+| `clockTolerance` | `number` | Clock skew tolerance in seconds (no default; undefined unless set) |
+| `dpop` | `DPoPOptions` | DPoP configuration (see the DPoP Support section below) |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ISSUER_BASE_URL` | Full issuer URL with `https://`, e.g. `https://your-tenant.us.auth0.com` (auto-detected by SDK) |
+| `AUDIENCE` | API Identifier, e.g. `https://your-api-identifier` (auto-detected by SDK) |
+
+### Request Object
+
+After successful validation, `req.auth` contains:
+```typescript
+req.auth.payload    // Decoded JWT payload (sub, iss, aud, exp, permissions, etc.)
+req.auth.header     // JWT header (alg, typ, kid)
+req.auth.token      // Raw JWT string
+```
+
+## SDK Architecture
+
+The `node-oauth2-jwt-bearer` monorepo contains three packages:
+
+| Package | Purpose |
+|---------|---------|
+| `express-oauth2-jwt-bearer` | **Main package.** Express middleware for JWT Bearer validation. Published to npm. |
+| `access-token-jwt` | Low-level JWT verification utilities (used internally). |
+| `oauth2-bearer` | RFC 6750 Bearer token extraction (used internally). |
+
+In practice, you only install and import `express-oauth2-jwt-bearer`.
+
+## Auth Flow Comparison
+
+| Auth Pattern | SDK | When to Use |
+|-------------|-----|-------------|
+| JWT Bearer (stateless) | `express-oauth2-jwt-bearer` | APIs called by SPAs, mobile apps, M2M clients |
+| Session-based (stateful) | `@auth0/express-openid-connect` | Web apps with login UI and server-side sessions |
+
+## Testing Quick Reference
+
+```bash
+# Capture a token into a shell variable — see "Testing Patterns" below for the
+# full command. Reference $ACCESS_TOKEN rather than pasting the raw token
+# inline; inline token values leak into shell history and terminal scrollback.
+
+# 1. Verify 401 on protected route (no token)
+curl -v http://localhost:3000/api/private
+
+# 2. Verify 200 with valid token
+curl -H "Authorization: Bearer $ACCESS_TOKEN" http://localhost:3000/api/private
+
+# 3. Verify 403 with valid token but missing scope
+curl -H "Authorization: Bearer $ACCESS_TOKEN" http://localhost:3000/api/admin
+
+# 4. Verify CORS preflight
+curl -v -X OPTIONS http://localhost:3000/api/private \
+  -H "Origin: http://localhost:5173" \
+  -H "Access-Control-Request-Method: GET" \
+  -H "Access-Control-Request-Headers: Authorization"
+```
+
+## References
+
+- [express-oauth2-jwt-bearer on npm](https://www.npmjs.com/package/express-oauth2-jwt-bearer)
+- [GitHub: auth0/node-oauth2-jwt-bearer](https://github.com/auth0/node-oauth2-jwt-bearer)
+- [Auth0 Node.js API Quickstart](https://auth0.com/docs/quickstart/backend/nodejs/interactive)
+- [Auth0 APIs Dashboard](https://manage.auth0.com/#/apis)
+- [RFC 6750 — Bearer Token Usage](https://datatracker.ietf.org/doc/html/rfc6750)
+
+---
+
+# express-oauth2-jwt-bearer API Reference & Testing
+
+## Configuration Reference
+
+All options are passed to the `auth()` function or set via environment variables.
+
+### auth() Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `issuerBaseURL` | `string` | No — defaults to `ISSUER_BASE_URL` env var | — | Full issuer URL with `https://`, e.g. `https://your-tenant.us.auth0.com` |
+| `audience` | `string` | No — defaults to `AUDIENCE` env var | — | API Identifier from Auth0 Dashboard, e.g. `https://my-api.com` |
+| `secret` | `string` | For HS256 only | — | Shared secret for symmetric JWT signing (HS256). Not required for RS256. |
+| `tokenSigningAlg` | `string` | No | `RS256` | JWT signing algorithm. Use `HS256` for symmetric keys. |
+| `issuer` | `string` | No (alternative to `issuerBaseURL`) | — | Issuer claim value — use with `jwksUri` for non-standard setups |
+| `jwksUri` | `string` | No | Derived from `issuerBaseURL` | Custom JWKS endpoint URL |
+| `authRequired` | `boolean` | No | `true` | Set `false` to allow unauthenticated requests through (attach auth info if present) |
+| `clockTolerance` | `number` | No | `(none)` | Clock skew tolerance in seconds (undefined unless explicitly set) |
+| `validators` | `Validators` | No | — | Custom validator overrides. Set `{ iss: false }` to skip issuer validation. |
+| `dpop` | `DPoPOptions` | No | — | DPoP configuration (see below) |
+
+### DPoPOptions
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `enabled` | `boolean` | Enable DPoP token binding. Default is `true` (hybrid Bearer+DPoP mode). |
+| `required` | `boolean` | Set `true` to reject plain Bearer tokens (DPoP-only mode). Default: `false`. |
+| `iatOffset` | `number` | Max age of a DPoP proof in seconds. |
+| `iatLeeway` | `number` | Leeway for `iat` claim in DPoP proofs. |
+
+### Environment Variables (auto-detected)
+
+`express-oauth2-jwt-bearer` reads these variables from the environment automatically, so `auth()` can be called with no arguments. This is the approach this skill uses — put the values in `.env` and let the SDK pick them up:
+
+| Variable | Description |
+|----------|-------------|
+| `ISSUER_BASE_URL` | Full issuer URL **with** `https://` prefix: `https://your-tenant.us.auth0.com` |
+| `AUDIENCE` | API Identifier: `https://your-api.example.com` |
+
+```javascript
+import 'dotenv/config'; // load .env before the SDK reads process.env
+
+// No arguments needed — ISSUER_BASE_URL and AUDIENCE are read from the environment
+const checkJwt = auth();
+```
+
+Pass `issuerBaseURL` / `audience` explicitly only if you need to source them from differently-named variables or compute them at runtime.
+
+## Claims Reference
+
+| Claim | Type | Description |
+|-------|------|-------------|
+| `sub` | `string` | Subject identifier — the user's or M2M app's unique Auth0 ID |
+| `iss` | `string` | Issuer — your Auth0 tenant URL (e.g. `https://your-tenant.us.auth0.com/`) |
+| `aud` | `string \| string[]` | Audience — must match your API Identifier |
+| `exp` | `number` | Expiration timestamp (Unix epoch) |
+| `iat` | `number` | Issued-at timestamp (Unix epoch) |
+| `scope` | `string` | Space-separated scopes granted to the token |
+| `permissions` | `string[]` | Array of RBAC permissions (Auth0-specific, enabled via RBAC settings on the API) |
+| `azp` | `string` | Authorized party — client ID of the application that requested the token |
+| `org_id` | `string` | Organization ID (Auth0 Organizations feature) |
+
+**Accessing claims in a handler:**
+```javascript
+app.get('/api/me', checkJwt, (req, res) => {
+  const { sub, permissions, scope } = req.auth.payload;
+  res.json({ sub, permissions });
+});
+```
+
+## Code Examples
+
+### Complete minimal example
+
+```javascript
+// server.js
+import 'dotenv/config';
+import express from 'express';
+import cors from 'cors';
+import { auth, requiredScopes, claimIncludes } from 'express-oauth2-jwt-bearer';
+
+const app = express();
+
+// 1. CORS before auth (required for preflight requests)
+app.use(cors({
+  origin: process.env.CORS_ORIGIN || 'http://localhost:5173',
+  allowedHeaders: ['Authorization', 'Content-Type', 'DPoP'],
+}));
+
+app.use(express.json());
+
+// 2. JWT validation middleware
+// Reads ISSUER_BASE_URL and AUDIENCE from the environment — no arguments needed
+const checkJwt = auth();
+
+// 3. Public endpoint (no auth required)
+app.get('/api/public', (req, res) => {
+  res.json({ message: 'This is a public endpoint' });
+});
+
+// 4. Private endpoint (JWT required)
+app.get('/api/private', checkJwt, (req, res) => {
+  res.json({
+    message: 'Authenticated',
+    sub: req.auth.payload.sub,
+  });
+});
+
+// 5. Scoped endpoint (specific scope required)
+app.get('/api/messages', checkJwt, requiredScopes('read:messages'), (req, res) => {
+  res.json({ messages: ['Hello', 'World'] });
+});
+
+// 6. Permission-based endpoint (RBAC permissions claim)
+app.get('/api/admin', checkJwt, claimIncludes('permissions', 'admin:access'), (req, res) => {
+  res.json({ message: 'Admin access granted' });
+});
+
+// 7. RFC 6750 error handler
+app.use((err, req, res, next) => {
+  if (err.status) {
+    return res.status(err.status).json({
+      error: err.code,
+      message: err.message,
+    });
+  }
+  next(err);
+});
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => console.log(`API listening on port ${PORT}`));
+```
+
+### Environment configuration (.env)
+
+```env
+ISSUER_BASE_URL=https://your-tenant.us.auth0.com
+AUDIENCE=https://your-api.example.com
+PORT=3000
+CORS_ORIGIN=http://localhost:5173
+```
+
+### TypeScript example
+
+```typescript
+import 'dotenv/config';
+import express, { Request, Response, NextFunction } from 'express';
+import { auth, requiredScopes } from 'express-oauth2-jwt-bearer';
+
+// Note: express-oauth2-jwt-bearer already declares req.auth on the Express
+// Request interface in its own .d.ts — no need to redeclare it here.
+
+const app = express();
+
+// Reads ISSUER_BASE_URL and AUDIENCE from the environment — no arguments needed
+const checkJwt = auth();
+
+app.get('/api/private', checkJwt, (req: Request, res: Response) => {
+  const sub = req.auth?.payload.sub;
+  res.json({ sub });
+});
+```
+
+## Testing Checklist
+
+- [ ] **Public endpoint** returns `200` without a token: `curl http://localhost:3000/api/public`
+- [ ] **Protected endpoint** returns `401` without a token: `curl http://localhost:3000/api/private`
+- [ ] **Protected endpoint** returns `200` with valid M2M token: `curl -H "Authorization: Bearer <token>" http://localhost:3000/api/private`
+- [ ] **Scoped endpoint** returns `403` with token missing required scope
+- [ ] **Scoped endpoint** returns `200` with token that has the required scope
+- [ ] **Expired token** returns `401` with error description
+- [ ] **Wrong audience** returns `401`
+- [ ] **CORS preflight** (`OPTIONS`) returns `200` from protected routes
+- [ ] `req.auth.payload.sub` contains the expected subject
+- [ ] `req.auth.payload.permissions` array is populated (if RBAC is enabled on the Auth0 API)
+
+### Getting a test token with M2M credentials
+
+```bash
+curl --request POST \
+  --url "https://YOUR_AUTH0_DOMAIN/oauth/token" \
+  --header "content-type: application/json" \
+  --data '{
+    "client_id": "YOUR_M2M_CLIENT_ID",
+    "client_secret": "YOUR_M2M_CLIENT_SECRET",
+    "audience": "YOUR_API_AUDIENCE",
+    "grant_type": "client_credentials"
+  }'
+```
+
+## Common Issues
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `UnauthorizedError: No authorization token was found` | No `Authorization: Bearer ...` header | Add the bearer token to the request header |
+| `UnauthorizedError: invalid_token — jwt audience invalid` | Audience mismatch | Verify `AUDIENCE` matches the API Identifier in Auth0 Dashboard exactly |
+| `UnauthorizedError: invalid_token — jwt issuer invalid` | Issuer mismatch | Verify `ISSUER_BASE_URL` is the Auth0 tenant URL including `https://` |
+| `UnauthorizedError: invalid_token — jwt expired` | Token has expired | Request a new token; check system clock drift (`clockTolerance` option) |
+| `Error: JWKS request failed` | Network or issuer misconfiguration | Verify `ISSUER_BASE_URL` is reachable; check network/proxy settings |
+| `InsufficientScopeError: Insufficient scope` | Token lacks required scope | Verify the requesting app has the scope granted; check `requiredScopes()` call |
+| `CORS error` on OPTIONS preflight | Auth middleware running before CORS | Move `cors()` middleware before `auth()` in the middleware chain |
+| `TypeError: Cannot read properties of undefined (reading 'payload')` | `req.auth` is undefined | Check that `checkJwt` middleware runs before the handler |
+
+## Security Considerations
+
+- **Never log tokens.** Full JWT strings contain sensitive claims. Log only `sub` or `jti` for tracing.
+- **CORS before auth.** Always register `cors()` before `auth()`. Auth middleware rejects OPTIONS preflight requests with 401 if CORS isn't set first.
+- **Audience validation is critical.** Without a matching `audience`, your API would accept tokens issued for other services.
+- **Issuer validation.** The `issuerBaseURL` is used to fetch the JWKS and validate the `iss` claim. Never disable issuer validation in production.
+- **RBAC via `permissions` claim.** Auth0 RBAC stores user permissions in the `permissions` JWT claim (not `scope`). Enable "Add Permissions in the Access Token" on your Auth0 API settings.
+- **DPoP.** For APIs requiring sender-constrained tokens, enable DPoP with `dpop: { enabled: true, required: true }`. This prevents token theft — stolen tokens cannot be replayed without the original private key.
+- **Helmet.** Pair with `helmet` for security headers: `npm install helmet` + `app.use(helmet())`.
+- **Production secrets.** Never commit `.env` to source control. Use environment variables in production (Railway, Heroku, Fly.io, etc.).
+
+---
+
+# Integration Patterns
+
+## Authentication Flow
+
+```text
+Client → API
+  1. Client obtains access token from Auth0 (via /oauth/token)
+  2. Client sends request with "Authorization: Bearer <token>" header
+  3. express-oauth2-jwt-bearer middleware:
+     a. Extracts bearer token from Authorization header
+     b. Fetches public key from Auth0 JWKS endpoint (cached)
+     c. Verifies token signature, issuer, audience, expiry
+     d. Attaches decoded token to req.auth
+  4. Route handler accesses req.auth.payload
+```
+
+## Protected Endpoints
+
+### Global protection
+
+Apply `checkJwt` middleware globally to protect all routes:
+
+```javascript
+import { auth } from 'express-oauth2-jwt-bearer';
+
+// Reads ISSUER_BASE_URL and AUDIENCE from the environment — no arguments needed
+const checkJwt = auth();
+
+// All routes below this require a valid JWT
+app.use(checkJwt);
+app.get('/api/users', (req, res) => {
+  res.json({ sub: req.auth.payload.sub });
+});
+```
+
+### Per-route protection
+
+Apply middleware to specific routes only:
+
+```javascript
+// Public — no auth
+app.get('/api/public', (req, res) => {
+  res.json({ message: 'Public endpoint' });
+});
+
+// Protected — JWT required
+app.get('/api/private', checkJwt, (req, res) => {
+  res.json({ sub: req.auth.payload.sub });
+});
+```
+
+### Optional authentication
+
+Allow unauthenticated requests but attach auth info when present:
+
+```javascript
+// issuer and audience come from ISSUER_BASE_URL / AUDIENCE in the environment
+const optionalAuth = auth({
+  authRequired: false,
+});
+
+app.get('/api/profile', optionalAuth, (req, res) => {
+  if (req.auth) {
+    res.json({ sub: req.auth.payload.sub, authenticated: true });
+  } else {
+    res.json({ authenticated: false });
+  }
+});
+```
+
+## RBAC — Scope-Based Authorization
+
+Use `requiredScopes()` to enforce scopes on access tokens:
+
+```javascript
+import { auth, requiredScopes } from 'express-oauth2-jwt-bearer';
+
+// All scopes must be present
+app.get('/api/messages', checkJwt, requiredScopes('read:messages'), (req, res) => {
+  res.json({ messages: [] });
+});
+
+// Multiple scopes required
+app.post('/api/messages', checkJwt, requiredScopes('read:messages write:messages'), (req, res) => {
+  res.json({ created: true });
+});
+```
+
+### Permission-based RBAC (Auth0 RBAC feature)
+
+When Auth0 RBAC is enabled on the API, permissions are stored in the `permissions` claim:
+
+```javascript
+import { auth, claimIncludes } from 'express-oauth2-jwt-bearer';
+
+// Require 'read:messages' in the permissions claim
+app.get('/api/messages', checkJwt, claimIncludes('permissions', 'read:messages'), (req, res) => {
+  res.json({ messages: [] });
+});
+
+// Require multiple permissions
+app.delete('/api/messages/:id', checkJwt, claimIncludes('permissions', 'delete:messages'), (req, res) => {
+  res.json({ deleted: true });
+});
+```
+
+## Claim Validation
+
+### claimEquals — exact value match
+
+```javascript
+import { auth, claimEquals } from 'express-oauth2-jwt-bearer';
+
+// Require org_id to equal a specific value
+app.get('/api/org-data', checkJwt, claimEquals('org_id', 'org_123'), (req, res) => {
+  res.json({ org: 'org_123' });
+});
+```
+
+### claimIncludes — array contains all values
+
+```javascript
+import { auth, claimIncludes } from 'express-oauth2-jwt-bearer';
+
+// Require the roles claim to include 'admin'
+app.get('/api/admin', checkJwt, claimIncludes('roles', 'admin'), (req, res) => {
+  res.json({ admin: true });
+});
+```
+
+### claimCheck — custom validation logic
+
+```javascript
+import { auth, claimCheck } from 'express-oauth2-jwt-bearer';
+
+// Custom validation function
+app.get('/api/premium', checkJwt, claimCheck((payload) => {
+  return payload?.subscription === 'premium' && payload?.active === true;
+}, 'Premium subscription required'), (req, res) => {
+  res.json({ premium: true });
+});
+```
+
+## CORS Configuration
+
+**Critical:** CORS middleware must come before auth middleware. Auth rejects OPTIONS preflight requests with 401 if CORS isn't configured first.
+
+```javascript
+import cors from 'cors';
+import { auth } from 'express-oauth2-jwt-bearer';
+
+// 1. CORS first (handles OPTIONS preflight)
+app.use(cors({
+  origin: 'http://localhost:5173',  // Your frontend URL
+  allowedHeaders: ['Authorization', 'Content-Type', 'DPoP'],
+  exposedHeaders: ['WWW-Authenticate'],
+}));
+
+// 2. Auth second
+// Reads ISSUER_BASE_URL and AUDIENCE from the environment — no arguments needed
+const checkJwt = auth();
+```
+
+## DPoP Support
+
+DPoP (Demonstration of Proof-of-Possession) binds tokens to the client's key pair, preventing token theft. The SDK supports DPoP natively.
+
+### Hybrid mode (Bearer or DPoP both accepted — default)
+
+```javascript
+// issuer and audience come from ISSUER_BASE_URL / AUDIENCE in the environment
+const checkJwt = auth({
+  dpop: {
+    enabled: true,
+    required: false,  // Accept both Bearer and DPoP tokens
+  },
+});
+```
+
+### DPoP-only mode (rejects plain Bearer tokens)
+
+```javascript
+// issuer and audience come from ISSUER_BASE_URL / AUDIENCE in the environment
+const checkJwt = auth({
+  dpop: {
+    enabled: true,
+    required: true,  // Reject plain Bearer tokens
+  },
+});
+```
+
+### Bearer-only mode (disable DPoP)
+
+```javascript
+// issuer and audience come from ISSUER_BASE_URL / AUDIENCE in the environment
+const checkJwt = auth({
+  dpop: { enabled: false },
+});
+```
+
+
+## Error Handling
+
+The SDK throws RFC 6750-compliant errors with `.status` and `.headers` properties. Add an error handler after your routes:
+
+```javascript
+app.use((err, req, res, next) => {
+  if (err.status) {
+    // JWT validation error — send WWW-Authenticate header per RFC 6750
+    res.set(err.headers);
+    return res.status(err.status).json({
+      error: err.code,
+      error_description: process.env.NODE_ENV === 'production' ? undefined : err.message,
+    });
+  }
+  // Other errors
+  console.error(err);
+  res.status(500).json({ error: 'internal_error' });
+});
+```
+
+### Error types
+
+| Error Class | Status | Code | Cause |
+|------------|--------|------|-------|
+| `UnauthorizedError` | 401 | `invalid_token` | Missing, expired, or malformed token |
+| `InvalidRequestError` | 400 | `invalid_request` | Malformed Authorization header |
+| `InvalidTokenError` | 401 | `invalid_token` | Token signature/claims validation failed |
+| `InsufficientScopeError` | 403 | `insufficient_scope` | Token lacks required scope |
+
+```javascript
+import {
+  UnauthorizedError,
+  InvalidTokenError,
+  InsufficientScopeError
+} from 'express-oauth2-jwt-bearer';
+
+app.use((err, req, res, next) => {
+  if (err instanceof InsufficientScopeError) {
+    return res.status(403).json({ error: 'forbidden' });
+  }
+  if (err instanceof UnauthorizedError || err instanceof InvalidTokenError) {
+    return res.status(401).json({ error: 'unauthorized' });
+  }
+  next(err);
+});
+```
+
+## Testing Patterns
+
+### Manual testing with curl
+
+```bash
+# 1. Get a test token (from Auth0 Dashboard → APIs → Test, or via M2M credentials)
+ACCESS_TOKEN=$(curl -s --request POST \
+  --url "https://YOUR_AUTH0_DOMAIN/oauth/token" \
+  --header "content-type: application/json" \
+  --data '{
+    "client_id": "YOUR_M2M_CLIENT_ID",
+    "client_secret": "YOUR_M2M_CLIENT_SECRET",
+    "audience": "YOUR_API_AUDIENCE",
+    "grant_type": "client_credentials"
+  }' | jq -r '.access_token')
+
+# 2. Test protected endpoint
+curl -H "Authorization: Bearer $ACCESS_TOKEN" http://localhost:3000/api/private
+
+# 3. Test scoped endpoint
+curl -H "Authorization: Bearer $ACCESS_TOKEN" http://localhost:3000/api/messages
+```
+
+### Unit testing with Jest/Vitest
+
+```javascript
+import request from 'supertest';
+import app from './app.js';
+
+describe('API Authentication', () => {
+  it('returns 401 without token', async () => {
+    const res = await request(app).get('/api/private');
+    expect(res.status).toBe(401);
+  });
+
+  it('returns 200 with valid token', async () => {
+    // Use a test token from Auth0 or a mocked JWT
+    const res = await request(app)
+      .get('/api/private')
+      .set('Authorization', `Bearer ${process.env.TEST_TOKEN}`);
+    expect(res.status).toBe(200);
+  });
+});
+```
+
+### Mocking in unit tests
+
+For unit tests, you can mock the `auth` middleware to bypass JWT validation:
+
+```javascript
+// test-utils.js
+import { jest } from '@jest/globals';
+
+export function mockAuth(payload = { sub: 'test-user' }) {
+  jest.mock('express-oauth2-jwt-bearer', () => ({
+    auth: () => (req, res, next) => {
+      req.auth = { payload };
+      next();
+    },
+    requiredScopes: (scopes) => (req, res, next) => {
+      const tokenScopes = req.auth?.payload?.scope?.split(' ') || [];
+      const missing = [scopes].flat().filter(s => !tokenScopes.includes(s));
+      if (missing.length) return res.status(403).json({ error: 'insufficient_scope' });
+      next();
+    },
+    claimIncludes: () => (req, res, next) => next(),
+  }));
+}
+```
+
+---
+
+# express-oauth2-jwt-bearer Setup Guide
+
+## Auth0 Configuration
+
+> **Agent instruction:**
+>
+> **Check if credentials are already provided in the user's prompt:** If the user's prompt already includes Auth0 Domain and API Audience (e.g. `your-tenant.us.auth0.com` and `https://api.example.com`), use them directly — skip to "Write the .env file" below. Do NOT call `AskUserQuestion` to re-confirm provided credentials, and do NOT run automatic setup.
+>
+> **Env var convention:** This skill uses the SDK-native variables `ISSUER_BASE_URL` (the full issuer URL, including `https://`) and `AUDIENCE`. `express-oauth2-jwt-bearer` reads them automatically, so `auth()` is called with no arguments.
+>
+> If credentials are NOT provided, offer setup choices:
+>
+> Use `AskUserQuestion` to ask the user:
+> "How would you like to configure Auth0 for this project?"
+> - Option A: **Automatic setup (recommended)** — use the Auth0 CLI to create the Auth0 API automatically
+> - Option B: **Manual setup** — provide Auth0 credentials manually
+>
+> **If Automatic Setup (Option A):**
+>
+> 1. **Pre-flight checks:**
+>    - Verify Auth0 CLI installed: `auth0 --version`
+>    - Verify logged in: `auth0 tenants list --csv --no-input`
+>    - If any check fails, guide user to install/login, or fall back to Option B
+>
+> 2. **Create the Auth0 API (Resource Server)** with the Auth0 CLI, then read back the identifier as `AUDIENCE`:
+>    ```bash
+>    auth0 apis create \
+>      --name "My Node API" \
+>      --identifier "https://my-api.example.com" \
+>      --json --no-input
+>    ```
+>    - The `--identifier` you choose becomes the `AUDIENCE` value your middleware validates against.
+>    - Get the tenant domain with `auth0 tenants list --csv --no-input`, then set `ISSUER_BASE_URL` to that domain prefixed with `https://`.
+>    - If an API with that identifier already exists, skip creation and reuse it (`auth0 apis list --json --no-input`).
+>
+> 3. **Write the `.env` configuration file** with the Domain + Audience (see below).
+>
+> **If Manual Setup (Option B):**
+>
+> Ask the user for:
+> - **Auth0 Domain** (e.g., `your-tenant.us.auth0.com`)
+> - **API Audience** — the API Identifier you set when creating the Auth0 API (e.g., `https://your-api.example.com`)
+>
+> Then write the `.env` file (see below).
+>
+> **Write the .env file** (both paths):
+> ```env
+> ISSUER_BASE_URL=https://your-tenant.us.auth0.com
+> AUDIENCE=https://your-api.example.com
+> PORT=3000
+> ```
+
+### Auth0 API Registration (Resource Server)
+
+The Automatic setup path runs `auth0 apis create` to register your API as a Resource Server. This produces the `AUDIENCE` value (the API Identifier) that your middleware uses for token validation.
+
+**Auth0 CLI command:**
+```bash
+auth0 apis create \
+  --name "My Node API" \
+  --identifier "https://my-api.example.com" \
+  --json --no-input
+```
+
+### Creating the Auth0 API manually (Dashboard)
+
+1. Go to [Auth0 Dashboard → APIs](https://manage.auth0.com/#/apis)
+2. Click **Create API**
+3. Set:
+   - **Name**: Your API name (e.g., "My Node API")
+   - **Identifier**: A URL-like identifier (e.g., `https://my-api.example.com`) — this becomes `AUDIENCE`
+   - **Signing Algorithm**: `RS256` (recommended)
+4. Click **Create**
+5. Note the **API Identifier** — this is your Audience value
+
+### Enable RBAC (optional)
+
+To use `claimIncludes('permissions', 'read:data')` with Auth0 RBAC:
+
+1. Go to Auth0 Dashboard → APIs → your API → Settings
+2. Enable **"Enable RBAC"**
+3. Enable **"Add Permissions in the Access Token"**
+4. Add permissions under the **Permissions** tab
+5. Assign permissions to roles, and roles to users via Auth0 Dashboard
+
+## Post-Setup Steps
+
+After completing automatic (Auth0 CLI) or manual setup:
+
+1. **Verify domain and audience** are correct in `.env`
+2. **Test the API is reachable**: `auth0 apis list --json --no-input | grep your-api`
+3. **Confirm CORS is configured** before auth middleware in your server file (see the CORS Configuration section below)
+4. **Request a test token** using M2M credentials or the Auth0 Dashboard test feature:
+   - Go to Auth0 Dashboard → APIs → your API → Test tab
+   - Click **Copy Token** to get a test access token
+
+## SDK Installation
+
+```bash
+npm install express-oauth2-jwt-bearer
+```
+
+**With additional recommended packages:**
+```bash
+npm install express-oauth2-jwt-bearer dotenv cors helmet
+npm install --save-dev @types/express @types/cors  # TypeScript projects
+```
+
+**package.json dependency:**
+```json
+{
+  "dependencies": {
+    "express-oauth2-jwt-bearer": "^1.7.4",
+    "dotenv": "^16.0.0",
+    "cors": "^2.8.5",
+    "helmet": "^7.0.0"
+  }
+}
+```
+
+## Secret Management
+
+`express-oauth2-jwt-bearer` requires only **Domain** and **Audience** — no Client Secret. The middleware validates tokens using the Auth0 JWKS (JSON Web Key Set) endpoint, which provides the public signing keys. This means:
+
+- **No client secret needed** for token validation
+- The JWKS endpoint is publicly accessible at `${ISSUER_BASE_URL}/.well-known/jwks.json`
+- The middleware fetches and caches keys automatically
+
+### .env file (development)
+
+```env
+# .env — Never commit to source control
+ISSUER_BASE_URL=https://your-tenant.us.auth0.com
+AUDIENCE=https://your-api.example.com
+PORT=3000
+```
+
+### Production environment variables
+
+Set these as environment variables in your hosting platform (not in `.env` files):
+
+| Variable | Example Value |
+|----------|--------------|
+| `ISSUER_BASE_URL` | `https://your-tenant.us.auth0.com` |
+| `AUDIENCE` | `https://your-api.example.com` |
+| `PORT` | `3000` |
+
+**Never commit `.env` to source control.** Add `.env` to `.gitignore`:
+```bash
+echo ".env" >> .gitignore
+```
+
+**Load `.env` in your entry file:**
+```javascript
+import 'dotenv/config'; // must be at the top
+// or: require('dotenv').config();
+```
+
+## Verification
+
+After setup, verify everything is working:
+
+1. **Start the server:**
+   ```bash
+   node server.js
+   # or: npm start
+   ```
+
+2. **Test public endpoint:**
+   ```bash
+   curl http://localhost:3000/api/public
+   # Expected: 200 OK
+   ```
+
+3. **Test protected endpoint without token:**
+   ```bash
+   curl http://localhost:3000/api/private
+   # Expected: 401 Unauthorized
+   ```
+
+4. **Get a test token** from Auth0 Dashboard → APIs → your API → Test tab, then:
+   ```bash
+   curl -H "Authorization: Bearer <your-test-token>" http://localhost:3000/api/private
+   # Expected: 200 OK with payload data
+   ```
diff --git a/main/.mintlify/skills/auth0/references/framework-express/index.md b/main/.mintlify/skills/auth0/references/framework-express/index.md
new file mode 100644
index 0000000000..7322487c34
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-express/index.md
@@ -0,0 +1,817 @@
+
+# Auth0 Express Integration
+
+Add authentication to Express.js web applications using express-openid-connect.
+
+## Prerequisites
+
+- Express.js application
+- Auth0 account and application configured
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **Single Page Applications** - Use the Auth0 integration workflow for React, Vue, or Angular for client-side auth
+- **Next.js applications** - Use the Auth0 integration workflow for Next.js, which handles both client and server
+- **Mobile applications** - Use the Auth0 integration workflow for React Native/Expo
+- **Stateless APIs** - Use JWT validation middleware instead of session-based auth
+- **Microservices** - Use JWT validation for service-to-service auth
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+npm install express-openid-connect dotenv
+```
+
+### 2. Configure Environment
+
+**For automated setup with Auth0 CLI**, see the Setup Guide section below for complete scripts.
+
+**For manual setup:**
+
+Create `.env`:
+
+```bash
+SECRET=<openssl-rand-hex-32>
+BASE_URL=http://localhost:3000
+CLIENT_ID=your-client-id
+CLIENT_SECRET=your-client-secret
+ISSUER_BASE_URL=https://your-tenant.auth0.com
+```
+
+Generate secret: `openssl rand -hex 32`
+
+### 3. Configure Auth Middleware
+
+Update your Express app (`app.js` or `index.js`):
+
+```javascript
+require('dotenv').config();
+const express = require('express');
+const { auth, requiresAuth } = require('express-openid-connect');
+
+const app = express();
+
+// Configure Auth0 middleware
+app.use(auth({
+  authRequired: false,  // Don't require auth for all routes
+  auth0Logout: true,    // Enable logout endpoint
+  secret: process.env.SECRET,
+  baseURL: process.env.BASE_URL,
+  clientID: process.env.CLIENT_ID,
+  issuerBaseURL: process.env.ISSUER_BASE_URL,
+  clientSecret: process.env.CLIENT_SECRET
+}));
+
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+This automatically creates:
+- `/login` - Login endpoint
+- `/logout` - Logout endpoint
+- `/callback` - OAuth callback
+
+### 4. Add Routes
+
+```javascript
+// Public route
+app.get('/', (req, res) => {
+  res.send(req.oidc.isAuthenticated() ? 'Logged in' : 'Logged out');
+});
+
+// Protected route
+app.get('/profile', requiresAuth(), (req, res) => {
+  res.send(`
+    <h1>Profile</h1>
+    <p>Name: ${req.oidc.user.name}</p>
+    <p>Email: ${req.oidc.user.email}</p>
+    <pre>${JSON.stringify(req.oidc.user, null, 2)}</pre>
+    <a href="/logout">Logout</a>
+  `);
+});
+
+// Login/logout links
+app.get('/', (req, res) => {
+  res.send(`
+    ${req.oidc.isAuthenticated() ? `
+      <p>Welcome, ${req.oidc.user.name}!</p>
+      <a href="/profile">Profile</a>
+      <a href="/logout">Logout</a>
+    ` : `
+      <a href="/login">Login</a>
+    `}
+  `);
+});
+```
+
+### 5. Test Authentication
+
+Start your server:
+
+```bash
+node app.js
+```
+
+Visit `http://localhost:3000` and test the login flow.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Forgot to add callback URL in Auth0 Dashboard | Add `/callback` path to Allowed Callback URLs (e.g., `http://localhost:3000/callback`) |
+| Missing or weak SECRET | Generate secure secret with `openssl rand -hex 32` and store in .env as `SECRET` |
+| Setting authRequired: true globally | Set to false and use `requiresAuth()` middleware on specific routes |
+| App created as SPA type in Auth0 | Must be Regular Web Application type for server-side auth |
+| Session secret exposed in code | Always use environment variables, never hardcode secrets |
+| Wrong baseURL for production | Update BASE_URL to match your production domain |
+| Not handling logout returnTo | Add your domain to Allowed Logout URLs in Auth0 Dashboard |
+
+## Related Skills
+
+- Auth0 setup — set it up with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Migrate from another auth provider → migration (migrate)
+- Multi-factor authentication → MFA (feature:mfa)
+- Manage Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+- B2B multi-tenancy → Organizations (feature:organizations)
+
+## Quick Reference
+
+**Middleware Options:**
+- `authRequired` - Require auth for all routes (default: false)
+- `auth0Logout` - Enable /logout endpoint (default: false)
+- `secret` - Session secret (required)
+- `baseURL` - Application URL (required)
+- `clientID` - Auth0 client ID (required)
+- `issuerBaseURL` - Auth0 tenant URL (required)
+
+**Request Properties:**
+- `req.oidc.isAuthenticated()` - Check if user is logged in
+- `req.oidc.user` - User profile object
+- `req.oidc.accessToken` - Access token for API calls
+- `req.oidc.idToken` - ID token
+- `req.oidc.refreshToken` - Refresh token
+
+**Common Use Cases:**
+- Protected routes → Use `requiresAuth()` middleware (see Step 4)
+- Check auth status → `req.oidc.isAuthenticated()`
+- Get user info → `req.oidc.user`
+- Call APIs → see the Calling APIs section below
+
+## References
+
+- [Express OpenID Connect Documentation](https://auth0.com/docs/libraries/express-openid-connect)
+- [Auth0 Express Quickstart](https://auth0.com/docs/quickstart/webapp/express)
+- [SDK GitHub Repository](https://github.com/auth0/express-openid-connect)
+- [Express.js Documentation](https://expressjs.com/)
+
+---
+
+## Common Patterns
+
+### Template Rendering with EJS
+
+**Install EJS:**
+```bash
+npm install ejs
+```
+
+**Configure:**
+```javascript
+app.set('view engine', 'ejs');
+```
+
+**Create `views/index.ejs`:**
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Auth0 App</title>
+</head>
+<body>
+  <% if (isAuthenticated) { %>
+    <h1>Welcome, <%= user.name %>!</h1>
+    <img src="<%= user.picture %>" alt="<%= user.name %>" />
+    <p><%= user.email %></p>
+    <a href="/logout">Logout</a>
+  <% } else { %>
+    <h1>Please log in</h1>
+    <a href="/login">Login</a>
+  <% } %>
+</body>
+</html>
+```
+
+**Update route:**
+```javascript
+app.get('/', (req, res) => {
+  res.render('index', {
+    isAuthenticated: req.oidc.isAuthenticated(),
+    user: req.oidc.user
+  });
+});
+```
+
+---
+
+### Custom Login with Return URL
+
+```javascript
+app.get('/dashboard', requiresAuth(), (req, res) => {
+  res.render('dashboard', { user: req.oidc.user });
+});
+
+// Login redirects to dashboard after authentication
+app.get('/login-to-dashboard', (req, res) => {
+  res.oidc.login({
+    returnTo: '/dashboard'
+  });
+});
+```
+
+---
+
+### Access User Information
+
+```javascript
+app.get('/user-info', requiresAuth(), (req, res) => {
+  // User profile
+  const user = req.oidc.user;
+
+  // Check if authenticated
+  const isAuth = req.oidc.isAuthenticated();
+
+  // ID token
+  const idToken = req.oidc.idToken;
+
+  // ID token claims
+  const idTokenClaims = req.oidc.idTokenClaims;
+
+  res.json({
+    user,
+    isAuthenticated: isAuth,
+    idToken: idToken
+  });
+});
+```
+
+---
+
+### Call External APIs
+
+```javascript
+app.get('/call-api', requiresAuth(), async (req, res) => {
+  try {
+    // Extract the token string from the access token object
+    const { access_token } = req.oidc.accessToken;
+
+    const response = await fetch('https://api.example.com/data', {
+      headers: {
+        Authorization: `Bearer ${access_token}`
+      }
+    });
+
+    const data = await response.json();
+    res.json(data);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+```
+
+**Note:** To call APIs, add `authorizationParams` to middleware config:
+
+```javascript
+app.use(auth({
+  authRequired: false,
+  auth0Logout: true,
+  secret: process.env.SECRET,
+  baseURL: process.env.BASE_URL,
+  clientID: process.env.CLIENT_ID,
+  issuerBaseURL: process.env.ISSUER_BASE_URL,
+  clientSecret: process.env.CLIENT_SECRET,
+  authorizationParams: {
+    response_type: 'code',
+    audience: 'https://your-api-identifier',  // Add this
+    scope: 'openid profile email'
+  }
+}));
+```
+
+---
+
+### Custom Logout Redirect
+
+```javascript
+app.get('/custom-logout', (req, res) => {
+  res.oidc.logout({
+    returnTo: 'https://app.example.com/goodbye'
+  });
+});
+```
+
+---
+
+### Conditional Authentication
+
+```javascript
+// Protect specific routes
+app.get('/admin', requiresAuth(), (req, res) => {
+  // Only authenticated users can access
+  res.render('admin', { user: req.oidc.user });
+});
+
+// Optional authentication (check manually)
+app.get('/home', (req, res) => {
+  if (req.oidc.isAuthenticated()) {
+    res.render('home-auth', { user: req.oidc.user });
+  } else {
+    res.render('home-public');
+  }
+});
+```
+
+---
+
+## Configuration Options
+
+### Complete Middleware Configuration
+
+```javascript
+app.use(auth({
+  authRequired: false,          // Don't require auth globally
+  auth0Logout: true,            // Enable logout route
+  secret: process.env.SECRET,
+  baseURL: process.env.BASE_URL,
+  clientID: process.env.CLIENT_ID,
+  issuerBaseURL: process.env.ISSUER_BASE_URL,
+  clientSecret: process.env.CLIENT_SECRET,
+
+  // Authorization parameters
+  authorizationParams: {
+    response_type: 'code',
+    audience: 'https://your-api-identifier',
+    scope: 'openid profile email'
+  },
+
+  // Custom routes
+  routes: {
+    login: '/auth/login',       // Default: /login
+    logout: '/auth/logout',     // Default: /logout
+    callback: '/auth/callback', // Default: /callback
+    postLogoutRedirect: '/'     // Where to go after logout
+  },
+
+  // Session configuration
+  session: {
+    rolling: true,              // Extend session on activity
+    rollingDuration: 86400,     // 24 hours in seconds
+    absoluteDuration: 604800    // 7 days in seconds
+  }
+}));
+```
+
+---
+
+## Testing
+
+1. Start your server: `node app.js` or `npm start`
+2. Visit `http://localhost:3000`
+3. Click "Login" - redirects to Auth0
+4. Complete authentication
+5. Verify redirect back with session established
+6. Visit `/profile` to see protected route
+7. Click "Logout" and verify session cleared
+
+---
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "Missing required parameter: state" | Ensure `SECRET` is set and at least 32 characters |
+| Session not persisting | Check cookies are enabled and `BASE_URL` is correct |
+| Infinite redirect loop | Check `authRequired: false` for middleware config |
+| Callback URL mismatch | Verify `BASE_URL/callback` is in Auth0 allowed callback URLs |
+| "Invalid redirect URI" | Ensure callback URL in Auth0 matches `BASE_URL` exactly |
+
+---
+
+## Advanced Configuration Options
+
+### attemptSilentLogin
+
+Automatically attempt silent login on the first unauthenticated request. Useful for checking if user is already logged in at their IDP without showing login prompt.
+
+```javascript
+app.use(auth({
+  authRequired: false,
+  attemptSilentLogin: true  // Try silent auth first (default: false)
+}));
+```
+
+### errorOnRequiredAuth
+
+Return 401 error instead of redirecting to login for protected routes. Useful for API endpoints that should return status codes instead of HTML redirects.
+
+```javascript
+app.use(auth({
+  errorOnRequiredAuth: true  // Return 401 instead of redirecting (default: false)
+}));
+```
+
+### idpLogout
+
+Log the user out from Auth0 (federated logout) when they log out of your application, not just the application session.
+
+```javascript
+app.use(auth({
+  idpLogout: true  // Also logout from Auth0 (default: false)
+}));
+```
+
+### afterCallback
+
+Execute custom logic after authentication callback, such as fetching additional user data or modifying the session.
+
+```javascript
+app.use(auth({
+  afterCallback: async (req, res, session, state) => {
+    // Fetch additional user profile data
+    const userProfile = await fetchUserProfile(session.user.sub);
+
+    // Add to session
+    return {
+      ...session,
+      userProfile  // Access via req.oidc.userProfile
+    };
+  }
+}));
+```
+
+### getLoginState
+
+Customize the state parameter passed during login to preserve custom application state through the authentication flow.
+
+```javascript
+app.use(auth({
+  getLoginState(req, options) {
+    return {
+      returnTo: options.returnTo || req.originalUrl,
+      customData: 'custom-value'  // Your custom state
+    };
+  }
+}));
+```
+
+---
+
+## Security Considerations
+
+- **Keep secrets secure** - Never commit `.env` to version control
+- **Use HTTPS in production** - Auth0 requires secure callback URLs
+- **Rotate secrets regularly** - Update `SECRET` periodically
+- **Validate on server** - Authentication is server-side, tokens are secure
+- **Configure session properly** - Set appropriate session durations
+- **Use helmet** - Add security headers with `npm install helmet`
+
+```javascript
+const helmet = require('helmet');
+app.use(helmet());
+```
+
+---
+
+# Auth0 Express Integration Patterns
+
+Server-side authentication patterns for Express.js.
+
+---
+
+## Protected Routes
+
+### Single Route
+
+```javascript
+const { requiresAuth } = require('express-openid-connect');
+
+app.get('/admin', requiresAuth(), (req, res) => {
+  res.send(`Admin: ${req.oidc.user.name}`);
+});
+```
+
+### Multiple Routes
+
+```javascript
+// Protect all /admin routes
+app.use('/admin', requiresAuth());
+
+app.get('/admin/dashboard', (req, res) => {
+  res.send('Dashboard');
+});
+
+app.get('/admin/settings', (req, res) => {
+  res.send('Settings');
+});
+```
+
+### Require Auth Globally
+
+```javascript
+app.use(auth({
+  authRequired: true  // All routes require authentication
+}));
+
+// Make specific routes public
+app.get('/public', (req, res) => {
+  res.send('Public page');
+});
+```
+
+---
+
+## Calling APIs
+
+### Get Access Token
+
+```javascript
+app.get('/api-call', requiresAuth(), async (req, res) => {
+  const { access_token } = req.oidc.accessToken;
+
+  const response = await fetch('https://api.example.com/data', {
+    headers: { Authorization: `Bearer ${access_token}` }
+  });
+
+  const data = await response.json();
+  res.json(data);
+});
+```
+
+Configure audience in middleware:
+
+```javascript
+app.use(auth({
+  authorizationParams: {
+    audience: 'https://your-api-identifier'
+  },
+  // ... other config
+}));
+```
+
+---
+
+## Custom Login/Logout
+
+### Custom Login Handler
+
+```javascript
+app.get('/custom-login', (req, res) => {
+  res.oidc.login({
+    returnTo: '/dashboard',
+    authorizationParams: {
+      connection: 'google-oauth2'
+    }
+  });
+});
+```
+
+### Custom Logout Handler
+
+```javascript
+app.get('/custom-logout', (req, res) => {
+  res.oidc.logout({
+    returnTo: '/goodbye'
+  });
+});
+```
+
+---
+
+## Silent Authentication
+
+### Automatic Silent Login
+
+Check if user is already authenticated at their IDP without forcing a login prompt.
+
+```javascript
+const { auth, attemptSilentLogin } = require('express-openid-connect');
+
+app.use(auth({
+  authRequired: false
+}));
+
+// Try silent authentication on first visit
+app.use(attemptSilentLogin());
+
+// Your routes
+app.get('/', (req, res) => {
+  if (req.oidc.isAuthenticated()) {
+    res.send(`Welcome back, ${req.oidc.user.name}!`);
+  } else {
+    res.send('Not logged in <a href="/login">Login</a>');
+  }
+});
+```
+
+**How it works:**
+- On the user's first visit, redirects to Auth0 with `prompt=none`
+- If user has active IDP session, they're silently logged in
+- If not, they see your page as anonymous
+- Uses a cookie to prevent repeated silent login attempts
+
+**Use cases:**
+- Show login/logout button based on IDP session status
+- Pre-authenticate users who have existing IDP sessions
+- Provide seamless experience for returning users
+
+---
+
+## Session Management
+
+### Access User Info
+
+```javascript
+app.get('/user', requiresAuth(), (req, res) => {
+  res.json({
+    isAuthenticated: req.oidc.isAuthenticated(),
+    user: req.oidc.user,
+    idToken: req.oidc.idToken,
+    accessToken: req.oidc.accessToken
+  });
+});
+```
+
+### Refresh Tokens
+
+```javascript
+app.use(auth({
+  authorizationParams: {
+    scope: 'openid profile email offline_access'
+  }
+}));
+
+// Access refresh token
+app.get('/refresh', requiresAuth(), (req, res) => {
+  const refreshToken = req.oidc.refreshToken;
+  // Use refresh token
+});
+```
+
+---
+
+## Error Handling
+
+```javascript
+app.use((err, req, res, next) => {
+  if (err.name === 'UnauthorizedError') {
+    res.status(401).send('Unauthorized');
+  } else {
+    next(err);
+  }
+});
+```
+
+---
+
+# Auth0 Express Setup Guide
+
+Setup instructions for Express.js applications.
+
+---
+
+## Quick Setup (Automated)
+
+Below automates the setup, except for the CLIENT_SECRET. Inform the user that they have to fill in the value for the CLIENT_SECRET themselves.
+
+**Never read the contents of `.env.local` or `.env` at any point during setup.** The file may contain sensitive secrets that should not be exposed in the LLM context. If you determine you need to read the file for any reason, ask the user for explicit permission before doing so — do not proceed until the user confirms.
+
+**Before running any part of this setup that writes to an env file, you MUST ask the user for explicit confirmation.** Follow the steps below precisely.
+
+### Step 1: Check for existing env files and confirm with user
+
+Before writing credentials, check which env files exist:
+
+```bash
+test -f .env.local && echo "ENV_LOCAL_EXISTS" || echo "ENV_LOCAL_NOT_FOUND"
+test -f .env && echo "ENV_EXISTS" || echo "ENV_NOT_FOUND"
+```
+
+Then ask the user for explicit confirmation before proceeding — do not continue until the user confirms:
+
+- If `.env.local` exists, ask:
+  - Question: "A `.env.local` file already exists and may contain secrets unrelated to Auth0. This setup will append Auth0 credentials to it without modifying existing content. Do you want to proceed?"
+  - Options: "Yes, append to existing .env.local" / "No, I'll update it manually"
+
+- If `.env.local` does **not** exist but `.env` exists, ask:
+  - Question: "A `.env` file already exists and may contain secrets unrelated to Auth0. This setup will append Auth0 credentials to it without modifying existing content. Do you want to proceed?"
+  - Options: "Yes, append to existing .env" / "No, I'll update it manually"
+
+- If neither exists, ask:
+  - Question: "This setup will create a `.env.local` file containing Auth0 credentials (CLIENT_ID, ISSUER_BASE_URL, SECRET) and a placeholder for CLIENT_SECRET. Do you want to proceed?"
+  - Options: "Yes, create .env.local" / "No, I'll configure it manually"
+
+**Do not proceed with writing to any env file unless the user selects the confirmation option.**
+
+### Step 2: Run automated setup (only after confirmation)
+
+```bash
+#!/bin/bash
+
+# Install Auth0 CLI
+if ! command -v auth0 &> /dev/null; then
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    brew install auth0/auth0-cli/auth0
+  else
+    # Download and review the install script before executing
+    curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh -o /tmp/auth0-install.sh
+    echo "⚠️  Review the install script at /tmp/auth0-install.sh before running"
+    sh /tmp/auth0-install.sh -b /usr/local/bin
+    rm /tmp/auth0-install.sh
+  fi
+fi
+
+# Login
+auth0 login 2>/dev/null || auth0 login
+
+# Create/select app
+auth0 apps list
+read -p "Enter app ID (or Enter to create): " APP_ID
+
+if [ -z "$APP_ID" ]; then
+  APP_ID=$(auth0 apps create --name "${PWD##*/}-express" --type regular \
+    --callbacks "http://localhost:3000/callback" \
+    --logout-urls "http://localhost:3000" \
+    --metadata "created_by=agent_skills" \
+    --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+fi
+
+# Get credentials
+DOMAIN=$(auth0 apps show "$APP_ID" --json | grep -o '"domain":"[^"]*' | cut -d'"' -f4)
+CLIENT_ID=$(auth0 apps show "$APP_ID" --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+SECRET=$(openssl rand -hex 32)
+
+# Determine target env file
+if [ -f .env.local ]; then
+  TARGET_FILE=".env.local"
+elif [ -f .env ]; then
+  TARGET_FILE=".env"
+else
+  TARGET_FILE=".env.local"
+fi
+
+# Append Auth0 credentials
+cat >> "$TARGET_FILE" << ENVEOF
+SECRET=$SECRET
+BASE_URL=http://localhost:3000
+CLIENT_ID=$CLIENT_ID
+CLIENT_SECRET='YOUR_CLIENT_SECRET'
+ISSUER_BASE_URL=https://$DOMAIN
+ENVEOF
+
+echo "✅ Auth0 credentials written to $TARGET_FILE"
+```
+
+After the script runs, remind the user to:
+1. Open the env file that was written and replace `YOUR_CLIENT_SECRET` with the actual client secret from Auth0.
+2. Ensure the env file is listed in `.gitignore` to avoid accidentally committing secrets.
+
+---
+
+## Manual Setup
+
+### Install Packages
+
+```bash
+npm install express-openid-connect dotenv
+```
+
+### Create .env
+
+```bash
+SECRET=<openssl-rand-hex-32>
+BASE_URL=http://localhost:3000
+CLIENT_ID=your-client-id
+CLIENT_SECRET=your-client-secret
+ISSUER_BASE_URL=https://your-tenant.auth0.com
+```
+
+### Get Auth0 Credentials
+
+CLI: `auth0 apps show <app-id> --reveal-secrets`
+
+Dashboard: Create Regular Web Application, copy credentials
+
+---
+
+## Troubleshooting
+
+**"Invalid state" error:** Regenerate `SECRET`
+
+**Client secret required:** Express uses Regular Web Application type
+
+**Callback URL mismatch:** Add `/callback` to Allowed Callback URLs
+
+---
diff --git a/main/.mintlify/skills/auth0/references/framework-fastapi-api/index.md b/main/.mintlify/skills/auth0/references/framework-fastapi-api/index.md
new file mode 100644
index 0000000000..ef64abfe55
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-fastapi-api/index.md
@@ -0,0 +1,1132 @@
+
+# Auth0 FastAPI API Integration
+
+Protect FastAPI API endpoints with JWT access token validation using `auth0-fastapi-api`.
+
+> **Note:** This SDK is currently in beta. The API surface may change before the stable 1.0 release. Check [PyPI](https://pypi.org/project/auth0-fastapi-api/) for the latest version. Requires Python >= 3.9 and FastAPI >= 0.115.11.
+
+## Prerequisites
+
+- FastAPI application (Python 3.9+)
+- Auth0 API resource configured (not an Application — must be an API)
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **Server-rendered web applications** — Use a session-based login/logout flow instead
+- **Single Page Applications** — Use the Auth0 integration workflow for React, Vue, or Angular for client-side auth
+- **Mobile applications** — Use the Auth0 integration workflow for React Native or Android
+- **Issuing tokens** — This skill is for *validating* access tokens, not issuing them
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+pip install auth0-fastapi-api python-dotenv
+```
+
+### 2. Create Auth0 API
+
+You need an **API** (not Application) in Auth0.
+
+> **STOP — ask the user before proceeding.**
+>
+> Ask exactly this question and wait for their answer before doing anything else:
+>
+> > "How would you like to create the Auth0 API resource?
+> > 1. **Automated** — I'll run Auth0 CLI scripts that create the resource and write the exact values to your `.env` automatically.
+> > 2. **Manual** — You create the API yourself in the Auth0 Dashboard (or via `auth0 apis create`) and provide me the Domain and Audience.
+> >
+> > Which do you prefer? (1 = Automated / 2 = Manual)"
+>
+> Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.
+
+**If the user chose Automated**, follow the Setup Guide section below for complete CLI scripts. The automated path writes `.env` for you — skip Step 3 below and proceed directly to Step 4.
+
+**If the user chose Manual**, follow the Setup Guide section below (Manual Setup) for full instructions. Then continue with Step 3 below.
+
+Quick reference for manual API creation:
+
+```bash
+# Using Auth0 CLI
+auth0 apis create \
+  --name "My FastAPI API" \
+  --identifier https://my-api.example.com
+```
+
+Or create manually in Auth0 Dashboard → Applications → APIs
+
+### 3. Configure Environment
+
+Create `.env`:
+
+```bash
+AUTH0_DOMAIN=your-tenant.us.auth0.com
+AUTH0_AUDIENCE=https://your-api.example.com
+```
+
+`AUTH0_DOMAIN` is your Auth0 tenant domain (without `https://`). `AUTH0_AUDIENCE` is the API identifier you set when creating the API resource in Auth0.
+
+### 4. Initialize Auth0
+
+```python
+import os
+from fastapi import FastAPI, Depends
+from fastapi_plugin import Auth0FastAPI
+from dotenv import load_dotenv
+
+load_dotenv()
+
+app = FastAPI()
+
+auth0 = Auth0FastAPI(
+    domain=os.getenv("AUTH0_DOMAIN"),
+    audience=os.getenv("AUTH0_AUDIENCE"),
+)
+```
+
+Create one `Auth0FastAPI` instance per application and reuse it across routes. Never hardcode the domain or audience — always use environment variables.
+
+### 5. Protect Routes
+
+```python
+# Require any valid access token
+@app.get("/api/private")
+async def private(claims: dict = Depends(auth0.require_auth())):
+    return {"user": claims["sub"]}
+
+# No authentication required
+@app.get("/api/public")
+async def public():
+    return {"message": "Public endpoint"}
+```
+
+The `require_auth()` dependency validates the Bearer token, verifies the issuer and audience, and returns the decoded JWT claims.
+
+Error responses:
+- **400** `invalid_request` — Missing or malformed Authorization header
+- **401** `invalid_token` — Expired token, invalid signature, wrong issuer/audience
+- **403** `insufficient_scope` — Valid token but missing required scopes
+- **500** `internal_server_error` — Unexpected errors
+
+Response body format: `{"detail": {"error": "...", "error_description": "..."}}`
+
+### 6. Protect Routes with Scope Checks
+
+```python
+# Requires the read:messages scope
+@app.get("/api/messages")
+async def get_messages(claims: dict = Depends(auth0.require_auth(scopes="read:messages"))):
+    return {"messages": []}
+
+# Requires both read:data and write:data scopes
+@app.post("/api/data")
+async def write_data(claims: dict = Depends(auth0.require_auth(scopes=["read:data", "write:data"]))):
+    return {"created": True}
+```
+
+`require_auth(scopes=...)` checks the `scope` claim in the JWT. All specified scopes must be present (AND logic). Missing scopes return **403**.
+
+### 7. Access Token Claims
+
+The decoded JWT claims are returned directly from the dependency:
+
+```python
+@app.get("/api/profile")
+async def profile(claims: dict = Depends(auth0.require_auth())):
+    return {
+        "sub": claims["sub"],       # user ID
+        "scope": claims.get("scope"),  # granted scopes
+    }
+```
+
+Key claims:
+- `claims["sub"]` — user/client ID
+- `claims["scope"]` — space-separated granted scopes
+- `claims["iss"]` — issuer (your Auth0 domain URL)
+- `claims["aud"]` — audience
+- `claims["exp"]` — expiration timestamp
+- `claims["iat"]` — issued-at timestamp
+
+### 8. Protect Routes Without Needing Claims
+
+```python
+@app.get("/api/protected", dependencies=[Depends(auth0.require_auth())])
+async def protected():
+    return {"message": "You need a valid access token to see this."}
+```
+
+### 9. Test the API
+
+```bash
+# No token — expect 401
+curl http://localhost:8000/api/private
+
+# With a valid access token
+curl http://localhost:8000/api/private \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+Get a test token via Client Credentials flow or Auth0 Dashboard → APIs → Test tab.
+Capture the token into a shell variable (`TOKEN=$(...)`) and reference `$TOKEN`
+rather than pasting the raw token inline — inline token values leak into shell
+history and terminal scrollback.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Hardcoding `domain` or `audience` in source | Always read from environment variables — never embed credentials in code |
+| Using `python-jose` or `PyJWT` directly | Not needed; `auth0-fastapi-api` handles all validation via JWKS |
+| Manually parsing `Authorization` header | The SDK extracts and validates the token automatically |
+| Calling `jwt.decode()` manually | The SDK verifies tokens against the JWKS endpoint — do not verify yourself |
+| Using `fastapi-users` for Auth0 JWT validation | That package is for user management, not Auth0 JWT verification |
+| Created an Application instead of an API in Auth0 | Must create an **API** resource (Applications → APIs) — an Application doesn't issue access tokens with the right audience |
+| Passing `domain` as full URL with `https://` | `domain` should be the bare domain, e.g. `my-tenant.us.auth0.com`, not `https://my-tenant.us.auth0.com` |
+| Using an ID token instead of an access token | Must use the **access token** for API auth — ID tokens are for the client app, not for API authorization |
+| Not configuring CORS for SPA clients | Add `CORSMiddleware` to allow requests from your frontend origin |
+| `os.getenv()` returns `None` silently | Ensure `python-dotenv` is installed and `load_dotenv()` is called before `Auth0FastAPI()` initialization — or use `os.environ[]` to fail fast |
+
+## DPoP Support
+
+Built-in proof-of-possession token binding per RFC 9449. DPoP is enabled by default in mixed mode (accepts both Bearer and DPoP tokens). See the DPoP Support section below for configuration.
+
+## Related Skills
+
+- Auth0 setup and framework detection → set up Auth0 first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- Managing Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+
+## Quick Reference
+
+**Auth0FastAPI configuration:**
+```python
+auth0 = Auth0FastAPI(
+    domain=os.getenv("AUTH0_DOMAIN"),       # required (or use domains)
+    audience=os.getenv("AUTH0_AUDIENCE"),    # required
+    dpop_enabled=True,                       # default; set False for Bearer-only
+    dpop_required=False,                     # default; set True to reject Bearer tokens
+)
+```
+
+**Route protection:**
+```python
+Depends(auth0.require_auth())                    # any valid token
+Depends(auth0.require_auth(scopes="read:res"))   # single scope
+Depends(auth0.require_auth(scopes=["r", "w"]))   # all scopes required
+```
+
+**Accessing claims:**
+```python
+claims["sub"]           # user/client ID
+claims["scope"]         # space-separated scopes
+```
+
+**Environment variables:**
+- `AUTH0_DOMAIN` — your Auth0 tenant domain (e.g. `tenant.us.auth0.com`)
+- `AUTH0_AUDIENCE` — your API identifier (e.g. `https://api.example.com`)
+
+**Common Use Cases:**
+- Protect routes → `Depends(auth0.require_auth())` (see Step 5)
+- Scope enforcement → `Depends(auth0.require_auth(scopes="..."))` (see Step 6)
+- DPoP token binding → see the DPoP Support section below
+- Reverse proxy setup → see the Reverse Proxy Support section below
+- Advanced configuration → see the API Reference section below
+
+## References
+
+- [auth0-fastapi-api GitHub](https://github.com/auth0/auth0-fastapi-api)
+- [auth0-fastapi-api on PyPI](https://pypi.org/project/auth0-fastapi-api/)
+- [Auth0 FastAPI API Quickstart](https://auth0.com/docs/quickstart/backend/fastapi)
+- [FastAPI Dependency Injection](https://fastapi.tiangolo.com/tutorial/dependencies/)
+- [Access Tokens Guide](https://auth0.com/docs/secure/tokens/access-tokens)
+
+---
+
+# Auth0 FastAPI API - API Reference
+
+Complete reference for `auth0-fastapi-api` configuration options and methods.
+
+---
+
+## Auth0FastAPI
+
+Main class for protecting FastAPI API routes with Auth0 JWT validation.
+
+```python
+from fastapi_plugin import Auth0FastAPI
+```
+
+### Constructor
+
+```python
+Auth0FastAPI(
+    domain=None,
+    audience="",
+    domains=None,
+    client_id=None,
+    client_secret=None,
+    custom_fetch=None,
+    dpop_enabled=True,
+    dpop_required=False,
+    dpop_iat_leeway=30,
+    dpop_iat_offset=300,
+    cache_adapter=None,
+    cache_ttl_seconds=600,
+    cache_max_entries=100,
+)
+```
+
+### Constructor Parameters
+
+| Parameter | Type | Default | Required | Description |
+|-----------|------|---------|----------|-------------|
+| `domain` | `str` | `None` | Yes* | Auth0 tenant domain (e.g., `my-tenant.us.auth0.com`). No `https://` prefix. Required unless `domains` is provided. |
+| `audience` | `str` | `""` | Yes | API identifier from Auth0 Dashboard. Must exactly match the API Identifier. |
+| `domains` | `list[str]` or `Callable` | `None` | No | List of allowed domain strings or a callable resolver for multi-custom domain (MCD) mode. Optional if `domain` is provided. |
+| `client_id` | `str` | `None` | No | Client ID for token exchange flows (e.g., `get_access_token_for_connection()`) |
+| `client_secret` | `str` | `None` | No | Client secret for token exchange flows |
+| `custom_fetch` | `Callable` | `None` | No | Optional HTTP fetch override. Signature: `async def custom_fetch(url, **kwargs)` |
+| `dpop_enabled` | `bool` | `True` | No | Enable DPoP support. When `True`, accepts both Bearer and DPoP tokens (unless `dpop_required=True`). |
+| `dpop_required` | `bool` | `False` | No | Require DPoP authentication and reject Bearer tokens. Only meaningful when `dpop_enabled=True`. |
+| `dpop_iat_leeway` | `int` | `30` | No | Clock skew tolerance for DPoP proof `iat` claim in seconds. |
+| `dpop_iat_offset` | `int` | `300` | No | Maximum DPoP proof age in seconds (5 minutes default). |
+| `cache_adapter` | `CacheAdapter` | `None` | No | Custom cache backend. If `None`, uses `InMemoryCache`. |
+| `cache_ttl_seconds` | `int` | `600` | No | Cache time-to-live in seconds (10 minutes default). |
+| `cache_max_entries` | `int` | `100` | No | Maximum cache entries before LRU eviction. Ignored when `cache_adapter` is provided. |
+
+**Raises:** `ValueError` if `audience` is empty or not provided.
+
+---
+
+## require_auth()
+
+Returns a FastAPI dependency that validates the incoming request and returns decoded JWT claims.
+
+```python
+auth0.require_auth(scopes=None)
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `scopes` | `str` or `list[str]` or `None` | `None` | Optional scope(s) to validate. All specified scopes must be present (AND logic). |
+
+### Return Value
+
+Returns an async FastAPI dependency function (`async def _dependency(request: Request) -> dict`).
+
+On success, the dependency returns a `dict` containing the decoded JWT claims (payload).
+
+### Usage
+
+```python
+# No scope check
+Depends(auth0.require_auth())
+
+# Single scope
+Depends(auth0.require_auth(scopes="read:data"))
+
+# Multiple scopes — all required
+Depends(auth0.require_auth(scopes=["read:data", "write:data"]))
+
+# As route dependency (no claims in handler)
+@app.get("/api/protected", dependencies=[Depends(auth0.require_auth())])
+async def protected():
+    return {"message": "Protected"}
+```
+
+### Error Responses
+
+| Status | Error Code | Cause |
+|--------|------------|-------|
+| 400 | `invalid_request` | Missing or malformed Authorization header, unsupported auth scheme |
+| 400 | `invalid_dpop_proof` | DPoP proof validation failure (missing proof, wrong algorithm, expired, thumbprint mismatch) |
+| 401 | `invalid_token` | Expired token, invalid signature, wrong issuer, wrong audience, DPoP binding mismatch |
+| 403 | `insufficient_scope` | Valid token but missing required scopes |
+| 500 | `internal_server_error` | Unexpected error during verification |
+
+All errors return:
+
+```json
+{
+    "detail": {
+        "error": "<error_code>",
+        "error_description": "<human-readable message>"
+    }
+}
+```
+
+Errors on 400/401 may include `WWW-Authenticate` response headers.
+
+---
+
+## DPoP Configuration
+
+### DPoP Modes
+
+| Mode | `dpop_enabled` | `dpop_required` | Behavior |
+|------|---------------|-----------------|----------|
+| Mixed (default) | `True` | `False` | Accepts both Bearer and DPoP tokens |
+| Required | `True` | `True` | Only DPoP tokens; rejects Bearer with 400 |
+| Disabled | `False` | `False` | Bearer only; rejects DPoP tokens |
+
+### DPoP Timing Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `dpop_iat_leeway` | `30` | Clock skew tolerance in seconds for DPoP proof `iat` claim |
+| `dpop_iat_offset` | `300` | Maximum DPoP proof age in seconds (reject older proofs as potential replay) |
+
+---
+
+## Reverse Proxy Configuration
+
+Enable `X-Forwarded-*` header trust for deployments behind reverse proxies:
+
+```python
+app.state.trust_proxy = True
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `app.state.trust_proxy` | `False` | When `True`, SDK uses `X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Forwarded-Prefix` for URL reconstruction |
+
+**Security:** Only enable when behind a trusted reverse proxy. The SDK includes path traversal protection for `X-Forwarded-Prefix`.
+
+---
+
+## Multiple Custom Domains (MCD)
+
+### Static Allowlist
+
+```python
+auth0 = Auth0FastAPI(
+    audience="<AUTH0_AUDIENCE>",
+    domains=["brand1.auth.example.com", "brand2.auth.example.com"],
+)
+```
+
+### Dynamic Domain Resolver
+
+```python
+from fastapi_plugin import DomainsResolverContext
+
+def domains_resolver(context: DomainsResolverContext) -> list:
+    request_url = context.get("request_url")
+    # Map request to allowed issuer domains
+    return ["brand1.auth.example.com"]
+
+auth0 = Auth0FastAPI(
+    audience="<AUTH0_AUDIENCE>",
+    domains=domains_resolver,
+)
+```
+
+The `DomainsResolverContext` dict contains:
+- `request_url` — The reconstructed request URL
+- `request_headers` — Request headers (lowercase keys)
+- `unverified_iss` — Issuer from token before signature verification
+
+### `domain` vs `domains`
+
+- When both are set, `domains` is used exclusively for token verification
+- `domain` is retained only for client flows (e.g., `get_access_token_for_connection()`)
+- If `domains` is not set, `domain` is used for discovery and verification
+
+---
+
+## Cache Configuration
+
+### Default Cache
+
+The SDK uses an in-memory LRU cache with:
+- `cache_ttl_seconds`: 600 (10 minutes)
+- `cache_max_entries`: 100
+
+### Custom In-Memory Cache
+
+```python
+auth0 = Auth0FastAPI(
+    domain="<AUTH0_DOMAIN>",
+    audience="<AUTH0_AUDIENCE>",
+    cache_ttl_seconds=1200,     # 20 minutes
+    cache_max_entries=200,
+)
+```
+
+### Custom Cache Adapter
+
+```python
+from fastapi_plugin import CacheAdapter
+
+class RedisCache(CacheAdapter):
+    def __init__(self, redis_client):
+        self.redis = redis_client
+
+    def get(self, key: str):
+        return self.redis.get(key)
+
+    def set(self, key: str, value, ttl_seconds=None):
+        self.redis.set(key, value, ex=ttl_seconds)
+
+    def delete(self, key: str):
+        self.redis.delete(key)
+
+    def clear(self):
+        self.redis.flushdb()
+
+auth0 = Auth0FastAPI(
+    domain="<AUTH0_DOMAIN>",
+    audience="<AUTH0_AUDIENCE>",
+    cache_adapter=RedisCache(redis_client),
+    cache_ttl_seconds=1200,
+)
+```
+
+---
+
+## Exports
+
+```python
+from fastapi_plugin import (
+    Auth0FastAPI,              # Main class
+    CacheAdapter,              # Interface for custom cache implementations
+    ConfigurationError,        # Raised when configuration is invalid
+    DomainsResolver,           # Type alias for domain resolver functions
+    DomainsResolverContext,    # Dict type for domain resolver context
+    DomainsResolverError,      # Raised when domain resolver fails
+    InMemoryCache,             # Default in-memory LRU cache
+)
+```
+
+---
+
+## api_client Property
+
+The underlying `ApiClient` instance is accessible for advanced operations:
+
+```python
+# Token exchange for upstream IdP connections
+connection_token = await auth0.api_client.get_access_token_for_connection({
+    "connection": "my-connection",
+    "access_token": user_access_token,
+})
+```
+
+Requires `client_id` and `client_secret` to be set in the constructor.
+
+---
+
+## References
+
+- [auth0-fastapi-api GitHub](https://github.com/auth0/auth0-fastapi-api)
+- [auth0-fastapi-api on PyPI](https://pypi.org/project/auth0-fastapi-api/)
+
+---
+
+# Auth0 FastAPI API Integration Patterns
+
+Advanced integration patterns for FastAPI API applications.
+
+---
+
+## Scope-Based Authorization
+
+### Define Permissions in Auth0
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Select your API
+3. Click the **Permissions** tab
+4. Add permissions matching the scopes you want to enforce (e.g., `read:messages`, `write:messages`)
+
+### Protect Routes with Scopes
+
+```python
+auth0 = Auth0FastAPI(
+    domain=os.getenv("AUTH0_DOMAIN"),
+    audience=os.getenv("AUTH0_AUDIENCE"),
+)
+
+# Single scope
+@app.get("/api/messages")
+async def get_messages(claims: dict = Depends(auth0.require_auth(scopes="read:messages"))):
+    return {"messages": []}
+
+# Multiple scopes — ALL must be present (AND logic)
+@app.delete("/api/resource/{id}")
+async def delete_resource(
+    id: str,
+    claims: dict = Depends(auth0.require_auth(scopes=["delete:data", "admin:access"]))
+):
+    return {"deleted": id}
+```
+
+### Request Tokens with Scopes
+
+Clients must request tokens that include the required scopes:
+
+```bash
+curl -X POST https://your-tenant.us.auth0.com/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_id": "YOUR_CLIENT_ID",
+    "client_secret": "YOUR_CLIENT_SECRET",
+    "audience": "https://my-api.example.com",
+    "grant_type": "client_credentials",
+    "scope": "read:messages write:messages"
+  }'
+```
+
+---
+
+## DPoP Support
+
+DPoP (Demonstrating Proof of Possession, RFC 9449) binds tokens to a specific client key pair, preventing token theft and replay.
+
+### DPoP Modes
+
+| Mode | Configuration | Behavior |
+|------|--------------|----------|
+| Mixed (default) | `dpop_enabled=True, dpop_required=False` | Accept both DPoP and Bearer tokens |
+| Required | `dpop_required=True` | Only accept DPoP tokens; reject Bearer |
+| Disabled | `dpop_enabled=False` | Bearer tokens only; reject DPoP |
+
+### Enable DPoP (Mixed Mode — Recommended for Migration)
+
+```python
+auth0 = Auth0FastAPI(
+    domain=os.getenv("AUTH0_DOMAIN"),
+    audience=os.getenv("AUTH0_AUDIENCE"),
+    dpop_enabled=True,      # default
+    dpop_required=False,    # default — accepts both Bearer and DPoP
+)
+```
+
+### DPoP Required Mode
+
+To reject standard Bearer tokens and accept only DPoP-bound tokens:
+
+```python
+auth0 = Auth0FastAPI(
+    domain=os.getenv("AUTH0_DOMAIN"),
+    audience=os.getenv("AUTH0_AUDIENCE"),
+    dpop_required=True,     # rejects Bearer tokens
+)
+```
+
+### Custom DPoP Timing
+
+```python
+auth0 = Auth0FastAPI(
+    domain=os.getenv("AUTH0_DOMAIN"),
+    audience=os.getenv("AUTH0_AUDIENCE"),
+    dpop_enabled=True,
+    dpop_iat_leeway=60,     # Clock skew tolerance in seconds (default: 30)
+    dpop_iat_offset=600,    # Maximum DPoP proof age in seconds (default: 300)
+)
+```
+
+### Bearer-Only Mode
+
+Disable DPoP support entirely:
+
+```python
+auth0 = Auth0FastAPI(
+    domain=os.getenv("AUTH0_DOMAIN"),
+    audience=os.getenv("AUTH0_AUDIENCE"),
+    dpop_enabled=False,     # Bearer tokens only
+)
+```
+
+### Client Requirements
+
+To use DPoP authentication, clients must:
+
+1. Generate an **ES256 key pair** for DPoP proof signing
+2. Include **two headers** in requests:
+   - `Authorization: DPoP <access-token>` — The DPoP-bound access token
+   - `DPoP: <proof-jwt>` — The DPoP proof JWT (ES256-signed)
+
+```bash
+# DPoP request example
+curl -H "Authorization: DPoP $TOKEN" \
+     -H "DPoP: $DPOP_PROOF_JWT" \
+     http://localhost:8000/api/protected
+```
+
+Capture the token into a shell variable (`TOKEN=$(...)`) and reference `$TOKEN`
+rather than pasting the raw token inline — inline token values leak into shell
+history and terminal scrollback.
+
+### Enable DPoP on Auth0 API
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Select your API
+3. Enable DPoP binding requirement
+
+### Migration Strategy
+
+Use mixed mode for gradual migration:
+
+```python
+# Phase 1: Accept both Bearer and DPoP (default)
+auth0 = Auth0FastAPI(
+    domain=os.getenv("AUTH0_DOMAIN"),
+    audience=os.getenv("AUTH0_AUDIENCE"),
+    dpop_enabled=True,
+    dpop_required=False,
+)
+
+# Phase 2: Enforce DPoP-only after all clients have migrated
+auth0 = Auth0FastAPI(
+    domain=os.getenv("AUTH0_DOMAIN"),
+    audience=os.getenv("AUTH0_AUDIENCE"),
+    dpop_required=True,
+)
+```
+
+### DPoP Error Responses
+
+DPoP-specific validation failures return **400** with error code `invalid_dpop_proof`:
+
+- Missing DPoP proof header
+- Wrong algorithm (must be ES256)
+- Expired proof (older than `dpop_iat_offset`)
+- Thumbprint mismatch between proof and token binding
+
+DPoP access token binding mismatches return **401** with `invalid_token`.
+
+---
+
+## Reverse Proxy Support
+
+When deploying behind a reverse proxy (nginx, AWS ALB, Cloudflare CDN), you **must** enable proxy trust for DPoP validation to work correctly.
+
+### Configuration
+
+```python
+from fastapi import FastAPI
+from fastapi_plugin import Auth0FastAPI
+
+app = FastAPI()
+
+# Enable proxy trust — REQUIRED when behind a reverse proxy
+app.state.trust_proxy = True
+
+auth0 = Auth0FastAPI(
+    domain=os.getenv("AUTH0_DOMAIN"),
+    audience=os.getenv("AUTH0_AUDIENCE"),
+    dpop_enabled=True,
+)
+```
+
+### Why This Matters
+
+- DPoP validation requires matching the exact URL the client used
+- Behind a proxy, your app sees internal URLs (e.g., `http://localhost:8000/api`)
+- The client's DPoP proof contains the public URL (e.g., `https://api.example.com/api`)
+- Without `trust_proxy=True`, DPoP validation will fail
+
+### Supported Headers
+
+When `trust_proxy=True`, the SDK reads:
+- `X-Forwarded-Proto` — Overrides scheme (http/https)
+- `X-Forwarded-Host` — Overrides host (handles comma-separated values for multiple proxies)
+- `X-Forwarded-Prefix` — Prepends path prefix (with path traversal protection)
+
+### Nginx Configuration Example
+
+```nginx
+location /api {
+    proxy_pass http://backend:8000;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Host $host;
+    proxy_set_header X-Forwarded-Prefix /api;
+}
+```
+
+**Important:** Only enable `trust_proxy=True` when your app is actually behind a trusted reverse proxy. Never enable for direct internet-facing deployments — it allows header injection attacks.
+
+---
+
+## Accessing User Claims
+
+### Standard Claims
+
+```python
+@app.get("/api/profile")
+async def profile(claims: dict = Depends(auth0.require_auth())):
+    return {
+        "user_id": claims["sub"],
+        "scopes": claims.get("scope", "").split(),
+        "issuer": claims["iss"],
+    }
+```
+
+### Custom Claims
+
+If your tokens include custom claims (added via Auth0 Actions), access them directly:
+
+```python
+@app.get("/api/custom")
+async def custom_claims(claims: dict = Depends(auth0.require_auth())):
+    permissions = claims.get("permissions", [])
+    role = claims.get("https://example.com/role")
+    return {"permissions": permissions, "role": role}
+```
+
+Custom claims added via Auth0 Actions use namespaced keys, e.g., `https://example.com/role`.
+
+### Common JWT Claims
+
+| Claim | Description |
+|-------|-------------|
+| `sub` | User ID (subject) |
+| `scope` | Space-separated list of granted scopes |
+| `aud` | Audience (your API identifier) |
+| `iss` | Issuer (your Auth0 tenant URL) |
+| `exp` | Expiration timestamp |
+| `iat` | Issued-at timestamp |
+
+---
+
+## Error Handling
+
+### Standard Error Responses
+
+| Status | Error Code | Cause | Fix |
+|--------|------------|-------|-----|
+| 400 | `invalid_request` | Missing or malformed Authorization header | Include valid `Authorization: Bearer <token>` header |
+| 400 | `invalid_dpop_proof` | Invalid DPoP proof JWT (wrong algorithm, expired, missing) | Generate a valid ES256-signed DPoP proof |
+| 401 | `invalid_token` | Expired token, invalid signature, wrong issuer/audience | Request a fresh access token with correct audience |
+| 403 | `insufficient_scope` | Token lacks required scopes | Request token with required scopes |
+| 500 | `internal_server_error` | Unexpected server error | Check server logs |
+
+### Response Format
+
+All error responses follow this structure:
+
+```json
+{
+    "detail": {
+        "error": "invalid_token",
+        "error_description": "Token has expired"
+    }
+}
+```
+
+Responses on 400/401 errors may include `WWW-Authenticate` headers with error details.
+
+### Custom Error Handling
+
+Wrap protected routes with try/except for application-level error handling:
+
+```python
+from fastapi import HTTPException
+from fastapi.responses import JSONResponse
+
+@app.exception_handler(HTTPException)
+async def custom_http_exception_handler(request, exc):
+    if exc.status_code in (401, 403):
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={
+                "error": exc.detail.get("error", "unauthorized"),
+                "message": exc.detail.get("error_description", "Authentication required"),
+            },
+            headers=exc.headers or {},
+        )
+    raise exc
+```
+
+---
+
+## Mixed Public and Protected Endpoints
+
+```python
+from fastapi import FastAPI, Depends
+from fastapi_plugin import Auth0FastAPI
+
+app = FastAPI()
+auth0 = Auth0FastAPI(
+    domain=os.getenv("AUTH0_DOMAIN"),
+    audience=os.getenv("AUTH0_AUDIENCE"),
+)
+
+# Public — no auth needed
+@app.get("/api/public")
+async def public():
+    return {"message": "Public endpoint"}
+
+# Protected — requires valid JWT
+@app.get("/api/private")
+async def private(claims: dict = Depends(auth0.require_auth())):
+    return {"message": "Private endpoint", "user_id": claims["sub"]}
+
+# Protected with scope
+@app.get("/api/messages")
+async def messages(claims: dict = Depends(auth0.require_auth(scopes="read:messages"))):
+    return {"messages": []}
+```
+
+---
+
+## CORS Configuration
+
+When your API receives requests from a browser-based SPA, configure CORS:
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["https://spa.example.com"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["Authorization", "Content-Type", "DPoP"],
+)
+```
+
+---
+
+## Testing
+
+### Basic Testing with FastAPI TestClient
+
+```python
+from fastapi import FastAPI, Depends
+from fastapi.testclient import TestClient
+from fastapi_plugin import Auth0FastAPI
+
+app = FastAPI()
+auth0 = Auth0FastAPI(domain="my-tenant.us.auth0.com", audience="my-api")
+
+@app.get("/public")
+async def public():
+    return {"message": "No token required"}
+
+@app.get("/secure")
+async def secure(claims: dict = Depends(auth0.require_auth())):
+    return {"message": f"Hello {claims['sub']}"}
+
+def test_public_route():
+    client = TestClient(app)
+    response = client.get("/public")
+    assert response.status_code == 200
+
+def test_protected_route_without_token():
+    client = TestClient(app)
+    response = client.get("/secure")
+    assert response.status_code == 400  # Missing Authorization header
+```
+
+### Integration Testing with Real Tokens
+
+```bash
+# Get a test token via Auth0 CLI
+auth0 test token --audience https://my-api.example.com
+```
+
+```python
+def test_protected_route_with_token():
+    client = TestClient(app)
+    response = client.get(
+        "/secure",
+        headers={"Authorization": "Bearer YOUR_TEST_TOKEN"},
+    )
+    assert response.status_code == 200
+```
+
+### Mocking Authentication
+
+For unit tests without hitting Auth0's JWKS endpoints, use `pytest-httpx` or mock the verification method:
+
+```python
+from unittest.mock import AsyncMock, patch
+
+@patch.object(auth0.api_client, "verify_request", new_callable=AsyncMock)
+async def test_with_mocked_auth(mock_verify):
+    mock_verify.return_value = {"sub": "user123", "scope": "read:data"}
+    client = TestClient(app)
+    response = client.get(
+        "/secure",
+        headers={"Authorization": "Bearer mock-token"},
+    )
+    assert response.status_code == 200
+```
+
+---
+
+## Security Considerations
+
+- **Never hardcode Domain or Audience** — Always use environment variables or configuration files
+- **Use HTTPS in production** — Auth0 requires HTTPS for token validation
+- **Use minimal scopes** — Only request and enforce scopes your API actually needs
+- **Keep packages updated** — Regularly update `auth0-fastapi-api` for security patches
+- **Only enable `trust_proxy` behind trusted proxies** — Never for direct internet-facing deployments
+- **Validate access tokens, not ID tokens** — ID tokens are for the client app, access tokens are for API authorization
+
+---
+
+---
+
+# Auth0 FastAPI API Setup Guide
+
+Setup instructions for FastAPI API applications.
+
+---
+
+## Quick Setup (Automated)
+
+Below uses the Auth0 CLI to create an Auth0 API resource and retrieve your credentials.
+
+### Step 1: Install Auth0 CLI and create API resource
+
+```bash
+# Install Auth0 CLI (macOS)
+brew install auth0/auth0-cli/auth0
+
+# Login
+auth0 login --no-input
+
+# Create an Auth0 API resource
+auth0 apis create \
+  --name "My FastAPI API" \
+  --identifier https://my-api.example.com \
+  --json
+```
+
+Note the `identifier` value — this is your Audience.
+
+### Step 2: Get your domain
+
+```bash
+# List tenants to get your domain
+auth0 tenants list
+```
+
+### Step 3: Add configuration
+
+Once you have your Domain and Audience, create a `.env` file:
+
+```bash
+AUTH0_DOMAIN=your-tenant.us.auth0.com
+AUTH0_AUDIENCE=https://my-api.example.com
+```
+
+Replace `your-tenant.us.auth0.com` with your Auth0 tenant domain and `https://my-api.example.com` with the identifier you used when creating the API resource.
+
+> **Important:** Never read the contents of `.env` at any point during setup. The file may contain sensitive secrets that should not be exposed in the LLM context.
+
+---
+
+## Manual Setup
+
+### Install Package
+
+```bash
+pip install auth0-fastapi-api python-dotenv
+```
+
+If you're using Poetry:
+
+```bash
+poetry add auth0-fastapi-api python-dotenv
+```
+
+### Create Auth0 API Resource
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Click **Create API**
+3. Set a **Name** and an **Identifier** (e.g., `https://my-api.example.com`)
+4. Note the Identifier — this is your `Audience`
+
+### Configure .env
+
+```bash
+AUTH0_DOMAIN=your-tenant.us.auth0.com
+AUTH0_AUDIENCE=https://my-api.example.com
+```
+
+**Important:** Domain format is `your-tenant.us.auth0.com` — do NOT include `https://`.
+
+### Get Auth0 Configuration
+
+- **Domain:** Auth0 Dashboard → Settings → Domain (or `auth0 tenants list`)
+- **Audience:** The identifier you set when creating the API resource
+
+### Using Environment Variables in Production
+
+For production/containers, export environment variables directly:
+
+```bash
+export AUTH0_DOMAIN=your-tenant.us.auth0.com
+export AUTH0_AUDIENCE=https://my-api.example.com
+```
+
+When using `os.environ[]` instead of `os.getenv()`, missing values will raise `KeyError` immediately — this is safer for production.
+
+---
+
+## Getting a Test Token
+
+### Via Auth0 Dashboard
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Select your API
+3. Click the **Test** tab
+4. Click **Copy Token** to get a test access token
+
+### Via Auth0 CLI
+
+```bash
+# Get access token for testing
+auth0 test token \
+  --audience https://my-api.example.com
+```
+
+### Via curl (Client Credentials Flow)
+
+```bash
+curl -X POST https://your-tenant.us.auth0.com/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_id": "YOUR_CLIENT_ID",
+    "client_secret": "YOUR_CLIENT_SECRET",
+    "audience": "https://my-api.example.com",
+    "grant_type": "client_credentials"
+  }'
+```
+
+### Request Tokens with Specific Scopes
+
+```bash
+curl -X POST https://your-tenant.us.auth0.com/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_id": "YOUR_CLIENT_ID",
+    "client_secret": "YOUR_CLIENT_SECRET",
+    "audience": "https://my-api.example.com",
+    "grant_type": "client_credentials",
+    "scope": "read:messages write:messages"
+  }'
+```
+
+---
+
+## Troubleshooting
+
+**401 Unauthorized — "invalid_token":** Verify that the `AUTH0_AUDIENCE` in `.env` exactly matches your API Identifier in Auth0 Dashboard.
+
+**401 Unauthorized — "invalid_issuer":** Ensure `AUTH0_DOMAIN` does not include `https://` — use `your-tenant.us.auth0.com` format only.
+
+**`os.getenv()` returns `None`:** Ensure `python-dotenv` is installed and `load_dotenv()` is called before `Auth0FastAPI()` initialization. In production, use `os.environ[]` to fail fast on missing values.
+
+**Token expired:** Test tokens from the Dashboard are short-lived. Request a fresh token.
+
+**`ValueError: audience is required.`:** The `audience` parameter cannot be empty. Ensure your `.env` file is loaded and the value is set.
+
+---
diff --git a/main/.mintlify/skills/auth0-fastify-api/SKILL.md b/main/.mintlify/skills/auth0/references/framework-fastify-api/index.md
similarity index 74%
rename from main/.mintlify/skills/auth0-fastify-api/SKILL.md
rename to main/.mintlify/skills/auth0/references/framework-fastify-api/index.md
index 1fadcf3c9b..a8912ef6c5 100644
--- a/main/.mintlify/skills/auth0-fastify-api/SKILL.md
+++ b/main/.mintlify/skills/auth0/references/framework-fastify-api/index.md
@@ -1,32 +1,23 @@
----
-name: auth0-fastify-api
-description: Use when securing Fastify API endpoints with JWT Bearer token validation, scope/permission checks, or stateless auth - integrates @auth0/auth0-fastify-api for REST APIs receiving access tokens from frontends or mobile apps.
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
 
 # Auth0 Fastify API Integration
 
 Protect Fastify API endpoints with JWT access token validation using @auth0/auth0-fastify-api.
 
----
 
 ## Prerequisites
 
 - Fastify API application (v5.x or newer)
 - Node.js 20 LTS or newer
 - Auth0 API configured (not Application - must be API resource)
-- If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
 
 ## When NOT to Use
 
 - **Server-rendered web applications** - Use `@auth0/auth0-fastify` for session-based auth
-- **Single Page Applications** - Use `auth0-react`, `auth0-vue`, or `auth0-angular` for client-side auth
-- **Next.js applications** - Use `auth0-nextjs` skill
-- **Mobile applications** - Use `auth0-react-native` for React Native/Expo
+- **Single Page Applications** - Use the Auth0 integration workflow for React, Vue, or Angular for client-side auth
+- **Next.js applications** - Use the Auth0 integration workflow for Next.js
+- **Mobile applications** - Use the Auth0 integration workflow for React Native/Expo
 
----
 
 ## Quick Start Workflow
 
@@ -105,7 +96,10 @@ fastify.get('/api/profile', {
   preHandler: fastify.requireAuth()
 }, async (request, reply) => {
   return {
-    profile: request.user,  // JWT claims
+    // Return only the fields the client needs. Returning the whole decoded
+    // token (request.user) exposes every claim — permissions, custom
+    // namespaces, and token metadata — to the client.
+    profile: { sub: request.user.sub, scope: request.user.scope },
   };
 });
 ```
@@ -122,10 +116,13 @@ Test protected endpoint (requires access token):
 
 ```bash
 curl http://localhost:3001/api/private \
-  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+  -H "Authorization: Bearer $TOKEN"
 ```
 
----
+> Capture the token into a shell variable (`TOKEN=$(...)`) and reference
+> `$TOKEN` rather than pasting the raw token inline — inline token values leak
+> into shell history and terminal scrollback.
+
 
 ## Common Mistakes
 
@@ -137,15 +134,14 @@ curl http://localhost:3001/api/private \
 | Using ID token instead of access token | Must use **access token** for API auth, not ID token |
 | Not handling 401/403 errors | Implement proper error handling for unauthorized/forbidden responses |
 
----
 
-## Related Skills
+## Related Capabilities
 
-- `auth0-quickstart` - Basic Auth0 setup
-- `auth0-fastify` - For server-rendered Fastify web apps with sessions
-- `auth0-mfa` - Add Multi-Factor Authentication
+- Basic Auth0 setup → set it up with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Server-rendered Fastify web apps with sessions → use the Auth0 integration workflow for Fastify (session-based)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- Manage Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
 
----
 
 ## Quick Reference
 
@@ -167,7 +163,6 @@ curl http://localhost:3001/api/private \
 - Get user ID → `request.user.sub`
 - Custom claims → Access via `request.user['namespace/claim']`
 
----
 
 ## References
 
diff --git a/main/.mintlify/skills/auth0-fastify/SKILL.md b/main/.mintlify/skills/auth0/references/framework-fastify/index.md
similarity index 83%
rename from main/.mintlify/skills/auth0-fastify/SKILL.md
rename to main/.mintlify/skills/auth0/references/framework-fastify/index.md
index 466fd4ba42..ffcca1035e 100644
--- a/main/.mintlify/skills/auth0-fastify/SKILL.md
+++ b/main/.mintlify/skills/auth0/references/framework-fastify/index.md
@@ -1,33 +1,24 @@
----
-name: auth0-fastify
-description: Use when adding authentication (login, logout, protected routes) to Fastify web applications - integrates @auth0/auth0-fastify for session-based auth. For stateless Fastify APIs use auth0-fastify-api instead.
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
 
 # Auth0 Fastify Integration
 
 Add authentication to Fastify web applications using @auth0/auth0-fastify.
 
----
 
 ## Prerequisites
 
 - Fastify application (v5.x or newer)
 - Node.js 20 LTS or newer
 - Auth0 account and application configured
-- If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
 
 ## When NOT to Use
 
-- **Single Page Applications** - Use `auth0-react`, `auth0-vue`, or `auth0-angular` for client-side auth
-- **Next.js applications** - Use `auth0-nextjs` skill which handles both client and server
-- **Mobile applications** - Use `auth0-react-native` for React Native/Expo
+- **Single Page Applications** - Use the Auth0 integration workflow for React, Vue, or Angular for client-side auth
+- **Next.js applications** - Use the Auth0 integration workflow for Next.js which handles both client and server
+- **Mobile applications** - Use the Auth0 integration workflow for React Native/Expo
 - **Stateless APIs** - Use `@auth0/auth0-fastify-api` instead for JWT validation without sessions
 - **Microservices** - Use JWT validation for service-to-service auth
 
----
 
 ## Quick Start Workflow
 
@@ -122,7 +113,6 @@ node server.js
 
 Visit `http://localhost:3000` and test the login flow.
 
----
 
 ## Common Mistakes
 
@@ -135,15 +125,14 @@ Visit `http://localhost:3000` and test the login flow.
 | Wrong appBaseUrl for production | Update APP_BASE_URL to match your production domain |
 | Not awaiting fastify.register | Fastify v4+ requires awaiting plugin registration |
 
----
 
 ## Related Skills
 
-- `auth0-quickstart` - Basic Auth0 setup
-- `auth0-migration` - Migrate from another auth provider
-- `auth0-mfa` - Add Multi-Factor Authentication
+- Auth0 setup → set it up with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Migrate from another auth provider → migration (migrate)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- Manage Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
 
----
 
 ## Quick Reference
 
@@ -167,7 +156,6 @@ Visit `http://localhost:3000` and test the login flow.
 - Get user info → `getUser({ request, reply })`
 - Call APIs → `getAccessToken({ request, reply })`
 
----
 
 ## References
 
diff --git a/main/.mintlify/skills/auth0/references/framework-flask/index.md b/main/.mintlify/skills/auth0/references/framework-flask/index.md
new file mode 100644
index 0000000000..5338358bd8
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-flask/index.md
@@ -0,0 +1,1050 @@
+
+# Auth0 Flask Web App Integration
+
+Add login, logout, and user profile to a Flask web application using `auth0-server-python`.
+
+## Prerequisites
+
+- Flask application
+- Auth0 Regular Web Application configured (not an API — must be an Application)
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **Python APIs with JWT Bearer validation** — Use `auth0-fastapi-api` for FastAPI, or see the [Django REST Framework quickstart](https://auth0.com/docs/quickstart/backend/django)
+- **FastAPI web app with login/logout UI** — No dedicated skill yet; see the [FastAPI quickstart](https://auth0.com/docs/quickstart/webapp/python)
+- **Single Page Applications** — Use the Auth0 integration workflow for React, Vue, or Angular for client-side auth
+- **Next.js applications** — Use the Auth0 integration workflow for Next.js, which handles both client and server
+- **Node.js web apps** — Use the Auth0 integration workflow for Express or Fastify for session-based auth
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+pip install auth0-server-python "flask[async]" python-dotenv
+```
+
+**Critical:** You must install `flask[async]` (not just `flask`). The `[async]` extra installs `asgiref` which is required for Flask 2.0+ to support `async def` route handlers. Without it, async routes will not work. In `requirements.txt`, use `flask[async]>=2.0.0`.
+
+### 2. Configure Environment
+
+Create `.env`:
+
+```bash
+AUTH0_DOMAIN=your-tenant.us.auth0.com
+AUTH0_CLIENT_ID=your_client_id
+AUTH0_CLIENT_SECRET=your_client_secret
+AUTH0_SECRET=your_generated_app_secret
+AUTH0_REDIRECT_URI=http://localhost:5000/callback
+```
+
+`AUTH0_DOMAIN` is your Auth0 tenant domain (without `https://`). `AUTH0_CLIENT_ID` and `AUTH0_CLIENT_SECRET` come from your Auth0 Application settings. `AUTH0_SECRET` is used for encrypting session data — generate with `openssl rand -hex 64`.
+
+### 3. Configure Auth0 Dashboard
+
+In your Auth0 Application settings:
+- **Allowed Callback URLs**: `http://localhost:5000/callback`
+- **Allowed Logout URLs**: `http://localhost:5000`
+
+### 4. Create Auth Module
+
+Create `auth.py` to initialize the `ServerClient` with Flask session-based stores. The stores use Flask's built-in `session` (cookie-based by default) for a **stateless** setup — no external database needed:
+
+```python
+import os
+from flask import session as flask_session
+from auth0_server_python.auth_server.server_client import ServerClient
+from auth0_server_python.auth_types import StateData, TransactionData
+from auth0_server_python.store import StateStore, TransactionStore
+from dotenv import load_dotenv
+
+load_dotenv()  # Uses .env by default; pass load_dotenv(".env.local") if credentials are in .env.local
+
+class FlaskSessionStateStore(StateStore):
+    """State store that uses Flask's session for persistence."""
+
+    def __init__(self, secret: str):
+        super().__init__({"secret": secret})
+
+    async def set(self, identifier, state, remove_if_expires=False, options=None):
+        data = state.dict() if hasattr(state, "dict") else state
+        flask_session[identifier] = self.encrypt(identifier, data)
+
+    async def get(self, identifier, options=None):
+        data = flask_session.get(identifier)
+        if data is None:
+            return None
+        decrypted = self.decrypt(identifier, data)
+        # Ensure to not return a dict, as the underlying SDK expects a StateData instance, not a dict
+        return StateData(**decrypted) if isinstance(decrypted, dict) else decrypted
+
+    async def delete(self, identifier, options=None):
+        flask_session.pop(identifier, None)
+
+    async def delete_by_logout_token(self, claims, options=None):
+        pass
+
+class FlaskSessionTransactionStore(TransactionStore):
+    """Transaction store that uses Flask's session for persistence."""
+
+    def __init__(self, secret: str):
+        super().__init__({"secret": secret})
+
+    async def set(self, identifier, state, remove_if_expires=False, options=None):
+        data = state.dict() if hasattr(state, "dict") else state
+        flask_session[identifier] = self.encrypt(identifier, data)
+
+    async def get(self, identifier, options=None):
+        data = flask_session.get(identifier)
+        if data is None:
+            return None
+        decrypted = self.decrypt(identifier, data)
+        # Ensure to not return a dict, as the underlying SDK expects a TransactionData instance, not a dict
+        return TransactionData(**decrypted) if isinstance(decrypted, dict) else decrypted
+
+    async def delete(self, identifier, options=None):
+        flask_session.pop(identifier, None)
+
+secret = os.getenv("AUTH0_SECRET")
+
+auth0 = ServerClient(
+    domain=os.getenv("AUTH0_DOMAIN"),
+    client_id=os.getenv("AUTH0_CLIENT_ID"),
+    client_secret=os.getenv("AUTH0_CLIENT_SECRET"),
+    secret=secret,
+    redirect_uri=os.getenv("AUTH0_REDIRECT_URI"),
+    state_store=FlaskSessionStateStore(secret=secret),
+    transaction_store=FlaskSessionTransactionStore(secret=secret),
+    authorization_params={"scope": "openid profile email"},
+)
+```
+
+Create one `ServerClient` instance and reuse it. Never hardcode credentials — always use environment variables.
+
+**How this works:** Flask's default session is cookie-based (stateless). The SDK encrypts session data (tokens, user profile) with JWE before storing it in the session, so data is both signed and encrypted in the cookie. No server-side database is required.
+
+**No `store_options` or `before_request` needed:** The SDK supports passing `store_options` (e.g. request/response objects) to store methods. Since these stores use `flask.session` — which is globally available during a request — they don't need anything from `store_options`, so you can call SDK methods without passing it. If you implement a custom store that manages cookies directly (instead of using `flask.session`), you would need to reintroduce `store_options` with `{"request": request, "response": response}`.
+
+**Cookie size note:** Stateless sessions store all data in a cookie (~4KB limit). For most apps this is sufficient. If you store large amounts of session data or hit cookie size limits, switch to [stateful setup](#stateful-setup-with-redis).
+
+### 5. Configure Flask App
+
+In `app.py`, set up Flask with the secret key and session configuration:
+
+```python
+import os
+from flask import Flask, redirect, request
+from auth import auth0
+from dotenv import load_dotenv
+
+load_dotenv()
+
+app = Flask(__name__)
+app.secret_key = os.getenv("AUTH0_SECRET")
+app.config.update(
+    SESSION_COOKIE_SECURE=False,  # Set to True in production (requires HTTPS)
+    SESSION_COOKIE_HTTPONLY=True,
+    SESSION_COOKIE_SAMESITE="Lax",
+)
+```
+
+**Critical:** `app.secret_key` must be set for Flask session management. Without it, sessions won't work.
+
+**For production:** Set `SESSION_COOKIE_SECURE=True` when deploying with HTTPS. Leaving it as `False` in production allows session cookies to be sent over unencrypted connections.
+
+### 6. Add Home Route
+
+```python
+@app.route("/")
+async def home():
+    user = await auth0.get_user()
+    if user:
+        return f"Hello, {user['name']}! <a href='/profile'>Profile</a> | <a href='/logout'>Logout</a>"
+    return "Welcome! <a href='/login'>Login</a>"
+```
+
+### 7. Add Login Route
+
+```python
+@app.route("/login")
+async def login():
+    authorization_url = await auth0.start_interactive_login()
+    return redirect(authorization_url)
+```
+
+`start_interactive_login()` returns a URL string pointing to Auth0's Universal Login page. You must wrap it in `redirect()`. Authorization params (scope, redirect_uri) are already configured on the `ServerClient`.
+
+### 8. Add Callback Route
+
+```python
+@app.route("/callback")
+async def callback():
+    try:
+        await auth0.complete_interactive_login(str(request.url))
+        return redirect("/")
+    except Exception as e:
+        return f"Authentication error: {str(e)}", 400
+```
+
+Pass `str(request.url)` as the first argument — this is the full callback URL including the authorization code query parameters. Always wrap in try/except since the token exchange can fail (e.g. expired code, CSRF mismatch).
+
+### 9. Add Profile Route (Protected)
+
+```python
+@app.route("/profile")
+async def profile():
+    user = await auth0.get_user()
+    if user is None:
+        return redirect("/login")
+    return (
+        f"<h1>{user['name']}</h1>"
+        f"<p>Email: {user['email']}</p>"
+        f"<img src='{user['picture']}' alt='{user['name']}' width='100' />"
+        f"<p><a href='/logout'>Logout</a></p>"
+    )
+```
+
+`get_user()` returns the user's profile from the session, or `None` if not logged in.
+
+### 10. Add Logout Route
+
+```python
+@app.route("/logout")
+async def logout():
+    url = await auth0.logout()
+    return redirect(url)
+```
+
+`logout()` returns the Auth0 logout URL. Redirect the user to it.
+
+### 11. Test the App
+
+```bash
+flask run
+```
+
+Visit `http://localhost:5000/login` to start the login flow.
+
+## Stateful Setup with Redis
+
+For production apps or when session data exceeds cookie size limits, use **Flask-Session** with Redis to store sessions server-side. Only a session ID is stored in the cookie.
+
+### 1. Install Dependencies
+
+```bash
+pip install flask-session redis
+```
+
+### 2. Configure Flask-Session
+
+Update `app.py` to use Redis-backed sessions:
+
+```python
+import os
+from flask import Flask, redirect, request
+from flask_session import Session
+from auth import auth0
+from dotenv import load_dotenv
+
+load_dotenv()
+
+app = Flask(__name__)
+app.secret_key = os.getenv("AUTH0_SECRET")
+app.config.update(
+    SESSION_TYPE="redis",
+    SESSION_PERMANENT=True,
+    SESSION_KEY_PREFIX="auth0:",
+    SESSION_COOKIE_SECURE=False,
+    SESSION_COOKIE_HTTPONLY=True,
+    SESSION_COOKIE_SAMESITE="Lax",
+)
+Session(app)
+```
+
+### 3. No Store Changes Needed
+
+The same `FlaskSessionStateStore` and `FlaskSessionTransactionStore` from `auth.py` work without modification. Flask-Session transparently switches the `flask.session` backend from cookies to Redis — the stores continue to use `flask.session` as before.
+
+**Routes are identical** to the stateless setup — no code changes needed.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Hardcoding `domain`, `client_id`, or `client_secret` in source | Always read from environment variables — never embed credentials in code |
+| Using `Authlib` or `python-jose` directly | Not needed; `auth0-server-python` handles all OAuth/OIDC flows |
+| Using `Flask-Login` or `Flask-Dance` | Not needed; the SDK manages sessions and authentication |
+| Manually parsing JWTs with `jwt.decode()` | The SDK handles token validation internally |
+| Installing `flask` without `[async]` extra | Must use `flask[async]>=2.0.0` in requirements.txt — without it, async route handlers silently fail |
+| Using synchronous route handlers | All routes calling SDK methods must be `async def` and use `await` |
+| Forgetting `app.secret_key` | Required for Flask session management — without it, sessions silently fail |
+| Using `auth0-fastapi-api` in Flask | That package is for FastAPI APIs — use `auth0-server-python` for Flask |
+| Passing `domain` as full URL with `https://` | `domain` should be the bare domain, e.g. `my-tenant.us.auth0.com`, not `https://my-tenant.us.auth0.com` |
+| Not configuring callback URL in Auth0 Dashboard | Must add `http://localhost:5000/callback` to Allowed Callback URLs |
+| Returning `start_interactive_login()` directly | It returns a URL string, not a response — must wrap in `redirect()` |
+| Not handling errors in `/callback` | `complete_interactive_login()` can fail — always wrap in try/except |
+| Calling SDK methods without `await` | All SDK methods are async — forgetting `await` returns a coroutine instead of the result |
+| Passing options positionally to `logout()` | Use `logout(store_options=...)` — the first positional parameter is `LogoutOptions`, not store options |
+| Expecting backchannel logout to work | Not supported with cookie-based sessions — `delete_by_logout_token` is a no-op. Use standard `/logout` route |
+| Deploying with `SESSION_COOKIE_SECURE=False` | Must set to `True` in production — cookies are sent over HTTP otherwise |
+
+## Key SDK Methods
+
+All methods are async:
+
+| Method | Signature | Purpose |
+|--------|-----------|---------|
+| `start_interactive_login` | `await auth0.start_interactive_login()` | Returns authorization URL string — wrap in `redirect()` |
+| `complete_interactive_login` | `await auth0.complete_interactive_login(str(request.url))` | Processes the callback URL, exchanges code for tokens |
+| `get_user` | `await auth0.get_user()` | Returns current session user dict or `None` |
+| `get_access_token` | `await auth0.get_access_token()` | Returns the access token for calling external APIs |
+| `logout` | `await auth0.logout()` | Returns Auth0 logout URL string |
+
+## Related Skills
+
+- Server-rendered Node.js web apps with login/logout sessions → the Auth0 integration workflow for Express or Fastify
+- Manage Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+
+## Quick Reference
+
+**ServerClient configuration:**
+```python
+auth0 = ServerClient(
+    domain=os.getenv("AUTH0_DOMAIN"),                    # required
+    client_id=os.getenv("AUTH0_CLIENT_ID"),              # required
+    client_secret=os.getenv("AUTH0_CLIENT_SECRET"),      # required
+    secret=os.getenv("AUTH0_SECRET"),                    # required (encryption secret)
+    redirect_uri=os.getenv("AUTH0_REDIRECT_URI"),        # required
+    state_store=FlaskSessionStateStore(secret=secret),   # required
+    transaction_store=FlaskSessionTransactionStore(secret=secret),  # required
+    authorization_params={"scope": "openid profile email"},  # recommended
+)
+```
+
+**Route protection pattern:**
+```python
+user = await auth0.get_user()
+if user is None:
+    return redirect("/login")
+```
+
+**Environment variables:**
+- `AUTH0_DOMAIN` — your Auth0 tenant domain (e.g. `tenant.us.auth0.com`)
+- `AUTH0_CLIENT_ID` — your Application's client ID
+- `AUTH0_CLIENT_SECRET` — your Application's client secret
+- `AUTH0_SECRET` — encryption and session secret key
+- `AUTH0_REDIRECT_URI` — callback URL (e.g. `http://localhost:5000/callback`)
+
+## References
+
+- [auth0-server-python on PyPI](https://pypi.org/project/auth0-server-python/)
+- [auth0-server-python GitHub](https://github.com/auth0/auth0-server-python)
+- [Auth0 Flask Quickstart](https://auth0.com/docs/quickstart/webapp/python)
+- [Flask Documentation](https://flask.palletsprojects.com/)
+- [Flask-Session Documentation](https://flask-session.readthedocs.io/)
+
+---
+
+# Auth0 Flask API Reference
+
+Complete configuration and API reference for Flask authentication.
+
+---
+
+## ServerClient Configuration
+
+### Complete Configuration Options
+
+```python
+from auth0_server_python.auth_server.server_client import ServerClient
+
+secret = os.getenv("AUTH0_SECRET")
+
+auth0 = ServerClient(
+    domain=os.getenv("AUTH0_DOMAIN"),                    # required: tenant domain (without https://)
+    client_id=os.getenv("AUTH0_CLIENT_ID"),              # required: app client ID
+    client_secret=os.getenv("AUTH0_CLIENT_SECRET"),      # required: app client secret
+    secret=secret,                                       # required: encryption secret (min 32 chars)
+    redirect_uri=os.getenv("AUTH0_REDIRECT_URI"),        # required: callback URL
+    state_store=FlaskSessionStateStore(secret=secret),   # required: state persistence
+    transaction_store=FlaskSessionTransactionStore(secret=secret),  # required: transaction persistence
+    authorization_params={                                # optional: OAuth params
+        "scope": "openid profile email",
+        "audience": "https://your-api-identifier",
+    },
+)
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `domain` | Yes | Auth0 tenant domain (e.g., `tenant.us.auth0.com`) — without `https://` |
+| `client_id` | Yes | Application client ID from Auth0 Dashboard |
+| `client_secret` | Yes | Application client secret from Auth0 Dashboard |
+| `secret` | Yes | Encryption secret for JWE — generate with `openssl rand -hex 64` |
+| `redirect_uri` | Yes | Callback URL (e.g., `http://localhost:5000/callback`) |
+| `state_store` | Yes | Store implementation for session state |
+| `transaction_store` | Yes | Store implementation for OAuth transaction data |
+| `authorization_params` | No | Default OAuth parameters (scope, audience, connection) |
+
+---
+
+## Flask Session Configuration
+
+### Cookie-Based Sessions (Stateless)
+
+```python
+app = Flask(__name__)
+app.secret_key = os.getenv("AUTH0_SECRET")
+app.config.update(
+    SESSION_COOKIE_SECURE=False,       # Set to True in production (requires HTTPS)
+    SESSION_COOKIE_HTTPONLY=True,       # Prevents JavaScript access to cookie
+    SESSION_COOKIE_SAMESITE="Lax",     # CSRF protection
+)
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `SESSION_COOKIE_SECURE` | `False` | Only send cookie over HTTPS — **must be `True` in production** |
+| `SESSION_COOKIE_HTTPONLY` | `True` | Prevent JavaScript access to session cookie |
+| `SESSION_COOKIE_SAMESITE` | `None` | CSRF protection — use `"Lax"` for auth flows |
+| `PERMANENT_SESSION_LIFETIME` | 31 days | Session expiration (accepts `timedelta`) |
+
+Cookie size limit: ~4KB. Sufficient for most apps with `openid profile email` scopes.
+
+### Redis-Based Sessions (Stateful)
+
+```python
+from flask_session import Session
+
+app = Flask(__name__)
+app.secret_key = os.getenv("AUTH0_SECRET")
+app.config.update(
+    SESSION_TYPE="redis",
+    SESSION_PERMANENT=True,
+    SESSION_KEY_PREFIX="auth0:",
+    SESSION_COOKIE_SECURE=False,       # Set to True in production
+    SESSION_COOKIE_HTTPONLY=True,
+    SESSION_COOKIE_SAMESITE="Lax",
+)
+Session(app)
+```
+
+No store code changes needed — Flask-Session transparently switches the `flask.session` backend from cookies to Redis. The same `FlaskSessionStateStore` and `FlaskSessionTransactionStore` work without modification.
+
+---
+
+## ServerClient Methods
+
+All methods are async and must be called with `await`.
+
+### start_interactive_login()
+
+Initiates the OAuth login flow and returns an authorization URL.
+
+```python
+authorization_url = await auth0.start_interactive_login()
+return redirect(authorization_url)
+```
+
+**Returns:** URL string — must wrap in `redirect()`.
+
+**With options:**
+
+```python
+from auth0_server_python.auth_types import StartInteractiveLoginOptions
+
+authorization_url = await auth0.start_interactive_login(
+    options=StartInteractiveLoginOptions(
+        authorization_params={
+            "connection": "google-oauth2",
+            "screen_hint": "signup",
+        }
+    )
+)
+```
+
+### complete_interactive_login(url)
+
+Processes the callback URL, exchanges the authorization code for tokens, and stores session state.
+
+```python
+await auth0.complete_interactive_login(str(request.url))
+```
+
+**Parameters:**
+- `url` (string): Full callback URL including query parameters
+
+**Raises:** Exception on state mismatch (CSRF), missing parameters, or token exchange failures.
+
+### get_user()
+
+Retrieves the current authenticated user from the session.
+
+```python
+user = await auth0.get_user()
+```
+
+**Returns:** User dict or `None` if not authenticated.
+
+**User dict keys:**
+- `sub` — Auth0 user ID (e.g., `google-oauth2|123456`)
+- `name` — Display name
+- `email` — Email address
+- `picture` — Avatar URL
+- `email_verified` — Boolean
+
+### get_access_token()
+
+Retrieves the access token for calling external APIs. Handles token refresh automatically if a refresh token is available and the access token is expired.
+
+```python
+access_token = await auth0.get_access_token()
+```
+
+**Returns:** Access token string. **Raises** on failure (e.g. expired token without refresh token).
+
+**Requires:** `audience` parameter in `authorization_params` during ServerClient initialization.
+
+### logout()
+
+Clears the session and returns the Auth0 logout URL.
+
+```python
+url = await auth0.logout()
+return redirect(url)
+```
+
+**Returns:** Auth0 logout URL string — must wrap in `redirect()`.
+
+**With options:**
+
+```python
+from auth0_server_python.auth_types import LogoutOptions
+
+url = await auth0.logout(
+    options=LogoutOptions(return_to="http://localhost:5000/goodbye")
+)
+```
+
+---
+
+## Store Implementation
+
+Both stores use Flask's built-in `session` object. Since `flask.session` is a context-local available during any request, the stores don't need `store_options` — they access the session directly.
+
+### FlaskSessionStateStore
+
+Stores OAuth state (user profile, tokens) in Flask session, encrypted with JWE.
+
+```python
+from flask import session as flask_session
+from auth0_server_python.auth_types import StateData
+from auth0_server_python.store import StateStore
+
+class FlaskSessionStateStore(StateStore):
+    """State store that uses Flask's session for persistence."""
+
+    def __init__(self, secret: str):
+        super().__init__({"secret": secret})
+
+    async def set(self, identifier, state, remove_if_expires=False, options=None):
+        data = state.dict() if hasattr(state, "dict") else state
+        flask_session[identifier] = self.encrypt(identifier, data)
+
+    async def get(self, identifier, options=None):
+        data = flask_session.get(identifier)
+        if data is None:
+            return None
+        decrypted = self.decrypt(identifier, data)
+        return StateData(**decrypted) if isinstance(decrypted, dict) else decrypted
+
+    async def delete(self, identifier, options=None):
+        flask_session.pop(identifier, None)
+
+    async def delete_by_logout_token(self, claims, options=None):
+        pass  # Not supported with stateless cookie sessions
+```
+
+### FlaskSessionTransactionStore
+
+Stores transaction data (PKCE code_verifier, nonce, state) during the login flow, encrypted with JWE.
+
+```python
+from flask import session as flask_session
+from auth0_server_python.auth_types import TransactionData
+from auth0_server_python.store import TransactionStore
+
+class FlaskSessionTransactionStore(TransactionStore):
+    """Transaction store that uses Flask's session for persistence."""
+
+    def __init__(self, secret: str):
+        super().__init__({"secret": secret})
+
+    async def set(self, identifier, state, remove_if_expires=False, options=None):
+        data = state.dict() if hasattr(state, "dict") else state
+        flask_session[identifier] = self.encrypt(identifier, data)
+
+    async def get(self, identifier, options=None):
+        data = flask_session.get(identifier)
+        if data is None:
+            return None
+        decrypted = self.decrypt(identifier, data)
+        return TransactionData(**decrypted) if isinstance(decrypted, dict) else decrypted
+
+    async def delete(self, identifier, options=None):
+        flask_session.pop(identifier, None)
+```
+
+**Why no `store_options`:** The SDK passes `store_options` (typically `{"request": request, "response": response}`) to store methods. Since Flask's `session` is a context-local that's automatically available during any request, the stores don't need request/response objects passed in — they access `flask_session` directly. The SDK passes `None` through without error.
+
+---
+
+## Security Considerations
+
+### SESSION_COOKIE_SECURE
+
+```python
+# Development (localhost HTTP)
+SESSION_COOKIE_SECURE=False
+
+# Production (HTTPS required)
+SESSION_COOKIE_SECURE=True
+```
+
+Setting `SESSION_COOKIE_SECURE=False` in production is a security risk — session cookies will be sent over unencrypted HTTP connections, exposing them to interception.
+
+### Backchannel Logout Limitation
+
+Backchannel logout (Auth0 sending a server-to-server logout token) is **not supported** with Flask session stores. The `delete_by_logout_token` method is a no-op because there is no server-side session store to query and delete from — session data lives in the user's browser cookie.
+
+**Impact:** If a user logs out from another application in the same Auth0 tenant, their Flask session will not be automatically revoked. The session persists until the user makes a new request and the app clears it, or the cookie expires.
+
+**Workaround:** For enterprise scenarios requiring federated logout, switch to Redis-backed sessions where you can implement `delete_by_logout_token` to scan and delete matching sessions.
+
+### Cookie Size Limits
+
+Stateless cookie sessions are limited to ~4KB by browsers. The SDK encrypts tokens and user profile with JWE before storing in the session. For typical apps with `openid profile email` scopes, this is well within limits.
+
+**When it breaks:** Large custom claims, multiple audience tokens, or extensive user metadata can exceed the limit. The browser silently truncates or rejects the cookie, causing mysterious session loss.
+
+**Fix:** Switch to Redis-backed sessions (see [Flask Session Configuration](#redis-based-sessions-stateful)).
+
+### Best Practices
+
+- **Keep secrets secure** — Never commit `.env` to version control
+- **Use HTTPS in production** — `SESSION_COOKIE_SECURE=True` requires HTTPS
+- **Rotate secrets regularly** — Update `AUTH0_SECRET` periodically
+- **Validate audience** — For API calls, always configure `audience` parameter
+- **Handle errors** — Always wrap `complete_interactive_login` in try/except
+
+---
+
+## Testing
+
+### Local Testing
+
+1. Start your app: `flask run`
+2. Visit `http://localhost:5000/login`
+3. Complete Auth0 login flow
+4. Verify redirect to callback and session established
+5. Visit protected route (e.g., `/profile`)
+6. Click logout and verify session cleared
+
+---
+
+# Auth0 Flask Integration Patterns
+
+Server-side authentication patterns for Flask.
+
+---
+
+## Protected Routes
+
+### Using Decorator Pattern
+
+```python
+from functools import wraps
+from flask import redirect, render_template
+from auth import auth0
+
+def require_auth(f):
+    @wraps(f)
+    async def decorated_function(*args, **kwargs):
+        user = await auth0.get_user()
+        if user is None:
+            return redirect("/login")
+        return await f(*args, **kwargs)
+    return decorated_function
+
+@app.route("/admin")
+@require_auth
+async def admin():
+    user = await auth0.get_user()
+    return render_template("admin.html", user=user)
+```
+
+### Manual Check in Route
+
+```python
+@app.route("/dashboard")
+async def dashboard():
+    user = await auth0.get_user()
+    if user is None:
+        return redirect("/login")
+    return render_template("dashboard.html", user=user)
+```
+
+### Blueprint Protection
+
+```python
+from flask import Blueprint, redirect, render_template
+from auth import auth0
+
+admin = Blueprint("admin", __name__, url_prefix="/admin")
+
+@admin.before_request
+async def check_auth():
+    user = await auth0.get_user()
+    if user is None:
+        return redirect("/login")
+
+@admin.route("/settings")
+async def settings():
+    user = await auth0.get_user()
+    return render_template("settings.html", user=user)
+
+app.register_blueprint(admin)
+```
+
+---
+
+## Calling External APIs
+
+### Get Access Token
+
+```python
+import httpx
+from flask import jsonify, redirect
+from auth import auth0
+
+@app.route("/api-call")
+async def api_call():
+    user = await auth0.get_user()
+    if user is None:
+        return redirect("/login")
+
+    try:
+        access_token = await auth0.get_access_token()
+    except Exception as e:
+        return f"Access token error: {e}", 401
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            "https://api.example.com/data",
+            headers={"Authorization": f"Bearer {access_token}"}
+        )
+
+    return jsonify(response.json())
+```
+
+### Configure Audience
+
+Update the `ServerClient` initialization in `auth.py` to include `audience`:
+
+```python
+auth0 = ServerClient(
+    domain=os.getenv("AUTH0_DOMAIN"),
+    client_id=os.getenv("AUTH0_CLIENT_ID"),
+    client_secret=os.getenv("AUTH0_CLIENT_SECRET"),
+    secret=secret,
+    redirect_uri=os.getenv("AUTH0_REDIRECT_URI"),
+    state_store=FlaskSessionStateStore(secret=secret),
+    transaction_store=FlaskSessionTransactionStore(secret=secret),
+    authorization_params={
+        "scope": "openid profile email",
+        "audience": "https://your-api-identifier",  # Add this
+    },
+)
+```
+
+---
+
+## Custom Login/Logout
+
+### Custom Login with Connection
+
+```python
+from auth0_server_python.auth_types import StartInteractiveLoginOptions
+
+@app.route("/login-google")
+async def login_google():
+    authorization_url = await auth0.start_interactive_login(
+        options=StartInteractiveLoginOptions(
+            authorization_params={"connection": "google-oauth2"}
+        )
+    )
+    return redirect(authorization_url)
+```
+
+### Custom Logout with Return URL
+
+```python
+from auth0_server_python.auth_types import LogoutOptions
+
+@app.route("/logout")
+async def logout():
+    url = await auth0.logout(
+        options=LogoutOptions(return_to="http://localhost:5000/goodbye")
+    )
+    return redirect(url)
+```
+
+---
+
+## Session Management
+
+### Access User Information
+
+```python
+@app.route("/user-info")
+async def user_info():
+    user = await auth0.get_user()
+
+    if user is None:
+        return jsonify({"authenticated": False})
+
+    return jsonify({
+        "authenticated": True,
+        "user": user,
+    })
+```
+
+### Store Custom Session Data
+
+```python
+from flask import session as flask_session
+
+@app.route("/callback")
+async def callback():
+    try:
+        await auth0.complete_interactive_login(str(request.url))
+        user = await auth0.get_user()
+
+        # Store custom data alongside Auth0 session
+        flask_session["user_role"] = "admin"
+
+        return redirect("/")
+    except Exception as e:
+        return f"Authentication error: {str(e)}", 400
+```
+
+### Inject User via before_request
+
+Make user available in all templates using a `before_request` hook (Flask supports async for `before_request` but not for `context_processor`):
+
+```python
+@app.before_request
+async def load_user():
+    g.user = await auth0.get_user()
+```
+
+Then in any template:
+
+```html
+{% if g.user %}
+  <p>Welcome, {{ g.user.name }}!</p>
+  <a href="/logout">Logout</a>
+{% else %}
+  <a href="/login">Login</a>
+{% endif %}
+```
+
+---
+
+## Error Handling
+
+### Callback Error Handling
+
+```python
+@app.route("/callback")
+async def callback():
+    try:
+        await auth0.complete_interactive_login(str(request.url))
+        return redirect("/")
+    except Exception as e:
+        # State validation, token exchange, or other authentication errors
+        return f"Authentication error: {str(e)}", 400
+```
+
+### Global Error Handler
+
+```python
+@app.errorhandler(401)
+def unauthorized(error):
+    return redirect("/login")
+```
+
+---
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "Callback URL mismatch" | Ensure `AUTH0_REDIRECT_URI` matches Allowed Callback URLs in Auth0 Dashboard exactly |
+| Session data lost on page reload | Check `app.secret_key` is set and Flask session is configured |
+| Access token is None | Configure `audience` in ServerClient `authorization_params` |
+| "Invalid state" error | Regenerate `AUTH0_SECRET` — it may be corrupted or too short |
+| Async routes not working | Use `flask[async]>=2.0.0` (not just `flask`) |
+| Redirect loop on login | Check that `/login` route is not itself protected by `require_auth` |
+
+---
+
+---
+
+# Auth0 Flask Setup Guide
+
+Setup instructions for Flask applications.
+
+---
+
+## Quick Setup (Automated)
+
+Below automates the setup, except for the CLIENT_SECRET. Inform the user that they have to fill in the value for the CLIENT_SECRET themselves.
+
+**Never read the contents of `.env.local` or `.env` at any point during setup.** The file may contain sensitive secrets that should not be exposed in the LLM context. If you determine you need to read the file for any reason, ask the user for explicit permission before doing so — do not proceed until the user confirms.
+
+**Before running any part of this setup that writes to an env file, you MUST ask the user for explicit confirmation.** Follow the steps below precisely.
+
+### Step 1: Check for existing env files and confirm with user
+
+Before writing credentials, check which env files exist:
+
+```bash
+test -f .env.local && echo "ENV_LOCAL_EXISTS" || echo "ENV_LOCAL_NOT_FOUND"
+test -f .env && echo "ENV_EXISTS" || echo "ENV_NOT_FOUND"
+```
+
+Then ask the user for explicit confirmation before proceeding — do not continue until the user confirms:
+
+- If `.env.local` exists, ask:
+  - Question: "A `.env.local` file already exists and may contain secrets unrelated to Auth0. This setup will append Auth0 credentials to it without modifying existing content. Do you want to proceed?"
+  - Options: "Yes, append to existing .env.local" / "No, I'll update it manually"
+
+- If `.env.local` does **not** exist but `.env` exists, ask:
+  - Question: "A `.env` file already exists and may contain secrets unrelated to Auth0. This setup will append Auth0 credentials to it without modifying existing content. Do you want to proceed?"
+  - Options: "Yes, append to existing .env" / "No, I'll update it manually"
+
+- If neither exists, ask:
+  - Question: "This setup will create a `.env` file containing Auth0 credentials (AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_SECRET) and a placeholder for AUTH0_CLIENT_SECRET. Do you want to proceed?"
+  - Options: "Yes, create .env" / "No, I'll configure it manually"
+
+**Do not proceed with writing to any env file unless the user selects the confirmation option.**
+
+### Step 2: Run automated setup (only after confirmation)
+
+```bash
+#!/bin/bash
+
+# Install Auth0 CLI
+if ! command -v auth0 &> /dev/null; then
+  [[ "$OSTYPE" == "darwin"* ]] && brew install auth0/auth0-cli/auth0 || \
+  curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b /usr/local/bin
+fi
+
+# Login
+auth0 login 2>/dev/null || auth0 login
+
+# Create/select app
+auth0 apps list
+read -p "Enter app ID (or Enter to create): " APP_ID
+
+if [ -z "$APP_ID" ]; then
+  APP_ID=$(auth0 apps create --name "${PWD##*/}-flask" --type regular \
+    --callbacks "http://localhost:5000/callback" \
+    --logout-urls "http://localhost:5000" \
+    --metadata "created_by=agent_skills" \
+    --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+fi
+
+# Get credentials
+DOMAIN=$(auth0 apps show "$APP_ID" --json | grep -o '"domain":"[^"]*' | cut -d'"' -f4)
+CLIENT_ID=$(auth0 apps show "$APP_ID" --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+SECRET=$(openssl rand -hex 64)
+
+# Determine target env file
+if [ -f .env.local ]; then
+  TARGET_FILE=".env.local"
+elif [ -f .env ]; then
+  TARGET_FILE=".env"
+else
+  TARGET_FILE=".env"
+fi
+
+# Append Auth0 credentials
+cat >> "$TARGET_FILE" << ENVEOF
+AUTH0_DOMAIN=$DOMAIN
+AUTH0_CLIENT_ID=$CLIENT_ID
+AUTH0_CLIENT_SECRET='YOUR_CLIENT_SECRET'
+AUTH0_SECRET=$SECRET
+AUTH0_REDIRECT_URI=http://localhost:5000/callback
+ENVEOF
+
+echo "Auth0 credentials written to $TARGET_FILE"
+```
+
+After the script runs, remind the user to:
+1. Open the env file that was written and replace `YOUR_CLIENT_SECRET` with the actual client secret from Auth0.
+2. Ensure the env file is listed in `.gitignore` to avoid accidentally committing secrets.
+
+---
+
+## Manual Setup
+
+### Install Packages
+
+```bash
+pip install auth0-server-python "flask[async]" python-dotenv
+```
+
+**Critical:** You must install `flask[async]` (not just `flask`). The `[async]` extra installs `asgiref` which is required for Flask 2.0+ to support `async def` route handlers.
+
+### Create .env
+
+```bash
+AUTH0_DOMAIN=your-tenant.us.auth0.com
+AUTH0_CLIENT_ID=your-client-id
+AUTH0_CLIENT_SECRET=your-client-secret
+AUTH0_SECRET=<openssl-rand-hex-64>
+AUTH0_REDIRECT_URI=http://localhost:5000/callback
+```
+
+Generate secret: `openssl rand -hex 64`
+
+### Get Auth0 Credentials
+
+CLI: `auth0 apps show <app-id> --reveal-secrets`
+
+Dashboard: Create Regular Web Application, copy credentials
+
+### Configure Auth0 Dashboard
+
+In your Auth0 Application settings:
+- **Allowed Callback URLs**: `http://localhost:5000/callback`
+- **Allowed Logout URLs**: `http://localhost:5000`
+
+---
+
+## Troubleshooting
+
+**"Missing AUTH0_SECRET" error:** Ensure `AUTH0_SECRET` is set and at least 32 characters long. Generate with `openssl rand -hex 64`.
+
+**"Invalid redirect_uri" error:** Add `http://localhost:5000/callback` to Allowed Callback URLs in Auth0 Dashboard.
+
+**Callback URL mismatch:** URL must match exactly between `AUTH0_REDIRECT_URI` in `.env` and the Allowed Callback URLs in Auth0 Dashboard.
+
+**Client secret required:** Flask uses Regular Web Application type — ensure the app was created as `--type regular`, not SPA or Native.
+
+**Async routes not working:** Ensure you installed `flask[async]` (not just `flask`). Without the `[async]` extra, async route handlers silently fail.
+
+---
diff --git a/main/.mintlify/skills/auth0/references/framework-flutter-native/index.md b/main/.mintlify/skills/auth0/references/framework-flutter-native/index.md
new file mode 100644
index 0000000000..81f9f98360
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-flutter-native/index.md
@@ -0,0 +1,433 @@
+# Auth0 Flutter Native
+
+> Ported from auth0/auth0-flutter-native skill.
+
+---
+
+
+# Auth0 Flutter Native (iOS/Android) Integration
+
+`auth0_flutter` is the official Auth0 SDK for Flutter applications. On **mobile (iOS/Android)**, it performs authentication through the device's system browser (Web Auth / Universal Login) and stores tokens securely in the platform keychain/keystore via the built-in `CredentialsManager`, with optional biometric protection.
+
+> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running one of:
+> ```bash
+> gh api repos/auth0/auth0-flutter/releases/latest --jq '.tag_name'
+> ```
+> ```bash
+> flutter pub info auth0_flutter 2>/dev/null | head -5
+> ```
+> Or check pub.dev:
+> ```bash
+> curl -s https://pub.dev/api/packages/auth0_flutter | python3 -c "import sys,json;print(json.load(sys.stdin)['latest']['version'])"
+> ```
+> Use the returned version in all dependency lines instead of any hardcoded version below. Current known version: `2.1.0`.
+
+## When NOT to Use
+
+- **Flutter web**: Use the Auth0 Flutter web integration — web uses a different platform interface (`Auth0Web`) wrapping Auth0 SPA JS
+- **Native iOS (Swift, no Flutter)**: Use the Auth0 Swift integration
+- **Native Android (Kotlin/Java, no Flutter)**: Use the Auth0 Android integration
+- **React Native**: Use the Auth0 React Native integration
+- **React SPA**: Use the Auth0 React integration
+- **Node.js/Express servers**: Use the Auth0 Express integration
+
+## Prerequisites
+
+- **Flutter** 3.24.0+
+- **Dart** 3.5.0+
+- **Android**: minSdkVersion 21+, compileSdkVersion 34+
+- **iOS**: 14.0+ (Universal Link callbacks require iOS 17.4+)
+- Auth0 account — [Sign up free](https://auth0.com/signup)
+- Auth0 CLI — [install instructions](https://github.com/auth0/auth0-cli) (used to create and configure the Auth0 application)
+
+## Quick Start Workflow
+
+> **Agent instruction:** Follow these steps in order. If you encounter an error at any step, attempt to fix it up to 5 times before calling `AskUserQuestion` to ask the user for guidance. Always search existing code first — if there are existing login/logout handlers, hook into them rather than creating new ones.
+
+### Step 1 — Install SDK
+
+> **Agent instruction:** Check the project directory for `pubspec.yaml`. If present, add the dependency. If not found, this is not a Flutter project — ask the user.
+>
+> Run in the project root:
+> ```bash
+> flutter pub add auth0_flutter
+> ```
+>
+> Verify the dependency was added to `pubspec.yaml`:
+> ```yaml
+> dependencies:
+>   auth0_flutter: ^2.1.0
+> ```
+
+### Step 2 — Configure Auth0
+
+> **Note:** The Auth0 Domain and Client ID are **public configuration** (not secrets) — a native app uses PKCE with no client secret. Pass them directly to `Auth0(domain, clientId)`; there is no need to store them in environment variables or hide them.
+>
+> **Agent instruction:**
+> - **If Auth0 credentials (domain AND client ID) are already in the user's prompt:** Use those values directly in the `Auth0(...)` constructor and proceed to Step 3.
+> - **If no credentials are provided:** Ask the user which setup they prefer using `AskUserQuestion`: _"How would you like to set up the Auth0 application — automatic (I run the Auth0 CLI to create it) or manual (you create it in the Auth0 Dashboard and give me the Domain + Client ID)?"_
+>   - **Automatic:** Follow the Auth0 CLI steps in the Setup Guide to create the Native application.
+>   - **Manual:** Ask the user for their Auth0 Domain and Client ID and use them directly.
+>
+> Follow the Setup Guide — Auth0 Configuration section (below) for the pre-flight checks and the `auth0 apps create` command.
+
+### Step 3 — Configure Android
+
+> **Agent instruction:** Edit `android/app/build.gradle` (or `build.gradle.kts`) and add `manifestPlaceholders` inside `android { defaultConfig { ... } }`. These supply the callback URL the SDK's `RedirectActivity` intent filter registers — without them the app will not build correctly for Auth0.
+
+For `android/app/build.gradle` (Groovy):
+```groovy
+android {
+    defaultConfig {
+        manifestPlaceholders = [auth0Domain: "YOUR_AUTH0_DOMAIN", auth0Scheme: "https"]
+    }
+}
+```
+
+For `android/app/build.gradle.kts` (Kotlin DSL):
+```kotlin
+android {
+    defaultConfig {
+        manifestPlaceholders["auth0Domain"] = "YOUR_AUTH0_DOMAIN"
+        manifestPlaceholders["auth0Scheme"] = "https"
+    }
+}
+```
+
+> **Agent instruction:** Use `auth0Scheme: "https"` to use Android App Links (recommended). If the app targets a custom scheme instead, set it to a lowercase scheme string and pass the same scheme to `webAuthentication(scheme: ...)` in Dart. See the Setup Guide section (below) for details.
+
+### Step 4 — Configure iOS
+
+> **Agent instruction:** For the default HTTPS (Universal Link) flow on iOS 17.4+, no `Info.plist` change is required, but the **Associated Domains** capability must be added in Xcode (`webcredentials:YOUR_AUTH0_DOMAIN`). For older iOS or a custom URL scheme, add a `CFBundleURLTypes` entry to `ios/Runner/Info.plist`:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleTypeRole</key>
+    <string>None</string>
+    <key>CFBundleURLName</key>
+    <string>auth0</string>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+    </array>
+  </dict>
+</array>
+```
+
+### Step 5 — Configure Callback URLs
+
+> **Agent instruction:** Register the platform-specific callback and logout URLs using the Auth0 CLI. Determine the Android package name (from `android/app/build.gradle` `applicationId`) and the iOS bundle identifier (from Xcode / `PRODUCT_BUNDLE_IDENTIFIER`), then run the command below, replacing the placeholders (`CLIENT_ID`, `YOUR_DOMAIN`, `ANDROID_PACKAGE_NAME`, `IOS_BUNDLE_ID`) with the project's values:
+>
+> ```bash
+> auth0 apps update CLIENT_ID \
+>   --callbacks "https://YOUR_DOMAIN/android/ANDROID_PACKAGE_NAME/callback,https://YOUR_DOMAIN/ios/IOS_BUNDLE_ID/callback" \
+>   --logout-urls "https://YOUR_DOMAIN/android/ANDROID_PACKAGE_NAME/callback,https://YOUR_DOMAIN/ios/IOS_BUNDLE_ID/callback" \
+>   --no-input
+> ```
+
+The callback URL formats are:
+- **Android**: `https://YOUR_DOMAIN/android/YOUR_PACKAGE_NAME/callback`
+- **iOS**: `https://YOUR_DOMAIN/ios/YOUR_BUNDLE_ID/callback`
+
+### Step 6 — Implement Authentication
+
+> **Agent instruction:** Search the project for the main app entry point (`main.dart`). Determine the state management approach:
+> - Look for `provider`, `riverpod`, `bloc`, `GetX`, or `mobx` imports
+> - If none found, use basic `StatefulWidget` with `setState`
+>
+> Then follow **only** the matching path below. If ambiguous, ask via `AskUserQuestion`: _"Which state management approach does your Flutter app use — Provider, Riverpod, Bloc, or basic setState?"_
+
+#### Basic StatefulWidget (Default)
+
+> **Agent instruction:** Create an `AuthService` class, then wire it into the app's root widget. Search for the `MaterialApp` or `CupertinoApp` widget and update accordingly. On startup, restore the session from the `CredentialsManager` cache.
+
+```dart
+// lib/auth_service.dart
+import 'package:auth0_flutter/auth0_flutter.dart';
+
+class AuthService {
+  late final Auth0 _auth0;
+  Credentials? _credentials;
+
+  AuthService({required String domain, required String clientId}) {
+    _auth0 = Auth0(domain, clientId);
+  }
+
+  bool get isAuthenticated => _credentials != null;
+  UserProfile? get user => _credentials?.user;
+
+  /// Restore a stored session on app startup, if one exists.
+  Future<void> init() async {
+    final hasValid = await _auth0.credentialsManager.hasValidCredentials();
+    if (hasValid) {
+      _credentials = await _auth0.credentialsManager.credentials();
+    }
+  }
+
+  /// Launch Web Auth via the system browser. Tokens are stored automatically.
+  Future<void> login() async {
+    _credentials = await _auth0
+        .webAuthentication()
+        .login(scopes: {'openid', 'profile', 'email', 'offline_access'});
+  }
+
+  /// Clear the session in the browser and wipe stored credentials.
+  Future<void> logout() async {
+    await _auth0.webAuthentication().logout();
+    await _auth0.credentialsManager.clearCredentials();
+    _credentials = null;
+  }
+}
+```
+
+```dart
+// lib/main.dart
+import 'package:flutter/material.dart';
+import 'package:auth0_flutter/auth0_flutter.dart'; // for WebAuthenticationException
+import 'auth_service.dart';
+
+void main() {
+  runApp(const MyApp());
+}
+
+class MyApp extends StatefulWidget {
+  const MyApp({super.key});
+
+  @override
+  State<MyApp> createState() => _MyAppState();
+}
+
+class _MyAppState extends State<MyApp> {
+  final _authService = AuthService(
+    domain: 'YOUR_AUTH0_DOMAIN',
+    clientId: 'YOUR_AUTH0_CLIENT_ID',
+  );
+  bool _isLoading = true;
+
+  @override
+  void initState() {
+    super.initState();
+    _initAuth();
+  }
+
+  Future<void> _initAuth() async {
+    await _authService.init();
+    setState(() => _isLoading = false);
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: _isLoading
+          ? const Scaffold(body: Center(child: CircularProgressIndicator()))
+          : _authService.isAuthenticated
+              ? HomeScreen(authService: _authService, onChanged: _refresh)
+              : LoginScreen(authService: _authService, onChanged: _refresh),
+    );
+  }
+
+  void _refresh() => setState(() {});
+}
+
+class LoginScreen extends StatelessWidget {
+  final AuthService authService;
+  final VoidCallback onChanged;
+  const LoginScreen({super.key, required this.authService, required this.onChanged});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: Center(
+        child: ElevatedButton(
+          onPressed: () async {
+            // Capture the messenger before the await to avoid using
+            // BuildContext across an async gap.
+            final messenger = ScaffoldMessenger.of(context);
+            try {
+              await authService.login();
+              onChanged();
+            } on WebAuthenticationException catch (e) {
+              messenger.showSnackBar(
+                SnackBar(content: Text('Login failed: ${e.message}')),
+              );
+            }
+          },
+          child: const Text('Log In'),
+        ),
+      ),
+    );
+  }
+}
+
+class HomeScreen extends StatelessWidget {
+  final AuthService authService;
+  final VoidCallback onChanged;
+  const HomeScreen({super.key, required this.authService, required this.onChanged});
+
+  @override
+  Widget build(BuildContext context) {
+    final user = authService.user;
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('Home'),
+        actions: [
+          IconButton(
+            onPressed: () async {
+              await authService.logout();
+              onChanged();
+            },
+            icon: const Icon(Icons.logout),
+          ),
+        ],
+      ),
+      body: Center(
+        child: Column(
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: [
+            if (user?.pictureUrl != null)
+              CircleAvatar(
+                backgroundImage: NetworkImage(user!.pictureUrl.toString()),
+                radius: 40,
+              ),
+            const SizedBox(height: 16),
+            Text('Welcome, ${user?.name ?? 'User'}!'),
+            Text(user?.email ?? ''),
+          ],
+        ),
+      ),
+    );
+  }
+}
+```
+
+#### Provider (State Management)
+
+> **Agent instruction:** If the project uses `provider`, create `AuthService` as a `ChangeNotifier` and inject it via `ChangeNotifierProvider` at the app root.
+
+```dart
+// lib/auth_service.dart
+import 'package:flutter/foundation.dart';
+import 'package:auth0_flutter/auth0_flutter.dart';
+
+class AuthService extends ChangeNotifier {
+  late final Auth0 _auth0;
+  Credentials? _credentials;
+  bool _isLoading = true;
+
+  AuthService({required String domain, required String clientId}) {
+    _auth0 = Auth0(domain, clientId);
+  }
+
+  bool get isAuthenticated => _credentials != null;
+  bool get isLoading => _isLoading;
+  UserProfile? get user => _credentials?.user;
+
+  Future<void> init() async {
+    if (await _auth0.credentialsManager.hasValidCredentials()) {
+      _credentials = await _auth0.credentialsManager.credentials();
+    }
+    _isLoading = false;
+    notifyListeners();
+  }
+
+  Future<void> login() async {
+    _credentials = await _auth0
+        .webAuthentication()
+        .login(scopes: {'openid', 'profile', 'email', 'offline_access'});
+    notifyListeners();
+  }
+
+  Future<void> logout() async {
+    await _auth0.webAuthentication().logout();
+    await _auth0.credentialsManager.clearCredentials();
+    _credentials = null;
+    notifyListeners();
+  }
+}
+```
+
+```dart
+// lib/main.dart — wrap with ChangeNotifierProvider
+import 'package:provider/provider.dart';
+
+void main() {
+  runApp(
+    ChangeNotifierProvider(
+      create: (_) => AuthService(
+        domain: 'YOUR_AUTH0_DOMAIN',
+        clientId: 'YOUR_AUTH0_CLIENT_ID',
+      )..init(),
+      child: const MyApp(),
+    ),
+  );
+}
+```
+
+For complete patterns with Riverpod, Bloc, biometrics, and advanced scenarios, see the Integration Patterns section (below).
+
+### Step 7 — Verify Build
+
+> **Agent instruction:** Run a build to verify the integration compiles without errors:
+> ```bash
+> flutter build apk --debug      # Android
+> flutter build ios --no-codesign  # iOS (on macOS)
+> ```
+> Then run the app on a device or emulator to test:
+> ```bash
+> flutter run
+> ```
+> If the build fails, review error messages and fix up to 5 times before asking the user.
+>
+> **Physical device testing:** Biometric protection (Face ID / Touch ID / fingerprint) cannot be exercised on a simulator/emulator — the iOS Simulator and Android emulator have limited or no biometric hardware. Test biometrics and the full Universal Login redirect on a real physical device before release.
+
+## Detailed Documentation
+
+- **Setup Guide** (see the Setup Guide section below) — Auth0 application creation via the Auth0 CLI, Android `manifestPlaceholders`, iOS `Info.plist` / Associated Domains, callback URL registration
+- **Integration Patterns** (see the Integration Patterns section below) — Web Auth login/logout, CredentialsManager, biometric protection, custom schemes, organizations, API access tokens, state management patterns, error handling
+- **API Reference & Testing** (see the API Reference & Testing section below) — Full API reference, configuration options, claims reference, testing checklist, troubleshooting
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Auth0 app type not set to **Native** | Create the application with `auth0 apps create --type native` (or select "Native" in the Auth0 Dashboard) |
+| Missing `manifestPlaceholders` on Android | Add `manifestPlaceholders = [auth0Domain: "...", auth0Scheme: "https"]` to `android/app/build.gradle` `defaultConfig` — the build fails without it |
+| Using `Auth0Web` on mobile | Mobile uses the `Auth0` class with `webAuthentication()`, not `Auth0Web` (that's the web-only API) |
+| Importing `auth0_flutter_web.dart` on mobile | Only import `package:auth0_flutter/auth0_flutter.dart` — the `_web` import is for Flutter web |
+| Callback URL mismatch | Register `https://YOUR_DOMAIN/android/PACKAGE_NAME/callback` and `https://YOUR_DOMAIN/ios/BUNDLE_ID/callback` in Allowed Callback URLs |
+| Scheme mismatch between Gradle and Dart | If `auth0Scheme` is a custom scheme, pass the same value to `webAuthentication(scheme: 'myscheme')` |
+| Custom scheme with uppercase letters on Android | Android custom schemes must be all lowercase |
+| Biometrics prompt never appears on Android | `MainActivity` must extend `FlutterFragmentActivity` (not `FlutterActivity`) for the biometric prompt to work |
+| Not storing credentials after login | `webAuthentication().login()` stores credentials automatically; do NOT also re-store unless renewing manually via `api.renewCredentials` |
+| Not restoring session on startup | Call `credentialsManager.hasValidCredentials()` + `credentials()` in `initState()` to restore the session |
+| Missing `offline_access` scope | Add `'offline_access'` to scopes so the CredentialsManager can silently renew expired access tokens with a refresh token |
+| Catching generic `Exception` | Catch `WebAuthenticationException` (login/logout) and `CredentialsManagerException` (credential errors) and inspect `isUserCancelledException`, `isNoCredentialsFound`, `isTokenRenewFailed`, etc. |
+
+## Related capabilities
+
+- Initial Auth0 setup and account creation — if Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Same SDK on the web platform — ask for the Auth0 Flutter web integration
+- Native iOS (Swift) — ask for the Auth0 Swift integration
+- Native Android (Kotlin/Java) — ask for the Auth0 Android integration
+
+## Quick Reference
+
+| API | Purpose |
+|-----|---------|
+| `Auth0(domain, clientId)` | Create the SDK client |
+| `auth0.webAuthentication().login(...)` | Launch Universal Login in the system browser |
+| `auth0.webAuthentication().logout()` | Clear the browser session |
+| `auth0.webAuthentication(scheme: '...')` | Use a custom URL scheme |
+| `auth0.credentialsManager.credentials()` | Get stored credentials (auto-renews if expired) |
+| `auth0.credentialsManager.hasValidCredentials()` | Check for a valid stored session |
+| `auth0.credentialsManager.clearCredentials()` | Wipe stored credentials |
+| `LocalAuthentication(title: ...)` | Enable biometric protection of stored credentials |
+
+## References
+
+- [auth0_flutter on pub.dev](https://pub.dev/packages/auth0_flutter)
+- [auth0_flutter GitHub](https://github.com/auth0/auth0-flutter)
+- [Flutter Quickstart (Native)](https://auth0.com/docs/quickstart/native/flutter)
+- [Auth0 Dashboard](https://manage.auth0.com)
diff --git a/main/.mintlify/skills/auth0/references/framework-flutter-web/index.md b/main/.mintlify/skills/auth0/references/framework-flutter-web/index.md
new file mode 100644
index 0000000000..9bce72a77f
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-flutter-web/index.md
@@ -0,0 +1,375 @@
+# Auth0 Flutter Web
+
+> Ported from auth0/auth0-flutter-web skill.
+
+---
+
+
+# Auth0 Flutter Web Integration
+
+`auth0_flutter` is the official Auth0 SDK for Flutter applications. On the **web platform**, it wraps the Auth0 SPA JS SDK to provide browser-based authentication via redirect or popup flows with built-in credential caching and automatic token renewal.
+
+> **Agent instruction:** The current SDK version is `2.1.0`. Use this version in all dependency lines below. If you need to verify, run `flutter pub add auth0_flutter` which will resolve the latest compatible version automatically.
+
+## When NOT to Use
+
+- **Flutter mobile (iOS/Android)**: use the Auth0 integration workflow for Flutter native — mobile uses a different platform interface with Web Auth via system browser
+- **Native iOS (Swift)**: use the Auth0 integration workflow for Swift
+- **Native Android (Kotlin/Java)**: use the Auth0 integration workflow for Android
+- **React SPA**: use the Auth0 integration workflow for React
+- **Angular SPA**: use the Auth0 integration workflow for Angular
+- **Vue SPA**: use the Auth0 integration workflow for Vue
+- **Node.js/Express servers**: use the Auth0 integration workflow for Express
+
+## Prerequisites
+
+- **Flutter** 3.24.0+
+- **Dart** 3.5.0+
+- Auth0 account — [Sign up free](https://auth0.com/signup)
+- Auth0 CLI — [install instructions](https://github.com/auth0/auth0-cli) (used to create and configure the Auth0 application)
+
+## Quick Start Workflow
+
+> **Agent instruction:** Follow these steps in order. If you encounter an error at any step, attempt to fix it up to 5 times before calling `AskUserQuestion` to ask the user for guidance. Always search existing code first — if there are existing login/logout handlers, hook into them rather than creating new ones.
+
+### Step 1 — Install SDK
+
+> **Agent instruction:** Check the project directory for `pubspec.yaml`. If present, add the dependency. If not found, this is not a Flutter project — ask the user.
+>
+> Run in the project root:
+>
+> ```bash
+> flutter pub add auth0_flutter
+> ```
+>
+> Verify the dependency was added to `pubspec.yaml`:
+>
+> ```yaml
+> dependencies:
+>   auth0_flutter: ^2.1.0
+> ```
+
+### Step 2 — Configure Auth0
+
+> **Note:** For Single Page Applications, the Auth0 Domain and Client ID are **public configuration** (not secrets). A SPA uses PKCE with no client secret, and these values ship in the browser bundle. Pass them directly to `Auth0Web(domain, clientId)` — there is no need to store them in environment variables or hide them.
+>
+> **Agent instruction:**
+> - **If Auth0 credentials (domain AND client ID) are already in the user's prompt:** Proceed to Step 3 and use those values directly in the `Auth0Web(...)` constructor.
+> - **If no credentials are provided:** Create the application with the Auth0 CLI — do NOT ask the user to create or configure an Auth0 application manually in the Dashboard. Always use the CLI path.
+>
+> Follow the Setup Guide — Auth0 Configuration section (below) for the pre-flight checks and the `auth0 apps create` command.
+
+### Step 3 — Add Auth0 SPA JS to index.html
+
+> **Agent instruction:**
+> 1. Locate the web entry point: `web/index.html`
+> 2. Add the Auth0 SPA JS script tag inside `<head>`:
+>
+> ```html
+> <script src="https://cdn.auth0.com/js/auth0-spa-js/2.1/auth0-spa-js.production.js" defer></script>
+> ```
+>
+> If `web/index.html` does not exist, the user may need to run `flutter create . --platforms=web` to add web support.
+
+### Step 4 — Configure Callback URLs
+
+> **Agent instruction:**
+> 1. Determine the app's web URL. For local development, default is `http://localhost:3000` (when running with `--web-port 3000`).
+> 2. Ask the user via `AskUserQuestion`: _"What port will you run your Flutter web app on locally? (default: 3000)"_
+> 3. Register the callback URLs using the Auth0 CLI (substitute real values for `CLIENT_ID`, `APP_URL`):
+>
+> ```bash
+> auth0 apps update CLIENT_ID \
+>   --callbacks "APP_URL" \
+>   --logout-urls "APP_URL" \
+>   --web-origins "APP_URL" \
+>   --no-input
+> ```
+>
+> For production, also add the production URL to each list.
+
+### Step 5 — Implement Authentication
+
+> **Agent instruction:** Search the project for the main app entry point (`main.dart`). Determine the state management approach:
+> - Look for `provider`, `riverpod`, `bloc`, `GetX`, or `mobx` imports
+> - If none found, use basic `StatefulWidget` with `setState`
+>
+> Then follow **only** the matching path below. If ambiguous, ask via `AskUserQuestion`: _"Which state management approach does your Flutter app use — Provider, Riverpod, Bloc, or basic setState?"_
+
+#### Basic StatefulWidget (Default)
+
+> **Agent instruction:** Create an `AuthService` class, then wire it into the app's root widget. Search for the `MaterialApp` or `CupertinoApp` widget and update accordingly.
+
+```dart
+// lib/auth_service.dart
+import 'package:auth0_flutter/auth0_flutter.dart';
+import 'package:auth0_flutter/auth0_flutter_web.dart';
+
+class AuthService {
+  late final Auth0Web _auth0;
+  Credentials? _credentials;
+
+  AuthService({required String domain, required String clientId}) {
+    _auth0 = Auth0Web(domain, clientId);
+  }
+
+  bool get isAuthenticated => _credentials != null;
+  Credentials? get credentials => _credentials;
+  UserProfile? get user => _credentials?.user;
+
+  /// Call on app startup to restore session from cache
+  Future<void> onLoad() async {
+    _credentials = await _auth0.onLoad();
+  }
+
+  /// Redirect to Auth0 Universal Login
+  Future<void> loginWithRedirect({String? redirectUrl}) async {
+    await _auth0.loginWithRedirect(
+      redirectUrl: redirectUrl,
+      scopes: {'openid', 'profile', 'email', 'offline_access'},
+    );
+  }
+
+  /// Open Auth0 login in a popup window
+  Future<void> loginWithPopup() async {
+    _credentials = await _auth0.loginWithPopup(
+      scopes: {'openid', 'profile', 'email', 'offline_access'},
+    );
+  }
+
+  /// Get cached credentials (auto-refreshes if expired)
+  Future<Credentials> getCredentials() async {
+    final creds = await _auth0.credentials();
+    _credentials = creds;
+    return creds;
+  }
+
+  /// Check if valid credentials exist
+  Future<bool> hasValidCredentials() async {
+    return await _auth0.hasValidCredentials();
+  }
+
+  /// Logout and redirect back to the app
+  Future<void> logout({String? returnToUrl}) async {
+    await _auth0.logout(returnToUrl: returnToUrl);
+    _credentials = null;
+  }
+}
+```
+
+```dart
+// lib/main.dart
+import 'package:flutter/material.dart';
+import 'auth_service.dart';
+
+void main() {
+  runApp(const MyApp());
+}
+
+class MyApp extends StatefulWidget {
+  const MyApp({super.key});
+
+  @override
+  State<MyApp> createState() => _MyAppState();
+}
+
+class _MyAppState extends State<MyApp> {
+  final _authService = AuthService(
+    domain: 'YOUR_AUTH0_DOMAIN',
+    clientId: 'YOUR_AUTH0_CLIENT_ID',
+  );
+  bool _isLoading = true;
+
+  @override
+  void initState() {
+    super.initState();
+    _initAuth();
+  }
+
+  Future<void> _initAuth() async {
+    await _authService.onLoad();
+    setState(() => _isLoading = false);
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: _isLoading
+          ? const Scaffold(body: Center(child: CircularProgressIndicator()))
+          : _authService.isAuthenticated
+              ? HomeScreen(authService: _authService)
+              : LoginScreen(authService: _authService),
+    );
+  }
+}
+
+class LoginScreen extends StatelessWidget {
+  final AuthService authService;
+  const LoginScreen({super.key, required this.authService});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: Center(
+        child: ElevatedButton(
+          onPressed: () => authService.loginWithRedirect(),
+          child: const Text('Log In'),
+        ),
+      ),
+    );
+  }
+}
+
+class HomeScreen extends StatelessWidget {
+  final AuthService authService;
+  const HomeScreen({super.key, required this.authService});
+
+  @override
+  Widget build(BuildContext context) {
+    final user = authService.user;
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('Home'),
+        actions: [
+          IconButton(
+            onPressed: () => authService.logout(
+              returnToUrl: Uri.base.origin,
+            ),
+            icon: const Icon(Icons.logout),
+          ),
+        ],
+      ),
+      body: Center(
+        child: Column(
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: [
+            if (user?.pictureUrl != null)
+              CircleAvatar(
+                backgroundImage: NetworkImage(user!.pictureUrl.toString()),
+                radius: 40,
+              ),
+            const SizedBox(height: 16),
+            Text('Welcome, ${user?.name ?? 'User'}!'),
+            Text(user?.email ?? ''),
+          ],
+        ),
+      ),
+    );
+  }
+}
+```
+
+#### Provider (State Management)
+
+> **Agent instruction:** If the project uses `provider`, create `AuthService` as a `ChangeNotifier` and inject it via `ChangeNotifierProvider` at the app root.
+
+```dart
+// lib/auth_service.dart
+import 'package:flutter/foundation.dart';
+import 'package:auth0_flutter/auth0_flutter.dart';
+import 'package:auth0_flutter/auth0_flutter_web.dart';
+
+class AuthService extends ChangeNotifier {
+  late final Auth0Web _auth0;
+  Credentials? _credentials;
+  bool _isLoading = true;
+
+  AuthService({required String domain, required String clientId}) {
+    _auth0 = Auth0Web(domain, clientId);
+  }
+
+  bool get isAuthenticated => _credentials != null;
+  bool get isLoading => _isLoading;
+  UserProfile? get user => _credentials?.user;
+
+  Future<void> init() async {
+    _credentials = await _auth0.onLoad();
+    _isLoading = false;
+    notifyListeners();
+  }
+
+  Future<void> loginWithRedirect() async {
+    await _auth0.loginWithRedirect(
+      scopes: {'openid', 'profile', 'email', 'offline_access'},
+    );
+  }
+
+  Future<void> loginWithPopup() async {
+    _credentials = await _auth0.loginWithPopup(
+      scopes: {'openid', 'profile', 'email', 'offline_access'},
+    );
+    notifyListeners();
+  }
+
+  Future<void> logout() async {
+    await _auth0.logout(returnToUrl: Uri.base.origin);
+    _credentials = null;
+    notifyListeners();
+  }
+}
+```
+
+```dart
+// lib/main.dart — wrap with ChangeNotifierProvider
+import 'package:provider/provider.dart';
+
+void main() {
+  runApp(
+    ChangeNotifierProvider(
+      create: (_) => AuthService(
+        domain: 'YOUR_AUTH0_DOMAIN',
+        clientId: 'YOUR_AUTH0_CLIENT_ID',
+      )..init(),
+      child: const MyApp(),
+    ),
+  );
+}
+```
+
+For complete patterns with Riverpod, Bloc, and advanced scenarios, see the Integration Patterns section (below).
+
+### Step 6 — Verify Build
+
+> **Agent instruction:** Run a build to verify the integration compiles without errors:
+>
+> ```bash
+> flutter build web
+> ```
+>
+> Then run the app locally to test:
+>
+> ```bash
+> flutter run -d chrome --web-port 3000
+> ```
+>
+> If the build fails, review error messages and fix up to 5 times before asking the user.
+
+## Detailed Documentation
+
+- **Setup Guide** (see the Setup Guide section below) — Auth0 application creation via the Auth0 CLI, web/index.html setup, callback URL registration
+- **Integration Patterns** (see the Integration Patterns section below) — Redirect login, popup login, credential management, state management patterns, organization support, error handling
+- **API Reference & Testing** (see the API Reference & Testing section below) — Full API reference, configuration options, claims reference, testing checklist, troubleshooting
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Auth0 app type not set to **Single Page Application** | In Auth0 Dashboard, select "Single Page Application" when creating the application |
+| Missing Auth0 SPA JS script in `web/index.html` | Add `<script src="https://cdn.auth0.com/js/auth0-spa-js/2.1/auth0-spa-js.production.js" defer></script>` to `<head>` |
+| Not calling `onLoad()` on app startup | Always call `onLoad()` in `initState()` or equivalent to restore sessions after redirect |
+| Missing `Allowed Web Origins` in Auth0 Dashboard | Add your app URL (e.g., `http://localhost:3000`) to Allowed Web Origins — required for silent token renewal |
+| Using `auth0_flutter` mobile API on web | Import **both** `package:auth0_flutter/auth0_flutter.dart` (for types like `Credentials`, `UserProfile`) AND `package:auth0_flutter/auth0_flutter_web.dart` (for `Auth0Web` class) |
+| Missing base import causes type errors | `Credentials` and `UserProfile` are exported from `auth0_flutter.dart`, not `auth0_flutter_web.dart` — you need both imports |
+| Callback URL mismatch | Ensure `Allowed Callback URLs` matches the exact URL where your app runs (including port) |
+| Not adding `--web-port` when running locally | Use `flutter run -d chrome --web-port 3000` to ensure consistent port matching callback URLs |
+| Popup blocked by browser | `loginWithPopup()` must be called from a direct user interaction (button click); cannot be called from `initState()` |
+| Missing `offline_access` scope | Add `'offline_access'` to scopes set to enable refresh token rotation for silent renewal |
+| CORS errors on token endpoint | Ensure `Allowed Web Origins` is configured in Auth0 Dashboard (not just Callback URLs) |
+
+## References
+
+- [auth0_flutter on pub.dev](https://pub.dev/packages/auth0_flutter)
+- [auth0_flutter GitHub](https://github.com/auth0/auth0-flutter)
+- [Flutter Web Quickstart](https://auth0.com/docs/quickstart/spa/flutter)
+- [Auth0 Dashboard](https://manage.auth0.com)
+- [Auth0 SPA JS SDK](https://github.com/auth0/auth0-spa-js)
diff --git a/main/.mintlify/skills/auth0/references/framework-go/index.md b/main/.mintlify/skills/auth0/references/framework-go/index.md
new file mode 100644
index 0000000000..777101b5ed
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-go/index.md
@@ -0,0 +1,1610 @@
+
+# Go JWT Middleware Integration
+
+Protect Go HTTP API endpoints with JWT access token validation using github.com/auth0/go-jwt-middleware/v3.
+
+## Critical rules
+
+- Access token values must stay out of the agent's view. Capture a token into a shell variable inside a single command chain and use it there; print only its length, and discard the shell variable when the command ends. The token itself remains valid until normal expiry or revocation.
+- To obtain a client secret, always have the user run `auth0 apps show <CLIENT_ID> --reveal-secrets` in their own terminal, rather than running `--reveal-secrets` from the agent.
+- A Client ID is required to run `auth0 test token`; complete the M2M application setup first to obtain it.
+
+> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
+> ```bash
+> gh api repos/auth0/go-jwt-middleware/releases/latest --jq '.tag_name'
+> ```
+> Use the returned version in all dependency lines instead of any hardcoded version below.
+
+## Prerequisites
+
+- Go 1.21 or higher
+- Auth0 API configured (not Application - must be API resource)
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **Go server-rendered web applications** - Use `go-auth0` for session-based web apps
+- **Single Page Applications** - Use the Auth0 integration workflow for React, Vue, or Angular for client-side auth
+- **Mobile applications** - Use the Auth0 integration workflow for Swift, Android, or React Native
+- **Non-Go backends** - Use the Auth0 integration workflow for ASP.NET Core (.NET), or `express-jwt` for Node.js
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+go get github.com/auth0/go-jwt-middleware/v3
+go get github.com/joho/godotenv
+```
+
+### 2. Create Auth0 API
+
+You need an **API** (not Application) in Auth0.
+
+> **Agent instruction:** If the user's prompt already provides Auth0 credentials (domain and audience), use them directly — skip the setup choice question below and proceed to Step 3 to write the `.env` file.
+>
+> **STOP — ask the user before proceeding.**
+>
+> Ask exactly this question and wait for their answer before doing anything else:
+>
+> > "How would you like to create the Auth0 API resource?
+> > 1. **Automated** — I'll use the Auth0 CLI to create the API resource and write the exact values to your .env file automatically.
+> > 2. **Manual** — You create the API yourself in the Auth0 Dashboard (or via `auth0 apis create`) and provide me the Domain and Audience.
+> >
+> > Which do you prefer? (1 = Automated / 2 = Manual)"
+>
+> Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.
+
+**If the user chose Automated**, follow the Setup Guide section below for the "Initial Setup" section (steps 1–6). The automated path writes `.env` for you — skip Step 3 below and proceed directly to Step 4.
+
+> **Agent instruction (Automated path checkpoints):**
+>
+> When following the automated path, you MUST complete these checkpoints in order. Do NOT skip any:
+>
+> 1. **Check Auth0 CLI** — verify `auth0` is installed.
+> 2. **Check Auth0 login** — run `auth0 tenants list` to verify authentication.
+> 3. **Confirm active tenant** — show the user which tenant is active and ask: _"Your active Auth0 tenant is `<domain>`. Is this the correct tenant?"_ Wait for confirmation. If they say no, ask them to run `auth0 tenants use <tenant>` in their terminal.
+> 4. **Ask about API name and identifier** — use `AskUserQuestion`: _"What would you like to name your Auth0 API, and what identifier (audience) should it use? For example: Name: 'My Go API', Identifier: 'https://my-api.example.com'. The identifier is a logical URI that doesn't need to resolve — it just uniquely identifies your API."_ Wait for answer. If the user is unsure, suggest deriving the identifier from the project's module name in go.mod (e.g., `https://<module-name>`).
+> 5. **Ask about scopes** — use `AskUserQuestion`: _"What scopes (permissions) does your API need? For example: `read:users`, `write:users`, `read:products`. If you're not sure yet, I can start with common defaults and you can add more later."_ Wait for answer.
+> 6. **Check for existing API** — run `auth0 apis list` and check if an API with the intended identifier already exists. If it does, ask the user whether to reuse it or create a new one with a different identifier.
+> 7. **Create the API resource** — using the name, identifier, and scopes from steps 4–5.
+> 8. **Handle .env** — if a `.env` file already exists, ask before modifying it. Never read existing `.env` contents (may contain secrets). If no `.env` exists, write one with `AUTH0_DOMAIN` and `AUTH0_AUDIENCE`.
+> 9. **Add `.env` to `.gitignore`** — if not already present.
+> 10. **Proceed to code integration** — skip Step 3 (already done) and go directly to Step 4 to write the middleware code.
+
+**If the user chose Manual**, follow the Setup Guide section below (Manual Setup) for full instructions. Then continue with Step 3 below.
+
+Quick reference for manual API creation:
+
+```bash
+# Using Auth0 CLI
+auth0 apis create \
+  --name "My Go API" \
+  --identifier https://my-api.example.com
+```
+
+Or create manually in Auth0 Dashboard → Applications → APIs
+
+### 3. Configure .env
+
+```env
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_AUDIENCE=https://my-api.example.com
+```
+
+**Important:** Domain must NOT include `https://`. The middleware constructs the issuer URL automatically.
+
+### 4. Configure main.go
+
+> **Agent instruction (integrating with existing code):**
+>
+> Before writing code, determine whether you are:
+> - **A) Adding auth to an existing project** — the user already has a `main.go` with routes defined. In this case, do NOT replace their file with the template below. Instead:
+>   1. Add the necessary imports (`jwtmiddleware`, `jwks`, `validator`, `godotenv`, `net/url`, `os`, `context`, `strings`).
+>   2. Add the `CustomClaims` struct and methods.
+>   3. Add the middleware setup code (issuer URL, JWKS provider, validator, middleware) near the top of `main()`.
+>   4. Ask which endpoints to protect (see below).
+>   5. Wrap the specified handlers with `middleware.CheckJWT()`.
+>
+> - **B) Creating a new project from scratch** — use the full template below as a starting point.
+>
+> **STOP — ask which endpoints to protect:**
+>
+> If the user's request does NOT explicitly specify which endpoints to protect, ask:
+>
+> > "Which endpoints should require authentication? For example:
+> > - **All except health/public** — protect everything, leave only specific public routes open
+> > - **Specific routes** — tell me which routes need auth
+> >
+> > Also, do any endpoints need specific scope/permission checks (e.g., `write:users` for POST/DELETE), or is a valid JWT sufficient for all?"
+>
+> Wait for the answer. If the user says "all" or "everything except health", protect all routes except `/health` (or whatever they specify as public). If they specify scope requirements per endpoint, implement per-route scope checks using `customClaims.HasScope()`.
+
+```go
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+
+	jwtmiddleware "github.com/auth0/go-jwt-middleware/v3"
+	"github.com/auth0/go-jwt-middleware/v3/jwks"
+	"github.com/auth0/go-jwt-middleware/v3/validator"
+	"github.com/joho/godotenv"
+)
+
+// CustomClaims contains custom data we want from the token.
+type CustomClaims struct {
+	Scope       string   `json:"scope"`
+	Permissions []string `json:"permissions"`
+}
+
+func (c CustomClaims) Validate(ctx context.Context) error {
+	return nil
+}
+
+func (c CustomClaims) HasScope(expectedScope string) bool {
+	for _, scope := range strings.Split(c.Scope, " ") {
+		if scope == expectedScope {
+			return true
+		}
+	}
+	return false
+}
+
+func main() {
+	if err := godotenv.Load(); err != nil {
+		log.Fatalf("Error loading .env file: %v", err)
+	}
+
+	issuerURL, err := url.Parse("https://" + os.Getenv("AUTH0_DOMAIN") + "/")
+	if err != nil {
+		log.Fatalf("Failed to parse issuer URL: %v", err)
+	}
+
+	provider, err := jwks.NewCachingProvider(
+		jwks.WithIssuerURL(issuerURL),
+	)
+	if err != nil {
+		log.Fatalf("Failed to set up JWKS provider: %v", err)
+	}
+
+	jwtValidator, err := validator.New(
+		validator.WithKeyFunc(provider.KeyFunc),
+		validator.WithAlgorithm(validator.RS256),
+		validator.WithIssuer(issuerURL.String()),
+		validator.WithAudience(os.Getenv("AUTH0_AUDIENCE")),
+		validator.WithCustomClaims(func() validator.CustomClaims {
+			return &CustomClaims{}
+		}),
+	)
+	if err != nil {
+		log.Fatalf("Failed to set up JWT validator: %v", err)
+	}
+
+	middleware, err := jwtmiddleware.New(
+		jwtmiddleware.WithValidator(jwtValidator),
+	)
+	if err != nil {
+		log.Fatalf("Failed to set up JWT middleware: %v", err)
+	}
+
+	mux := http.NewServeMux()
+
+	// Public endpoint - no authentication
+	mux.HandleFunc("/api/public", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]string{"message": "Hello from a public endpoint!"})
+	})
+
+	// Protected endpoint - requires valid JWT
+	mux.Handle("/api/private", middleware.CheckJWT(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
+		if err != nil {
+			http.Error(w, `{"message":"Failed to get token claims."}`, http.StatusInternalServerError)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]string{
+			"message": "Hello from a private endpoint!",
+			"userId":  claims.RegisteredClaims.Subject,
+		})
+	})))
+
+	// Protected + scoped endpoint - requires JWT with specific scope
+	mux.Handle("/api/private-scoped", middleware.CheckJWT(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
+		if err != nil {
+			http.Error(w, `{"message":"Failed to get token claims."}`, http.StatusInternalServerError)
+			return
+		}
+		customClaims := claims.CustomClaims.(*CustomClaims)
+		if !customClaims.HasScope("read:messages") {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusForbidden)
+			json.NewEncoder(w).Encode(map[string]string{"message": "Insufficient scope."})
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]string{"message": "Hello from a scoped endpoint!"})
+	})))
+
+	log.Println("Server listening on :8080")
+	log.Fatal(http.ListenAndServe(":8080", mux))
+}
+```
+
+### 5. Protect Endpoints
+
+Use `middleware.CheckJWT()` to wrap handlers that require authentication:
+
+```go
+// Public endpoint - no authentication
+mux.HandleFunc("/api/public", publicHandler)
+
+// Protected endpoint - requires valid JWT
+mux.Handle("/api/private", middleware.CheckJWT(http.HandlerFunc(privateHandler)))
+
+// Protected + scoped - requires JWT with specific permission
+mux.Handle("/api/private-scoped", middleware.CheckJWT(http.HandlerFunc(privateScopedHandler)))
+```
+
+### 6. Test API
+
+> **Agent instruction:** After writing the code, verify the build compiles:
+> ```bash
+> go build ./...
+> ```
+> If compilation fails, diagnose the error and fix it. Repeat up to 5-6 times.
+>
+> **Failcheck:** If the build still fails after 5-6 fix attempts, stop and ask the user using `AskUserQuestion`:
+> _"The build is still failing after several fix attempts. How would you like to proceed?"_
+> - **Let me continue fixing iteratively**
+> - **Fix it manually** — I'll show the remaining errors
+> - **Skip build verification** — proceed without a successful build
+>
+> Repeat this check after every 5-6 iterations if errors persist.
+
+> **Agent instruction: STOP — ask after build succeeds.**
+>
+> Once the build compiles successfully, ask the user:
+>
+> > "Your API is set up and compiles successfully. Would you like me to help you set up testing?
+> > 1. **Yes** — I'll help you configure an M2M application to get test tokens.
+> > 2. **No** — I'm done for now.
+> >
+> > Which do you prefer?"
+>
+> Do NOT proceed with testing setup unless the user says yes. If they say no, summarize what was done and stop.
+
+> **Agent instruction (M2M app setup — only if user wants testing):**
+>
+> If the user chose to set up testing, ask:
+>
+> > "To test your protected endpoints, you need a Machine-to-Machine (M2M) application authorized to request tokens for this API.
+> > 1. **Create new** — I'll create a new M2M application and authorize it for this API.
+> > 2. **Use existing** — You already have an M2M application. Provide the Client ID and I'll authorize it for this API.
+> >
+> > Which do you prefer? (1 = Create new / 2 = Use existing)"
+>
+> Do NOT proceed until the user answers. Do NOT silently pick an existing application from the tenant.
+>
+> **If the user chose "Create new":**
+> ```bash
+> auth0 apps create \
+>   --name "<PROJECT_NAME> (Test App)" \
+>   --type m2m \
+>   --no-input --json
+> ```
+> Parse the JSON to extract `client_id`. Do NOT use `--reveal-secrets` — instead, if the client secret is needed, have the user run `auth0 apps show <CLIENT_ID> --reveal-secrets` in their own terminal so secrets stay out of the agent context.
+> Then create a client grant:
+> ```bash
+> auth0 api post "client-grants" --data '{
+>   "client_id": "<CLIENT_ID>",
+>   "audience": "<API_IDENTIFIER>",
+>   "scope": ["<SCOPES>"]
+> }'
+> ```
+>
+> **If the user chose "Use existing":**
+> Ask for the Client ID. Then create a client grant to authorize it for this API:
+> ```bash
+> auth0 api post "client-grants" --data '{
+>   "client_id": "<USER_PROVIDED_CLIENT_ID>",
+>   "audience": "<API_IDENTIFIER>",
+>   "scope": ["<SCOPES>"]
+> }'
+> ```
+> If the grant already exists (409 conflict), that's fine — the app is already authorized.
+
+> **Agent instruction (token isolation — critical):**
+>
+> The agent must never directly see or display access token values. Token security rules:
+> - Do NOT run `auth0 test token` on its own — it outputs the token to stdout
+> - Do NOT run `curl` commands to the `/oauth/token` endpoint on their own
+> - Do NOT ask the user to paste their token into the conversation
+> - Do NOT echo, print, or log the token value
+> - Do NOT store the token in a file
+>
+> **Secure testing approach (single-command chain):**
+>
+> If the user explicitly asks to test the protected endpoints, the agent MAY use a single-command chain that captures the token into a shell variable and immediately uses it — the token value is never printed or visible to the agent:
+>
+> ```bash
+> TEST_TOKEN=$(auth0 test token <CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2> 2>/dev/null | grep -o 'ey[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*') && \
+> [ -n "$TEST_TOKEN" ] && echo "Token acquired (${#TEST_TOKEN} chars)" && \
+> curl -s http://localhost:8080/<ENDPOINT> -H "Authorization: Bearer $TEST_TOKEN"
+> ```
+>
+> **Security guarantees of this approach:**
+> - `$(...)` captures stdout — the token is consumed into the variable, not displayed
+> - `grep -o` extracts only the JWT pattern (ey...) — no surrounding output leaks
+> - `echo "Token acquired (${#TEST_TOKEN} chars)"` confirms success by printing LENGTH only, never the value
+> - The shell variable `$TEST_TOKEN` exists only for the duration of that single command chain — it dies immediately after
+> - Agent sees only: `"Token acquired (834 chars)"` + the API response body (JSON)
+> - No file is written, no env is exported, nothing persists
+>
+> **Rules for using this pattern:**
+> 1. ONLY use when the user explicitly asks to test (e.g., "test it", "run the tests", "verify endpoints work")
+> 2. Always chain token acquisition + curl in a SINGLE `&&` command — never separate them into two Bash calls
+> 3. To test multiple endpoints, chain multiple curls in the same command:
+>    ```bash
+>    TEST_TOKEN=$(auth0 test token <CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2> 2>/dev/null | grep -o 'ey[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*') && \
+>    [ -n "$TEST_TOKEN" ] && echo "Token acquired (${#TEST_TOKEN} chars)" && \
+>    echo "=== GET /users ===" && \
+>    curl -s http://localhost:8080/users -H "Authorization: Bearer $TEST_TOKEN" && \
+>    echo "" && echo "=== POST /users ===" && \
+>    curl -s -X POST http://localhost:8080/users -H "Authorization: Bearer $TEST_TOKEN" -d '{"id":"99","name":"Test","email":"test@example.com"}' && \
+>    echo "" && echo "=== GET /products ===" && \
+>    curl -s http://localhost:8080/products -H "Authorization: Bearer $TEST_TOKEN"
+>    ```
+> 4. Do not add `echo $TEST_TOKEN`, `printf $TEST_TOKEN`, or any command that would print the raw token value — keep the value inside the variable only
+> 5. If the token acquisition fails (empty variable), the `[ -n "$TEST_TOKEN" ]` check will halt the chain — report to the user that the M2M app may not be authorized
+> 6. **Client ID is required** — the `auth0 test token` command requires a Client ID to be passed as the first argument. This must be the `client_id` obtained from the M2M app setup step (create new or use existing). If the M2M step has not been completed yet (no Client ID available), do NOT attempt to run the test token command. Instead, ask the user: _"I need an M2M application Client ID to get a test token. Would you like me to create one or do you have an existing one?"_ — then complete the M2M setup first.
+>
+> **If the user does NOT ask to test**, just provide the commands for them to run manually:
+>
+> ```
+> auth0 test token <CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2>
+> curl http://localhost:8080/<endpoint> -H "Authorization: Bearer <PASTE_TOKEN_HERE>"
+> ```
+
+After M2M setup is complete:
+1. Start the server with `go run .` in the background
+2. Verify public endpoints return 200 and protected endpoints return 401 (no token needed)
+3. If the user asked to test: use the secure single-command chain above for authenticated requests
+4. If the user did NOT ask to test: provide the manual commands and tell them to run in their terminal
+
+Test public endpoint:
+
+```bash
+curl http://localhost:8080/api/public
+```
+
+Test protected endpoint without token (should return 401):
+
+```bash
+curl http://localhost:8080/api/private
+```
+
+Test protected endpoint with token (secure single-command chain):
+
+```bash
+TEST_TOKEN=$(auth0 test token <M2M_CLIENT_ID> --audience https://my-api.example.com --scopes <SCOPE1,SCOPE2> 2>/dev/null | grep -o 'ey[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*') && \
+[ -n "$TEST_TOKEN" ] && echo "Token acquired (${#TEST_TOKEN} chars)" && \
+curl -s http://localhost:8080/api/private -H "Authorization: Bearer $TEST_TOKEN"
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Created Application instead of API in Auth0 | Must create API resource in Auth0 Dashboard → Applications → APIs |
+| Audience doesn't match API Identifier | Must exactly match the API Identifier set in Auth0 Dashboard |
+| Domain includes `https://` | Use `your-tenant.auth0.com` format only - the issuer URL is constructed automatically |
+| Using v2 positional parameters instead of v3 options | v3 uses `validator.WithKeyFunc()`, `validator.WithAlgorithm()` etc. |
+| Missing trailing slash on issuer URL | Issuer must be `https://domain/` with trailing slash |
+| Checking `scope` claim instead of `permissions` for RBAC | Use custom claims struct with `Permissions []string` field |
+| Missing `godotenv.Load()` call | Add `github.com/joho/godotenv` and call `godotenv.Load()` before reading env vars |
+| Using `ContextKey{}` to access claims (v2 pattern) | Use `jwtmiddleware.GetClaims[T]()` type-safe generics instead |
+
+## Scope-Based Authorization
+
+See the Integration Guide section below for defining and enforcing scope and permission policies.
+
+## CORS Configuration
+
+For APIs called from browser-based SPAs, configure CORS before any auth middleware:
+
+```go
+func corsMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Access-Control-Allow-Origin", "http://localhost:3000")
+		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
+		w.Header().Set("Access-Control-Allow-Headers", "Authorization, Content-Type")
+		if r.Method == "OPTIONS" {
+			w.WriteHeader(http.StatusNoContent)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+```
+
+Apply it as the outermost handler wrapping your mux:
+
+```go
+handler := corsMiddleware(mux)
+log.Fatal(http.ListenAndServe(":8080", handler))
+```
+
+See the Integration Guide section below for detailed CORS patterns.
+
+## DPoP Support
+
+Built-in proof-of-possession token binding per RFC 9449. See the Integration Guide section below for configuration.
+
+## Related Skills
+
+- Auth0 setup → set it up with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+
+## Quick Reference
+
+**Configuration Options:**
+- `validator.WithKeyFunc(provider.KeyFunc)` - JWKS key function for signature verification (required)
+- `validator.WithAlgorithm(validator.RS256)` - Expected signing algorithm (required)
+- `validator.WithIssuer(url)` - Token issuer URL with trailing slash (required)
+- `validator.WithAudience(aud)` - API Identifier from Auth0 API settings (required)
+- `validator.WithCustomClaims(fn)` - Factory for custom claims struct
+- `validator.WithAllowedClockSkew(d)` - Clock skew tolerance
+
+**Claims Access:**
+- `jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())` - Type-safe claims retrieval
+- `claims.RegisteredClaims.Subject` - User ID (sub)
+- `claims.CustomClaims.(*CustomClaims).Scope` - Space-separated scopes
+- `claims.CustomClaims.(*CustomClaims).Permissions` - Permission strings
+
+**Common Use Cases:**
+- Protect routes → `middleware.CheckJWT(handler)` (see Step 5)
+- Permission enforcement → see the Integration Guide section below
+- DPoP token binding → see the Integration Guide section below
+- Framework adapters (Gin, Echo) → see the Integration Guide section below
+- Advanced JWT config → see the API Reference section below
+
+## References
+
+- [Auth0 Go API Quickstart](https://auth0.com/docs/quickstart/backend/golang/interactive)
+- [SDK GitHub Repository](https://github.com/auth0/go-jwt-middleware)
+- [Go Package Documentation](https://pkg.go.dev/github.com/auth0/go-jwt-middleware/v3)
+- [Access Tokens Guide](https://auth0.com/docs/secure/tokens/access-tokens)
+- [Migration Guide (v2 to v3)](https://github.com/auth0/go-jwt-middleware/blob/master/MIGRATION_GUIDE.md)
+
+---
+
+# Go JWT Middleware API Reference
+
+Complete reference for github.com/auth0/go-jwt-middleware/v3 configuration options.
+
+---
+
+## Validator Options
+
+Create a validator with `validator.New()` using functional options:
+
+```go
+jwtValidator, err := validator.New(
+	validator.WithKeyFunc(provider.KeyFunc),
+	validator.WithAlgorithm(validator.RS256),
+	validator.WithIssuer(issuerURL.String()),
+	validator.WithAudience(os.Getenv("AUTH0_AUDIENCE")),
+)
+```
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `validator.WithKeyFunc(fn)` | `func(context.Context) (any, error)` | Yes | Key function for signature verification. Use `provider.KeyFunc` from JWKS provider. |
+| `validator.WithAlgorithm(alg)` | `validator.Algorithm` | Yes | Expected signing algorithm. Use `validator.RS256` for Auth0. |
+| `validator.WithIssuer(url)` | `string` | Yes | Token issuer URL. Must be `https://{domain}/` with trailing slash. |
+| `validator.WithAudience(aud)` | `string` | Yes | Expected audience. Must match API Identifier in Auth0 Dashboard. |
+| `validator.WithCustomClaims(fn)` | `func() validator.CustomClaims` | No | Factory function returning a custom claims struct. |
+| `validator.WithAllowedClockSkew(d)` | `time.Duration` | No | Clock skew tolerance for token expiration. Default: 0. |
+
+---
+
+## Middleware Options
+
+Create middleware with `jwtmiddleware.New()` using functional options:
+
+```go
+middleware, err := jwtmiddleware.New(
+	jwtmiddleware.WithValidator(jwtValidator),
+)
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `jwtmiddleware.WithValidator(v)` | `core.Validator` | JWT validator instance (required) |
+| `jwtmiddleware.WithErrorHandler(fn)` | `func(http.ResponseWriter, *http.Request, error)` | Custom error response handler |
+| `jwtmiddleware.WithCredentialsOptional(b)` | `bool` | Allow requests without tokens (default: false) |
+| `jwtmiddleware.WithTokenExtractor(fn)` | `jwtmiddleware.TokenExtractor` | Custom token extraction from request |
+| `jwtmiddleware.WithExclusionUrls(urls)` | `[]string` | URL paths to skip JWT validation |
+| `jwtmiddleware.WithLogger(l)` | `*slog.Logger` | Structured logger for validation events |
+| `jwtmiddleware.WithDPoPMode(mode)` | `jwtmiddleware.DPoPMode` | DPoP proof-of-possession mode |
+| `jwtmiddleware.WithStandardProxy()` | - | Trust X-Forwarded-* headers for DPoP behind reverse proxies |
+
+---
+
+## JWKS Provider Options
+
+Create a caching JWKS provider with `jwks.NewCachingProvider()`:
+
+```go
+provider, err := jwks.NewCachingProvider(
+	jwks.WithIssuerURL(issuerURL),
+)
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `jwks.WithIssuerURL(url)` | `*url.URL` | Auth0 issuer URL. Fetches JWKS from `{url}.well-known/jwks.json`. |
+
+---
+
+## Claims Reference
+
+### Registered Claims
+
+Access via `claims.RegisteredClaims`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `Subject` | `string` | User ID (`sub` claim) |
+| `Issuer` | `string` | Token issuer (`iss` claim) |
+| `Audience` | `[]string` | Audience list (`aud` claim) |
+| `Expiry` | `*time.Time` | Expiration time (`exp` claim) |
+| `IssuedAt` | `*time.Time` | Issue time (`iat` claim) |
+
+### Custom Claims
+
+Access via `claims.CustomClaims.(*YourType)`:
+
+```go
+claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
+if err != nil {
+	// handle error
+}
+
+// Registered claims
+userId := claims.RegisteredClaims.Subject
+
+// Custom claims (requires CustomClaims registered with validator)
+customClaims := claims.CustomClaims.(*CustomClaims)
+scope := customClaims.Scope
+permissions := customClaims.Permissions
+```
+
+---
+
+## DPoP Modes
+
+| Mode | Value | Behavior |
+|------|-------|----------|
+| Disabled | `jwtmiddleware.DPoPDisabled` | Standard JWT Bearer only (default) |
+| Allowed | `jwtmiddleware.DPoPAllowed` | Accept both DPoP-bound and standard Bearer tokens |
+| Required | `jwtmiddleware.DPoPRequired` | Only accept DPoP-bound tokens; reject standard Bearer |
+
+---
+
+## Token Extractors
+
+| Extractor | Usage | Description |
+|-----------|-------|-------------|
+| Default (Header) | Automatic | Extracts from `Authorization: Bearer <token>` |
+| Cookie | `jwtmiddleware.CookieTokenExtractor("name")` | Extracts from named cookie |
+| Parameter | `jwtmiddleware.ParameterTokenExtractor("param")` | Extracts from URL query parameter |
+| Multi | `jwtmiddleware.MultiTokenExtractor(e1, e2, ...)` | Tries multiple extractors in order |
+
+---
+
+## Supported Algorithms
+
+| Family | Algorithms |
+|--------|-----------|
+| HMAC | `HS256`, `HS384`, `HS512` |
+| RSA | `RS256`, `RS384`, `RS512` |
+| RSA-PSS | `PS256`, `PS384`, `PS512` |
+| ECDSA | `ES256`, `ES384`, `ES512`, `ES256K` |
+| EdDSA | `EdDSA` |
+
+Auth0 uses **RS256** by default. Always use `validator.RS256` for Auth0 JWKS validation.
+
+---
+
+## Complete Code Example
+
+```go
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"log"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+
+	jwtmiddleware "github.com/auth0/go-jwt-middleware/v3"
+	"github.com/auth0/go-jwt-middleware/v3/jwks"
+	"github.com/auth0/go-jwt-middleware/v3/validator"
+	"github.com/joho/godotenv"
+)
+
+type CustomClaims struct {
+	Scope       string   `json:"scope"`
+	Permissions []string `json:"permissions"`
+}
+
+func (c CustomClaims) Validate(ctx context.Context) error {
+	return nil
+}
+
+func (c CustomClaims) HasScope(expectedScope string) bool {
+	for _, scope := range strings.Split(c.Scope, " ") {
+		if scope == expectedScope {
+			return true
+		}
+	}
+	return false
+}
+
+func main() {
+	if err := godotenv.Load(); err != nil {
+		log.Fatalf("Error loading .env file: %v", err)
+	}
+
+	issuerURL, err := url.Parse("https://" + os.Getenv("AUTH0_DOMAIN") + "/")
+	if err != nil {
+		log.Fatalf("Failed to parse issuer URL: %v", err)
+	}
+
+	provider, err := jwks.NewCachingProvider(
+		jwks.WithIssuerURL(issuerURL),
+	)
+	if err != nil {
+		log.Fatalf("Failed to set up JWKS provider: %v", err)
+	}
+
+	jwtValidator, err := validator.New(
+		validator.WithKeyFunc(provider.KeyFunc),
+		validator.WithAlgorithm(validator.RS256),
+		validator.WithIssuer(issuerURL.String()),
+		validator.WithAudience(os.Getenv("AUTH0_AUDIENCE")),
+		validator.WithCustomClaims(func() validator.CustomClaims {
+			return &CustomClaims{}
+		}),
+	)
+	if err != nil {
+		log.Fatalf("Failed to set up JWT validator: %v", err)
+	}
+
+	middleware, err := jwtmiddleware.New(
+		jwtmiddleware.WithValidator(jwtValidator),
+		jwtmiddleware.WithErrorHandler(func(w http.ResponseWriter, r *http.Request, err error) {
+			w.Header().Set("Content-Type", "application/json")
+			if errors.Is(err, jwtmiddleware.ErrJWTMissing) {
+				w.WriteHeader(http.StatusUnauthorized)
+				json.NewEncoder(w).Encode(map[string]string{"message": "Missing authorization token."})
+				return
+			}
+			w.WriteHeader(http.StatusUnauthorized)
+			json.NewEncoder(w).Encode(map[string]string{"message": "Invalid token."})
+		}),
+		jwtmiddleware.WithLogger(slog.Default()),
+	)
+	if err != nil {
+		log.Fatalf("Failed to set up JWT middleware: %v", err)
+	}
+
+	mux := http.NewServeMux()
+
+	mux.HandleFunc("/api/public", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]string{"message": "Hello from a public endpoint!"})
+	})
+
+	mux.Handle("/api/private", middleware.CheckJWT(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		claims, _ := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]string{
+			"message": "Hello from a private endpoint!",
+			"userId":  claims.RegisteredClaims.Subject,
+		})
+	})))
+
+	mux.Handle("/api/private-scoped", middleware.CheckJWT(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		claims, _ := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
+		customClaims := claims.CustomClaims.(*CustomClaims)
+		if !customClaims.HasScope("read:messages") {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusForbidden)
+			json.NewEncoder(w).Encode(map[string]string{"message": "Insufficient scope."})
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]string{"message": "Hello from a scoped endpoint!"})
+	})))
+
+	server := &http.Server{
+		Addr:    ":8080",
+		Handler: mux,
+	}
+
+	log.Println("Server listening on :8080")
+	log.Fatal(server.ListenAndServe())
+}
+```
+
+---
+
+## Testing Checklist
+
+| Test | Command | Expected |
+|------|---------|----------|
+| Public endpoint | `curl http://localhost:8080/api/public` | 200 with message |
+| Private without token | `curl http://localhost:8080/api/private` | 401 |
+| Private with token | `curl -H "Authorization: Bearer TOKEN" http://localhost:8080/api/private` | 200 with userId |
+| Scoped with token | `curl -H "Authorization: Bearer TOKEN" http://localhost:8080/api/private-scoped` | 200 (with scope) or 403 |
+| Invalid token | `curl -H "Authorization: Bearer invalid" http://localhost:8080/api/private` | 401 |
+
+---
+
+## Common Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| 401 on all requests | Wrong issuer URL | Ensure trailing slash: `https://domain/` |
+| 401 invalid_token | Audience mismatch | `AUTH0_AUDIENCE` must exactly match API identifier |
+| panic: nil pointer | Missing error check | Always check `err` from `New()` functions |
+| JWKS fetch fails | Network/firewall | Check connectivity to `https://domain/.well-known/jwks.json` |
+| Claims type assertion fails | Wrong type parameter | Use `GetClaims[*validator.ValidatedClaims]`, not `ValidatedClaims` |
+| v2 code doesn't compile | Breaking API changes | See [Migration Guide](https://github.com/auth0/go-jwt-middleware/blob/master/MIGRATION_GUIDE.md) |
+
+---
+
+## Security Considerations
+
+- **Never hardcode Domain or Audience** - Use `.env` for development, environment variables for production
+- **Use HTTPS in production** - Auth0 requires HTTPS for secure token validation
+- **Use minimal scopes** - Only request and enforce scopes your API actually needs
+- **Keep packages updated** - Run `go get -u github.com/auth0/go-jwt-middleware/v3` for security patches
+- **Set appropriate clock skew** - Use `validator.WithAllowedClockSkew()` in distributed environments
+- **Validate custom claims** - Implement non-trivial `Validate()` logic when business rules require it
+- **Use DPoP for high-security APIs** - Prevents token theft and replay attacks
+
+---
+
+# Go JWT Middleware Integration Patterns
+
+Advanced integration patterns for Go API applications using go-jwt-middleware v3.
+
+---
+
+## Permission-Based Authorization
+
+### Define Custom Claims
+
+```go
+type CustomClaims struct {
+	Scope       string   `json:"scope"`
+	Permissions []string `json:"permissions"`
+}
+
+func (c CustomClaims) Validate(ctx context.Context) error {
+	return nil
+}
+
+func (c CustomClaims) HasScope(expectedScope string) bool {
+	for _, scope := range strings.Split(c.Scope, " ") {
+		if scope == expectedScope {
+			return true
+		}
+	}
+	return false
+}
+
+func (c CustomClaims) HasPermission(expectedPermission string) bool {
+	for _, p := range c.Permissions {
+		if p == expectedPermission {
+			return true
+		}
+	}
+	return false
+}
+```
+
+### Register Custom Claims with Validator
+
+```go
+jwtValidator, err := validator.New(
+	validator.WithKeyFunc(provider.KeyFunc),
+	validator.WithAlgorithm(validator.RS256),
+	validator.WithIssuer(issuerURL.String()),
+	validator.WithAudience(os.Getenv("AUTH0_AUDIENCE")),
+	validator.WithCustomClaims(func() validator.CustomClaims {
+		return &CustomClaims{}
+	}),
+)
+```
+
+### Check Permissions in Handlers
+
+```go
+func privateScopedHandler(w http.ResponseWriter, r *http.Request) {
+	claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
+	if err != nil {
+		w.Header().Set("Content-Type", "application/json")
+		http.Error(w, `{"message":"Failed to get token claims."}`, http.StatusInternalServerError)
+		return
+	}
+
+	customClaims := claims.CustomClaims.(*CustomClaims)
+	if !customClaims.HasScope("read:messages") {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusForbidden)
+		json.NewEncoder(w).Encode(map[string]string{"message": "Insufficient scope."})
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{"message": "Hello from a scoped endpoint!"})
+}
+```
+
+### Define Permissions in Auth0
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Select your API
+3. Click the **Permissions** tab
+4. Add permissions matching your scope names (e.g., `read:messages`, `write:messages`)
+
+### Request Tokens with Scopes
+
+Clients must request tokens that include the required scopes:
+
+```bash
+curl -X POST https://your-tenant.auth0.com/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_id": "YOUR_CLIENT_ID",
+    "client_secret": "YOUR_CLIENT_SECRET",
+    "audience": "https://my-api.example.com",
+    "grant_type": "client_credentials",
+    "scope": "read:messages write:messages"
+  }'
+```
+
+---
+
+## CORS Configuration
+
+For APIs called from browser-based SPAs, configure CORS before the JWT middleware. CORS must handle preflight OPTIONS requests before auth:
+
+```go
+func corsMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Access-Control-Allow-Origin", "http://localhost:3000")
+		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
+		w.Header().Set("Access-Control-Allow-Headers", "Authorization, Content-Type")
+		w.Header().Set("Access-Control-Max-Age", "86400")
+
+		if r.Method == "OPTIONS" {
+			w.WriteHeader(http.StatusNoContent)
+			return
+		}
+
+		next.ServeHTTP(w, r)
+	})
+}
+```
+
+Apply CORS before JWT middleware:
+
+```go
+mux := http.NewServeMux()
+mux.HandleFunc("/api/public", publicHandler)
+mux.Handle("/api/private", middleware.CheckJWT(http.HandlerFunc(privateHandler)))
+
+// CORS wraps the entire mux — must be outermost
+handler := corsMiddleware(mux)
+log.Fatal(http.ListenAndServe(":8080", handler))
+```
+
+For production, replace the hardcoded origin with your SPA domain. Use the `rs/cors` package for more advanced CORS configuration:
+
+```bash
+go get github.com/rs/cors
+```
+
+```go
+import "github.com/rs/cors"
+
+c := cors.New(cors.Options{
+	AllowedOrigins:   []string{"https://your-spa.example.com"},
+	AllowedMethods:   []string{"GET", "POST", "PUT", "DELETE"},
+	AllowedHeaders:   []string{"Authorization", "Content-Type"},
+	AllowCredentials: true,
+})
+
+handler := c.Handler(mux)
+```
+
+---
+
+## DPoP Support
+
+DPoP (Demonstrating Proof of Possession, RFC 9449) binds tokens to a specific client key pair, preventing token theft.
+
+### Enable DPoP
+
+```go
+middleware, err := jwtmiddleware.New(
+	jwtmiddleware.WithValidator(jwtValidator),
+	jwtmiddleware.WithDPoPMode(jwtmiddleware.DPoPAllowed),
+)
+```
+
+### DPoP Required Mode
+
+To reject standard Bearer tokens and accept only DPoP-bound tokens:
+
+```go
+middleware, err := jwtmiddleware.New(
+	jwtmiddleware.WithValidator(jwtValidator),
+	jwtmiddleware.WithDPoPMode(jwtmiddleware.DPoPRequired),
+)
+```
+
+### DPoP Modes
+
+| Mode | Behavior |
+|------|----------|
+| `jwtmiddleware.DPoPDisabled` | Standard JWT Bearer only, DPoP disabled |
+| `jwtmiddleware.DPoPAllowed` | Accept both DPoP-bound and standard Bearer tokens |
+| `jwtmiddleware.DPoPRequired` | Only accept DPoP-bound tokens; reject standard Bearer |
+
+### Trusted Proxy Configuration
+
+For APIs behind a reverse proxy (e.g., nginx, AWS ALB):
+
+```go
+middleware, err := jwtmiddleware.New(
+	jwtmiddleware.WithValidator(jwtValidator),
+	jwtmiddleware.WithDPoPMode(jwtmiddleware.DPoPRequired),
+	jwtmiddleware.WithStandardProxy(),
+)
+```
+
+---
+
+## Accessing Claims
+
+### Type-Safe Claims Retrieval (v3)
+
+```go
+claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
+if err != nil {
+	http.Error(w, "Failed to get claims", http.StatusInternalServerError)
+	return
+}
+
+userId := claims.RegisteredClaims.Subject
+issuer := claims.RegisteredClaims.Issuer
+customClaims := claims.CustomClaims.(*CustomClaims)
+```
+
+### Common JWT Claims
+
+| Claim | Go Access Pattern | Description |
+|-------|-------------------|-------------|
+| `sub` | `claims.RegisteredClaims.Subject` | User ID (subject) |
+| `iss` | `claims.RegisteredClaims.Issuer` | Token issuer (your Auth0 tenant URL) |
+| `aud` | `claims.RegisteredClaims.Audience` | Audience (your API identifier) |
+| `exp` | `claims.RegisteredClaims.Expiry` | Expiration timestamp |
+| `iat` | `claims.RegisteredClaims.IssuedAt` | Issued-at timestamp |
+| `scope` | `customClaims.Scope` | Space-separated list of granted scopes |
+| `permissions` | `customClaims.Permissions` | Permission strings (RBAC) |
+
+Custom claims added via Auth0 Actions use namespaced keys. Add them to your `CustomClaims` struct:
+
+```go
+type CustomClaims struct {
+	Scope       string   `json:"scope"`
+	Permissions []string `json:"permissions"`
+	Email       string   `json:"https://example.com/email"`
+}
+```
+
+---
+
+## Error Handling
+
+### Custom Error Handler
+
+```go
+func customErrorHandler(w http.ResponseWriter, r *http.Request, err error) {
+	w.Header().Set("Content-Type", "application/json")
+
+	if errors.Is(err, jwtmiddleware.ErrJWTMissing) {
+		w.WriteHeader(http.StatusUnauthorized)
+		json.NewEncoder(w).Encode(map[string]string{
+			"error":   "missing_token",
+			"message": "Authorization header with Bearer token is required.",
+		})
+		return
+	}
+
+	w.WriteHeader(http.StatusUnauthorized)
+	json.NewEncoder(w).Encode(map[string]string{
+		"error":   "invalid_token",
+		"message": "The provided token is invalid.",
+	})
+}
+
+middleware, err := jwtmiddleware.New(
+	jwtmiddleware.WithValidator(jwtValidator),
+	jwtmiddleware.WithErrorHandler(customErrorHandler),
+)
+```
+
+### Standard Error Responses
+
+| Status | Cause | Fix |
+|--------|-------|-----|
+| 401 | Missing or invalid token | Include valid `Authorization: Bearer <token>` header |
+| 401 | Expired token | Request a fresh access token |
+| 401 | Wrong audience | Token's `aud` claim must match your API Identifier |
+| 403 | Insufficient scope | Token must include required scopes/permissions |
+
+---
+
+## Mixed Public and Protected Endpoints
+
+```go
+mux := http.NewServeMux()
+
+// Public - no auth needed
+mux.HandleFunc("/api/public", publicHandler)
+
+// Protected - requires valid JWT
+mux.Handle("/api/private", middleware.CheckJWT(http.HandlerFunc(privateHandler)))
+
+// Protected with scope - requires JWT + specific permission
+mux.Handle("/api/private-scoped", middleware.CheckJWT(http.HandlerFunc(privateScopedHandler)))
+```
+
+---
+
+## Optional Credentials Mode
+
+Allow endpoints to work for both authenticated and unauthenticated users:
+
+```go
+middleware, err := jwtmiddleware.New(
+	jwtmiddleware.WithValidator(jwtValidator),
+	jwtmiddleware.WithCredentialsOptional(true),
+)
+```
+
+In your handler, check if claims exist:
+
+```go
+func handler(w http.ResponseWriter, r *http.Request) {
+	if jwtmiddleware.HasClaims(r.Context()) {
+		claims, _ := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
+		// Authenticated user
+	} else {
+		// Anonymous user
+	}
+}
+```
+
+---
+
+## URL Exclusions
+
+Skip JWT validation for specific paths:
+
+```go
+middleware, err := jwtmiddleware.New(
+	jwtmiddleware.WithValidator(jwtValidator),
+	jwtmiddleware.WithExclusionUrls([]string{"/health", "/metrics", "/api/public"}),
+)
+```
+
+---
+
+## Framework Adapters
+
+### Gin
+
+```go
+import "github.com/gin-gonic/gin"
+
+r := gin.Default()
+
+r.GET("/api/public", func(c *gin.Context) {
+	c.JSON(200, gin.H{"message": "public"})
+})
+
+r.GET("/api/private", gin.WrapH(middleware.CheckJWT(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+	claims, _ := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{"userId": claims.RegisteredClaims.Subject})
+}))))
+```
+
+### Echo
+
+```go
+import "github.com/labstack/echo/v4"
+
+e := echo.New()
+
+e.GET("/api/public", func(c echo.Context) error {
+	return c.JSON(200, map[string]string{"message": "public"})
+})
+
+e.GET("/api/private", echo.WrapHandler(middleware.CheckJWT(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+	claims, _ := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{"userId": claims.RegisteredClaims.Subject})
+}))))
+```
+
+---
+
+## Structured Logging
+
+```go
+import "log/slog"
+
+middleware, err := jwtmiddleware.New(
+	jwtmiddleware.WithValidator(jwtValidator),
+	jwtmiddleware.WithLogger(slog.Default()),
+)
+```
+
+---
+
+## Custom Token Extraction
+
+### From Cookie
+
+```go
+middleware, err := jwtmiddleware.New(
+	jwtmiddleware.WithValidator(jwtValidator),
+	jwtmiddleware.WithTokenExtractor(jwtmiddleware.CookieTokenExtractor("jwt")),
+)
+```
+
+### From Query Parameter
+
+```go
+middleware, err := jwtmiddleware.New(
+	jwtmiddleware.WithValidator(jwtValidator),
+	jwtmiddleware.WithTokenExtractor(jwtmiddleware.ParameterTokenExtractor("token")),
+)
+```
+
+### Multiple Sources
+
+```go
+middleware, err := jwtmiddleware.New(
+	jwtmiddleware.WithValidator(jwtValidator),
+	jwtmiddleware.WithTokenExtractor(jwtmiddleware.MultiTokenExtractor(
+		jwtmiddleware.AuthHeaderTokenExtractor,
+		jwtmiddleware.CookieTokenExtractor("jwt"),
+	)),
+)
+```
+
+---
+
+## Testing
+
+### Unit Testing with httptest
+
+```go
+func TestPublicEndpoint_Returns200(t *testing.T) {
+	mux := setupRouter() // your function that sets up routes
+	req := httptest.NewRequest("GET", "/api/public", nil)
+	w := httptest.NewRecorder()
+	mux.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200, got %d", w.Code)
+	}
+}
+
+func TestPrivateEndpoint_WithoutToken_Returns401(t *testing.T) {
+	mux := setupRouter()
+	req := httptest.NewRequest("GET", "/api/private", nil)
+	w := httptest.NewRecorder()
+	mux.ServeHTTP(w, req)
+
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("expected 401, got %d", w.Code)
+	}
+}
+```
+
+### Testing with a Real Token
+
+```bash
+# Get a token via Auth0 CLI (uses client credentials for M2M apps)
+TOKEN=$(auth0 test token <M2M_CLIENT_ID> --audience https://my-api.example.com --scopes "read:messages" --json | jq -r '.access_token')
+
+# Test private endpoint
+curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/private
+```
+
+---
+
+---
+
+# Go JWT Middleware Setup Guide
+
+Setup instructions for Go API applications.
+
+---
+
+## Auth0 Configuration
+
+> **Agent instruction:**
+>
+> **Credential check (always first):**
+> If the user's prompt already provides Auth0 credentials (domain and audience), use them directly. Write the `.env` file and proceed to integration. Do NOT call `AskUserQuestion` to re-confirm.
+>
+> **If credentials are NOT in the prompt:**
+>
+> Use `AskUserQuestion` to ask the user:
+> "How would you like to configure Auth0 for this project?"
+> - Option A: "Automatic setup (recommended)" — uses the Auth0 CLI to create the API resource
+> - Option B: "Manual setup" — provide Auth0 credentials manually
+>
+> **If Automatic Setup:**
+>
+> **Important:** Do NOT run `auth0 login` from the agent — it is interactive and will hang. If the user needs to log in, ask them to run it in their terminal.
+>
+> ---
+> **INITIAL SETUP (steps 1–6) — always run during automated setup:**
+>
+> 1. **Check Auth0 CLI**: Run `command -v auth0`. If missing, ask user to install (`brew install auth0/auth0-cli/auth0`) or switch to manual setup.
+> 2. **Check Auth0 login**: Run `auth0 tenants list --csv --no-input 2>&1`. If it fails or returns empty:
+>    - Tell the user: _"Please run `auth0 login` in your terminal and let me know when done."_
+>    - Wait for the user to confirm, then re-run the check to verify.
+> 3. **Confirm active tenant**: Parse the output to identify the active tenant domain. Tell the user: _"Your active Auth0 tenant is: `<domain>`. Is this the correct tenant?"_
+>    - If yes, proceed.
+>    - If no, ask the user to run `auth0 tenants use <tenant-domain>` in their terminal, then re-run step 2 to confirm the new active tenant.
+> 4. **Create the Auth0 API resource**: Ask for the API name, identifier, and scopes (see SKILL.md checkpoints 4–5 for exact prompts).
+>    **Before creating**, check if an API with the same identifier already exists:
+>    ```bash
+>    auth0 apis list --json 2>&1 | grep -c "<INTENDED_IDENTIFIER>"
+>    ```
+>    If it already exists, ask the user: _"An API with identifier `<ID>` already exists. Would you like to reuse it, or should I create a new one with a different identifier?"_
+>    If creating new:
+>    ```bash
+>    auth0 apis create \
+>      --name "<API_NAME>" \
+>      --identifier <API_IDENTIFIER> \
+>      --scopes "<COMMA_SEPARATED_SCOPES>" \
+>      --no-input --json
+>    ```
+>    If creation fails with a conflict/duplicate error, inform the user and ask how to proceed.
+>    Parse the JSON output to extract the `identifier` (audience) value.
+> 5. **Write `.env` file**:
+>    - **Never read the contents of an existing `.env` file** — it may contain sensitive secrets that should not be exposed in the LLM context.
+>    - If a `.env` file already exists, ask the user for confirmation using `AskUserQuestion`: _"A `.env` file already exists in this project. Can I add the Auth0 configuration to it?"_
+>    - If no `.env` exists, create it with `AUTH0_DOMAIN` (from the active tenant in step 3) and `AUTH0_AUDIENCE` (from step 4).
+> 6. **Add `.env` to `.gitignore`** if not already present.
+>
+> After step 6, proceed to code integration (SKILL.md Step 4).
+>
+> ---
+> **TESTING SETUP (steps 7–8) — only run when user agrees to test (SKILL.md Step 6):**
+>
+> 7. **M2M application setup**: Use `AskUserQuestion` to ask:
+>    _"Would you like me to create a new Machine-to-Machine application to test your API, or do you have an existing application you'd like to authorize?"_
+>    - **Option A: "Create a new M2M app"** — Create a new M2M application and authorize it against the API:
+>      ```bash
+>      auth0 apps create \
+>        --name "<PROJECT_NAME> (Test App)" \
+>        --type m2m \
+>        --no-input --json
+>      ```
+>      Parse the JSON output to extract the `client_id`. **Do NOT use `--reveal-secrets`** — instead, rather than handling client secrets in agent context, tell the user: _"Your M2M app has been created. To get the client secret, run `auth0 apps show <CLIENT_ID> --reveal-secrets` in your terminal."_
+>      Then create a client grant to authorize the app for the API:
+>      ```bash
+>      auth0 api post "client-grants" --data '{
+>        "client_id": "<CLIENT_ID>",
+>        "audience": "<API_IDENTIFIER>",
+>        "scope": ["<SCOPES>"]
+>      }'
+>      ```
+>    - **Option B: "Use an existing application"** — Ask the user for the `client_id` of their existing application. Then create a client grant to authorize it for this API:
+>      ```bash
+>      auth0 api post "client-grants" --data '{
+>        "client_id": "<CLIENT_ID>",
+>        "audience": "<API_IDENTIFIER>",
+>        "scope": ["<SCOPES>"]
+>      }'
+>      ```
+>      If the grant already exists (409 conflict), that's fine — the app is already authorized.
+>
+> 8. **Test endpoints (TOKEN ISOLATION — CRITICAL)**:
+>    The agent MUST NEVER directly see or display access token values.
+>
+>    **If the user explicitly asks to test**, use the secure single-command chain pattern.
+>    The token is captured into a shell variable via `$(...)`, never printed, and dies when the command ends:
+>    ```bash
+>    TEST_TOKEN=$(auth0 test token <CLIENT_ID> --audience <API_IDENTIFIER> --scopes <SCOPE1,SCOPE2> 2>/dev/null | grep -o 'ey[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*') && \
+>    [ -n "$TEST_TOKEN" ] && echo "Token acquired (${#TEST_TOKEN} chars)" && \
+>    curl -s http://localhost:8080/<ENDPOINT> -H "Authorization: Bearer $TEST_TOKEN"
+>    ```
+>    Security guarantees:
+>    - Token goes into `$TEST_TOKEN` — stdout is consumed, not displayed
+>    - Only the token LENGTH is echoed (e.g., "Token acquired (834 chars)")
+>    - Shell variable dies at end of command chain — no persistence between calls
+>    - Agent sees only: confirmation line + API response JSON
+>    - No file written, no env exported
+>
+>    Rules:
+>    - ONLY use when user explicitly asks to test
+>    - Always chain token capture + all curls in a SINGLE `&&` command
+>    - NEVER echo/print/log the raw token value
+>    - NEVER split into multiple Bash calls (variable won't persist)
+>    - **Client ID is REQUIRED** — `auth0 test token` needs the M2M app's `client_id` as the first argument. If the M2M setup step (step 7) has not been completed, do NOT attempt to run this. Complete M2M setup first to obtain the Client ID.
+>
+>    **If the user does NOT ask to test**, provide the manual commands:
+>    ```bash
+>    auth0 test token <CLIENT_ID> \
+>      --audience <API_IDENTIFIER> \
+>      --scopes <SCOPE1,SCOPE2>
+>    ```
+>    Then:
+>    ```bash
+>    curl -H "Authorization: Bearer <PASTE_TOKEN_HERE>" http://localhost:8080/<ENDPOINT>
+>    ```
+>
+>    The agent MAY always verify unauthenticated behavior:
+>    - Public/health endpoints return 200
+>    - Protected endpoints return 401 without a token
+>
+> ---
+> **If Manual Setup:**
+>
+> Ask the user for:
+> - Auth0 Domain (e.g., `your-tenant.auth0.com`)
+> - API Audience (e.g., `https://my-api.example.com`)
+>
+> Write the `.env` file with provided values.
+
+## Quick Setup (Automated)
+
+Below uses the Auth0 CLI to create an Auth0 API resource and retrieve your credentials.
+
+### Step 1: Install Auth0 CLI and create API resource
+
+```bash
+# Install Auth0 CLI (macOS)
+brew install auth0/auth0-cli/auth0
+
+# Login (opens browser for authentication)
+auth0 login
+
+# Create an Auth0 API resource
+auth0 apis create \
+  --name "My Go API" \
+  --identifier https://my-api.example.com \
+  --json
+```
+
+Note the `identifier` value - this is your Audience.
+
+### Step 1b: Create or authorize an application for token generation
+
+To test your API, you need an application authorized to request tokens for this API:
+
+```bash
+# Create a Machine-to-Machine application
+auth0 apps create \
+  --name "My Go API (Test App)" \
+  --type m2m \
+  --no-input --json
+```
+
+Note the `client_id` from the JSON output. Then authorize it for your API by creating a client grant:
+
+```bash
+auth0 api post "client-grants" --data '{
+  "client_id": "YOUR_M2M_CLIENT_ID",
+  "audience": "https://my-api.example.com",
+  "scope": ["read:messages"]
+}'
+```
+
+To retrieve the client secret for manual token requests, run in your terminal:
+```bash
+auth0 apps show YOUR_M2M_CLIENT_ID --reveal-secrets
+```
+
+If you already have an application you'd like to use, run the same `auth0 api post "client-grants"` command with your existing app's `client_id` to authorize it for this API.
+
+### Step 2: Add configuration
+
+Once you have your Domain and Audience, create a `.env` file in your project root:
+
+```env
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_AUDIENCE=https://my-api.example.com
+```
+
+Replace `your-tenant.auth0.com` with your Auth0 tenant domain and `https://my-api.example.com` with the identifier you used when creating the API resource.
+
+---
+
+## Manual Setup
+
+### Install Dependencies
+
+```bash
+go get github.com/auth0/go-jwt-middleware/v3
+go get github.com/joho/godotenv
+```
+
+### Create Auth0 API Resource
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Click **Create API**
+3. Set a **Name** and an **Identifier** (e.g., `https://my-api.example.com`)
+4. Note the Identifier - this is your `Audience`
+
+### Configure .env
+
+```env
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_AUDIENCE=https://my-api.example.com
+```
+
+**Important:** Domain format is `your-tenant.auth0.com` - do NOT include `https://`.
+
+### Get Auth0 Configuration
+
+- **Domain:** Auth0 Dashboard → Settings → Domain (or `auth0 tenants list`)
+- **Audience:** The identifier you set when creating the API resource
+
+---
+
+## Post-Setup Steps
+
+> **Agent instruction:** After setup, verify:
+> 1. `.env` file exists with `AUTH0_DOMAIN` and `AUTH0_AUDIENCE`
+> 2. `go.mod` includes `github.com/auth0/go-jwt-middleware/v3` and `github.com/joho/godotenv`
+> 3. Run `go build ./...` to verify compilation
+
+---
+
+## Secret Management
+
+For Go BACKEND_API projects:
+- **Development:** `.env` file loaded via `godotenv.Load()`
+- **Production:** Environment variables (`AUTH0_DOMAIN`, `AUTH0_AUDIENCE`)
+- **No client secret needed** - JWT validation uses JWKS public keys from Auth0's well-known endpoint
+
+Add `.env` to `.gitignore` to prevent committing credentials:
+
+```bash
+echo ".env" >> .gitignore
+```
+
+---
+
+## Getting a Test Token
+
+To test your protected API, you need an access token issued for your API's audience. You can use an existing authorized application or create a new Machine-to-Machine (M2M) app.
+
+### Create an M2M Application (if you don't have one)
+
+```bash
+# Create a new M2M application
+auth0 apps create \
+  --name "My Go API (Test App)" \
+  --type m2m \
+  --no-input --json
+```
+
+Note the `client_id` from the output. To get the client secret, run `auth0 apps show <CLIENT_ID> --reveal-secrets` in your terminal. Then authorize the app for your API:
+
+```bash
+auth0 api post "client-grants" --data '{
+  "client_id": "YOUR_M2M_CLIENT_ID",
+  "audience": "https://my-api.example.com",
+  "scope": ["read:messages"]
+}'
+```
+
+### Via Auth0 CLI
+
+```bash
+auth0 test token <M2M_CLIENT_ID> \
+  --audience https://my-api.example.com \
+  --scopes read:messages,write:messages
+```
+
+For M2M apps, this uses the client credentials grant automatically and returns the access token.
+
+### Via curl (Client Credentials Flow)
+
+```bash
+curl -s -X POST https://your-tenant.auth0.com/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_id": "YOUR_M2M_CLIENT_ID",
+    "client_secret": "YOUR_M2M_CLIENT_SECRET",
+    "audience": "https://my-api.example.com",
+    "grant_type": "client_credentials"
+  }'
+```
+
+The response JSON contains an `access_token` field — use it in the `Authorization: Bearer <token>` header.
+
+### Via Auth0 Dashboard
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Select your API
+3. Click the **Test** tab
+4. Click **Copy Token** to get a test access token
+
+---
+
+## Verification
+
+```bash
+# Start server
+go run main.go
+
+# Test public endpoint (should return 200)
+curl http://localhost:8080/api/public
+
+# Test protected endpoint without token (should return 401)
+curl http://localhost:8080/api/private
+
+# Test protected endpoint with token (should return 200)
+curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
+  http://localhost:8080/api/private
+```
+
+---
+
+## Troubleshooting
+
+**401 Unauthorized - "invalid_token":** Verify that the `AUTH0_AUDIENCE` in .env exactly matches your API Identifier in Auth0 Dashboard.
+
+**401 Unauthorized - "invalid_issuer":** Ensure `AUTH0_DOMAIN` does not include `https://` - use `your-tenant.auth0.com` format only. Also ensure the issuer URL has a trailing slash (`https://domain/`).
+
+**JWKS fetch fails:** Check network connectivity to `https://your-tenant.auth0.com/.well-known/jwks.json`. Verify the domain is correct.
+
+**Token expired:** Test tokens from the Dashboard are short-lived. Request a fresh token.
+
+**panic: nil pointer:** Always check the `err` return value from `jwtmiddleware.New()`, `validator.New()`, and `jwks.NewCachingProvider()`.
+
+---
diff --git a/main/.mintlify/skills/auth0/references/framework-ionic-angular/index.md b/main/.mintlify/skills/auth0/references/framework-ionic-angular/index.md
new file mode 100644
index 0000000000..3512cab6c1
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-ionic-angular/index.md
@@ -0,0 +1,1361 @@
+
+# Auth0 Ionic Angular (Capacitor) Integration
+
+Add authentication to an Ionic Angular application using the `@auth0/auth0-angular` SDK with Capacitor plugins for native iOS and Android. This skill covers login, logout, user profile display, and secure token management using the system browser (SFSafariViewController on iOS, Chrome Custom Tabs on Android) via Capacitor's Browser plugin.
+
+## Critical rules
+
+- **SECURITY — NEVER display credentials.** After obtaining Auth0 credentials (domain, client ID) from the CLI or a user-provided env file, write them directly to the config file silently. Do not print, echo, or display them in text output; instead, confirm the config file was written and tell the user where to find it.
+
+## Prerequisites
+
+- Node.js 20+ and npm 10+
+- Ionic CLI (`npm install -g @ionic/cli`)
+- Capacitor 5+ configured in the project
+- Auth0 CLI (for automatic setup): `brew install auth0/auth0-cli/auth0`
+- An Auth0 account (free tier works)
+
+## When NOT to Use
+
+| Use Case | Use Instead |
+|----------|------------------|
+| Ionic **React** app with Capacitor | the Auth0 integration workflow for Ionic React |
+| Ionic **Vue** app with Capacitor | the Auth0 integration workflow for Ionic Vue |
+| Angular SPA (browser-only, no Capacitor) | the Auth0 integration workflow for Angular (or React) |
+| React Native (no Ionic) | the Auth0 integration workflow for React Native |
+| Expo (React Native) | the Auth0 integration workflow for Expo |
+| Native iOS (Swift) | the Auth0 integration workflow for Swift (iOS) |
+| Native Android (Kotlin) | the Auth0 integration workflow for Android (Kotlin) |
+
+## Quick Start Workflow
+
+> **Agent instruction:** Follow these steps in order. **Always** use `AskUserQuestion` to let the developer choose between Automatic Setup and Manual Setup before proceeding — even if credentials are already provided in the prompt.
+>
+> **SECURITY — Never display credentials:** After obtaining Auth0 credentials (domain, client ID) via the CLI or from a file, NEVER print, echo, or display them in your text output. Write them directly to the config file (`src/environments/environment.ts`) silently. Do NOT produce output like "Domain: xxx" or "Client ID: yyy". Instead, confirm that the config file has been written and tell the user where to find it.
+>
+> **UI reuse:** Before creating new login/logout components, search the existing project for login/logout handlers or buttons. If found, hook Auth0 into the existing UI rather than creating duplicate components.
+
+### Step 1: Install Dependencies
+
+```bash
+npm install @auth0/auth0-angular @capacitor/browser @capacitor/app
+```
+
+### Step 2: Configure Auth0
+
+> **Agent instruction:** **Always** present the setup choice using `AskUserQuestion` — even if the user has already provided credentials:
+>
+> ```
+> AskUserQuestion:
+>   question: "How would you like to configure Auth0 for your Ionic Angular app?"
+>   options:
+>     - label: "Automatic Setup (Recommended)"
+>       description: "Uses the Auth0 CLI to create a Native application, configure callback URLs, and store credentials in your project automatically."
+>     - label: "Manual Setup"
+>       description: "You provide an .env file with your Auth0 Domain and Client ID, and the agent reads it and writes the project configuration for you."
+> ```
+>
+> Follow the chosen path in the Setup Guide section (below) which has the full step-by-step instructions for both options.
+
+**Auth0 Dashboard settings (Native application type):**
+
+| Setting | Value |
+|---------|-------|
+| Application Type | **Native** |
+| Allowed Callback URLs | `PACKAGE_ID://YOUR_DOMAIN/capacitor/PACKAGE_ID/callback` |
+| Allowed Logout URLs | `PACKAGE_ID://YOUR_DOMAIN/capacitor/PACKAGE_ID/callback` |
+| Allowed Origins | `capacitor://localhost, http://localhost` |
+
+Replace `PACKAGE_ID` with your `appId` from `capacitor.config.ts` (e.g., `com.example.myapp`) and `YOUR_DOMAIN` with your Auth0 domain.
+
+> **Note:** For Automatic Setup, these URLs are configured automatically by the Auth0 CLI. For Manual Setup, the user must configure them in the Auth0 Dashboard.
+
+> **Note:** For local web development (`ionic serve`), also add `http://localhost:8100` to Allowed Callback URLs, Allowed Logout URLs, and Allowed Web Origins.
+
+### Step 3: Configure the SDK
+
+In `src/app/app.module.ts` (NgModule) or `src/app/app.config.ts` (standalone):
+
+The `provideAuth0()` function (or `AuthModule.forRoot()`) is the Angular equivalent of `Auth0Provider` — it acts as the **provider/wrapper** that wraps the app and makes `AuthService` available everywhere. For local web development with `ionic serve`, the callback URL is `http://localhost:8100`.
+
+**Standalone (Angular 17+):**
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideAuth0 } from '@auth0/auth0-angular';
+
+// Replace with your capacitor.config.ts appId and Auth0 domain
+const appId = 'com.example.myapp';
+const domain = 'YOUR_AUTH0_DOMAIN';
+const callbackUri = `${appId}://${domain}/capacitor/${appId}/callback`;
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAuth0({
+      domain,
+      clientId: 'YOUR_AUTH0_CLIENT_ID',
+      useRefreshTokens: true,
+      useRefreshTokensFallback: false,
+      authorizationParams: {
+        redirect_uri: callbackUri,
+      },
+    }),
+  ],
+};
+```
+
+**NgModule (Angular 16 and earlier):**
+```typescript
+import { AuthModule } from '@auth0/auth0-angular';
+
+const appId = 'com.example.myapp';
+const domain = 'YOUR_AUTH0_DOMAIN';
+const callbackUri = `${appId}://${domain}/capacitor/${appId}/callback`;
+
+@NgModule({
+  imports: [
+    AuthModule.forRoot({
+      domain,
+      clientId: 'YOUR_AUTH0_CLIENT_ID',
+      useRefreshTokens: true,
+      useRefreshTokensFallback: false,
+      authorizationParams: {
+        redirect_uri: callbackUri,
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Step 4: Handle Deep Link Callbacks (AppComponent)
+
+Register the `appUrlOpen` listener at the app root so it persists across navigation:
+
+```typescript
+import { Component, NgZone, OnInit } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+import { Browser } from '@capacitor/browser';
+import { App as CapApp } from '@capacitor/app';
+import { mergeMap } from 'rxjs/operators';
+
+@Component({
+  selector: 'app-root',
+  template: `<ion-app><ion-router-outlet></ion-router-outlet></ion-app>`,
+})
+export class AppComponent implements OnInit {
+  constructor(
+    private auth: AuthService,
+    private ngZone: NgZone
+  ) {}
+
+  ngOnInit() {
+    CapApp.addListener('appUrlOpen', ({ url }) => {
+      this.ngZone.run(() => {
+        if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
+          this.auth
+            .handleRedirectCallback(url)
+            .pipe(mergeMap(() => Browser.close()))
+            .subscribe();
+        }
+      });
+    });
+  }
+}
+```
+
+### Step 5: Implement Login
+
+```typescript
+import { Component } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+import { Browser } from '@capacitor/browser';
+
+@Component({
+  selector: 'app-login',
+  template: `<ion-button (click)="login()">Log In</ion-button>`,
+})
+export class LoginPage {
+  constructor(public auth: AuthService) {}
+
+  login() {
+    this.auth
+      .loginWithRedirect({
+        async openUrl(url: string) {
+          await Browser.open({ url, windowName: '_self' });
+        },
+      })
+      .subscribe();
+  }
+}
+```
+
+### Step 6: Implement Logout
+
+```typescript
+import { Component } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+import { Browser } from '@capacitor/browser';
+
+@Component({
+  selector: 'app-logout-button',
+  template: `<ion-button (click)="logout()">Log Out</ion-button>`,
+})
+export class LogoutButtonComponent {
+  constructor(public auth: AuthService) {}
+
+  logout() {
+    this.auth
+      .logout({
+        logoutParams: {
+          returnTo: `YOUR_PACKAGE_ID://YOUR_AUTH0_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback`,
+        },
+        async openUrl(url: string) {
+          await Browser.open({ url, windowName: '_self' });
+        },
+      })
+      .subscribe();
+  }
+}
+```
+
+### Step 7: Display User Profile
+
+```typescript
+import { Component } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+import { AsyncPipe } from '@angular/common';
+
+@Component({
+  selector: 'app-profile',
+  template: `
+    <div *ngIf="auth.user$ | async as user">
+      <img [src]="user.picture" [alt]="user.name" />
+      <h2>{{ user.name }}</h2>
+      <p>{{ user.email }}</p>
+    </div>
+  `,
+})
+export class ProfileComponent {
+  constructor(public auth: AuthService) {}
+}
+```
+
+### Step 8: Build and Test
+
+> **Agent instruction:** After writing all code, verify the build succeeds:
+> ```bash
+> npm run build
+> npx cap sync
+> ```
+> If the build fails, investigate errors and fix (up to 5-6 iterations). If still failing, use `AskUserQuestion` to ask the user for help.
+
+## Detailed Documentation
+
+- **Setup Guide** (see below) — Auth0 configuration, Auth0 CLI setup, Capacitor platform setup, deep linking
+- **Integration Patterns** (see below) — Login/logout flows, token management, user profile, error handling, Capacitor lifecycle
+- **API Reference & Testing** (see below) — AuthService API, configuration options, claims reference, testing checklist
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Auth0 app type set to **SPA** instead of **Native** | Change to **Native** in Auth0 Dashboard → Application Settings |
+| Missing callback URL in Auth0 Dashboard | Add `PACKAGE_ID://{domain}/capacitor/PACKAGE_ID/callback` to Allowed Callback URLs AND Allowed Logout URLs |
+| Not wrapping `handleRedirectCallback` in `ngZone.run()` | Angular won't detect auth state changes — always wrap in `ngZone.run()` |
+| Using `window.location.href` for login redirect | Must use `Browser.open()` from `@capacitor/browser` for system browser |
+| `useRefreshTokens` not set to `true` | Required for mobile — localStorage is unreliable on native platforms |
+| `useRefreshTokensFallback` not set to `false` | Must be `false` to avoid falling back to iframe-based token refresh (unsupported on mobile) |
+| Missing `@capacitor/app` listener for deep links | The `appUrlOpen` listener is required to handle the callback from the system browser |
+| Using `loginWithPopup` on mobile | Popups don't work on native — use `loginWithRedirect` with `Browser.open` |
+| Callback URL mismatch (scheme vs package ID) | The URL scheme must match the `appId` in `capacitor.config.ts` exactly |
+
+## WebAuth Method
+
+Ionic with Capacitor uses the **Web Auth** method for authentication:
+
+1. User taps **Log In** → app calls `loginWithRedirect` with a custom `openUrl` that uses `Browser.open()`
+2. Capacitor's Browser plugin opens the Auth0 Universal Login page in the system browser (SFSafariViewController / Chrome Custom Tabs)
+3. User authenticates → Auth0 redirects to the custom URL scheme callback
+4. OS routes the deep link to your app → `appUrlOpen` event fires
+5. `handleRedirectCallback(url)` processes the auth code exchange inside `ngZone.run()`
+6. `Browser.close()` dismisses the system browser
+7. `auth.isAuthenticated$` emits `true`, and `auth.user$` emits the user profile
+
+## Related Skills
+
+- Ionic React with Capacitor → the Auth0 integration workflow for Ionic React
+- Ionic Vue with Capacitor → the Auth0 integration workflow for Ionic Vue
+- Angular SPA (browser-only) → the Auth0 integration workflow for Angular
+- Native iOS (Swift) → the Auth0 integration workflow for Swift
+- Native Android (Kotlin) → the Auth0 integration workflow for Android
+
+## Quick Reference
+
+| API | Description |
+|-----|-------------|
+| `AuthService.loginWithRedirect(options)` | Start login flow with custom `openUrl` for Capacitor |
+| `AuthService.logout(options)` | Log out with custom `openUrl` and `returnTo` |
+| `AuthService.handleRedirectCallback(url)` | Process the callback URL from the deep link |
+| `AuthService.isAuthenticated$` | Observable boolean — whether user is logged in |
+| `AuthService.user$` | Observable — current user profile (name, email, picture) |
+| `AuthService.isLoading$` | Observable boolean — SDK initialization state |
+| `AuthService.error$` | Observable — authentication errors |
+| `AuthService.getAccessTokenSilently()` | Get access token (uses refresh tokens on mobile) |
+| `Browser.open({ url })` | Open URL in system browser (Capacitor) |
+| `CapApp.addListener('appUrlOpen', cb)` | Listen for deep link callbacks (Capacitor) |
+
+## References
+
+- [Auth0 Angular SDK — GitHub](https://github.com/auth0/auth0-angular)
+- [Auth0 Ionic Angular Quickstart](https://auth0.com/docs/quickstart/native/ionic-angular)
+- [Auth0 Angular SDK — API Reference](https://auth0.github.io/auth0-angular/)
+- [Capacitor Browser Plugin](https://capacitorjs.com/docs/apis/browser)
+- [Capacitor App Plugin — Deep Links](https://capacitorjs.com/docs/apis/app)
+- [Ionic Framework — Angular](https://ionicframework.com/docs/angular/overview)
+
+---
+
+# auth0-ionic-angular — API Reference & Testing
+
+## Configuration Options
+
+### `provideAuth0()` / `AuthModule.forRoot()` Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `domain` | `string` | Yes | — | Auth0 tenant domain (e.g., `your-tenant.auth0.com`) |
+| `clientId` | `string` | Yes | — | Auth0 application Client ID |
+| `useRefreshTokens` | `boolean` | Yes (mobile) | `false` | Must be `true` for Ionic Capacitor apps |
+| `useRefreshTokensFallback` | `boolean` | Yes (mobile) | `true` | Must be `false` for Ionic Capacitor apps |
+| `cacheLocation` | `'memory' \| 'localstorage'` | No | `'memory'` | Where to store tokens — `'memory'` recommended for mobile |
+| `authorizationParams.redirect_uri` | `string` | Yes (Capacitor) | `window.location.origin` | Must be set to custom URL scheme for Capacitor: `PACKAGE_ID://DOMAIN/capacitor/PACKAGE_ID/callback` |
+| `authorizationParams.audience` | `string` | No | — | API audience for access token scoping |
+| `authorizationParams.scope` | `string` | No | `'openid profile email'` | OAuth scopes to request |
+| `httpInterceptor.allowedList` | `string[] \| HttpInterceptorRouteConfig[]` | No | `[]` | API URLs to attach access tokens to |
+| `errorPath` | `string` | No | — | Route to redirect to on authentication error |
+
+### Capacitor Configuration (`capacitor.config.ts`)
+
+```typescript
+import type { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'com.example.myapp',      // Used as URL scheme
+  appName: 'My Ionic App',
+  webDir: 'www',
+  server: {
+    androidScheme: 'https',
+  },
+};
+
+export default config;
+```
+
+## AuthService API
+
+### Properties (Observables)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isAuthenticated$` | `Observable<boolean>` | Emits `true` when user is authenticated |
+| `isLoading$` | `Observable<boolean>` | Emits `true` while SDK is initializing |
+| `user$` | `Observable<User \| null \| undefined>` | Emits user profile after authentication |
+| `error$` | `Observable<Error \| undefined>` | Emits authentication errors |
+| `idTokenClaims$` | `Observable<IdToken \| null \| undefined>` | Emits raw ID token claims |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `loginWithRedirect(options?)` | `Observable<void>` | Redirect to Auth0 Universal Login. Pass `openUrl` for Capacitor. |
+| `logout(options?)` | `Observable<void>` | Log out and redirect. Pass `openUrl` and `logoutParams.returnTo` for Capacitor. |
+| `handleRedirectCallback(url?)` | `Observable<RedirectLoginResult>` | Process callback URL from deep link. Call inside `ngZone.run()`. |
+| `getAccessTokenSilently(options?)` | `Observable<string>` | Get access token using refresh token (no iframe on mobile). |
+| `getAccessTokenWithPopup(options?)` | `Observable<string>` | Not supported on mobile — use `getAccessTokenSilently()`. |
+
+### `loginWithRedirect` Options (Capacitor)
+
+```typescript
+// callbackUri = `${appId}://${domain}/capacitor/${appId}/callback`
+this.auth.loginWithRedirect({
+  authorizationParams: {
+    audience: 'https://my-api.example.com',
+    scope: 'openid profile email read:data',
+    redirect_uri: callbackUri,
+  },
+  async openUrl(url: string) {
+    await Browser.open({ url, windowName: '_self' });
+  },
+}).subscribe();
+```
+
+### `logout` Options (Capacitor)
+
+```typescript
+// callbackUri = `${appId}://${domain}/capacitor/${appId}/callback`
+this.auth.logout({
+  logoutParams: {
+    returnTo: callbackUri,
+  },
+  async openUrl(url: string) {
+    await Browser.open({ url, windowName: '_self' });
+  },
+}).subscribe();
+```
+
+## Claims Reference
+
+### Standard OIDC Claims (`user$`)
+
+| Claim | Type | Description |
+|-------|------|-------------|
+| `sub` | `string` | Unique user identifier (e.g., `auth0\|abc123`) |
+| `name` | `string` | Full name |
+| `given_name` | `string` | First name |
+| `family_name` | `string` | Last name |
+| `nickname` | `string` | Casual name |
+| `picture` | `string` | Profile picture URL |
+| `email` | `string` | Email address |
+| `email_verified` | `boolean` | Whether email is verified |
+| `locale` | `string` | User locale |
+| `updated_at` | `string` | Last profile update timestamp |
+
+### Auth0-Specific Claims
+
+| Claim | Type | Source | Description |
+|-------|------|--------|-------------|
+| `org_id` | `string` | Organizations | Organization identifier |
+| `permissions` | `string[]` | RBAC | Granted permissions (requires API audience + RBAC enabled) |
+
+## HTTP Interceptor for API Calls
+
+Attach access tokens to outgoing API requests automatically:
+
+```typescript
+provideAuth0({
+  domain: 'YOUR_AUTH0_DOMAIN',
+  clientId: 'YOUR_AUTH0_CLIENT_ID',
+  useRefreshTokens: true,
+  useRefreshTokensFallback: false,
+  authorizationParams: {
+    audience: 'https://my-api.example.com',
+  },
+  httpInterceptor: {
+    allowedList: [
+      'https://my-api.example.com/*',
+      {
+        uri: 'https://my-api.example.com/admin/*',
+        tokenOptions: {
+          authorizationParams: {
+            scope: 'admin:access',
+          },
+        },
+      },
+    ],
+  },
+}),
+provideHttpClient(withInterceptors([authHttpInterceptorFn])),
+```
+
+## Complete Minimal Example
+
+### `src/app/app.config.ts`
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideRouter } from '@angular/router';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { provideAuth0, authHttpInterceptorFn } from '@auth0/auth0-angular';
+import { routes } from './app.routes';
+
+const appId = 'YOUR_PACKAGE_ID';
+const domain = 'YOUR_AUTH0_DOMAIN';
+const callbackUri = `${appId}://${domain}/capacitor/${appId}/callback`;
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideRouter(routes),
+    provideHttpClient(withInterceptors([authHttpInterceptorFn])),
+    provideAuth0({
+      domain,
+      clientId: 'YOUR_AUTH0_CLIENT_ID',
+      useRefreshTokens: true,
+      useRefreshTokensFallback: false,
+      authorizationParams: {
+        redirect_uri: callbackUri,
+      },
+    }),
+  ],
+};
+```
+
+### `src/app/app.component.ts`
+```typescript
+import { Component, NgZone, OnInit } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+import { Browser } from '@capacitor/browser';
+import { App as CapApp } from '@capacitor/app';
+import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';
+import { mergeMap } from 'rxjs/operators';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [IonApp, IonRouterOutlet],
+  template: `
+    <ion-app>
+      <ion-router-outlet></ion-router-outlet>
+    </ion-app>
+  `,
+})
+export class AppComponent implements OnInit {
+  constructor(
+    private auth: AuthService,
+    private ngZone: NgZone
+  ) {}
+
+  ngOnInit() {
+    CapApp.addListener('appUrlOpen', ({ url }) => {
+      this.ngZone.run(() => {
+        if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
+          this.auth
+            .handleRedirectCallback(url)
+            .pipe(mergeMap(() => Browser.close()))
+            .subscribe();
+        }
+      });
+    });
+  }
+}
+```
+
+## Testing Checklist
+
+- [ ] App opens Auth0 Universal Login in system browser (not in-app WebView)
+- [ ] After login, system browser closes and app receives user profile
+- [ ] `auth.isAuthenticated$` emits `true` after successful login
+- [ ] `auth.user$` contains name, email, and picture
+- [ ] Logout opens system browser, clears session, and returns to app
+- [ ] After logout, `auth.isAuthenticated$` emits `false`
+- [ ] Token refresh works silently (no login prompt on app restart if session valid)
+- [ ] Deep link callback URL matches Auth0 Dashboard configuration exactly
+- [ ] App works on both iOS (SFSafariViewController) and Android (Chrome Custom Tabs)
+- [ ] `ngZone.run()` wraps all callback handling (UI updates correctly)
+- [ ] Build succeeds: `npm run build && npx cap sync`
+
+## Common Issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Login opens but never returns to app | Callback URL mismatch | Ensure `PACKAGE_ID://{domain}/capacitor/PACKAGE_ID/callback` is in Auth0 Dashboard |
+| UI doesn't update after login | Missing `ngZone.run()` | Wrap `handleRedirectCallback` in `this.ngZone.run()` |
+| `getAccessTokenSilently` fails | `useRefreshTokens` not `true` | Set `useRefreshTokens: true` and `useRefreshTokensFallback: false` |
+| "Callback URL mismatch" error | Wrong app type in Auth0 | Change application type to **Native** (not SPA) |
+| White screen after login on Android | `androidScheme` not set | Add `server: { androidScheme: 'https' }` to `capacitor.config.ts` |
+| Token lost on app restart | Cache location issue | Ensure `useRefreshTokens: true` for persistent sessions |
+| `Browser.open` not available | Missing Capacitor plugin | Run `npm install @capacitor/browser && npx cap sync` |
+
+## Security Considerations
+
+- **Never store tokens in localStorage** on mobile — use `useRefreshTokens: true` with in-memory cache
+- **Never embed Client Secret** in mobile apps — Native apps use PKCE (no secret needed)
+- **Always validate the callback URL** contains `state` and `code`/`error` before calling `handleRedirectCallback`
+- **Use HTTPS** for any API calls made with access tokens
+- **Set `useRefreshTokensFallback: false`** to prevent iframe-based token refresh attempts on mobile
+
+---
+
+# auth0-ionic-angular — Integration Patterns
+
+## Authentication Flow Overview
+
+```text
+User taps Login
+    → auth.loginWithRedirect({ openUrl: Browser.open })
+    → System browser opens Auth0 Universal Login
+    → User authenticates
+    → Auth0 redirects to custom URL scheme
+    → OS routes deep link to app
+    → CapApp.addListener('appUrlOpen') fires
+    → ngZone.run() → auth.handleRedirectCallback(url)
+    → Browser.close()
+    → auth.isAuthenticated$ emits true
+    → auth.user$ emits user profile
+```
+
+## Deep Link Callback Handler
+
+The callback handler must be registered early in the app lifecycle. The recommended location is `AppComponent.ngOnInit()`:
+
+```typescript
+import { Component, NgZone, OnInit } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+import { Browser } from '@capacitor/browser';
+import { App as CapApp } from '@capacitor/app';
+import { mergeMap } from 'rxjs/operators';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [IonApp, IonRouterOutlet],
+  template: `
+    <ion-app>
+      <ion-router-outlet></ion-router-outlet>
+    </ion-app>
+  `,
+})
+export class AppComponent implements OnInit {
+  constructor(
+    private auth: AuthService,
+    private ngZone: NgZone
+  ) {}
+
+  ngOnInit() {
+    CapApp.addListener('appUrlOpen', ({ url }) => {
+      this.ngZone.run(() => {
+        if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
+          this.auth
+            .handleRedirectCallback(url)
+            .pipe(mergeMap(() => Browser.close()))
+            .subscribe();
+        }
+      });
+    });
+  }
+}
+```
+
+**Why `ngZone.run()`?** Capacitor plugin callbacks execute outside Angular's zone. Without `ngZone.run()`, Angular won't detect the authentication state change and the UI won't update.
+
+## Login
+
+### Basic Login
+
+```typescript
+import { Component } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+import { Browser } from '@capacitor/browser';
+
+@Component({
+  selector: 'app-login',
+  template: `
+    <ion-button (click)="login()" *ngIf="(auth.isAuthenticated$ | async) === false">
+      Log In
+    </ion-button>
+  `,
+})
+export class LoginPage {
+  constructor(public auth: AuthService) {}
+
+  login() {
+    this.auth
+      .loginWithRedirect({
+        async openUrl(url: string) {
+          await Browser.open({ url, windowName: '_self' });
+        },
+      })
+      .subscribe();
+  }
+}
+```
+
+### Login with Custom Audience and Scopes
+
+```typescript
+login() {
+  this.auth
+    .loginWithRedirect({
+      authorizationParams: {
+        audience: 'https://my-api.example.com',
+        scope: 'openid profile email read:data',
+      },
+      async openUrl(url: string) {
+        await Browser.open({ url, windowName: '_self' });
+      },
+    })
+    .subscribe();
+}
+```
+
+### Login with Organization
+
+```typescript
+login() {
+  this.auth
+    .loginWithRedirect({
+      authorizationParams: {
+        organization: 'org_abc123',
+      },
+      async openUrl(url: string) {
+        await Browser.open({ url, windowName: '_self' });
+      },
+    })
+    .subscribe();
+}
+```
+
+## Logout
+
+### Basic Logout
+
+```typescript
+import { Component } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+import { Browser } from '@capacitor/browser';
+
+@Component({
+  selector: 'app-logout-button',
+  template: `
+    <ion-button (click)="logout()" *ngIf="auth.isAuthenticated$ | async">
+      Log Out
+    </ion-button>
+  `,
+})
+export class LogoutButtonComponent {
+  constructor(public auth: AuthService) {}
+
+  logout() {
+    this.auth
+      .logout({
+        logoutParams: {
+          returnTo: `PACKAGE_ID://YOUR_AUTH0_DOMAIN/capacitor/PACKAGE_ID/callback`,
+        },
+        async openUrl(url: string) {
+          await Browser.open({ url, windowName: '_self' });
+        },
+      })
+      .subscribe();
+  }
+}
+```
+
+### Building the Logout Return URL Dynamically
+
+```typescript
+import { Inject } from '@angular/core';
+import { AuthClientConfig } from '@auth0/auth0-angular';
+import { DOCUMENT } from '@angular/common';
+
+export class LogoutButtonComponent {
+  constructor(
+    public auth: AuthService,
+    private config: AuthClientConfig,
+  ) {}
+
+  logout() {
+    const domain = this.config.get().domain;
+    const packageId = 'com.example.myapp'; // from capacitor.config.ts
+    const returnTo = `${packageId}://${domain}/capacitor/${packageId}/callback`;
+
+    this.auth
+      .logout({
+        logoutParams: { returnTo },
+        async openUrl(url: string) {
+          await Browser.open({ url, windowName: '_self' });
+        },
+      })
+      .subscribe();
+  }
+}
+```
+
+## User Profile
+
+### Display User Info
+
+```typescript
+import { Component } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+import { AsyncPipe, NgIf } from '@angular/common';
+import { IonCard, IonCardHeader, IonCardTitle, IonCardContent, IonAvatar } from '@ionic/angular/standalone';
+
+@Component({
+  selector: 'app-profile',
+  standalone: true,
+  imports: [AsyncPipe, NgIf, IonCard, IonCardHeader, IonCardTitle, IonCardContent, IonAvatar],
+  template: `
+    <ion-card *ngIf="auth.user$ | async as user">
+      <ion-card-header>
+        <ion-avatar>
+          <img [src]="user.picture" [alt]="user.name" />
+        </ion-avatar>
+        <ion-card-title>{{ user.name }}</ion-card-title>
+      </ion-card-header>
+      <ion-card-content>
+        <p>{{ user.email }}</p>
+      </ion-card-content>
+    </ion-card>
+  `,
+})
+export class ProfileComponent {
+  constructor(public auth: AuthService) {}
+}
+```
+
+### Access ID Token Claims
+
+```typescript
+import { Component } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+
+@Component({
+  selector: 'app-claims',
+  template: `
+    <pre *ngIf="auth.idTokenClaims$ | async as claims">
+      {{ claims | json }}
+    </pre>
+  `,
+})
+export class ClaimsComponent {
+  constructor(public auth: AuthService) {}
+}
+```
+
+## Token Management
+
+### Get Access Token
+
+```typescript
+import { Component } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+
+@Component({ ... })
+export class ApiComponent {
+  constructor(private auth: AuthService, private http: HttpClient) {}
+
+  callApi() {
+    this.auth.getAccessTokenSilently().subscribe(token => {
+      this.http.get('https://my-api.example.com/data', {
+        headers: { Authorization: `Bearer ${token}` },
+      }).subscribe(data => console.log(data));
+    });
+  }
+}
+```
+
+### Use HTTP Interceptor (Recommended)
+
+The `authHttpInterceptorFn` automatically attaches tokens to matching requests:
+
+```typescript
+// app.config.ts
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { provideAuth0, authHttpInterceptorFn } from '@auth0/auth0-angular';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(withInterceptors([authHttpInterceptorFn])),
+    provideAuth0({
+      domain: 'YOUR_AUTH0_DOMAIN',
+      clientId: 'YOUR_AUTH0_CLIENT_ID',
+      useRefreshTokens: true,
+      useRefreshTokensFallback: false,
+      authorizationParams: {
+        audience: 'https://my-api.example.com',
+      },
+      httpInterceptor: {
+        allowedList: ['https://my-api.example.com/*'],
+      },
+    }),
+  ],
+};
+```
+
+Then make HTTP calls as normal — tokens are added automatically:
+
+```typescript
+this.http.get('https://my-api.example.com/data').subscribe(data => {
+  console.log(data);
+});
+```
+
+## Route Guards
+
+### Protect Routes with `authGuardFn`
+
+```typescript
+import { Routes } from '@angular/router';
+import { authGuardFn } from '@auth0/auth0-angular';
+
+export const routes: Routes = [
+  { path: '', component: HomePage },
+  { path: 'profile', component: ProfilePage, canActivate: [authGuardFn] },
+  { path: 'settings', component: SettingsPage, canActivate: [authGuardFn] },
+];
+```
+
+When an unauthenticated user navigates to a protected route, `authGuardFn` automatically triggers `loginWithRedirect()`.
+
+## Error Handling
+
+### Subscribe to Auth Errors
+
+```typescript
+import { Component, OnInit } from '@angular/core';
+import { AuthService } from '@auth0/auth0-angular';
+
+@Component({ ... })
+export class AppComponent implements OnInit {
+  constructor(private auth: AuthService) {}
+
+  ngOnInit() {
+    this.auth.error$.subscribe(error => {
+      if (error) {
+        console.error('Auth error:', error.message);
+        // Show toast or navigate to error page
+      }
+    });
+  }
+}
+```
+
+### Handle Callback Errors
+
+```typescript
+CapApp.addListener('appUrlOpen', ({ url }) => {
+  this.ngZone.run(() => {
+    if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
+      this.auth.handleRedirectCallback(url).pipe(
+        mergeMap(() => Browser.close()),
+      ).subscribe({
+        error: (err) => {
+          console.error('Callback error:', err);
+          Browser.close();
+        },
+      });
+    }
+  });
+});
+```
+
+## Capacitor Lifecycle Considerations
+
+### Listener Cleanup
+
+If registering the `appUrlOpen` listener in a component that can be destroyed (not AppComponent), clean up:
+
+```typescript
+import { Component, NgZone, OnInit, OnDestroy } from '@angular/core';
+import { App as CapApp } from '@capacitor/app';
+import { PluginListenerHandle } from '@capacitor/core';
+
+@Component({ ... })
+export class AuthCallbackComponent implements OnInit, OnDestroy {
+  private listenerHandle?: PluginListenerHandle;
+
+  async ngOnInit() {
+    this.listenerHandle = await CapApp.addListener('appUrlOpen', ({ url }) => {
+      this.ngZone.run(() => {
+        // handle callback...
+      });
+    });
+  }
+
+  async ngOnDestroy() {
+    await this.listenerHandle?.remove();
+  }
+}
+```
+
+### App Resume / Background
+
+The Auth0 Angular SDK handles token refresh automatically via `useRefreshTokens: true`. When the app resumes from background:
+- If the refresh token is still valid, `getAccessTokenSilently()` returns a fresh access token
+- If the refresh token has expired, `isAuthenticated$` will emit `false` and the user needs to log in again
+
+## Testing Patterns
+
+### Mock AuthService in Unit Tests
+
+```typescript
+import { TestBed } from '@angular/core/testing';
+import { AuthService } from '@auth0/auth0-angular';
+import { of } from 'rxjs';
+
+const mockAuthService = {
+  isAuthenticated$: of(true),
+  user$: of({ name: 'Test User', email: 'test@example.com', picture: 'https://example.com/pic.jpg' }),
+  loginWithRedirect: jasmine.createSpy('loginWithRedirect').and.returnValue(of(void 0)),
+  logout: jasmine.createSpy('logout').and.returnValue(of(void 0)),
+  getAccessTokenSilently: jasmine.createSpy('getAccessTokenSilently').and.returnValue(of('mock-token')),
+};
+
+TestBed.configureTestingModule({
+  providers: [
+    { provide: AuthService, useValue: mockAuthService },
+  ],
+});
+```
+
+---
+
+# auth0-ionic-angular — Setup Guide
+
+## Auth0 Configuration
+
+> **Agent instruction:**
+>
+> **SECURITY — Never display credentials:**
+> After obtaining Auth0 credentials (domain, client ID) — whether from the Auth0 CLI or a user-provided env file — never print, echo, or display them in your text output. Write them directly to the config file (`src/environments/environment.ts`) silently. Do not produce output like "Domain: xxx" or "Client ID: yyy". Instead, confirm that the config file has been written and tell the user where to find it.
+>
+> **Always present the setup choice:**
+> Regardless of whether the user has already provided credentials in their prompt, **always** use `AskUserQuestion` to let the developer choose between Automatic and Manual setup:
+>
+> ```
+> AskUserQuestion:
+>   question: "How would you like to configure Auth0 for your Ionic Angular app?"
+>   options:
+>     - label: "Automatic Setup (Recommended)"
+>       description: "Uses the Auth0 CLI to create a Native application, configure callback URLs, and store credentials in your project automatically."
+>     - label: "Manual Setup"
+>       description: "You provide an .env file with your Auth0 Domain and Client ID, and the agent reads it and writes the project configuration for you."
+> ```
+
+---
+
+### Option A: Automatic Setup (Auth0 CLI)
+
+The agent executes Auth0 CLI commands to create the application, configure it, retrieve credentials, and write them to the project config file — fully hands-free.
+
+#### Step A1: Pre-flight checks
+
+Run these checks in order. If any fail, guide the user to fix the issue or fall back to Manual Setup.
+
+```bash
+# Verify Node.js 20+
+node --version
+
+# Verify Auth0 CLI is installed
+auth0 --version --no-input
+
+# Verify logged in to Auth0
+auth0 tenants list --csv --no-input
+```
+
+If the Auth0 CLI is not installed, instruct the user:
+```bash
+# macOS
+brew install auth0/auth0-cli/auth0
+
+# Linux
+curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh
+```
+
+If not logged in:
+```bash
+auth0 login
+```
+
+#### Step A2: Detect project and appId
+
+- Verify `package.json` contains `@angular/core`, `@ionic/angular`, and `@capacitor/core`
+- Read `appId` from `capacitor.config.ts` (match `appId: 'com.example.app'`) or `capacitor.config.json`
+- If neither config file exists or `appId` is not found, use `com.example.app` as default and warn the user
+
+#### Step A3: Get the active tenant domain
+
+```bash
+auth0 tenants list --csv --no-input
+```
+
+Parse the output to find the line containing `→` — the second CSV column on that line is the active domain.
+
+#### Step A4: Create a Native Auth0 application
+
+```bash
+auth0 apps create \
+  --name "PROJECT_NAME-ionic-angular" \
+  --type native \
+  --auth-method none \
+  --callbacks "PACKAGE_ID://DOMAIN/capacitor/PACKAGE_ID/callback" \
+  --logout-urls "PACKAGE_ID://DOMAIN/capacitor/PACKAGE_ID/callback" \
+  --origins "capacitor://localhost,http://localhost" \
+  --json --no-input
+```
+
+Replace `PROJECT_NAME` with the project name from `package.json`, `PACKAGE_ID` with the `appId` from Step A2, and `DOMAIN` with the tenant domain from Step A3.
+
+Extract `client_id` from the JSON output.
+
+#### Step A5: Enable Username-Password-Authentication connection
+
+```bash
+auth0 api get connections
+```
+
+Parse the JSON array to find the connection with `"name": "Username-Password-Authentication"`.
+
+- **If it exists** but doesn't include the new `client_id` in `enabled_clients`, update it:
+  ```bash
+  auth0 api patch "connections/CONNECTION_ID" --data '{"enabled_clients":["EXISTING_ID_1","EXISTING_ID_2","NEW_CLIENT_ID"]}'
+  ```
+  Keep all existing `enabled_clients` and append the new one.
+
+- **If it doesn't exist**, create it:
+  ```bash
+  auth0 api post connections --data '{"strategy":"auth0","name":"Username-Password-Authentication","enabled_clients":["CLIENT_ID"]}'
+  ```
+
+- **If it already includes the client_id**, skip this step.
+
+#### Step A6: Write config file
+
+Create `src/environments/` directory if it doesn't exist, then write `src/environments/environment.ts`:
+
+```typescript
+export const environment = {
+  production: false,
+  auth0: {
+    domain: 'DOMAIN',
+    clientId: 'CLIENT_ID',
+    callbackUrl: 'PACKAGE_ID://DOMAIN/capacitor/PACKAGE_ID/callback',
+    appId: 'PACKAGE_ID',
+  },
+};
+```
+
+#### Step A7: Confirm completion
+
+Tell the user that Auth0 has been configured and credentials have been written to `src/environments/environment.ts`. Do NOT display the domain, client ID, or any credential values in the output.
+
+---
+
+### Option B: Manual Setup
+
+The developer provides an `.env` file containing their Auth0 credentials. The agent reads the file, extracts the values, and writes the project configuration.
+
+#### Step B1: Ask for the env file path
+
+Use `AskUserQuestion` to ask the developer for the path to their `.env` file:
+
+```
+AskUserQuestion:
+  question: "Please provide the path to your .env file containing Auth0 credentials (AUTH0_DOMAIN and AUTH0_CLIENT_ID):"
+```
+
+The `.env` file should contain lines in this format:
+```
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_CLIENT_ID=your_client_id_here
+```
+
+> **Agent instruction:** Read the file at the path the user provides. Extract the values for `AUTH0_DOMAIN` and `AUTH0_CLIENT_ID` by parsing `KEY=VALUE` lines. If the file is missing either key, use `AskUserQuestion` to ask the user to provide the missing value. Accept common variations: `DOMAIN` / `AUTH0_DOMAIN`, `CLIENT_ID` / `AUTH0_CLIENT_ID`.
+
+#### Step B2: Detect appId
+
+Read `appId` from `capacitor.config.ts` (match `appId: 'com.example.app'`) or `capacitor.config.json`. If not found, use `com.example.app` as default and warn the user.
+
+#### Step B3: Write config file
+
+Create `src/environments/` directory if it doesn't exist, then write `src/environments/environment.ts`:
+
+```typescript
+export const environment = {
+  production: false,
+  auth0: {
+    domain: 'DOMAIN',
+    clientId: 'CLIENT_ID',
+    callbackUrl: 'PACKAGE_ID://DOMAIN/capacitor/PACKAGE_ID/callback',
+    appId: 'PACKAGE_ID',
+  },
+};
+```
+
+#### Step B4: Remind user to configure Auth0 Dashboard
+
+Since credentials were provided manually, the user must also configure the Auth0 Dashboard themselves. Display these required settings:
+
+| Setting | Value |
+|---------|-------|
+| **Application Type** | **Native** |
+| **Allowed Callback URLs** | `PACKAGE_ID://DOMAIN/capacitor/PACKAGE_ID/callback` |
+| **Allowed Logout URLs** | `PACKAGE_ID://DOMAIN/capacitor/PACKAGE_ID/callback` |
+| **Allowed Origins** | `capacitor://localhost, http://localhost` |
+
+Also add `http://localhost:8100` to Callback URLs, Logout URLs, and Web Origins if the user will use `ionic serve` for local development.
+
+No Client Secret is needed — Native apps use PKCE.
+
+## Auth0 Dashboard Configuration
+
+### Create a Native Application
+
+1. Go to **Auth0 Dashboard → Applications → Create Application**
+2. Select **Native** as the application type
+3. Note the **Domain** and **Client ID** from the Settings tab
+
+### Configure URLs
+
+Determine your `appId` from `capacitor.config.ts` (e.g., `com.example.myapp`).
+
+| Setting | Value |
+|---------|-------|
+| **Allowed Callback URLs** | `PACKAGE_ID://YOUR_DOMAIN/capacitor/PACKAGE_ID/callback` |
+| **Allowed Logout URLs** | `PACKAGE_ID://YOUR_DOMAIN/capacitor/PACKAGE_ID/callback` |
+| **Allowed Origins** | `capacitor://localhost, http://localhost` |
+
+Example with `appId = com.example.myapp` and domain `dev-abc123.us.auth0.com`:
+```text
+com.example.myapp://dev-abc123.us.auth0.com/capacitor/com.example.myapp/callback
+```
+
+## SDK Installation
+
+```bash
+npm install @auth0/auth0-angular @capacitor/browser @capacitor/app
+```
+
+If Capacitor platforms aren't added yet:
+```bash
+npx cap add ios
+npx cap add android
+```
+
+## SDK Configuration
+
+### Standalone Components (Angular 17+)
+
+In `src/app/app.config.ts`:
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideRouter } from '@angular/router';
+import { provideAuth0 } from '@auth0/auth0-angular';
+import { routes } from './app.routes';
+
+// Replace with your capacitor.config.ts appId and Auth0 domain
+const appId = 'YOUR_PACKAGE_ID';
+const domain = 'YOUR_AUTH0_DOMAIN';
+const callbackUri = `${appId}://${domain}/capacitor/${appId}/callback`;
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideRouter(routes),
+    provideAuth0({
+      domain,
+      clientId: 'YOUR_AUTH0_CLIENT_ID',
+      useRefreshTokens: true,
+      useRefreshTokensFallback: false,
+      authorizationParams: {
+        redirect_uri: callbackUri,
+      },
+    }),
+  ],
+};
+```
+
+### NgModule (Angular 16 and earlier)
+
+In `src/app/app.module.ts`:
+
+```typescript
+import { NgModule } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { IonicModule } from '@ionic/angular';
+import { AuthModule } from '@auth0/auth0-angular';
+import { AppComponent } from './app.component';
+import { AppRoutingModule } from './app-routing.module';
+
+const appId = 'YOUR_PACKAGE_ID';
+const domain = 'YOUR_AUTH0_DOMAIN';
+const callbackUri = `${appId}://${domain}/capacitor/${appId}/callback`;
+
+@NgModule({
+  declarations: [AppComponent],
+  imports: [
+    BrowserModule,
+    IonicModule.forRoot(),
+    AppRoutingModule,
+    AuthModule.forRoot({
+      domain,
+      clientId: 'YOUR_AUTH0_CLIENT_ID',
+      useRefreshTokens: true,
+      useRefreshTokensFallback: false,
+      authorizationParams: {
+        redirect_uri: callbackUri,
+      },
+    }),
+  ],
+  bootstrap: [AppComponent],
+})
+export class AppModule {}
+```
+
+## Post-Setup: Deep Linking Configuration
+
+### iOS
+
+The custom URL scheme is automatically registered by Capacitor from `capacitor.config.ts`. Verify in `ios/App/App/Info.plist`:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>PACKAGE_ID</string>
+    </array>
+  </dict>
+</array>
+```
+
+### Android
+
+Verify the intent filter in `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<intent-filter>
+  <action android:name="android.intent.action.VIEW" />
+  <category android:name="android.intent.category.DEFAULT" />
+  <category android:name="android.intent.category.BROWSABLE" />
+  <data android:scheme="PACKAGE_ID" />
+</intent-filter>
+```
+
+## Secret Management
+
+- **No Client Secret needed** — Ionic Capacitor apps are Native apps that use PKCE for authentication
+- **Never embed secrets in client-side code** — the Auth0 Angular SDK only requires `domain` and `clientId`
+- Configuration values (domain, clientId) can be hardcoded in `app.config.ts` / `app.module.ts` or loaded from `environment.ts`
+
+### Using `environment.ts` (optional)
+
+```typescript
+// src/environments/environment.ts
+export const environment = {
+  production: false,
+  auth0: {
+    domain: 'YOUR_AUTH0_DOMAIN',
+    clientId: 'YOUR_AUTH0_CLIENT_ID',
+  },
+};
+```
+
+```typescript
+// src/app/app.config.ts
+import { environment } from '../environments/environment';
+
+const appId = 'YOUR_PACKAGE_ID'; // from capacitor.config.ts
+const callbackUri = `${appId}://${environment.auth0.domain}/capacitor/${appId}/callback`;
+
+provideAuth0({
+  domain: environment.auth0.domain,
+  clientId: environment.auth0.clientId,
+  useRefreshTokens: true,
+  useRefreshTokensFallback: false,
+  authorizationParams: {
+    redirect_uri: callbackUri,
+  },
+}),
+```
+
+## Verification
+
+After setup, verify:
+
+1. **Build succeeds:** `npm run build`
+2. **Capacitor sync:** `npx cap sync`
+3. **Run on device/emulator:**
+   - iOS: `npx cap open ios` → Run in Xcode
+   - Android: `npx cap open android` → Run in Android Studio
+4. **Login opens system browser** (not in-app WebView)
+5. **Callback returns to app** with user profile
diff --git a/main/.mintlify/skills/auth0/references/framework-ionic-react/index.md b/main/.mintlify/skills/auth0/references/framework-ionic-react/index.md
new file mode 100644
index 0000000000..e05457de50
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-ionic-react/index.md
@@ -0,0 +1,1013 @@
+
+# Auth0 Ionic React (Capacitor) Integration
+
+Add Auth0 authentication to Ionic React applications using Capacitor. This skill covers native mobile authentication using the `@auth0/auth0-react` SDK combined with `@capacitor/browser` and `@capacitor/app` plugins for deep link handling on iOS and Android.
+
+## Prerequisites
+
+- Node.js 18+
+- Ionic CLI (`npm install -g @ionic/cli`)
+- An existing Ionic React application with Capacitor configured
+- Auth0 account and tenant
+- For iOS: Xcode 14+ and CocoaPods
+- For Android: Android Studio with API level 21+
+- Auth0 CLI — `brew install auth0/auth0-cli/auth0`
+
+## When NOT to Use
+
+| Use Case | Use instead |
+|----------|------------------|
+| React SPA (no Capacitor/Ionic) | the Auth0 integration workflow for React |
+| React Native (bare CLI) | the Auth0 integration workflow for React Native |
+| Expo (React Native) | the Auth0 integration workflow for Expo |
+| Ionic + Angular + Capacitor | the Auth0 integration workflow for Ionic Angular |
+| Ionic + Vue + Capacitor | the Auth0 integration workflow for Ionic Vue |
+| Next.js (server-side) | the Auth0 integration workflow for Next.js |
+| iOS native (Swift) | the Auth0 integration workflow for iOS (Swift) |
+| Android native (Kotlin) | the Auth0 integration workflow for Android (Kotlin) |
+
+## Quick Start Workflow
+
+### Step 1: Configure Auth0
+
+**For automated setup with Auth0 CLI**, see the Setup Guide section (below) for complete scripts.
+
+**For manual setup**, configure a **Native** application in the [Auth0 Dashboard](https://manage.auth0.com/) and note your Domain and Client ID.
+
+### Step 2: Install Dependencies
+
+```bash
+npm install @auth0/auth0-react @capacitor/browser @capacitor/app
+npx cap sync
+```
+
+### Step 3: Set Up Auth0Provider
+
+Wrap the app root with `Auth0Provider`, configuring it for Capacitor. In `src/main.tsx`:
+
+```tsx
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { Auth0Provider } from '@auth0/auth0-react';
+import App from './App';
+
+const domain = import.meta.env.VITE_AUTH0_DOMAIN;
+const clientId = import.meta.env.VITE_AUTH0_CLIENT_ID;
+const packageId = import.meta.env.VITE_AUTH0_PACKAGE_ID; // e.g., com.example.myapp
+
+const redirectUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;
+
+createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <Auth0Provider
+      domain={domain}
+      clientId={clientId}
+      useRefreshTokens={true}
+      useRefreshTokensFallback={false}
+      authorizationParams={{
+        redirect_uri: redirectUri
+      }}
+    >
+      <App />
+    </Auth0Provider>
+  </React.StrictMode>
+);
+```
+
+### Step 4: Implement Login with Capacitor Browser
+
+```tsx
+import { useAuth0 } from '@auth0/auth0-react';
+import { Browser } from '@capacitor/browser';
+
+const { loginWithRedirect } = useAuth0();
+
+const login = async () => {
+  await loginWithRedirect({
+    async openUrl(url) {
+      await Browser.open({ url, windowName: "_self" });
+    }
+  });
+};
+```
+
+### Step 5: Handle Callback via Deep Link
+
+```tsx
+import { useEffect } from 'react';
+import { App as CapApp } from '@capacitor/app';
+import { Browser } from '@capacitor/browser';
+import { useAuth0 } from '@auth0/auth0-react';
+
+const { handleRedirectCallback } = useAuth0();
+
+useEffect(() => {
+  const listener = CapApp.addListener('appUrlOpen', async ({ url }) => {
+    if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
+      await handleRedirectCallback(url);
+    }
+    await Browser.close();
+  });
+
+  return () => {
+    listener.then(l => l.remove());
+  };
+}, [handleRedirectCallback]);
+```
+
+### Step 6: Implement Logout
+
+```tsx
+const doLogout = async () => {
+  await logout({
+    logoutParams: {
+      returnTo: `${packageId}://${domain}/capacitor/${packageId}/callback`
+    },
+    async openUrl(url) {
+      await Browser.open({ url, windowName: "_self" });
+    }
+  });
+};
+```
+
+### Step 7: Build and Test
+
+> **Agent instruction:** After integration, verify the build:
+> ```bash
+> ionic build
+> npx cap sync
+> ```
+> For iOS: `npx cap open ios` then build in Xcode.
+> For Android: `npx cap open android` then build in Android Studio.
+> If the build fails, iterate up to 5-6 times to fix issues. If still failing, use `AskUserQuestion` to request help.
+
+## Detailed Documentation
+
+- **Setup Guide** (see below) — Auth0 CLI configuration, Capacitor URL scheme registration, secret management
+- **Integration Patterns** (see below) — Login/logout with Capacitor Browser, deep link callback handling, user profile, protected routes, token access, error handling
+- **Testing & Reference** (see below) — Full API reference for Auth0Provider props, useAuth0 hook, Capacitor plugin configuration, testing checklist, common issues
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| App type not set to **Native** in Auth0 Dashboard | Change application type to "Native" in Dashboard settings |
+| Missing or incorrect callback URL format | Use `YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback` — must match exactly |
+| Not enabling refresh tokens | Set `useRefreshTokens={true}` and `useRefreshTokensFallback={false}` on Auth0Provider |
+| Missing `@capacitor/browser` or `@capacitor/app` | Install both: `npm install @capacitor/browser @capacitor/app && npx cap sync` |
+| Not handling deep link callback | Add `CapApp.addListener('appUrlOpen', ...)` to process Auth0 redirect |
+| Forgetting `npx cap sync` after install | Always run `npx cap sync` after installing Capacitor plugins |
+| Using `window.location.origin` as redirect URI | Use the custom URL scheme (`packageId://domain/...`), not `http://localhost` |
+| Missing Allowed Origins in Dashboard | Add `capacitor://localhost, http://localhost` to Allowed Origins |
+| localStorage treated as persistent on mobile | Use refresh tokens (`useRefreshTokens={true}`) for reliable token persistence |
+| iOS SSO not working | SFSafariViewController doesn't share cookies with Safari on iOS 11+; this is expected |
+| Not testing on physical device | Always test auth flows on a physical device; simulators may not handle deep links correctly |
+
+## WebAuth Method
+
+This SDK uses Auth0's Universal Login (WebAuth) via the Capacitor Browser plugin. The `loginWithRedirect()` method opens the Auth0 authorization endpoint in a system browser (SFSafariViewController on iOS, Chrome Custom Tabs on Android). After authentication, Auth0 redirects back to the app using a native callback URL with a custom scheme: `{packageId}://{domain}/capacitor/{packageId}/callback`. The `@capacitor/app` plugin captures this deep link, and `handleRedirectCallback(url)` processes the authorization code exchange.
+
+Unlike standard native SDKs that use `https://{domain}/android/{packageId}/callback` or `https://{domain}/ios/{bundleId}/callback`, Ionic Capacitor apps use the Capacitor-specific callback path with the package ID as the URL scheme.
+
+## Related Skills
+
+All of this lives in the one `auth0` skill — just describe what you need (e.g. "add MFA", "protect my API").
+
+## Quick Reference
+
+| API | Description |
+|-----|-------------|
+| `Auth0Provider` | Context provider — wraps app root with Auth0 config |
+| `useAuth0()` | Hook — returns `{ isLoading, isAuthenticated, user, loginWithRedirect, logout, getAccessTokenSilently, handleRedirectCallback }` |
+| `loginWithRedirect({ openUrl })` | Login via Universal Login — use `Browser.open()` in `openUrl` callback |
+| `logout({ logoutParams, openUrl })` | Logout — use `Browser.open()` in `openUrl` callback |
+| `handleRedirectCallback(url)` | Process Auth0 callback URL from deep link |
+| `getAccessTokenSilently()` | Get access token (uses refresh tokens on mobile) |
+| `withAuthenticationRequired(Component)` | HOC to protect routes |
+| `Browser.open({ url })` | Capacitor — opens URL in system browser (SFSafariViewController / Chrome Custom Tabs) |
+| `CapApp.addListener('appUrlOpen', cb)` | Capacitor — listens for deep link events |
+| `Browser.close()` | Capacitor — closes the in-app browser after callback |
+
+## References
+
+- [Auth0 Ionic React Quickstart](https://auth0.com/docs/quickstart/native/ionic-react/interactive)
+- [Auth0 React SDK GitHub](https://github.com/auth0/auth0-react)
+- [Auth0 React SDK API Reference](https://auth0.github.io/auth0-react/)
+- [Ionic React Capacitor Sample App](https://github.com/auth0-samples/auth0-ionic-samples/tree/main/react)
+- [Capacitor Browser Plugin](https://capacitorjs.com/docs/apis/browser)
+- [Capacitor App Plugin](https://capacitorjs.com/docs/apis/app)
+- [Auth0 Dashboard](https://manage.auth0.com/)
+
+---
+
+# Auth0 Ionic React (Capacitor) — API Reference & Testing
+
+## Auth0Provider Configuration
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `domain` | `string` | Yes | — | Auth0 tenant domain (e.g., `your-tenant.auth0.com`) |
+| `clientId` | `string` | Yes | — | Auth0 application Client ID |
+| `useRefreshTokens` | `boolean` | Yes (for Capacitor) | `false` | Must be `true` for native mobile — uses refresh tokens instead of iframe |
+| `useRefreshTokensFallback` | `boolean` | Yes (for Capacitor) | `true` | Must be `false` for native mobile — disables iframe fallback |
+| `authorizationParams.redirect_uri` | `string` | Yes | — | Custom scheme callback URL: `{packageId}://{domain}/capacitor/{packageId}/callback` |
+| `authorizationParams.audience` | `string` | No | — | API identifier for access token audience |
+| `authorizationParams.scope` | `string` | No | `openid profile email` | OAuth scopes to request |
+| `cacheLocation` | `string` | No | `memory` | Token cache location: `memory` or `localstorage` |
+
+### Capacitor-Specific Configuration
+
+```tsx
+<Auth0Provider
+  domain="your-tenant.auth0.com"
+  clientId="your-client-id"
+  useRefreshTokens={true}
+  useRefreshTokensFallback={false}
+  authorizationParams={{
+    redirect_uri: "com.example.myapp://your-tenant.auth0.com/capacitor/com.example.myapp/callback"
+  }}
+>
+  <App />
+</Auth0Provider>
+```
+
+## useAuth0() Hook
+
+```tsx
+const {
+  isLoading,          // boolean — true while SDK initializes
+  isAuthenticated,    // boolean — true if user has valid session
+  user,               // User | undefined — authenticated user profile
+  error,              // Error | undefined — last authentication error
+  loginWithRedirect,  // (options?) => Promise<void>
+  logout,             // (options?) => Promise<void>
+  getAccessTokenSilently, // (options?) => Promise<string>
+  getAccessTokenWithPopup, // (options?) => Promise<string> (not for Capacitor)
+  handleRedirectCallback,  // (url?) => Promise<RedirectLoginResult>
+} = useAuth0();
+```
+
+## loginWithRedirect Options (Capacitor)
+
+```tsx
+await loginWithRedirect({
+  // Required for Capacitor: opens URL in system browser
+  async openUrl(url: string) {
+    await Browser.open({ url, windowName: "_self" });
+  },
+  // Optional: additional authorization params
+  authorizationParams: {
+    audience: "https://api.example.com/",
+    scope: "openid profile email read:data",
+    organization: "org_abc123",
+    invitation: "inv_xyz789",
+  }
+});
+```
+
+## logout Options (Capacitor)
+
+```tsx
+await logout({
+  logoutParams: {
+    returnTo: "com.example.myapp://your-tenant.auth0.com/capacitor/com.example.myapp/callback"
+  },
+  async openUrl(url: string) {
+    await Browser.open({ url, windowName: "_self" });
+  }
+});
+```
+
+## getAccessTokenSilently Options
+
+```tsx
+const token = await getAccessTokenSilently({
+  authorizationParams: {
+    audience: "https://api.example.com/",
+    scope: "read:data",
+  }
+});
+
+// Use token in API calls
+const response = await fetch("https://api.example.com/data", {
+  headers: { Authorization: `Bearer ${token}` }
+});
+```
+
+## Claims Reference
+
+| Claim | Source | Description |
+|-------|--------|-------------|
+| `sub` | ID Token | User identifier (e.g., `auth0|abc123`) |
+| `name` | ID Token | User's full name |
+| `email` | ID Token | User's email address |
+| `email_verified` | ID Token | Whether email has been verified |
+| `picture` | ID Token | URL to user's profile picture |
+| `nickname` | ID Token | User's nickname |
+| `updated_at` | ID Token | Last profile update timestamp |
+| `org_id` | ID Token | Organization ID (when using Organizations) |
+| `permissions` | Access Token | RBAC permissions array (when API has RBAC enabled) |
+
+## Capacitor Plugin Configuration
+
+### capacitor.config.ts
+
+```typescript
+import type { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'com.example.myapp',
+  appName: 'My App',
+  webDir: 'dist',  // or 'build' for CRA
+  server: {
+    androidScheme: 'https'
+  }
+};
+
+export default config;
+```
+
+### iOS: URL Scheme Registration
+
+No additional URL scheme registration needed for Capacitor — the deep link uses the app's bundle ID as the scheme, which Capacitor handles automatically.
+
+### Android: URL Scheme Registration
+
+Capacitor handles deep link registration automatically via the `appId` in `capacitor.config.ts`. Ensure the `appId` matches the `applicationId` in `android/app/build.gradle`.
+
+## Auth0 Dashboard Configuration
+
+### Callback URLs
+
+```text
+YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback
+```
+
+Example: `com.example.myapp://your-tenant.auth0.com/capacitor/com.example.myapp/callback`
+
+### Logout URLs
+
+Same as callback URL:
+```text
+YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback
+```
+
+### Allowed Origins
+
+```text
+capacitor://localhost, http://localhost
+```
+
+## Testing Checklist
+
+- [ ] Auth0Provider wraps root component with correct domain and clientId
+- [ ] `useRefreshTokens={true}` and `useRefreshTokensFallback={false}` are set
+- [ ] `redirect_uri` uses custom scheme format (`packageId://domain/capacitor/packageId/callback`)
+- [ ] Login opens system browser (SFSafariViewController on iOS, Chrome Custom Tabs on Android)
+- [ ] Deep link callback is handled via `CapApp.addListener('appUrlOpen', ...)`
+- [ ] `handleRedirectCallback(url)` is called when URL contains `state` and `code`/`error`
+- [ ] `Browser.close()` is called after handling callback
+- [ ] Logout redirects back to app via custom scheme
+- [ ] `getAccessTokenSilently()` works with refresh tokens
+- [ ] User profile data is accessible via `useAuth0().user`
+- [ ] `npx cap sync` has been run after installing Capacitor plugins
+- [ ] Auth0 Dashboard has correct Callback URLs, Logout URLs, and Allowed Origins
+- [ ] Application type is set to "Native" in Auth0 Dashboard
+
+## Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Login opens but never returns to app | Callback URL mismatch or missing deep link handler | Verify callback URL in Dashboard matches `redirect_uri`; ensure `appUrlOpen` listener is registered |
+| `handleRedirectCallback` not called | Deep link listener not set up or URL check is wrong | Verify `CapApp.addListener('appUrlOpen', ...)` runs on app mount |
+| Token refresh fails silently | `useRefreshTokens` not enabled | Set `useRefreshTokens={true}` on Auth0Provider |
+| iframe fallback error on mobile | `useRefreshTokensFallback` not disabled | Set `useRefreshTokensFallback={false}` on Auth0Provider |
+| `Browser.open` does nothing | `@capacitor/browser` not installed or synced | Run `npm install @capacitor/browser && npx cap sync` |
+| App crashes on deep link | Missing `@capacitor/app` plugin | Run `npm install @capacitor/app && npx cap sync` |
+| CORS error during token exchange | Missing Allowed Origins in Auth0 Dashboard | Add `capacitor://localhost, http://localhost` to Allowed Origins |
+| `user` is `undefined` after login | Callback not processed before reading user | Wait for `isLoading === false` before accessing `user` |
+| SSO not working on iOS | SFSafariViewController doesn't share Safari cookies (iOS 11+) | Expected limitation — SSO across apps is not supported on iOS |
+
+## Security Considerations
+
+- **No client secret**: Native applications must not include a client secret. Use PKCE (Auth Code + PKCE) flow, which is the default.
+- **Refresh tokens**: Always enable `useRefreshTokens={true}` for Capacitor apps. localStorage is transient on mobile.
+- **Token storage**: The SDK stores tokens in memory by default. On mobile, refresh tokens are the reliable mechanism for session persistence.
+- **Custom scheme validation**: The callback URL scheme must match the app's package/bundle ID exactly.
+- **HTTPS**: Capacitor uses HTTPS for Android by default (`androidScheme: 'https'` in config). Do not change this.
+
+---
+
+# Integration Patterns
+
+## Authentication Flow
+
+The Ionic React + Capacitor authentication flow:
+
+1. User taps "Login" button
+2. `loginWithRedirect()` is called with a custom `openUrl` that uses `Browser.open()`
+3. Capacitor Browser opens Auth0 Universal Login in a system browser (SFSafariViewController on iOS, Chrome Custom Tabs on Android)
+4. User authenticates with Auth0
+5. Auth0 redirects to the custom scheme callback URL (`packageId://domain/capacitor/packageId/callback`)
+6. Capacitor App plugin receives the deep link via `appUrlOpen` event
+7. `handleRedirectCallback(url)` processes the authorization code
+8. `Browser.close()` dismisses the system browser
+9. User is now authenticated — `isAuthenticated` is `true`, `user` is populated
+
+## Auth0Provider Setup
+
+Configure `Auth0Provider` at your app's entry point (`src/main.tsx` or `src/index.tsx`):
+
+```tsx
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { Auth0Provider } from '@auth0/auth0-react';
+import App from './App';
+
+const domain = "your-tenant.auth0.com";
+const clientId = "your-client-id";
+const packageId = "com.example.myapp";
+const callbackUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;
+
+const root = createRoot(document.getElementById('root')!);
+
+root.render(
+  <Auth0Provider
+    domain={domain}
+    clientId={clientId}
+    useRefreshTokens={true}
+    useRefreshTokensFallback={false}
+    authorizationParams={{
+      redirect_uri: callbackUri
+    }}
+  >
+    <App />
+  </Auth0Provider>
+);
+```
+
+### Why These Props Are Required for Capacitor
+
+| Prop | Value | Reason |
+|------|-------|--------|
+| `useRefreshTokens` | `true` | Mobile apps cannot use iframe-based token renewal. Refresh tokens provide reliable session persistence. |
+| `useRefreshTokensFallback` | `false` | Prevents the SDK from attempting iframe fallback, which fails on native. |
+| `authorizationParams.redirect_uri` | Custom scheme URL | Native apps use a custom URL scheme, not `http://localhost`. |
+
+## Login Implementation
+
+```tsx
+import React from 'react';
+import { useAuth0 } from '@auth0/auth0-react';
+import { Browser } from '@capacitor/browser';
+import { IonButton } from '@ionic/react';
+
+const LoginButton: React.FC = () => {
+  const { loginWithRedirect } = useAuth0();
+
+  const login = async () => {
+    await loginWithRedirect({
+      async openUrl(url) {
+        await Browser.open({
+          url,
+          windowName: "_self"
+        });
+      }
+    });
+  };
+
+  return <IonButton onClick={login}>Log in</IonButton>;
+};
+
+export default LoginButton;
+```
+
+## Deep Link Callback Handling
+
+Handle the callback in your main App component. This must run on app initialization:
+
+```tsx
+import React, { useEffect } from 'react';
+import { useAuth0 } from '@auth0/auth0-react';
+import { App as CapApp } from '@capacitor/app';
+import { Browser } from '@capacitor/browser';
+import {
+  IonApp,
+  IonRouterOutlet,
+  setupIonicReact
+} from '@ionic/react';
+import { IonReactRouter } from '@ionic/react-router';
+
+setupIonicReact();
+
+const App: React.FC = () => {
+  const { handleRedirectCallback } = useAuth0();
+
+  useEffect(() => {
+    const handleAppUrlOpen = async ({ url }: { url: string }) => {
+      if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
+        await handleRedirectCallback(url);
+      }
+      await Browser.close();
+    };
+
+    CapApp.addListener('appUrlOpen', handleAppUrlOpen);
+
+    return () => {
+      CapApp.removeAllListeners();
+    };
+  }, [handleRedirectCallback]);
+
+  return (
+    <IonApp>
+      <IonReactRouter>
+        <IonRouterOutlet>
+          {/* Your routes */}
+        </IonRouterOutlet>
+      </IonReactRouter>
+    </IonApp>
+  );
+};
+
+export default App;
+```
+
+## Logout Implementation
+
+```tsx
+import React from 'react';
+import { useAuth0 } from '@auth0/auth0-react';
+import { Browser } from '@capacitor/browser';
+import { IonButton } from '@ionic/react';
+
+const domain = "your-tenant.auth0.com";
+const packageId = "com.example.myapp";
+const logoutUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;
+
+const LogoutButton: React.FC = () => {
+  const { logout } = useAuth0();
+
+  const doLogout = async () => {
+    await logout({
+      logoutParams: {
+        returnTo: logoutUri
+      },
+      async openUrl(url) {
+        await Browser.open({
+          url,
+          windowName: "_self"
+        });
+      }
+    });
+  };
+
+  return <IonButton onClick={doLogout}>Log out</IonButton>;
+};
+
+export default LogoutButton;
+```
+
+## User Profile Display
+
+```tsx
+import React from 'react';
+import { useAuth0 } from '@auth0/auth0-react';
+import {
+  IonCard,
+  IonCardContent,
+  IonCardHeader,
+  IonCardTitle,
+  IonAvatar,
+  IonItem,
+  IonLabel,
+  IonSpinner
+} from '@ionic/react';
+
+const Profile: React.FC = () => {
+  const { user, isLoading, isAuthenticated } = useAuth0();
+
+  if (isLoading) {
+    return <IonSpinner />;
+  }
+
+  if (!isAuthenticated || !user) {
+    return null;
+  }
+
+  return (
+    <IonCard>
+      <IonCardHeader>
+        <IonItem lines="none">
+          <IonAvatar slot="start">
+            <img src={user.picture} alt={user.name} />
+          </IonAvatar>
+          <IonLabel>
+            <IonCardTitle>{user.name}</IonCardTitle>
+            <p>{user.email}</p>
+          </IonLabel>
+        </IonItem>
+      </IonCardHeader>
+      <IonCardContent>
+        <pre>{JSON.stringify(user, null, 2)}</pre>
+      </IonCardContent>
+    </IonCard>
+  );
+};
+
+export default Profile;
+```
+
+## Protected Routes
+
+Use `withAuthenticationRequired` HOC to protect Ionic pages:
+
+```tsx
+import React from 'react';
+import { withAuthenticationRequired } from '@auth0/auth0-react';
+import { IonPage, IonContent, IonSpinner } from '@ionic/react';
+
+const ProtectedPage: React.FC = () => {
+  return (
+    <IonPage>
+      <IonContent>
+        <h1>Protected Content</h1>
+      </IonContent>
+    </IonPage>
+  );
+};
+
+export default withAuthenticationRequired(ProtectedPage, {
+  onRedirecting: () => (
+    <IonPage>
+      <IonContent className="ion-text-center ion-padding">
+        <IonSpinner />
+      </IonContent>
+    </IonPage>
+  ),
+});
+```
+
+### Route Setup with IonReactRouter
+
+```tsx
+import { Route, Redirect } from 'react-router-dom';
+import { IonRouterOutlet } from '@ionic/react';
+import { IonReactRouter } from '@ionic/react-router';
+
+import HomePage from './pages/Home';
+import ProtectedPage from './pages/Protected';
+
+<IonReactRouter>
+  <IonRouterOutlet>
+    <Route exact path="/home" component={HomePage} />
+    <Route exact path="/protected" component={ProtectedPage} />
+    <Redirect exact from="/" to="/home" />
+  </IonRouterOutlet>
+</IonReactRouter>
+```
+
+## Accessing API Tokens
+
+```tsx
+import { useAuth0 } from '@auth0/auth0-react';
+
+const ApiCaller: React.FC = () => {
+  const { getAccessTokenSilently } = useAuth0();
+
+  const callApi = async () => {
+    const token = await getAccessTokenSilently({
+      authorizationParams: {
+        audience: "https://api.example.com/",
+        scope: "read:data",
+      }
+    });
+
+    const response = await fetch("https://api.example.com/data", {
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+    });
+
+    return response.json();
+  };
+
+  // ...
+};
+```
+
+To use API tokens, configure the `audience` in Auth0Provider:
+
+```tsx
+<Auth0Provider
+  domain={domain}
+  clientId={clientId}
+  useRefreshTokens={true}
+  useRefreshTokensFallback={false}
+  authorizationParams={{
+    redirect_uri: callbackUri,
+    audience: "https://api.example.com/",
+  }}
+>
+```
+
+## Conditional Login/Logout UI
+
+```tsx
+import React from 'react';
+import { useAuth0 } from '@auth0/auth0-react';
+import { Browser } from '@capacitor/browser';
+import { IonButton } from '@ionic/react';
+
+const AuthButton: React.FC = () => {
+  const { isAuthenticated, loginWithRedirect, logout } = useAuth0();
+
+  const domain = "your-tenant.auth0.com";
+  const packageId = "com.example.myapp";
+  const callbackUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;
+
+  if (isAuthenticated) {
+    return (
+      <IonButton onClick={() => logout({
+        logoutParams: { returnTo: callbackUri },
+        async openUrl(url) {
+          await Browser.open({ url, windowName: "_self" });
+        }
+      })}>
+        Log out
+      </IonButton>
+    );
+  }
+
+  return (
+    <IonButton onClick={() => loginWithRedirect({
+      async openUrl(url) {
+        await Browser.open({ url, windowName: "_self" });
+      }
+    })}>
+      Log in
+    </IonButton>
+  );
+};
+
+export default AuthButton;
+```
+
+## Organizations Support
+
+```tsx
+await loginWithRedirect({
+  authorizationParams: {
+    organization: "org_abc123",
+  },
+  async openUrl(url) {
+    await Browser.open({ url, windowName: "_self" });
+  }
+});
+```
+
+To accept an organization invitation:
+
+```tsx
+await loginWithRedirect({
+  authorizationParams: {
+    organization: "org_abc123",
+    invitation: "inv_xyz789",
+  },
+  async openUrl(url) {
+    await Browser.open({ url, windowName: "_self" });
+  }
+});
+```
+
+## Error Handling
+
+```tsx
+import { useAuth0 } from '@auth0/auth0-react';
+
+const App: React.FC = () => {
+  const { error, isLoading } = useAuth0();
+
+  if (isLoading) {
+    return <IonSpinner />;
+  }
+
+  if (error) {
+    return (
+      <IonCard color="danger">
+        <IonCardContent>
+          <h2>Authentication Error</h2>
+          <p>{error.message}</p>
+        </IonCardContent>
+      </IonCard>
+    );
+  }
+
+  return <App />;
+};
+```
+
+### Common Error Types
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `login_required` | Session expired or not authenticated | Re-trigger `loginWithRedirect()` |
+| `consent_required` | User hasn't consented to requested scopes | Re-trigger login with `prompt: 'consent'` |
+| `invalid_grant` | Refresh token expired or revoked | Clear session and re-authenticate |
+| `access_denied` | User denied consent or rule blocked access | Check Auth0 Actions/Rules for blocks |
+| `mfa_required` | MFA is required for the user | Handle MFA enrollment flow |
+
+## Testing Patterns
+
+### Physical Device Testing
+
+Always test authentication flows on a physical device. Simulators and emulators may not correctly handle deep link callbacks or system browser interactions. To test on a physical device:
+
+```bash
+ionic build
+npx cap sync
+npx cap open ios   # Build and run on device from Xcode
+npx cap open android  # Build and run on device from Android Studio
+```
+
+### Manual Testing Flow
+
+1. Run `ionic serve` for browser testing (limited — deep links won't work)
+2. Build and deploy to a physical device:
+   ```bash
+   ionic build
+   npx cap sync
+   npx cap open ios   # or: npx cap open android
+   ```
+3. Build and run from Xcode/Android Studio on a physical device
+4. Tap Login → should open system browser
+5. Authenticate → should return to app with user data
+6. Tap Logout → should clear session and redirect back
+
+---
+
+# Auth0 Ionic React (Capacitor) — Setup Guide
+
+## Auth0 Configuration
+
+> **Agent instruction:**
+>
+> **IMPORTANT — Never display credentials:** After obtaining credentials from the CLI or user input, write them directly into config files. Do NOT echo, print, or display the domain, client ID, or any credential values in conversation output.
+>
+> Always ask the user to choose between automatic and manual setup using `AskUserQuestion`:
+> _"How would you like to configure Auth0 for this Ionic React project?"_
+>   - **Automatic setup (Recommended)** — uses the Auth0 CLI to create a Native application, configure callback URLs, and store credentials in the project config files automatically
+>   - **Manual setup** — you provide an existing `.env` file or Auth0 credentials (domain, client ID) and the agent writes them to the project config
+
+### Automatic Setup (Auth0 CLI)
+
+> **Agent instruction:** Run these pre-flight checks before creating the Auth0 application. Do NOT run `auth0 login` from the agent — it is interactive and will hang.
+>
+> 1. **Check Auth0 CLI**: `command -v auth0`. If missing, install it: `brew install auth0/auth0-cli/auth0`.
+> 2. **Check Auth0 login**: `auth0 tenants list --csv --no-input 2>&1`. If it fails or returns empty:
+>    - Tell the user: _"Please run `auth0 login` in your terminal and let me know when done."_
+>    - Wait for confirmation, then re-run the check. Retry up to 3 times before treating as a persistent failure.
+> 3. **Confirm active tenant**: Parse the `→` line from the CSV output. Tell the user: _"Your active Auth0 tenant is: `<domain>`. Is this correct?"_
+>    - If no, ask the user to run `auth0 tenants use <tenant-domain>`, then re-run step 2.
+>
+> Once confirmed, run the following steps:
+>
+> **Step A — Detect package ID:**
+> Read `capacitor.config.ts` (or `capacitor.config.json`) and extract the `appId` field (e.g., `com.example.myapp`).
+>
+> **Step B — Create Native application:**
+> ```bash
+> auth0 apps create \
+>   --name "APP_NAME" \
+>   --type native \
+>   --auth-method None \
+>   --callbacks "PACKAGE_ID://DOMAIN/capacitor/PACKAGE_ID/callback" \
+>   --logout-urls "PACKAGE_ID://DOMAIN/capacitor/PACKAGE_ID/callback" \
+>   --origins "capacitor://localhost,http://localhost" \
+>   --json \
+>   --no-input
+> ```
+> Parse the JSON output to extract `client_id` and `domain` (the tenant domain).
+>
+> **Step C — Write credentials to config files (never display them):**
+> Write the `client_id` and `domain` from Step B directly into the project `.env` file. Detect whether the project uses Vite (`VITE_` prefix) or CRA (`REACT_APP_` prefix) and use the appropriate variable names. **Do NOT echo, print, or display the domain, client ID, or any credential values in your conversation output.** Simply confirm that the Auth0 app was created and credentials were saved, without showing the actual values.
+>
+> If any CLI command fails due to session expiry, ask the user to run `auth0 login` again, then retry. Retry up to 3 times.
+> Only if the CLI keeps failing after retries: fall back to **Manual Setup** below.
+
+### Manual Setup (User-Provided Configuration)
+
+> **Agent instruction:** Ask the user to provide their Auth0 configuration. Accept either:
+> - **An `.env` file path** — read the file to extract the Auth0 domain and client ID, then copy or reference it in the project.
+> - **Direct credentials** — ask using `AskUserQuestion`: _"Please provide your Auth0 Domain and Client ID."_
+>
+> Once credentials are obtained, write them to the project `.env` file. Detect whether the project uses Vite (`VITE_` prefix) or CRA (`REACT_APP_` prefix) and use the appropriate variable names. **Do NOT display the credentials in conversation output.**
+
+### Callback URL Format
+
+| Field | Value |
+|-------|-------|
+| **Allowed Callback URLs** | `YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback` |
+| **Allowed Logout URLs** | `YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback` |
+| **Allowed Web Origins** | `capacitor://localhost, http://localhost` |
+
+Replace `YOUR_PACKAGE_ID` with your app's package ID (e.g., `com.example.myapp`) and `YOUR_DOMAIN` with your Auth0 domain. These are set automatically when using the CLI commands above.
+
+## SDK Installation
+
+```bash
+npm install @auth0/auth0-react @capacitor/browser @capacitor/app
+npx cap sync
+```
+
+### Plugin purposes
+
+| Package | Purpose |
+|---------|---------|
+| `@auth0/auth0-react` | Auth0 React SDK — provides `Auth0Provider` and `useAuth0` hook |
+| `@capacitor/browser` | Opens Auth0 Universal Login in system browser (SFSafariViewController / Chrome Custom Tabs) |
+| `@capacitor/app` | Handles deep link callbacks from Auth0 after login/logout |
+
+## Post-Setup Steps
+
+### 1. Verify Capacitor Configuration
+
+Ensure `capacitor.config.ts` has the correct `appId`:
+
+```typescript
+import type { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'com.example.myapp', // Must match YOUR_PACKAGE_ID in callback URLs
+  appName: 'My App',
+  webDir: 'dist',
+  server: {
+    androidScheme: 'https'
+  }
+};
+
+export default config;
+```
+
+### 2. Sync Native Projects
+
+After installing plugins, always sync:
+
+```bash
+npx cap sync
+```
+
+### 3. Verify Platform Setup
+
+**iOS:** Open the iOS project to verify:
+```bash
+npx cap open ios
+```
+Ensure the Bundle Identifier in Xcode matches `appId` in `capacitor.config.ts`.
+
+**Android:** Open the Android project to verify:
+```bash
+npx cap open android
+```
+Ensure `applicationId` in `android/app/build.gradle` matches `appId` in `capacitor.config.ts`.
+
+## Secret Management
+
+**Ionic React + Capacitor apps are Native applications** — they do not use a client secret. Instead, use PKCE (Proof Key for Code Exchange) with a custom URL scheme callback (e.g. `YOUR_PACKAGE_ID://your-tenant.auth0.com/capacitor/YOUR_PACKAGE_ID/callback`) to complete the login flow securely.
+
+- Configuration contains only: **Domain**, **Client ID**, and **Callback URL**
+- These values are not secrets and can be included in source code
+- Token validation uses PKCE (Proof Key for Code Exchange) — no client secret needed
+- Never include a client secret in a mobile/native application
+
+### Environment Variables (Optional)
+
+If you prefer environment variables for Domain and Client ID during development:
+
+```bash
+# .env (for Vite-based Ionic projects)
+VITE_AUTH0_DOMAIN=your-tenant.auth0.com
+VITE_AUTH0_CLIENT_ID=your-client-id
+
+# .env (for CRA-based Ionic projects)
+REACT_APP_AUTH0_DOMAIN=your-tenant.auth0.com
+REACT_APP_AUTH0_CLIENT_ID=your-client-id
+```
+
+Then reference in code:
+```tsx
+<Auth0Provider
+  domain={import.meta.env.VITE_AUTH0_DOMAIN}
+  clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
+  // ...
+>
+```
+
+## Verification
+
+After setup, verify the configuration:
+
+1. Run `ionic serve` — the app should load without Auth0 errors
+2. Run `ionic build && npx cap sync` — native projects should sync cleanly
+3. Open in Xcode/Android Studio and build — no missing plugin errors
+4. Tap login — system browser should open Auth0 Universal Login
+5. After login — app should receive the deep link callback and show the user profile
diff --git a/main/.mintlify/skills/auth0/references/framework-ionic-vue/index.md b/main/.mintlify/skills/auth0/references/framework-ionic-vue/index.md
new file mode 100644
index 0000000000..a62b36e470
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-ionic-vue/index.md
@@ -0,0 +1,1263 @@
+
+# Auth0 Ionic Vue (Capacitor) Integration
+
+Add Auth0 authentication to Ionic Vue applications using Capacitor. This skill covers native mobile authentication using the `@auth0/auth0-vue` SDK combined with `@capacitor/browser` and `@capacitor/app` plugins for deep link handling on iOS and Android.
+
+## Critical rules
+
+- **IMPORTANT — never display credentials.** After obtaining the domain, client ID, or any credential value from the CLI or user input, write them directly into config files. Do not echo, print, or display them in conversation output.
+
+## Prerequisites
+
+- Node.js 18+
+- Ionic CLI (`npm install -g @ionic/cli`)
+- An existing Ionic Vue application with Capacitor configured
+- Auth0 account and tenant
+- For iOS: Xcode 14+ and CocoaPods
+- For Android: Android Studio with API level 21+
+- Auth0 CLI — `brew install auth0/auth0-cli/auth0`
+
+## When NOT to Use
+
+| Use Case | Use Instead |
+|----------|------------------|
+| Vue SPA (no Capacitor/Ionic) | the Auth0 integration workflow for Vue |
+| React SPA (no Capacitor/Ionic) | the Auth0 integration workflow for React |
+| React Native (bare CLI) | the Auth0 integration workflow for React Native |
+| Expo (React Native) | the Auth0 integration workflow for Expo |
+| Ionic + React + Capacitor | the Auth0 integration workflow for Ionic React |
+| Ionic + Angular + Capacitor | the Auth0 integration workflow for Ionic Angular |
+| Next.js (server-side) | the Auth0 integration workflow for Next.js |
+| Nuxt (server-side) | the Auth0 integration workflow for Nuxt |
+| iOS native (Swift) | the Auth0 integration workflow for iOS (Swift) |
+| Android native (Kotlin) | the Auth0 integration workflow for Android (Kotlin) |
+
+## Quick Start Workflow
+
+### Step 1: Configure Auth0
+
+**For automated setup with Auth0 CLI**, see the Setup Guide section (below) for complete scripts.
+
+**For manual setup**, configure a **Native** application in the [Auth0 Dashboard](https://manage.auth0.com/) and note your Domain and Client ID.
+
+### Step 2: Install Dependencies
+
+```bash
+npm install @auth0/auth0-vue @capacitor/browser @capacitor/app
+npx cap sync
+```
+
+### Step 3: Set Up Auth0 Plugin
+
+> **Agent instruction:** If Step 1 already wrote `.env` and updated `src/main.ts`, verify the configuration looks correct and skip to Step 4. Only use the template below if configuring manually.
+
+Register the Auth0 Vue plugin in your app entry point (`src/main.ts`), configuring it for Capacitor. Credentials are read from `.env` via `import.meta.env`:
+
+```typescript
+import { createApp } from 'vue';
+import { createAuth0 } from '@auth0/auth0-vue';
+import { IonicVue } from '@ionic/vue';
+import App from './App.vue';
+import router from './router';
+
+// Agent: read appId from capacitor.config.ts and replace this value
+const packageId = "YOUR_PACKAGE_ID";
+
+const app = createApp(App);
+
+app.use(IonicVue);
+app.use(router);
+app.use(
+  createAuth0({
+    domain: import.meta.env.VITE_AUTH0_DOMAIN,
+    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+    useRefreshTokens: true,
+    useRefreshTokensFallback: false,
+    authorizationParams: {
+      redirect_uri: `${packageId}://${import.meta.env.VITE_AUTH0_DOMAIN}/capacitor/${packageId}/callback`
+    }
+  })
+);
+
+router.isReady().then(() => {
+  app.mount('#app');
+});
+```
+
+### Step 4: Implement Login with Capacitor Browser
+
+```vue
+<script setup lang="ts">
+import { useAuth0 } from '@auth0/auth0-vue';
+import { Browser } from '@capacitor/browser';
+import { IonButton } from '@ionic/vue';
+
+const { loginWithRedirect } = useAuth0();
+
+const login = async () => {
+  await loginWithRedirect({
+    async openUrl(url: string) {
+      await Browser.open({ url, windowName: "_self" });
+    }
+  });
+};
+</script>
+
+<template>
+  <ion-button @click="login">Log in</ion-button>
+</template>
+```
+
+### Step 5: Handle Callback via Deep Link
+
+Handle the deep link callback in your App.vue component. This must run on app initialization:
+
+```vue
+<script setup lang="ts">
+import { onMounted, onUnmounted } from 'vue';
+import { useAuth0 } from '@auth0/auth0-vue';
+import { App as CapApp } from '@capacitor/app';
+import { Browser } from '@capacitor/browser';
+import { IonApp, IonRouterOutlet } from '@ionic/vue';
+
+const { handleRedirectCallback } = useAuth0();
+
+let urlOpenListener: any;
+
+onMounted(async () => {
+  urlOpenListener = await CapApp.addListener('appUrlOpen', async ({ url }) => {
+    if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
+      await handleRedirectCallback(url);
+    }
+    await Browser.close();
+  });
+});
+
+onUnmounted(() => {
+  urlOpenListener?.remove();
+});
+</script>
+
+<template>
+  <ion-app>
+    <ion-router-outlet />
+  </ion-app>
+</template>
+```
+
+### Step 6: Implement Logout
+
+```vue
+<script setup lang="ts">
+import { useAuth0 } from '@auth0/auth0-vue';
+import { Browser } from '@capacitor/browser';
+import { IonButton } from '@ionic/vue';
+
+const domain = import.meta.env.VITE_AUTH0_DOMAIN;
+// Agent: read appId from capacitor.config.ts and replace this value
+const packageId = "YOUR_PACKAGE_ID";
+const logoutUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;
+
+const { logout } = useAuth0();
+
+const doLogout = async () => {
+  await logout({
+    logoutParams: {
+      returnTo: logoutUri
+    },
+    async openUrl(url: string) {
+      await Browser.open({ url, windowName: "_self" });
+    }
+  });
+};
+</script>
+
+<template>
+  <ion-button @click="doLogout">Log out</ion-button>
+</template>
+```
+
+### Step 7: Build and Test
+
+> **Agent instruction:** After integration, verify the build:
+> ```bash
+> ionic build
+> npx cap sync
+> ```
+> For iOS: `npx cap open ios` then build in Xcode.
+> For Android: `npx cap open android` then build in Android Studio.
+> If the build fails, iterate up to 5-6 times to fix issues. If still failing, use `AskUserQuestion` to request help.
+
+## Detailed Documentation
+
+- **Setup Guide** (see below) — Auth0 CLI automated setup (login, app creation, credential injection), Capacitor URL scheme registration, secret management
+- **Integration Patterns** (see below) — Login/logout with Capacitor Browser, deep link callback handling, user profile, protected routes, token access, error handling
+- **Testing & Reference** (see below) — Full API reference for createAuth0 options, useAuth0 composable, Capacitor plugin configuration, testing checklist, common issues
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| App type not set to **Native** in Auth0 Dashboard | Change application type to "Native" in Dashboard settings |
+| Missing or incorrect callback URL format | Use `YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback` — must match exactly |
+| Not enabling refresh tokens | Set `useRefreshTokens: true` and `useRefreshTokensFallback: false` in `createAuth0()` |
+| Missing `@capacitor/browser` or `@capacitor/app` | Install both: `npm install @capacitor/browser @capacitor/app && npx cap sync` |
+| Not handling deep link callback | Add `CapApp.addListener('appUrlOpen', ...)` to process Auth0 redirect |
+| Forgetting `npx cap sync` after install | Always run `npx cap sync` after installing Capacitor plugins |
+| Using `window.location.origin` as redirect URI | Use the custom URL scheme (`packageId://domain/...`), not `http://localhost` |
+| Missing Allowed Origins in Dashboard | Add `capacitor://localhost, http://localhost` to Allowed Origins |
+| Not calling `app.use(createAuth0(...))` before mount | Register Auth0 plugin before calling `app.mount('#app')` |
+| Accessing `.value` incorrectly on auth refs | `useAuth0()` returns Vue refs — use `.value` in `<script>`, template unwraps automatically |
+| localStorage treated as persistent on mobile | Use refresh tokens (`useRefreshTokens: true`) for reliable token persistence |
+
+## WebAuth Method
+
+This SDK uses Auth0's Universal Login (WebAuth) via the Capacitor Browser plugin. The `loginWithRedirect()` method opens the Auth0 authorization endpoint in a system browser (SFSafariViewController on iOS, Chrome Custom Tabs on Android). After authentication, Auth0 redirects back to the app using a native callback URL with a custom scheme: `{packageId}://{domain}/capacitor/{packageId}/callback`. The `@capacitor/app` plugin captures this deep link, and `handleRedirectCallback(url)` processes the authorization code exchange.
+
+Unlike standard native SDKs that use `https://{domain}/android/{packageId}/callback` or `https://{domain}/ios/{bundleId}/callback`, Ionic Capacitor apps use the Capacitor-specific callback path with the package ID as the URL scheme.
+
+## Related Skills
+
+All of this lives in the one `auth0` skill — just describe what you need (e.g. "add MFA", "protect my API").
+
+## Quick Reference
+
+| API | Description |
+|-----|-------------|
+| `createAuth0(options)` | Vue plugin factory — registers Auth0 with `app.use()` |
+| `useAuth0()` | Composable — returns `{ isLoading, isAuthenticated, user, loginWithRedirect, logout, getAccessTokenSilently, handleRedirectCallback, error }` |
+| `loginWithRedirect({ openUrl })` | Login via Universal Login — use `Browser.open()` in `openUrl` callback |
+| `logout({ logoutParams, openUrl })` | Logout — use `Browser.open()` in `openUrl` callback |
+| `handleRedirectCallback(url)` | Process Auth0 callback URL from deep link |
+| `getAccessTokenSilently()` | Get access token (uses refresh tokens on mobile) |
+| `createAuthGuard(app)` | Vue Router navigation guard factory for protected routes |
+| `Browser.open({ url })` | Capacitor — opens URL in system browser (SFSafariViewController / Chrome Custom Tabs) |
+| `CapApp.addListener('appUrlOpen', cb)` | Capacitor — listens for deep link events |
+| `Browser.close()` | Capacitor — closes the in-app browser after callback |
+
+## References
+
+- [Auth0 Ionic Vue Quickstart](https://auth0.com/docs/quickstart/native/ionic-vue/interactive)
+- [Auth0 Vue SDK GitHub](https://github.com/auth0/auth0-vue)
+- [Auth0 Vue SDK API Reference](https://auth0.github.io/auth0-vue/)
+- [Ionic Vue Capacitor Sample App](https://github.com/auth0-samples/auth0-ionic-samples/tree/main/vue)
+- [Capacitor Browser Plugin](https://capacitorjs.com/docs/apis/browser)
+- [Capacitor App Plugin](https://capacitorjs.com/docs/apis/app)
+- [Auth0 Dashboard](https://manage.auth0.com/)
+
+---
+
+# Auth0 Ionic Vue (Capacitor) — API Reference & Testing
+
+## createAuth0 Configuration
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `domain` | `string` | Yes | — | Auth0 tenant domain (e.g., `your-tenant.auth0.com`) |
+| `clientId` | `string` | Yes | — | Auth0 application Client ID |
+| `useRefreshTokens` | `boolean` | Yes (for Capacitor) | `false` | Must be `true` for native mobile — uses refresh tokens instead of iframe |
+| `useRefreshTokensFallback` | `boolean` | Yes (for Capacitor) | `true` | Must be `false` for native mobile — disables iframe fallback |
+| `authorizationParams.redirect_uri` | `string` | Yes | — | Custom scheme callback URL: `{packageId}://{domain}/capacitor/{packageId}/callback` |
+| `authorizationParams.audience` | `string` | No | — | API identifier for access token audience |
+| `authorizationParams.scope` | `string` | No | `openid profile email` | OAuth scopes to request |
+| `cacheLocation` | `string` | No | `memory` | Token cache location: `memory` or `localstorage` |
+
+### Capacitor-Specific Configuration
+
+```typescript
+app.use(
+  createAuth0({
+    domain: "your-tenant.auth0.com",
+    clientId: "your-client-id",
+    useRefreshTokens: true,
+    useRefreshTokensFallback: false,
+    authorizationParams: {
+      redirect_uri: "com.example.myapp://your-tenant.auth0.com/capacitor/com.example.myapp/callback"
+    }
+  })
+);
+```
+
+## useAuth0() Composable
+
+```typescript
+const {
+  isLoading,              // Ref<boolean> — true while SDK initializes
+  isAuthenticated,        // Ref<boolean> — true if user has valid session
+  user,                   // Ref<User | undefined> — authenticated user profile
+  error,                  // Ref<Error | undefined> — last authentication error
+  loginWithRedirect,      // (options?) => Promise<void>
+  logout,                 // (options?) => Promise<void>
+  getAccessTokenSilently, // (options?) => Promise<string>
+  getAccessTokenWithPopup, // (options?) => Promise<string> (not for Capacitor)
+  handleRedirectCallback, // (url?) => Promise<RedirectLoginResult>
+  idTokenClaims,          // Ref<IdToken | undefined> — raw ID token claims
+  checkSession,           // () => Promise<void> — refresh authentication state
+} = useAuth0();
+```
+
+**Note:** All reactive properties (`isLoading`, `isAuthenticated`, `user`, `error`, `idTokenClaims`) are Vue `Ref` objects. Access their values with `.value` in `<script>` blocks; templates unwrap refs automatically.
+
+## loginWithRedirect Options (Capacitor)
+
+```typescript
+await loginWithRedirect({
+  // Required for Capacitor: opens URL in system browser
+  async openUrl(url: string) {
+    await Browser.open({ url, windowName: "_self" });
+  },
+  // Optional: additional authorization params
+  authorizationParams: {
+    audience: "https://api.example.com/",
+    scope: "openid profile email read:data",
+    organization: "org_abc123",
+    invitation: "inv_xyz789",
+  }
+});
+```
+
+## logout Options (Capacitor)
+
+```typescript
+await logout({
+  logoutParams: {
+    returnTo: "com.example.myapp://your-tenant.auth0.com/capacitor/com.example.myapp/callback"
+  },
+  async openUrl(url: string) {
+    await Browser.open({ url, windowName: "_self" });
+  }
+});
+```
+
+## getAccessTokenSilently Options
+
+```typescript
+const token = await getAccessTokenSilently({
+  authorizationParams: {
+    audience: "https://api.example.com/",
+    scope: "read:data",
+  }
+});
+
+// Use token in API calls
+const response = await fetch("https://api.example.com/data", {
+  headers: { Authorization: `Bearer ${token}` }
+});
+```
+
+## createAuthGuard
+
+Factory function that creates a Vue Router navigation guard for protected routes:
+
+```typescript
+import { createAuthGuard } from '@auth0/auth0-vue';
+import type { App } from 'vue';
+
+// In router setup (needs app instance)
+export function setupRouter(app: App) {
+  const router = createRouter({
+    history: createWebHistory(),
+    routes: [
+      {
+        path: '/profile',
+        component: () => import('../views/Profile.vue'),
+        beforeEnter: createAuthGuard(app)
+      }
+    ]
+  });
+  return router;
+}
+```
+
+## Claims Reference
+
+| Claim | Source | Description |
+|-------|--------|-------------|
+| `sub` | ID Token | User identifier (e.g., `auth0\|abc123`) |
+| `name` | ID Token | User's full name |
+| `email` | ID Token | User's email address |
+| `email_verified` | ID Token | Whether email has been verified |
+| `picture` | ID Token | URL to user's profile picture |
+| `nickname` | ID Token | User's nickname |
+| `updated_at` | ID Token | Last profile update timestamp |
+| `org_id` | ID Token | Organization ID (when using Organizations) |
+| `permissions` | Access Token | RBAC permissions array (when API has RBAC enabled) |
+
+## Capacitor Plugin Configuration
+
+### capacitor.config.ts
+
+```typescript
+import type { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'com.example.myapp',
+  appName: 'My App',
+  webDir: 'dist',  // Ionic Vue with Vite uses 'dist'
+  server: {
+    androidScheme: 'https'
+  }
+};
+
+export default config;
+```
+
+### iOS: URL Scheme Registration
+
+Add a custom URL scheme to `ios/App/App/Info.plist` so iOS can route the Auth0 callback deep link back to the app:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>YOUR_PACKAGE_ID</string>
+    </array>
+  </dict>
+</array>
+```
+
+Replace `YOUR_PACKAGE_ID` with the `appId` from `capacitor.config.ts` (e.g., `com.example.myapp`).
+
+### Android: URL Scheme Registration
+
+Add an intent filter to `android/app/src/main/AndroidManifest.xml` inside the main `<activity>` to handle the custom scheme callback:
+
+```xml
+<intent-filter>
+  <action android:name="android.intent.action.VIEW" />
+  <category android:name="android.intent.category.DEFAULT" />
+  <category android:name="android.intent.category.BROWSABLE" />
+  <data android:scheme="YOUR_PACKAGE_ID" />
+</intent-filter>
+```
+
+Replace `YOUR_PACKAGE_ID` with the `appId` from `capacitor.config.ts`. Ensure the `appId` matches the `applicationId` in `android/app/build.gradle`.
+
+## Auth0 Dashboard Configuration
+
+### Callback URLs
+
+```text
+YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback
+```
+
+Example: `com.example.myapp://your-tenant.auth0.com/capacitor/com.example.myapp/callback`
+
+### Logout URLs
+
+Same as callback URL:
+```text
+YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback
+```
+
+### Allowed Origins
+
+```text
+capacitor://localhost, http://localhost
+```
+
+## Testing Checklist
+
+- [ ] Auth0 plugin registered with `app.use(createAuth0({...}))` with correct domain and clientId
+- [ ] `useRefreshTokens: true` and `useRefreshTokensFallback: false` are set
+- [ ] `redirect_uri` uses custom scheme format (`packageId://domain/capacitor/packageId/callback`)
+- [ ] Login opens system browser (SFSafariViewController on iOS, Chrome Custom Tabs on Android)
+- [ ] Deep link callback is handled via `CapApp.addListener('appUrlOpen', ...)`
+- [ ] `handleRedirectCallback(url)` is called when URL contains `state` and `code`/`error`
+- [ ] `Browser.close()` is called after handling callback
+- [ ] Logout redirects back to app via custom scheme
+- [ ] `getAccessTokenSilently()` works with refresh tokens
+- [ ] User profile data is accessible via `useAuth0().user`
+- [ ] `npx cap sync` has been run after installing Capacitor plugins
+- [ ] Auth0 Dashboard has correct Callback URLs, Logout URLs, and Allowed Origins
+- [ ] Application type is set to "Native" in Auth0 Dashboard
+- [ ] Vue refs are accessed with `.value` in script, template unwraps automatically
+
+## Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Login opens but never returns to app | Callback URL mismatch or missing deep link handler | Verify callback URL in Dashboard matches `redirect_uri`; ensure `appUrlOpen` listener is registered |
+| `handleRedirectCallback` not called | Deep link listener not set up or URL check is wrong | Verify `CapApp.addListener('appUrlOpen', ...)` runs in `onMounted` |
+| Token refresh fails silently | `useRefreshTokens` not enabled | Set `useRefreshTokens: true` in `createAuth0()` |
+| iframe fallback error on mobile | `useRefreshTokensFallback` not disabled | Set `useRefreshTokensFallback: false` in `createAuth0()` |
+| `Browser.open` does nothing | `@capacitor/browser` not installed or synced | Run `npm install @capacitor/browser && npx cap sync` |
+| App crashes on deep link | Missing `@capacitor/app` plugin | Run `npm install @capacitor/app && npx cap sync` |
+| CORS error during token exchange | Missing Allowed Origins in Auth0 Dashboard | Add `capacitor://localhost, http://localhost` to Allowed Origins |
+| `user` is `undefined` after login | Callback not processed before reading user | Wait for `isLoading.value === false` before accessing `user.value` |
+| SSO not working on iOS | SFSafariViewController doesn't share Safari cookies (iOS 11+) | Expected limitation — SSO across apps is not supported on iOS |
+| Auth plugin not found | `createAuth0()` not registered before mount | Call `app.use(createAuth0({...}))` before `app.mount('#app')` |
+| Composable returns undefined | `useAuth0()` called outside setup or before plugin registration | Ensure `useAuth0()` is called inside `<script setup>` or `setup()` of a component |
+
+## Security Considerations
+
+- **No client secret**: Native applications must not include a client secret. Use PKCE (Auth Code + PKCE) flow, which is the default.
+- **Refresh tokens**: Always enable `useRefreshTokens: true` for Capacitor apps. localStorage is transient on mobile.
+- **Token storage**: The SDK stores tokens in memory by default. On mobile, refresh tokens are the reliable mechanism for session persistence.
+- **Custom scheme validation**: The callback URL scheme must match the app's package/bundle ID exactly.
+- **HTTPS**: Capacitor uses HTTPS for Android by default (`androidScheme: 'https'` in config). Do not change this.
+
+---
+
+# Integration Patterns
+
+## Authentication Flow
+
+The Ionic Vue + Capacitor authentication flow:
+
+1. User taps "Login" button
+2. `loginWithRedirect()` is called with a custom `openUrl` that uses `Browser.open()`
+3. Capacitor Browser opens Auth0 Universal Login in a system browser (SFSafariViewController on iOS, Chrome Custom Tabs on Android)
+4. User authenticates with Auth0
+5. Auth0 redirects to the custom scheme callback URL (`packageId://domain/capacitor/packageId/callback`)
+6. Capacitor App plugin receives the deep link via `appUrlOpen` event
+7. `handleRedirectCallback(url)` processes the authorization code
+8. `Browser.close()` dismisses the system browser
+9. User is now authenticated — `isAuthenticated` is `true`, `user` is populated
+
+## Auth0 Plugin Setup
+
+Configure the Auth0 Vue plugin at your app's entry point (`src/main.ts`):
+
+```typescript
+import { createApp } from 'vue';
+import { createAuth0 } from '@auth0/auth0-vue';
+import { IonicVue } from '@ionic/vue';
+import App from './App.vue';
+import router from './router';
+
+const domain = "your-tenant.auth0.com";
+const clientId = "your-client-id";
+const packageId = "com.example.myapp";
+const callbackUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;
+
+const app = createApp(App);
+
+app.use(IonicVue);
+app.use(router);
+app.use(
+  createAuth0({
+    domain,
+    clientId,
+    useRefreshTokens: true,
+    useRefreshTokensFallback: false,
+    authorizationParams: {
+      redirect_uri: callbackUri
+    }
+  })
+);
+
+router.isReady().then(() => {
+  app.mount('#app');
+});
+```
+
+### Why These Options Are Required for Capacitor
+
+| Option | Value | Reason |
+|--------|-------|--------|
+| `useRefreshTokens` | `true` | Mobile apps cannot use iframe-based token renewal. Refresh tokens provide reliable session persistence. |
+| `useRefreshTokensFallback` | `false` | Prevents the SDK from attempting iframe fallback, which fails on native. |
+| `authorizationParams.redirect_uri` | Custom scheme URL | Native apps use a custom URL scheme, not `http://localhost`. |
+
+## Login Implementation
+
+```vue
+<script setup lang="ts">
+import { useAuth0 } from '@auth0/auth0-vue';
+import { Browser } from '@capacitor/browser';
+import { IonButton } from '@ionic/vue';
+
+const { loginWithRedirect } = useAuth0();
+
+const login = async () => {
+  await loginWithRedirect({
+    async openUrl(url: string) {
+      await Browser.open({
+        url,
+        windowName: "_self"
+      });
+    }
+  });
+};
+</script>
+
+<template>
+  <ion-button @click="login">Log in</ion-button>
+</template>
+```
+
+## Deep Link Callback Handling
+
+Handle the callback in your App.vue component. This must run on app initialization:
+
+```vue
+<script setup lang="ts">
+import { onMounted, onUnmounted } from 'vue';
+import { useAuth0 } from '@auth0/auth0-vue';
+import { App as CapApp } from '@capacitor/app';
+import { Browser } from '@capacitor/browser';
+import { IonApp, IonRouterOutlet } from '@ionic/vue';
+
+const { handleRedirectCallback } = useAuth0();
+
+let urlOpenListener: any;
+
+onMounted(async () => {
+  urlOpenListener = await CapApp.addListener('appUrlOpen', async ({ url }) => {
+    if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
+      await handleRedirectCallback(url);
+    }
+    await Browser.close();
+  });
+});
+
+onUnmounted(() => {
+  urlOpenListener?.remove();
+});
+</script>
+
+<template>
+  <ion-app>
+    <ion-router-outlet />
+  </ion-app>
+</template>
+```
+
+## Logout Implementation
+
+```vue
+<script setup lang="ts">
+import { useAuth0 } from '@auth0/auth0-vue';
+import { Browser } from '@capacitor/browser';
+import { IonButton } from '@ionic/vue';
+
+const domain = "your-tenant.auth0.com";
+const packageId = "com.example.myapp";
+const logoutUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;
+
+const { logout } = useAuth0();
+
+const doLogout = async () => {
+  await logout({
+    logoutParams: {
+      returnTo: logoutUri
+    },
+    async openUrl(url: string) {
+      await Browser.open({
+        url,
+        windowName: "_self"
+      });
+    }
+  });
+};
+</script>
+
+<template>
+  <ion-button @click="doLogout">Log out</ion-button>
+</template>
+```
+
+## User Profile Display
+
+```vue
+<script setup lang="ts">
+import { useAuth0 } from '@auth0/auth0-vue';
+import {
+  IonCard,
+  IonCardContent,
+  IonCardHeader,
+  IonCardTitle,
+  IonAvatar,
+  IonItem,
+  IonLabel,
+  IonSpinner
+} from '@ionic/vue';
+
+const { user, isLoading, isAuthenticated } = useAuth0();
+</script>
+
+<template>
+  <ion-spinner v-if="isLoading" />
+
+  <ion-card v-else-if="isAuthenticated && user">
+    <ion-card-header>
+      <ion-item lines="none">
+        <ion-avatar slot="start">
+          <img :src="user.picture" :alt="user.name" />
+        </ion-avatar>
+        <ion-label>
+          <ion-card-title>{{ user.name }}</ion-card-title>
+          <p>{{ user.email }}</p>
+        </ion-label>
+      </ion-item>
+    </ion-card-header>
+    <ion-card-content>
+      <pre>{{ JSON.stringify(user, null, 2) }}</pre>
+    </ion-card-content>
+  </ion-card>
+</template>
+```
+
+## Protected Routes
+
+Use Vue Router navigation guards with `createAuthGuard` to protect Ionic pages:
+
+```typescript
+// src/router/index.ts
+import { createRouter, createWebHistory } from '@ionic/vue-router';
+import { createAuthGuard } from '@auth0/auth0-vue';
+import type { App } from 'vue';
+
+export function setupRouter(app: App) {
+  const router = createRouter({
+    history: createWebHistory(import.meta.env.BASE_URL),
+    routes: [
+      {
+        path: '/',
+        redirect: '/home'
+      },
+      {
+        path: '/home',
+        component: () => import('../views/HomePage.vue')
+      },
+      {
+        path: '/profile',
+        component: () => import('../views/ProfilePage.vue'),
+        beforeEnter: createAuthGuard(app)
+      }
+    ]
+  });
+
+  return router;
+}
+```
+
+### Alternative: Component-Level Guard
+
+```vue
+<script setup lang="ts">
+import { watchEffect } from 'vue';
+import { useAuth0 } from '@auth0/auth0-vue';
+import { IonPage, IonContent, IonSpinner } from '@ionic/vue';
+
+const { isAuthenticated, isLoading, loginWithRedirect } = useAuth0();
+import { Browser } from '@capacitor/browser';
+
+watchEffect(() => {
+  if (!isLoading.value && !isAuthenticated.value) {
+    loginWithRedirect({
+      async openUrl(url: string) {
+        await Browser.open({ url, windowName: "_self" });
+      }
+    });
+  }
+});
+</script>
+
+<template>
+  <ion-page>
+    <ion-content v-if="isLoading" class="ion-text-center ion-padding">
+      <ion-spinner />
+    </ion-content>
+    <ion-content v-else-if="isAuthenticated">
+      <h1>Protected Content</h1>
+    </ion-content>
+  </ion-page>
+</template>
+```
+
+## Accessing API Tokens
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useAuth0 } from '@auth0/auth0-vue';
+
+const { getAccessTokenSilently } = useAuth0();
+const data = ref(null);
+const error = ref<string | null>(null);
+const loading = ref(false);
+
+const callApi = async () => {
+  loading.value = true;
+  error.value = null;
+
+  try {
+    const token = await getAccessTokenSilently({
+      authorizationParams: {
+        audience: "https://api.example.com/",
+        scope: "read:data",
+      }
+    });
+
+    const response = await fetch("https://api.example.com/data", {
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+    });
+
+    data.value = await response.json();
+  } catch (err: any) {
+    error.value = err.message;
+  } finally {
+    loading.value = false;
+  }
+};
+</script>
+
+<template>
+  <div>
+    <ion-button @click="callApi" :disabled="loading">
+      {{ loading ? 'Loading...' : 'Call API' }}
+    </ion-button>
+    <div v-if="error" class="error">{{ error }}</div>
+    <pre v-if="data">{{ JSON.stringify(data, null, 2) }}</pre>
+  </div>
+</template>
+```
+
+To use API tokens, configure the `audience` in the Auth0 plugin:
+
+```typescript
+app.use(
+  createAuth0({
+    domain,
+    clientId,
+    useRefreshTokens: true,
+    useRefreshTokensFallback: false,
+    authorizationParams: {
+      redirect_uri: callbackUri,
+      audience: "https://api.example.com/",
+    }
+  })
+);
+```
+
+## Conditional Login/Logout UI
+
+```vue
+<script setup lang="ts">
+import { useAuth0 } from '@auth0/auth0-vue';
+import { Browser } from '@capacitor/browser';
+import { IonButton } from '@ionic/vue';
+
+const { isAuthenticated, loginWithRedirect, logout } = useAuth0();
+
+const domain = "your-tenant.auth0.com";
+const packageId = "com.example.myapp";
+const callbackUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;
+
+const login = async () => {
+  await loginWithRedirect({
+    async openUrl(url: string) {
+      await Browser.open({ url, windowName: "_self" });
+    }
+  });
+};
+
+const doLogout = async () => {
+  await logout({
+    logoutParams: { returnTo: callbackUri },
+    async openUrl(url: string) {
+      await Browser.open({ url, windowName: "_self" });
+    }
+  });
+};
+</script>
+
+<template>
+  <ion-button v-if="isAuthenticated" @click="doLogout">Log out</ion-button>
+  <ion-button v-else @click="login">Log in</ion-button>
+</template>
+```
+
+## Organizations Support
+
+```typescript
+await loginWithRedirect({
+  authorizationParams: {
+    organization: "org_abc123",
+  },
+  async openUrl(url: string) {
+    await Browser.open({ url, windowName: "_self" });
+  }
+});
+```
+
+To accept an organization invitation:
+
+```typescript
+await loginWithRedirect({
+  authorizationParams: {
+    organization: "org_abc123",
+    invitation: "inv_xyz789",
+  },
+  async openUrl(url: string) {
+    await Browser.open({ url, windowName: "_self" });
+  }
+});
+```
+
+## Error Handling
+
+```vue
+<script setup lang="ts">
+import { useAuth0 } from '@auth0/auth0-vue';
+import { IonSpinner, IonCard, IonCardContent } from '@ionic/vue';
+
+const { error, isLoading } = useAuth0();
+</script>
+
+<template>
+  <ion-spinner v-if="isLoading" />
+
+  <ion-card v-else-if="error" color="danger">
+    <ion-card-content>
+      <h2>Authentication Error</h2>
+      <p>{{ error.message }}</p>
+    </ion-card-content>
+  </ion-card>
+
+  <slot v-else />
+</template>
+```
+
+### Common Error Types
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `login_required` | Session expired or not authenticated | Re-trigger `loginWithRedirect()` |
+| `consent_required` | User hasn't consented to requested scopes | Re-trigger login with `prompt: 'consent'` |
+| `invalid_grant` | Refresh token expired or revoked | Clear session and re-authenticate |
+| `access_denied` | User denied consent or rule blocked access | Check Auth0 Actions/Rules for blocks |
+| `mfa_required` | MFA is required for the user | Handle MFA enrollment flow |
+
+## Testing Patterns
+
+### Physical Device Testing
+
+Always test authentication flows on a physical device. Simulators and emulators may not correctly handle deep link callbacks or system browser interactions. To test on a physical device:
+
+```bash
+ionic build
+npx cap sync
+npx cap open ios   # Build and run on device from Xcode
+npx cap open android  # Build and run on device from Android Studio
+```
+
+### Manual Testing Flow
+
+1. Run `ionic serve` for browser testing (limited — deep links won't work)
+2. Build and deploy to a physical device:
+   ```bash
+   ionic build
+   npx cap sync
+   npx cap open ios   # or: npx cap open android
+   ```
+3. Build and run from Xcode/Android Studio on a physical device
+4. Tap Login → should open system browser
+5. Authenticate → should return to app with user data
+6. Tap Logout → should clear session and redirect back
+
+---
+
+# Auth0 Ionic Vue (Capacitor) — Setup Guide
+
+## Auth0 Configuration
+
+> **Agent instruction:**
+>
+> **Important — do not display credentials:** After obtaining credentials from the CLI or user input, write them directly into config files. Do not echo, print, or display the domain, client ID, or any credential values in conversation output.
+>
+> Always ask the user to choose between automatic and manual setup using `AskUserQuestion`:
+> _"How would you like to configure Auth0 for this Ionic Vue project?"_
+>   - **Automatic setup (Recommended)** — uses the Auth0 CLI to create a Native application, configure callback URLs, and store credentials in the project `.env` file automatically
+>   - **Manual setup** — you provide an existing `.env` file or Auth0 credentials (domain, client ID) and the agent writes them to the project config
+>
+> **If credentials are already provided in the user's prompt:** Use them directly — skip to "SDK Installation" below. Do NOT call `AskUserQuestion` to re-confirm.
+
+### Auth0 CLI Automated Setup
+
+> **Agent instruction:** Execute these steps in order. Do NOT run `auth0 login` from the agent — it is interactive and will hang. All other `auth0` CLI commands below are non-interactive and safe to run.
+>
+> ---
+>
+> #### Step A — Check Auth0 CLI is installed
+>
+> ```bash
+> command -v auth0
+> ```
+>
+> If missing, install it:
+> ```bash
+> brew install auth0/auth0-cli/auth0
+> ```
+> On Linux: `curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh`
+>
+> ---
+>
+> #### Step B — Verify Auth0 CLI login session
+>
+> ```bash
+> auth0 tenants list --csv --no-input 2>&1
+> ```
+>
+> - **If the command succeeds** and returns CSV output with tenant rows: proceed to Step C.
+> - **If the command fails** (exit code non-zero, or output contains "login" / "unauthorized" / is empty):
+>   - Tell the user: _"You're not logged in to the Auth0 CLI. Please run `auth0 login` in your terminal and let me know when done."_
+>   - Use `AskUserQuestion` to wait for confirmation.
+>   - After confirmation, re-run this check. Retry up to 3 times.
+>   - If still failing after 3 retries: use `AskUserQuestion` to ask the user for their Auth0 Domain and Client ID manually, then skip to Step F.
+>
+> ---
+>
+> #### Step C — Detect active Auth0 tenant domain
+>
+> Parse the CSV output from Step B. The active tenant line contains `→` (Unicode arrow U+2192).
+>
+> ```
+> Example output:
+>   ACTIVE,DOMAIN
+>   →,dev-example.us.auth0.com
+>     ,dev-other.us.auth0.com
+> ```
+>
+> Extract the domain from the second column of the `→` line (e.g., `dev-example.us.auth0.com`).
+>
+> Tell the user: _"Your active Auth0 tenant is: `<domain>`. Is this correct?"_
+> - If no, ask the user to run `auth0 tenants use <correct-tenant-domain>`, then re-run Step B.
+>
+> Store this as `AUTH0_DOMAIN`.
+>
+> ---
+>
+> #### Step D — Detect package ID from Capacitor config
+>
+> Read `capacitor.config.ts` (or `capacitor.config.json`) in the project root:
+>
+> - For `.ts`: parse `appId: 'com.example.myapp'` using regex.
+> - For `.json`: parse the `appId` field from JSON.
+>
+> Store this as `PACKAGE_ID` (e.g., `com.example.myapp`).
+>
+> Also extract `appName` if available (for the Auth0 app display name). Fall back to the project name from `package.json` if not found.
+>
+> ---
+>
+> #### Step E — Create Native Auth0 application
+>
+> Build the callback URL: `PACKAGE_ID://AUTH0_DOMAIN/capacitor/PACKAGE_ID/callback`
+>
+> ```bash
+> auth0 apps create \
+>   --name "APP_NAME" \
+>   --type native \
+>   --auth-method none \
+>   --callbacks "PACKAGE_ID://AUTH0_DOMAIN/capacitor/PACKAGE_ID/callback" \
+>   --logout-urls "PACKAGE_ID://AUTH0_DOMAIN/capacitor/PACKAGE_ID/callback" \
+>   --origins "capacitor://localhost,http://localhost" \
+>   --json \
+>   --no-input
+> ```
+>
+> Replace `APP_NAME`, `PACKAGE_ID`, and `AUTH0_DOMAIN` with the actual values from Steps C and D.
+>
+> **Parse the JSON output** to extract `client_id`. Example response:
+> ```json
+> {
+>   "client_id": "abc123def456...",
+>   "name": "my-app",
+>   "app_type": "native",
+>   ...
+> }
+> ```
+>
+> Store `client_id` as `AUTH0_CLIENT_ID`.
+>
+> If this command fails due to session expiry, ask the user to run `auth0 login` again and retry. Retry up to 3 times.
+>
+> ---
+>
+> #### Step F — Write `.env` with real credentials
+>
+> Write (or update) the `.env` file in the project root with the actual values from Steps C–E:
+>
+> ```bash
+> VITE_AUTH0_DOMAIN=AUTH0_DOMAIN
+> VITE_AUTH0_CLIENT_ID=AUTH0_CLIENT_ID
+> VITE_AUTH0_CALLBACK_URI=PACKAGE_ID://AUTH0_DOMAIN/capacitor/PACKAGE_ID/callback
+> ```
+>
+> Replace `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, and `PACKAGE_ID` with the actual values.
+>
+> - **If `.env` already exists:** Update or add these three variables without removing other existing variables.
+> - **If `.env` does not exist:** Create the file.
+> - **If `.gitignore` does not include `.env`:** Add `.env` to `.gitignore`.
+>
+> ---
+>
+> #### Step G — Update `src/main.ts` to use env vars
+>
+> Read `src/main.ts` and wire it to read credentials from `import.meta.env`:
+>
+> **If `createAuth0()` already exists in the file:**
+> - Replace any hardcoded `domain` value (e.g., `"YOUR_AUTH0_DOMAIN"` or a real domain string) with `import.meta.env.VITE_AUTH0_DOMAIN`.
+> - Replace any hardcoded `clientId` value with `import.meta.env.VITE_AUTH0_CLIENT_ID`.
+> - Replace the `redirect_uri` value with `` `${packageId}://${import.meta.env.VITE_AUTH0_DOMAIN}/capacitor/${packageId}/callback` `` (where `packageId` is read from the Capacitor config or hardcoded if it never changes).
+>
+> **If `createAuth0()` does NOT exist in the file:**
+> 1. Add the import: `import { createAuth0 } from '@auth0/auth0-vue';`
+> 2. Add the Auth0 plugin registration before `router.isReady()` or `app.mount()`:
+>    ```typescript
+>    const packageId = "PACKAGE_ID"; // From capacitor.config.ts appId
+>
+>    app.use(
+>      createAuth0({
+>        domain: import.meta.env.VITE_AUTH0_DOMAIN,
+>        clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+>        useRefreshTokens: true,
+>        useRefreshTokensFallback: false,
+>        authorizationParams: {
+>          redirect_uri: `${packageId}://${import.meta.env.VITE_AUTH0_DOMAIN}/capacitor/${packageId}/callback`
+>        }
+>      })
+>    );
+>    ```
+>
+> Replace `PACKAGE_ID` with the actual package ID from Step D.
+>
+> ---
+>
+> #### Step H — Confirm setup to user (never display credentials)
+>
+> After completing all steps, tell the user:
+> - _"Auth0 application created and configured successfully."_
+> - _"Credentials have been written to `.env` (`VITE_AUTH0_DOMAIN` and `VITE_AUTH0_CLIENT_ID`)."_
+> - _"`src/main.ts` reads credentials from `import.meta.env`."_
+>
+> **Do NOT display the actual domain, client ID, or callback URL values.** Only confirm that the setup succeeded and where the credentials were saved.
+>
+> If the CLI keeps failing after retries, fall back to **Manual Setup** below.
+
+### Manual Setup (User-Provided Configuration)
+
+> **Agent instruction:** Ask the user to provide their Auth0 configuration. Accept either:
+> - **An `.env` file path** — read the file to extract the Auth0 domain and client ID, then copy or reference it in the project.
+> - **Direct credentials** — ask using `AskUserQuestion`: _"Please provide your Auth0 Domain and Client ID."_
+>
+> Once credentials are obtained, write them to the project `.env` file using `VITE_AUTH0_DOMAIN` and `VITE_AUTH0_CLIENT_ID` variable names. **Do NOT display the credentials in conversation output.**
+
+### Callback URL Format
+
+| Field | Value |
+|-------|-------|
+| **Allowed Callback URLs** | `YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback` |
+| **Allowed Logout URLs** | `YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback` |
+| **Allowed Web Origins** | `capacitor://localhost, http://localhost` |
+
+Replace `YOUR_PACKAGE_ID` with your app's package ID (e.g., `com.example.myapp`) and `YOUR_DOMAIN` with your Auth0 domain. These are set automatically when using the CLI commands above.
+
+## SDK Installation
+
+```bash
+npm install @auth0/auth0-vue @capacitor/browser @capacitor/app
+npx cap sync
+```
+
+### Plugin purposes
+
+| Package | Purpose |
+|---------|---------|
+| `@auth0/auth0-vue` | Auth0 Vue SDK — provides `createAuth0` plugin and `useAuth0` composable |
+| `@capacitor/browser` | Opens Auth0 Universal Login in system browser (SFSafariViewController / Chrome Custom Tabs) |
+| `@capacitor/app` | Handles deep link callbacks from Auth0 after login/logout |
+
+## Post-Setup Steps
+
+### 1. Verify Capacitor Configuration
+
+Ensure `capacitor.config.ts` has the correct `appId`:
+
+```typescript
+import type { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'com.example.myapp', // Must match YOUR_PACKAGE_ID in callback URLs
+  appName: 'My App',
+  webDir: 'dist',
+  server: {
+    androidScheme: 'https'
+  }
+};
+
+export default config;
+```
+
+### 2. Sync Native Projects
+
+After installing plugins, always sync:
+
+```bash
+npx cap sync
+```
+
+### 3. Verify Platform Setup
+
+**iOS:** Open the iOS project to verify:
+```bash
+npx cap open ios
+```
+Ensure the Bundle Identifier in Xcode matches `appId` in `capacitor.config.ts`.
+
+**Android:** Open the Android project to verify:
+```bash
+npx cap open android
+```
+Ensure `applicationId` in `android/app/build.gradle` matches `appId` in `capacitor.config.ts`.
+
+## Secret Management
+
+**Ionic Vue + Capacitor apps are Native applications** — they do not use a client secret. Instead, use PKCE (Proof Key for Code Exchange) with a custom URL scheme callback (e.g. `YOUR_PACKAGE_ID://your-tenant.auth0.com/capacitor/YOUR_PACKAGE_ID/callback`) to complete the login flow securely.
+
+- Configuration contains only: **Domain**, **Client ID**, and **Callback URL**
+- These values are not secrets and can be included in source code
+- Token validation uses PKCE (Proof Key for Code Exchange) — no client secret needed
+- Never include a client secret in a mobile/native application
+
+### Environment Variables (Optional)
+
+If you prefer environment variables for Domain and Client ID during development:
+
+```bash
+# .env (for Vite-based Ionic Vue projects)
+VITE_AUTH0_DOMAIN=your-tenant.auth0.com
+VITE_AUTH0_CLIENT_ID=your-client-id
+```
+
+Then reference in code:
+```typescript
+app.use(
+  createAuth0({
+    domain: import.meta.env.VITE_AUTH0_DOMAIN,
+    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+    useRefreshTokens: true,
+    useRefreshTokensFallback: false,
+    authorizationParams: {
+      redirect_uri: `${packageId}://${import.meta.env.VITE_AUTH0_DOMAIN}/capacitor/${packageId}/callback`
+    }
+  })
+);
+```
+
+## Verification
+
+After setup, verify the configuration:
+
+1. Run `ionic serve` — the app should load without Auth0 errors
+2. Run `ionic build && npx cap sync` — native projects should sync cleanly
+3. Open in Xcode/Android Studio and build — no missing plugin errors
+4. Tap login — system browser should open Auth0 Universal Login
+5. After login — app should receive the deep link callback and show the user profile
diff --git a/main/.mintlify/skills/auth0/references/framework-java-mvc/index.md b/main/.mintlify/skills/auth0/references/framework-java-mvc/index.md
new file mode 100644
index 0000000000..28ffb98726
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-java-mvc/index.md
@@ -0,0 +1,1276 @@
+
+# Auth0 Java MVC Common Integration
+
+Add Auth0 authentication to Java Servlet web applications using `com.auth0:mvc-auth-commons`. Provides `AuthenticationController` for building authorize URLs and handling callbacks, with session-based authentication and support for Organizations and Multiple Custom Domains.
+
+> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
+> ```bash
+> gh api repos/auth0/auth0-java-mvc-common/releases/latest --jq '.tag_name'
+> ```
+> Use the returned version in all dependency lines instead of any hardcoded version below. If the API call fails, use `1.12.0`.
+
+## Prerequisites
+
+- Java 8+ (Java 17+ recommended)
+- Servlet container (Tomcat, Jetty, etc.) with javax.servlet 3+
+- Maven 3.6+ or Gradle 7+
+- Auth0 Regular Web Application configured
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+| Use Case | Recommended Skill |
+|----------|-------------------|
+| Spring Boot web applications with auto-configuration | Use Spring Boot + Okta starter for auto-configured Spring Boot login |
+| Spring Boot REST APIs (stateless JWT) | Use the Auth0 integration workflow for Spring Boot REST APIs (JWT Bearer token validation) |
+| Single Page Applications | Use the Auth0 integration workflow for React, Vue, or Angular for client-side auth |
+| Mobile applications | Use the Auth0 integration workflow for Android or Swift for native mobile |
+| Machine-to-machine API calls | Use Auth0 Management API SDK for server-to-server |
+
+## Quick Start Workflow
+
+> **Agent instruction:** Do not write or echo credential values (domain, client ID, client secret) yourself. If the user's prompt already provides Auth0 credentials, skip the credential questions and instruct the user to populate their `.env` file — provide the variable names and file path but use placeholders (`<YOUR_DOMAIN>`, `<YOUR_CLIENT_ID>`, `<YOUR_CLIENT_SECRET>`), never actual values. Never repeat credentials back in responses.
+
+> **Secret handling rules:**
+> - Never retrieve or parse `client_secret` from Auth0 CLI output.
+> - Never write actual credential values into any file using the Write or Edit tool — always use placeholders and instruct the user to substitute their real values.
+> - Do NOT read `.env` files (to avoid exposing existing secrets in context).
+> - Always ensure `.env` is in `.gitignore` — add the entry automatically if missing.
+
+### 1. Install SDK
+
+**Gradle (build.gradle):**
+
+```groovy
+implementation 'com.auth0:mvc-auth-commons:1.12.0'
+```
+
+**Maven (pom.xml):**
+
+```xml
+<dependency>
+    <groupId>com.auth0</groupId>
+    <artifactId>mvc-auth-commons</artifactId>
+    <version>1.12.0</version>
+</dependency>
+```
+
+### 2. Create Auth0 Application
+
+You need a **Regular Web Application** (not SPA or Native) in Auth0.
+
+> **STOP — ask the user before proceeding.**
+>
+> Ask exactly this question and wait for their answer before doing anything else:
+>
+> > "How would you like to create the Auth0 application?
+> > 1. **Automated** — I'll run Auth0 CLI commands that create the application and write the values to your config automatically.
+> > 2. **Manual** — You create the application yourself in the Auth0 Dashboard (or via `auth0 apps create`) and provide me the Domain, Client ID, and Client Secret.
+> >
+> > Which do you prefer? (1 = Automated / 2 = Manual)"
+>
+> Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.
+
+**If the user chose Automated**, follow the Setup Guide section below for the complete Auth0 CLI steps. The automated path writes configuration for you — skip Step 3 below and proceed directly to Step 4.
+
+**If the user chose Manual**, follow the Setup Guide section below (Manual Setup section). Then continue with Step 3.
+
+Quick reference for manual application creation:
+
+```bash
+# Using Auth0 CLI
+auth0 apps create \
+  --name "My Java Web App" \
+  --type regular \
+  --callbacks http://localhost:3000/callback \
+  --logout-urls http://localhost:3000
+```
+
+Or create manually in Auth0 Dashboard → Applications → Applications → Create Application → Regular Web Applications
+
+### 3. Configure Credentials
+
+Store credentials as environment variables (never hardcode in source):
+
+```bash
+export AUTH0_DOMAIN="your-tenant.auth0.com"
+export AUTH0_CLIENT_ID="your-client-id"
+export AUTH0_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"
+```
+
+Or use a `.env` file (add to `.gitignore`):
+
+```properties
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_CLIENT_ID=your-client-id
+AUTH0_CLIENT_SECRET=<YOUR_CLIENT_SECRET>
+```
+
+> **Agent instruction:** Never write actual credential values to files. Instead, instruct the user to create or update `.env` with their credentials. Provide the template with placeholders only. Always add `.env` to `.gitignore` if not already present. Warn the user: _"Check your `.env` for duplicate Auth0 entries if you've configured it previously."_
+>
+> Java does not auto-load `.env` files. `System.getenv()` only reads OS-level environment variables. If you generate a `.env` file, you must also either: (1) add [dotenv-java](https://github.com/cdimascio/dotenv-java) as a dependency and use `Dotenv.load().get("AUTH0_DOMAIN")` instead of `System.getenv()`, or (2) instruct the user to run `source .env` before starting the server. Do not generate code that uses both a `.env` file and `System.getenv()` without a loading mechanism — the values will be `null`.
+
+**Important:** Domain must NOT include `https://`. The library constructs the issuer URL automatically.
+
+### 4. Initialize AuthenticationController
+
+Create a singleton `AuthenticationController` instance:
+
+```java
+import com.auth0.AuthenticationController;
+import com.auth0.jwk.JwkProviderBuilder;
+import com.auth0.jwk.JwkProvider;
+
+public class Auth0Config {
+
+    private static final AuthenticationController controller = createController();
+
+    private static AuthenticationController createController() {
+        String domain = System.getenv("AUTH0_DOMAIN");
+        String clientId = System.getenv("AUTH0_CLIENT_ID");
+        String clientSecret = System.getenv("AUTH0_CLIENT_SECRET");
+
+        JwkProvider jwkProvider = new JwkProviderBuilder(domain).build();
+
+        return AuthenticationController.newBuilder(domain, clientId, clientSecret)
+            .withJwkProvider(jwkProvider)
+            .build();
+    }
+
+    public static AuthenticationController getAuthController() {
+        return controller;
+    }
+}
+```
+
+### 5. Create Login Servlet
+
+```java
+import com.auth0.AuthenticationController;
+import com.auth0.AuthorizeUrl;
+
+import javax.servlet.ServletException;
+import javax.servlet.annotation.WebServlet;
+import javax.servlet.http.HttpServlet;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.io.IOException;
+
+@WebServlet(urlPatterns = {"/login"})
+public class LoginServlet extends HttpServlet {
+
+    @Override
+    protected void doGet(HttpServletRequest request, HttpServletResponse response)
+            throws ServletException, IOException {
+        AuthenticationController controller = Auth0Config.getAuthController();
+
+        // Build callback URL — omit port for standard ports (80/443) to avoid
+        // mismatch with the URL registered in Auth0 Dashboard, especially behind proxies.
+        String scheme = request.getScheme();
+        int port = request.getServerPort();
+        String redirectUrl = scheme + "://" + request.getServerName()
+            + ((port == 80 || port == 443) ? "" : ":" + port) + "/callback";
+
+        AuthorizeUrl authorizeUrl = controller.buildAuthorizeUrl(request, response, redirectUrl)
+            .withScope("openid profile email");
+
+        response.sendRedirect(authorizeUrl.build());
+    }
+}
+```
+
+### 6. Create Callback Servlet
+
+```java
+import com.auth0.AuthenticationController;
+import com.auth0.IdentityVerificationException;
+import com.auth0.Tokens;
+
+import javax.servlet.ServletException;
+import javax.servlet.annotation.WebServlet;
+import javax.servlet.http.HttpServlet;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.io.IOException;
+
+@WebServlet(urlPatterns = {"/callback"})
+public class CallbackServlet extends HttpServlet {
+
+    @Override
+    protected void doGet(HttpServletRequest request, HttpServletResponse response)
+            throws ServletException, IOException {
+        AuthenticationController controller = Auth0Config.getAuthController();
+
+        try {
+            Tokens tokens = controller.handle(request, response);
+
+            request.getSession().setAttribute("accessToken", tokens.getAccessToken());
+            request.getSession().setAttribute("idToken", tokens.getIdToken());
+
+            response.sendRedirect("/dashboard");
+        } catch (IdentityVerificationException e) {
+            response.sendRedirect("/login?error=" + e.getCode());
+        }
+    }
+}
+```
+
+### 7. Protect Routes with Authentication Middleware (Servlet Filter)
+
+```java
+import javax.servlet.*;
+import javax.servlet.annotation.WebFilter;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import javax.servlet.http.HttpSession;
+import java.io.IOException;
+
+@WebFilter(urlPatterns = {"/dashboard/*", "/api/private/*"})
+public class AuthenticationFilter implements Filter {
+
+    @Override
+    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
+            throws IOException, ServletException {
+        HttpServletRequest request = (HttpServletRequest) req;
+        HttpServletResponse response = (HttpServletResponse) res;
+        HttpSession session = request.getSession(false);
+
+        if (session == null || session.getAttribute("idToken") == null) {
+            response.sendRedirect("/login");
+            return;
+        }
+
+        chain.doFilter(req, res);
+    }
+
+    @Override
+    public void init(FilterConfig filterConfig) {}
+
+    @Override
+    public void destroy() {}
+}
+```
+
+### 8. Test Application
+
+> **Agent instruction:** After writing all code, verify the build succeeds:
+> ```bash
+> ./gradlew build
+> ```
+> or `mvn package`. If build fails, diagnose and fix. After 5-6 failed attempts, use `AskUserQuestion` to get help.
+
+1. Start the application and navigate to `http://localhost:3000/login`
+2. You should be redirected to the Auth0 Universal Login page
+3. After login, the callback servlet handles the response and redirects to `/dashboard`
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Domain includes `https://` | Use `your-tenant.auth0.com` format only — no scheme prefix |
+| Client secret hardcoded in source | Use environment variables or `.env` file, add to `.gitignore` |
+| Created SPA or Native app instead of Regular Web | Must create **Regular Web Application** in Auth0 Dashboard |
+| Callback URL mismatch | Callback URL in code must exactly match what's registered in Auth0 Dashboard |
+| Missing `openid` scope | Always include `openid` in the scope — required for ID token |
+| Not handling `IdentityVerificationException` | Always catch this in the callback handler to show login errors |
+| Using `response_type=token` | Regular web apps must use `code` flow (the default) — never implicit |
+| Session not invalidated on logout | Call `request.getSession().invalidate()` before redirecting to Auth0 logout |
+
+## Scope and Audience Configuration
+
+See the Integration Patterns sections below for requesting custom scopes, audience for API access tokens, and Organizations support.
+
+## Multiple Custom Domains (MCD)
+
+Built-in support for routing users to the correct Auth0 domain via `DomainResolver`. See the Multiple Custom Domains (MCD) section below for configuration.
+
+## Related Skills
+
+- Basic Auth0 setup and account creation → set it up with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Spring Boot REST APIs with JWT Bearer token validation → the Auth0 integration workflow for Spring Boot APIs
+
+## Quick Reference
+
+**Core Classes:**
+- `AuthenticationController` — Main entry point, builds authorize URLs and handles callbacks
+- `AuthenticationController.Builder` — Configures the controller via `newBuilder(domain, clientId, clientSecret)`
+- `AuthorizeUrl` — Fluent builder for `/authorize` URL parameters
+- `Tokens` — Access token, ID token, refresh token from callback
+- `IdentityVerificationException` — Authentication error with error code
+- `DomainResolver` — Interface for Multiple Custom Domain support
+
+**Builder Methods (`AuthorizeUrl`):**
+- `.withScope("openid profile email")` — Set requested scopes
+- `.withAudience("https://my-api")` — Request API access token
+- `.withOrganization("org_xxx")` — Lock to specific Organization
+- `.withInvitation("invite_xxx")` — Accept Organization invitation
+- `.withConnection("google-oauth2")` — Skip to specific connection
+- `.withParameter("key", "value")` — Add custom authorize parameter
+
+**Token Access (`Tokens`):**
+- `tokens.getAccessToken()` — Access token string
+- `tokens.getIdToken()` — ID token (JWT) string
+- `tokens.getRefreshToken()` — Refresh token (if `offline_access` scope requested)
+- `tokens.getExpiresIn()` — Token expiration in seconds
+- `tokens.getType()` — Token type (usually "Bearer")
+- `tokens.getDomain()` — Auth0 domain that issued the tokens
+- `tokens.getIssuer()` — Token issuer URL
+
+## References
+
+- [Auth0 Java Web App Quickstart](https://auth0.com/docs/quickstart/webapp/java)
+- [SDK GitHub Repository](https://github.com/auth0/auth0-java-mvc-common)
+- [Auth0 Universal Login](https://auth0.com/docs/authenticate/login/auth0-universal-login)
+- [Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)
+- [Auth0 Organizations](https://auth0.com/docs/manage-users/organizations)
+
+---
+
+# Auth0 Java MVC Common API Reference
+
+Complete API reference for `com.auth0:mvc-auth-commons`.
+
+---
+
+## AuthenticationController
+
+Main entry point for Auth0 authentication in Java Servlet applications.
+
+### Builder
+
+```java
+AuthenticationController.newBuilder(String domain, String clientId, String clientSecret)
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `domain` | `String` | Yes | Auth0 tenant domain (no `https://` prefix) |
+| `clientId` | `String` | Yes | Application Client ID |
+| `clientSecret` | `String` | Yes | Application Client Secret |
+
+**Builder with DomainResolver (MCD):**
+
+```java
+AuthenticationController.newBuilder(DomainResolver resolver, String clientId, String clientSecret)
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `resolver` | `DomainResolver` | Yes | Resolves domain per request for Multiple Custom Domains |
+| `clientId` | `String` | Yes | Application Client ID |
+| `clientSecret` | `String` | Yes | Application Client Secret |
+
+### Builder Configuration Methods
+
+| Method | Description |
+|--------|-------------|
+| `.withResponseType("code")` | Set OAuth response_type (default: `code`) |
+| `.withJwkProvider(JwkProvider)` | Custom JWK provider for token verification |
+| `.withClockSkew(int)` | Clock skew tolerance in seconds for token validation (default: 60) |
+| `.withHttpOptions(HttpOptions)` | HTTP proxy/timeout configuration |
+| `.withCookiePath(String)` | Cookie path attribute |
+| `.withAuthenticationMaxAge(Integer)` | Validates `auth_time` claim in the ID token |
+| `.withLegacySameSiteCookie(boolean)` | Controls SameSite=None fallback cookie (default: `true`) |
+| `.withOrganization(String)` | Sends `organization` to `/authorize` **and** validates `org_id`/`org_name` claim in the returned ID token via `IdTokenVerifier`. If the value starts with `org_`, validates `org_id`; otherwise validates `org_name` (case-insensitive). Throws `TokenValidationException` on mismatch. |
+| `.withInvitation(String)` | Sends `invitation` parameter to `/authorize` (no callback validation) |
+| `.build()` | Build the `AuthenticationController` instance |
+
+> **Note:** `Builder.withOrganization()` does two things: it passes the `organization` parameter to `/authorize` (via `AuthorizeUrl`) **and** validates the org claim in the returned token. `AuthorizeUrl.withOrganization()` only sends the parameter to `/authorize` without any token validation. When using `Builder.withOrganization()`, you do not need to also call `AuthorizeUrl.withOrganization()` — the Builder handles both automatically.
+
+### Instance Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `buildAuthorizeUrl(request, response, redirectUrl)` | `AuthorizeUrl` | Build `/authorize` URL with CSRF state |
+| `handle(request, response)` | `Tokens` | Exchange authorization code for tokens |
+| `buildAuthorizeUrl(request, redirectUrl)` | `AuthorizeUrl` | **Deprecated** — use the 3-argument version with response |
+| `handle(request)` | `Tokens` | **Deprecated** — use the 2-argument version with response |
+
+---
+
+## AuthorizeUrl
+
+Fluent builder for constructing the Auth0 `/authorize` redirect URL.
+
+### Methods
+
+| Method | Parameter | Description |
+|--------|-----------|-------------|
+| `.withScope(String)` | `"openid profile email"` | Space-separated scopes to request |
+| `.withAudience(String)` | `"https://my-api"` | API audience for access token |
+| `.withOrganization(String)` | `"org_xxx"` | Lock login to specific Organization |
+| `.withInvitation(String)` | `"invite_xxx"` | Accept Organization invitation |
+| `.withConnection(String)` | `"google-oauth2"` | Skip to specific identity provider |
+| `.withParameter(String, String)` | key, value | Add any custom `/authorize` parameter. **Throws `IllegalArgumentException` for `state`, `nonce`, `response_type`, `redirect_uri` — use dedicated methods instead.** |
+| `.withNonce(String)` | nonce value | Set a custom nonce for ID token validation |
+| `.withSecureCookie(boolean)` | `true`/`false` | Set the Secure flag on state/nonce cookies |
+| `.withState(String)` | state value | Custom state parameter (overrides CSRF state) |
+| `.build()` | — | Returns the complete authorize URL string |
+
+**Example:**
+
+```java
+String authorizeUrl = controller.buildAuthorizeUrl(request, response, redirectUrl)
+    .withScope("openid profile email")
+    .withAudience("https://my-api.example.com")
+    .withOrganization("org_abc123")
+    .build();
+```
+
+---
+
+## Tokens
+
+Holds the tokens returned after a successful authentication.
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getAccessToken()` | `String` | OAuth2 access token |
+| `getIdToken()` | `String` | OpenID Connect ID token (JWT) |
+| `getRefreshToken()` | `String` | Refresh token (requires `offline_access` scope) |
+| `getType()` | `String` | Token type (usually "Bearer") |
+| `getExpiresIn()` | `Long` | Token lifetime in seconds |
+| `getDomain()` | `String` | Auth0 domain that issued the tokens |
+| `getIssuer()` | `String` | Token issuer URL |
+
+---
+
+## DomainResolver
+
+Interface for Multiple Custom Domains (MCD) support.
+
+```java
+public interface DomainResolver {
+    String resolve(HttpServletRequest request);
+}
+```
+
+### Implementation Example
+
+```java
+public class SubdomainDomainResolver implements DomainResolver {
+    @Override
+    public String resolve(HttpServletRequest request) {
+        String host = request.getServerName();
+        if (host.startsWith("eu.")) {
+            return "my-tenant-eu.auth0.com";
+        }
+        return "my-tenant.auth0.com";
+    }
+}
+```
+
+---
+
+## IdentityVerificationException
+
+Thrown when authentication fails during callback handling.
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getCode()` | `String` | Error code identifier |
+| `getMessage()` | `String` | Human-readable error message |
+| `isAPIError()` | `boolean` | Whether the error came from the Auth0 API |
+| `isJWTError()` | `boolean` | Whether the error is a JWT validation failure |
+
+### Error Codes
+
+| Code | Description |
+|------|-------------|
+| `a0.api_error` | Auth0 API returned an error |
+| `a0.missing_jwt_public_key_error` | Could not retrieve JWKS public key |
+| `a0.invalid_jwt_error` | JWT validation failed (bad signature, expired, wrong audience) |
+
+---
+
+## InvalidRequestException
+
+Extends `IdentityVerificationException`. Thrown when the callback request itself is invalid (e.g., state mismatch, missing tokens).
+
+### Error Codes
+
+| Code | Description |
+|------|-------------|
+| `a0.invalid_state` | State parameter mismatch between login and callback |
+| `a0.missing_id_token` | No ID token returned |
+| `a0.missing_access_token` | No access token returned |
+
+Since `InvalidRequestException` extends `IdentityVerificationException`, it is caught by the same `catch` block. Use `getCode()` to distinguish specific error conditions.
+
+---
+
+## Environment Variable Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AUTH0_DOMAIN` | Yes | Auth0 tenant domain (e.g., `your-tenant.auth0.com`) |
+| `AUTH0_CLIENT_ID` | Yes | Application Client ID from Auth0 Dashboard |
+| `AUTH0_CLIENT_SECRET` | Yes | Application Client Secret from Auth0 Dashboard |
+
+### Reading Environment Variables
+
+```java
+String domain = System.getenv("AUTH0_DOMAIN");
+String clientId = System.getenv("AUTH0_CLIENT_ID");
+String clientSecret = System.getenv("AUTH0_CLIENT_SECRET");
+```
+
+Or via servlet context parameters in `web.xml`:
+
+```xml
+<context-param>
+    <param-name>auth0.domain</param-name>
+    <param-value>${AUTH0_DOMAIN}</param-value>
+</context-param>
+<context-param>
+    <param-name>auth0.clientId</param-name>
+    <param-value>${AUTH0_CLIENT_ID}</param-value>
+</context-param>
+<context-param>
+    <param-name>auth0.clientSecret</param-name>
+    <param-value>${AUTH0_CLIENT_SECRET}</param-value>
+</context-param>
+```
+
+---
+
+## Standard OIDC Claims (from ID Token)
+
+| Claim | Description |
+|-------|-------------|
+| `sub` | User ID (subject) |
+| `name` | Full name |
+| `email` | Email address |
+| `email_verified` | Whether email is verified |
+| `picture` | Profile picture URL |
+| `nickname` | User nickname |
+| `updated_at` | Last profile update timestamp |
+
+Custom claims added via Auth0 Actions use namespaced keys, e.g., `https://example.com/roles`.
+
+---
+
+## Testing Checklist
+
+- [ ] Login redirects to Auth0 Universal Login page
+- [ ] Callback servlet exchanges code for tokens successfully
+- [ ] Session stores tokens after successful login
+- [ ] Protected routes redirect to `/login` when no session exists
+- [ ] Protected routes allow access when session has valid tokens
+- [ ] Logout invalidates session and redirects to Auth0 logout endpoint
+- [ ] Error handling catches `IdentityVerificationException` on callback
+- [ ] Environment variables are used (no hardcoded credentials)
+- [ ] Callback URL in code matches Auth0 Dashboard configuration
+- [ ] `openid` scope is always included in authorize request
+
+### Test with curl
+
+```bash
+# Start the application
+./gradlew appRun  # or mvn jetty:run
+
+# Open login in browser (redirects to Auth0)
+open http://localhost:3000/login
+
+# After login, check session cookie is set
+curl -v http://localhost:3000/dashboard --cookie "JSESSIONID=your-session-id"
+```
+
+---
+
+## Common Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `a0.invalid_jwt_error` on callback | Clock skew between server and Auth0 | Use `.withClockSkew(300)` on builder |
+| `a0.missing_jwt_public_key_error` | Cannot reach Auth0 JWKS endpoint | Check network/firewall, verify domain |
+| Redirect loop on callback | Callback URL not registered in Auth0 | Add exact callback URL to Allowed Callback URLs |
+| `state` parameter mismatch | Session lost between login and callback | Ensure same session across redirect (check cookie settings) |
+| No refresh token returned | Missing `offline_access` scope | Add `offline_access` to `.withScope()` |
+
+---
+
+## Security Considerations
+
+- **Never hardcode credentials** — Always use environment variables or secret management
+- **Always include `openid` scope** — Required for ID token and user identification
+- **Use HTTPS in production** — Auth0 requires HTTPS for callback URLs in production
+- **Validate state parameter** — The library handles CSRF via state automatically; do not disable
+- **Invalidate session on logout** — Always call `session.invalidate()` before Auth0 logout redirect
+- **Rotate client secret** — If secret is compromised, rotate in Auth0 Dashboard immediately
+- **Store tokens server-side only** — Never expose tokens to the browser via cookies or HTML
+
+---
+
+## References
+
+- [Auth0 Java Web App Quickstart](https://auth0.com/docs/quickstart/webapp/java)
+- [SDK GitHub Repository](https://github.com/auth0/auth0-java-mvc-common)
+- [Auth0 Universal Login](https://auth0.com/docs/authenticate/login/auth0-universal-login)
+- [Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)
+
+---
+
+# Auth0 Java MVC Common Integration Patterns
+
+Advanced integration patterns for Java Servlet applications using `com.auth0:mvc-auth-commons`.
+
+---
+
+## Login and Callback Flow
+
+### Basic Login
+
+```java
+@WebServlet(urlPatterns = {"/login"})
+public class LoginServlet extends HttpServlet {
+
+    @Override
+    protected void doGet(HttpServletRequest request, HttpServletResponse response)
+            throws ServletException, IOException {
+        AuthenticationController controller = Auth0Config.getAuthController();
+
+        String scheme = request.getScheme();
+        int port = request.getServerPort();
+        String redirectUrl = scheme + "://" + request.getServerName()
+            + ((port == 80 || port == 443) ? "" : ":" + port) + "/callback";
+
+        String authorizeUrl = controller.buildAuthorizeUrl(request, response, redirectUrl)
+            .withScope("openid profile email")
+            .build();
+
+        response.sendRedirect(authorizeUrl);
+    }
+}
+```
+
+### Callback Handler
+
+```java
+@WebServlet(urlPatterns = {"/callback"})
+public class CallbackServlet extends HttpServlet {
+
+    @Override
+    protected void doGet(HttpServletRequest request, HttpServletResponse response)
+            throws ServletException, IOException {
+        AuthenticationController controller = Auth0Config.getAuthController();
+
+        try {
+            Tokens tokens = controller.handle(request, response);
+
+            // Store tokens in session
+            request.getSession().setAttribute("accessToken", tokens.getAccessToken());
+            request.getSession().setAttribute("idToken", tokens.getIdToken());
+
+            // Redirect to original requested page or dashboard
+            String returnTo = (String) request.getSession().getAttribute("returnTo");
+            response.sendRedirect(returnTo != null ? returnTo : "/dashboard");
+
+        } catch (IdentityVerificationException e) {
+            response.sendRedirect("/login?error=" + e.getCode());
+        }
+    }
+}
+```
+
+---
+
+## Logout
+
+### Complete Logout (Session + Auth0)
+
+```java
+@WebServlet(urlPatterns = {"/logout"})
+public class LogoutServlet extends HttpServlet {
+
+    @Override
+    protected void doGet(HttpServletRequest request, HttpServletResponse response)
+            throws ServletException, IOException {
+        // Invalidate local session
+        if (request.getSession(false) != null) {
+            request.getSession().invalidate();
+        }
+
+        // Redirect to Auth0 logout endpoint
+        String domain = System.getenv("AUTH0_DOMAIN");
+        String clientId = System.getenv("AUTH0_CLIENT_ID");
+        String scheme = request.getScheme();
+        int port = request.getServerPort();
+        String returnTo = scheme + "://" + request.getServerName()
+            + ((port == 80 || port == 443) ? "" : ":" + port);
+
+        String logoutUrl = String.format(
+            "https://%s/v2/logout?client_id=%s&returnTo=%s",
+            domain, clientId, java.net.URLEncoder.encode(returnTo, "UTF-8")
+        );
+
+        response.sendRedirect(logoutUrl);
+    }
+}
+```
+
+**Important:** Always invalidate the local session AND redirect to Auth0 `/v2/logout` to clear the Auth0 session.
+
+---
+
+## Requesting API Access Tokens
+
+To call external APIs with an access token, include the `audience` parameter:
+
+```java
+String authorizeUrl = controller.buildAuthorizeUrl(request, response, redirectUrl)
+    .withScope("openid profile email read:messages")
+    .withAudience("https://my-api.example.com")
+    .build();
+```
+
+The returned access token will be scoped to the specified audience:
+
+```java
+Tokens tokens = controller.handle(request, response);
+String apiToken = tokens.getAccessToken();  // Use this to call your API
+```
+
+---
+
+## Organizations Support
+
+### Lock Login to Specific Organization
+
+```java
+String authorizeUrl = controller.buildAuthorizeUrl(request, response, redirectUrl)
+    .withScope("openid profile email")
+    .withOrganization("org_abc123")
+    .build();
+```
+
+### Accept Organization Invitation
+
+```java
+// Extract from invitation URL query parameters
+String organization = request.getParameter("organization");
+String invitation = request.getParameter("invitation");
+
+AuthorizeUrl url = controller.buildAuthorizeUrl(request, response, redirectUrl)
+    .withScope("openid profile email")
+    .withOrganization(organization)
+    .withInvitation(invitation);
+
+response.sendRedirect(url.build());
+```
+
+### Organization Claim in Token
+
+After login with an organization, the ID token contains an `org_id` claim:
+
+```java
+Tokens tokens = controller.handle(request, response);
+// Decode the ID token to access org_id claim
+// The library validates that org_id matches if withOrganization() was used
+```
+
+---
+
+## Multiple Custom Domains (MCD)
+
+Use `DomainResolver` to route users to different Auth0 domains based on the request:
+
+### Implement DomainResolver
+
+```java
+import com.auth0.DomainResolver;
+import javax.servlet.http.HttpServletRequest;
+
+public class SubdomainDomainResolver implements DomainResolver {
+
+    @Override
+    public String resolve(HttpServletRequest request) {
+        String host = request.getServerName();
+
+        if (host.startsWith("eu.")) {
+            return "my-tenant-eu.custom-domain.com";
+        } else if (host.startsWith("au.")) {
+            return "my-tenant-au.custom-domain.com";
+        }
+
+        return System.getenv("AUTH0_DOMAIN");
+    }
+}
+```
+
+> **Security warning:** When resolving domains from the request, always validate against a trusted allowlist of known domains. Never use the raw request `Host` header as a domain value — an attacker could manipulate it. For single-tenant deployments, return a hardcoded domain. If behind a reverse proxy, ensure `X-Forwarded-Host` is set by a trusted proxy only.
+
+### Configure with DomainResolver
+
+```java
+DomainResolver resolver = new SubdomainDomainResolver();
+AuthenticationController controller = AuthenticationController
+    .newBuilder(resolver, clientId, clientSecret)
+    .build();
+```
+
+The `DomainResolver` is called on each request, so each user can be directed to the correct Auth0 custom domain.
+
+---
+
+## Custom Scopes and Parameters
+
+### Request Additional Scopes
+
+```java
+AuthorizeUrl url = controller.buildAuthorizeUrl(request, response, redirectUrl)
+    .withScope("openid profile email offline_access read:messages write:messages");
+```
+
+Common scopes:
+
+| Scope | Description |
+|-------|-------------|
+| `openid` | Required — enables OpenID Connect |
+| `profile` | User's name, nickname, picture |
+| `email` | User's email and verification status |
+| `offline_access` | Request a refresh token |
+| Custom scopes | API-specific scopes (e.g., `read:messages`) |
+
+### Skip to Specific Connection
+
+```java
+// Go directly to Google login (skip Universal Login selection)
+AuthorizeUrl url = controller.buildAuthorizeUrl(request, response, redirectUrl)
+    .withScope("openid profile email")
+    .withConnection("google-oauth2");
+```
+
+### Custom Parameters
+
+```java
+AuthorizeUrl url = controller.buildAuthorizeUrl(request, response, redirectUrl)
+    .withScope("openid profile email")
+    .withParameter("screen_hint", "signup")     // Show signup instead of login
+    .withParameter("login_hint", "user@example.com")  // Pre-fill email
+    .withParameter("ui_locales", "fr");                // French UI
+```
+
+---
+
+## Clock Skew Configuration
+
+If your server clock drifts from Auth0 servers, token validation may fail with `a0.invalid_jwt_error`:
+
+```java
+AuthenticationController controller = AuthenticationController
+    .newBuilder(domain, clientId, clientSecret)
+    .withClockSkew(300)  // Allow 5 minutes of clock skew
+    .build();
+```
+
+---
+
+## Protected Routes with Authentication Filter
+
+### Basic Authentication Filter
+
+```java
+@WebFilter(urlPatterns = {"/dashboard/*", "/api/private/*"})
+public class AuthenticationFilter implements Filter {
+
+    @Override
+    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
+            throws IOException, ServletException {
+        HttpServletRequest request = (HttpServletRequest) req;
+        HttpServletResponse response = (HttpServletResponse) res;
+        HttpSession session = request.getSession(false);
+
+        if (session == null || session.getAttribute("idToken") == null) {
+            // Store requested URL for redirect after login
+            request.getSession(true).setAttribute("returnTo", request.getRequestURI());
+            response.sendRedirect("/login");
+            return;
+        }
+
+        chain.doFilter(req, res);
+    }
+
+    @Override
+    public void init(FilterConfig filterConfig) {}
+
+    @Override
+    public void destroy() {}
+}
+```
+
+---
+
+## Accessing User Claims
+
+### Decode ID Token Claims
+
+The ID token is a JWT. Decode it to access user claims:
+
+```java
+import com.auth0.jwt.JWT;
+import com.auth0.jwt.interfaces.DecodedJWT;
+
+@WebServlet(urlPatterns = {"/dashboard"})
+public class DashboardServlet extends HttpServlet {
+
+    @Override
+    protected void doGet(HttpServletRequest request, HttpServletResponse response)
+            throws ServletException, IOException {
+        String idToken = (String) request.getSession().getAttribute("idToken");
+        DecodedJWT jwt = JWT.decode(idToken);
+
+        String userId = jwt.getSubject();
+        String email = jwt.getClaim("email").asString();
+        String name = jwt.getClaim("name").asString();
+        String picture = jwt.getClaim("picture").asString();
+
+        // Render dashboard with user info
+        request.setAttribute("userId", userId);
+        request.setAttribute("email", email);
+        request.setAttribute("name", name);
+        request.setAttribute("picture", picture);
+        request.getRequestDispatcher("/WEB-INF/dashboard.jsp").forward(request, response);
+    }
+}
+```
+
+**Note:** Decoding with `JWT.decode()` does not verify the signature — the library already verified it during `controller.handle()`.
+
+---
+
+## Error Handling
+
+### IdentityVerificationException
+
+```java
+try {
+    Tokens tokens = controller.handle(request, response);
+    // Success — store tokens
+} catch (IdentityVerificationException e) {
+    String errorCode = e.getCode();
+
+    switch (errorCode) {
+        case "a0.api_error":
+            // Auth0 API error — check tenant config
+            break;
+        case "a0.missing_jwt_public_key_error":
+            // Cannot reach JWKS — check network
+            break;
+        case "a0.invalid_jwt_error":
+            // JWT validation failed — check clock skew
+            break;
+        case "a0.invalid_state":
+            // State mismatch between login and callback — session may have been lost
+            break;
+        case "a0.missing_id_token":
+            // No ID token returned — check scopes include "openid"
+            break;
+        case "a0.missing_access_token":
+            // No access token returned
+            break;
+        default:
+            // Other error
+            break;
+    }
+
+    request.setAttribute("error", e.getMessage());
+    request.getRequestDispatcher("/WEB-INF/error.jsp").forward(request, response);
+}
+```
+
+### User-Denied Consent
+
+If a user denies consent on the Auth0 login page, the callback receives `error=access_denied`. The library wraps this in `IdentityVerificationException`.
+
+---
+
+## HTTP Logging (Debugging)
+
+### SDK Built-in Logging
+
+The simplest way to enable debug logging:
+
+```java
+AuthenticationController controller = AuthenticationController
+    .newBuilder(domain, clientId, clientSecret)
+    .build();
+
+controller.setLoggingEnabled(true);
+```
+
+### SLF4J / Logback
+
+For more granular control, add SLF4J + Logback and configure in `logback.xml`:
+
+```xml
+<logger name="com.auth0" level="DEBUG" />
+```
+
+---
+
+## Servlet API Compatibility
+
+The SDK currently supports `javax.servlet` only. The code and README use `javax.servlet` imports:
+
+```java
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+```
+
+If your project uses `jakarta.servlet` (Jakarta EE 9+), this SDK is not compatible. Check for a Jakarta-specific version or consider an alternative like the Spring Boot Okta starter which supports Jakarta.
+
+---
+
+## Security Considerations
+
+- **CSRF protection** — The library automatically generates and validates `state` parameter
+- **Session fixation** — Regenerate session ID after login: `request.changeSessionId()`
+- **Token storage** — Store tokens in server-side session only, never in cookies or HTML
+- **HTTPS** — Use HTTPS in production; Auth0 requires it for callback URLs
+- **Client secret** — Never expose in client-side code or commit to source control
+- **Session timeout** — Configure session timeout in `web.xml`:
+
+```xml
+<session-config>
+    <session-timeout>30</session-timeout> <!-- minutes -->
+</session-config>
+```
+
+---
+
+---
+
+# Auth0 Java MVC Common Setup Guide
+
+Setup and configuration guide for Auth0 Java Servlet authentication using `com.auth0:mvc-auth-commons`.
+
+---
+
+## Auth0 Configuration
+
+> **Agent instruction:** Do not write or echo credential values yourself. If the user's prompt already provides Auth0 credentials (domain, client ID, client secret), skip the credential questions and instruct the user to populate their `.env` file — provide variable names and placeholders (`<YOUR_DOMAIN>`, `<YOUR_CLIENT_ID>`, `<YOUR_CLIENT_SECRET>`), never actual values.
+>
+> **Secret handling:** Never retrieve or parse `client_secret` from Auth0 CLI output. Never write actual credential values into any file — always use placeholders. Do NOT read `.env` files. Always add `.env` to `.gitignore` if not already present. Warn the user to check for duplicates if they may have already configured credentials.
+
+### Option A: Automatic Setup (Auth0 CLI)
+
+> **Agent instruction:** Use Auth0 CLI to handle Auth0 configuration automatically:
+> 1. **Pre-flight checks:**
+>    - Verify Auth0 CLI is installed: `auth0 --version`
+>    - Verify logged in: `auth0 tenants list --csv --no-input`
+>    - If any check fails, guide user to install/login, or fall back to manual setup
+>
+> 2. **Create the application using Auth0 CLI:**
+>    ```bash
+>    auth0 apps create --name "My Java Web App" --type regular --callbacks http://localhost:3000/callback --logout-urls http://localhost:3000 --json --no-input
+>    ```
+>    From the JSON output, note the `domain` and `client_id`. Instruct the user to add these values (along with `client_secret`) to their `.env` file themselves.
+>    Do NOT extract or write any credential values from the CLI output.
+
+### Option B: Manual Setup
+
+> **Agent instruction:** If the user chose manual setup, use `AskUserQuestion` to collect:
+> 1. Auth0 Domain
+> 2. Client ID
+> 3. Client Secret
+>
+> Then instruct the user to add these values to their `.env` file. Do not write credential values yourself — provide the template with placeholders only.
+
+#### 1. Create Auth0 Application
+
+```bash
+# Using Auth0 CLI
+auth0 apps create \
+  --name "My Java Web App" \
+  --type regular \
+  --callbacks http://localhost:3000/callback \
+  --logout-urls http://localhost:3000 \
+  --json
+```
+
+Or manually in Auth0 Dashboard:
+1. Go to Applications → Applications → Create Application
+2. Select **Regular Web Applications**
+3. Note the **Domain**, **Client ID**, and **Client Secret**
+4. Under Settings → Application URIs:
+   - Allowed Callback URLs: `http://localhost:3000/callback`
+   - Allowed Logout URLs: `http://localhost:3000`
+
+#### 2. Set Up Database Connection
+
+```bash
+# List existing connections
+auth0 connections list --json
+
+# Enable your app on the default database connection
+# (done automatically if using Option A: Automatic Setup)
+```
+
+#### 3. Write Environment Configuration
+
+Create a `.env` file in your project root (add to `.gitignore`):
+
+```properties
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_CLIENT_ID=your-client-id
+AUTH0_CLIENT_SECRET=<YOUR_CLIENT_SECRET>
+```
+
+> **Agent instruction:** Never write actual credential values to files. Instruct the user to populate `.env` with their credentials. If `.env` already exists, remind the user to append (not overwrite). Always add `.env` to `.gitignore` automatically.
+
+> **Agent instruction:** Java does not auto-load `.env` files. If you generate a `.env` file, also add [dotenv-java](https://github.com/cdimascio/dotenv-java) and use `Dotenv.load().get("AUTH0_DOMAIN")`, or instruct the user to run `source .env` before starting the server.
+
+---
+
+## Secret Management
+
+### Development
+
+Use a `.env` file in the project root:
+
+```properties
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_CLIENT_ID=your-client-id
+AUTH0_CLIENT_SECRET=<YOUR_CLIENT_SECRET>
+```
+
+> **Agent instruction:** Never write actual credential values to files. Instruct the user to populate `.env` with their own values. Never retrieve secrets from CLI output. Always ensure `.env` is in `.gitignore`.
+
+**Important:** Add `.env` to `.gitignore` to prevent committing secrets:
+
+```bash
+echo ".env" >> .gitignore
+```
+
+Load environment variables in your application. For servlet containers:
+
+**Option 1: System environment variables**
+
+Set on the system or in the container startup script:
+
+```bash
+export AUTH0_DOMAIN="your-tenant.auth0.com"
+export AUTH0_CLIENT_ID="your-client-id"
+export AUTH0_CLIENT_SECRET="<YOUR_CLIENT_SECRET>"
+```
+
+**Option 2: Servlet context parameters (web.xml)**
+
+```xml
+<context-param>
+    <param-name>auth0.domain</param-name>
+    <param-value>${AUTH0_DOMAIN}</param-value>
+</context-param>
+```
+
+Read in code:
+
+```java
+String domain = getServletContext().getInitParameter("auth0.domain");
+```
+
+### Production
+
+Use your deployment platform's secret management:
+
+| Platform | Method |
+|----------|--------|
+| Docker | `docker run -e AUTH0_DOMAIN=... -e AUTH0_CLIENT_ID=...` |
+| Kubernetes | Secrets mounted as env vars |
+| AWS | Parameter Store or Secrets Manager |
+| Heroku | `heroku config:set AUTH0_DOMAIN=...` |
+| Tomcat | Set in `setenv.sh` or JNDI context |
+
+**Never commit secrets to source control.**
+
+---
+
+## Dependency Installation
+
+### Gradle (build.gradle)
+
+```groovy
+dependencies {
+    implementation 'com.auth0:mvc-auth-commons:1.12.0'
+}
+```
+
+### Maven (pom.xml)
+
+```xml
+<dependency>
+    <groupId>com.auth0</groupId>
+    <artifactId>mvc-auth-commons</artifactId>
+    <version>1.12.0</version>
+</dependency>
+```
+
+### Verify Installation
+
+```bash
+# Gradle
+./gradlew dependencies | grep mvc-auth-commons
+
+# Maven
+mvn dependency:tree | grep mvc-auth-commons
+```
+
+---
+
+## Project Structure
+
+Typical Java Servlet project with Auth0:
+
+```text
+src/main/java/
+├── com/example/
+│   ├── Auth0Config.java          # AuthenticationController singleton
+│   ├── LoginServlet.java         # /login endpoint
+│   ├── CallbackServlet.java      # /callback endpoint
+│   ├── LogoutServlet.java        # /logout endpoint
+│   ├── AuthenticationFilter.java # Protect routes
+│   └── DashboardServlet.java     # Protected page
+src/main/webapp/
+├── WEB-INF/
+│   └── web.xml                   # Servlet configuration
+.env                              # Auth0 credentials (gitignored)
+```
+
+---
+
+## Callback URL Configuration
+
+The callback URL must match **exactly** between your code and Auth0 Dashboard.
+
+| Environment | Callback URL |
+|-------------|-------------|
+| Development | `http://localhost:3000/callback` |
+| Production | `https://yourdomain.com/callback` |
+
+**Build callback URL dynamically in the Login servlet:**
+
+```java
+String scheme = request.getScheme();
+int port = request.getServerPort();
+String redirectUrl = scheme + "://" + request.getServerName()
+    + ((port == 80 || port == 443) ? "" : ":" + port) + "/callback";
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| `ClassNotFoundException: com.auth0.AuthenticationController` | Dependency not in classpath | Verify Maven/Gradle dependency and rebuild |
+| Auth0 returns "Callback URL mismatch" | URL in code ≠ Dashboard | Copy exact URL from code to Allowed Callback URLs |
+| `IdentityVerificationException: a0.invalid_jwt_error` | Clock skew | Add `.withClockSkew(300)` to builder |
+| Login redirects but callback fails silently | Missing session cookie across redirects | Check cookie SameSite settings and domain |
+| `NullPointerException` reading env vars | Environment variables not set | Verify `.env` is loaded or vars are exported |
+
+---
diff --git a/main/.mintlify/skills/auth0/references/framework-laravel-api/index.md b/main/.mintlify/skills/auth0/references/framework-laravel-api/index.md
new file mode 100644
index 0000000000..3f7c6992a5
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-laravel-api/index.md
@@ -0,0 +1,475 @@
+# Auth0 Laravel API
+
+> Ported from auth0/auth0-laravel-api skill.
+
+---
+
+
+# Auth0 Laravel API Integration
+
+Protect Laravel API endpoints with JWT access token validation using `auth0/login` and the `AuthorizationGuard`.
+
+## Critical rules
+
+- **Token isolation is CRITICAL:** the agent MUST NEVER directly see, echo, store, or display access token values. Do not run `auth0 test token` to read a token, and do not ask the user to paste one — instead, pipe the token straight into `curl` using the single-command chains shown in Step 10.
+
+---
+
+## Prerequisites
+
+- Laravel 11+ application
+- PHP 8.2+ with extensions: `mbstring`, `openssl`, `json`
+- Composer installed
+- Auth0 API resource configured (not an Application - must be an API)
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+| Scenario | Use Instead |
+|----------|-------------|
+| Laravel web app with login/logout UI | the Auth0 integration workflow for Laravel web apps (session-based `AuthenticationGuard`) |
+| Plain PHP API (no framework) | the Auth0 integration workflow for plain PHP APIs |
+| Plain PHP web app | the Auth0 integration workflow for plain PHP web apps |
+| Single Page Applications | the Auth0 integration workflow for React, Vue, or Angular |
+| FastAPI / Python APIs | the Auth0 integration workflow for FastAPI |
+| Express / Node.js APIs | the Auth0 integration workflow for Express/Node.js APIs |
+| Issuing tokens | This skill is for *validating* access tokens, not issuing them |
+
+---
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+composer require auth0/login
+```
+
+The `auth0/login` package requires `auth0/auth0-php` (v8.19+) and installs it automatically. It also requires a PSR-18 HTTP client - if you don't already have one:
+
+```bash
+composer require guzzlehttp/guzzle guzzlehttp/psr7
+```
+
+### 2. Publish Configuration
+
+```bash
+php artisan vendor:publish --tag=auth0
+```
+
+This creates `config/auth0.php` with guard, middleware, and route configuration.
+
+### 3. Create Auth0 API
+
+You need an **API** (not Application) in Auth0.
+
+> **STOP - ask the user before proceeding.**
+>
+> Ask exactly this question and wait for their answer before doing anything else:
+>
+> > "How would you like to create the Auth0 API resource?
+> > 1. **Automated** - I'll run Auth0 CLI scripts that create the resource and write the exact values to your `.env` automatically.
+> > 2. **Manual** - You create the API yourself in the Auth0 Dashboard (or via `auth0 apis create`) and provide me the Domain and Audience.
+> >
+> > Which do you prefer? (1 = Automated / 2 = Manual)"
+>
+> Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.
+
+**If the user chose Automated**, follow the Setup Guide section below for complete CLI scripts. The automated path writes `.env` for you - skip Step 4 below and proceed directly to Step 5.
+
+**If the user chose Manual**, follow the Setup Guide section below (Manual Setup section) for full instructions. Then continue with Step 4 below.
+
+Quick reference for manual API creation:
+
+```bash
+auth0 apis create \
+  --name "My Laravel API" \
+  --identifier https://my-api.example.com \
+  --json
+```
+
+Or create manually in Auth0 Dashboard -> Applications -> APIs
+
+### 4. Configure Environment
+
+Add to your `.env`:
+
+```bash
+AUTH0_DOMAIN=your-tenant.us.auth0.com
+AUTH0_AUDIENCE=https://your-api.example.com
+```
+
+`AUTH0_DOMAIN` is your Auth0 tenant domain (without `https://`). `AUTH0_AUDIENCE` is the API identifier you set when creating the API resource in Auth0.
+
+### 5. Configure Auth Guard
+
+Update `config/auth.php` to add the API guard:
+
+```php
+'guards' => [
+    'web' => [
+        'driver' => 'session',
+        'provider' => 'users',
+    ],
+    'auth0-api' => [
+        'driver' => 'auth0.authorizer',
+        'provider' => 'auth0-provider',
+        'configuration' => 'api',
+    ],
+],
+
+'providers' => [
+    'users' => [
+        'driver' => 'eloquent',
+        'model' => App\Models\User::class,
+    ],
+    'auth0-provider' => [
+        'driver' => 'auth0.provider',
+        'repository' => 'auth0.repository',
+    ],
+],
+```
+
+Key points:
+- `driver` must be `auth0.authorizer` (not `auth0.authenticator` which is for web apps)
+- `configuration` must be `'api'` which maps to the `api` guard in `config/auth0.php`
+- The SDK auto-registers an `auth0-api` guard with this config, but defining it explicitly is clearer
+
+### 6. Verify Auth0 Config
+
+After publishing, verify that `config/auth0.php` contains a `guards.api` key with `strategy` set to `SdkConfiguration::STRATEGY_API` (value: `'api'`). This is already present in the published config — no manual editing needed.
+
+The published file uses class constants for keys (e.g., `Configuration::CONFIG_STRATEGY`), which resolve to the same string values at runtime:
+
+```php
+'guards' => [
+    'api' => [
+        'strategy' => SdkConfiguration::STRATEGY_API,  // value: 'api'
+    ],
+],
+```
+
+The published config also includes `default` and `web` guard sections — these can be ignored for API-only usage. The `STRATEGY_API` strategy disables all session/cookie machinery and enables stateless Bearer token validation.
+
+### 7. Add Protected API Routes
+
+Laravel 11+ does not include `routes/api.php` by default. If the file does not exist, scaffold it:
+
+```bash
+php artisan install:api
+```
+
+This creates `routes/api.php` and registers it in `bootstrap/app.php` with the `/api` prefix. It also installs Laravel Sanctum, which is unused but harmless alongside Auth0.
+
+In `routes/api.php`:
+
+```php
+use Illuminate\Support\Facades\Route;
+
+Route::get('/public', function () {
+    return response()->json(['message' => 'Public endpoint - no authentication required']);
+});
+
+Route::middleware('auth:auth0-api')->group(function () {
+    Route::get('/private', function () {
+        $user = auth('auth0-api')->user();
+        return response()->json([
+            'message' => 'Private endpoint',
+            'sub' => $user->getAuthIdentifier(),
+        ]);
+    });
+});
+```
+
+The `auth:auth0-api` middleware validates the Bearer token, verifies the signature against the JWKS endpoint, and checks issuer and audience claims. Requests without a valid token receive a 401 response.
+
+### 8. Scope and Permission Checks
+
+Use the guard's `hasScope()` and `hasPermission()` methods:
+
+```php
+Route::middleware('auth:auth0-api')->group(function () {
+    Route::get('/messages', function () {
+        $guard = auth('auth0-api');
+
+        if (!$guard->hasScope('read:messages')) {
+            return response()->json(['error' => 'insufficient_scope'], 403);
+        }
+
+        return response()->json(['messages' => []]);
+    });
+
+    Route::delete('/users/{id}', function (string $id) {
+        $guard = auth('auth0-api');
+
+        if (!$guard->hasPermission('delete:users')) {
+            return response()->json(['error' => 'insufficient_permissions'], 403);
+        }
+
+        return response()->json(['deleted' => $id]);
+    });
+});
+```
+
+- `hasScope()` checks the `scope` claim (space-separated string in the JWT)
+- `hasPermission()` checks the `permissions` claim (array, requires RBAC enabled on the API in Auth0 Dashboard)
+
+### 9. Access Token Claims
+
+The authenticated user is a `StatelessUser` instance with dynamic claim access:
+
+```php
+Route::middleware('auth:auth0-api')->get('/profile', function () {
+    $user = auth('auth0-api')->user();
+
+    return response()->json([
+        'sub' => $user->getAuthIdentifier(),
+        'email' => $user->email,
+        'permissions' => $user->permissions ?? [],
+        'all_claims' => $user->jsonSerialize(),
+    ]);
+});
+```
+
+Claims are accessed via:
+- `$user->getAuthIdentifier()` - Returns `sub` claim
+- `$user->claim_name` - Dynamic property access via `__get`
+- `$user->getAttribute('claim_name')` - Explicit access
+- `$user->jsonSerialize()` - All claims as array
+
+### 10. Test the API
+
+> **Agent instruction:** Start the Laravel dev server and verify the basic endpoints work without credentials:
+> ```bash
+> php artisan serve &
+> sleep 2
+> curl -s -H "Accept: application/json" http://localhost:8000/api/public
+> curl -s -o /dev/null -w "%{http_code}" -H "Accept: application/json" http://localhost:8000/api/private
+> ```
+> - `/api/public` should return `{"message":"Public endpoint - no authentication required"}`
+> - `/api/private` should return HTTP 401
+>
+> **Important:** The `-H "Accept: application/json"` header is required. Without it, Laravel's `Authenticate` middleware returns a 302 redirect instead of 401.
+>
+> If both pass, the guard is working. Kill the background server when done:
+> ```bash
+> kill %1 2>/dev/null
+> ```
+>
+> **Failcheck:** If the server fails to start or responses are unexpected, check that `config/auth0.php` exists and `.env` has `AUTH0_DOMAIN` and `AUTH0_AUDIENCE` set. After 5-6 failed iterations, use `AskUserQuestion`.
+
+> **Agent instruction: STOP - ask after basic tests pass.**
+>
+> Once public/401 tests pass, ask the user:
+>
+> > "Your API is set up and the guard is working (public returns 200, private returns 401 without a token). Would you like me to help you set up testing with a real access token?
+> > 1. **Yes** - I'll help you configure an M2M application to get test tokens.
+> > 2. **No** - I'm done for now.
+> >
+> > Which do you prefer?"
+>
+> Do NOT proceed with M2M/token setup unless the user says yes.
+
+> **Agent instruction (M2M app setup - only if user wants testing):**
+>
+> If the user chose to set up testing, ask:
+>
+> > "To test your protected endpoints, you need a Machine-to-Machine (M2M) application authorized to request tokens for this API.
+> > 1. **Create new** - I'll create a new M2M application and authorize it for this API.
+> > 2. **Use existing** - You already have an M2M application. Provide the Client ID and I'll authorize it for this API.
+> >
+> > Which do you prefer? (1 = Create new / 2 = Use existing)"
+>
+> Do NOT proceed until the user answers.
+>
+> **If the user chose "Create new":**
+> ```bash
+> auth0 apps create \
+>   --name "${PWD##*/} (Test App)" \
+>   --type m2m \
+>   --no-input --json
+> ```
+> Parse JSON with `jq` to extract `client_id`. Do NOT use `--reveal-secrets`; instead, use only the `client_id` — the client secret is not needed for the token flow below.
+> Then create a client grant:
+> ```bash
+> auth0 api post "client-grants" --data '{
+>   "client_id": "<CLIENT_ID>",
+>   "audience": "<API_IDENTIFIER>",
+>   "scope": ["<SCOPES>"]
+> }'
+> ```
+>
+> **If the user chose "Use existing":**
+> Ask for Client ID. Create a client grant (409 conflict = already authorized, fine).
+
+> **Agent instruction (token isolation — critical):**
+>
+> The agent must never directly see or display access token values.
+> - Do NOT run `auth0 test token` on its own
+> - Do NOT ask the user to paste their token
+> - Do NOT echo or store the token value
+>
+> **Secure testing (single-command chain):**
+> ```bash
+> php artisan serve &
+> sleep 2
+> TEST_TOKEN=$(auth0 test token <M2M_CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2> 2>/dev/null | grep -o 'ey[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*') && \
+> [ -n "$TEST_TOKEN" ] && echo "Token acquired (${#TEST_TOKEN} chars)" && \
+> curl -s -H "Accept: application/json" -H "Authorization: Bearer $TEST_TOKEN" http://localhost:8000/api/private
+> kill %1 2>/dev/null
+> ```
+>
+> **If the user does NOT ask to test**, provide commands for them to run manually:
+> ```bash
+> auth0 test token <CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2>
+> curl -H "Accept: application/json" -H "Authorization: Bearer <PASTE_TOKEN_HERE>" http://localhost:8000/api/private
+> ```
+
+Start the server:
+
+```bash
+php artisan serve
+```
+
+Test public endpoint (no token needed):
+
+```bash
+curl -H "Accept: application/json" http://localhost:8000/api/public
+```
+
+Test protected endpoint without token (should return 401):
+
+```bash
+curl -H "Accept: application/json" http://localhost:8000/api/private
+```
+
+Note: The `Accept: application/json` header is required. Without it, Laravel redirects (302) instead of returning 401.
+
+Test protected endpoint with token:
+
+```bash
+curl http://localhost:8000/api/private \
+  -H "Accept: application/json" \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+```
+
+Get a test token via Auth0 Dashboard -> APIs -> Test tab, or via the M2M flow described above.
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using `auth0.authenticator` driver for API routes | API guard must use `auth0.authorizer` - `auth0.authenticator` is for session-based web apps |
+| Using `auth:web` middleware for API routes | Use `auth:auth0-api` to specify the API guard |
+| Created an Application instead of an API in Auth0 | Must create an **API** resource (Dashboard -> Applications -> APIs) |
+| Passing `domain` with `https://` prefix | Use bare domain: `tenant.us.auth0.com` not `https://tenant.us.auth0.com` |
+| Using `auth0/auth0-php` directly | Use `auth0/login` which wraps the SDK with Laravel guards and middleware |
+| Not publishing config | Run `php artisan vendor:publish --tag=auth0` before configuring |
+| Missing `AUTH0_AUDIENCE` in `.env` | Required for token validation - without it, tokens can't be verified against the correct audience |
+| Using `$request->user()` without guard name | Defaults to the `web` guard - use `auth('auth0-api')->user()` or `$request->user('auth0-api')` |
+| Checking `$user->scope` as a string | The `scope` claim in JWTs is space-separated - use `hasScope()` instead of string comparison |
+| Calling `hasPermission()` without enabling RBAC | Must enable "Add Permissions in the Access Token" in Auth0 Dashboard -> APIs -> Settings |
+| Using ID tokens for API auth | Must use **access tokens** - ID tokens are for the client app |
+| Setting `configuration => 'web'` on the API guard | Must be `'api'` which maps to the `STRATEGY_API` config in `config/auth0.php` |
+| Testing with `curl` without `Accept: application/json` header | Laravel returns 302 redirect instead of 401 - always send `Accept: application/json` for API requests |
+| `hasScope()` returns false for scopes not defined on the API | Scopes must be defined on the API resource in Auth0 Dashboard - requesting a scope in the token request does not grant it unless defined |
+| `hasPermission()` returns false with M2M tokens | RBAC permissions are only embedded in tokens from user-based flows (Authorization Code), not client-credentials grants |
+| `routes/api.php` missing in Laravel 11+ | Run `php artisan install:api` to scaffold API routing - Laravel 11 does not include it by default |
+
+---
+
+## Key SDK Methods
+
+| Method | Returns | Purpose |
+|--------|---------|---------|
+| `auth('auth0-api')->user()` | `?StatelessUser` | Returns authenticated user or `null` |
+| `auth('auth0-api')->check()` | `bool` | Whether request has a valid token |
+| `auth('auth0-api')->hasScope($scope)` | `bool` | Check if token has a specific scope |
+| `auth('auth0-api')->hasPermission($perm)` | `bool` | Check if token has a specific RBAC permission |
+| `auth('auth0-api')->id()` | `?string` | Returns the `sub` claim directly |
+| `$user->getAuthIdentifier()` | `int\|string\|null` | Returns `sub` claim |
+| `$user->getAttribute('key')` | `mixed` | Returns any claim value |
+| `$user->jsonSerialize()` | `array` | Returns all claims as array |
+| `auth('auth0-api')->getCredential()` | `?CredentialEntity` | Full credential with decoded token data |
+
+---
+
+## Related Skills
+
+- Laravel web apps with login/logout (session-based auth) → the Auth0 integration workflow for Laravel web apps
+- Plain PHP APIs without Laravel → the Auth0 integration workflow for plain PHP APIs
+- Initial Auth0 setup → run the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- Manage Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+
+---
+
+## Quick Reference
+
+**Guard configuration (`config/auth.php`):**
+```php
+'guards' => [
+    'auth0-api' => [
+        'driver' => 'auth0.authorizer',
+        'provider' => 'auth0-provider',
+        'configuration' => 'api',
+    ],
+],
+'providers' => [
+    'auth0-provider' => [
+        'driver' => 'auth0.provider',
+        'repository' => 'auth0.repository',
+    ],
+],
+```
+
+**Route protection:**
+```php
+Route::middleware('auth:auth0-api')->group(function () {
+    Route::get('/resource', fn() => response()->json([...]));
+});
+```
+
+**Scope/permission checks:**
+```php
+$guard = auth('auth0-api');
+$guard->hasScope('read:messages');       // checks scope claim
+$guard->hasPermission('delete:users');   // checks permissions claim (RBAC)
+```
+
+**User claims:**
+```php
+$user = auth('auth0-api')->user();
+$user->getAuthIdentifier();   // sub
+$user->email;                 // any claim via __get
+$user->getAttribute('iss');   // explicit claim access
+```
+
+**Environment variables:**
+- `AUTH0_DOMAIN` - Auth0 tenant domain (e.g. `tenant.us.auth0.com`)
+- `AUTH0_AUDIENCE` - API identifier (e.g. `https://api.example.com`)
+
+**Common Use Cases:**
+- Protect routes -> `auth:auth0-api` middleware (see Step 7)
+- Scope enforcement -> `hasScope()` (see Step 8)
+- Permission enforcement -> `hasPermission()` (see Step 8)
+- Advanced configuration -> API Reference (see below)
+
+---
+
+## Detailed Documentation
+
+- **Setup Guide** (see below) - Auth0 CLI setup, environment configuration, getting test tokens
+- **Integration Guide** (see below) - Scopes, permissions, CORS, custom user repositories, error handling, multi-guard
+- **API Reference** (see below) - Complete AuthorizationGuard API, StatelessUser, CredentialEntity, configuration options
+
+---
+
+## References
+
+- [Auth0 Laravel API Quickstart](https://auth0.com/docs/quickstart/backend/laravel)
+- [SDK GitHub Repository](https://github.com/auth0/laravel-auth0)
+- [SDK on Packagist](https://packagist.org/packages/auth0/login)
+- [Access Tokens Guide](https://auth0.com/docs/secure/tokens/access-tokens)
diff --git a/main/.mintlify/skills/auth0/references/framework-laravel/index.md b/main/.mintlify/skills/auth0/references/framework-laravel/index.md
new file mode 100644
index 0000000000..fbc93d71be
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-laravel/index.md
@@ -0,0 +1,319 @@
+# Auth0 Laravel
+
+> Ported from auth0/auth0-laravel skill.
+
+---
+
+
+# Auth0 Laravel Web App Integration
+
+Add login, logout, and user profile to a Laravel web application using `auth0/login` (Laravel Auth0 SDK).
+
+---
+
+## Prerequisites
+
+- Laravel 11+ application
+- PHP 8.2+ with extensions: `mbstring`, `openssl`, `json`
+- Composer installed
+- Auth0 Regular Web Application configured (not an API - must be an Application)
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+| Scenario | Use Instead |
+|----------|-------------|
+| Laravel API with JWT Bearer validation | the Auth0 integration workflow for Laravel (API) — stateless token guard |
+| Plain PHP (no framework) web app | the Auth0 integration workflow for plain PHP |
+| Plain PHP API | the Auth0 integration workflow for plain PHP (API) |
+| Single Page Applications | the Auth0 integration workflow for React, Vue, or Angular |
+| Next.js applications | the Auth0 integration workflow for Next.js |
+| Node.js web apps | the Auth0 integration workflow for Express or Fastify |
+| Flask web apps | the Auth0 integration workflow for Flask |
+
+---
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+composer require auth0/login
+```
+
+The `auth0/login` package requires `auth0/auth0-php` (v8.19+) and will install it automatically. It also requires a PSR-18 HTTP client - if you don't already have one, install Guzzle:
+
+```bash
+composer require guzzlehttp/guzzle guzzlehttp/psr7
+```
+
+### 2. Publish Configuration
+
+```bash
+php artisan vendor:publish --tag=auth0
+```
+
+This creates `config/auth0.php` with guard, middleware, and route configuration.
+
+### 3. Configure Environment
+
+Add to your `.env`:
+
+```bash
+APP_URL=http://localhost:8000
+AUTH0_DOMAIN=your-tenant.us.auth0.com
+AUTH0_CLIENT_ID=your_client_id
+AUTH0_CLIENT_SECRET=your_client_secret
+AUTH0_AUDIENCE=https://your-api-identifier
+AUTH0_REDIRECT_URI=${APP_URL}/callback
+```
+
+`AUTH0_DOMAIN` is your Auth0 tenant domain (without `https://`). `AUTH0_CLIENT_ID` and `AUTH0_CLIENT_SECRET` come from your Auth0 Application settings. `AUTH0_AUDIENCE` must be set to an API identifier registered in Auth0 (Auth0 Dashboard > Applications > APIs) - without it, Auth0 returns opaque access tokens that the SDK cannot decode, causing a crash on session restore. The SDK uses `APP_KEY` as the cookie secret by default - no separate secret needed.
+
+**Important:** Ensure `APP_URL` includes the port if using the built-in dev server (`http://localhost:8000`). Fresh Laravel installs default to `http://localhost` (no port) which causes callback URL mismatches.
+
+### 4. Configure Auth0 Dashboard
+
+In your Auth0 Application settings:
+- **Application Type**: Regular Web Application
+- **Allowed Callback URLs**: `http://localhost:8000/callback`
+- **Allowed Logout URLs**: `http://localhost:8000`
+
+### 5. Configure Auth Guards
+
+Update `config/auth.php` to use Auth0 guards:
+
+```php
+'guards' => [
+    'web' => [
+        'driver' => 'auth0.authenticator',
+        'provider' => 'auth0-provider',
+        'configuration' => 'web',
+    ],
+],
+
+'providers' => [
+    'auth0-provider' => [
+        'driver' => 'auth0.provider',
+        'repository' => 'auth0.repository',
+    ],
+],
+```
+
+The `configuration` key maps to the guard definition in `config/auth0.php` (`web` uses `STRATEGY_REGULAR` with session-based auth). We override the default `web` guard so that Laravel's built-in `auth` middleware and `auth()->user()` work without specifying a guard name. The SDK also auto-registers an `auth0-session` guard with identical config, but overriding `web` is simpler.
+
+### 6. Routes Are Auto-Registered
+
+The SDK automatically registers these routes when `registerAuthenticationRoutes` is `true` in `config/auth0.php`:
+
+- `GET /login` - Redirects to Auth0 Universal Login
+- `GET /callback` - Handles OAuth callback, exchanges code for tokens
+- `GET /logout` - Destroys session and redirects to Auth0 logout
+
+No manual route definitions needed for the auth flow.
+
+### 7. Add Protected Routes
+
+In `routes/web.php`:
+
+```php
+use Illuminate\Support\Facades\Route;
+
+Route::get('/', function () {
+    return view('home', ['user' => auth()->user()]);
+});
+
+Route::middleware('auth')->group(function () {
+    Route::get('/profile', function () {
+        return view('profile', ['user' => auth()->user()]);
+    });
+});
+```
+
+The standard `auth` middleware works with the Auth0 guard. Unauthenticated users are redirected to `/login`.
+
+### 8. Create Views
+
+Create `resources/views/home.blade.php`:
+
+```blade
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Home</title>
+</head>
+<body>
+    @if($user)
+        <h1>Welcome, {{ $user->name }}!</h1>
+        <p><a href="/profile">Profile</a></p>
+        <p><a href="/logout">Logout</a></p>
+    @else
+        <h1>Welcome</h1>
+        <p><a href="/login">Login</a></p>
+    @endif
+</body>
+</html>
+```
+
+Create `resources/views/profile.blade.php`:
+
+```blade
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Profile</title>
+</head>
+<body>
+    <h1>{{ $user->name }}</h1>
+    <p>Email: {{ $user->email }}</p>
+    <img src="{{ $user->picture }}" alt="avatar" width="100" />
+    <hr>
+    <h2>User Claims</h2>
+    <pre>{{ json_encode($user->jsonSerialize(), JSON_PRETTY_PRINT) }}</pre>
+    <p><a href="/">Home</a> | <a href="/logout">Logout</a></p>
+</body>
+</html>
+```
+
+### 9. Test Authentication
+
+```bash
+php artisan serve
+```
+
+Visit `http://localhost:8000` and click Login.
+
+**Important:** Always access the app via `http://localhost:8000` (not `http://127.0.0.1:8000`). The callback URL uses `localhost`, so the session cookie must be set for `localhost` to persist across the Auth0 login redirect. Using `127.0.0.1` causes an "Invalid state" error because the session cookie won't be sent to the `localhost` callback URL.
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using `auth0/auth0-php` directly in Laravel | Use `auth0/login` which wraps the SDK with Laravel guards, middleware, and routes |
+| App created as SPA type in Auth0 Dashboard | Must be Regular Web Application for server-side session auth |
+| Missing callback URL in Auth0 Dashboard | Add `http://localhost:8000/callback` to Allowed Callback URLs |
+| Missing logout URL in Auth0 Dashboard | Add `http://localhost:8000` to Allowed Logout URLs |
+| Not publishing the config | Run `php artisan vendor:publish --tag=auth0` before configuring |
+| Using wrong guard driver name | Driver is `auth0.authenticator` (not `auth0` or `auth0.guard`) |
+| Forgetting to set `APP_KEY` | Run `php artisan key:generate` - the SDK uses this as cookie secret |
+| Calling `Auth0::getCredentials()` directly | Use Laravel's `auth()->user()` - the SDK integrates via guards |
+| Manually defining `/login`, `/callback`, `/logout` routes | Routes are auto-registered by the service provider |
+| Setting `AUTH0_DOMAIN` with `https://` prefix | Use bare domain: `tenant.us.auth0.com` not `https://tenant.us.auth0.com` |
+| Using `$request->user()` without middleware | Only available in routes with the `auth` middleware applied |
+| Missing `AUTH0_AUDIENCE` env var | Without an audience, Auth0 returns opaque tokens the SDK cannot parse - causes "JWT string must contain two dots" crash |
+| Visiting `http://127.0.0.1:8000` instead of `http://localhost:8000` | Session cookies set for `127.0.0.1` won't be sent to the `localhost` callback - causes "Invalid state" error |
+| Using `$user->getName()` or `$user->getEmail()` | `StatefulUser` uses magic `__get` - use `$user->name`, `$user->email`, `$user->picture` |
+
+---
+
+## Key SDK Methods
+
+| Method | Usage | Purpose |
+|--------|-------|---------|
+| `auth()->user()` | In routes/controllers | Returns the authenticated `StatefulUser` or `null` |
+| `auth()->check()` | In routes/controllers/views | Returns `true` if user is authenticated |
+| `auth()->guard('web')` | When using multiple guards | Gets a specific Auth0 guard instance |
+| `$user->name` | On user object | User's display name (via `__get` magic) |
+| `$user->email` | On user object | User's email (via `__get` magic) |
+| `$user->picture` | On user object | User's avatar URL (via `__get` magic) |
+| `$user->getAuthIdentifier()` | On user object | Returns the Auth0 `sub` claim |
+| `$user->getAttribute('claim')` | On user object | Returns any claim value explicitly |
+| `$user->jsonSerialize()` | On user object | Returns all user claims as array |
+
+---
+
+## User Object
+
+The authenticated user is a `StatefulUser` instance implementing Laravel's `Authenticatable` contract. It uses `__get` magic for property-style access to claims:
+
+```php
+$user = auth()->user();
+
+$user->name;                   // display name (via __get)
+$user->email;                  // email address (via __get)
+$user->picture;                // avatar URL (via __get)
+$user->email_verified;         // any claim via property access
+$user->getAuthIdentifier();   // Auth0 'sub' (e.g. 'auth0|abc123')
+$user->getAttribute('sub');    // explicit claim access
+$user->jsonSerialize();        // all claims as array
+```
+
+Access any ID token claim as a property: `$user->nickname`, `$user->updated_at`, `$user->sub`, etc. For explicit access, use `$user->getAttribute('claim_name')`.
+
+---
+
+## Related Skills
+
+- Protecting Laravel API routes with JWT Bearer token validation → the Auth0 integration workflow for Laravel APIs
+- Plain PHP web apps without a framework → the Auth0 integration workflow for plain PHP
+- Initial Auth0 setup → run the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- Manage Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+
+---
+
+## Quick Reference
+
+**Guard configuration (`config/auth.php`):**
+```php
+'guards' => [
+    'web' => [
+        'driver' => 'auth0.authenticator',
+        'provider' => 'auth0-provider',
+        'configuration' => 'web',
+    ],
+],
+'providers' => [
+    'auth0-provider' => [
+        'driver' => 'auth0.provider',
+        'repository' => 'auth0.repository',
+    ],
+],
+```
+
+**Route protection:**
+```php
+Route::middleware('auth')->group(function () {
+    Route::get('/dashboard', [DashboardController::class, 'index']);
+});
+```
+
+**Check auth in Blade:**
+```blade
+@auth
+    <p>Hello, {{ auth()->user()->name }}</p>
+@else
+    <a href="/login">Login</a>
+@endauth
+```
+
+**Environment variables:**
+- `APP_URL` - Application URL with port (e.g. `http://localhost:8000`)
+- `AUTH0_DOMAIN` - Auth0 tenant domain (e.g. `tenant.us.auth0.com`)
+- `AUTH0_CLIENT_ID` - Application client ID
+- `AUTH0_CLIENT_SECRET` - Application client secret
+- `AUTH0_AUDIENCE` - API identifier (required for JWT access tokens)
+- `AUTH0_REDIRECT_URI` - Callback URL (defaults to `${APP_URL}/callback`)
+- `APP_KEY` - Laravel app key, used as cookie encryption secret
+
+---
+
+## Detailed Documentation
+
+- **Setup Guide** (see below) - Automated setup scripts, environment configuration, Auth0 CLI usage
+- **Integration Guide** (see below) - Scope checking, calling APIs, events, custom user models, session management
+- **API Reference** (see below) - Complete guard API, configuration options, user model methods
+
+---
+
+## References
+
+- [Auth0 Laravel Quickstart](https://auth0.com/docs/quickstart/webapp/laravel)
+- [SDK GitHub Repository](https://github.com/auth0/laravel-auth0)
+- [SDK on Packagist](https://packagist.org/packages/auth0/login)
diff --git a/main/.mintlify/skills/auth0/references/framework-maui/index.md b/main/.mintlify/skills/auth0/references/framework-maui/index.md
new file mode 100644
index 0000000000..2a9028acc6
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-maui/index.md
@@ -0,0 +1,250 @@
+# Auth0 .NET MAUI
+
+> Ported from auth0/auth0-maui skill.
+
+---
+
+
+# auth0-maui Integration
+
+Add Auth0 authentication to .NET MAUI applications targeting iOS, Android, macOS, and Windows. This skill integrates the `Auth0.OidcClient.MAUI` NuGet package which uses the system browser via MAUI's `WebAuthenticator` for secure OIDC-based login and logout flows with PKCE.
+
+> **Agent instruction:** Before providing SDK setup instructions, fetch the latest MAUI release version by running:
+> ```bash
+> gh api repos/auth0/auth0-oidc-client-net/releases --jq '[.[] | select(.tag_name | startswith("maui-")) | .tag_name | ltrimstr("maui-")] | .[0]'
+> ```
+> Use the returned version in all dependency lines instead of any hardcoded version below.
+
+## Critical rules
+
+- **ALWAYS** set `Scope = "openid profile email offline_access"` on `Auth0ClientOptions` — the `offline_access` scope is REQUIRED to receive a refresh token for silent token renewal; without it the user must re-authenticate every time the access token expires.
+- **ALWAYS** persist the refresh token with `SecureStorage.Default.SetAsync("refresh_token", ...)` after login, restore it with `SecureStorage.Default.GetAsync("refresh_token")` on app startup, and clear it with `SecureStorage.Default.Remove("refresh_token")` on logout.
+- On Windows you MUST do both: register the custom URL scheme in `Platforms/Windows/Package.appxmanifest` (`<uap:Extension Category="windows.protocol"><uap:Protocol Name="myapp"/></uap:Extension>` inside `<Extensions>`), AND call `Activator.Default.CheckRedirectionActivation()` as the first line of the `App()` constructor in `Platforms/Windows/App.xaml.cs`, before `InitializeComponent()`. Without both, Windows will not intercept the callback URL.
+
+## Prerequisites
+
+- .NET 8.0 SDK or later
+- Visual Studio 2022 (17.8+) with MAUI workload, or JetBrains Rider with MAUI support
+- For iOS: macOS with Xcode 15+
+- For Android: Android SDK API 33+ (net8.0) or API 34+ (net9.0)
+- For Windows: Windows 10 (10.0.19041.0)+
+- Auth0 account with a Native application configured
+- Node.js 20+ (for Auth0 CLI automated setup)
+
+## When NOT to Use
+
+| Use Case | Use instead |
+|----------|------------------|
+| ASP.NET Core server-side web app | the Auth0 integration workflow for ASP.NET Core |
+| ASP.NET Core Web API (JWT validation) | the Auth0 integration workflow for ASP.NET Core Web API |
+| React Native mobile app | the Auth0 integration workflow for React Native |
+| iOS-only Swift app | the Auth0 integration workflow for Swift (iOS/macOS) |
+| Android-only Kotlin app | the Auth0 integration workflow for Android |
+| Expo React Native app | the Auth0 integration workflow for Expo |
+
+## Quick Start Workflow
+
+> **Agent instruction:** Before starting, examine the user's project:
+> 1. Identify the .NET version from the `.csproj` file (`TargetFrameworks`)
+> 2. Check for existing authentication implementations — search for existing login/logout handlers and hook into them if found
+> 3. Note the project's namespace and directory conventions
+> 4. Look for existing `Auth0Client` or `Auth0ClientOptions` usage to avoid duplicate configuration
+
+1. **Install SDK**: `dotnet add package Auth0.OidcClient.MAUI`
+2. **Configure Auth0**: See the Setup Guide section (below) for automatic or manual configuration.
+3. **Integrate authentication**: Add `Auth0Client` instantiation and wire login/logout to UI actions.
+   - **Important:** Always set `Scope = "openid profile email offline_access"` — the `offline_access` scope is required to receive a refresh token for silent token renewal.
+4. **Persist tokens with SecureStorage**: After login, store the refresh token using `await SecureStorage.Default.SetAsync("refresh_token", loginResult.RefreshToken)`. On app startup, restore the session with `RefreshTokenAsync`. Clear on logout with `SecureStorage.Default.Remove("refresh_token")`.
+5. **Register URL scheme**: Configure platform-specific callback handling:
+   - Android: Create `WebAuthenticatorActivity` with IntentFilter for your custom scheme (e.g., `myapp`)
+   - Windows (two steps required): (1) Add `<uap:Extension Category="windows.protocol"><uap:Protocol Name="myapp"/></uap:Extension>` to `Platforms/Windows/Package.appxmanifest`, AND (2) call `Activator.Default.CheckRedirectionActivation()` in `Platforms/Windows/App.xaml.cs`
+   - iOS/macOS: No extra configuration needed
+6. **Build and verify**: `dotnet build`
+
+> **Agent instruction:** When writing the Auth0Client configuration:
+> - **Always** include `offline_access` in the Scope string — without it, no refresh token is returned and the user must re-authenticate every time the access token expires.
+> - **Always** implement token persistence using `SecureStorage.Default.SetAsync("refresh_token", ...)` after login and `SecureStorage.Default.GetAsync("refresh_token")` on app startup to restore sessions silently.
+> - Clear stored tokens on logout with `SecureStorage.Default.Remove("refresh_token")`.
+> - **Always** create/update `Platforms/Windows/Package.appxmanifest` to register the custom URL scheme protocol. Without this, Windows will not intercept the callback URL after authentication. Add a `<uap:Extension Category="windows.protocol"><uap:Protocol Name="myapp"/></uap:Extension>` inside the `<Extensions>` element of the `<Application>` node.
+> - **Always** add `CheckRedirectionActivation()` in `Platforms/Windows/App.xaml.cs` as the first line in the constructor, before `InitializeComponent()`.
+>
+> After writing configuration and code, verify the build succeeds:
+> ```bash
+> dotnet build
+> ```
+> If the build fails, attempt to fix the issue. After 5-6 failed attempts, ask the user for help.
+
+## Callback URL Configuration
+
+The MAUI SDK uses a custom URL scheme for callbacks. The default pattern is:
+
+```text
+myapp://callback
+```
+
+Unlike other Auth0 native SDKs that use `https://{domain}/{platform}/{bundleId}/callback` or
+`{bundleId}.auth0://{domain}/ios/{bundleId}/callback` patterns, MAUI uses a simpler custom scheme
+approach. You can customize the scheme (e.g., `com.mycompany.myapp://callback`). Whatever scheme you choose must be:
+1. Registered in Auth0 Dashboard under **Allowed Callback URLs** and **Allowed Logout URLs**
+2. Configured in the platform-specific callback handler (Android `IntentFilter`, Windows `Package.appxmanifest`)
+3. Set in `Auth0ClientOptions.RedirectUri` and `Auth0ClientOptions.PostLogoutRedirectUri`
+
+> **Note:** For production apps, use a reverse-domain scheme (e.g., `com.yourcompany.yourapp://callback`) to reduce the risk of URL scheme hijacking.
+
+## Done When
+
+- [ ] `Auth0.OidcClient.MAUI` package installed
+- [ ] `Auth0Client` configured with Domain, ClientId, and `Scope` including `offline_access`
+- [ ] URL scheme registered on Android (WebAuthenticatorCallbackActivity) and Windows (Package.appxmanifest)
+- [ ] Callback URL (`myapp://callback`) added to Auth0 Dashboard Allowed Callback URLs and Allowed Logout URLs
+- [ ] Login/logout flow working
+- [ ] Refresh token persisted via `SecureStorage.Default.SetAsync` after login
+- [ ] Session restoration implemented via `SecureStorage.Default.GetAsync` + `RefreshTokenAsync` on app startup
+- [ ] Build succeeds with no errors
+- [ ] Tested on physical device or emulator/simulator
+
+## Detailed Documentation
+
+- **Setup Guide** (see below) — Auth0 tenant configuration, SDK installation, platform-specific callback setup
+- **Integration Patterns** (see below) — Login/logout flows, token refresh, user profile, error handling, MVVM patterns
+- **API Reference & Testing** (see below) — Full `Auth0ClientOptions` reference, claims, testing checklist, troubleshooting
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| App type not set to **Native** in Auth0 Dashboard | Change application type to "Native" in Dashboard settings |
+| Missing callback URL in Auth0 Dashboard | Add `myapp://callback` (or your scheme) to Allowed Callback URLs AND Allowed Logout URLs |
+| Android: Missing `WebAuthenticatorCallbackActivity` | Create activity class with `[IntentFilter]` matching your callback scheme |
+| Windows: Not calling `CheckRedirectionActivation()` | Add `Activator.Default.CheckRedirectionActivation()` at start of Windows `App.xaml.cs`, before `InitializeComponent()` |
+| Using `https://` prefix in Domain | Domain should be hostname only (e.g., `tenant.auth0.com`, not `https://tenant.auth0.com`) |
+| Not requesting `offline_access` scope for token refresh | Add `offline_access` to `Scope` in `Auth0ClientOptions` to get a refresh token |
+| RedirectUri/PostLogoutRedirectUri not matching Dashboard | Ensure the exact URI (scheme + path) matches what's configured in Auth0 Dashboard |
+| Not registering URL scheme on Android/Windows | Register the custom URL scheme in platform-specific config (see Platform setup step) |
+| Storing tokens in plain text | Use `SecureStorage` from MAUI Essentials for persisting refresh tokens |
+
+## Testing Notes
+
+> **Agent instruction:** Remind the user to test on a physical device in addition to emulators/simulators. Some WebAuthenticator behaviors (system browser integration, URL scheme interception) may differ on physical devices vs. emulators. Test the full login → callback → token flow on real hardware before shipping.
+
+**Testing Checklist:**
+- Login flow: System browser opens → authenticate → returns to app
+- Logout flow: Browser opens → session cleared → returns to app
+- Token refresh: `RefreshTokenAsync` with stored refresh token works
+- Cancel: User cancels login → app handles `UserCancel` gracefully
+- Physical device: Test on real iOS/Android device (not just simulator)
+- Offline: Verify token refresh works when the app is restarted
+- Multi-platform: Test on at least one mobile platform (iOS or Android) and Windows
+
+## Related Skills
+
+All of this lives in the one `auth0` skill — just describe what you need (e.g. "add MFA", "protect my API").
+
+## Quick Reference
+
+```csharp
+using Auth0.OidcClient;
+
+// Initialize client
+var client = new Auth0Client(new Auth0ClientOptions
+{
+    Domain = "YOUR_AUTH0_DOMAIN",
+    ClientId = "YOUR_AUTH0_CLIENT_ID",
+    RedirectUri = "myapp://callback",
+    PostLogoutRedirectUri = "myapp://callback",
+    Scope = "openid profile email offline_access"
+});
+
+// Login — opens system browser
+var loginResult = await client.LoginAsync();
+if (!loginResult.IsError)
+{
+    var user = loginResult.User;
+    var accessToken = loginResult.AccessToken;
+    var idToken = loginResult.IdentityToken;
+    var refreshToken = loginResult.RefreshToken;
+
+    // Access user claims
+    var name = user.FindFirst("name")?.Value;
+    var email = user.FindFirst("email")?.Value;
+
+    // Persist refresh token securely for session restoration
+    if (!string.IsNullOrEmpty(refreshToken))
+        await SecureStorage.Default.SetAsync("refresh_token", refreshToken);
+}
+
+// Logout — clears Auth0 session and stored tokens
+await client.LogoutAsync();
+SecureStorage.Default.Remove("refresh_token");
+
+// Restore session on app startup (no user interaction needed)
+var savedToken = await SecureStorage.Default.GetAsync("refresh_token");
+if (!string.IsNullOrEmpty(savedToken))
+{
+    var refreshResult = await client.RefreshTokenAsync(savedToken);
+    if (!refreshResult.IsError)
+    {
+        var newAccessToken = refreshResult.AccessToken;
+        // Update stored token if rotated
+        if (!string.IsNullOrEmpty(refreshResult.RefreshToken))
+            await SecureStorage.Default.SetAsync("refresh_token", refreshResult.RefreshToken);
+    }
+    else
+    {
+        // Refresh failed — clear and require re-login
+        SecureStorage.Default.Remove("refresh_token");
+    }
+}
+
+// Get user info from /userinfo endpoint
+var userInfo = await client.GetUserInfoAsync(accessToken);
+
+// Login with extra parameters (organization, audience, connection)
+var orgLogin = await client.LoginAsync(new { organization = "org_abc123" });
+var apiLogin = await client.LoginAsync(new { audience = "https://my-api.example.com" });
+```
+
+### Android Callback Activity (Required)
+
+```csharp
+[Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)]
+[IntentFilter(new[] { Intent.ActionView },
+    Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
+    DataScheme = CALLBACK_SCHEME)]
+public class WebAuthenticatorActivity : Microsoft.Maui.Authentication.WebAuthenticatorCallbackActivity
+{
+    const string CALLBACK_SCHEME = "myapp";
+}
+```
+
+### Windows Platform Setup (Required — Both Steps)
+
+**Step 1: Register protocol in `Platforms/Windows/Package.appxmanifest`:**
+
+```xml
+<Extensions>
+  <uap:Extension Category="windows.protocol">
+    <uap:Protocol Name="myapp"/>
+  </uap:Extension>
+</Extensions>
+```
+
+**Step 2: Handle redirection in `Platforms/Windows/App.xaml.cs`:**
+
+```csharp
+// In Platforms/Windows/App.xaml.cs
+public App()
+{
+    if (Auth0.OidcClient.Platforms.Windows.Activator.Default.CheckRedirectionActivation())
+        return;
+    this.InitializeComponent();
+}
+```
+
+## References
+
+- [Auth0 MAUI Quickstart](https://auth0.com/docs/quickstart/native/maui)
+- [GitHub Repository](https://github.com/auth0/auth0-oidc-client-net)
+- [NuGet Package](https://www.nuget.org/packages/Auth0.OidcClient.MAUI)
+- [SDK API Documentation](https://auth0.github.io/auth0-oidc-client-net/documentation/intro.html)
+- [Auth0 Native App Documentation](https://auth0.com/docs/get-started/auth0-overview/create-applications/native-apps)
diff --git a/main/.mintlify/skills/auth0/references/framework-net-android/index.md b/main/.mintlify/skills/auth0/references/framework-net-android/index.md
new file mode 100644
index 0000000000..6c839845e9
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-net-android/index.md
@@ -0,0 +1,250 @@
+# Auth0 .NET Android
+
+> Ported from auth0/auth0-net-android skill.
+
+---
+
+
+# auth0-net-android Integration
+
+Add Auth0 authentication to .NET Android applications. This skill integrates the `Auth0.OidcClient.AndroidX` NuGet package which uses Chrome Custom Tabs for secure OIDC-based login and logout flows with PKCE.
+
+> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
+> ```bash
+> gh api repos/auth0/auth0-oidc-client-net/releases --jq '[.[] | select(.tag_name | startswith("androidx-")) | .tag_name | ltrimstr("androidx-")] | .[0]'
+> ```
+> Use the returned version in all dependency lines instead of any hardcoded version below.
+
+## Prerequisites
+
+- .NET 8.0 SDK or later
+- Visual Studio 2022 (17.8+) with .NET Android workload, or JetBrains Rider
+- Android SDK API 21+ (minimum), API 34+ recommended for net9.0-android
+- Auth0 account with a Native application configured
+- Node.js 20+ (for Auth0 CLI automated setup)
+
+## When NOT to Use
+
+| Use Case | Use instead |
+|----------|------------------|
+| .NET MAUI cross-platform app (iOS + Android + Windows) | the .NET MAUI integration workflow |
+| .NET iOS-only app | the .NET iOS integration workflow |
+| Android-only Kotlin app | the Android (Kotlin) integration workflow |
+| ASP.NET Core server-side web app | the ASP.NET Core integration workflow |
+| ASP.NET Core Web API (JWT validation) | the ASP.NET Core Web API integration workflow |
+| React Native mobile app | the React Native integration workflow |
+
+## Quick Start Workflow
+
+> **Agent instruction:** Before starting, examine the user's project:
+> 1. Identify the .NET version from the `.csproj` file (`TargetFramework`)
+> 2. Check for existing authentication implementations — search for existing login/logout handlers and hook into them if found (reuse existing UI elements like login buttons rather than creating duplicates)
+> 3. Note the project's namespace and package name from the `.csproj` or `AndroidManifest.xml`
+> 4. Look for existing `Auth0Client` or `Auth0ClientOptions` usage to avoid duplicate configuration
+
+1. **Install SDK**: `dotnet add package Auth0.OidcClient.AndroidX`
+2. **Configure Auth0**: See the Setup Guide section (below) for automatic or manual configuration.
+3. **Integrate authentication**: Add `Auth0Client` instantiation, configure the `IntentFilter` on your Activity, and wire login/logout to UI actions.
+4. **Handle callback**: Override `OnNewIntent` and call `ActivityMediator.Instance.Send(intent.DataString)` to complete the authentication flow.
+5. **Build and verify**: `dotnet build`
+
+> **Agent instruction:** When writing the Auth0Client configuration:
+> - Pass `this` (the Activity) as the second argument to `Auth0Client` constructor.
+> - **Always set `Scope = "openid profile email offline_access"`** — the `offline_access` scope is required to receive refresh tokens, enabling silent token renewal without re-prompting the user.
+> - The callback URL format is `YOUR_ANDROID_PACKAGE_NAME://YOUR_AUTH0_DOMAIN/android/YOUR_ANDROID_PACKAGE_NAME/callback` — all lowercase.
+> - The `DataScheme` in the `IntentFilter` must be lowercase or Android will not receive callbacks.
+> - Set `LaunchMode = LaunchMode.SingleTask` on the Activity to prevent duplicate instances. Do NOT use `SingleTop` — it does not correctly handle the callback redirect and will create duplicate Activity instances.
+> - The Activity should either extend `Auth0ClientActivity` OR manually override `OnNewIntent` and call `ActivityMediator.Instance.Send(intent.DataString)`.
+> - **Store tokens securely**: After successful login, persist `AccessToken` and `RefreshToken` using `SecureStorage` (MAUI/Essentials) or `EncryptedSharedPreferences` (AndroidX Security — requires `dotnet add package Xamarin.AndroidX.Security.SecurityCrypto`). Never store tokens in plain `SharedPreferences` or in-memory variables only.
+>
+> After writing configuration and code, verify the build succeeds:
+> ```bash
+> dotnet build
+> ```
+> If the build fails, attempt to fix the issue. After 5-6 failed attempts, ask the user for help.
+
+## WebAuth — How Authentication Works
+
+The SDK uses the WebAuth pattern via Chrome Custom Tabs (the system browser). When `LoginAsync()` is called, the SDK:
+
+1. Constructs the `/authorize` URL with PKCE parameters
+2. Opens Chrome Custom Tabs with the authorization URL
+3. After authentication, Auth0 redirects to the native callback URL
+4. The Android system matches the URL scheme and delivers it to your Activity via `OnNewIntent`
+5. `ActivityMediator` completes the token exchange
+
+This is the standard OAuth 2.0 Authorization Code flow with PKCE, recommended for native mobile applications.
+
+## Callback URL Configuration
+
+The native callback URL for .NET Android uses the package name as the scheme. The format is:
+
+```text
+YOUR_ANDROID_PACKAGE_NAME://YOUR_AUTH0_DOMAIN/android/YOUR_ANDROID_PACKAGE_NAME/callback
+```
+
+Where `YOUR_ANDROID_PACKAGE_NAME` is the Package Name for your application, such as `com.mycompany.myapplication`. For example: `com.mycompany.myapp://tenant.us.auth0.com/android/com.mycompany.myapp/callback`.
+
+> **Note:** Some Auth0 native SDKs use `https://{domain}/android/{package}/callback` as the callback URL format. The .NET Android SDK uses the package name as the URL scheme instead.
+
+Ensure that the Callback URL is in lowercase.
+
+This URL must be:
+1. Registered in Auth0 Dashboard under **Allowed Callback URLs** and **Allowed Logout URLs**
+2. Matched by the `IntentFilter` attributes (`DataScheme`, `DataHost`, `DataPathPrefix`) on your Activity
+
+## Done When
+
+- [ ] `Auth0.OidcClient.AndroidX` package installed (latest stable version)
+- [ ] `Auth0Client` configured with Domain, ClientId, and `Scope = "openid profile email offline_access"`
+- [ ] `IntentFilter` configured on Activity with correct DataScheme, DataHost, DataPathPrefix
+- [ ] `LaunchMode = LaunchMode.SingleTask` set on Activity
+- [ ] `OnNewIntent` handled with `ActivityMediator.Instance.Send(intent.DataString)`
+- [ ] Callback URL added to Auth0 Dashboard Allowed Callback URLs and Allowed Logout URLs
+- [ ] Tokens stored securely (SecureStorage or EncryptedSharedPreferences)
+- [ ] Login/logout flow working
+- [ ] Build succeeds with no errors
+
+## Detailed Documentation
+
+- **Setup Guide** (see below) — Auth0 tenant configuration, SDK installation, IntentFilter setup
+- **Integration Patterns** (see below) — Login/logout flows, token access, user profile, error handling
+- **API Reference & Testing** (see below) — Full `Auth0ClientOptions` reference, claims, testing checklist, troubleshooting
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| App type not set to **Native** in Auth0 Dashboard | Change application type to "Native" in Dashboard settings |
+| Missing callback URL in Auth0 Dashboard | Add `yourpackagename://{domain}/android/yourpackagename/callback` to Allowed Callback URLs AND Allowed Logout URLs |
+| `DataScheme` not lowercase | Android requires the scheme to be lowercase — use lowercase package name |
+| Missing `LaunchMode.SingleTask` | Set `LaunchMode = LaunchMode.SingleTask` on the Activity to prevent duplicate instances |
+| Not handling `OnNewIntent` | Override `OnNewIntent` and call `ActivityMediator.Instance.Send(intent.DataString)` |
+| Using `https://` prefix in Domain | Domain should be hostname only (e.g., `tenant.auth0.com`, not `https://tenant.auth0.com`) |
+| Not passing Activity context to Auth0Client | Pass `this` as second parameter: `new Auth0Client(options, this)` |
+| IntentFilter DataHost/DataPathPrefix mismatch | Ensure DataHost matches your Auth0 domain and DataPathPrefix is `/android/yourpackagename/callback` |
+| Missing `offline_access` scope | Always include `offline_access` in Scope to receive refresh tokens for silent renewal |
+| Using `LaunchMode.SingleTop` instead of `SingleTask` | Must use `LaunchMode.SingleTask` — `SingleTop` does not correctly handle the Auth0 callback redirect |
+| Storing tokens in plain SharedPreferences | Use `SecureStorage` or `EncryptedSharedPreferences` from AndroidX Security library |
+
+## Testing Notes
+
+> **Agent instruction:** Remind the user to test on a physical device in addition to emulators. Some WebAuth behaviors (Chrome Custom Tabs, URL scheme interception) may differ on physical devices vs. emulators. Test the full login → callback → token flow on real hardware before shipping.
+
+**Physical Device Testing:**
+- Login flow: Chrome Custom Tab opens → authenticate → returns to app
+- Callback: `OnNewIntent` fires with correct intent data
+- Logout flow: Browser opens → session cleared → returns to app
+- Cancel: User presses back → app handles `UserCancel` gracefully
+
+## Related Workflows
+
+- .NET MAUI cross-platform apps (iOS + Android + Windows) → the .NET MAUI integration workflow
+- .NET iOS-only apps → the .NET iOS integration workflow
+- Android-native Kotlin apps → the Android (Kotlin) integration workflow
+- ASP.NET Core server-side web apps → the ASP.NET Core integration workflow
+- ASP.NET Core Web API with JWT validation → the ASP.NET Core Web API integration workflow
+
+## Quick Reference
+
+```csharp
+using Auth0.OidcClient;
+
+var client = new Auth0Client(new Auth0ClientOptions
+{
+    Domain = "YOUR_AUTH0_DOMAIN",
+    ClientId = "YOUR_AUTH0_CLIENT_ID",
+    Scope = "openid profile email offline_access"
+}, this);
+```
+
+### Login
+
+```csharp
+var loginResult = await client.LoginAsync();
+```
+
+### Handle Errors
+
+```csharp
+var loginResult = await client.LoginAsync();
+
+if (loginResult.IsError)
+{
+    Debug.WriteLine($"An error occurred during login: {loginResult.Error}");
+}
+```
+
+### Access Tokens
+
+```csharp
+var loginResult = await client.LoginAsync();
+
+if (!loginResult.IsError)
+{
+    Debug.WriteLine($"Authentication successful.");
+}
+```
+
+### User Information
+
+```csharp
+if (!loginResult.IsError)
+{
+    Debug.WriteLine($"name: {loginResult.User.FindFirst(c => c.Type == "name")?.Value}");
+    Debug.WriteLine($"email: {loginResult.User.FindFirst(c => c.Type == "email")?.Value}");
+}
+```
+
+### List All Claims
+
+```csharp
+if (!loginResult.IsError)
+{
+    foreach (var claim in loginResult.User.Claims)
+    {
+        Debug.WriteLine($"{claim.Type} = {claim.Value}");
+    }
+}
+```
+
+### Logout
+
+```csharp
+BrowserResultType browserResult = await client.LogoutAsync();
+```
+
+### Activity with IntentFilter (Required)
+
+```csharp
+[Activity(Label = "AndroidSample", MainLauncher = true, Icon = "@drawable/icon",
+    LaunchMode = LaunchMode.SingleTask)]
+[IntentFilter(
+    new[] { Intent.ActionView },
+    Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
+    DataScheme = "YOUR_ANDROID_PACKAGE_NAME",
+    DataHost = "YOUR_AUTH0_DOMAIN",
+    DataPathPrefix = "/android/YOUR_ANDROID_PACKAGE_NAME/callback")]
+public class MainActivity : Activity
+{
+    // Code omitted
+}
+```
+
+### Handle Callback in OnNewIntent (Required)
+
+```csharp
+protected override async void OnNewIntent(Intent intent)
+{
+    base.OnNewIntent(intent);
+
+    Auth0.OidcClient.ActivityMediator.Instance.Send(intent.DataString);
+}
+```
+
+## References
+
+- [.NET Android & iOS Quickstart](https://auth0.com/docs/quickstart/native/net-android-ios)
+- [GitHub Repository](https://github.com/auth0/auth0-oidc-client-net)
+- [NuGet Package — Auth0.OidcClient.AndroidX](https://www.nuget.org/packages/Auth0.OidcClient.AndroidX)
+- [SDK API Documentation](https://auth0.github.io/auth0-oidc-client-net/documentation/intro.html)
diff --git a/main/.mintlify/skills/auth0/references/framework-net-ios/index.md b/main/.mintlify/skills/auth0/references/framework-net-ios/index.md
new file mode 100644
index 0000000000..7363eee605
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-net-ios/index.md
@@ -0,0 +1,177 @@
+# Auth0 .NET iOS
+
+> Ported from auth0/auth0-net-ios skill.
+
+---
+
+
+# auth0-net-ios Integration
+
+Add Auth0 authentication to .NET iOS applications. This skill integrates the `Auth0.OidcClient.iOS` NuGet package which uses `ASWebAuthenticationSession` for secure OIDC-based login and logout flows with PKCE.
+
+> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
+> ```bash
+> gh api repos/auth0/auth0-oidc-client-net/releases --jq '[.[] | select(.tag_name | startswith("ios-")) | .tag_name | ltrimstr("ios-")] | .[0]'
+> ```
+> Use the returned version in all dependency lines instead of any hardcoded version below.
+
+## Prerequisites
+
+- .NET 8.0 SDK or later (.NET 9 also supported — use `net9.0-ios` target framework)
+- JetBrains Rider or VS Code with C# Dev Kit (with iOS workload)
+- macOS with Xcode 15+
+- iOS 14.0+ deployment target
+- Auth0 account with a Native application configured
+- Node.js 20+ (for Auth0 CLI automated setup)
+
+## When NOT to Use
+
+| Use Case | Use instead |
+|----------|------------------|
+| .NET MAUI cross-platform app (iOS + Android + Windows) | the Auth0 integration workflow for .NET MAUI |
+| .NET Android-only app | the Auth0 integration workflow for .NET Android |
+| iOS-only Swift app | the Auth0 integration workflow for Swift |
+| ASP.NET Core server-side web app | the Auth0 integration workflow for ASP.NET Core |
+| ASP.NET Core Web API (JWT validation) | the Auth0 integration workflow for ASP.NET Core Web API |
+| React Native mobile app | the Auth0 integration workflow for React Native |
+
+## Quick Start Workflow
+
+> **Agent instruction:** Before starting, examine the user's project:
+> 1. Identify the .NET version from the `.csproj` file (`TargetFramework`)
+> 2. Check for existing authentication implementations — search for existing login/logout handlers and hook into them if found (reuse existing UI elements like login buttons rather than creating duplicates)
+> 3. Note the project's Bundle Identifier from `Info.plist` or `.csproj`
+> 4. Look for existing `Auth0Client` or `Auth0ClientOptions` usage to avoid duplicate configuration
+
+1. **Install SDK**: `dotnet add package Auth0.OidcClient.iOS`
+2. **Configure Auth0**: See the Setup Guide section (below) for automatic or manual configuration.
+3. **Integrate authentication**: Add `Auth0Client` instantiation, register the URL scheme in `Info.plist`, and wire login/logout to UI actions.
+4. **Handle callback**: Implement `OpenUrl` in `AppDelegate` and call `ActivityMediator.Instance.Send(url.AbsoluteString)`.
+5. **Build and verify**: `dotnet build`
+
+> **Agent instruction:** When writing the Auth0Client configuration:
+> - The iOS SDK does NOT require passing an Activity context — just `new Auth0Client(options)`.
+> - **Always set `Scope = "openid profile email offline_access"`** — the `offline_access` scope is required to receive refresh tokens, enabling silent token renewal without re-prompting the user.
+> - The callback URL is automatically derived from the Bundle Identifier: `{BundleId}://{domain}/ios/{BundleId}/callback`.
+> - The Bundle Identifier must be registered as a URL scheme in `Info.plist`.
+> - The `AppDelegate` must handle `OpenUrl` and call `ActivityMediator.Instance.Send(url.AbsoluteString)`.
+> - **Store tokens securely**: After successful login, persist `AccessToken` and `RefreshToken` using iOS Keychain (via `Security` framework or a wrapper like `KeychainAccess`). Never store tokens in `UserDefaults` or in-memory variables only.
+>
+> After writing configuration and code, verify the build succeeds:
+> ```bash
+> dotnet build
+> ```
+> If the build fails, attempt to fix the issue. After 5-6 failed attempts, ask the user for help.
+
+## WebAuth — How Authentication Works
+
+The SDK uses ASWebAuthenticationSession (the secure system browser). When `LoginAsync()` is called:
+
+1. SDK constructs the `/authorize` URL with PKCE parameters (code verifier + challenge)
+2. ASWebAuthenticationSession opens showing the Auth0 login page
+3. User authenticates (login form, social connections, MFA, etc.)
+4. Auth0 redirects to the native callback URL: `{BundleId}://{domain}/ios/{BundleId}/callback`
+5. iOS intercepts the URL scheme and delivers it to `AppDelegate.OpenUrl`
+6. `ActivityMediator.Instance.Send(url.AbsoluteString)` completes the token exchange
+7. SDK returns `LoginResult` with access token, ID token, refresh token, and user claims
+
+This is the standard OAuth 2.0 Authorization Code flow with PKCE, recommended for native mobile applications.
+
+## Callback URL Configuration
+
+The native callback URL for .NET iOS uses the Bundle Identifier as the scheme. The format is:
+
+```text
+YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback
+```
+
+Where `YOUR_BUNDLE_IDENTIFIER` is the Bundle Identifier for your application, such as `com.mycompany.myapplication`. For example: `com.mycompany.myapp://tenant.us.auth0.com/ios/com.mycompany.myapp/callback`.
+
+> **Note:** Some Auth0 native SDKs use `https://{domain}/ios/{bundleId}/callback` or `{bundleId}.auth0://{domain}/ios/{bundleId}/callback` as the callback URL format. The .NET iOS SDK uses the Bundle Identifier directly as the URL scheme.
+
+Ensure that the Callback URL is in lowercase.
+
+This URL must be:
+1. Registered in Auth0 Dashboard under **Allowed Callback URLs** and **Allowed Logout URLs**
+2. Registered as a URL scheme in `Info.plist` under `CFBundleURLSchemes`
+
+## Done When
+
+- [ ] `Auth0.OidcClient.iOS` package installed (latest stable version)
+- [ ] `Auth0Client` configured with Domain, ClientId, and `Scope = "openid profile email offline_access"`
+- [ ] URL scheme registered in `Info.plist` matching the Bundle Identifier
+- [ ] `AppDelegate.OpenUrl` implemented with `ActivityMediator.Instance.Send(url.AbsoluteString)`
+- [ ] Callback URL added to Auth0 Dashboard Allowed Callback URLs and Allowed Logout URLs
+- [ ] Tokens stored securely using iOS Keychain (`Security` framework with `SecKeyChain.Add`)
+- [ ] Login/logout flow working
+- [ ] Build succeeds with no errors
+
+## Detailed Documentation
+
+- **Setup Guide** (see below) — Auth0 tenant configuration, SDK installation, Info.plist URL scheme setup
+- **Integration Patterns** (see below) — Login/logout flows, token access, user profile, error handling
+- **API Reference & Testing** (see below) — Full `Auth0ClientOptions` reference, claims, testing checklist, troubleshooting
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| App type not set to **Native** in Auth0 Dashboard | Change application type to "Native" in Dashboard settings |
+| Missing callback URL in Auth0 Dashboard | Add `yourbundleid://{domain}/ios/yourbundleid/callback` to Allowed Callback URLs AND Allowed Logout URLs |
+| Missing URL scheme in Info.plist | Add `CFBundleURLSchemes` entry matching your Bundle Identifier |
+| Not handling `OpenUrl` in AppDelegate | Override `OpenUrl` and call `ActivityMediator.Instance.Send(url.AbsoluteString)` |
+| Using `https://` prefix in Domain | Domain should be hostname only (e.g., `tenant.auth0.com`, not `https://tenant.auth0.com`) |
+| Passing Activity context to Auth0Client (Android pattern) | iOS does not need context — just `new Auth0Client(options)` |
+| URL scheme not matching Bundle Identifier | The CFBundleURLSchemes value must exactly match the Bundle Identifier |
+| Storing tokens in `UserDefaults` or only in memory | Use iOS Keychain via the `Security` framework (`SecKeyChain.Add`) for token persistence |
+
+## Testing Notes
+
+> **Agent instruction:** Remind the user to test on a physical device in addition to simulators. Some WebAuth/ASWebAuthenticationSession behaviors may differ on physical devices vs. simulators. Test the full login → callback → token flow on real hardware before shipping.
+
+**Physical Device Testing:**
+- Login flow: ASWebAuthenticationSession opens → authenticate → returns to app
+- Callback: `OpenUrl` fires in AppDelegate with correct URL
+- Logout flow: Browser opens → session cleared → returns to app
+- Cancel: User dismisses sheet → app handles `UserCancel` gracefully
+
+## Related Skills
+
+All of this lives in the one `auth0` skill — just describe what you need (e.g. "add MFA", "protect my API").
+
+## Quick Reference
+
+```csharp
+using Auth0.OidcClient;
+
+var client = new Auth0Client(new Auth0ClientOptions
+{
+    Domain = "YOUR_AUTH0_DOMAIN",
+    ClientId = "YOUR_AUTH0_CLIENT_ID",
+    Scope = "openid profile email offline_access"
+});
+
+var loginResult = await client.LoginAsync();
+BrowserResultType browserResult = await client.LogoutAsync();
+```
+
+> **Agent instruction:** Always include `offline_access` in the scope to enable refresh tokens. This allows the app to silently refresh access tokens without forcing the user to re-authenticate.
+>
+> **Agent instruction:** After login, always persist tokens to the iOS Keychain using the `Security` framework (`SecKeyChain.Add` with `SecAccessible.WhenUnlockedThisDeviceOnly`). Never store tokens in `UserDefaults` or leave them only in memory. Clear tokens on logout. See the Integration Patterns section (below) for the full `SecureTokenStorage` helper class.
+
+### Required Platform Configuration
+
+These two pieces are required for the callback to work — see the Setup Guide section (below) for full code:
+
+1. **Info.plist**: Add `CFBundleURLSchemes` entry matching the Bundle Identifier
+2. **AppDelegate**: Override `OpenUrl` and call `ActivityMediator.Instance.Send(url.AbsoluteString)`
+
+For login with extra parameters, error handling, token refresh, user claims access, and complete ViewController examples, see the Integration Patterns section (below).
+
+## References
+
+- [.NET Android & iOS Quickstart](https://auth0.com/docs/quickstart/native/net-android-ios)
+- [GitHub Repository](https://github.com/auth0/auth0-oidc-client-net)
+- [NuGet Package — Auth0.OidcClient.iOS](https://www.nuget.org/packages/Auth0.OidcClient.iOS)
+- [SDK API Documentation](https://auth0.github.io/auth0-oidc-client-net/documentation/intro.html)
+- [Auth0 Native App Documentation](https://auth0.com/docs/get-started/auth0-overview/create-applications/native-apps)
diff --git a/main/.mintlify/skills/auth0/references/framework-nextjs/index.md b/main/.mintlify/skills/auth0/references/framework-nextjs/index.md
new file mode 100644
index 0000000000..68670ae90a
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-nextjs/index.md
@@ -0,0 +1,833 @@
+
+# Auth0 Next.js Integration
+
+Add authentication to Next.js applications using @auth0/nextjs-auth0. Supports both App Router and Pages Router.
+
+## Prerequisites
+
+- Next.js 13+ application (App Router or Pages Router)
+- Auth0 account and application configured
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **Client-side only React apps** - Use the Auth0 integration workflow for React (Vite/CRA SPAs)
+- **React Native mobile apps** - Use the Auth0 integration workflow for React Native (iOS/Android)
+- **Non-Next.js frameworks** - Use framework-specific SDKs (Express, Vue, Angular, etc.)
+- **Stateless APIs only** - Use JWT validation middleware if you don't need session management
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+npm install @auth0/nextjs-auth0
+```
+
+### 2. Configure Environment
+
+**For automated setup with Auth0 CLI**, see the Setup Guide section below for complete scripts.
+
+**For manual setup:**
+
+Create `.env.local`:
+
+```bash
+AUTH0_SECRET=<generate-a-32-character-secret>
+APP_BASE_URL=http://localhost:3000
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_CLIENT_ID=your-client-id
+AUTH0_CLIENT_SECRET=your-client-secret
+```
+
+Generate secret: `openssl rand -hex 32`
+
+**Important:** Add `.env.local` to `.gitignore`
+
+### 3. Create Auth0 Client and Middleware
+
+**Detect project structure first:** Check whether the project uses a `src/` directory (i.e. `src/app/` or `src/pages/` exists). This determines where to place files:
+- **With `src/`:** `src/lib/auth0.ts`, `src/middleware.ts` (or `src/proxy.ts` for Next.js 16)
+- **Without `src/`:** `lib/auth0.ts`, `middleware.ts` (or `proxy.ts` for Next.js 16)
+
+Create `lib/auth0.ts` (or `src/lib/auth0.ts` if using the `src/` convention):
+
+```typescript
+import { Auth0Client } from '@auth0/nextjs-auth0/server';
+
+export const auth0 = new Auth0Client({
+  domain: process.env.AUTH0_DOMAIN!,
+  clientId: process.env.AUTH0_CLIENT_ID!,
+  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
+  secret: process.env.AUTH0_SECRET!,
+  appBaseUrl: process.env.APP_BASE_URL!,
+});
+```
+
+**Middleware Configuration (Next.js 15 vs 16):**
+
+**Next.js 15** - Create `middleware.ts` (at project root, or `src/middleware.ts` if using `src/`):
+
+```typescript
+import { NextRequest } from 'next/server';
+import { auth0 } from '@/lib/auth0';
+
+export async function middleware(request: NextRequest) {
+  return await auth0.middleware(request);
+}
+
+export const config = {
+  matcher: [
+    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
+  ],
+};
+```
+
+**Next.js 16** - You have two options:
+
+**Option 1:** Use `middleware.ts` (same as Next.js 15, same `src/` placement rules):
+
+```typescript
+import { NextRequest } from 'next/server';
+import { auth0 } from '@/lib/auth0';
+
+export async function middleware(request: NextRequest) {
+  return await auth0.middleware(request);
+}
+
+export const config = {
+  matcher: [
+    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
+  ],
+};
+```
+
+**Option 2:** Use `proxy.ts` (at project root, or `src/proxy.ts` if using `src/`):
+
+```typescript
+import { NextRequest } from 'next/server';
+import { auth0 } from '@/lib/auth0';
+
+export async function proxy(request: NextRequest) {
+  return await auth0.middleware(request);
+}
+
+export const config = {
+  matcher: [
+    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
+  ],
+};
+```
+
+This automatically creates endpoints:
+- `/auth/login` - Login
+- `/auth/logout` - Logout
+- `/auth/callback` - OAuth callback
+- `/auth/profile` - User profile
+
+### 4. Add User Context (Optional)
+
+**Note:** In v4, wrapping with `<Auth0Provider>` is optional. Only needed if you want to pass an initial user during server rendering to `useUser()`.
+
+**App Router** - Optionally wrap app in `app/layout.tsx`:
+
+```typescript
+import { Auth0Provider } from '@auth0/nextjs-auth0/client';
+import { auth0 } from '@/lib/auth0';
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const session = await auth0.getSession();
+
+  return (
+    <html>
+      <body>
+        <Auth0Provider user={session?.user}>{children}</Auth0Provider>
+      </body>
+    </html>
+  );
+}
+```
+
+**Pages Router** - Optionally wrap app in `pages/_app.tsx`:
+
+```typescript
+import { Auth0Provider } from '@auth0/nextjs-auth0/client';
+import type { AppProps } from 'next/app';
+
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <Auth0Provider user={pageProps.user}>
+      <Component {...pageProps} />
+    </Auth0Provider>
+  );
+}
+```
+
+### 5. Add Authentication UI
+
+**Client Component** (works in both routers):
+
+```typescript
+'use client'; // Only needed for App Router
+
+import { useUser } from '@auth0/nextjs-auth0/client';
+
+export default function Profile() {
+  const { user, isLoading } = useUser();
+
+  if (isLoading) return <div>Loading...</div>;
+
+  if (user) {
+    return (
+      <div>
+        <img src={user.picture} alt={user.name} />
+        <h2>Welcome, {user.name}!</h2>
+        <a href="/auth/logout">Logout</a>
+      </div>
+    );
+  }
+
+  return <a href="/auth/login">Login</a>;
+}
+```
+
+### 6. Test Authentication
+
+Start your dev server:
+
+```bash
+npm run dev
+```
+
+Visit `http://localhost:3000` and test the login flow.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using v3 environment variables | v4 uses `APP_BASE_URL` and `AUTH0_DOMAIN` (not `AUTH0_BASE_URL` or `AUTH0_ISSUER_BASE_URL`) |
+| Forgot to add callback URL in Auth0 Dashboard | Add `/auth/callback` to Allowed Callback URLs (e.g., `http://localhost:3000/auth/callback`) |
+| Missing middleware configuration | v4 requires middleware to mount auth routes - create `middleware.ts` (Next.js 15+16) or `proxy.ts` (Next.js 16 only) with `auth0.middleware()` |
+| Wrong route paths | v4 uses `/auth/login` not `/api/auth/login` - routes drop the `/api` prefix |
+| Missing or weak AUTH0_SECRET | Generate secure secret with `openssl rand -hex 32` and store in .env.local |
+| Using .env instead of .env.local | Next.js requires .env.local for local secrets, and .env.local should be in .gitignore |
+| App created as SPA type in Auth0 | Must be Regular Web Application type for Next.js |
+| Using removed v3 helpers | v4 removed `withPageAuthRequired` and `withApiAuthRequired` - use `getSession()` instead |
+| Using useUser in Server Component | useUser is client-only, use `auth0.getSession()` for Server Components |
+| AUTH0_DOMAIN includes https:// | v4 `AUTH0_DOMAIN` should be just the domain (e.g., `example.auth0.com`), no scheme |
+
+## Related Capabilities
+
+- Auth0 setup — run the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Migrating from another auth provider → ask for migration (migrate)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- Managing Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+
+## Quick Reference
+
+**V4 Setup:**
+- Detect `src/` convention: check if `src/app/` or `src/pages/` exists — place all files inside `src/` if so
+- Create `lib/auth0.ts` (or `src/lib/auth0.ts`) with `Auth0Client` instance
+- Create middleware configuration (required):
+  - Next.js 15: `middleware.ts` (or `src/middleware.ts`) with `middleware()` function
+  - Next.js 16: `middleware.ts` with `middleware()` OR `proxy.ts` with `proxy()` function (same `src/` rules)
+- Optional: Wrap with `<Auth0Provider>` for SSR user
+
+**Client-Side Hooks:**
+- `useUser()` - Get user in client components
+- `user` - User profile object
+- `isLoading` - Loading state
+
+**Server-Side Methods:**
+- `auth0.getSession()` - Get session in Server Components/API routes/middleware
+- `auth0.getAccessToken()` - Get access token for calling APIs
+
+**Common Use Cases:**
+- Login/Logout links → Use `/auth/login` and `/auth/logout` paths (see Step 5)
+- Protected pages (App Router) → see the Protected Pages (App Router) section below
+- Protected pages (Pages Router) → see the Protected Pages (Pages Router) section below
+- API routes with auth → see the Protected API Routes section below
+- Middleware protection → see the Middleware section below
+
+## References
+
+- [Auth0 Next.js SDK Documentation](https://auth0.com/docs/libraries/nextjs)
+- [Auth0 Next.js Quickstart](https://auth0.com/docs/quickstart/webapp/nextjs)
+- [SDK GitHub Repository](https://github.com/auth0/nextjs-auth0)
+
+---
+
+## Common Patterns
+
+### Custom Login with Options
+
+```typescript
+<a href="/auth/login?returnTo=/dashboard">
+  Login and go to Dashboard
+</a>
+```
+
+Or programmatically:
+
+```typescript
+const router = useRouter();
+router.push('/auth/login?returnTo=/dashboard');
+```
+
+---
+
+### Get Access Token for External APIs
+
+```typescript
+import { auth0 } from '@/lib/auth0';
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  const { token } = await auth0.getAccessToken();
+
+  if (!token) {
+    return new NextResponse('Unauthorized', { status: 401 });
+  }
+
+  const apiResponse = await fetch('https://external-api.com/data', {
+    headers: {
+      Authorization: `Bearer ${token}`
+    }
+  });
+
+  return NextResponse.json(await apiResponse.json());
+}
+```
+
+---
+
+### Silent Authentication
+
+Users remain logged in across sessions automatically with refresh tokens.
+
+To force re-authentication:
+
+```typescript
+<a href="/auth/login?prompt=login">
+  Force Re-login
+</a>
+```
+
+---
+
+## Configuration Options
+
+### Advanced Auth0 Configuration
+
+Create `lib/auth0.ts`:
+
+```typescript
+import { Auth0Client } from '@auth0/nextjs-auth0/server';
+
+export const auth0 = new Auth0Client({
+  domain: process.env.AUTH0_DOMAIN!,
+  clientId: process.env.AUTH0_CLIENT_ID!,
+  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
+  secret: process.env.AUTH0_SECRET!,
+  appBaseUrl: process.env.APP_BASE_URL!,
+  authorizationParameters: {
+    scope: 'openid profile email',
+    audience: process.env.AUTH0_AUDIENCE,
+  },
+  routes: {
+    login: '/auth/login',
+    callback: '/auth/callback',
+    logout: '/auth/logout',
+    profile: '/auth/profile',
+  },
+  session: {
+    rolling: true,
+    rollingDuration: 24 * 60 * 60, // 24 hours in seconds
+    absoluteDuration: 7 * 24 * 60 * 60, // 7 days in seconds
+  },
+});
+```
+
+**Note:** Most configuration can be omitted - v4 uses sensible defaults. The middleware automatically mounts auth routes.
+
+---
+
+## Testing
+
+1. Start your dev server: `npm run dev`
+2. Visit `http://localhost:3000`
+3. Click "Login" - redirects to Auth0
+4. Complete authentication
+5. Verify redirect back with user session
+6. Test protected pages and API routes
+7. Click "Logout" and verify session cleared
+
+---
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "Missing required parameter: redirect_uri" | Ensure `APP_BASE_URL` is set correctly (v4 renamed from `AUTH0_BASE_URL`) |
+| "Invalid state" error | Clear cookies/storage. Verify callback URL in Auth0 dashboard matches `APP_BASE_URL/auth/callback` |
+| User session not persisting | Check `AUTH0_SECRET` is set and at least 32 characters |
+| API routes return 401 | Check session with `auth0.getSession()` in route handler |
+| Middleware loops infinitely | Ensure middleware matcher excludes `/auth/*` routes, not `/api/auth/*` |
+| Import errors for v3 helpers | v4 removed `withApiAuthRequired` and `withPageAuthRequired` - use `auth0.getSession()` |
+| Environment variable not recognized | v4 uses `AUTH0_DOMAIN` (no scheme) and `APP_BASE_URL`, not `AUTH0_ISSUER_BASE_URL` or `AUTH0_BASE_URL` |
+
+---
+
+## Security Considerations
+
+- **Keep secrets secure** - Never commit `.env.local` to version control
+- **Use HTTPS in production** - Auth0 requires secure callback URLs
+- **Rotate secrets regularly** - Update `AUTH0_SECRET` periodically
+- **Validate on server** - Always verify authentication server-side, not client-side
+- **Configure CORS** - Set allowed origins in Auth0 application settings
+
+---
+
+## Related Capabilities
+
+- Auth0 account setup — run the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Migrating from another auth provider → ask for migration (migrate)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- B2B multi-tenancy support → ask for Organizations (feature:organizations)
+- Passkey authentication → ask for MFA (feature:mfa)
+
+---
+
+## References
+
+- [Auth0 Next.js SDK Documentation](https://auth0.com/docs/libraries/nextjs-auth0)
+- [Auth0 Next.js SDK GitHub](https://github.com/auth0/nextjs-auth0)
+- [Auth0 Next.js Quickstart](https://auth0.com/docs/quickstart/webapp/nextjs)
+- [Next.js Middleware Documentation](https://nextjs.org/docs/app/building-your-application/routing/middleware)
+
+---
+
+# Auth0 Next.js Integration Patterns
+
+Server-side and client-side auth patterns for both App and Pages Router.
+
+---
+
+## Protected Pages
+
+### App Router - Server Component
+
+```typescript
+// app/profile/page.tsx
+import { auth0 } from '@/lib/auth0';
+import { redirect } from 'next/navigation';
+
+export default async function Profile() {
+  // In App Router, getSession() reads the request/response from Next.js' async context,
+  // so you don't pass req/res like in the Pages Router example below.
+  const session = await auth0.getSession();
+
+  if (!session) {
+    redirect('/auth/login?returnTo=/profile');
+  }
+
+  return (
+    <div>
+      <h1>Welcome, {session.user.name}!</h1>
+      <img src={session.user.picture} alt={session.user.name} />
+    </div>
+  );
+}
+```
+
+### Pages Router - SSR
+
+```typescript
+// pages/profile.tsx
+import { auth0 } from '@/lib/auth0';
+import { GetServerSideProps } from 'next';
+
+export default function Profile({ user }: { user: any }) {
+  return <h1>Welcome, {user.name}!</h1>;
+}
+
+export const getServerSideProps: GetServerSideProps = async ({ req, res }) => {
+  const session = await auth0.getSession(req, res);
+
+  if (!session) {
+    return {
+      redirect: {
+        destination: '/auth/login?returnTo=/profile',
+        permanent: false,
+      },
+    };
+  }
+
+  return {
+    props: { user: session.user },
+  };
+};
+```
+
+---
+
+## Protected API Routes
+
+### App Router
+
+```typescript
+// app/api/private/route.ts
+import { auth0 } from '@/lib/auth0';
+import { NextResponse } from 'next/server';
+
+export async function GET(request: Request) {
+  const session = await auth0.getSession();
+
+  if (!session) {
+    return new NextResponse('Unauthorized', { status: 401 });
+  }
+
+  return NextResponse.json({ data: 'Protected data', user: session.user });
+}
+```
+
+### Pages Router
+
+```typescript
+// pages/api/private.ts
+import { auth0 } from '@/lib/auth0';
+import { NextApiRequest, NextApiResponse } from 'next';
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  const session = await auth0.getSession(req, res);
+
+  if (!session) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+
+  res.json({ user: session.user });
+}
+```
+
+---
+
+## Middleware (App Router)
+
+Protect multiple routes with middleware.
+
+**File placement:** If the project uses a `src/` directory (i.e. `src/app/` exists), place `middleware.ts` or `proxy.ts` inside `src/`. Otherwise, place at the project root.
+
+**Next.js 15** - Use `middleware.ts` (or `src/middleware.ts`):
+
+```typescript
+// middleware.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { auth0 } from '@/lib/auth0';
+
+export async function middleware(request: NextRequest) {
+  const authRes = await auth0.middleware(request);
+
+  // Allow auth routes to be handled by SDK
+  if (request.nextUrl.pathname.startsWith('/auth')) {
+    return authRes;
+  }
+
+  // Public routes
+  if (request.nextUrl.pathname === '/') {
+    return authRes;
+  }
+
+  // Protected routes - check session
+  const session = await auth0.getSession(request);
+
+  if (!session) {
+    const { origin } = new URL(request.url);
+    return NextResponse.redirect(`${origin}/auth/login?returnTo=${request.nextUrl.pathname}`);
+  }
+
+  return authRes;
+}
+
+export const config = {
+  matcher: [
+    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
+  ],
+};
+```
+
+**Next.js 16** - Use either `middleware.ts` (same as above) or `proxy.ts` (same `src/` placement rules):
+
+```typescript
+// proxy.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { auth0 } from '@/lib/auth0';
+
+export async function proxy(request: NextRequest) {
+  const authRes = await auth0.middleware(request);
+
+  // Allow auth routes to be handled by SDK
+  if (request.nextUrl.pathname.startsWith('/auth')) {
+    return authRes;
+  }
+
+  // Public routes
+  if (request.nextUrl.pathname === '/') {
+    return authRes;
+  }
+
+  // Protected routes - check session
+  const session = await auth0.getSession(request);
+
+  if (!session) {
+    const { origin } = new URL(request.url);
+    return NextResponse.redirect(`${origin}/auth/login?returnTo=${request.nextUrl.pathname}`);
+  }
+
+  return authRes;
+}
+
+export const config = {
+  matcher: [
+    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
+  ],
+};
+```
+
+---
+
+## Calling External APIs
+
+### App Router - Server Action
+
+```typescript
+// app/actions.ts
+'use server';
+
+import { auth0 } from '@/lib/auth0';
+
+export async function getData() {
+  const { token } = await auth0.getAccessToken();
+
+  if (!token) {
+    throw new Error('No access token available');
+  }
+
+  const response = await fetch('https://api.example.com/data', {
+    headers: { Authorization: `Bearer ${token}` }
+  });
+
+  return response.json();
+}
+```
+
+### Pages Router - API Route
+
+```typescript
+// pages/api/data.ts
+import { auth0 } from '@/lib/auth0';
+import { NextApiRequest, NextApiResponse } from 'next';
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  const session = await auth0.getSession(req, res);
+
+  if (!session) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+
+  const { token } = await auth0.getAccessToken(req, res);
+
+  if (!token) {
+    return res.status(401).json({ error: 'No access token' });
+  }
+
+  const response = await fetch('https://api.example.com/data', {
+    headers: { Authorization: `Bearer ${token}` }
+  });
+
+  const data = await response.json();
+  res.json(data);
+}
+```
+
+---
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "Invalid state" error | Regenerate `AUTH0_SECRET`, clear cookies |
+| Client secret required | Next.js uses Regular Web Application type |
+| Callback URL mismatch | Add `/auth/callback` to Allowed Callback URLs (v4 dropped `/api` prefix) |
+| Middleware not protecting routes | Ensure middleware calls `auth0.middleware()` and check `matcher` config |
+| Routes return 404 | v4 uses `/auth/*` paths, not `/api/auth/*` - update all auth links |
+
+---
+
+---
+
+# Auth0 Next.js Setup Guide
+
+Setup instructions for Next.js with App Router or Pages Router.
+
+---
+
+## Quick Setup (Automated)
+
+**Never read the contents of `.env.local` or `.env` at any point during setup.** The file may contain sensitive secrets that should not be exposed in the LLM context. If you determine you need to read the file for any reason, ask the user for explicit permission before doing so — do not proceed until the user confirms.
+
+**Before running any part of this setup that writes to an env file, you MUST ask the user for explicit confirmation.** Follow the steps below precisely.
+
+### Step 1: Check for existing env files and confirm with user
+
+Before writing credentials, check which env files exist:
+
+```bash
+test -f .env.local && echo "ENV_LOCAL_EXISTS" || echo "ENV_LOCAL_NOT_FOUND"
+test -f .env && echo "ENV_EXISTS" || echo "ENV_NOT_FOUND"
+```
+
+Then ask the user for explicit confirmation before proceeding — do not continue until the user confirms:
+
+- If `.env.local` exists, ask:
+  - Question: "A `.env.local` file already exists and may contain secrets unrelated to Auth0. This setup will append Auth0 credentials to it without modifying existing content. Do you want to proceed?"
+  - Options: "Yes, append to existing .env.local" / "No, I'll update it manually"
+
+- If `.env.local` does **not** exist but `.env` exists, ask:
+  - Question: "A `.env` file already exists and may contain secrets unrelated to Auth0. This setup will append Auth0 credentials to it without modifying existing content. Do you want to proceed?"
+  - Options: "Yes, append to existing .env" / "No, I'll update it manually"
+
+- If neither exists, ask:
+  - Question: "This setup will create a `.env.local` file containing Auth0 credentials (AUTH0_CLIENT_ID, AUTH0_DOMAIN, AUTH0_SECRET) and a placeholder for AUTH0_CLIENT_SECRET that you will need to fill in manually. Do you want to proceed?"
+  - Options: "Yes, create .env.local" / "No, I'll configure it manually"
+
+**Do not proceed with writing to any env file unless the user selects the confirmation option.**
+
+### Step 2: Run automated setup (only after confirmation)
+
+```bash
+#!/bin/bash
+
+# Install Auth0 CLI
+if ! command -v auth0 &> /dev/null; then
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    brew install auth0/auth0-cli/auth0
+  else
+    # Download and review the install script before executing
+    curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh -o /tmp/auth0-install.sh
+    echo "⚠️  Review the install script at /tmp/auth0-install.sh before running"
+    sh /tmp/auth0-install.sh -b /usr/local/bin
+    rm /tmp/auth0-install.sh
+  fi
+fi
+
+# Login
+if ! auth0 tenants list &> /dev/null; then
+  echo "Visit https://auth0.com/signup if you need an account"
+  auth0 login
+fi
+
+# Create/select app
+auth0 apps list
+read -p "Enter app ID (or Enter to create new): " APP_ID
+
+if [ -z "$APP_ID" ]; then
+  APP_ID=$(auth0 apps create \
+    --name "${PWD##*/}-nextjs" \
+    --type regular \
+    --callbacks "http://localhost:3000/auth/callback" \
+    --logout-urls "http://localhost:3000" \
+    --metadata "created_by=agent_skills" \
+    --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+fi
+
+# Get credentials
+AUTH0_DOMAIN=$(auth0 apps show "$APP_ID" --json | grep -o '"domain":"[^"]*' | cut -d'"' -f4)
+AUTH0_CLIENT_ID=$(auth0 apps show "$APP_ID" --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+
+# Generate secret
+AUTH0_SECRET=$(openssl rand -hex 32)
+
+# Determine target env file
+if [ -f .env.local ]; then
+  TARGET_FILE=".env.local"
+elif [ -f .env ]; then
+  TARGET_FILE=".env"
+else
+  TARGET_FILE=".env.local"
+fi
+
+# Append Auth0 credentials
+cat >> "$TARGET_FILE" << ENVEOF
+AUTH0_SECRET=$AUTH0_SECRET
+APP_BASE_URL=http://localhost:3000
+AUTH0_DOMAIN=$AUTH0_DOMAIN
+AUTH0_CLIENT_ID=$AUTH0_CLIENT_ID
+AUTH0_CLIENT_SECRET='YOUR_CLIENT_SECRET'
+ENVEOF
+
+echo "✅ Auth0 credentials written to $TARGET_FILE"
+```
+
+After the script runs, remind the user to:
+1. Open the env file that was written and replace `YOUR_CLIENT_SECRET` with the actual client secret from Auth0.
+2. Ensure the env file is listed in `.gitignore` to avoid accidentally committing secrets.
+
+---
+
+## Manual Setup
+
+### Step 1: Install SDK
+
+```bash
+npm install @auth0/nextjs-auth0
+```
+
+### Step 2: Create .env.local
+
+```bash
+AUTH0_SECRET=<openssl-rand-hex-32>
+APP_BASE_URL=http://localhost:3000
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_CLIENT_ID=your-client-id
+AUTH0_CLIENT_SECRET=your-client-secret
+```
+
+Generate `AUTH0_SECRET`:
+```bash
+openssl rand -hex 32
+```
+
+### Step 3: Configure Auth0 Application
+
+Via CLI:
+```bash
+auth0 login
+auth0 apps create --name "My Next.js App" --type regular \
+  --callbacks "http://localhost:3000/auth/callback" \
+  --logout-urls "http://localhost:3000"
+```
+
+Via Dashboard:
+1. Create **Regular Web Application**
+2. Configure:
+   - Allowed Callback URLs: `http://localhost:3000/auth/callback`
+   - Allowed Logout URLs: `http://localhost:3000`
+3. Copy credentials to `.env.local`
+
+---
+
+## Troubleshooting
+
+**"Invalid state" error:**
+- Regenerate `AUTH0_SECRET`
+- Clear cookies and restart dev server
+
+**Client secret not working:**
+- Next.js uses Regular Web Application (not SPA)
+- Verify client secret copied correctly
+
+**Callback URL mismatch:**
+- Ensure `/auth/callback` is in Allowed Callback URLs
+- Check `APP_BASE_URL` matches your domain
+
+---
diff --git a/main/.mintlify/skills/auth0/references/framework-nuxt/index.md b/main/.mintlify/skills/auth0/references/framework-nuxt/index.md
new file mode 100644
index 0000000000..74147ae24f
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-nuxt/index.md
@@ -0,0 +1,1708 @@
+
+# Auth0 Nuxt SDK
+
+## Overview
+
+Server-side session authentication for Nuxt 3/4. NOT the same as @auth0/auth0-vue (client-side SPA).
+
+**Core principle:** Uses server-side encrypted cookie sessions, not client-side tokens.
+
+## When to Use
+
+**Use this when:**
+- Building Nuxt 3/4 applications with server-side rendering (Node.js 20 LTS+)
+- Need secure session management with encrypted cookies
+- Protecting server routes and API endpoints
+- Accessing Auth0 Management API or custom APIs
+
+**Don't use this when:**
+- Using Nuxt 2 (not supported - use different Auth0 SDK)
+- Building pure client-side SPA without server (use @auth0/auth0-vue instead)
+- Using non-Auth0 authentication provider
+- Static site generation only (SSG) without server runtime
+
+## Critical Mistakes to Avoid
+
+| Mistake | Solution |
+|---------|----------|
+| Installing `@auth0/auth0-vue` or `@auth0/auth0-spa-js` | Use `@auth0/auth0-nuxt` |
+| Auth0 app type "Single Page Application" | Use "Regular Web Application" |
+| Env vars: `VITE_AUTH0_*` or `VUE_APP_AUTH0_*` | Use `NUXT_AUTH0_*` prefix |
+| Using `useUser()` for security checks | Use `useAuth0(event).getSession()` server-side |
+| Missing callback URLs in Auth0 Dashboard | Add `http://localhost:3000/auth/callback` |
+| Weak/missing session secret | Generate: `openssl rand -hex 64` |
+| Hardcoding credentials in `nuxt.config.ts` | Leave runtimeConfig values as empty strings; Nuxt auto-fills from `NUXT_AUTH0_*` env vars |
+
+## Quick Setup
+
+```bash
+# 1. Install
+npm install @auth0/auth0-nuxt
+
+# 2. Generate secret
+openssl rand -hex 64
+```
+
+```bash
+# 3. .env
+NUXT_AUTH0_DOMAIN=your-tenant.auth0.com
+NUXT_AUTH0_CLIENT_ID=your-client-id
+NUXT_AUTH0_CLIENT_SECRET=your-client-secret
+NUXT_AUTH0_SESSION_SECRET=<from-openssl>
+NUXT_AUTH0_APP_BASE_URL=http://localhost:3000
+NUXT_AUTH0_AUDIENCE=https://your-api  # optional
+```
+
+```typescript
+// 4. nuxt.config.ts
+// Leave values as empty strings — Nuxt auto-fills them from NUXT_AUTH0_* env vars at runtime.
+// If you prefer explicit mapping, use: domain: process.env.NUXT_AUTH0_DOMAIN || ''
+export default defineNuxtConfig({
+  modules: ['@auth0/auth0-nuxt'],
+  runtimeConfig: {
+    auth0: {
+      domain: '',
+      clientId: '',
+      clientSecret: '',
+      sessionSecret: '',
+      appBaseUrl: 'http://localhost:3000',
+      audience: '',  // optional
+    },
+  },
+})
+```
+
+## Built-in Routes
+
+The SDK automatically mounts these routes:
+
+| Route | Method | Purpose |
+|-------|--------|---------|
+| `/auth/login` | GET | Initiates login flow. Supports `?returnTo=/path` parameter |
+| `/auth/callback` | GET | Handles Auth0 callback after login |
+| `/auth/logout` | GET | Logs user out and redirects to Auth0 logout |
+| `/auth/backchannel-logout` | POST | Receives logout tokens for back-channel logout |
+
+**Customize:** Pass `routes: { login, callback, logout, backchannelLogout }` or `mountRoutes: false` to module config.
+
+## Composables
+
+| Composable | Context | Usage |
+|------------|---------|-------|
+| `useAuth0(event)` | Server-side | Access `getUser()`, `getSession()`, `getAccessToken()`, `logout()` |
+| `useUser()` | Client-side | Display user data only. **Never use for security checks** — instead, enforce them server-side with `useAuth0(event).getSession()` |
+
+```typescript
+// Server example
+const auth0 = useAuth0(event);
+const session = await auth0.getSession();
+```
+
+```vue
+<script setup>
+const user = useUser();
+</script>
+
+<template>
+  <div v-if="user">Welcome {{ user.name }}</div>
+<template>
+```
+
+## Protecting Routes
+
+**Three layers:** Route middleware (client), server middleware (SSR), API guards.
+
+```typescript
+// middleware/auth.ts - Client navigation
+export default defineNuxtRouteMiddleware((to) => {
+  if (!useUser().value) return navigateTo(`/auth/login?returnTo=${encodeURIComponent(to.path)}`);
+});
+```
+
+```typescript
+// server/middleware/auth.server.ts - SSR protection
+export default defineEventHandler(async (event) => {
+  const url = getRequestURL(event);
+  const auth0Client = useAuth0(event);
+  const session = await auth0Client.getSession();
+  if (!session)  {
+    return sendRedirect(event, `/auth/login?returnTo=${encodeURIComponent(url.pathname)}`);
+  }
+});
+```
+
+```typescript
+// server/api/protected.ts - API endpoint protection
+export default defineEventHandler(async (event) => {
+  const auth0Client = useAuth0(event);
+  const session = await auth0Client.getSession();
+
+  if (!session) {
+    throw createError({
+      statusCode: 401,
+      statusMessage: 'Unauthorized'
+    });
+  }
+
+  return { data: 'protected data' };
+});
+```
+
+**For role-based, permission-based, and advanced patterns, see the Route Protection Patterns section below.**
+
+## Session Management
+
+### Stateless (Default)
+Uses encrypted, chunked cookies. No configuration needed.
+
+### Stateful (Redis, MongoDB, etc.)
+For larger sessions or distributed systems:
+
+```typescript
+// nuxt.config.ts
+modules: [
+  ['@auth0/auth0-nuxt', {
+    sessionStoreFactoryPath: '~/server/utils/session-store-factory.ts'
+  }]
+]
+```
+
+**For complete session store implementations, see the Custom Session Stores section below.**
+
+## API Integration
+
+Configure audience for API access tokens:
+
+```typescript
+// nuxt.config.ts
+runtimeConfig: {
+  auth0: {
+    audience: 'https://your-api-identifier',
+  }
+}
+```
+
+Retrieve tokens server-side:
+
+```typescript
+// server/api/call-api.ts
+export default defineEventHandler(async (event) => {
+  const auth0Client = useAuth0(event);
+  const { accessToken } = await auth0Client.getAccessToken();
+
+  return await $fetch('https://api.example.com/data', {
+    headers: {
+      Authorization: `Bearer ${accessToken}`
+    }
+  });
+});
+```
+
+## Security Checklist
+
+- ✅ Server-side validation only (never trust `useUser()`)
+- ✅ HTTPS in production
+- ✅ Strong session secret (`openssl rand -hex 64`)
+- ✅ Never commit `.env` files
+- ✅ Stateful sessions for PII/large data
+
+## Troubleshooting
+
+| Error | Solution |
+|-------|----------|
+| "Module not found" | Install `@auth0/auth0-nuxt`, not `@auth0/auth0-vue` |
+| "Missing domain/clientId/clientSecret" | Check `NUXT_AUTH0_` prefix, `.env` location, `runtimeConfig` |
+| "Redirect URI mismatch" | Match Auth0 Dashboard callback to `appBaseUrl + /auth/callback` |
+| "useAuth0 is not defined" | Use only in server context with H3 event object |
+| Cookies too large | Use stateful sessions or reduce scopes |
+
+## Additional Resources
+
+**Guides (sections below):** Route Protection Patterns • Custom Session Stores • Common Examples
+
+## Related Capabilities
+
+- Auth0 setup — if Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Managing Auth0 resources from the terminal — the Auth0 CLI (`tooling-cli`)
+
+
+**Links:** [Auth0-Nuxt GitHub](https://github.com/auth0/auth0-nuxt) • [Auth0 Docs](https://auth0.com/docs) • [Nuxt Modules](https://nuxt.com/modules)
+
+---
+
+# Route Protection Patterns for Auth0-Nuxt
+
+Comprehensive guide for protecting routes, pages, and API endpoints in Nuxt 3/4 applications with Auth0.
+
+## Protection Layers
+
+Auth0-Nuxt provides three protection layers:
+
+1. **Route Middleware** - Client-side navigation guards (pages)
+2. **Server Middleware** - SSR protection (server-rendered routes)
+3. **API Route Guards** - Protect API endpoints
+
+## Route Middleware (Client-Side Navigation)
+
+### Basic Route Middleware
+
+Create `middleware/auth.ts`:
+
+```typescript
+export default defineNuxtRouteMiddleware((to, from) => {
+  const user = useUser();
+
+  if (!user.value) {
+    return navigateTo(`/auth/login?returnTo=${encodeURIComponent(to.path)}`);
+  }
+});
+```
+
+### Apply to Specific Pages
+
+```vue
+<!-- pages/dashboard.vue -->
+<script setup>
+definePageMeta({
+  middleware: ['auth']
+});
+</script>
+
+<template>
+  <div>Private Dashboard</div>
+</template>
+```
+
+### Role-Based Middleware
+
+```typescript
+// middleware/admin.ts
+export default defineNuxtRouteMiddleware((to, from) => {
+  const user = useUser();
+
+  if (!user.value) {
+    return navigateTo(`/auth/login?returnTo=${encodeURIComponent(to.path)}`);
+  }
+
+  // Check for admin role
+  const roles = user.value['https://my-app.com/roles'] || [];
+  if (!roles.includes('admin')) {
+    return navigateTo('/unauthorized');
+  }
+});
+```
+
+```vue
+<!-- pages/admin/index.vue -->
+<script setup>
+definePageMeta({
+  middleware: ['admin']
+});
+</script>
+```
+
+### Permission-Based Middleware
+
+```typescript
+// middleware/permissions.ts
+export default defineNuxtRouteMiddleware((to, from) => {
+  const user = useUser();
+
+  if (!user.value) {
+    return navigateTo(`/auth/login?returnTo=${encodeURIComponent(to.path)}`);
+  }
+
+  // Check for specific permission
+  const permissions = user.value['https://my-app.com/permissions'] || [];
+  const requiredPermission = to.meta.permission;
+
+  if (requiredPermission && !permissions.includes(requiredPermission)) {
+    return navigateTo('/forbidden');
+  }
+});
+```
+
+```vue
+<!-- pages/settings/billing.vue -->
+<script setup>
+definePageMeta({
+  middleware: ['permissions'],
+  permission: 'read:billing'
+});
+</script>
+```
+
+### Multiple Middleware Chain
+
+```vue
+<script setup>
+definePageMeta({
+  middleware: ['auth', 'admin', 'audit-log']
+});
+</script>
+```
+
+## Server Middleware (SSR Protection)
+
+### Global Server Middleware
+
+```typescript
+// server/middleware/auth.server.ts
+export default defineEventHandler(async (event) => {
+  const url = getRequestURL(event);
+
+  // Skip auth routes
+  if (url.pathname.startsWith('/auth/')) {
+    return;
+  }
+
+  // Protect all /dashboard routes
+  if (url.pathname.startsWith('/dashboard')) {
+    const auth0Client = useAuth0(event);
+    const session = await auth0Client.getSession();
+
+    if (!session) {
+      return sendRedirect(event, `/auth/login?returnTo=${encodeURIComponent(url.pathname)}`);
+    }
+  }
+});
+```
+
+### Path-Specific Protection
+
+```typescript
+// server/middleware/auth.server.ts
+const protectedPaths = ['/dashboard', '/profile', '/settings'];
+
+export default defineEventHandler(async (event) => {
+  const url = getRequestURL(event);
+
+  const isProtected = protectedPaths.some(path =>
+    url.pathname.startsWith(path)
+  );
+
+  if (isProtected) {
+    const auth0Client = useAuth0(event);
+    const session = await auth0Client.getSession();
+
+    if (!session) {
+      return sendRedirect(event, `/auth/login?returnTo=${encodeURIComponent(url.pathname)}`);
+    }
+  }
+});
+```
+
+### Role-Based Server Protection
+
+```typescript
+// server/middleware/admin-routes.server.ts
+export default defineEventHandler(async (event) => {
+  const url = getRequestURL(event);
+
+  if (url.pathname.startsWith('/admin')) {
+    const auth0Client = useAuth0(event);
+    const session = await auth0Client.getSession();
+
+    if (!session) {
+      return sendRedirect(event, `/auth/login?returnTo=${encodeURIComponent(url.pathname)}`);
+    }
+
+    const user = await auth0Client.getUser();
+    const roles = user?.['https://my-app.com/roles'] || [];
+
+    if (!roles.includes('admin')) {
+      throw createError({
+        statusCode: 403,
+        statusMessage: 'Forbidden: Admin access required'
+      });
+    }
+  }
+});
+```
+
+## API Route Protection
+
+### Basic API Protection
+
+```typescript
+// server/api/user-data.ts
+export default defineEventHandler(async (event) => {
+  const auth0Client = useAuth0(event);
+  const session = await auth0Client.getSession();
+
+  if (!session) {
+    throw createError({
+      statusCode: 401,
+      statusMessage: 'Unauthorized'
+    });
+  }
+
+  return { data: 'protected user data' };
+});
+```
+
+### Reusable Auth Guard
+
+```typescript
+// server/utils/require-auth.ts
+export async function requireAuth(event: H3Event) {
+  const auth0Client = useAuth0(event);
+  const session = await auth0Client.getSession();
+
+  if (!session) {
+    throw createError({
+      statusCode: 401,
+      statusMessage: 'Unauthorized'
+    });
+  }
+
+  return session;
+}
+```
+
+Use in API routes:
+
+```typescript
+// server/api/protected.ts
+export default defineEventHandler(async (event) => {
+  await requireAuth(event);
+  return { message: 'This is protected' };
+});
+```
+
+### Permission-Based API Protection
+
+```typescript
+// server/utils/require-permission.ts
+export async function requirePermission(
+  event: H3Event,
+  permission: string
+) {
+  const auth0Client = useAuth0(event);
+  const user = await auth0Client.getUser();
+
+  if (!user) {
+    throw createError({
+      statusCode: 401,
+      statusMessage: 'Unauthorized'
+    });
+  }
+
+  const permissions = user['https://my-app.com/permissions'] || [];
+
+  if (!permissions.includes(permission)) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: `Forbidden: Missing permission '${permission}'`
+    });
+  }
+
+  return user;
+}
+```
+
+Use in API routes:
+
+```typescript
+// server/api/billing/invoices.get.ts
+export default defineEventHandler(async (event) => {
+  await requirePermission(event, 'read:billing');
+
+  return { invoices: [] };
+});
+```
+
+### Global API Middleware
+
+```typescript
+// server/middleware/api-auth.server.ts
+export default defineEventHandler(async (event) => {
+  const url = getRequestURL(event);
+
+  // Protect all API routes except public ones
+  if (url.pathname.startsWith('/api/')) {
+    const publicRoutes = ['/api/health', '/api/version'];
+
+    if (!publicRoutes.includes(url.pathname)) {
+      const auth0Client = useAuth0(event);
+      const session = await auth0Client.getSession();
+
+      if (!session) {
+        throw createError({
+          statusCode: 401,
+          statusMessage: 'Unauthorized'
+        });
+      }
+    }
+  }
+});
+```
+
+## Advanced Patterns
+
+### Conditional Protection by Environment
+
+```typescript
+// middleware/auth.ts
+export default defineNuxtRouteMiddleware((to, from) => {
+  const config = useRuntimeConfig();
+
+  // Skip auth in development
+  if (config.public.environment === 'development') {
+    return;
+  }
+
+  const user = useUser();
+  if (!user.value) {
+    return navigateTo(`/auth/login?returnTo=${encodeURIComponent(to.path)}`);
+  }
+});
+```
+
+### Subscription-Based Protection
+
+```typescript
+// middleware/subscription.ts
+export default defineNuxtRouteMiddleware((to, from) => {
+  const user = useUser();
+
+  if (!user.value) {
+    return navigateTo(`/auth/login?returnTo=${encodeURIComponent(to.path)}`);
+  }
+
+  const subscription = user.value['https://my-app.com/subscription'];
+
+  if (!subscription || subscription.status !== 'active') {
+    return navigateTo('/subscribe');
+  }
+});
+```
+
+### Rate Limiting Protection
+
+```typescript
+// server/middleware/rate-limit.server.ts
+const rateLimitMap = new Map<string, { count: number; resetAt: number }>();
+
+export default defineEventHandler(async (event) => {
+  const auth0Client = useAuth0(event);
+  const user = await auth0Client.getUser();
+
+  if (!user) {
+    return;
+  }
+
+  const userId = user.sub;
+  const now = Date.now();
+  const limit = rateLimitMap.get(userId);
+
+  if (!limit || now > limit.resetAt) {
+    rateLimitMap.set(userId, {
+      count: 1,
+      resetAt: now + 60000 // 1 minute
+    });
+  } else {
+    limit.count++;
+
+    if (limit.count > 100) {
+      throw createError({
+        statusCode: 429,
+        statusMessage: 'Too Many Requests'
+      });
+    }
+  }
+});
+```
+
+### Email Verification Required
+
+```typescript
+// middleware/verified.ts
+export default defineNuxtRouteMiddleware((to, from) => {
+  const user = useUser();
+
+  if (!user.value) {
+    return navigateTo(`/auth/login?returnTo=${encodeURIComponent(to.path)}`);
+  }
+
+  if (!user.value.email_verified) {
+    return navigateTo('/verify-email');
+  }
+});
+```
+
+## Error Pages
+
+### 401 Unauthorized Page
+
+```vue
+<!-- pages/unauthorized.vue -->
+<template>
+  <div>
+    <h1>Unauthorized</h1>
+    <p>You need to log in to access this page.</p>
+    <a :href="`/auth/login?returnTo=${encodeURIComponent($route.query.returnTo || '/')}`">
+      Log In
+    </a>
+  </div>
+</template>
+```
+
+### 403 Forbidden Page
+
+```vue
+<!-- pages/forbidden.vue -->
+<template>
+  <div>
+    <h1>Forbidden</h1>
+    <p>You don't have permission to access this resource.</p>
+    <a href="/">Go Home</a>
+  </div>
+</template>
+```
+
+## Testing Protected Routes
+
+### Unit Testing Middleware
+
+```typescript
+// middleware/auth.spec.ts
+import { describe, it, expect, vi } from 'vitest';
+import { mockNuxtImport } from '@nuxt/test-utils/runtime';
+
+mockNuxtImport('useUser', () => {
+  return () => ({ value: null });
+});
+
+mockNuxtImport('navigateTo', () => {
+  return vi.fn((path) => path);
+});
+
+describe('auth middleware', () => {
+  it('should redirect to login when user is not authenticated', async () => {
+    const { default: authMiddleware } = await import('./auth');
+    const result = authMiddleware(
+      { path: '/dashboard' },
+      { path: '/' }
+    );
+
+    expect(result).toBe('/auth/login?returnTo=/dashboard');
+  });
+});
+```
+
+### E2E Testing with Playwright
+
+```typescript
+// test/protected-routes.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('should redirect to login when accessing protected route', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page).toHaveURL(/\/auth\/login/);
+});
+
+test('should access protected route when logged in', async ({ page }) => {
+  // Login first
+  await page.goto('/auth/login');
+  // ... perform login
+  await page.waitForURL('/');
+
+  // Access protected route
+  await page.goto('/dashboard');
+  await expect(page).toHaveURL('/dashboard');
+});
+```
+
+## Security Checklist
+
+- [ ] Never rely on `useUser()` for any security-critical decisions (it's client-side only and can be tampered with)
+- [ ] Always validate sessions server-side with `useAuth0(event).getSession()` for all security-critical decisions
+- [ ] Implement proper error handling (401/403 responses)
+- [ ] Validate `returnTo` parameter (SDK does this automatically)
+- [ ] Use HTTPS in production
+- [ ] Implement rate limiting for API routes
+- [ ] Log authentication failures for monitoring
+- [ ] Test protected routes thoroughly
+- [ ] Implement proper error pages
+- [ ] Consider role/permission hierarchies
+
+## Common Pitfalls
+
+### ❌ Client-Side Only Protection
+```typescript
+// BAD - Can be bypassed
+if (!useUser().value) {
+  return navigateTo('/login');
+}
+```
+
+### ✅ Server-Side Validation
+```typescript
+// GOOD - Cannot be bypassed
+const session = await useAuth0(event).getSession();
+if (!session) {
+  throw createError({ statusCode: 401 });
+}
+```
+
+### ❌ Forgetting SSR Context
+```typescript
+// BAD - Only protects client-side navigation
+definePageMeta({ middleware: ['auth'] });
+```
+
+### ✅ Both Client and Server Protection
+```typescript
+// GOOD - Protects both client navigation and SSR
+definePageMeta({ middleware: ['auth'] });
+// PLUS server middleware in server/middleware/
+```
+
+---
+
+# Common Patterns and Examples
+
+Real-world patterns and complete examples for Auth0-Nuxt implementations.
+
+## Basic App Layout
+
+### Navigation with Conditional Login/Logout
+
+```vue
+<!-- components/AppHeader.vue -->
+<script setup>
+const user = useUser();
+const route = useRoute();
+</script>
+
+<template>
+  <header>
+    <nav>
+      <a href="/">Home</a>
+      <a href="/dashboard" v-if="user">Dashboard</a>
+      <a href="/profile" v-if="user">Profile</a>
+
+      <div class="auth-actions">
+        <a v-if="user" :href="`/auth/logout`">
+          Logout ({{ user.name }})
+        </a>
+        <a v-else :href="`/auth/login?returnTo=${encodeURIComponent(route.path)}`">
+          Login
+        </a>
+      </div>
+    </nav>
+  </header>
+</template>
+```
+
+### App Layout with User Avatar
+
+```vue
+<!-- layouts/default.vue -->
+<script setup>
+const user = useUser();
+</script>
+
+<template>
+  <div class="app-layout">
+    <header>
+      <nav>
+        <a href="/">Home</a>
+
+        <div v-if="user" class="user-menu">
+          <img :src="user.picture" :alt="user.name" />
+          <span>{{ user.name }}</span>
+          <a href="/auth/logout">Logout</a>
+        </div>
+        <a v-else href="/auth/login">Login</a>
+      </nav>
+    </header>
+
+    <main>
+      <slot />
+    </main>
+  </div>
+</template>
+```
+
+## User Profile Page
+
+```vue
+<!-- pages/profile.vue -->
+<script setup lang="ts">
+definePageMeta({
+  middleware: ['auth']
+});
+
+const user = useUser();
+</script>
+
+<template>
+  <div class="profile" v-if="user">
+    <h1>Profile</h1>
+
+    <div class="profile-info">
+      <img :src="user.picture" :alt="user.name" />
+
+      <dl>
+        <dt>Name</dt>
+        <dd>{{ user.name }}</dd>
+
+        <dt>Email</dt>
+        <dd>{{ user.email }}</dd>
+        <dd v-if="user.email_verified" class="verified">✓ Verified</dd>
+        <dd v-else class="not-verified">⚠ Not Verified</dd>
+
+        <dt>User ID</dt>
+        <dd>{{ user.sub }}</dd>
+
+        <dt>Last Updated</dt>
+        <dd>{{ new Date(user.updated_at).toLocaleString() }}</dd>
+      </dl>
+    </div>
+  </div>
+</template>
+```
+
+## Protected API Calls
+
+### Fetching User-Specific Data
+
+```typescript
+// server/api/user/profile.get.ts
+export default defineEventHandler(async (event) => {
+  const auth0Client = useAuth0(event);
+  const user = await auth0Client.getUser();
+
+  if (!user) {
+    throw createError({
+      statusCode: 401,
+      statusMessage: 'Unauthorized'
+    });
+  }
+
+  // Fetch user profile from database
+  const profile = await getUserProfile(user.sub);
+
+  return { profile };
+});
+```
+
+### Calling External API with Access Token
+
+```typescript
+// server/api/external/data.get.ts
+export default defineEventHandler(async (event) => {
+  const auth0Client = useAuth0(event);
+  const { accessToken } = await auth0Client.getAccessToken();
+
+  const response = await $fetch('https://api.example.com/data', {
+    headers: {
+      Authorization: `Bearer ${accessToken}`
+    }
+  });
+
+  return response;
+});
+```
+
+### Client-Side API Call Pattern
+
+```vue
+<!-- pages/dashboard.vue -->
+<script setup>
+definePageMeta({
+  middleware: ['auth']
+});
+
+const { data, error } = await useFetch('/api/user/profile');
+</script>
+
+<template>
+  <div>
+    <h1>Dashboard</h1>
+    <pre v-if="data">{{ data }}</pre>
+    <div v-if="error">Error: {{ error }}</div>
+  </div>
+</template>
+```
+
+## Role-Based UI
+
+### Conditional Rendering by Role
+
+```vue
+<script setup>
+const user = useUser();
+
+const hasRole = (role: string) => {
+  if (!user.value) return false;
+  const roles = user.value['https://my-app.com/roles'] || [];
+  return roles.includes(role);
+};
+</script>
+
+<template>
+  <div>
+    <h1>Dashboard</h1>
+
+    <div v-if="hasRole('admin')">
+      <h2>Admin Panel</h2>
+      <a href="/admin">Admin Dashboard</a>
+    </div>
+
+    <div v-if="hasRole('editor')">
+      <h2>Editor Tools</h2>
+      <a href="/editor">Content Editor</a>
+    </div>
+
+    <div>
+      <h2>User Content</h2>
+      <p>All users see this</p>
+    </div>
+  </div>
+</template>
+```
+
+### Composable for Role Checking
+
+```typescript
+// composables/useRoles.ts
+export const useRoles = () => {
+  const user = useUser();
+
+  const hasRole = (role: string) => {
+    if (!user.value) return false;
+    const roles = user.value['https://my-app.com/roles'] || [];
+    return roles.includes(role);
+  };
+
+  const hasAnyRole = (roles: string[]) => {
+    return roles.some(role => hasRole(role));
+  };
+
+  const hasAllRoles = (roles: string[]) => {
+    return roles.every(role => hasRole(role));
+  };
+
+  return {
+    hasRole,
+    hasAnyRole,
+    hasAllRoles
+  };
+};
+```
+
+Usage:
+
+```vue
+<script setup>
+const { hasRole, hasAnyRole } = useRoles();
+</script>
+
+<template>
+  <button v-if="hasRole('admin')">Delete</button>
+  <button v-if="hasAnyRole(['admin', 'moderator'])">Edit</button>
+</template>
+```
+
+## Multi-Tenant Applications
+
+### Tenant Selection After Login
+
+```typescript
+// server/api/auth/callback.get.ts
+export default defineEventHandler(async (event) => {
+  const auth0Client = useAuth0(event);
+  const { appState } = await auth0Client.completeInteractiveLogin(
+    new URL(event.node.req.url, useRuntimeConfig().auth0.appBaseUrl)
+  );
+
+  const user = await auth0Client.getUser();
+  const tenants = user?.['https://my-app.com/tenants'] || [];
+
+  // If user has multiple tenants, redirect to tenant selection
+  if (tenants.length > 1) {
+    return sendRedirect(event, '/select-tenant');
+  }
+
+  // Single tenant, set and redirect
+  if (tenants.length === 1) {
+    // Store tenant in session or cookie
+    setCookie(event, 'tenant-id', tenants[0]);
+  }
+
+  return sendRedirect(event, appState?.returnTo || '/');
+});
+```
+
+### Tenant-Based Data Isolation
+
+```typescript
+// server/api/data.get.ts
+export default defineEventHandler(async (event) => {
+  const auth0Client = useAuth0(event);
+  const user = await auth0Client.getUser();
+
+  if (!user) {
+    throw createError({ statusCode: 401 });
+  }
+
+  const tenantId = getCookie(event, 'tenant-id');
+
+  if (!tenantId) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'No tenant selected'
+    });
+  }
+
+  // Verify user has access to this tenant
+  const tenants = user['https://my-app.com/tenants'] || [];
+  if (!tenants.includes(tenantId)) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: 'Access denied to this tenant'
+    });
+  }
+
+  return getTenantData(tenantId);
+});
+```
+
+## Organization Support
+
+### Organization Login
+
+```vue
+<!-- pages/org/[organization]/login.vue -->
+<script setup>
+const route = useRoute();
+const organization = route.params.organization;
+</script>
+
+<template>
+  <a :href="`/auth/login?organization=${organization}`">
+    Login to {{ organization }}
+  </a>
+</template>
+```
+
+### Custom Login Handler with Organization
+
+```typescript
+// server/routes/auth/org-login.get.ts
+export default defineEventHandler(async (event) => {
+  const query = getQuery(event);
+  const organization = query.organization as string;
+
+  if (!organization) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Organization parameter required'
+    });
+  }
+
+  const auth0Client = useAuth0(event);
+  const authUrl = await auth0Client.startInteractiveLogin({
+    authorizationParams: {
+      organization: organization
+    },
+    appState: {
+      returnTo: query.returnTo || '/'
+    }
+  });
+
+  return sendRedirect(event, authUrl.href);
+});
+```
+
+## Impersonation Support
+
+### Start Impersonation
+
+```typescript
+// server/api/admin/impersonate.post.ts
+export default defineEventHandler(async (event) => {
+  const auth0Client = useAuth0(event);
+  const admin = await auth0Client.getUser();
+
+  if (!admin) {
+    throw createError({ statusCode: 401 });
+  }
+
+  // Check admin permission
+  const permissions = admin['https://my-app.com/permissions'] || [];
+  if (!permissions.includes('impersonate:users')) {
+    throw createError({ statusCode: 403 });
+  }
+
+  const body = await readBody(event);
+  const { userId } = body;
+
+  // Store impersonation in session
+  const session = await auth0Client.getSession();
+  if (session) {
+    session.impersonating = {
+      adminId: admin.sub,
+      userId: userId
+    };
+  }
+
+  return { success: true };
+});
+```
+
+### End Impersonation
+
+```typescript
+// server/api/admin/stop-impersonate.post.ts
+export default defineEventHandler(async (event) => {
+  const auth0Client = useAuth0(event);
+  const session = await auth0Client.getSession();
+
+  if (session?.impersonating) {
+    delete session.impersonating;
+  }
+
+  return { success: true };
+});
+```
+
+## Progressive Enhancement
+
+### Login Link with Fallback
+
+```vue
+<template>
+  <!-- Progressive enhancement: JavaScript-free login -->
+  <a href="/auth/login" @click.prevent="handleLogin">
+    Login
+  </a>
+</template>
+
+<script setup>
+const handleLogin = async () => {
+  // Enhanced behavior with JavaScript
+  const returnTo = useRoute().fullPath;
+  await navigateTo(`/auth/login?returnTo=${encodeURIComponent(returnTo)}`);
+};
+</script>
+```
+
+## Error Handling
+
+### Global Error Handler
+
+```typescript
+// server/middleware/error-handler.server.ts
+export default defineEventHandler(async (event) => {
+  try {
+    // Continue to next middleware/handler
+  } catch (error) {
+    console.error('Authentication error:', error);
+
+    if (error.statusCode === 401) {
+      return sendRedirect(event, '/auth/login');
+    }
+
+    throw error;
+  }
+});
+```
+
+### Client-Side Error Boundary
+
+```vue
+<!-- error.vue -->
+<script setup>
+const error = useError();
+</script>
+
+<template>
+  <div v-if="error.statusCode === 401">
+    <h1>Authentication Required</h1>
+    <a href="/auth/login">Log In</a>
+  </div>
+
+  <div v-else-if="error.statusCode === 403">
+    <h1>Access Denied</h1>
+    <p>You don't have permission to access this resource.</p>
+  </div>
+
+  <div v-else>
+    <h1>Error {{ error.statusCode }}</h1>
+    <p>{{ error.message }}</p>
+  </div>
+</template>
+```
+
+## Loading States
+
+### Auth Loading Component
+
+```vue
+<!-- components/AuthGuard.vue -->
+<script setup>
+const user = useUser();
+const loading = ref(true);
+
+onMounted(() => {
+  // Give time for SSR hydration
+  setTimeout(() => {
+    loading.value = false;
+  }, 100);
+});
+</script>
+
+<template>
+  <div v-if="loading">
+    Loading...
+  </div>
+  <div v-else-if="user">
+    <slot />
+  </div>
+  <div v-else>
+    <p>You need to log in</p>
+    <a href="/auth/login">Log In</a>
+  </div>
+</template>
+```
+
+## Logging and Monitoring
+
+### Audit Log Middleware
+
+```typescript
+// server/middleware/audit-log.server.ts
+export default defineEventHandler(async (event) => {
+  const auth0Client = useAuth0(event);
+  const user = await auth0Client.getUser();
+
+  if (user) {
+    console.log({
+      timestamp: new Date().toISOString(),
+      userId: user.sub,
+      path: event.node.req.url,
+      method: event.node.req.method,
+      ip: getRequestIP(event);
+    });
+  }
+});
+```
+
+## Token Refresh Handling
+
+```typescript
+// server/api/sensitive-data.get.ts
+export default defineEventHandler(async (event) => {
+  const auth0Client = useAuth0(event);
+
+  try {
+    const { accessToken } = await auth0Client.getAccessToken();
+
+    return await $fetch('https://api.example.com/sensitive', {
+      headers: { Authorization: `Bearer ${accessToken}` }
+    });
+  } catch (error) {
+    // Token might be expired, SDK handles refresh automatically
+    // If refresh fails, session is invalid
+    if (error.statusCode === 401) {
+      throw createError({
+        statusCode: 401,
+        statusMessage: 'Session expired, please log in again'
+      });
+    }
+    throw error;
+  }
+});
+```
+
+---
+
+# Custom Session Stores for Auth0-Nuxt
+
+This guide covers implementing custom session stores for stateful session management in Auth0-Nuxt.
+
+## When to Use Custom Session Stores
+
+Use custom session stores when:
+- Session data exceeds cookie size limits (4KB per chunk)
+- Running in distributed/load-balanced environments
+- Storing sensitive PII that shouldn't be in cookies
+- Need centralized session management across services
+- Implementing advanced session features (expiration, revocation)
+
+## Stateless vs Stateful Sessions
+
+### Stateless (Default)
+- **Storage**: Encrypted, chunked cookies
+- **Advantages**: Simple, no infrastructure, scales horizontally
+- **Disadvantages**: 4KB size limit per chunk, data in browser
+- **Use When**: Sessions are small, simple deployments
+
+### Stateful (Custom Store)
+- **Storage**: Redis, MongoDB, PostgreSQL, etc.
+- **Advantages**: Unlimited size, centralized control, revocable
+- **Disadvantages**: Requires infrastructure, network latency
+- **Use When**: Large sessions, distributed systems, compliance requirements
+
+## SessionStore Interface
+
+All custom stores must implement this interface:
+
+```typescript
+interface SessionStore {
+  set(identifier: string, stateData: StateData): Promise<void>;
+  get(identifier: string): Promise<StateData | undefined>;
+  delete(identifier: string): Promise<void>;
+  deleteByLogoutToken(claims: any, options?: StoreOptions): Promise<void>;
+}
+```
+
+## Redis Session Store
+
+Complete implementation using Nitro's unstorage layer:
+
+### 1. Create Session Store Factory
+
+```typescript
+// server/utils/session-store-factory.ts
+import type { SessionStore, StateData, StoreOptions } from '@auth0/auth0-nuxt';
+import type { Storage } from 'unstorage';
+
+export class RedisSessionStore implements SessionStore {
+  readonly #store: Storage<StateData>;
+
+  constructor(store: Storage<StateData>) {
+    this.#store = store;
+  }
+
+  async set(identifier: string, stateData: StateData): Promise<void> {
+    await this.#store.setItem(identifier, stateData);
+  }
+
+  async get(identifier: string): Promise<StateData | undefined> {
+    const result = await this.#store.getItem<StateData>(identifier);
+    // Redis returns null for missing keys, map to undefined
+    return result ?? undefined;
+  }
+
+  async delete(identifier: string): Promise<void> {
+    await this.#store.removeItem(identifier);
+  }
+
+  async deleteByLogoutToken(claims: any, options?: StoreOptions): Promise<void> {
+    // Extract session ID from logout token claims
+    const sid = claims.sid;
+
+    if (sid) {
+      // Delete session by session ID
+      await this.delete(sid);
+    }
+  }
+}
+
+export default function getSessionStoreInstance() {
+  const storage = useStorage<StateData>('redis');
+  return new RedisSessionStore(storage);
+}
+```
+
+### 2. Configure Module
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: [
+    ['@auth0/auth0-nuxt', {
+      sessionStoreFactoryPath: '~/server/utils/session-store-factory.ts'
+    }]
+  ],
+  runtimeConfig: {
+    auth0: {
+      domain: '',
+      clientId: '',
+      clientSecret: '',
+      sessionSecret: '',
+      appBaseUrl: 'http://localhost:3000',
+    },
+  },
+});
+```
+
+### 3. Configure Nitro Storage
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  nitro: {
+    storage: {
+      redis: {
+        driver: 'redis',
+        host: process.env.REDIS_HOST || '127.0.0.1',
+        port: parseInt(process.env.REDIS_PORT || '6379'),
+        password: process.env.REDIS_PASSWORD,
+        db: parseInt(process.env.REDIS_DB || '0'),
+      }
+    }
+  }
+});
+```
+
+### 4. Docker Compose for Local Development
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - '6379:6379'
+    volumes:
+      - redis_data:/data
+
+volumes:
+  redis_data:
+```
+
+## MongoDB Session Store
+
+Implementation using Nitro's MongoDB driver:
+
+```typescript
+// server/utils/session-store-factory.ts
+import type { SessionStore, StateData, StoreOptions } from '@auth0/auth0-nuxt';
+import type { Storage } from 'unstorage';
+
+export class MongoSessionStore implements SessionStore {
+  readonly #store: Storage<StateData>;
+
+  constructor(store: Storage<StateData>) {
+    this.#store = store;
+  }
+
+  async set(identifier: string, stateData: StateData): Promise<void> {
+    await this.#store.setItem(identifier, stateData);
+  }
+
+  async get(identifier: string): Promise<StateData | undefined> {
+    const result = await this.#store.getItem<StateData>(identifier);
+    return result ?? undefined;
+  }
+
+  async delete(identifier: string): Promise<void> {
+    await this.#store.removeItem(identifier);
+  }
+
+  async deleteByLogoutToken(claims: any, options?: StoreOptions): Promise<void> {
+    const sid = claims.sid;
+    if (sid) {
+      await this.delete(sid);
+    }
+  }
+}
+
+export default function getSessionStoreInstance() {
+  const storage = useStorage<StateData>('mongodb');
+  return new MongoSessionStore(storage);
+}
+```
+
+### MongoDB Nitro Configuration
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  nitro: {
+    storage: {
+      mongodb: {
+        driver: 'mongodb',
+        connectionString: process.env.MONGODB_URI || 'mongodb://localhost:27017',
+        databaseName: 'auth0_sessions',
+        collectionName: 'sessions',
+      }
+    }
+  }
+});
+```
+
+## PostgreSQL Session Store
+
+Using a custom implementation with pg library:
+
+```typescript
+// server/utils/session-store-factory.ts
+import type { SessionStore, StateData, StoreOptions } from '@auth0/auth0-nuxt';
+import { Pool } from 'pg';
+
+export class PostgresSessionStore implements SessionStore {
+  readonly #pool: Pool;
+
+  constructor() {
+    this.#pool = new Pool({
+      host: process.env.POSTGRES_HOST || 'localhost',
+      port: parseInt(process.env.POSTGRES_PORT || '5432'),
+      database: process.env.POSTGRES_DB || 'auth0_sessions',
+      user: process.env.POSTGRES_USER,
+      password: process.env.POSTGRES_PASSWORD,
+    });
+  }
+
+  async set(identifier: string, stateData: StateData): Promise<void> {
+    const query = `
+      INSERT INTO sessions (id, data, expires_at)
+      VALUES ($1, $2, NOW() + INTERVAL '1 day')
+      ON CONFLICT (id) DO UPDATE SET data = $2, expires_at = NOW() + INTERVAL '1 day'
+    `;
+    await this.#pool.query(query, [identifier, JSON.stringify(stateData)]);
+  }
+
+  async get(identifier: string): Promise<StateData | undefined> {
+    const query = `
+      SELECT data FROM sessions
+      WHERE id = $1 AND expires_at > NOW()
+    `;
+    const result = await this.#pool.query(query, [identifier]);
+
+    if (result.rows.length === 0) {
+      return undefined;
+    }
+
+    return JSON.parse(result.rows[0].data);
+  }
+
+  async delete(identifier: string): Promise<void> {
+    await this.#pool.query('DELETE FROM sessions WHERE id = $1', [identifier]);
+  }
+
+  async deleteByLogoutToken(claims: any, options?: StoreOptions): Promise<void> {
+    const sid = claims.sid;
+    if (sid) {
+      await this.delete(sid);
+    }
+  }
+}
+
+export default function getSessionStoreInstance() {
+  return new PostgresSessionStore();
+}
+```
+
+### PostgreSQL Schema
+
+```sql
+CREATE TABLE sessions (
+  id VARCHAR(255) PRIMARY KEY,
+  data JSONB NOT NULL,
+  expires_at TIMESTAMP NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX idx_sessions_expires_at ON sessions(expires_at);
+```
+
+## Back-Channel Logout Implementation
+
+Proper implementation of `deleteByLogoutToken`:
+
+```typescript
+async deleteByLogoutToken(claims: any, options?: StoreOptions): Promise<void> {
+  // Claims from the logout_token JWT
+  const sid = claims.sid; // Session ID
+  const sub = claims.sub; // User ID
+
+  if (sid) {
+    // Delete specific session by session ID
+    await this.delete(sid);
+  } else if (sub) {
+    // Delete all sessions for the user
+    // Implementation depends on your storage
+    // This example assumes you track sessions by user
+    await this.deleteAllForUser(sub);
+  }
+}
+```
+
+## Session Expiration
+
+Implement TTL (Time-To-Live) in your session store:
+
+```typescript
+// Redis with TTL
+async set(identifier: string, stateData: StateData): Promise<void> {
+  await this.#store.setItem(identifier, stateData, {
+    ttl: 86400, // 24 hours in seconds
+  });
+}
+
+// PostgreSQL with automatic cleanup
+// Run this periodically (cronjob or Nitro task)
+async cleanup(): Promise<void> {
+  await this.#pool.query('DELETE FROM sessions WHERE expires_at < NOW()');
+}
+```
+
+## Testing Your Session Store
+
+```typescript
+// test/session-store.test.ts
+import { describe, it, expect } from 'vitest';
+import getSessionStoreInstance from '~/server/utils/session-store-factory';
+
+describe('Session Store', () => {
+  const store = getSessionStoreInstance();
+  const testData = {
+    user: { sub: 'test-user' },
+    idToken: 'test-token',
+    tokenSets: [],
+    internal: { sid: 'test-session', createdAt: Date.now() },
+  };
+
+  it('should store and retrieve session', async () => {
+    await store.set('test-id', testData);
+    const result = await store.get('test-id');
+    expect(result).toEqual(testData);
+  });
+
+  it('should delete session', async () => {
+    await store.set('test-id-2', testData);
+    await store.delete('test-id-2');
+    const result = await store.get('test-id-2');
+    expect(result).toBeUndefined();
+  });
+
+  it('should handle logout token', async () => {
+    await store.set('test-id-3', testData);
+    await store.deleteByLogoutToken({ sid: 'test-session' });
+    const result = await store.get('test-id-3');
+    expect(result).toBeUndefined();
+  });
+});
+```
+
+## Performance Considerations
+
+1. **Connection Pooling**: Always use connection pools for database connections
+2. **Caching**: Consider caching frequently accessed sessions
+3. **Indexing**: Add indexes on session ID and expiration columns
+4. **TTL**: Implement automatic expiration to prevent storage bloat
+5. **Serialization**: Use efficient serialization (JSON, MessagePack)
+
+## Security Considerations
+
+1. **Encryption**: Session data is already encrypted by Auth0-Nuxt
+2. **Access Control**: Restrict database access to your application only
+3. **Network Security**: Use TLS for database connections
+4. **Secrets Management**: Store credentials in environment variables
+5. **Audit Logging**: Log session access for compliance
+
+## Migration from Stateless to Stateful
+
+1. Deploy stateful configuration alongside stateless
+2. New sessions use stateful store
+3. Old cookie-based sessions continue working
+4. Gradually phase out cookie sessions as they expire
+5. Monitor cookie size metrics
diff --git a/main/.mintlify/skills/auth0/references/framework-php-api/index.md b/main/.mintlify/skills/auth0/references/framework-php-api/index.md
new file mode 100644
index 0000000000..44a612e598
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-php-api/index.md
@@ -0,0 +1,1499 @@
+
+# Auth0 PHP API Integration
+
+Protect PHP API endpoints with JWT access token validation using `auth0/auth0-php` in API mode (`STRATEGY_API`).
+
+## Critical rules
+
+- TOKEN ISOLATION: the agent must NEVER directly see, display, echo, log, or store access token values. Do not run `auth0 test token` on its own, and do not ask the user to paste a token into the conversation.
+- When testing protected endpoints, ALWAYS chain token acquisition and the `curl` call in a single `&&` command that captures the token into a shell variable and uses it immediately.
+- A Client ID is REQUIRED for the M2M token flow — if M2M setup was not completed, ask the user first.
+- ALWAYS read `domain` and `audience` from environment variables; never embed credentials in source.
+
+## Prerequisites
+
+- PHP 8.2+ with extensions: `mbstring`, `openssl`, `json`
+- Composer installed
+- Auth0 API resource configured (not an Application - must be an API)
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **PHP web applications with login/logout flows** - use the Auth0 PHP web app integration workflow for session-based authentication
+- **Laravel applications** - Use `auth0/laravel-auth0` which has built-in API guard support
+- **Symfony applications** - Use `auth0/symfony` with its security bundle
+- **Single Page Applications** - use the Auth0 integration workflow for React, Vue, or Angular for client-side auth
+- **Issuing tokens** - This skill is for *validating* access tokens, not issuing them
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+composer require auth0/auth0-php vlucas/phpdotenv guzzlehttp/guzzle guzzlehttp/psr7 "symfony/cache:^7.0"
+```
+
+- `auth0/auth0-php` - The Auth0 SDK (v8.x)
+- `vlucas/phpdotenv` - Load `.env` files into `$_ENV`
+- `guzzlehttp/guzzle` + `guzzlehttp/psr7` - PSR-18 HTTP client required by the SDK
+- `symfony/cache` - PSR-6 cache for JWKS key caching (recommended for production)
+
+### 2. Create Auth0 API
+
+You need an **API** (not Application) in Auth0.
+
+> **STOP - ask the user before proceeding.**
+>
+> Ask exactly this question and wait for their answer before doing anything else:
+>
+> > "How would you like to create the Auth0 API resource?
+> > 1. **Automated** - I'll run Auth0 CLI scripts that create the resource and write the exact values to your `.env` automatically.
+> > 2. **Manual** - You create the API yourself in the Auth0 Dashboard (or via `auth0 apis create`) and provide me the Domain and Audience.
+> >
+> > Which do you prefer? (1 = Automated / 2 = Manual)"
+>
+> Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.
+
+**If the user chose Automated**, follow the Setup Guide section below for complete CLI scripts. The automated path writes `.env` for you - skip Step 3 below and proceed directly to Step 4.
+
+**If the user chose Manual**, follow the Setup Guide section below (Manual Setup) for full instructions. Then continue with Step 3 below.
+
+Quick reference for manual API creation:
+
+```bash
+# Using Auth0 CLI
+auth0 apis create \
+  --name "My PHP API" \
+  --identifier https://my-api.example.com \
+  --json
+```
+
+Or create manually in Auth0 Dashboard -> Applications -> APIs
+
+### 3. Configure Environment
+
+Create `.env`:
+
+```bash
+AUTH0_DOMAIN=your-tenant.us.auth0.com
+AUTH0_AUDIENCE=https://your-api.example.com
+```
+
+`AUTH0_DOMAIN` is your Auth0 tenant domain (without `https://`). `AUTH0_AUDIENCE` is the API identifier you set when creating the API resource in Auth0.
+
+### 4. Initialize Auth0 in API Mode
+
+Create `auth0.php` to initialize the SDK:
+
+```php
+<?php
+
+require 'vendor/autoload.php';
+
+use Auth0\SDK\Auth0;
+use Auth0\SDK\Configuration\SdkConfiguration;
+use Symfony\Component\Cache\Adapter\FilesystemAdapter;
+
+$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
+$dotenv->load();
+
+$configuration = new SdkConfiguration(
+    strategy: SdkConfiguration::STRATEGY_API,
+    domain: $_ENV['AUTH0_DOMAIN'],
+    clientId: null,
+    audience: [$_ENV['AUTH0_AUDIENCE']],
+    tokenAlgorithm: 'RS256',
+    tokenCache: new FilesystemAdapter('auth0_jwks', 600, __DIR__ . '/var/cache'),
+    tokenCacheTtl: 600,
+);
+
+$auth0 = new Auth0($configuration);
+```
+
+Key differences from web app mode:
+- `STRATEGY_API` - stateless, no sessions or cookies
+- `clientId` is not required for RS256 validation (only needed for HS256)
+- `audience` accepts an array of allowed audience strings
+- `tokenCache` is a PSR-6 `CacheItemPoolInterface` for JWKS caching
+
+### 5. Create Middleware Function
+
+Since the SDK does not include a built-in middleware, create a reusable guard function. Create `middleware.php`:
+
+```php
+<?php
+
+use Auth0\SDK\Auth0;
+use Auth0\SDK\Token;
+use Auth0\SDK\Exception\InvalidTokenException;
+
+function requireAuth(Auth0 $auth0, ?array $requiredScopes = null): array
+{
+    $token = $auth0->getBearerToken(
+        server: ['HTTP_AUTHORIZATION']
+    );
+
+    if ($token === null) {
+        http_response_code(401);
+        header('Content-Type: application/json');
+        echo json_encode(['error' => 'unauthorized', 'message' => 'Missing or invalid Bearer token']);
+        exit;
+    }
+
+    $claims = $token->toArray();
+
+    if ($requiredScopes !== null) {
+        $grantedScopes = isset($claims['scope']) ? explode(' ', $claims['scope']) : [];
+        $missingScopes = array_diff($requiredScopes, $grantedScopes);
+
+        if (!empty($missingScopes)) {
+            http_response_code(403);
+            header('Content-Type: application/json');
+            echo json_encode(['error' => 'insufficient_scope', 'message' => 'Token lacks required scopes']);
+            exit;
+        }
+    }
+
+    return $claims;
+}
+```
+
+`getBearerToken()` searches for a Bearer token at the locations you specify, verifies the signature against the JWKS endpoint, and validates claims (issuer, audience, expiration). The `server` parameter is an array of `$_SERVER` key names to check (e.g., `['HTTP_AUTHORIZATION']`) - not `$_SERVER` itself. Returns a `TokenInterface` on success or `null` if no valid token is found (does not throw).
+
+### 6. Create API Routes
+
+Create `index.php` as a front controller:
+
+```php
+<?php
+
+require 'auth0.php';
+require 'middleware.php';
+
+$method = $_SERVER['REQUEST_METHOD'];
+$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
+
+header('Content-Type: application/json');
+
+switch ($path) {
+    case '/api/public':
+        echo json_encode(['message' => 'Public endpoint - no authentication required']);
+        break;
+
+    case '/api/private':
+        $claims = requireAuth($auth0);
+        echo json_encode(['message' => 'Private endpoint', 'sub' => $claims['sub']]);
+        break;
+
+    case '/api/private-scoped':
+        $claims = requireAuth($auth0, ['read:messages']);
+        echo json_encode(['messages' => [], 'sub' => $claims['sub']]);
+        break;
+
+    default:
+        http_response_code(404);
+        echo json_encode(['error' => 'not_found']);
+        break;
+}
+```
+
+### 7. Access Token Claims
+
+The decoded JWT claims are returned as an associative array:
+
+```php
+$claims = requireAuth($auth0);
+
+$userId = $claims['sub'];       // user/client ID
+$scopes = $claims['scope'];     // space-separated granted scopes
+$issuer = $claims['iss'];       // issuer (your Auth0 domain URL)
+$audience = $claims['aud'];     // audience (string or array)
+$expiration = $claims['exp'];   // expiration timestamp
+```
+
+You can also use the `Token` object's typed accessor methods:
+
+```php
+$token = $auth0->getBearerToken(server: ['HTTP_AUTHORIZATION']);
+if ($token !== null) {
+    $subject = $token->getSubject();     // returns ?string
+    $issuer = $token->getIssuer();       // returns ?string
+    $audience = $token->getAudience();   // returns ?array
+    $expiration = $token->getExpiration(); // returns ?int
+}
+```
+
+### 8. Add CORS Headers
+
+When your API receives requests from a browser-based SPA, add CORS headers. Create `cors.php`:
+
+```php
+<?php
+
+function handleCors(array $allowedOrigins): void
+{
+    $origin = $_SERVER['HTTP_ORIGIN'] ?? '';
+
+    if (in_array($origin, $allowedOrigins, true)) {
+        header("Access-Control-Allow-Origin: $origin");
+        header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
+        header('Access-Control-Allow-Headers: Authorization, Content-Type');
+        header('Access-Control-Max-Age: 86400');
+    }
+
+    if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
+        http_response_code(204);
+        exit;
+    }
+}
+```
+
+Then add these lines at the top of `index.php`, before the existing `require 'auth0.php'` line:
+
+```php
+require 'cors.php';
+handleCors(['https://spa.example.com']);
+```
+
+The updated `index.php` head should be:
+
+```php
+<?php
+
+require 'cors.php';
+handleCors(['https://spa.example.com']);
+
+require 'auth0.php';
+require 'middleware.php';
+
+// ... rest of index.php
+```
+
+CORS must be handled before auth so that preflight `OPTIONS` requests short-circuit without triggering token validation.
+
+### 9. Test the API
+
+> **Agent instruction:** Start the PHP built-in server and verify the basic endpoints work without credentials:
+> ```bash
+> php -S localhost:8000 index.php &
+> sleep 1
+> curl -s http://localhost:8000/api/public
+> curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/private
+> ```
+> - `/api/public` should return `{"message":"Public endpoint - no authentication required"}`
+> - `/api/private` should return HTTP 401
+>
+> If both pass, the middleware is working. Kill the background server when done:
+> ```bash
+> kill %1 2>/dev/null
+> ```
+>
+> **Failcheck:** If the server fails to start or `/api/public` errors, check for PHP syntax issues or missing `.env`. After 5-6 failed iterations, use `AskUserQuestion` to ask the user for more details about their environment.
+
+> **Agent instruction: STOP - ask after basic tests pass.**
+>
+> Once public/401 tests pass, ask the user:
+>
+> > "Your API is set up and the middleware is working (public returns 200, private returns 401 without a token). Would you like me to help you set up testing with a real access token?
+> > 1. **Yes** - I'll help you configure an M2M application to get test tokens.
+> > 2. **No** - I'm done for now.
+> >
+> > Which do you prefer?"
+>
+> Do NOT proceed with M2M/token setup unless the user says yes. If they say no, summarize what was done and stop.
+
+> **Agent instruction (M2M app setup - only if user wants testing):**
+>
+> If the user chose to set up testing, ask:
+>
+> > "To test your protected endpoints, you need a Machine-to-Machine (M2M) application authorized to request tokens for this API.
+> > 1. **Create new** - I'll create a new M2M application and authorize it for this API.
+> > 2. **Use existing** - You already have an M2M application. Provide the Client ID and I'll authorize it for this API.
+> >
+> > Which do you prefer? (1 = Create new / 2 = Use existing)"
+>
+> Do NOT proceed until the user answers. Do NOT silently pick an existing application from the tenant.
+>
+> **If the user chose "Create new":**
+> ```bash
+> auth0 apps create \
+>   --name "${PWD##*/} (Test App)" \
+>   --type m2m \
+>   --no-input --json
+> ```
+> Parse the JSON with `jq` to extract `client_id`. Do NOT use `--reveal-secrets` - never expose client secrets in agent context. Instead, use only the `client_id`; the client-credentials/client-grant flow below does not require the secret in agent context.
+> Then create a client grant:
+> ```bash
+> auth0 api post "client-grants" --data '{
+>   "client_id": "<CLIENT_ID>",
+>   "audience": "<API_IDENTIFIER>",
+>   "scope": ["<SCOPES>"]
+> }'
+> ```
+>
+> **If the user chose "Use existing":**
+> Ask for the Client ID. Then create a client grant to authorize it for this API:
+> ```bash
+> auth0 api post "client-grants" --data '{
+>   "client_id": "<USER_PROVIDED_CLIENT_ID>",
+>   "audience": "<API_IDENTIFIER>",
+>   "scope": ["<SCOPES>"]
+> }'
+> ```
+> If the grant already exists (409 conflict), that's fine - the app is already authorized.
+
+> **Agent instruction (token isolation — critical):**
+>
+> The agent must never directly see or display access token values. Token security rules:
+> - Do NOT run `auth0 test token` on its own - it outputs the token to stdout
+> - Do NOT ask the user to paste their token into the conversation
+> - Do NOT echo, print, or log the token value
+> - Do NOT store the token in a file
+>
+> **Secure testing approach (single-command chain):**
+>
+> If the user explicitly asks to test the protected endpoints, use a single-command chain that captures the token into a shell variable and immediately uses it:
+>
+> ```bash
+> php -S localhost:8000 index.php &
+> sleep 1
+> TEST_TOKEN=$(auth0 test token <M2M_CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2> 2>/dev/null | grep -o 'ey[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*') && \
+> [ -n "$TEST_TOKEN" ] && echo "Token acquired (${#TEST_TOKEN} chars)" && \
+> echo "=== GET /api/private ===" && \
+> curl -s http://localhost:8000/api/private -H "Authorization: Bearer $TEST_TOKEN" && \
+> echo "" && echo "=== GET /api/private-scoped ===" && \
+> curl -s http://localhost:8000/api/private-scoped -H "Authorization: Bearer $TEST_TOKEN"
+> kill %1 2>/dev/null
+> ```
+>
+> **Rules:**
+> 1. ONLY use when the user explicitly asks to test
+> 2. Always chain token acquisition + curl in a SINGLE `&&` command
+> 3. Do not add `echo $TEST_TOKEN` or any command that would print the raw token value
+> 4. If the token acquisition fails (empty variable), report that the M2M app may not be authorized
+> 5. **Client ID is required** - if M2M setup was not completed, ask the user first
+>
+> **If the user does NOT ask to test**, just provide the commands for them to run manually:
+> ```
+> auth0 test token <CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2>
+> curl http://localhost:8000/api/private -H "Authorization: Bearer <PASTE_TOKEN_HERE>"
+> ```
+
+Start the server:
+
+```bash
+php -S localhost:8000 index.php
+```
+
+Test public endpoint (no token needed):
+
+```bash
+curl http://localhost:8000/api/public
+```
+
+Test protected endpoint without token (should return 401):
+
+```bash
+curl http://localhost:8000/api/private
+```
+
+Test protected endpoint with token:
+
+```bash
+curl http://localhost:8000/api/private \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+```
+
+Test scoped endpoint:
+
+```bash
+curl http://localhost:8000/api/private-scoped \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+```
+
+Get a test token via Auth0 Dashboard -> APIs -> Test tab, or via the M2M flow described above.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Hardcoding `domain` or `audience` in source | Always read from environment variables - never embed credentials in code |
+| Using `STRATEGY_REGULAR` for an API | API mode must use `SdkConfiguration::STRATEGY_API` - it disables sessions and cookies |
+| Installing without a PSR-18 HTTP client | Must have `guzzlehttp/guzzle` or another PSR-18 client or the SDK cannot fetch JWKS |
+| Not caching JWKS keys | Without a PSR-6 cache, the SDK fetches JWKS on every request - always configure `tokenCache` |
+| Passing `audience` as a string | `audience` must be an array: `['https://my-api.example.com']` not `'https://my-api.example.com'` |
+| Passing `domain` as full URL with `https://` | `domain` should be the bare domain, e.g. `my-tenant.us.auth0.com`, not `https://my-tenant.us.auth0.com` |
+| Using `decode()` without specifying token type | Always pass `tokenType: Token::TYPE_ACCESS_TOKEN` when manually calling `decode()` |
+| Echoing exception messages to users | Use `error_log()` for the real error and return a generic JSON error message |
+| Using an ID token instead of an access token | Must use the **access token** for API auth - ID tokens are for the client app |
+| Created an Application instead of an API in Auth0 | Must create an **API** resource (Applications -> APIs) - an Application doesn't issue access tokens with the right audience |
+| Setting `clientId` and expecting RS256 to need it | For RS256, `clientId` is optional - the SDK validates against the JWKS endpoint |
+| Using `clientSecret` for RS256 validation | `clientSecret` is only needed for HS256 - RS256 uses the public key from JWKS |
+| Passing `$_SERVER` directly to `getBearerToken()` | The `server` param takes an array of key names to look up, e.g. `['HTTP_AUTHORIZATION']` - not `$_SERVER` itself |
+
+## Key SDK Methods
+
+| Method | Returns | Purpose |
+|--------|---------|---------|
+| `getBearerToken` | `?TokenInterface` | Searches specified `$_SERVER` keys for a Bearer token, verifies signature, validates claims. Returns `null` if no token found or validation fails (does not throw). |
+| `decode` | `TokenInterface` | Manually decodes and validates a JWT string |
+| `configuration` | `SdkConfiguration` | Access the SDK configuration instance |
+| `Token::toArray` | `array` | Returns all token claims as an associative array |
+| `Token::getSubject` | `?string` | Returns the `sub` claim (user/client ID) |
+| `Token::getIssuer` | `?string` | Returns the `iss` claim |
+| `Token::getAudience` | `?array` | Returns the `aud` claim |
+| `Token::getExpiration` | `?int` | Returns the `exp` claim (Unix timestamp) |
+
+## Related Skills
+
+- PHP web apps with login/logout using session-based auth → ask for the Auth0 PHP web app integration workflow
+- Basic Auth0 setup and framework detection → set up Auth0 with the CLI (`auth0 login`, then `auth0 apps create`)
+- Manage Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+- Add Multi-Factor Authentication → ask for MFA (feature:mfa)
+
+## Quick Reference
+
+**SdkConfiguration for APIs:**
+```php
+$configuration = new SdkConfiguration(
+    strategy: SdkConfiguration::STRATEGY_API,       // required - stateless mode
+    domain: $_ENV['AUTH0_DOMAIN'],                   // required
+    audience: [$_ENV['AUTH0_AUDIENCE']],             // required - array of identifiers
+    tokenAlgorithm: 'RS256',                        // default
+    tokenCache: $psrCacheAdapter,                    // recommended for production
+    tokenCacheTtl: 600,                             // JWKS cache TTL in seconds
+);
+```
+
+**Token validation:**
+```php
+$token = $auth0->getBearerToken(server: ['HTTP_AUTHORIZATION']);  // returns ?TokenInterface
+$claims = $token->toArray();                         // all claims as array
+$userId = $token->getSubject();                      // sub claim
+```
+
+**Manual decode:**
+```php
+use Auth0\SDK\Token;
+
+$token = $auth0->decode(
+    $jwtString,
+    tokenType: Token::TYPE_ACCESS_TOKEN,
+);
+```
+
+**Environment variables:**
+- `AUTH0_DOMAIN` - your Auth0 tenant domain (e.g. `tenant.us.auth0.com`)
+- `AUTH0_AUDIENCE` - your API identifier (e.g. `https://api.example.com`)
+
+**Common Use Cases:**
+- Protect routes -> `requireAuth($auth0)` (see Step 5)
+- Scope enforcement -> `requireAuth($auth0, ['read:messages'])` (see Step 5)
+- CORS setup -> see the CORS Configuration section below
+- Multi-audience validation -> see the Multi-Audience Validation section below
+- Advanced configuration -> see the API Reference section below
+
+## References
+
+- [auth0/auth0-php on Packagist](https://packagist.org/packages/auth0/auth0-php)
+- [auth0/auth0-PHP on GitHub](https://github.com/auth0/auth0-PHP)
+- [Auth0 PHP API Quickstart](https://auth0.com/docs/quickstart/backend/php)
+- [PHP Documentation](https://www.php.net/)
+- [Access Tokens Guide](https://auth0.com/docs/secure/tokens/access-tokens)
+
+---
+
+# Auth0 PHP API - API Reference
+
+Complete reference for `auth0/auth0-php` in API mode (`STRATEGY_API`).
+
+---
+
+## SdkConfiguration
+
+Configuration class for the Auth0 SDK.
+
+```php
+use Auth0\SDK\Configuration\SdkConfiguration;
+```
+
+### Constructor (API Mode)
+
+```php
+$configuration = new SdkConfiguration(
+    strategy: SdkConfiguration::STRATEGY_API,
+    domain: 'your-tenant.us.auth0.com',
+    clientId: null,
+    clientSecret: null,
+    audience: ['https://my-api.example.com'],
+    organization: null,
+    tokenAlgorithm: 'RS256',
+    tokenJwksUri: null,
+    tokenLeeway: 60,
+    tokenCache: null,
+    tokenCacheTtl: 60,
+);
+```
+
+### Strategy Constants
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `SdkConfiguration::STRATEGY_API` | `'api'` | Stateless JWT validation (no sessions) |
+| `SdkConfiguration::STRATEGY_REGULAR` | `'webapp'` | Session-based web app auth |
+| `SdkConfiguration::STRATEGY_MANAGEMENT_API` | `'management'` | Management API client |
+| `SdkConfiguration::STRATEGY_NONE` | `'none'` | Manual configuration |
+
+### Constructor Parameters (API Mode)
+
+| Parameter | Type | Default | Required | Description |
+|-----------|------|---------|----------|-------------|
+| `strategy` | `string` | `'webapp'` | Yes | Must be `SdkConfiguration::STRATEGY_API` for stateless mode |
+| `domain` | `?string` | `null` | Yes | Auth0 tenant domain (e.g., `my-tenant.us.auth0.com`). No `https://` prefix. |
+| `clientId` | `?string` | `null` | No* | Application Client ID. Required for HS256; optional for RS256. |
+| `clientSecret` | `?string` | `null` | No* | Client Secret. Required for HS256 signature verification. |
+| `audience` | `?array` | `null` | Yes | Array of allowed API identifiers. Token `aud` must intersect. |
+| `organization` | `?array` | `null` | No | Array of allowed organization IDs/names for `org_id`/`org_name` validation. |
+| `tokenAlgorithm` | `string` | `'RS256'` | No | Signing algorithm: `'RS256'` (asymmetric) or `'HS256'` (symmetric). |
+| `tokenJwksUri` | `?string` | `null` | No | JWKS endpoint URI. Auto-set to `https://{domain}/.well-known/jwks.json` if null. |
+| `tokenLeeway` | `int` | `60` | No | Clock skew tolerance in seconds for time-based claim validation (`exp`, `iat`, `auth_time`). |
+| `tokenCache` | `?CacheItemPoolInterface` | `null` | No | PSR-6 cache adapter for JWKS keys. Strongly recommended for production. |
+| `tokenCacheTtl` | `int` | `60` | No | JWKS cache TTL in seconds. |
+
+### Getter Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getAudience()` | `?array` | Configured audience values |
+| `getClientId()` | `?string` | Client ID |
+| `getClientSecret()` | `?string` | Client Secret |
+| `getDomain()` | `?string` | Raw domain string |
+| `formatDomain()` | `string` | Domain with `https://` prefix and trailing slash |
+| `getTokenAlgorithm()` | `string` | `'RS256'` or `'HS256'` |
+| `getTokenJwksUri()` | `?string` | JWKS endpoint URI |
+| `getTokenLeeway()` | `int` | Clock skew tolerance |
+| `getTokenCache()` | `?CacheItemPoolInterface` | PSR-6 cache instance |
+| `getTokenCacheTtl()` | `int` | Cache TTL in seconds |
+
+---
+
+## Auth0
+
+Main SDK class for token operations.
+
+```php
+use Auth0\SDK\Auth0;
+```
+
+### Constructor
+
+```php
+$auth0 = new Auth0($configuration); // accepts SdkConfiguration or array
+```
+
+When passing an array, it is forwarded to the `SdkConfiguration` constructor:
+
+```php
+$auth0 = new Auth0([
+    'strategy' => SdkConfiguration::STRATEGY_API,
+    'domain' => $_ENV['AUTH0_DOMAIN'],
+    'audience' => [$_ENV['AUTH0_AUDIENCE']],
+    'tokenCache' => $cache,
+]);
+```
+
+### getBearerToken
+
+Extracts, verifies, and validates a Bearer token from the request.
+
+```php
+$token = $auth0->getBearerToken(
+    ?array $get = null,
+    ?array $post = null,
+    ?array $server = null,
+    ?array $haystack = null,
+    ?array $needles = null,
+); // returns ?TokenInterface
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `$get` | `?array` | `null` | Array of `$_GET` key names to check for a token (e.g., `['access_token']`) |
+| `$post` | `?array` | `null` | Array of `$_POST` key names to check for a token (e.g., `['access_token']`) |
+| `$server` | `?array` | `null` | Array of `$_SERVER` key names to check for a Bearer token (e.g., `['HTTP_AUTHORIZATION']`). **Not** `$_SERVER` itself. |
+| `$haystack` | `?array` | `null` | Custom array to search for the token |
+| `$needles` | `?array` | `null` | Custom keys to search within haystack |
+
+**Important:** The `$server`, `$get`, and `$post` parameters are arrays of KEY NAMES to look up in the respective superglobals, not the superglobals themselves. Pass `['HTTP_AUTHORIZATION']` not `$_SERVER`.
+
+**Token extraction priority:**
+1. `Authorization: Bearer <token>` header (from `$_SERVER['HTTP_AUTHORIZATION']` when `server: ['HTTP_AUTHORIZATION']`)
+2. Token value from `$_GET` keys listed in `$get`
+3. Token value from `$_POST` keys listed in `$post`
+4. Custom `$haystack` keys
+
+**Returns:** `TokenInterface` on success (signature verified, claims validated), `null` on failure.
+
+**Typical usage:**
+```php
+$token = $auth0->getBearerToken(server: ['HTTP_AUTHORIZATION']);
+```
+
+### decode
+
+Manually decodes, verifies, and validates a JWT string.
+
+```php
+$token = $auth0->decode(
+    string $token,
+    ?array $tokenAudience = null,
+    ?array $tokenOrganization = null,
+    ?string $tokenNonce = null,
+    ?int $tokenMaxAge = null,
+    ?int $tokenLeeway = null,
+    ?int $tokenNow = null,
+    ?int $tokenType = null,
+); // returns TokenInterface
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `$token` | `string` | - | Raw JWT string |
+| `$tokenAudience` | `?array` | `null` | Override audience validation (uses config if null) |
+| `$tokenOrganization` | `?array` | `null` | Override organization validation |
+| `$tokenNonce` | `?string` | `null` | Expected nonce (for ID tokens) |
+| `$tokenMaxAge` | `?int` | `null` | Maximum `auth_time` age in seconds |
+| `$tokenLeeway` | `?int` | `null` | Override leeway (uses config if null) |
+| `$tokenNow` | `?int` | `null` | Override current time for testing |
+| `$tokenType` | `?int` | `null` | Token type constant (see Token class) |
+
+**Throws:** `InvalidTokenException` on validation failure.
+
+**Typical usage for APIs:**
+```php
+use Auth0\SDK\Token;
+
+$token = $auth0->decode($jwtString, tokenType: Token::TYPE_ACCESS_TOKEN);
+```
+
+### configuration
+
+Returns the SDK configuration instance.
+
+```php
+$config = $auth0->configuration(); // returns SdkConfiguration
+```
+
+---
+
+## Token (TokenInterface)
+
+Represents a validated JWT token with typed claim accessors.
+
+```php
+use Auth0\SDK\Token;
+```
+
+### Type Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `Token::TYPE_ID_TOKEN` | `1` | ID token (contains `nonce`) |
+| `Token::TYPE_ACCESS_TOKEN` | `2` | Access token (for API authorization) |
+| `Token::TYPE_LOGOUT_TOKEN` | `3` | Back-channel logout token |
+
+### Algorithm Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `Token::ALGO_RS256` | `'RS256'` | RSA-SHA256 (asymmetric, recommended) |
+| `Token::ALGO_RS384` | `'RS384'` | RSA-SHA384 |
+| `Token::ALGO_RS512` | `'RS512'` | RSA-SHA512 |
+| `Token::ALGO_HS256` | `'HS256'` | HMAC-SHA256 (symmetric) |
+| `Token::ALGO_HS384` | `'HS384'` | HMAC-SHA384 |
+| `Token::ALGO_HS512` | `'HS512'` | HMAC-SHA512 |
+
+### Claim Accessor Methods
+
+| Method | Returns | Claim | Description |
+|--------|---------|-------|-------------|
+| `getSubject()` | `?string` | `sub` | User or client identifier |
+| `getIssuer()` | `?string` | `iss` | Token issuer (Auth0 domain URL) |
+| `getAudience()` | `?array` | `aud` | Intended audience(s) |
+| `getExpiration()` | `?int` | `exp` | Expiration Unix timestamp |
+| `getIssued()` | `?int` | `iat` | Issued-at Unix timestamp |
+| `getAuthTime()` | `?int` | `auth_time` | Authentication time |
+| `getNonce()` | `?string` | `nonce` | Token nonce (ID tokens) |
+| `getOrganization()` | `?string` | `org_id` | Organization identifier |
+| `getOrganizationId()` | `?string` | `org_id` | Organization ID |
+| `getOrganizationName()` | `?string` | `org_name` | Organization name |
+| `getAuthorizedParty()` | `?string` | `azp` | Authorized party |
+| `getIdentifier()` | `?string` | `sid` | Session identifier |
+
+### Data Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `toArray()` | `array` | All claims as associative array |
+| `toJson()` | `string` | Claims as JSON string |
+| `verify()` | `self` | Verify token signature (chainable) |
+| `validate()` | `self` | Validate token claims (chainable) |
+
+---
+
+## InvalidTokenException
+
+Thrown when token verification or validation fails.
+
+```php
+use Auth0\SDK\Exception\InvalidTokenException;
+```
+
+### Common Exception Scenarios
+
+| Method | Message Pattern | Cause |
+|--------|----------------|-------|
+| `missingAudienceClaim()` | "aud claim missing" | Token has no `aud` claim |
+| `mismatchedAudClaim()` | "aud mismatch" | Token `aud` doesn't match configured audience |
+| `missingIssClaim()` | "iss claim missing" | Token has no `iss` claim |
+| `mismatchedIssClaim()` | "iss mismatch" | Token `iss` doesn't match expected issuer |
+| `missingExpClaim()` | "exp claim missing" | Token has no `exp` claim |
+| `mismatchedExpClaim()` | "token expired" | Token `exp` is in the past (accounting for leeway) |
+| `badSignature()` | "signature invalid" | JWT signature doesn't match |
+| `missingKidHeader()` | "kid header missing" | RS256 token missing `kid` header for JWKS lookup |
+| `requiresClientSecret()` | "client secret required" | HS256 validation attempted without `clientSecret` |
+| `unsupportedSigningAlgorithm()` | "unsupported algorithm" | Token uses an algorithm not in supported list |
+
+### Usage
+
+```php
+use Auth0\SDK\Exception\InvalidTokenException;
+
+try {
+    $token = $auth0->decode($jwt, tokenType: Token::TYPE_ACCESS_TOKEN);
+} catch (InvalidTokenException $e) {
+    error_log('Token validation failed: ' . $e->getMessage());
+    http_response_code(401);
+    header('Content-Type: application/json');
+    echo json_encode(['error' => 'invalid_token', 'message' => 'Token validation failed']);
+    exit;
+}
+```
+
+---
+
+## Token Verification Flow
+
+When `getBearerToken()` or `decode()` is called, the SDK performs:
+
+1. **Parse** - Splits JWT into header, payload, signature; base64-decodes each
+2. **Verify** (signature) - For RS256: fetches public key from JWKS by `kid` header, verifies RSA signature. For HS256: verifies HMAC using `clientSecret`.
+3. **Validate** (claims) - Checks `iss` matches `https://{domain}/`, `aud` intersects configured audience, `exp` is in the future (with leeway)
+
+### JWKS Caching Behavior
+
+- Cache key: Derived from the JWKS URI (`https://{domain}/.well-known/jwks.json`)
+- On cache miss: HTTP GET to the JWKS endpoint
+- On cache hit: Uses cached keyset directly
+- Cache TTL: Controlled by `tokenCacheTtl` (default 60 seconds)
+- Keys are stored as the full JWKS response (all keys)
+- If the expected `kid` is not in the cached response, the cache is invalidated and JWKS is re-fetched
+
+---
+
+## Full Initialization Example
+
+```php
+<?php
+
+require 'vendor/autoload.php';
+
+use Auth0\SDK\Auth0;
+use Auth0\SDK\Configuration\SdkConfiguration;
+use Symfony\Component\Cache\Adapter\FilesystemAdapter;
+
+$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
+$dotenv->load();
+
+$cache = new FilesystemAdapter('auth0_jwks', 600, __DIR__ . '/var/cache');
+
+$auth0 = new Auth0(new SdkConfiguration(
+    strategy: SdkConfiguration::STRATEGY_API,
+    domain: $_ENV['AUTH0_DOMAIN'],
+    audience: [$_ENV['AUTH0_AUDIENCE']],
+    tokenAlgorithm: 'RS256',
+    tokenCache: $cache,
+    tokenCacheTtl: 600,
+    tokenLeeway: 60,
+));
+
+// Validate Bearer token
+$token = $auth0->getBearerToken(server: ['HTTP_AUTHORIZATION']);
+
+if ($token === null) {
+    http_response_code(401);
+    header('Content-Type: application/json');
+    echo json_encode(['error' => 'unauthorized']);
+    exit;
+}
+
+$claims = $token->toArray();
+$userId = $token->getSubject();
+```
+
+---
+
+## References
+
+- [auth0/auth0-PHP on GitHub](https://github.com/auth0/auth0-PHP)
+
+---
+
+# Auth0 PHP API Integration Patterns
+
+Advanced integration patterns for PHP API applications using `auth0/auth0-php` in API mode.
+
+---
+
+## Scope-Based Authorization
+
+### Define Permissions in Auth0
+
+1. Go to Auth0 Dashboard -> Applications -> APIs
+2. Select your API
+3. Click the **Permissions** tab
+4. Add permissions matching the scopes you want to enforce (e.g., `read:messages`, `write:messages`)
+
+### Enforce Scopes in Middleware
+
+```php
+function requireAuth(Auth0 $auth0, ?array $requiredScopes = null): array
+{
+    $token = $auth0->getBearerToken(server: ['HTTP_AUTHORIZATION']);
+
+    if ($token === null) {
+        http_response_code(401);
+        header('Content-Type: application/json');
+        echo json_encode(['error' => 'unauthorized', 'message' => 'Missing or invalid Bearer token']);
+        exit;
+    }
+
+    $claims = $token->toArray();
+
+    if ($requiredScopes !== null) {
+        $grantedScopes = isset($claims['scope']) ? explode(' ', $claims['scope']) : [];
+        $missingScopes = array_diff($requiredScopes, $grantedScopes);
+
+        if (!empty($missingScopes)) {
+            http_response_code(403);
+            header('Content-Type: application/json');
+            header('WWW-Authenticate: Bearer error="insufficient_scope"');
+            echo json_encode(['error' => 'insufficient_scope', 'message' => 'Token lacks required scopes']);
+            exit;
+        }
+    }
+
+    return $claims;
+}
+```
+
+### Route Examples
+
+```php
+// Requires read:messages scope
+case '/api/messages':
+    $claims = requireAuth($auth0, ['read:messages']);
+    echo json_encode(['messages' => fetchMessages($claims['sub'])]);
+    break;
+
+// Requires both read:data and write:data (AND logic)
+case '/api/data':
+    if ($method === 'POST') {
+        $claims = requireAuth($auth0, ['read:data', 'write:data']);
+        echo json_encode(['created' => true]);
+    }
+    break;
+```
+
+### Request Tokens with Scopes
+
+Clients must request tokens that include the required scopes:
+
+```bash
+curl -X POST https://your-tenant.us.auth0.com/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_id": "YOUR_CLIENT_ID",
+    "client_secret": "YOUR_CLIENT_SECRET",
+    "audience": "https://my-api.example.com",
+    "grant_type": "client_credentials",
+    "scope": "read:messages write:messages"
+  }'
+```
+
+---
+
+## Permission-Based RBAC
+
+Auth0 can embed RBAC permissions directly in the access token (instead of scopes). Enable this in Auth0 Dashboard -> APIs -> Settings -> "Add Permissions in the Access Token".
+
+```php
+function requirePermission(Auth0 $auth0, array $requiredPermissions): array
+{
+    $token = $auth0->getBearerToken(server: ['HTTP_AUTHORIZATION']);
+
+    if ($token === null) {
+        http_response_code(401);
+        header('Content-Type: application/json');
+        echo json_encode(['error' => 'unauthorized', 'message' => 'Missing or invalid Bearer token']);
+        exit;
+    }
+
+    $claims = $token->toArray();
+    $grantedPermissions = $claims['permissions'] ?? [];
+    $missingPermissions = array_diff($requiredPermissions, $grantedPermissions);
+
+    if (!empty($missingPermissions)) {
+        http_response_code(403);
+        header('Content-Type: application/json');
+        echo json_encode(['error' => 'insufficient_permissions', 'message' => 'Missing required permissions']);
+        exit;
+    }
+
+    return $claims;
+}
+```
+
+---
+
+## Multi-Audience Validation
+
+If your token may target multiple APIs, configure multiple audiences:
+
+```php
+$configuration = new SdkConfiguration(
+    strategy: SdkConfiguration::STRATEGY_API,
+    domain: $_ENV['AUTH0_DOMAIN'],
+    audience: [
+        $_ENV['AUTH0_AUDIENCE'],
+        'https://secondary-api.example.com',
+    ],
+    tokenCache: new FilesystemAdapter('auth0_jwks', 600, __DIR__ . '/var/cache'),
+);
+```
+
+The SDK validates that the token's `aud` claim intersects with at least one of the configured audiences (ANY match succeeds).
+
+---
+
+## CORS Configuration
+
+When your API receives requests from a browser-based SPA, CORS headers are required.
+
+### Basic CORS Handler
+
+```php
+function handleCors(array $allowedOrigins): void
+{
+    $origin = $_SERVER['HTTP_ORIGIN'] ?? '';
+
+    if (in_array($origin, $allowedOrigins, true)) {
+        header("Access-Control-Allow-Origin: $origin");
+        header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
+        header('Access-Control-Allow-Headers: Authorization, Content-Type');
+        header('Access-Control-Max-Age: 86400');
+        header('Vary: Origin');
+    }
+
+    if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
+        http_response_code(204);
+        exit;
+    }
+}
+```
+
+Call before any other logic in `index.php`:
+
+```php
+require 'cors.php';
+handleCors(['https://your-spa.example.com', 'http://localhost:3000']);
+
+require 'auth0.php';
+require 'middleware.php';
+// ... routes
+```
+
+### Production CORS
+
+- Never use `*` for `Access-Control-Allow-Origin` with credentialed requests
+- Always validate the `Origin` header against an allowlist
+- Include `Vary: Origin` to prevent cache poisoning
+
+---
+
+## Error Handling
+
+### Structured Error Responses
+
+```php
+function apiError(int $status, string $error, string $message): never
+{
+    http_response_code($status);
+    header('Content-Type: application/json');
+    echo json_encode(['error' => $error, 'message' => $message]);
+    exit;
+}
+```
+
+### Handling Token Validation Errors
+
+`getBearerToken()` returns `null` when validation fails. For more granular error handling, use `decode()` directly:
+
+```php
+use Auth0\SDK\Token;
+use Auth0\SDK\Exception\InvalidTokenException;
+
+$authHeader = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
+if (!str_starts_with($authHeader, 'Bearer ')) {
+    apiError(401, 'unauthorized', 'Missing Bearer token');
+}
+
+$jwt = substr($authHeader, 7);
+
+try {
+    $token = $auth0->decode(
+        $jwt,
+        tokenType: Token::TYPE_ACCESS_TOKEN,
+    );
+    $claims = $token->toArray();
+} catch (InvalidTokenException $e) {
+    error_log('Token validation failed: ' . $e->getMessage());
+    apiError(401, 'invalid_token', 'Token validation failed');
+}
+```
+
+### Common Error Codes
+
+| Status | Error Code | Cause |
+|--------|------------|-------|
+| 401 | `unauthorized` | Missing or malformed Authorization header |
+| 401 | `invalid_token` | Expired token, invalid signature, wrong issuer/audience |
+| 403 | `insufficient_scope` | Valid token but missing required scopes |
+| 403 | `insufficient_permissions` | Valid token but missing required RBAC permissions |
+
+---
+
+## PSR-6 Cache Setup
+
+### Filesystem Cache (Development)
+
+```php
+use Symfony\Component\Cache\Adapter\FilesystemAdapter;
+
+$cache = new FilesystemAdapter(
+    'auth0_jwks',       // namespace
+    600,                // default TTL in seconds
+    __DIR__ . '/var/cache'  // cache directory
+);
+```
+
+### APCu Cache (Production - Single Server)
+
+```php
+use Symfony\Component\Cache\Adapter\ApcuAdapter;
+
+$cache = new ApcuAdapter('auth0_jwks', 600);
+```
+
+Requires the `apcu` PHP extension.
+
+### Redis Cache (Production - Multi-Server)
+
+```php
+use Symfony\Component\Cache\Adapter\RedisAdapter;
+
+$redis = RedisAdapter::createConnection('redis://localhost:6379');
+$cache = new RedisAdapter($redis, 'auth0_jwks', 600);
+```
+
+### Memcached
+
+```php
+use Symfony\Component\Cache\Adapter\MemcachedAdapter;
+
+$memcached = MemcachedAdapter::createConnection('memcached://localhost:11211');
+$cache = new MemcachedAdapter($memcached, 'auth0_jwks', 600);
+```
+
+### Using the Cache
+
+Pass any PSR-6 `CacheItemPoolInterface` to `SdkConfiguration`:
+
+```php
+$configuration = new SdkConfiguration(
+    strategy: SdkConfiguration::STRATEGY_API,
+    domain: $_ENV['AUTH0_DOMAIN'],
+    audience: [$_ENV['AUTH0_AUDIENCE']],
+    tokenCache: $cache,
+    tokenCacheTtl: 600,
+);
+```
+
+---
+
+## Custom Claims
+
+Access custom claims added via Auth0 Actions:
+
+```php
+$claims = requireAuth($auth0);
+
+// Namespaced custom claims (recommended)
+$role = $claims['https://example.com/role'] ?? null;
+$orgId = $claims['https://example.com/org_id'] ?? null;
+
+// RBAC permissions (if enabled on the API)
+$permissions = $claims['permissions'] ?? [];
+```
+
+Auth0 Actions add custom claims using namespaced keys to avoid collisions with registered JWT claims.
+
+---
+
+## Organization Validation
+
+For multi-tenant applications using Auth0 Organizations:
+
+```php
+$configuration = new SdkConfiguration(
+    strategy: SdkConfiguration::STRATEGY_API,
+    domain: $_ENV['AUTH0_DOMAIN'],
+    audience: [$_ENV['AUTH0_AUDIENCE']],
+    organization: ['org_abc123', 'org_def456'],
+    tokenCache: new FilesystemAdapter('auth0_jwks', 600, __DIR__ . '/var/cache'),
+);
+```
+
+The SDK validates the `org_id` or `org_name` claim in the token against the configured allowlist.
+
+---
+
+## HS256 Configuration
+
+If your API uses HS256 (symmetric signing) instead of RS256:
+
+```php
+$configuration = new SdkConfiguration(
+    strategy: SdkConfiguration::STRATEGY_API,
+    domain: $_ENV['AUTH0_DOMAIN'],
+    clientId: $_ENV['AUTH0_CLIENT_ID'],
+    clientSecret: $_ENV['AUTH0_CLIENT_SECRET'],
+    audience: [$_ENV['AUTH0_AUDIENCE']],
+    tokenAlgorithm: 'HS256',
+);
+```
+
+HS256 uses the client secret as the signing key. No JWKS fetching or caching is needed. However, RS256 is recommended for APIs as it doesn't require sharing secrets.
+
+---
+
+## Testing
+
+### Unit Tests with PHPUnit
+
+```php
+use PHPUnit\Framework\TestCase;
+
+class ApiTest extends TestCase
+{
+    public function testPublicEndpoint(): void
+    {
+        $response = $this->request('GET', '/api/public');
+        $this->assertEquals(200, $response['status']);
+    }
+
+    public function testProtectedEndpointWithoutToken(): void
+    {
+        $response = $this->request('GET', '/api/private');
+        $this->assertEquals(401, $response['status']);
+    }
+
+    private function request(string $method, string $path, ?string $token = null): array
+    {
+        // Use PHP's built-in test server or a test framework
+        $ch = curl_init("http://localhost:8000$path");
+        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+        if ($token !== null) {
+            curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer $token"]);
+        }
+        $body = curl_exec($ch);
+        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+        curl_close($ch);
+        return ['status' => $status, 'body' => json_decode($body, true)];
+    }
+}
+```
+
+### Integration Testing with Real Tokens
+
+```bash
+# Get a test token via Auth0 CLI
+TOKEN=$(auth0 test token --audience https://my-api.example.com --no-input 2>/dev/null)
+
+# Test protected endpoint
+curl -s http://localhost:8000/api/private \
+  -H "Authorization: Bearer $TOKEN" | jq .
+```
+
+---
+
+## Security Considerations
+
+- **Never hardcode Domain or Audience** - Always use environment variables or configuration files
+- **Always cache JWKS keys** - Without caching, every request fetches from Auth0's JWKS endpoint
+- **Use HTTPS in production** - Bearer tokens are sent in headers and must be encrypted in transit
+- **Use minimal scopes** - Only request and enforce scopes your API actually needs
+- **Validate access tokens, not ID tokens** - ID tokens are for the client app, access tokens are for API authorization
+- **Never echo exception details** - Use `error_log()` and return generic error messages
+- **Set short token expiration** - Configure access token lifetime in Auth0 Dashboard -> APIs -> Settings
+
+---
+
+---
+
+# Auth0 PHP API Setup Guide
+
+Setup instructions for PHP API applications using `auth0/auth0-php` in API mode.
+
+---
+
+## Quick Setup (Automated)
+
+Below automates the setup using the Auth0 CLI.
+
+**Never read the contents of `.env.local` or `.env` at any point during setup.** The file may contain sensitive secrets that should not be exposed in the LLM context. If you determine you need to read the file for any reason, ask the user for explicit permission before doing so - do not proceed until the user confirms.
+
+**Before running any part of this setup that writes to an env file, you MUST ask the user for explicit confirmation.** Follow the steps below precisely.
+
+### Step 1: Check for existing env files and confirm with user
+
+Before writing credentials, check which env files exist:
+
+```bash
+test -f .env.local && echo "ENV_LOCAL_EXISTS" || echo "ENV_LOCAL_NOT_FOUND"
+test -f .env && echo "ENV_EXISTS" || echo "ENV_NOT_FOUND"
+```
+
+Then determine the target file using this precedence: `.env.local` (if present), otherwise `.env`. Ask the user for explicit confirmation before proceeding - do not continue until the user confirms:
+
+- If the target file (`.env.local` or `.env`) exists, ask:
+  - Question: "A `<target file>` already exists and may contain secrets unrelated to Auth0. This setup will append Auth0 credentials without modifying existing content. Do you want to proceed?"
+  - Options: "Yes, append to existing `<target file>`" / "No, I'll update it manually"
+
+- If neither file exists, ask:
+  - Question: "This setup will create a `.env` file containing Auth0 credentials (AUTH0_DOMAIN, AUTH0_AUDIENCE). Do you want to proceed?"
+  - Options: "Yes, create .env" / "No, I'll configure it manually"
+
+**Do not proceed with writing to any env file unless the user selects the confirmation option.**
+
+### Step 2: Run automated setup (only after confirmation)
+
+```bash
+#!/bin/bash
+
+# Install Auth0 CLI
+if ! command -v auth0 &> /dev/null; then
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    brew install auth0/auth0-cli/auth0
+  else
+    curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh -o /tmp/auth0-install.sh
+    echo "Review the install script at /tmp/auth0-install.sh before running"
+    sh /tmp/auth0-install.sh -b /usr/local/bin
+    rm /tmp/auth0-install.sh
+  fi
+fi
+
+# Verify jq is available (used to parse JSON from Auth0 CLI)
+if ! command -v jq &> /dev/null; then
+  echo "jq is required but not installed. Install it: https://jqlang.github.io/jq/download/" >&2
+  exit 1
+fi
+
+# Login
+auth0 login 2>/dev/null || auth0 login
+
+# Create API resource
+API_JSON=$(auth0 apis create \
+  --name "${PWD##*/}-api" \
+  --identifier "https://${PWD##*/}.example.com" \
+  --json)
+
+AUDIENCE=$(printf '%s' "$API_JSON" | jq -r '.identifier')
+if [ -z "$AUDIENCE" ] || [ "$AUDIENCE" = "null" ]; then
+  echo "Failed to resolve API identifier from CLI output" >&2
+  exit 1
+fi
+
+# Get domain
+DOMAIN=$(auth0 tenants list --json | jq -r '.[0].name')
+if [ -z "$DOMAIN" ] || [ "$DOMAIN" = "null" ]; then
+  echo "Failed to resolve Auth0 tenant domain" >&2
+  exit 1
+fi
+
+# Determine target env file
+if [ -f .env.local ]; then
+  TARGET_FILE=".env.local"
+elif [ -f .env ]; then
+  TARGET_FILE=".env"
+else
+  TARGET_FILE=".env"
+fi
+
+# Append Auth0 credentials
+cat >> "$TARGET_FILE" << ENVEOF
+
+# Auth0 API Configuration
+AUTH0_DOMAIN=$DOMAIN
+AUTH0_AUDIENCE=$AUDIENCE
+ENVEOF
+
+echo "Auth0 API credentials written to $TARGET_FILE"
+```
+
+---
+
+## Manual Setup
+
+### Install Packages
+
+```bash
+composer require auth0/auth0-php vlucas/phpdotenv guzzlehttp/guzzle guzzlehttp/psr7 "symfony/cache:^7.0"
+```
+
+**Package breakdown:**
+- `auth0/auth0-php` - The Auth0 SDK (v8.x)
+- `vlucas/phpdotenv` - Load `.env` files
+- `guzzlehttp/guzzle` - PSR-18 HTTP client (required by the SDK for JWKS fetching)
+- `guzzlehttp/psr7` - PSR-7 HTTP messages (required by the SDK)
+- `symfony/cache` - PSR-6 cache adapter for JWKS key caching
+
+### Create Auth0 API Resource
+
+1. Go to Auth0 Dashboard -> Applications -> APIs
+2. Click **Create API**
+3. Set a **Name** and an **Identifier** (e.g., `https://my-api.example.com`)
+4. Note the Identifier - this is your `Audience`
+
+### Create .env
+
+```bash
+AUTH0_DOMAIN=your-tenant.us.auth0.com
+AUTH0_AUDIENCE=https://my-api.example.com
+```
+
+**Important:** Domain format is `your-tenant.us.auth0.com` - do NOT include `https://`.
+
+### Get Auth0 Configuration
+
+- **Domain:** Auth0 Dashboard -> Settings -> Domain (or `auth0 tenants list`)
+- **Audience:** The identifier you set when creating the API resource
+
+### Using Environment Variables in Production
+
+For production/containers, export environment variables directly:
+
+```bash
+export AUTH0_DOMAIN=your-tenant.us.auth0.com
+export AUTH0_AUDIENCE=https://my-api.example.com
+```
+
+---
+
+## Getting a Test Token
+
+### Via Auth0 Dashboard
+
+1. Go to Auth0 Dashboard -> Applications -> APIs
+2. Select your API
+3. Click the **Test** tab
+4. Click **Copy Token** to get a test access token
+
+### Via Auth0 CLI
+
+```bash
+# Get access token for testing
+auth0 test token \
+  --audience https://my-api.example.com
+```
+
+### Via curl (Client Credentials Flow)
+
+First, you need a Machine-to-Machine application authorized for your API:
+
+1. Go to Auth0 Dashboard -> Applications -> APIs -> Your API -> Machine to Machine Applications
+2. Authorize an existing M2M app or create a new one
+3. Note the Client ID and Client Secret
+
+```bash
+curl -X POST https://your-tenant.us.auth0.com/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_id": "YOUR_M2M_CLIENT_ID",
+    "client_secret": "YOUR_M2M_CLIENT_SECRET",
+    "audience": "https://my-api.example.com",
+    "grant_type": "client_credentials"
+  }'
+```
+
+### Request Tokens with Specific Scopes
+
+First, define permissions on your API resource (Dashboard -> APIs -> Permissions tab), then:
+
+```bash
+curl -X POST https://your-tenant.us.auth0.com/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_id": "YOUR_M2M_CLIENT_ID",
+    "client_secret": "YOUR_M2M_CLIENT_SECRET",
+    "audience": "https://my-api.example.com",
+    "grant_type": "client_credentials",
+    "scope": "read:messages write:messages"
+  }'
+```
+
+---
+
+## PHP Version Requirements
+
+- PHP 8.2 or higher
+- Required extensions: `mbstring`, `openssl`, `json`
+- Verify with: `php -v && php -m | grep -E "mbstring|openssl|json"`
+
+---
+
+## PSR Dependencies
+
+The SDK uses PSR auto-discovery (`psr-discovery/all`) to find compatible HTTP implementations. If you install `guzzlehttp/guzzle`, it satisfies all PSR requirements automatically.
+
+If you prefer a different HTTP client:
+- **Symfony HTTP Client**: `composer require symfony/http-client nyholm/psr7`
+- **PHP-HTTP Curl**: `composer require php-http/curl-client nyholm/psr7`
+
+---
+
+## Troubleshooting
+
+**401 Unauthorized - "invalid_token":** Verify that `AUTH0_AUDIENCE` in `.env` exactly matches your API Identifier in Auth0 Dashboard.
+
+**401 Unauthorized - "invalid_issuer":** Ensure `AUTH0_DOMAIN` does not include `https://` - use `your-tenant.us.auth0.com` format only.
+
+**"No PSR-18 HTTP Client found":** Install `guzzlehttp/guzzle` or another PSR-18 compatible client.
+
+**Token expired:** Test tokens from the Dashboard are short-lived. Request a fresh token.
+
+**JWKS fetch fails:** Check that your server can make outbound HTTPS requests to `https://{domain}/.well-known/jwks.json`.
+
+**"audience is required":** Ensure `audience` is passed as a non-empty array in `SdkConfiguration`.
+
+---
diff --git a/main/.mintlify/skills/auth0/references/framework-php/index.md b/main/.mintlify/skills/auth0/references/framework-php/index.md
new file mode 100644
index 0000000000..c878902700
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-php/index.md
@@ -0,0 +1,1513 @@
+
+# Auth0 PHP Web App Integration
+
+Add login, logout, and user profile to a PHP web application using `auth0/auth0-php`.
+
+## Prerequisites
+
+- PHP 8.2+ with extensions: `mbstring`, `openssl`, `json`
+- Composer installed
+- Auth0 Regular Web Application configured (not an API - must be an Application)
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **PHP APIs with JWT Bearer validation** - Use the Auth0 PHP API integration workflow for stateless API token validation
+- **Laravel applications** - Use a dedicated Laravel integration with `auth0/laravel-auth0`
+- **Symfony applications** - Use a dedicated Symfony integration with `auth0/symfony`
+- **Single Page Applications** - Use the Auth0 integration workflow for React, Vue, or Angular for client-side auth
+- **Next.js applications** - Use the Auth0 integration workflow for Next.js, which handles both client and server
+- **Node.js web apps** - Use the Auth0 integration workflow for Express or Fastify for session-based auth
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+composer require auth0/auth0-php vlucas/phpdotenv guzzlehttp/guzzle guzzlehttp/psr7
+```
+
+- `auth0/auth0-php` - The Auth0 SDK
+- `vlucas/phpdotenv` - Load `.env` files into `$_ENV`
+- `guzzlehttp/guzzle` + `guzzlehttp/psr7` - PSR-18 HTTP client required by the SDK
+
+### 2. Configure Environment
+
+Create `.env`:
+
+```bash
+AUTH0_DOMAIN=your-tenant.us.auth0.com
+AUTH0_CLIENT_ID=your_client_id
+AUTH0_CLIENT_SECRET=your_client_secret
+AUTH0_COOKIE_SECRET=your_generated_secret
+AUTH0_REDIRECT_URI=http://localhost:3000/callback
+```
+
+`AUTH0_DOMAIN` is your Auth0 tenant domain (without `https://`). `AUTH0_CLIENT_ID` and `AUTH0_CLIENT_SECRET` come from your Auth0 Application settings. `AUTH0_COOKIE_SECRET` is used for encrypting session cookies - generate with `openssl rand -hex 32`.
+
+### 3. Configure Auth0 Dashboard
+
+In your Auth0 Application settings:
+- **Application Type**: Regular Web Application
+- **Allowed Callback URLs**: `http://localhost:3000/callback`
+- **Allowed Logout URLs**: `http://localhost:3000`
+
+### 4. Create Auth Configuration
+
+Create `auth0.php` to initialize the SDK:
+
+```php
+<?php
+
+require 'vendor/autoload.php';
+
+use Auth0\SDK\Auth0;
+use Auth0\SDK\Configuration\SdkConfiguration;
+
+// Load environment variables
+$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
+$dotenv->load();
+
+$configuration = new SdkConfiguration(
+    strategy: SdkConfiguration::STRATEGY_REGULAR,
+    domain: $_ENV['AUTH0_DOMAIN'],
+    clientId: $_ENV['AUTH0_CLIENT_ID'],
+    clientSecret: $_ENV['AUTH0_CLIENT_SECRET'],
+    cookieSecret: $_ENV['AUTH0_COOKIE_SECRET'],
+    redirectUri: $_ENV['AUTH0_REDIRECT_URI'],
+    scope: ['openid', 'profile', 'email'],
+);
+
+$auth0 = new Auth0($configuration);
+```
+
+Create one `Auth0` instance and reuse it. Never hardcode credentials - always use environment variables.
+
+**How this works:** The SDK encrypts session data (tokens, user profile) using AES-256-GCM with a key derived from `cookieSecret` via HKDF-SHA256. Session data is stored in an encrypted cookie by default - no server-side database required.
+
+### 5. Create Index Page (Router)
+
+Create `index.php` as a simple front controller. Create the `routes/` directory first:
+
+```php
+<?php
+
+$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
+
+if ($path === '/style.css') {
+    header('Content-Type: text/css');
+    readfile(__DIR__ . '/style.css');
+    exit;
+}
+
+require 'auth0.php';
+
+switch ($path) {
+    case '/':
+        require 'routes/home.php';
+        break;
+    case '/login':
+        require 'routes/login.php';
+        break;
+    case '/callback':
+        require 'routes/callback.php';
+        break;
+    case '/profile':
+        require 'routes/profile.php';
+        break;
+    case '/logout':
+        require 'routes/logout.php';
+        break;
+    default:
+        http_response_code(404);
+        echo 'Not found';
+        break;
+}
+```
+
+The static file handler for `/style.css` is placed before `require 'auth0.php'` so stylesheets load without initializing the SDK.
+
+### 6. Add Stylesheet
+
+Create `style.css`:
+
+```css
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+
+body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    background: #f5f7fa;
+    color: #1a1a2e;
+    line-height: 1.6;
+    min-height: 100vh;
+}
+
+.container {
+    max-width: 800px;
+    margin: 0 auto;
+    padding: 40px 20px;
+}
+
+.card {
+    background: #fff;
+    border-radius: 12px;
+    padding: 28px;
+    margin-bottom: 20px;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);
+    border: 1px solid #e8ecf0;
+}
+
+.card.center {
+    text-align: center;
+    padding: 60px 28px;
+}
+
+h1 {
+    font-size: 1.5rem;
+    font-weight: 600;
+    margin-bottom: 4px;
+}
+
+h2 {
+    font-size: 1.1rem;
+    font-weight: 600;
+    margin-bottom: 16px;
+    color: #444;
+}
+
+.subtitle {
+    color: #666;
+    font-size: 0.95rem;
+}
+
+.card.center .subtitle {
+    margin: 12px 0 28px;
+}
+
+.user-header {
+    display: flex;
+    align-items: center;
+    gap: 16px;
+}
+
+.avatar {
+    width: 48px;
+    height: 48px;
+    border-radius: 50%;
+    object-fit: cover;
+}
+
+.avatar-lg {
+    width: 72px;
+    height: 72px;
+}
+
+.nav-links {
+    margin-top: 20px;
+    display: flex;
+    gap: 12px;
+}
+
+.top-nav {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 20px;
+}
+
+.btn {
+    display: inline-block;
+    padding: 10px 20px;
+    border-radius: 8px;
+    text-decoration: none;
+    font-size: 0.9rem;
+    font-weight: 500;
+    transition: all 0.15s ease;
+}
+
+.btn-primary {
+    background: #635bff;
+    color: #fff;
+}
+
+.btn-primary:hover {
+    background: #4b44d4;
+}
+
+.btn-secondary {
+    background: #f0f0f5;
+    color: #444;
+}
+
+.btn-secondary:hover {
+    background: #e4e4ec;
+}
+
+.btn-back {
+    background: none;
+    color: #635bff;
+    padding: 10px 0;
+}
+
+.btn-back:hover {
+    color: #4b44d4;
+}
+
+.info-table {
+    width: 100%;
+    border-collapse: collapse;
+}
+
+.info-table tr {
+    border-bottom: 1px solid #f0f0f5;
+}
+
+.info-table tr:last-child {
+    border-bottom: none;
+}
+
+.info-table td {
+    padding: 10px 0;
+    vertical-align: top;
+}
+
+.info-table .label {
+    font-weight: 500;
+    color: #666;
+    width: 160px;
+    font-size: 0.85rem;
+    text-transform: uppercase;
+    letter-spacing: 0.02em;
+}
+
+.info-table .value {
+    color: #1a1a2e;
+    word-break: break-all;
+}
+
+.token-box {
+    background: #f8f9fb;
+    border: 1px solid #e8ecf0;
+    border-radius: 8px;
+    padding: 14px;
+    font-size: 0.8rem;
+    font-family: 'SF Mono', Monaco, 'Cascadia Code', monospace;
+    word-break: break-all;
+    white-space: pre-wrap;
+    max-height: 120px;
+    overflow-y: auto;
+    margin-bottom: 16px;
+}
+```
+
+### 7. Add Home Route
+
+Create `routes/home.php`:
+
+```php
+<?php
+
+$credentials = $auth0->getCredentials();
+?>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Auth0 PHP App</title>
+    <link rel="stylesheet" href="/style.css">
+</head>
+<body>
+    <div class="container">
+        <?php if ($credentials): ?>
+            <div class="card">
+                <div class="user-header">
+                    <img src="<?= htmlspecialchars($credentials->user['picture'] ?? '') ?>" alt="avatar" class="avatar" />
+                    <div>
+                        <h1>Hello, <?= htmlspecialchars($credentials->user['name'] ?? 'User') ?>!</h1>
+                        <p class="subtitle"><?= htmlspecialchars($credentials->user['email'] ?? '') ?></p>
+                    </div>
+                </div>
+                <nav class="nav-links">
+                    <a href="/profile" class="btn btn-primary">View Profile & Tokens</a>
+                    <a href="/logout" class="btn btn-secondary">Logout</a>
+                </nav>
+            </div>
+        <?php else: ?>
+            <div class="card center">
+                <h1>Auth0 PHP Web App</h1>
+                <p class="subtitle">Session-based authentication with Auth0 SDK</p>
+                <a href="/login" class="btn btn-primary">Login</a>
+            </div>
+        <?php endif; ?>
+    </div>
+</body>
+</html>
+```
+
+### 8. Add Login Route
+
+Create `routes/login.php`:
+
+```php
+<?php
+
+header('Location: ' . $auth0->login());
+exit;
+```
+
+`login()` returns a URL string pointing to Auth0's Universal Login page. You must redirect the user to it.
+
+### 9. Add Callback Route
+
+Create `routes/callback.php`:
+
+```php
+<?php
+
+if (null !== $auth0->getExchangeParameters()) {
+    try {
+        $auth0->exchange();
+        header('Location: /');
+        exit;
+    } catch (\Exception $e) {
+        error_log('Auth0 callback error: ' . $e->getMessage());
+        http_response_code(400);
+        echo "Authentication failed. Please try again.";
+        exit;
+    }
+}
+
+header('Location: /');
+exit;
+```
+
+`getExchangeParameters()` checks if the callback contains authorization code parameters. `exchange()` exchanges the code for tokens and establishes the session. Always wrap in try/catch since the token exchange can fail (e.g. expired code, CSRF mismatch).
+
+### 10. Add Profile Route (Protected)
+
+Create `routes/profile.php`:
+
+```php
+<?php
+
+$credentials = $auth0->getCredentials();
+
+if (null === $credentials) {
+    header('Location: /login');
+    exit;
+}
+
+$user = $credentials->user;
+?>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Profile - Auth0 PHP App</title>
+    <link rel="stylesheet" href="/style.css">
+</head>
+<body>
+    <div class="container">
+        <nav class="top-nav">
+            <a href="/" class="btn btn-back">&larr; Back to Home</a>
+            <a href="/logout" class="btn btn-secondary">Logout</a>
+        </nav>
+
+        <div class="card">
+            <div class="user-header">
+                <img src="<?= htmlspecialchars($user['picture'] ?? '') ?>" alt="avatar" class="avatar avatar-lg" />
+                <div>
+                    <h1><?= htmlspecialchars($user['name'] ?? 'User') ?></h1>
+                    <p class="subtitle"><?= htmlspecialchars($user['email'] ?? '') ?></p>
+                </div>
+            </div>
+        </div>
+
+        <div class="card">
+            <h2>User Profile Claims</h2>
+            <table class="info-table">
+                <?php foreach ($user as $key => $value): ?>
+                <tr>
+                    <td class="label"><?= htmlspecialchars($key) ?></td>
+                    <td class="value"><?= htmlspecialchars(is_array($value) ? json_encode($value) : (string)$value) ?></td>
+                </tr>
+                <?php endforeach; ?>
+            </table>
+        </div>
+
+        <div class="card">
+            <h2>ID Token</h2>
+            <pre class="token-box"><?= htmlspecialchars($credentials->idToken ?? 'N/A') ?></pre>
+        </div>
+
+        <div class="card">
+            <h2>Access Token</h2>
+            <pre class="token-box"><?= htmlspecialchars($credentials->accessToken ?? 'N/A') ?></pre>
+            <table class="info-table">
+                <tr>
+                    <td class="label">Expires</td>
+                    <td class="value"><?= $credentials->accessTokenExpiration ? date('Y-m-d H:i:s', $credentials->accessTokenExpiration) . ' (' . ($credentials->accessTokenExpired ? 'EXPIRED' : 'valid') . ')' : 'N/A' ?></td>
+                </tr>
+                <tr>
+                    <td class="label">Scopes</td>
+                    <td class="value"><?= htmlspecialchars(implode(', ', $credentials->accessTokenScope ?? [])) ?></td>
+                </tr>
+            </table>
+        </div>
+
+        <?php if ($credentials->refreshToken): ?>
+        <div class="card">
+            <h2>Refresh Token</h2>
+            <pre class="token-box"><?= htmlspecialchars($credentials->refreshToken) ?></pre>
+        </div>
+        <?php endif; ?>
+    </div>
+</body>
+</html>
+```
+
+`getCredentials()` returns the user's session data, or `null` if not logged in. The profile page displays all user claims and tokens for verification during development.
+
+### 11. Add Logout Route
+
+Create `routes/logout.php`:
+
+```php
+<?php
+
+header('Location: ' . $auth0->logout(returnUri: 'http://localhost:3000'));
+exit;
+```
+
+`logout()` returns the Auth0 logout URL. Redirect the user to it. The `returnUri` is where Auth0 sends the user after logout - it must be listed in Allowed Logout URLs. In production, replace with your actual domain.
+
+### 12. Test the App
+
+```bash
+php -S localhost:3000 index.php
+```
+
+Visit `http://localhost:3000/login` to start the login flow.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Hardcoding `domain`, `clientId`, or `clientSecret` in source | Always read from environment variables - never embed credentials in code |
+| Using an old `auth0-PHP` version < 8.0 | Require PHP 8.2+ and v8.x of the SDK; older versions have different APIs |
+| Installing without a PSR-18 HTTP client | Must have a PSR-18 client (e.g. `guzzlehttp/guzzle`) or the SDK cannot make HTTP requests |
+| Using `STRATEGY_API` for a web app | Web apps must use `SdkConfiguration::STRATEGY_REGULAR` for session-based auth |
+| Passing `domain` as full URL with `https://` | `domain` should be the bare domain, e.g. `my-tenant.us.auth0.com`, not `https://my-tenant.us.auth0.com` |
+| Forgetting `cookieSecret` | Required for session encryption - without it, the SDK throws a ConfigurationException |
+| Not checking `getExchangeParameters()` before `exchange()` | Calling `exchange()` without parameters causes errors; always check first |
+| Not handling errors in callback | `exchange()` can fail - always wrap in try/catch |
+| Created app as SPA type in Auth0 | Must be Regular Web Application type for server-side auth |
+| Not configuring callback URL in Auth0 Dashboard | Must add `http://localhost:3000/callback` to Allowed Callback URLs |
+| Using `$_SESSION` directly | The SDK manages its own encrypted cookie session - do not use `$_SESSION` unless you configure a custom `SessionStore` |
+| Deploying without `cookieSecure: true` | Must set to `true` in production - cookies are sent over HTTP otherwise |
+| Calling `login()` or `logout()` without redirecting | Both return URL strings, not responses - must use `header('Location: ...')` |
+| "Network error resulted in unfulfilled request" on callback | Usually means `AUTH0_CLIENT_SECRET` is wrong, not an actual network issue - verify your credentials in `.env` |
+
+## Key SDK Methods
+
+| Method | Signature | Purpose |
+|--------|-----------|---------|
+| `login` | `$auth0->login(?string $redirectUrl, ?array $params): string` | Returns authorization URL string - redirect user to it |
+| `exchange` | `$auth0->exchange(?string $redirectUri, ?string $code, ?string $state): bool` | Exchanges authorization code for tokens, establishes session |
+| `getCredentials` | `$auth0->getCredentials(): ?object` | Returns current session credentials or `null` |
+| `getExchangeParameters` | `$auth0->getExchangeParameters(): ?object` | Checks if callback contains exchange parameters |
+| `logout` | `$auth0->logout(?string $returnUri, ?array $params): string` | Returns Auth0 logout URL string |
+| `renew` | `$auth0->renew(?array $params): self` | Refreshes expired access token (requires `offline_access` scope) |
+| `clear` | `$auth0->clear(bool $transient = true): self` | Clears local session without Auth0 logout |
+
+## Credentials Object
+
+After successful authentication, `getCredentials()` returns an object with:
+
+```php
+$credentials = $auth0->getCredentials();
+
+$credentials->user;                    // array - user profile claims
+$credentials->idToken;                 // string - raw ID token
+$credentials->accessToken;             // string - access token
+$credentials->refreshToken;            // string|null - refresh token (requires offline_access)
+$credentials->accessTokenExpiration;   // int - expiration timestamp
+$credentials->accessTokenExpired;      // bool - whether token is expired
+$credentials->accessTokenScope;        // array - granted scopes
+```
+
+**User profile claims** (`$credentials->user`):
+- `sub` - unique user identifier
+- `name`, `nickname`, `picture`
+- `email`, `email_verified`
+- `given_name`, `family_name`
+- `updated_at`, `locale`
+
+## Related Capabilities
+
+- Protecting PHP APIs with JWT Bearer token validation → ask for the Auth0 PHP API integration workflow
+- Auth0 setup and framework detection → set up Auth0 with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Managing Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+
+## Quick Reference
+
+**SdkConfiguration for web apps:**
+```php
+$configuration = new SdkConfiguration(
+    strategy: SdkConfiguration::STRATEGY_REGULAR,        // required
+    domain: $_ENV['AUTH0_DOMAIN'],                        // required
+    clientId: $_ENV['AUTH0_CLIENT_ID'],                   // required
+    clientSecret: $_ENV['AUTH0_CLIENT_SECRET'],           // required
+    cookieSecret: $_ENV['AUTH0_COOKIE_SECRET'],           // required
+    redirectUri: $_ENV['AUTH0_REDIRECT_URI'],             // required
+    scope: ['openid', 'profile', 'email'],               // recommended
+);
+```
+
+**Route protection pattern:**
+```php
+$credentials = $auth0->getCredentials();
+if (null === $credentials) {
+    header('Location: /login');
+    exit;
+}
+```
+
+**Environment variables:**
+- `AUTH0_DOMAIN` - your Auth0 tenant domain (e.g. `tenant.us.auth0.com`)
+- `AUTH0_CLIENT_ID` - your Application's client ID
+- `AUTH0_CLIENT_SECRET` - your Application's client secret
+- `AUTH0_COOKIE_SECRET` - encryption secret key (generate: `openssl rand -hex 32`)
+- `AUTH0_REDIRECT_URI` - callback URL (e.g. `http://localhost:3000/callback`)
+
+## References
+
+- [auth0/auth0-php on Packagist](https://packagist.org/packages/auth0/auth0-php)
+- [auth0/auth0-PHP on GitHub](https://github.com/auth0/auth0-PHP)
+- [Auth0 PHP Web App Quickstart](https://auth0.com/docs/quickstart/webapp/php)
+- [PHP Documentation](https://www.php.net/)
+
+---
+
+# Auth0 PHP API Reference
+
+Complete API reference for the `auth0/auth0-php` SDK in web application (stateful) mode.
+
+---
+
+## SdkConfiguration
+
+### Constructor Parameters
+
+```php
+use Auth0\SDK\Configuration\SdkConfiguration;
+
+$configuration = new SdkConfiguration(
+    // Strategy
+    strategy: SdkConfiguration::STRATEGY_REGULAR,  // 'webapp' - required for web apps
+
+    // Required
+    domain: 'tenant.us.auth0.com',
+    clientId: 'your_client_id',
+    clientSecret: 'your_client_secret',
+    cookieSecret: 'generated_32_byte_hex',
+    redirectUri: 'http://localhost:3000/callback',
+
+    // Scopes
+    scope: ['openid', 'profile', 'email'],
+
+    // Cookie settings
+    cookieExpires: 0,            // 0 = session cookie; seconds for persistent
+    cookieSecure: false,         // true in production (requires HTTPS)
+    cookieSameSite: 'lax',       // 'lax', 'strict', or 'none'
+    cookieDomain: null,          // auto-detected; set for cross-subdomain
+    cookiePath: '/',             // cookie path scope
+
+    // Session storage
+    sessionStorage: null,        // null = CookieStore (default)
+    transientStorage: null,      // null = CookieStore (default)
+    sessionStorageId: 'auth0_session',  // namespace prefix
+
+    // Token settings
+    tokenAlgorithm: 'RS256',     // 'RS256' (recommended) or 'HS256'
+    tokenMaxAge: null,           // max age in seconds
+    tokenLeeway: 60,             // clock skew tolerance in seconds
+    tokenCache: null,            // PSR-6 CacheItemPoolInterface
+
+    // Persistence
+    persistUser: true,
+    persistIdToken: true,
+    persistAccessToken: true,
+    persistRefreshToken: true,
+
+    // OIDC
+    usePkce: true,               // PKCE enabled by default
+    responseMode: 'query',       // 'query' or 'form_post'
+    responseType: 'code',        // authorization code flow
+
+    // Optional
+    audience: [],                // API identifiers
+    organization: [],            // organization IDs or names
+    queryUserInfo: false,        // query /userinfo endpoint
+);
+```
+
+### Strategy Constants
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `STRATEGY_REGULAR` | `'webapp'` | Stateful web app with sessions |
+| `STRATEGY_API` | `'api'` | Stateless API token validation |
+| `STRATEGY_MANAGEMENT_API` | `'management'` | Management API client |
+| `STRATEGY_NONE` | `'none'` | No default behavior |
+
+---
+
+## Auth0 Class
+
+### Constructor
+
+```php
+use Auth0\SDK\Auth0;
+
+$auth0 = new Auth0($configuration);
+```
+
+### Authentication Methods
+
+#### login()
+
+Initiates the login flow. Returns the authorization URL to redirect the user to.
+
+```php
+$url = $auth0->login(
+    ?string $redirectUrl = null,  // override redirectUri for this request
+    ?array $params = null         // additional authorization parameters
+); // returns string
+```
+
+**Parameters for `$params`:**
+- `prompt` - `'login'`, `'none'`, `'consent'`, `'select_account'`
+- `screen_hint` - `'signup'` to show registration form
+- `connection` - force a specific connection (e.g. `'google-oauth2'`)
+- `organization` - organization ID for B2B
+- `invitation` - invitation ticket for org invites
+- `login_hint` - pre-fill email on login form
+- `max_age` - max authentication age in seconds
+
+**Example:**
+```php
+header('Location: ' . $auth0->login(params: ['prompt' => 'login']));
+exit;
+```
+
+#### signup()
+
+Shortcut for login with `screen_hint=signup`:
+
+```php
+$url = $auth0->signup(
+    ?string $redirectUrl = null,
+    ?array $params = null
+); // returns string
+```
+
+#### exchange()
+
+Completes the authentication flow by exchanging the authorization code for tokens.
+
+```php
+$success = $auth0->exchange(
+    ?string $redirectUri = null,  // override redirectUri
+    ?string $code = null,         // authorization code (auto-detected from $_GET)
+    ?string $state = null         // state parameter (auto-detected from $_GET)
+); // returns bool
+```
+
+**Returns:** `true` on success.
+
+**Throws:**
+- `StateException` - invalid state, missing code, PKCE error
+- `NetworkException` - cannot reach Auth0
+
+#### getExchangeParameters()
+
+Checks whether the current request contains authorization code parameters (code + state).
+
+```php
+$params = $auth0->getExchangeParameters();
+```
+
+**Returns:** Object with `code` and `state` properties, or `null` if not a callback request.
+
+#### logout()
+
+Clears the local session and returns the Auth0 logout URL.
+
+```php
+$url = $auth0->logout(
+    ?string $returnUri = null,  // where Auth0 redirects after logout
+    ?array $params = null       // additional parameters
+); // returns string
+```
+
+**Example:**
+```php
+header('Location: ' . $auth0->logout(returnUri: 'http://localhost:3000'));
+exit;
+```
+
+#### clear()
+
+Clears the local session without redirecting to Auth0 (no federated logout).
+
+```php
+$auth0->clear(bool $transient = true); // returns self
+```
+
+#### renew()
+
+Refreshes the access token using the stored refresh token. Requires `offline_access` scope.
+
+```php
+$auth0->renew(?array $params = null); // returns self
+```
+
+**Throws:** Exception if no refresh token is available or refresh fails.
+
+---
+
+### Session Methods
+
+#### getCredentials()
+
+Returns the current session data, or `null` if not authenticated.
+
+```php
+$credentials = $auth0->getCredentials();
+```
+
+**Returns object with:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `user` | `array` | User profile claims from ID token |
+| `idToken` | `string` | Raw ID token JWT |
+| `accessToken` | `string` | Access token |
+| `refreshToken` | `string\|null` | Refresh token (if `offline_access` scope) |
+| `accessTokenExpiration` | `int` | Unix timestamp when access token expires |
+| `accessTokenExpired` | `bool` | Whether the access token has expired |
+| `accessTokenScope` | `array` | Array of granted scope strings |
+
+#### isAuthenticated()
+
+Convenience check for whether a session exists.
+
+```php
+$isAuth = $auth0->isAuthenticated(); // returns bool
+```
+
+#### getUser()
+
+Returns user profile array or null.
+
+```php
+$user = $auth0->getUser();
+```
+
+#### getAccessToken()
+
+Returns access token string or null.
+
+```php
+$token = $auth0->getAccessToken();
+```
+
+#### getIdToken()
+
+Returns ID token string or null.
+
+```php
+$token = $auth0->getIdToken();
+```
+
+#### getRefreshToken()
+
+Returns refresh token string or null.
+
+```php
+$token = $auth0->getRefreshToken();
+```
+
+---
+
+## User Profile Claims
+
+Standard OpenID Connect claims available in `$credentials->user`:
+
+| Claim | Type | Description |
+|-------|------|-------------|
+| `sub` | string | Unique user identifier (e.g. `auth0\|abc123`) |
+| `name` | string | Full name |
+| `nickname` | string | Casual name |
+| `picture` | string | Profile picture URL |
+| `email` | string | Email address |
+| `email_verified` | bool | Whether email is verified |
+| `given_name` | string | First name |
+| `family_name` | string | Last name |
+| `locale` | string | User locale |
+| `updated_at` | string | Last profile update (ISO 8601) |
+| `org_id` | string | Organization ID (if using organizations) |
+
+---
+
+## Session Storage
+
+### CookieStore (Default)
+
+Stores encrypted session data in HTTP cookies. No server-side state.
+
+- **Encryption:** AES-256-GCM
+- **Key derivation:** HKDF-SHA256 from `cookieSecret`
+- **Max size:** ~4KB (browser cookie limit)
+- **Tradeoff:** Stateless but limited by cookie size
+
+### SessionStore
+
+Uses PHP's native `$_SESSION` for server-side storage.
+
+```php
+use Auth0\SDK\Store\SessionStore;
+
+$configuration = new SdkConfiguration(
+    // ... required params
+    sessionStorage: new SessionStore(),
+    transientStorage: new SessionStore(),
+);
+```
+
+**Requirements:**
+- `session_start()` must be called before Auth0 initialization
+- Shared session backend (Redis, Memcache) for load-balanced environments
+
+### Custom Store
+
+Implement `Auth0\SDK\Contract\StoreInterface`:
+
+```php
+use Auth0\SDK\Contract\StoreInterface;
+
+class RedisStore implements StoreInterface
+{
+    public function set(string $key, mixed $value): void { /* ... */ }
+    public function get(string $key, mixed $default = null): mixed { /* ... */ }
+    public function delete(string $key): void { /* ... */ }
+    public function purge(): void { /* ... */ }
+    public function defer(int $seconds): void { /* ... */ }
+}
+```
+
+---
+
+## Exception Types
+
+| Exception | When Thrown |
+|-----------|------------|
+| `Auth0\SDK\Exception\ConfigurationException` | Missing required configuration parameters |
+| `Auth0\SDK\Exception\StateException` | Invalid state, missing code, PKCE errors during exchange |
+| `Auth0\SDK\Exception\NetworkException` | HTTP request to Auth0 failed |
+| `Auth0\SDK\Exception\InvalidTokenException` | Token signature or claims validation failed |
+| `Auth0\SDK\Exception\ArgumentException` | Invalid arguments passed to methods |
+
+---
+
+## PSR Compatibility
+
+The SDK uses PSR auto-discovery (`psr-discovery/all`):
+
+| PSR | Purpose | Common Implementation |
+|-----|---------|----------------------|
+| PSR-18 | HTTP Client | `guzzlehttp/guzzle` |
+| PSR-17 | HTTP Factories | `guzzlehttp/psr7` |
+| PSR-7 | HTTP Messages | `guzzlehttp/psr7` |
+| PSR-6 | Caching (optional) | `symfony/cache` |
+| PSR-14 | Events (optional) | `symfony/event-dispatcher` |
+
+---
+
+## Token Validation
+
+The SDK validates tokens automatically during `exchange()`. Claims checked:
+
+- `iss` (issuer) - must match `https://{domain}/`
+- `aud` (audience) - must match `clientId` (or configured audience)
+- `exp` (expiration) - must not be expired (with `tokenLeeway`)
+- `iat` (issued at) - must be reasonable
+- `nonce` - must match stored nonce (CSRF protection)
+- Signature - verified against JWKS endpoint (`https://{domain}/.well-known/jwks.json`)
+
+JWKS keys are cached using PSR-6 if a `tokenCache` is provided.
+
+---
+
+---
+
+# Auth0 PHP Integration Patterns
+
+Server-side authentication patterns for PHP web applications.
+
+---
+
+## Protected Routes
+
+### Single Route Protection
+
+```php
+<?php
+require 'auth0.php';
+
+$credentials = $auth0->getCredentials();
+if (null === $credentials) {
+    header('Location: /login');
+    exit;
+}
+
+// User is authenticated - proceed with route logic
+$user = $credentials->user;
+echo "Welcome, " . htmlspecialchars($user['name']);
+```
+
+### Reusable Auth Guard
+
+Create a helper function for route protection:
+
+```php
+<?php
+// helpers.php
+
+function requireAuth(Auth0\SDK\Auth0 $auth0): object
+{
+    $credentials = $auth0->getCredentials();
+    if (null === $credentials) {
+        header('Location: /login');
+        exit;
+    }
+    return $credentials;
+}
+```
+
+Use it in any route:
+
+```php
+<?php
+require 'auth0.php';
+require 'helpers.php';
+
+$credentials = requireAuth($auth0);
+$user = $credentials->user;
+```
+
+### Optional Authentication
+
+Check auth status without requiring it:
+
+```php
+<?php
+require 'auth0.php';
+
+$credentials = $auth0->getCredentials();
+
+if ($credentials) {
+    echo "Hello, " . htmlspecialchars($credentials->user['name']) . "! ";
+    echo "<a href='/logout'>Logout</a>";
+} else {
+    echo "Welcome, guest! <a href='/login'>Login</a>";
+}
+```
+
+---
+
+## Calling External APIs
+
+### Get Access Token for API Calls
+
+Configure an audience to receive an access token for your API:
+
+```php
+$configuration = new SdkConfiguration(
+    strategy: SdkConfiguration::STRATEGY_REGULAR,
+    domain: $_ENV['AUTH0_DOMAIN'],
+    clientId: $_ENV['AUTH0_CLIENT_ID'],
+    clientSecret: $_ENV['AUTH0_CLIENT_SECRET'],
+    cookieSecret: $_ENV['AUTH0_COOKIE_SECRET'],
+    redirectUri: $_ENV['AUTH0_REDIRECT_URI'],
+    audience: [$_ENV['AUTH0_AUDIENCE']],
+    scope: ['openid', 'profile', 'email', 'read:data'],
+);
+```
+
+Then use the access token:
+
+```php
+<?php
+$credentials = $auth0->getCredentials();
+if (null === $credentials) {
+    header('Location: /login');
+    exit;
+}
+
+$accessToken = $credentials->accessToken;
+
+$ch = curl_init('https://your-api.example.com/data');
+curl_setopt_array($ch, [
+    CURLOPT_HTTPHEADER => ["Authorization: Bearer $accessToken"],
+    CURLOPT_RETURNTRANSFER => true,
+]);
+$response = curl_exec($ch);
+$data = json_decode($response, true);
+curl_close($ch);
+```
+
+### Token Refresh
+
+If the access token is expired, refresh it (requires `offline_access` scope):
+
+```php
+$configuration = new SdkConfiguration(
+    // ... other config
+    scope: ['openid', 'profile', 'email', 'offline_access'],
+);
+
+// Later, when making API calls:
+$credentials = $auth0->getCredentials();
+
+if (null === $credentials) {
+    header('Location: /login');
+    exit;
+}
+
+if ($credentials->accessTokenExpired) {
+    try {
+        $auth0->renew();
+        $credentials = $auth0->getCredentials();
+    } catch (\Exception $e) {
+        // Refresh token expired or revoked - re-authenticate
+        header('Location: /login');
+        exit;
+    }
+}
+
+$accessToken = $credentials->accessToken;
+```
+
+---
+
+## Session Management
+
+### Session Lifecycle
+
+The SDK manages sessions automatically using encrypted cookies:
+
+1. **Login** - Creates encrypted session cookie after `exchange()`
+2. **Requests** - `getCredentials()` decrypts and returns session data
+3. **Refresh** - `renew()` refreshes tokens without re-authentication
+4. **Logout** - `logout()` clears session and redirects to Auth0
+
+### Clear Local Session
+
+Clear the local session without redirecting to Auth0 logout:
+
+```php
+$auth0->clear();
+header('Location: /');
+exit;
+```
+
+### Cookie Configuration for Production
+
+```php
+$configuration = new SdkConfiguration(
+    // ... required params
+    cookieSecure: true,        // HTTPS only (required for production)
+    cookieSameSite: 'lax',     // Prevent CSRF (default)
+    cookieDomain: '.myapp.com', // Share across subdomains
+    cookieExpires: 86400,      // 24 hours (0 = session cookie)
+    cookiePath: '/',           // Available on all paths
+);
+```
+
+### Server-Side Sessions (Alternative)
+
+For high-traffic apps or when cookie size is a concern, use PHP's native sessions:
+
+```php
+use Auth0\SDK\Store\SessionStore;
+
+$configuration = new SdkConfiguration(
+    // ... required params
+    sessionStorage: new SessionStore(),
+    transientStorage: new SessionStore(),
+);
+```
+
+**Note:** When using `SessionStore`, you must call `session_start()` before creating the `Auth0` instance. For load-balanced environments, configure a shared session backend (Redis, Memcached).
+
+---
+
+## Custom Login Parameters
+
+### Force Login Prompt
+
+```php
+header('Location: ' . $auth0->login(params: ['prompt' => 'login']));
+exit;
+```
+
+### Signup Instead of Login
+
+```php
+header('Location: ' . $auth0->login(params: ['screen_hint' => 'signup']));
+exit;
+```
+
+### Specify Connection
+
+```php
+header('Location: ' . $auth0->login(params: ['connection' => 'google-oauth2']));
+exit;
+```
+
+### Custom Return URL
+
+```php
+header('Location: ' . $auth0->login(redirectUrl: 'http://localhost:3000/dashboard'));
+exit;
+```
+
+---
+
+## Organization Support
+
+For B2B multi-tenant applications:
+
+```php
+$configuration = new SdkConfiguration(
+    // ... required params
+    organization: ['org_abc123'],
+);
+
+// Or prompt for organization at login:
+header('Location: ' . $auth0->login(params: ['organization' => 'org_abc123']));
+exit;
+```
+
+After login, check the organization claim:
+
+```php
+$credentials = $auth0->getCredentials();
+$orgId = $credentials->user['org_id'] ?? null;
+```
+
+---
+
+## Error Handling
+
+### Callback Errors
+
+```php
+<?php
+// routes/callback.php
+
+if (null !== $auth0->getExchangeParameters()) {
+    try {
+        $auth0->exchange();
+        header('Location: /');
+        exit;
+    } catch (\Auth0\SDK\Exception\StateException $e) {
+        // Invalid state, PKCE error, or expired authorization code
+        http_response_code(400);
+        echo "Login failed: invalid state. Please try again.";
+        echo " <a href='/login'>Retry Login</a>";
+        exit;
+    } catch (\Auth0\SDK\Exception\NetworkException $e) {
+        // Network error calling Auth0
+        http_response_code(502);
+        echo "Unable to reach authentication server. Please try again.";
+        exit;
+    } catch (\Exception $e) {
+        error_log('Auth0 callback error: ' . $e->getMessage());
+        http_response_code(400);
+        echo "Authentication failed. Please try again.";
+        exit;
+    }
+}
+```
+
+### Token Expiration
+
+```php
+$credentials = $auth0->getCredentials();
+if ($credentials && $credentials->accessTokenExpired) {
+    try {
+        $auth0->renew();
+    } catch (\Exception $e) {
+        $auth0->clear();
+        header('Location: /login');
+        exit;
+    }
+}
+```
+
+---
+
+## Using with PHP Frameworks (Non-Laravel/Symfony)
+
+### Slim Framework
+
+```php
+<?php
+use Slim\Factory\AppFactory;
+
+require 'vendor/autoload.php';
+require 'auth0.php';
+
+$app = AppFactory::create();
+
+$app->get('/', function ($request, $response) use ($auth0) {
+    $credentials = $auth0->getCredentials();
+    $body = $credentials
+        ? "Hello, " . htmlspecialchars($credentials->user['name'])
+        : "<a href='/login'>Login</a>";
+    $response->getBody()->write($body);
+    return $response;
+});
+
+$app->get('/login', function ($request, $response) use ($auth0) {
+    return $response->withHeader('Location', $auth0->login())->withStatus(302);
+});
+
+$app->get('/callback', function ($request, $response) use ($auth0) {
+    if (null !== $auth0->getExchangeParameters()) {
+        $auth0->exchange();
+    }
+    return $response->withHeader('Location', '/')->withStatus(302);
+});
+
+$app->get('/logout', function ($request, $response) use ($auth0) {
+    return $response->withHeader('Location', $auth0->logout(returnUri: 'http://localhost:3000'))->withStatus(302);
+});
+
+$app->run();
+```
+
+---
+
+## Security Considerations
+
+- **Keep secrets secure** - Never commit `.env` to version control
+- **Use HTTPS in production** - Set `cookieSecure: true`
+- **Rotate cookie secret** - Update `AUTH0_COOKIE_SECRET` periodically
+- **PKCE is enabled by default** - Do not disable it
+- **Validate on server** - Authentication is server-side, tokens are encrypted in cookies
+- **Set appropriate cookie expiration** - Use `cookieExpires` for session timeout
+- **Always use `htmlspecialchars()`** when outputting user data to prevent XSS
+
+---
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "No PSR-18 client discovered" | Install `guzzlehttp/guzzle` |
+| "Invalid state" on callback | Regenerate `AUTH0_COOKIE_SECRET`; ensure cookies are not blocked |
+| Session not persisting across requests | Check that `cookieDomain` and `cookiePath` are correct |
+| "Configuration error: cookieSecret required" | Ensure `.env` is loaded before `SdkConfiguration` is created |
+| Cookie too large | Switch to `SessionStore` for server-side sessions |
+| Token expired errors | Add `offline_access` scope and call `renew()` |
+
+---
+
+---
+
+# Auth0 PHP Setup Guide
+
+Setup instructions for PHP web applications.
+
+---
+
+## Quick Setup (Automated)
+
+Below automates the setup, except for the CLIENT_SECRET. Inform the user that they have to fill in the value for the CLIENT_SECRET themselves.
+
+**Never read the contents of `.env.local` or `.env` at any point during setup.** The file may contain sensitive secrets that should not be exposed in the LLM context. If you determine you need to read the file for any reason, ask the user for explicit permission before doing so - do not proceed until the user confirms.
+
+**Before running any part of this setup that writes to an env file, you MUST ask the user for explicit confirmation.** Follow the steps below precisely.
+
+### Step 1: Check for existing env files and confirm with user
+
+Before writing credentials, check which env files exist:
+
+```bash
+test -f .env.local && echo "ENV_LOCAL_EXISTS" || echo "ENV_LOCAL_NOT_FOUND"
+test -f .env && echo "ENV_EXISTS" || echo "ENV_NOT_FOUND"
+```
+
+Then determine the target file using this precedence: `.env.local` (if present), otherwise `.env`. Ask the user for explicit confirmation before proceeding - do not continue until the user confirms:
+
+- If the target file (`.env.local` or `.env`) exists, ask:
+  - Question: "A `<target file>` already exists and may contain secrets unrelated to Auth0. This setup will append Auth0 credentials without modifying existing content. Do you want to proceed?"
+  - Options: "Yes, append to existing `<target file>`" / "No, I'll update it manually"
+
+- If neither file exists, ask:
+  - Question: "This setup will create a `.env` file containing Auth0 credentials (AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_COOKIE_SECRET, AUTH0_REDIRECT_URI) and a placeholder for AUTH0_CLIENT_SECRET. Do you want to proceed?"
+  - Options: "Yes, create .env" / "No, I'll configure it manually"
+
+**Do not proceed with writing to any env file unless the user selects the confirmation option.**
+
+### Step 2: Run automated setup (only after confirmation)
+
+```bash
+#!/bin/bash
+
+# Install Auth0 CLI
+if ! command -v auth0 &> /dev/null; then
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    brew install auth0/auth0-cli/auth0
+  else
+    curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh -o /tmp/auth0-install.sh
+    echo "Review the install script at /tmp/auth0-install.sh before running"
+    sh /tmp/auth0-install.sh -b /usr/local/bin
+    rm /tmp/auth0-install.sh
+  fi
+fi
+
+# Verify jq is available (used to parse JSON from Auth0 CLI)
+if ! command -v jq &> /dev/null; then
+  echo "jq is required but not installed. Install it: https://jqlang.github.io/jq/download/" >&2
+  exit 1
+fi
+
+# Login
+auth0 login 2>/dev/null || auth0 login
+
+# Create/select app
+auth0 apps list
+read -p "Enter app ID (or Enter to create): " APP_ID
+
+if [ -z "$APP_ID" ]; then
+  APP_ID=$(auth0 apps create --name "${PWD##*/}-php" --type regular \
+    --callbacks "http://localhost:3000/callback" \
+    --logout-urls "http://localhost:3000" \
+    --metadata "created_by=agent_skills" \
+    --json | jq -r '.client_id')
+fi
+
+# Get credentials
+APP_JSON=$(auth0 apps show "$APP_ID" --json)
+DOMAIN=$(printf '%s' "$APP_JSON" | jq -r '.domain')
+CLIENT_ID=$(printf '%s' "$APP_JSON" | jq -r '.client_id')
+if [ -z "$DOMAIN" ] || [ "$DOMAIN" = "null" ] || [ -z "$CLIENT_ID" ] || [ "$CLIENT_ID" = "null" ]; then
+  echo "Failed to resolve Auth0 app credentials from CLI output" >&2
+  exit 1
+fi
+COOKIE_SECRET=$(openssl rand -hex 32)
+
+# Determine target env file
+if [ -f .env.local ]; then
+  TARGET_FILE=".env.local"
+elif [ -f .env ]; then
+  TARGET_FILE=".env"
+else
+  TARGET_FILE=".env"
+fi
+
+# Append Auth0 credentials
+cat >> "$TARGET_FILE" << ENVEOF
+
+# Auth0 Configuration
+AUTH0_DOMAIN=$DOMAIN
+AUTH0_CLIENT_ID=$CLIENT_ID
+AUTH0_CLIENT_SECRET='YOUR_CLIENT_SECRET'
+AUTH0_COOKIE_SECRET=$COOKIE_SECRET
+AUTH0_REDIRECT_URI=http://localhost:3000/callback
+ENVEOF
+
+echo "Auth0 credentials written to $TARGET_FILE"
+```
+
+After the script runs, remind the user to:
+1. Open the env file that was written and replace `YOUR_CLIENT_SECRET` with the actual client secret from Auth0.
+2. Ensure the env file is listed in `.gitignore` to avoid accidentally committing secrets.
+
+---
+
+## Manual Setup
+
+### Install Packages
+
+```bash
+composer require auth0/auth0-php vlucas/phpdotenv guzzlehttp/guzzle guzzlehttp/psr7
+```
+
+**Package breakdown:**
+- `auth0/auth0-php` - The Auth0 SDK
+- `vlucas/phpdotenv` - Load `.env` files
+- `guzzlehttp/guzzle` - PSR-18 HTTP client (required by the SDK)
+- `guzzlehttp/psr7` - PSR-7 HTTP messages (required by the SDK)
+
+### Create .env
+
+```bash
+AUTH0_DOMAIN=your-tenant.us.auth0.com
+AUTH0_CLIENT_ID=your_client_id
+AUTH0_CLIENT_SECRET=your_client_secret
+AUTH0_COOKIE_SECRET=<openssl-rand-hex-32>
+AUTH0_REDIRECT_URI=http://localhost:3000/callback
+```
+
+### Get Auth0 Credentials
+
+CLI: `auth0 apps show <app-id> --reveal-secrets`
+
+Dashboard: Applications > Your App > Settings, copy Domain, Client ID, Client Secret
+
+---
+
+## PHP Version Requirements
+
+- PHP 8.2 or higher
+- Required extensions: `mbstring`, `openssl`, `json`
+- Verify with: `php -v && php -m | grep -E "mbstring|openssl|json"`
+
+---
+
+## PSR Dependencies
+
+The SDK uses PSR auto-discovery (`psr-discovery/all`) to find compatible HTTP implementations. If you install `guzzlehttp/guzzle`, it satisfies all PSR requirements automatically.
+
+If you prefer a different HTTP client:
+- **Symfony HTTP Client**: `composer require symfony/http-client nyholm/psr7`
+- **PHP-HTTP Curl**: `composer require php-http/curl-client nyholm/psr7`
+
+---
+
+## Troubleshooting
+
+**"No PSR-18 HTTP Client found":** Install `guzzlehttp/guzzle` or another PSR-18 compatible client.
+
+**"Invalid state" error:** Regenerate `AUTH0_COOKIE_SECRET` with `openssl rand -hex 32`
+
+**"Client secret required":** Ensure you created a Regular Web Application (not SPA) in Auth0.
+
+**Callback URL mismatch:** Add `http://localhost:3000/callback` to Allowed Callback URLs in Auth0 Dashboard.
+
+**Cookie not persisting:** Ensure `cookieSecure` is `false` for local development (HTTP). Set to `true` only in production with HTTPS.
+
+---
diff --git a/main/.mintlify/skills/auth0/references/framework-react-native/index.md b/main/.mintlify/skills/auth0/references/framework-react-native/index.md
new file mode 100644
index 0000000000..dfaeba5de7
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-react-native/index.md
@@ -0,0 +1,627 @@
+
+# Auth0 React Native Integration
+
+Add authentication to React Native and Expo mobile applications using react-native-auth0.
+
+## Prerequisites
+
+- React Native or Expo application
+- Auth0 account and application configured as Native type
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **Expo managed workflow** - Use the Auth0 integration workflow for Expo (config plugin)
+- **React web applications** - Use the Auth0 integration workflow for React SPAs (Vite/CRA)
+- **React Server Components** - Use the Auth0 integration workflow for Next.js applications
+- **Non-React native apps** - Use platform-specific SDKs (Swift for iOS, Kotlin for Android)
+- **Backend APIs** - Use JWT validation libraries for your server language
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+**Expo:**
+```bash
+npx expo install react-native-auth0
+```
+
+**React Native CLI:**
+```bash
+npm install react-native-auth0
+npx pod-install  # iOS only
+```
+
+### 2. Configure Environment
+
+**For automated setup with Auth0 CLI**, see the Setup Guide section below for complete scripts.
+
+**For manual setup:**
+
+Create `.env`:
+
+```bash
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_CLIENT_ID=your-client-id
+```
+
+### 3. Configure Native Platforms
+
+**iOS** - Update `ios/{YourApp}/Info.plist`:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleTypeRole</key>
+    <string>None</string>
+    <key>CFBundleURLName</key>
+    <string>auth0</string>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>$(PRODUCT_BUNDLE_IDENTIFIER).auth0</string>
+    </array>
+  </dict>
+</array>
+```
+
+**Android** - Update `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<activity
+    android:name="com.auth0.android.provider.RedirectActivity"
+    android:exported="true">
+    <intent-filter>
+        <action android:name="android.intent.action.VIEW" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <category android:name="android.intent.category.BROWSABLE" />
+        <data
+            android:host="YOUR_AUTH0_DOMAIN"
+            android:pathPrefix="/android/${applicationId}/callback"
+            android:scheme="${applicationId}" />
+    </intent-filter>
+</activity>
+```
+
+**Expo** - Update `app.json`:
+
+```json
+{
+  "expo": {
+    "scheme": "your-app-scheme",
+    "ios": {
+      "bundleIdentifier": "com.yourcompany.yourapp"
+    },
+    "android": {
+      "package": "com.yourcompany.yourapp"
+    }
+  }
+}
+```
+
+### 4. Add Authentication with Auth0Provider
+
+Wrap your app with `Auth0Provider`:
+
+```typescript
+import React from 'react';
+import { Auth0Provider } from 'react-native-auth0';
+import App from './App';
+
+export default function Root() {
+  return (
+    <Auth0Provider
+      domain={process.env.AUTH0_DOMAIN}
+      clientId={process.env.AUTH0_CLIENT_ID}
+    >
+      <App />
+    </Auth0Provider>
+  );
+}
+```
+
+### 5. Use the useAuth0 Hook
+
+```typescript
+import React from 'react';
+import { View, Button, Text, ActivityIndicator } from 'react-native';
+import { useAuth0 } from 'react-native-auth0';
+
+export default function App() {
+  const { user, authorize, clearSession, isLoading } = useAuth0();
+
+  const login = async () => {
+    try {
+      await authorize({
+        scope: 'openid profile email'
+      });
+    } catch (error) {
+      console.error('Login error:', error);
+    }
+  };
+
+  const logout = async () => {
+    try {
+      await clearSession();
+    } catch (error) {
+      console.error('Logout error:', error);
+    }
+  };
+
+  if (isLoading) {
+    return <ActivityIndicator />;
+  }
+
+  return (
+    <View>
+      {user ? (
+        <>
+          <Text>Welcome, {user.name}!</Text>
+          <Text>{user.email}</Text>
+          <Button title="Logout" onPress={logout} />
+        </>
+      ) : (
+        <Button title="Login" onPress={login} />
+      )}
+    </View>
+  );
+}
+```
+
+### 6. Test Authentication
+
+**Expo:**
+```bash
+npx expo start
+```
+
+**React Native:**
+```bash
+npx react-native run-ios
+# or
+npx react-native run-android
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Forgot to wrap app with Auth0Provider | All components using useAuth0() must be children of Auth0Provider |
+| Forgot to configure deep linking | Add URL scheme to iOS Info.plist and Android AndroidManifest.xml (see Step 3) |
+| Callback URL mismatch | Ensure callback URL in Auth0 Dashboard matches your app's URL scheme (e.g., `com.yourapp.auth0://YOUR_DOMAIN/ios/com.yourapp/callback`) |
+| iOS build fails after install | Run `npx pod-install` to link native dependencies |
+| App created as SPA type in Auth0 | Must be Native application type for mobile apps |
+| Not handling auth errors | Wrap authorize/clearSession calls in try-catch blocks |
+| Deep link not working on Android | Verify `android:exported="true"` is set on RedirectActivity |
+
+## Related Capabilities
+
+- Auth0 setup — run the CLI: `auth0 login`, then `auth0 apps create`
+- Migrate from another auth provider → ask for migration (migrate)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- Manage Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+
+## Quick Reference
+
+**Core Hook API:**
+- `useAuth0()` - Main hook for authentication
+- `authorize()` - Initiate login
+- `clearSession()` - Logout
+- `user` - User profile object
+- `getCredentials()` - Get tokens for API calls
+- `isLoading` - Loading state
+
+**Common Use Cases:**
+- Login/Logout → See Step 5 above
+- Secure token storage → Automatic with `Auth0Provider`
+- Biometric authentication → see the Biometric Auth section below
+- API calls with tokens → see the Calling APIs section below
+- Token refresh → Automatic with `getCredentials()`
+
+## References
+
+- [Auth0 React Native SDK Documentation](https://auth0.com/docs/libraries/react-native-auth0)
+- [Auth0 React Native Quickstart](https://auth0.com/docs/quickstart/native/react-native)
+- [SDK GitHub Repository](https://github.com/auth0/react-native-auth0)
+
+---
+
+## Testing
+
+### iOS Testing
+
+1. Run the app: `npx react-native run-ios` or `npx expo run:ios`
+2. Tap "Login" button
+3. Safari opens with Auth0 Universal Login
+4. Complete authentication
+5. App opens via deep link with user authenticated
+6. Tap "Logout" and verify session cleared
+
+### Android Testing
+
+1. Run the app: `npx react-native run-android` or `npx expo run:android`
+2. Tap "Login" button
+3. Chrome Custom Tabs opens with Auth0 login
+4. Complete authentication
+5. App resumes via intent filter with user authenticated
+6. Tap "Logout" and verify session cleared
+
+---
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Deep link not working (iOS) | Check `CFBundleURLSchemes` matches bundle identifier exactly |
+| Deep link not working (Android) | Verify `android:scheme` and `android:host` in AndroidManifest.xml |
+| "Invalid state" error | Clear app data and reinstall. Check callback URLs match configuration |
+| Login opens but doesn't return to app | Ensure deep linking is properly configured and tested |
+| Expo build fails | Run `npx expo prebuild` to generate native configuration |
+| iOS builds fail after pod install | Run `cd ios && pod deintegrate && pod install` |
+
+---
+
+## Security Considerations
+
+- **Use secure storage** - Credentials are stored securely using Keychain (iOS) and Keystore (Android)
+- **HTTPS only** - Auth0 requires HTTPS callback URLs (except localhost for dev)
+- **Validate tokens on backend** - Never trust client-side token validation
+- **Use PKCE** - Enabled by default with react-native-auth0
+- **Implement biometric authentication** - Use react-native-biometrics with Auth0 for enhanced security
+- **Handle token expiration** - Implement refresh token logic with `getCredentials()`
+
+---
+
+## Related Capabilities
+
+- Auth0 setup — run the CLI: `auth0 login`, then `auth0 apps create`
+- Migrate from another auth provider → ask for migration (migrate)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- Passkey authentication → ask for MFA/passkeys (feature:mfa)
+- B2B multi-tenancy support → ask for Organizations (feature:organizations)
+
+---
+
+## References
+
+- [React Native Auth0 SDK Documentation](https://auth0.com/docs/libraries/auth0-react-native)
+- [React Native Auth0 SDK GitHub](https://github.com/auth0/react-native-auth0)
+- [Auth0 React Native Quickstart](https://auth0.com/docs/quickstart/native/react-native)
+- [React Native Deep Linking](https://reactnative.dev/docs/linking)
+- [Expo Deep Linking](https://docs.expo.dev/guides/deep-linking/)
+
+---
+
+## Common Patterns
+
+### Protected Screen with Navigation
+
+```tsx
+import { useAuth0 } from 'react-native-auth0';
+import { useEffect } from 'react';
+import { NavigationProp } from '@react-navigation/native';
+
+export function ProtectedScreen({ navigation }: { navigation: NavigationProp<any> }) {
+  const { user, isLoading } = useAuth0();
+
+  useEffect(() => {
+    if (!isLoading && !user) {
+      navigation.navigate('Login');
+    }
+  }, [isLoading, user, navigation]);
+
+  if (isLoading) {
+    return <ActivityIndicator />;
+  }
+
+  if (!user) {
+    return null;
+  }
+
+  return (
+    <View>
+      <Text>Protected Content</Text>
+      <Text>User ID: {user.sub}</Text>
+    </View>
+  );
+}
+```
+
+---
+
+### Get User Profile
+
+```tsx
+import { useAuth0 } from 'react-native-auth0';
+import { View, Text, Image } from 'react-native';
+
+export function ProfileScreen() {
+  const { user } = useAuth0();
+
+  if (!user) {
+    return <Text>Please log in</Text>;
+  }
+
+  return (
+    <View>
+      {user.picture && (
+        <Image
+          source={{ uri: user.picture }}
+          style={{ width: 100, height: 100, borderRadius: 50 }}
+        />
+      )}
+      <Text>Name: {user.name}</Text>
+      <Text>Email: {user.email}</Text>
+      <Text>Email Verified: {user.email_verified ? 'Yes' : 'No'}</Text>
+      <Text>User ID: {user.sub}</Text>
+    </View>
+  );
+}
+```
+
+---
+
+### Call Protected API
+
+```tsx
+import { useAuth0 } from 'react-native-auth0';
+import { useState } from 'react';
+import { View, Button, Text } from 'react-native';
+
+export function ApiTestScreen() {
+  const { getCredentials } = useAuth0();
+  const [data, setData] = useState(null);
+  const [error, setError] = useState(null);
+
+  const callApi = async () => {
+    try {
+      const credentials = await getCredentials();
+
+      const response = await fetch('https://api.example.com/data', {
+        headers: {
+          Authorization: `Bearer ${credentials.accessToken}`
+        }
+      });
+
+      const json = await response.json();
+      setData(json);
+    } catch (err) {
+      setError(err.message);
+    }
+  };
+
+  return (
+    <View>
+      <Button title="Call API" onPress={callApi} />
+      {error && <Text>Error: {error}</Text>}
+      {data && <Text>{JSON.stringify(data, null, 2)}</Text>}
+    </View>
+  );
+}
+```
+
+**Note:** To call APIs, configure `audience` parameter:
+
+```tsx
+const login = async () => {
+  await authorize({
+    audience: 'https://your-api-identifier',
+    scope: 'openid profile email'
+  });
+};
+```
+
+---
+
+### Silent Authentication
+
+```tsx
+import { useAuth0 } from 'react-native-auth0';
+import { useEffect } from 'react';
+
+export function App() {
+  const { getCredentials, user } = useAuth0();
+
+  useEffect(() => {
+    // Attempt silent authentication on app start
+    const checkAuth = async () => {
+      try {
+        await getCredentials();
+      } catch (e) {
+        // User not logged in, do nothing
+      }
+    };
+
+    if (!user) {
+      checkAuth();
+    }
+  }, []);
+
+  // Rest of your app...
+}
+```
+
+---
+
+### Custom Login Options
+
+```tsx
+const login = async () => {
+  await authorize({
+    scope: 'openid profile email offline_access',
+    audience: 'https://your-api-identifier',
+    connection: 'google-oauth2', // Optional: force specific connection
+    prompt: 'login', // Force re-authentication
+  });
+};
+```
+
+---
+
+## Configuration Options
+
+### Complete Auth0Provider Configuration
+
+```tsx
+<Auth0Provider
+  domain="your-tenant.auth0.com"
+  clientId="your-client-id"
+>
+  <App />
+</Auth0Provider>
+```
+
+### Complete authorize() Options
+
+```tsx
+await authorize({
+  scope: 'openid profile email offline_access',
+  audience: 'https://your-api-identifier',
+  connection: 'Username-Password-Authentication', // Optional
+  prompt: 'login', // or 'consent'
+  screen_hint: 'signup', // Show signup instead of login
+  max_age: 300, // Force re-auth if session older than 5 minutes
+});
+```
+
+---
+
+---
+
+# Auth0 React Native Setup Guide
+
+Setup instructions for React Native and Expo mobile applications.
+
+---
+
+## Quick Setup
+
+### For Expo
+
+```bash
+# Install SDK
+npx expo install react-native-auth0
+
+# Configure app.json
+# Add scheme, bundleIdentifier, and package
+```
+
+### For React Native CLI
+
+```bash
+# Install SDK
+npm install react-native-auth0
+
+# iOS: Install pods
+cd ios && pod install && cd ..
+
+# Configure iOS Info.plist and Android AndroidManifest.xml
+```
+
+---
+
+## Manual Setup
+
+### 1. Install SDK
+
+**Expo:**
+```bash
+npx expo install react-native-auth0
+```
+
+**React Native CLI:**
+```bash
+npm install react-native-auth0
+npx pod-install  # iOS only
+```
+
+### 2. Create Auth0 Native Application
+
+Via CLI:
+```bash
+auth0 login
+auth0 apps create --name "My Mobile App" --type native \
+  --auth-method None \
+  --callbacks "com.yourcompany.yourapp.auth0://YOUR_DOMAIN/ios/com.yourcompany.yourapp/callback,com.yourcompany.yourapp.auth0://YOUR_DOMAIN/android/com.yourcompany.yourapp/callback" \
+  --logout-urls "com.yourcompany.yourapp.auth0://YOUR_DOMAIN/ios/com.yourcompany.yourapp/callback,com.yourcompany.yourapp.auth0://YOUR_DOMAIN/android/com.yourcompany.yourapp/callback" \
+  --metadata "created_by=agent_skills"
+```
+
+Via Dashboard:
+1. Create **Native** application type
+2. Configure callback URLs with your app scheme
+3. Copy domain and client ID
+
+### 3. Configure iOS
+
+Update `ios/{YourApp}/Info.plist`:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleTypeRole</key>
+    <string>None</string>
+    <key>CFBundleURLName</key>
+    <string>auth0</string>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>$(PRODUCT_BUNDLE_IDENTIFIER).auth0</string>
+    </array>
+  </dict>
+</array>
+```
+
+### 4. Configure Android
+
+Update `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<activity android:name="com.auth0.android.provider.RedirectActivity" android:exported="true">
+  <intent-filter>
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+    <data
+      android:host="YOUR_DOMAIN"
+      android:pathPrefix="/android/${applicationId}/callback"
+      android:scheme="${applicationId}" />
+  </intent-filter>
+</activity>
+```
+
+### 5. Configure Expo
+
+Update `app.json`:
+
+```json
+{
+  "expo": {
+    "scheme": "myappscheme",
+    "ios": {
+      "bundleIdentifier": "com.mycompany.myapp"
+    },
+    "android": {
+      "package": "com.mycompany.myapp"
+    }
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+**Callback not working:**
+- Verify scheme matches bundle ID/package name
+- Check Auth0 allowed callbacks include your scheme
+
+**Build errors on iOS:**
+- Run `pod install` in ios/ directory
+- Clean build folder in Xcode
+
+**Android redirect issues:**
+- Ensure RedirectActivity is exported
+- Check scheme matches package name
+
+---
diff --git a/main/.mintlify/skills/auth0/references/framework-react/index.md b/main/.mintlify/skills/auth0/references/framework-react/index.md
new file mode 100644
index 0000000000..ea24fb14ce
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-react/index.md
@@ -0,0 +1,1709 @@
+
+# Auth0 React Integration
+
+Add authentication to React single-page applications using @auth0/auth0-react.
+
+## Critical rules
+
+- Always ask the user for explicit confirmation before running any setup step that writes to `.env`; wait for their answer before proceeding.
+- Keep the contents of `.env` out of the agent context. If reading it seems necessary, ask the user for explicit permission first.
+
+## Prerequisites
+
+- React 16.11+ application (Vite or Create React App) - supports React 16, 17, 18, and 19
+- Auth0 account and application configured
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **Next.js applications** - Use the Auth0 integration workflow for Next.js (App Router and Pages Router)
+- **React Native mobile apps** - Use the Auth0 integration workflow for React Native (iOS/Android)
+- **Server-side rendered React** - Use framework-specific SDK (Next.js, Remix, etc.)
+- **Embedded login** - This SDK uses Auth0 Universal Login (redirect-based)
+- **Backend API authentication** - Use express-openid-connect or JWT validation instead
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+npm install @auth0/auth0-react
+```
+
+### 2. Configure Environment
+
+**For automated setup with Auth0 CLI**, see the Setup Guide section below for complete scripts.
+
+**For manual setup:**
+
+Create `.env` file:
+
+**Vite:**
+```bash
+VITE_AUTH0_DOMAIN=your-tenant.auth0.com
+VITE_AUTH0_CLIENT_ID=your-client-id
+```
+
+**Create React App:**
+```bash
+REACT_APP_AUTH0_DOMAIN=your-tenant.auth0.com
+REACT_APP_AUTH0_CLIENT_ID=your-client-id
+```
+
+### 3. Wrap App with Auth0Provider
+
+Update `src/main.tsx` (Vite) or `src/index.tsx` (CRA):
+
+```tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { Auth0Provider } from '@auth0/auth0-react';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <Auth0Provider
+      domain={import.meta.env.VITE_AUTH0_DOMAIN} // or process.env.REACT_APP_AUTH0_DOMAIN
+      clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
+      authorizationParams={{
+        redirect_uri: window.location.origin
+      }}
+    >
+      <App />
+    </Auth0Provider>
+  </React.StrictMode>
+);
+```
+
+### 4. Add Authentication UI
+
+```tsx
+import { useAuth0 } from '@auth0/auth0-react';
+
+export function LoginButton() {
+  const { loginWithRedirect, logout, isAuthenticated, user, isLoading } = useAuth0();
+
+  if (isLoading) return <div>Loading...</div>;
+
+  if (isAuthenticated) {
+    return (
+      <div>
+        <span>Welcome, {user?.name}</span>
+        <button onClick={() => logout({ logoutParams: { returnTo: window.location.origin } })}>
+          Logout
+        </button>
+      </div>
+    );
+  }
+
+  return <button onClick={() => loginWithRedirect()}>Login</button>;
+}
+```
+
+### 5. Test Authentication
+
+Start your dev server and test the login flow:
+
+```bash
+npm run dev  # Vite
+# or
+npm start    # CRA
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Forgot to add redirect URI in Auth0 Dashboard | Add your application URL (e.g., `http://localhost:3000`, `https://app.example.com`) to Allowed Callback URLs in Auth0 Dashboard |
+| Using wrong env var prefix | Vite uses `VITE_` prefix, Create React App uses `REACT_APP_` |
+| Not handling loading state | Always check `isLoading` before rendering auth-dependent UI |
+| Storing tokens in localStorage | Never manually store tokens - SDK handles secure storage automatically |
+| Missing Auth0Provider wrapper | Entire app must be wrapped in `<Auth0Provider>` |
+| Provider not at root level | Auth0Provider must wrap all components that use auth hooks |
+| Wrong import path for env vars | Vite uses `import.meta.env.VITE_*`, CRA uses `process.env.REACT_APP_*` |
+| Using `acr_values` redirect for in-app MFA | Use `useAuth0().mfa` API for in-app enrollment/challenge/verify flows |
+| Not catching `MfaRequiredError` | Wrap `getAccessTokenSilently` in try/catch and check `instanceof MfaRequiredError` |
+| Making direct HTTP calls to MFA endpoints | Use the `mfa` property from `useAuth0()` — it handles token management automatically |
+| Forgetting refresh tokens for step-up MFA | Set `useRefreshTokens={true}` on Auth0Provider when using `interactiveErrorHandler="popup"` |
+
+## Related Skills
+
+- Basic Auth0 setup → set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Migrate from another auth provider → ask for migration (migrate)
+- Add Multi-Factor Authentication → ask for MFA (feature:mfa)
+- Add passkey authentication → ask for passkeys (feature:mfa)
+- B2B multi-tenancy support → ask for Organizations (feature:organizations)
+- Manage Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+
+## Quick Reference
+
+**Core Hooks:**
+- `useAuth0()` - Main authentication hook
+- `isAuthenticated` - Check if user is logged in
+- `user` - User profile information
+- `loginWithRedirect()` - Initiate login
+- `logout()` - Log out user
+- `getAccessTokenSilently()` - Get access token for API calls
+- `mfa` - MFA API client for enrollment, challenge, and verification
+  - `mfa.getAuthenticators(mfaToken)` - List enrolled authenticators
+  - `mfa.getEnrollmentFactors(mfaToken)` - Get available enrollment factors
+  - `mfa.enroll(params)` - Enroll new authenticator (OTP, SMS, Email, Voice, Push)
+  - `mfa.challenge(params)` - Initiate MFA challenge
+  - `mfa.verify(params)` - Verify MFA challenge and complete authentication
+
+**MFA Error Types (import from `@auth0/auth0-react`):**
+- `MfaRequiredError` - Thrown by `getAccessTokenSilently` when MFA is needed (has `mfa_token` and `mfa_requirements`)
+- `MfaEnrollmentError`, `MfaChallengeError`, `MfaVerifyError` - Thrown by respective `mfa.*` methods
+
+**Common Use Cases:**
+- Login/Logout buttons → See Step 4 above
+- Protected routes → see the Protected Routes section below
+- API calls with tokens → see the Calling APIs section below
+- Error handling → see the Error Handling section below
+- MFA handling → see the MFA Handling section below
+
+## References
+
+- [Auth0 React SDK Documentation](https://auth0.com/docs/libraries/auth0-react)
+- [Auth0 React SDK GitHub](https://github.com/auth0/auth0-react)
+- [Auth0 React Quickstart](https://auth0.com/docs/quickstart/spa/react)
+- [useAuth0 Hook API](https://auth0.github.io/auth0-react/interfaces/Auth0ContextInterface.html)
+- [Auth0 React API Reference](https://auth0.github.io/auth0-react/)
+- [Auth0 Universal Login](https://auth0.com/docs/universal-login)
+- [PKCE Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-proof-key-for-code-exchange-pkce)
+
+---
+
+# Auth0 React SDK API Reference
+
+Complete API documentation for @auth0/auth0-react SDK.
+
+---
+
+## Auth0Provider Configuration
+
+### Complete Configuration Options
+
+```tsx
+import { Auth0Provider } from '@auth0/auth0-react';
+
+<Auth0Provider
+  // Required
+  domain="your-tenant.auth0.com"
+  clientId="your-client-id"
+
+  // Authorization parameters
+  authorizationParams={{
+    redirect_uri: window.location.origin,
+    audience: 'https://your-api-identifier', // For API calls
+    scope: 'openid profile email', // Default scopes
+    connection: 'google-oauth2', // Force specific connection
+    prompt: 'login', // Force login prompt
+    ui_locales: 'en', // Localization
+    screen_hint: 'signup', // Show signup page by default
+  }}
+
+  // Token management
+  cacheLocation="localstorage" // or "memory" for stricter security (default: "memory")
+  useRefreshTokens={true} // Enable refresh tokens (default: false)
+  useRefreshTokensFallback={false} // Fall back to iframe if refresh token exchange fails (default: false)
+  useMrrt={false} // Enable Multi-Refresh-Token for multi-tenant apps (default: false)
+
+  // MFA / Step-up
+  interactiveErrorHandler="popup" // Automatically handle MFA via popup (requires useRefreshTokens)
+
+  // Advanced options
+  skipRedirectCallback={false} // Skip automatic callback handling
+  context={Auth0Context} // Custom React context
+
+  // Callbacks
+  onRedirectCallback={(appState) => {
+    // Handle redirect after login
+    // appState receives the custom state passed to loginWithRedirect()
+    // Example: if login was called with appState: { targetUrl: '/dashboard' }
+    // then appState.targetUrl will be '/dashboard' here
+    window.location.replace(appState?.returnTo || '/');
+  }}
+>
+  <App />
+</Auth0Provider>
+```
+
+### Configuration Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `domain` | string | **Required** | Your Auth0 tenant domain |
+| `clientId` | string | **Required** | Your Auth0 application client ID |
+| `authorizationParams` | object | `{}` | Authorization parameters (see below) |
+| `cacheLocation` | `'memory' \| 'localstorage'` | `'memory'` | Where to store tokens |
+| `useRefreshTokens` | boolean | `false` | Enable refresh token rotation |
+| `useRefreshTokensFallback` | boolean | `false` | Fall back to iframe if refresh token exchange fails |
+| `useMrrt` | boolean | `false` | Enable Multi-Refresh-Token support for multi-tenant apps. Requires `useRefreshTokens` and `useRefreshTokensFallback` to be `true` |
+| `workerUrl` | string | - | Custom worker script URL for token calls. Useful for CSP compliance when using `useRefreshTokens: true` with `cacheLocation: 'memory'` |
+| `context` | React.Context | - | Custom React context for nested Auth0Providers. Allows multiple Auth0Providers in same app |
+| `interactiveErrorHandler` | `'popup'` | - | Automatically handle MFA via popup when `getAccessTokenSilently` encounters `mfa_required`. Requires `useRefreshTokens={true}` |
+| `skipRedirectCallback` | boolean | `false` | Skip automatic callback handling |
+| `onRedirectCallback` | function | - | Callback after successful login |
+
+### Authorization Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `redirect_uri` | string | URL to redirect after authentication |
+| `audience` | string | API audience identifier |
+| `scope` | string | Requested scopes (space-separated) |
+| `connection` | string | Force specific connection |
+| `prompt` | string | `'none'`, `'login'`, `'consent'`, or `'select_account'` |
+| `ui_locales` | string | Language code (e.g., `'en'`, `'es'`) |
+| `screen_hint` | string | `'signup'` to show signup by default |
+| `max_age` | number | Maximum authentication age in seconds |
+| `organization` | string | Organization ID for B2B |
+| `invitation` | string | Invitation ID for organization invites |
+
+---
+
+## useAuth0 Hook
+
+### Hook Interface
+
+```typescript
+const {
+  // Authentication state
+  isLoading,
+  isAuthenticated,
+  error,
+  user,
+
+  // Methods
+  loginWithRedirect,
+  loginWithPopup,
+  logout,
+  getAccessTokenSilently,
+  getAccessTokenWithPopup,
+  getIdTokenClaims,
+  handleRedirectCallback,
+
+  // MFA API
+  mfa,
+} = useAuth0();
+```
+
+### Authentication State
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isLoading` | boolean | True while Auth0 is initializing |
+| `isAuthenticated` | boolean | True if user is logged in |
+| `error` | Error \| undefined | Authentication error if any |
+| `user` | User \| undefined | User profile information |
+
+### User Object
+
+```typescript
+interface User {
+  sub: string;          // User ID
+  name: string;         // Display name
+  email: string;        // Email address
+  email_verified: boolean;
+  picture: string;      // Avatar URL
+  updated_at: string;   // Last update timestamp
+  // Custom claims...
+}
+```
+
+### Methods
+
+#### loginWithRedirect
+
+```typescript
+await loginWithRedirect(options?: RedirectLoginOptions);
+```
+
+Redirects to Auth0 Universal Login page.
+
+**Options:**
+```typescript
+interface RedirectLoginOptions {
+  authorizationParams?: {
+    redirect_uri?: string;
+    audience?: string;
+    scope?: string;
+    connection?: string;
+    prompt?: 'none' | 'login' | 'consent' | 'select_account';
+    max_age?: number;
+    ui_locales?: string;
+    screen_hint?: 'signup' | 'login';
+  };
+  appState?: any; // Custom state to preserve
+  fragment?: string; // URL fragment
+}
+```
+
+**Example:**
+```tsx
+// Basic login
+await loginWithRedirect();
+
+// Login with specific connection
+await loginWithRedirect({
+  authorizationParams: {
+    connection: 'google-oauth2'
+  }
+});
+
+// Login with custom state (preserved through redirect)
+await loginWithRedirect({
+  appState: { targetUrl: '/dashboard' }
+});
+// After login, onRedirectCallback receives appState.targetUrl = '/dashboard'
+```
+
+#### loginWithPopup
+
+```typescript
+await loginWithPopup(options?: PopupLoginOptions);
+```
+
+Opens Auth0 login in popup window (better UX, but may be blocked).
+
+**Options:**
+```typescript
+interface PopupLoginOptions {
+  authorizationParams?: AuthorizationParams;
+  config?: PopupConfigOptions; // Popup window configuration
+}
+```
+
+**Example:**
+```tsx
+try {
+  await loginWithPopup();
+} catch (error) {
+  // Handle popup blocked or closed
+  console.error('Popup login failed:', error);
+}
+```
+
+#### logout
+
+```typescript
+logout(options?: LogoutOptions);
+```
+
+Logs out the user and optionally redirects.
+
+**Options:**
+```typescript
+interface LogoutOptions {
+  logoutParams?: {
+    returnTo?: string; // URL to redirect after logout
+    federated?: boolean; // Logout from identity provider too
+    client_id?: string; // Client ID (if different from current)
+  };
+  openUrl?: (url: string) => void; // Custom URL opener
+}
+```
+
+**Example:**
+```tsx
+// Basic logout
+logout();
+
+// Logout with redirect
+logout({
+  logoutParams: {
+    returnTo: window.location.origin
+  }
+});
+
+// Federated logout (logout from Google/Facebook too)
+logout({
+  logoutParams: {
+    returnTo: window.location.origin,
+    federated: true
+  }
+});
+```
+
+#### getAccessTokenSilently
+
+```typescript
+const token = await getAccessTokenSilently(options?: GetTokenSilentlyOptions);
+```
+
+Gets access token without user interaction (uses refresh token or iframe).
+
+**Options:**
+```typescript
+interface GetTokenSilentlyOptions {
+  authorizationParams?: {
+    audience?: string;
+    scope?: string;
+    ignoreCache?: boolean; // Force new token
+    timeoutInSeconds?: number; // Request timeout
+    detailedResponse?: boolean; // Return full response with expiry
+  };
+}
+```
+
+**Example:**
+```tsx
+// Basic usage
+const token = await getAccessTokenSilently();
+
+// With specific audience
+const token = await getAccessTokenSilently({
+  authorizationParams: {
+    audience: 'https://api.example.com'
+  }
+});
+
+// Force fresh token
+const token = await getAccessTokenSilently({
+  authorizationParams: {
+    ignoreCache: true
+  }
+});
+
+// Get detailed response with expiry
+const { access_token, expires_in } = await getAccessTokenSilently({
+  authorizationParams: {
+    detailedResponse: true
+  }
+});
+```
+
+#### getAccessTokenWithPopup
+
+```typescript
+const token = await getAccessTokenWithPopup(options?: GetTokenWithPopupOptions);
+```
+
+Gets access token via popup window. Useful as fallback when `getAccessTokenSilently` fails (e.g., third-party cookies blocked).
+
+**Options:**
+```typescript
+interface GetTokenWithPopupOptions {
+  authorizationParams?: {
+    audience?: string;
+    scope?: string;
+  };
+  config?: PopupConfigOptions; // Popup window configuration
+}
+```
+
+**Example:**
+```tsx
+// Try silent auth, fall back to popup
+try {
+  const token = await getAccessTokenSilently();
+} catch (error) {
+  // Fallback to popup if silent auth fails
+  const token = await getAccessTokenWithPopup();
+}
+
+// Direct popup usage with specific audience
+const token = await getAccessTokenWithPopup({
+  authorizationParams: {
+    audience: 'https://api.example.com'
+  }
+});
+```
+
+#### getIdTokenClaims
+
+```typescript
+const claims = await getIdTokenClaims();
+```
+
+Returns ID token claims.
+
+**Example:**
+```tsx
+const claims = await getIdTokenClaims();
+console.log(claims.sub); // User ID
+console.log(claims.email);
+console.log(claims.custom_claim);
+```
+
+#### handleRedirectCallback
+
+```typescript
+const result = await handleRedirectCallback(url?: string);
+```
+
+Manually handle redirect callback (when `skipRedirectCallback` is true).
+
+**Returns:**
+```typescript
+interface RedirectLoginResult {
+  appState: any; // Custom state from login
+}
+```
+
+#### mfa
+
+The `mfa` property provides access to the MFA API client for in-app Multi-Factor Authentication flows.
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `mfa.getAuthenticators(mfaToken)` | List enrolled authenticators for the user |
+| `mfa.getEnrollmentFactors(mfaToken)` | Get available enrollment factors (when user needs to enroll) |
+| `mfa.enroll(params)` | Enroll a new authenticator (OTP, SMS, Email, Voice, Push) |
+| `mfa.challenge(params)` | Initiate an MFA challenge for an enrolled authenticator |
+| `mfa.verify(params)` | Verify an MFA challenge and complete authentication |
+
+**Enroll params:**
+
+```typescript
+// OTP enrollment
+await mfa.enroll({ mfaToken, factorType: 'otp' });
+// Returns: { barcodeUri, recoveryCodes, ... }
+
+// SMS enrollment
+await mfa.enroll({ mfaToken, factorType: 'sms', phoneNumber: '+12025551234' });
+
+// Email enrollment
+await mfa.enroll({ mfaToken, factorType: 'email', email: 'user@example.com' });
+
+// Voice enrollment
+await mfa.enroll({ mfaToken, factorType: 'voice', phoneNumber: '+12025551234' });
+
+// Push enrollment
+await mfa.enroll({ mfaToken, factorType: 'push' });
+```
+
+**Challenge params:**
+
+```typescript
+// OTP challenge (optional — code is already in authenticator app)
+await mfa.challenge({ mfaToken, challengeType: 'otp', authenticatorId });
+
+// SMS/Voice/Email/Push challenge (required — sends code to user)
+await mfa.challenge({ mfaToken, challengeType: 'oob', authenticatorId });
+// Returns: { oobCode }
+```
+
+**Verify params:**
+
+```typescript
+// Verify with OTP code
+const tokens = await mfa.verify({ mfaToken, otp: '123456' });
+
+// Verify with OOB code (SMS/Voice/Email)
+const tokens = await mfa.verify({ mfaToken, oobCode, bindingCode: '123456' });
+
+// Verify with recovery code
+const tokens = await mfa.verify({ mfaToken, recoveryCode: 'recovery-code-here' });
+```
+
+---
+
+### MFA Error Types
+
+All MFA error types are importable from `@auth0/auth0-react`.
+
+| Error | When thrown | Key properties |
+|-------|-----------|----------------|
+| `MfaRequiredError` | `getAccessTokenSilently()` encounters an MFA requirement | `mfa_token`, `mfa_requirements` |
+| `MfaEnrollmentError` | `mfa.enroll()` fails | `error_description` |
+| `MfaChallengeError` | `mfa.challenge()` fails | `error_description` |
+| `MfaVerifyError` | `mfa.verify()` fails (e.g., invalid OTP code) | `error_description` |
+| `MfaListAuthenticatorsError` | `mfa.getAuthenticators()` fails | `error_description` |
+| `MfaEnrollmentFactorsError` | `mfa.getEnrollmentFactors()` fails | `error_description` |
+
+**MfaRequiredError properties:**
+- `mfa_token` — Token used for all subsequent MFA operations
+- `mfa_requirements.enroll` — Array of factor types the user can enroll in (present when user needs to set up MFA)
+- `mfa_requirements.challenge` — Array of factor types the user can challenge (present when user has enrolled authenticators)
+
+**Import:**
+
+```typescript
+import {
+  MfaRequiredError,
+  MfaEnrollmentError,
+  MfaChallengeError,
+  MfaVerifyError,
+} from '@auth0/auth0-react';
+```
+
+---
+
+## Custom Hooks
+
+### withAuth0
+
+Higher-order component for class components:
+
+```tsx
+import { withAuth0 } from '@auth0/auth0-react';
+
+class Profile extends React.Component {
+  render() {
+    const { auth0, isLoading, isAuthenticated, user } = this.props;
+    // Use auth0 methods and state
+  }
+}
+
+export default withAuth0(Profile);
+```
+
+### withAuthenticationRequired
+
+HOC to protect components requiring authentication:
+
+```tsx
+import { withAuthenticationRequired } from '@auth0/auth0-react';
+
+const ProtectedComponent = () => {
+  return <div>Protected content</div>;
+};
+
+export default withAuthenticationRequired(ProtectedComponent, {
+  onRedirecting: () => <div>Loading...</div>,
+  returnTo: '/profile', // Where to return after login
+  loginOptions: {
+    authorizationParams: {
+      connection: 'google-oauth2'
+    }
+  }
+});
+```
+
+---
+
+## Testing
+
+### Testing with React Testing Library
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import { Auth0Provider } from '@auth0/auth0-react';
+import App from './App';
+
+// Mock Auth0
+jest.mock('@auth0/auth0-react', () => ({
+  ...jest.requireActual('@auth0/auth0-react'),
+  Auth0Provider: ({ children }) => children,
+  useAuth0: () => ({
+    isLoading: false,
+    isAuthenticated: true,
+    user: {
+      name: 'Test User',
+      email: 'test@example.com'
+    },
+    loginWithRedirect: jest.fn(),
+    logout: jest.fn(),
+  }),
+}));
+
+test('renders authenticated app', () => {
+  render(<App />);
+  expect(screen.getByText('Test User')).toBeInTheDocument();
+});
+```
+
+### Testing with Custom Mock
+
+```tsx
+// testUtils.tsx
+import { Auth0Provider } from '@auth0/auth0-react';
+
+export const mockAuth0User = {
+  name: 'Test User',
+  email: 'test@example.com',
+  picture: 'https://example.com/avatar.jpg',
+};
+
+export function renderWithAuth0(ui: React.ReactElement, isAuthenticated = true) {
+  return render(
+    <Auth0Provider
+      domain="test.auth0.com"
+      clientId="test-client-id"
+      authorizationParams={{
+        redirect_uri: window.location.origin
+      }}
+    >
+      {ui}
+    </Auth0Provider>
+  );
+}
+```
+
+---
+
+## TypeScript Types
+
+### Import Types
+
+```typescript
+import type {
+  Auth0ContextInterface,
+  User,
+  RedirectLoginOptions,
+  PopupLoginOptions,
+  LogoutOptions,
+  GetTokenSilentlyOptions,
+  MfaApiClient,
+  Authenticator,
+  EnrollParams,
+  ChallengeResponse,
+  VerifyParams,
+  EnrollmentFactor,
+} from '@auth0/auth0-react';
+
+// MFA error types (value imports, not type-only)
+import {
+  MfaRequiredError,
+  MfaEnrollmentError,
+  MfaChallengeError,
+  MfaVerifyError,
+} from '@auth0/auth0-react';
+```
+
+### Type User Profile
+
+```typescript
+interface CustomUser extends User {
+  app_metadata?: {
+    roles?: string[];
+  };
+  user_metadata?: {
+    preferences?: any;
+  };
+}
+
+const { user } = useAuth0<CustomUser>();
+console.log(user?.app_metadata?.roles);
+```
+
+---
+
+# Auth0 React Integration Patterns
+
+Practical implementation patterns and examples for common use cases.
+
+---
+
+## Protected Routes
+
+### Basic Protected Route Component
+
+```tsx
+import { useAuth0 } from '@auth0/auth0-react';
+import { Navigate } from 'react-router-dom';
+
+export function ProtectedRoute({ children }: { children: React.ReactNode }) {
+  const { isAuthenticated, isLoading, loginWithRedirect } = useAuth0();
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  if (!isAuthenticated) {
+    loginWithRedirect();
+    return null;
+  }
+
+  return <>{children}</>;
+}
+```
+
+### Usage with React Router
+
+```tsx
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import { ProtectedRoute } from './components/ProtectedRoute';
+
+function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path="/" element={<Home />} />
+        <Route
+          path="/profile"
+          element={
+            <ProtectedRoute>
+              <Profile />
+            </ProtectedRoute>
+          }
+        />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+---
+
+## User Profile
+
+### Display User Information
+
+```tsx
+import { useAuth0 } from '@auth0/auth0-react';
+
+export function Profile() {
+  const { user, isAuthenticated } = useAuth0();
+
+  if (!isAuthenticated) {
+    return <div>Please log in</div>;
+  }
+
+  return (
+    <div>
+      <img src={user?.picture} alt={user?.name} />
+      <h2>{user?.name}</h2>
+      <p>{user?.email}</p>
+    </div>
+  );
+}
+```
+
+---
+
+## Calling APIs
+
+### Call Protected API with Access Token
+
+```tsx
+import { useAuth0 } from '@auth0/auth0-react';
+import { useState } from 'react';
+
+export function ApiTest() {
+  const { getAccessTokenSilently } = useAuth0();
+  const [data, setData] = useState(null);
+  const [error, setError] = useState(null);
+
+  const callApi = async () => {
+    try {
+      const token = await getAccessTokenSilently({
+        authorizationParams: {
+          audience: 'https://your-api-identifier', // Your API identifier
+        }
+      });
+
+      const response = await fetch('https://api.example.com/data', {
+        headers: {
+          Authorization: `Bearer ${token}`
+        }
+      });
+
+      const json = await response.json();
+      setData(json);
+    } catch (err) {
+      setError(err.message);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={callApi}>Call API</button>
+      {error && <div>Error: {error}</div>}
+      {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
+    </div>
+  );
+}
+```
+
+### Configure Provider for API Calls
+
+When calling APIs, add `audience` to your Auth0Provider:
+
+```tsx
+<Auth0Provider
+  domain={import.meta.env.VITE_AUTH0_DOMAIN}
+  clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
+  authorizationParams={{
+    redirect_uri: window.location.origin,
+    audience: 'https://your-api-identifier' // Add this
+  }}
+>
+  <App />
+</Auth0Provider>
+```
+
+---
+
+## Error Handling
+
+### Handle Loading and Error States
+
+```tsx
+import { useAuth0 } from '@auth0/auth0-react';
+
+export function App() {
+  const { isLoading, error, isAuthenticated, user } = useAuth0();
+
+  if (isLoading) {
+    return <div>Loading authentication...</div>;
+  }
+
+  if (error) {
+    return <div>Authentication error: {error.message}</div>;
+  }
+
+  return isAuthenticated ? (
+    <div>
+      <h1>Welcome back, {user?.name}!</h1>
+      <AuthenticatedApp />
+    </div>
+  ) : (
+    <div>
+      <h1>Please log in</h1>
+      <LoginButton />
+    </div>
+  );
+}
+```
+
+---
+
+## Silent Authentication
+
+### Auto-login on Page Load
+
+```tsx
+import { useAuth0 } from '@auth0/auth0-react';
+import { useEffect } from 'react';
+
+export function App() {
+  const { isAuthenticated, isLoading, getAccessTokenSilently } = useAuth0();
+
+  useEffect(() => {
+    if (!isLoading && !isAuthenticated) {
+      // Attempt silent authentication
+      getAccessTokenSilently().catch(() => {
+        // User not logged in, do nothing
+      });
+    }
+  }, [isLoading, isAuthenticated, getAccessTokenSilently]);
+
+  // Rest of your app...
+}
+```
+
+---
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "Invalid state" error | Clear browser storage and try again. Ensure `redirect_uri` matches configured callback URL |
+| User stuck on loading | Check Auth0 application settings have correct callback URLs configured |
+| API calls fail with 401 | Ensure `audience` is configured in Auth0Provider and matches your API identifier |
+| Logout doesn't work | Include `returnTo` URL in logout options and configure in Auth0 "Allowed Logout URLs" |
+| CORS errors when calling API | Add your application URL to "Allowed Web Origins" in Auth0 application settings |
+| Tokens not refreshing | Enable `useRefreshTokens={true}` in Auth0Provider and ensure refresh token rotation is enabled in Auth0 |
+
+---
+
+## MFA Handling
+
+The `@auth0/auth0-react` SDK provides a built-in MFA API for handling Multi-Factor Authentication entirely within your app — no redirects to Universal Login required. Access it via the `mfa` property from `useAuth0()`.
+
+> **Note:** MFA support via SDKs is currently in Early Access. For a simpler approach that uses Universal Login to handle MFA automatically (no custom UI), see the [Step-Up via Popup](#step-up-via-popup-simpler-approach) section below.
+
+### Catching MfaRequiredError
+
+When `getAccessTokenSilently()` encounters an MFA requirement, it throws `MfaRequiredError`. Catch it and inspect `mfa_requirements` to determine the flow:
+
+```tsx
+import { useAuth0, MfaRequiredError } from '@auth0/auth0-react';
+import { useState } from 'react';
+
+export function ProtectedApiCall() {
+  const { getAccessTokenSilently, mfa } = useAuth0();
+  const [mfaToken, setMfaToken] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const callApi = async () => {
+    try {
+      const token = await getAccessTokenSilently();
+      // Use token to call API...
+    } catch (err) {
+      if (err instanceof MfaRequiredError) {
+        setMfaToken(err.mfa_token);
+
+        // Check if enrollment or challenge is needed
+        const factors = await mfa.getEnrollmentFactors(err.mfa_token);
+        if (factors.length > 0) {
+          // User needs to enroll — show enrollment UI
+        } else {
+          // User has authenticators — show challenge UI
+          const authenticators = await mfa.getAuthenticators(err.mfa_token);
+          // Let user pick authenticator and proceed with challenge
+        }
+      } else {
+        setError(err.message);
+      }
+    }
+  };
+
+  return <button onClick={callApi}>Call Protected API</button>;
+}
+```
+
+### OTP Enrollment
+
+When the user needs to set up MFA for the first time:
+
+```tsx
+import { useAuth0, MfaEnrollmentError } from '@auth0/auth0-react';
+import { useState } from 'react';
+
+export function OtpEnrollment({ mfaToken }: { mfaToken: string }) {
+  const { mfa } = useAuth0();
+  const [barcodeUri, setBarcodeUri] = useState<string | null>(null);
+  const [recoveryCodes, setRecoveryCodes] = useState<string[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const startEnrollment = async () => {
+    try {
+      const enrollment = await mfa.enroll({ mfaToken, factorType: 'otp' });
+      setBarcodeUri(enrollment.barcodeUri);
+      setRecoveryCodes(enrollment.recoveryCodes);
+    } catch (err) {
+      if (err instanceof MfaEnrollmentError) {
+        setError(err.error_description);
+      }
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={startEnrollment}>Set up authenticator app</button>
+      {barcodeUri && (
+        <div>
+          <p>Scan this QR code with your authenticator app:</p>
+          {/* Render barcodeUri as QR code using a library like qrcode.react */}
+          <code>{barcodeUri}</code>
+        </div>
+      )}
+      {recoveryCodes && (
+        <div>
+          <p>Save these recovery codes:</p>
+          <ul>
+            {recoveryCodes.map((code, i) => <li key={i}>{code}</li>)}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Challenge and Verify
+
+When the user already has enrolled authenticators:
+
+```tsx
+import {
+  useAuth0,
+  MfaChallengeError,
+  MfaVerifyError,
+} from '@auth0/auth0-react';
+import { useState } from 'react';
+
+export function MfaChallenge({ mfaToken }: { mfaToken: string }) {
+  const { mfa } = useAuth0();
+  const [otp, setOtp] = useState('');
+  const [error, setError] = useState<string | null>(null);
+
+  const handleVerify = async () => {
+    try {
+      // For OTP authenticators, you can skip challenge() and go straight to verify()
+      const tokens = await mfa.verify({ mfaToken, otp });
+      // User is now authenticated — tokens are cached by the SDK
+      // Access token available at tokens.access_token
+    } catch (err) {
+      if (err instanceof MfaVerifyError) {
+        setError('Invalid code. Please try again.');
+      } else if (err instanceof MfaChallengeError) {
+        setError('Challenge failed: ' + err.error_description);
+      }
+    }
+  };
+
+  return (
+    <div>
+      <h3>Enter your verification code</h3>
+      <input
+        type="text"
+        value={otp}
+        onChange={(e) => setOtp(e.target.value)}
+        placeholder="6-digit code"
+        maxLength={6}
+      />
+      <button onClick={handleVerify}>Verify</button>
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+    </div>
+  );
+}
+```
+
+### SMS/Email Challenge (Out-of-Band)
+
+For SMS, Email, Voice, or Push authenticators, you must call `challenge()` first to send the code:
+
+```tsx
+// Initiate challenge to send code via SMS/Email
+const response = await mfa.challenge({
+  mfaToken,
+  challengeType: 'oob',
+  authenticatorId: authenticator.id,
+});
+
+// Verify with the OOB code and the binding code the user received
+const tokens = await mfa.verify({
+  mfaToken,
+  oobCode: response.oobCode,
+  bindingCode: userEnteredCode,
+});
+```
+
+### Step-Up via Popup (Simpler Approach)
+
+If you don't need a custom MFA UI, configure `interactiveErrorHandler` to let the SDK handle MFA automatically via a Universal Login popup:
+
+```tsx
+<Auth0Provider
+  domain={import.meta.env.VITE_AUTH0_DOMAIN}
+  clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
+  authorizationParams={{
+    redirect_uri: window.location.origin,
+    audience: 'https://your-api-identifier',
+  }}
+  useRefreshTokens={true}
+  interactiveErrorHandler="popup"
+>
+  <App />
+</Auth0Provider>
+```
+
+With this setup, `getAccessTokenSilently()` automatically opens a popup when MFA is required. No error handling needed — the token is returned after the user completes MFA in the popup.
+
+---
+
+## Security Considerations
+
+### Client-Side Security
+
+- **Never expose client secret** - React is client-side, use only public client credentials
+- **Use PKCE** - Enabled by default with @auth0/auth0-react
+- **Validate tokens on backend** - Never trust client-side token validation
+- **Use HTTPS in production** - Auth0 requires HTTPS for production redirect URLs
+- **Implement proper CORS** - Configure allowed origins in Auth0 application settings
+
+### Token Storage
+
+```tsx
+// Default: memory storage for highest security (tokens cleared on page refresh)
+<Auth0Provider
+  cacheLocation="memory"
+  {...other props}
+>
+
+// Or localstorage for better UX (tokens persist across refreshes)
+<Auth0Provider
+  cacheLocation="localstorage"
+  {...other props}
+>
+```
+
+### Secure API Calls
+
+Always validate tokens on your backend:
+
+**Installation:**
+```bash
+npm install express-oauth2-jwt-bearer
+```
+
+**Backend validation example (Node.js):**
+```javascript
+const { auth, requiredScopes } = require('express-oauth2-jwt-bearer');
+
+const checkJwt = auth({
+  audience: process.env.AUTH0_AUDIENCE,
+  issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
+});
+
+app.get('/api/private', checkJwt, (req, res) => {
+  res.json({ message: 'Secured data' });
+});
+
+// With scope validation
+app.get('/api/users', checkJwt, requiredScopes('read:users'), (req, res) => {
+  res.json({ users: [] });
+});
+```
+
+---
+
+## Advanced Patterns
+
+### Custom Login with Redirect Options
+
+```tsx
+const { loginWithRedirect } = useAuth0();
+
+// Login with specific connection
+await loginWithRedirect({
+  authorizationParams: {
+    connection: 'google-oauth2'
+  }
+});
+
+// Login with prompt
+await loginWithRedirect({
+  authorizationParams: {
+    prompt: 'login' // Force login even if user has session
+  }
+});
+
+// Login with custom state
+await loginWithRedirect({
+  appState: { targetUrl: '/protected-page' }
+});
+```
+
+### Handle Redirect Callback
+
+```tsx
+import { useAuth0 } from '@auth0/auth0-react';
+import { useEffect } from 'react';
+import { useNavigate } from 'react-router-dom';
+
+export function Callback() {
+  const { handleRedirectCallback } = useAuth0();
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    (async () => {
+      const result = await handleRedirectCallback();
+      const targetUrl = result.appState?.targetUrl || '/';
+      navigate(targetUrl);
+    })();
+  }, [handleRedirectCallback, navigate]);
+
+  return <div>Processing login...</div>;
+}
+```
+
+### Custom Logout
+
+```tsx
+const { logout } = useAuth0();
+
+// Logout with custom return URL
+logout({
+  logoutParams: {
+    returnTo: `${window.location.origin}/goodbye`
+  }
+});
+
+// Logout without redirect (federated logout)
+logout({
+  logoutParams: {
+    federated: true
+  }
+});
+```
+
+---
+
+## Testing
+
+### Manual Testing Checklist
+
+1. **Login Flow**
+   - Start dev server: `npm run dev` (Vite) or `npm start` (CRA)
+   - Click "Login" button
+   - Complete Auth0 Universal Login
+   - Verify redirect back to your app with user authenticated
+   - Check user profile displays correctly
+
+2. **Logout Flow**
+   - Click "Logout" button
+   - Verify user is logged out
+   - Verify redirect to correct page
+
+3. **Protected Routes**
+   - Navigate to protected route while logged out
+   - Verify redirect to Auth0 login
+   - After login, verify redirect back to protected route
+
+4. **API Calls**
+   - Call protected API endpoint
+   - Verify access token is included in request
+   - Verify API responds correctly
+
+---
+
+---
+
+# Auth0 React Setup Guide
+
+Complete setup instructions with automated scripts and manual configuration options.
+
+---
+
+## Quick Setup (Automated)
+
+**Never read the contents of `.env` at any point during setup.** The file may contain sensitive secrets that should not be exposed in the LLM context. If you determine you need to read the file for any reason, ask the user for explicit permission before doing so — do not proceed until the user confirms.
+
+**Before running any part of this setup that writes to `.env`, you must ask the user for explicit confirmation.** Follow the steps below precisely.
+
+### Step 1: Check for existing .env and confirm with user
+
+Before writing to `.env`, check whether the file already exists:
+
+```bash
+test -f .env && echo "EXISTS" || echo "NOT_FOUND"
+```
+
+Then ask the user for explicit confirmation before proceeding — do not continue until the user confirms:
+
+- If `.env` does **not** exist, ask:
+  - Question: "This setup will create a `.env` file containing Auth0 credentials (domain and client ID). Do you want to proceed?"
+  - Options: "Yes, create .env" / "No, I'll configure it manually"
+
+- If `.env` **already exists**, ask:
+  - Question: "A `.env` file already exists and may contain secrets unrelated to Auth0. This setup will append Auth0 credentials to it without modifying existing content. Do you want to proceed?"
+  - Options: "Yes, append to existing .env" / "No, I'll update it manually"
+
+**Do not proceed with writing to `.env` unless the user selects the confirmation option.**
+
+### Step 2: Run automated setup (only after confirmation)
+
+#### Bash Script (macOS/Linux)
+
+Run this script to automatically set up everything:
+
+```bash
+#!/bin/bash
+
+# Detect OS and install Auth0 CLI if needed
+if ! command -v auth0 &> /dev/null; then
+  echo "Installing Auth0 CLI..."
+  if [[ "$OSTYPE" == "darwin"* || "$OSTYPE" == "linux-gnu"* ]]; then
+    if ! command -v brew &> /dev/null; then
+      echo "❌ Homebrew is required to install the Auth0 CLI."
+      echo "   Install Homebrew: https://brew.sh"
+      echo "   Then re-run this script, or install the CLI manually:"
+      echo "   https://github.com/auth0/auth0-cli#installation"
+      exit 1
+    fi
+    brew install auth0/auth0-cli/auth0
+  elif [[ "$OSTYPE" == "msys" || "$OSTYPE" == "cygwin" ]]; then
+    echo "Please install Auth0 CLI: https://github.com/auth0/auth0-cli#installation"
+    exit 1
+  fi
+fi
+
+# Check if logged in to Auth0
+if ! auth0 tenants list &> /dev/null; then
+  echo ""
+  echo "======================================"
+  echo "Auth0 Login Required"
+  echo "======================================"
+  echo ""
+  read -p "Do you have an Auth0 account? (y/n): " HAS_ACCOUNT
+
+  if [[ "$HAS_ACCOUNT" != "y" ]]; then
+    echo ""
+    echo "Let's create your free Auth0 account!"
+    echo ""
+    echo "1. Visit: https://auth0.com/signup"
+    echo "2. Sign up with your email or GitHub"
+    echo "3. Choose a tenant domain (e.g., 'mycompany')"
+    echo "4. Complete the onboarding"
+    echo ""
+    read -p "Press Enter when you've created your account..."
+  fi
+
+  echo ""
+  echo "Logging in to Auth0..."
+  echo "A browser will open for authentication."
+  echo ""
+  auth0 login
+
+  if ! auth0 tenants list &> /dev/null; then
+    echo "❌ Login failed. Please try again or visit https://auth0.com/docs"
+    exit 1
+  fi
+
+  echo "✅ Successfully logged in to Auth0!"
+fi
+
+# Detect if Vite or CRA
+if grep -q '"vite"' package.json 2>/dev/null; then
+  PREFIX="VITE_AUTH0"
+elif grep -q '"react-scripts"' package.json 2>/dev/null; then
+  PREFIX="REACT_APP_AUTH0"
+else
+  echo "Detecting React project type..."
+  PREFIX="VITE_AUTH0"  # Default to Vite
+fi
+
+# List apps and prompt for selection
+echo "Your Auth0 applications:"
+auth0 apps list
+
+read -p "Enter your Auth0 app ID (or press Enter to create a new one): " APP_ID
+
+if [ -z "$APP_ID" ]; then
+  echo "Creating new Auth0 SPA application..."
+  APP_NAME="${PWD##*/}-react-app"
+  APP_ID=$(auth0 apps create \
+    --name "$APP_NAME" \
+    --type spa \
+    --auth-method None \
+    --callbacks "http://localhost:3000,http://localhost:5173" \
+    --logout-urls "http://localhost:3000,http://localhost:5173" \
+    --origins "http://localhost:3000,http://localhost:5173" \
+    --web-origins "http://localhost:3000,http://localhost:5173" \
+    --metadata "created_by=agent_skills" \
+    --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+  echo "Created app with ID: $APP_ID"
+fi
+
+# Get app details and create .env file
+echo "Fetching Auth0 credentials..."
+AUTH0_DOMAIN=$(auth0 apps show "$APP_ID" --json | grep -o '"domain":"[^"]*' | cut -d'"' -f4)
+AUTH0_CLIENT_ID=$(auth0 apps show "$APP_ID" --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+
+# Append Auth0 credentials to .env
+cat >> .env << EOF
+${PREFIX}_DOMAIN=$AUTH0_DOMAIN
+${PREFIX}_CLIENT_ID=$AUTH0_CLIENT_ID
+EOF
+
+echo "✅ Auth0 configuration complete!"
+echo "Appended to .env:"
+echo "  ${PREFIX}_DOMAIN=$AUTH0_DOMAIN"
+echo "  ${PREFIX}_CLIENT_ID=$AUTH0_CLIENT_ID"
+```
+
+#### PowerShell Script (Windows)
+
+```powershell
+# Install Auth0 CLI if not present
+if (!(Get-Command auth0 -ErrorAction SilentlyContinue)) {
+  Write-Host "Installing Auth0 CLI..."
+  scoop install auth0
+}
+
+# Check if logged in
+try {
+  auth0 tenants list | Out-Null
+} catch {
+  Write-Host ""
+  Write-Host "======================================"
+  Write-Host "Auth0 Login Required"
+  Write-Host "======================================"
+  Write-Host ""
+
+  $hasAccount = Read-Host "Do you have an Auth0 account? (y/n)"
+
+  if ($hasAccount -ne "y") {
+    Write-Host ""
+    Write-Host "Let's create your free Auth0 account!"
+    Write-Host ""
+    Write-Host "1. Visit: https://auth0.com/signup"
+    Write-Host "2. Sign up with your email or GitHub"
+    Write-Host "3. Choose a tenant domain (e.g., 'mycompany')"
+    Write-Host "4. Complete the onboarding"
+    Write-Host ""
+    Read-Host "Press Enter when you've created your account"
+  }
+
+  Write-Host ""
+  Write-Host "Logging in to Auth0..."
+  Write-Host "A browser will open for authentication."
+  Write-Host ""
+  auth0 login
+
+  try {
+    auth0 tenants list | Out-Null
+    Write-Host "✅ Successfully logged in to Auth0!"
+  } catch {
+    Write-Host "❌ Login failed. Please try again or visit https://auth0.com/docs"
+    exit 1
+  }
+}
+
+# Detect project type
+$prefix = if (Select-String -Path "package.json" -Pattern '"vite"' -Quiet) { "VITE_AUTH0" }
+          elseif (Select-String -Path "package.json" -Pattern '"react-scripts"' -Quiet) { "REACT_APP_AUTH0" }
+          else { "VITE_AUTH0" }
+
+# List and select app
+Write-Host "Your Auth0 applications:"
+auth0 apps list
+
+$appId = Read-Host "Enter your Auth0 app ID (or press Enter to create new)"
+
+if ([string]::IsNullOrEmpty($appId)) {
+  $appName = Split-Path -Leaf (Get-Location)
+  Write-Host "Creating new Auth0 SPA application..."
+  $appJson = auth0 apps create --name "$appName-react-app" --type spa `
+    --auth-method None `
+    --callbacks "http://localhost:3000,http://localhost:5173" `
+    --logout-urls "http://localhost:3000,http://localhost:5173" `
+    --origins "http://localhost:3000,http://localhost:5173" `
+    --web-origins "http://localhost:3000,http://localhost:5173" `
+    --metadata "created_by=agent_skills" --json
+
+  $appId = ($appJson | ConvertFrom-Json).client_id
+  Write-Host "Created app with ID: $appId"
+}
+
+# Get credentials and create .env
+Write-Host "Fetching Auth0 credentials..."
+$appDetails = auth0 apps show $appId --json | ConvertFrom-Json
+
+@"
+${prefix}_DOMAIN=$($appDetails.domain)
+${prefix}_CLIENT_ID=$($appDetails.client_id)
+"@ | Out-File -FilePath .env -Encoding UTF8 -Append
+
+Write-Host "✅ Auth0 configuration complete!"
+Write-Host "Appended to .env:"
+Write-Host "  ${prefix}_DOMAIN=$($appDetails.domain)"
+Write-Host "  ${prefix}_CLIENT_ID=$($appDetails.client_id)"
+```
+
+---
+
+## Manual Setup
+
+If you prefer manual setup or the scripts don't work:
+
+### Step 1: Install SDK
+
+```bash
+npm install @auth0/auth0-react
+```
+
+### Step 2: Install Auth0 CLI
+
+**macOS:**
+```bash
+brew install auth0/auth0-cli/auth0
+```
+
+**Linux (via Homebrew):**
+```bash
+# Requires Homebrew on Linux: https://brew.sh
+brew install auth0/auth0-cli/auth0
+```
+
+**Windows:**
+```powershell
+scoop install auth0
+# Or: choco install auth0-cli
+```
+
+### Step 3: Get Credentials
+
+```bash
+# Login to Auth0
+auth0 login
+
+# List your apps
+auth0 apps list
+
+# Get app details (replace <app-id>)
+auth0 apps show <app-id>
+```
+
+### Step 4: Create .env File
+
+**For Vite:**
+```bash
+VITE_AUTH0_DOMAIN=<your-tenant>.auth0.com
+VITE_AUTH0_CLIENT_ID=<your-client-id>
+```
+
+**For Create React App:**
+```bash
+REACT_APP_AUTH0_DOMAIN=<your-tenant>.auth0.com
+REACT_APP_AUTH0_CLIENT_ID=<your-client-id>
+```
+
+---
+
+## Creating an Auth0 Application via Dashboard
+
+If you prefer using the Auth0 Dashboard instead of the CLI:
+
+1. Go to [Auth0 Dashboard](https://manage.auth0.com)
+2. Navigate to **Applications** → **Applications**
+3. Click **Create Application**
+4. Choose:
+   - Name: Your app name
+   - Type: **Single Page Web Applications**
+5. Configure:
+   - **Allowed Callback URLs**: `http://localhost:3000, http://localhost:5173`
+   - **Allowed Logout URLs**: `http://localhost:3000, http://localhost:5173`
+   - **Allowed Web Origins**: `http://localhost:3000, http://localhost:5173`
+   - **Allowed Origins (CORS)**: `http://localhost:3000, http://localhost:5173`
+6. Copy your **Domain** and **Client ID**
+7. Create `.env` file as shown in Step 4 above
+
+---
+
+## Troubleshooting Setup
+
+### CLI Installation Issues
+
+**macOS - Homebrew not found:**
+```bash
+# Install Homebrew first
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+**Windows - Scoop not found:**
+```powershell
+# Install Scoop first
+iwr -useb get.scoop.sh | iex
+```
+
+### Login Issues
+
+**Browser doesn't open:**
+```bash
+# Use device code flow
+auth0 login --no-browser
+```
+
+**"Not logged in" error:**
+```bash
+# Force new login
+auth0 login --force
+```
+
+### Environment Variable Issues
+
+**Variables not loading (Vite):**
+- Ensure variables start with `VITE_`
+- Restart dev server after creating `.env`
+- Check file is named exactly `.env` (not `.env.local`)
+
+**Variables not loading (CRA):**
+- Ensure variables start with `REACT_APP_`
+- Restart dev server after creating `.env`
+- CRA doesn't support `.env` hot reload
+
+---
+
+## Next Steps
+
+After setup is complete:
+1. Return to the main skill guide for integration steps
diff --git a/main/.mintlify/skills/auth0/references/framework-spa-js/index.md b/main/.mintlify/skills/auth0/references/framework-spa-js/index.md
new file mode 100644
index 0000000000..ed31c12b15
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-spa-js/index.md
@@ -0,0 +1,1176 @@
+
+# Auth0 SPA JS Integration
+
+Add authentication to any browser-based single-page application using `@auth0/auth0-spa-js` — the low-level Auth0 SDK for Vanilla JS, Svelte, SolidJS, and any SPA not using React, Angular, or Vue.
+
+> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
+> ```
+> gh api repos/auth0/auth0-spa-js/releases/latest --jq '.tag_name'
+> ```
+> Use the returned version in all dependency lines instead of any hardcoded version below. If the command fails, fall back to checking https://github.com/auth0/auth0-spa-js/releases.
+
+## Critical rules
+
+- **You MUST ask the user for explicit confirmation before running any setup step that writes to `.env`.** Never read the contents of `.env` during setup; if you believe you need to, ask the user for explicit permission first and wait for confirmation.
+
+## Prerequisites
+
+- Modern browser with ES2017+ support
+- npm or yarn (or use CDN for no-bundler apps)
+- Auth0 account with a Single Page Application configured
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **React SPAs** (hooks, Auth0Provider): use the Auth0 integration workflow for React
+- **Angular SPAs** (AuthModule, AuthGuard): use the Auth0 integration workflow for Angular
+- **Vue 3 SPAs** (createAuth0, useAuth0): use the Auth0 integration workflow for Vue
+- **Next.js** (server-side sessions, App Router): use the Auth0 integration workflow for Next.js
+- **Nuxt** (server-side SSR): use the Auth0 integration workflow for Nuxt
+- **Express server-side web apps**: use the Auth0 integration workflow for Express
+- **React Native / Expo mobile apps**: use the Auth0 integration workflow for React Native
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+npm install @auth0/auth0-spa-js
+```
+
+Or via CDN (no bundler). Run this to get the latest version, then use it in your HTML:
+```bash
+VERSION=$(npm view @auth0/auth0-spa-js version)
+```
+```html
+<script src="https://cdn.auth0.com/js/auth0-spa-js/$VERSION/auth0-spa-js.production.js"></script>
+```
+
+### 2. Configure Auth0
+
+**For automated setup with Auth0 CLI**, see the Setup Guide section below for complete scripts.
+
+**For manual setup**, create `.env` (Vite):
+
+```bash
+VITE_AUTH0_DOMAIN=your-tenant.auth0.com
+VITE_AUTH0_CLIENT_ID=your-client-id
+```
+
+In Auth0 Dashboard, set for your **Single Page Application**:
+- **Allowed Callback URLs**: `http://localhost:5173`
+- **Allowed Logout URLs**: `http://localhost:5173`
+- **Allowed Web Origins**: `http://localhost:5173`
+
+### 3. Initialize Auth0 Client
+
+```js
+import { createAuth0Client } from '@auth0/auth0-spa-js';
+
+const auth0 = await createAuth0Client({
+  domain: import.meta.env.VITE_AUTH0_DOMAIN,
+  clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+  authorizationParams: {
+    redirect_uri: window.location.origin
+  }
+});
+
+// Handle redirect callback after login
+const query = new URLSearchParams(window.location.search);
+if ((query.has('code') || query.has('error')) && query.has('state')) {
+  await auth0.handleRedirectCallback();
+  window.history.replaceState({}, document.title, window.location.pathname);
+}
+```
+
+### 4. Add Login / Logout
+
+> **Agent instruction:** Before adding new UI elements, search the project for existing click handlers for login, logout, sign-in, or sign-out buttons. If existing handlers are found, hook the Auth0 code into them without modifying the existing UI. Only create new buttons if no existing handlers are found.
+
+```js
+// Login
+document.getElementById('login-btn').addEventListener('click', async () => {
+  await auth0.loginWithRedirect();
+});
+
+// Logout
+document.getElementById('logout-btn').addEventListener('click', () => {
+  auth0.logout({
+    logoutParams: { returnTo: window.location.origin }
+  });
+});
+
+// Update UI based on auth state
+const isAuthenticated = await auth0.isAuthenticated();
+if (isAuthenticated) {
+  const user = await auth0.getUser();
+  console.log(user.name, user.email);
+}
+```
+
+### 5. Get Access Tokens for API Calls
+
+```js
+const accessToken = await auth0.getTokenSilently();
+
+const response = await fetch('https://your-api.example.com/data', {
+  headers: { Authorization: `Bearer ${accessToken}` }
+});
+```
+
+### 6. Build & Verify
+
+> **Agent instruction:** After completing the integration, build the project to verify it compiles successfully:
+> ```bash
+> npm run build
+> ```
+> If the build fails, analyze the error output and fix the issues. Common integration build failures include:
+> - **Module not found**: Missing `npm install @auth0/auth0-spa-js` — run the install command
+> - **Cannot find name 'import.meta'**: TypeScript target too low — set `"target": "ES2020"` or higher in `tsconfig.json`
+> - **`createAuth0Client` is not a function**: Wrong import path or CDN usage without bundle step
+> - **Env vars undefined at runtime**: Vite requires `VITE_` prefix; webpack/CRA requires `REACT_APP_` prefix
+>
+> Re-run the build after each fix. Track the number of build-fix iterations.
+>
+> **Failcheck:** If the build still fails after 5–6 fix attempts, stop and ask the user using `AskUserQuestion`:
+> _"The build is still failing after several fix attempts. How would you like to proceed?"_
+> - **Let the skill continue fixing iteratively** — continue the build-fix loop for another 5–6 attempts
+> - **Fix it manually** — show the remaining errors and let the user resolve them
+> - **Skip build verification** — proceed without a successful build
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Callback URL port mismatch (e.g., `localhost:3001` vs `localhost:5173`) | Match Allowed Callback URLs exactly to your dev server port in Auth0 Dashboard |
+| `client_secret` in SPA code | SPAs must never have a client secret — remove it. Auth0 sets auth method to `None` for SPA apps |
+| Tokens stored in `localStorage` | Use in-memory storage (default) or `sessionStorage`. Never `localStorage` — XSS risk |
+| `getTokenSilently()` throws `login_required` on page refresh | Add your app origin to **Allowed Web Origins** in Auth0 Dashboard |
+| `handleRedirectCallback()` not called after redirect | Must call after login redirect to exchange the auth code; without this the URL params persist and re-trigger |
+| Domain includes `https://` prefix | Auth0 domain should be hostname only: `your-tenant.auth0.com`, not `https://your-tenant.auth0.com` |
+| `loginWithPopup()` called from async init code | Popups must be triggered directly from a user gesture (click handler). Never call from init or page load code |
+| Using `Auth0Provider` from `@auth0/auth0-react` in Vanilla JS | For Vanilla JS, use `createAuth0Client()` directly — no provider component needed |
+
+## Related Capabilities
+
+- Auth0 setup — run the CLI: `auth0 login`, then `auth0 apps create`
+- React SPAs with hooks — use the Auth0 integration workflow for React
+- Angular SPAs — use the Auth0 integration workflow for Angular
+- Vue 3 SPAs — use the Auth0 integration workflow for Vue
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- Manage Auth0 resources from the terminal — the Auth0 CLI (`tooling-cli`)
+
+## Quick Reference
+
+### Core Methods
+
+| Method | Description |
+|--------|-------------|
+| `createAuth0Client(options)` | Create and initialize client (calls `checkSession` internally) |
+| `new Auth0Client(options)` | Instantiate without auto session check |
+| `auth0.loginWithRedirect(options?)` | Redirect to Auth0 Universal Login |
+| `auth0.loginWithPopup(options?)` | Open Auth0 login in a popup |
+| `auth0.logout(options?)` | Clear session and redirect |
+| `auth0.handleRedirectCallback(url?)` | Process redirect result after login |
+| `auth0.isAuthenticated()` | `Promise<boolean>` |
+| `auth0.getUser()` | `Promise<User \| undefined>` |
+| `auth0.getTokenSilently(options?)` | `Promise<string>` — access token |
+| `auth0.checkSession()` | Attempt silent re-authentication |
+
+### Common Use Cases
+
+- Login/Logout → See Step 4 above
+- Protecting content → see the Protecting Content section below
+- API calls with tokens → see the Calling Protected APIs section below
+- Refresh tokens → see the Refresh Token Rotation section below
+- Organizations → see the Organizations section below
+- MFA handling → see the MFA Handling section below
+- Error handling → see the Error Handling section below
+
+## References
+
+- [Auth0 SPA JS SDK Documentation](https://auth0.com/docs/libraries/auth0-spa-js)
+- [Auth0 Vanilla JS Quickstart](https://auth0.com/docs/quickstart/spa/vanillajs)
+- [SDK GitHub Repository](https://github.com/auth0/auth0-spa-js)
+- [EXAMPLES.md — Advanced patterns](https://github.com/auth0/auth0-spa-js/blob/main/EXAMPLES.md)
+- [API Documentation](https://auth0.github.io/auth0-spa-js/)
+
+---
+
+# Auth0 SPA JS — API Reference & Testing
+
+---
+
+## Configuration Reference
+
+### Auth0ClientOptions
+
+Options passed to `createAuth0Client()` or `new Auth0Client()`.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `domain` | `string` | Yes | Auth0 tenant domain — hostname only, no `https://` prefix |
+| `clientId` | `string` | Yes | SPA application Client ID from Auth0 Dashboard |
+| `authorizationParams` | `AuthorizationParams` | No | Authorization request parameters |
+| `authorizationParams.redirect_uri` | `string` | No | Where Auth0 redirects after login (default: `window.location.origin`) |
+| `authorizationParams.audience` | `string` | No | API identifier (e.g., `https://api.example.com`) for access tokens |
+| `authorizationParams.scope` | `string` | No | Space-separated OIDC scopes (default: `openid profile email`) |
+| `authorizationParams.organization` | `string` | No | Organization ID or name for multi-tenant apps |
+| `useRefreshTokens` | `boolean` | No | Enable refresh token rotation (default: `false`) |
+| `useRefreshTokensFallback` | `boolean` | No | Fall back to iframe silent auth if refresh token fails (default: `false`) |
+| `cacheLocation` | `'memory' \| 'localstorage'` | No | Token cache location (default: `'memory'`) |
+| `cache` | `ICache` | No | Custom cache implementation |
+| `useDpop` | `boolean` | No | Enable DPoP token binding (default: `false`) |
+| `useMrrt` | `boolean` | No | Multi-resource refresh tokens — requires `useRefreshTokens: true` (default: `false`) |
+| `leeway` | `number` | No | Clock skew tolerance in seconds (default: `60`) |
+| `sessionCheckExpiryDays` | `number` | No | Days before session check cookie expires (default: `1`) |
+| `httpTimeoutInSeconds` | `number` | No | HTTP request timeout (default: `10`) |
+| `issuer` | `string` | No | Override expected token issuer |
+
+### getTokenSilently Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `authorizationParams.audience` | `string` | Override audience for this token request |
+| `authorizationParams.scope` | `string` | Override scopes for this token request |
+| `cacheMode` | `'on' \| 'off' \| 'cache-only'` | Cache behavior (default: `'on'`) |
+| `detailedResponse` | `boolean` | Return `{ access_token, token_type, id_token, expires_in }` instead of string |
+| `timeoutInSeconds` | `number` | Override timeout for this call |
+
+---
+
+## Environment Variables
+
+| Bundler | Domain Variable | Client ID Variable |
+|---------|----------------|-------------------|
+| Vite | `VITE_AUTH0_DOMAIN` | `VITE_AUTH0_CLIENT_ID` |
+| Create React App | `REACT_APP_AUTH0_DOMAIN` | `REACT_APP_AUTH0_CLIENT_ID` |
+| Webpack (custom) | `AUTH0_DOMAIN` | `AUTH0_CLIENT_ID` |
+
+**Vite access:**
+```js
+import.meta.env.VITE_AUTH0_DOMAIN
+```
+
+**CRA access:**
+```js
+process.env.REACT_APP_AUTH0_DOMAIN
+```
+
+---
+
+## Error Types
+
+| Class | Import | When Thrown |
+|-------|--------|-------------|
+| `AuthenticationError` | `@auth0/auth0-spa-js` | `handleRedirectCallback` — Auth0 returned an error |
+| `GenericError` | `@auth0/auth0-spa-js` | Network or Auth0 API errors; base class for all SDK errors |
+| `TimeoutError` | `@auth0/auth0-spa-js` | Silent auth or network request timeout |
+| `PopupTimeoutError` | `@auth0/auth0-spa-js` | `loginWithPopup` — user didn't complete in time |
+| `PopupCancelledError` | `@auth0/auth0-spa-js` | `loginWithPopup` — popup was closed by the user |
+| `PopupOpenError` | `@auth0/auth0-spa-js` | `loginWithPopup` — `window.open` returned null (popups blocked) |
+| `MfaRequiredError` | `@auth0/auth0-spa-js` | `getTokenSilently` — MFA step required; access `error.mfa_token` |
+| `MissingRefreshTokenError` | `@auth0/auth0-spa-js` | `getTokenSilently` — refresh token not available |
+| `ConnectError` | `@auth0/auth0-spa-js` | `handleRedirectCallback` — error in connected accounts flow |
+| `MfaListAuthenticatorsError` | `@auth0/auth0-spa-js` | `auth0.mfa.getAuthenticators()` failed |
+| `MfaEnrollmentError` | `@auth0/auth0-spa-js` | `auth0.mfa.enroll()` failed |
+| `MfaChallengeError` | `@auth0/auth0-spa-js` | `auth0.mfa.challenge()` failed |
+| `MfaVerifyError` | `@auth0/auth0-spa-js` | `auth0.mfa.verify()` failed |
+
+---
+
+## Claims Reference
+
+Claims available from `auth0.getUser()` (ID token):
+
+| Claim | Type | Description |
+|-------|------|-------------|
+| `sub` | `string` | Subject — unique user ID: `auth0\|64abc...` |
+| `name` | `string` | Full name |
+| `given_name` | `string` | First name |
+| `family_name` | `string` | Last name |
+| `nickname` | `string` | Nickname or username |
+| `email` | `string` | Email address |
+| `email_verified` | `boolean` | Whether email is verified |
+| `picture` | `string` | Profile picture URL |
+| `locale` | `string` | User locale |
+| `updated_at` | `string` | Last profile update ISO timestamp |
+
+Claims on the **access token** (from `getTokenSilently({ detailedResponse: true })`):
+
+| Claim | Description |
+|-------|-------------|
+| `iss` | Issuer — your Auth0 domain URL |
+| `aud` | Audience — API identifier(s) |
+| `azp` | Authorized party — your Client ID |
+| `scope` | Space-separated scopes granted |
+| `permissions` | RBAC permissions array (requires API audience + Auth0 RBAC enabled) |
+| `org_id` | Organization ID for multi-tenant apps |
+
+---
+
+## Testing Checklist
+
+### Core Authentication
+
+- [ ] Login redirect sends user to Auth0 Universal Login page
+- [ ] After login, user is returned to app (no dangling `code=` params in URL)
+- [ ] `auth0.isAuthenticated()` returns `true` after successful login
+- [ ] `auth0.getUser()` returns profile with `sub`, `name`, `email`
+- [ ] Logout clears session and redirects to `returnTo` URL
+- [ ] After logout, `isAuthenticated()` returns `false`
+
+### Token Management
+
+- [ ] `getTokenSilently()` returns a JWT string
+- [ ] Access token decoded at [jwt.io](https://jwt.io) shows correct `aud`, `iss`, `sub`
+- [ ] Tokens are **not** stored in `localStorage` (DevTools → Application → Local Storage)
+- [ ] Page refresh maintains authentication (silent auth via `checkSession`)
+- [ ] `getTokenSilently()` works without redirecting when session is active
+
+### Error Handling
+
+- [ ] Navigating to app when not logged in does not throw uncaught errors
+- [ ] `login_required` error on `getTokenSilently` triggers re-authentication
+- [ ] Network failure in `getTokenSilently` is caught and handled gracefully
+
+### Security
+
+- [ ] Auth0 Dashboard: Application type is **Single Page Application**
+- [ ] Auth0 Dashboard: Token Endpoint Auth Method is **None**
+- [ ] Auth0 Dashboard: Allowed Web Origins includes your app origin
+- [ ] No `client_secret` anywhere in source code or `.env`
+- [ ] Dev `.env` file is in `.gitignore`
+
+---
+
+## Common Issues
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `login_required` on `getTokenSilently` | Allowed Web Origins not configured | Add `http://localhost:5173` to Allowed Web Origins in Auth0 Dashboard |
+| `invalid_client` | Wrong Client ID | Check env var matches Auth0 Dashboard Client ID |
+| Callback URL mismatch error | Port mismatch between app and Dashboard | Match exactly: `http://localhost:5173` in both places |
+| `Unable to open popup` | Popup not triggered by user gesture | Call `loginWithPopup` directly in a click handler, never from async init |
+| Token not refreshing silently | `offline_access` scope missing | Add `scope: 'openid profile email offline_access'` with `useRefreshTokens: true` |
+| `MissingRefreshTokenError` | `useRefreshTokens` false or scope missing | Enable `useRefreshTokens: true` and include `offline_access` scope |
+| User logged out on page refresh | Allowed Web Origins missing or no refresh tokens | Add Allowed Web Origins; enable `useRefreshTokens: true` |
+| Cross-origin iframe blocked | Browser blocks third-party cookies | Use `useRefreshTokens: true` instead of silent iframe auth |
+| Domain includes protocol | `domain` option should not include `https://` | Use `your-tenant.auth0.com` not `https://your-tenant.auth0.com` |
+
+---
+
+## Security Considerations
+
+### Token Storage
+
+| Strategy | Security | Session Persistence |
+|----------|----------|-------------------|
+| In-memory (default) | Highest — no persistent token theft | Lost on page refresh |
+| Refresh tokens (`useRefreshTokens: true`) | High — refresh token in memory | Persists across page refreshes |
+| `localStorage` | Lowest — vulnerable to XSS | Persists across page refreshes |
+
+**Recommendation:** Use `useRefreshTokens: true` with `cacheLocation: 'memory'` (the default) for the best balance of security and user experience.
+
+### No Client Secret
+
+SPAs run entirely in the browser and cannot protect secrets. The Auth0 SPA application type explicitly disables client secret authentication. Never add `client_secret` to a browser-based application.
+
+### PKCE Flow
+
+`@auth0/auth0-spa-js` always uses the Authorization Code + PKCE (Proof Key for Code Exchange) flow. This protects against authorization code interception and is the only secure OAuth 2.0 flow for browser-based applications.
+
+### Content Security Policy
+
+If you need to restrict iframe origins (only relevant when NOT using `useRefreshTokens`):
+```
+Content-Security-Policy: frame-src https://your-tenant.auth0.com;
+```
+
+### XSS Protection
+
+Never use `cacheLocation: 'localstorage'` in production unless you have fully mitigated all XSS risks. XSS can steal tokens from `localStorage`. Instead, use the default in-memory cache: it is the safer default because it avoids persistent token theft (tokens are gone once the tab closes), though XSS running in the authenticated app context can still act on tokens held in memory during the session.
+
+---
+
+# Auth0 SPA JS Integration Patterns
+
+---
+
+## Client Initialization
+
+### Using createAuth0Client (Recommended)
+
+`createAuth0Client` initializes the client and automatically calls `checkSession()` to restore any existing session:
+
+```js
+import { createAuth0Client } from '@auth0/auth0-spa-js';
+
+const auth0 = await createAuth0Client({
+  domain: import.meta.env.VITE_AUTH0_DOMAIN,
+  clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+  authorizationParams: {
+    redirect_uri: window.location.origin
+  }
+});
+```
+
+### Using Auth0Client Directly
+
+Use when you need more control over initialization order:
+
+```js
+import { Auth0Client } from '@auth0/auth0-spa-js';
+
+const auth0 = new Auth0Client({
+  domain: import.meta.env.VITE_AUTH0_DOMAIN,
+  clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+  authorizationParams: {
+    redirect_uri: window.location.origin
+  }
+});
+
+// Manually check existing session
+try {
+  await auth0.getTokenSilently();
+} catch (error) {
+  if (error.error !== 'login_required') {
+    throw error;
+  }
+}
+```
+
+---
+
+## Login
+
+### Login with Redirect
+
+```js
+// Basic redirect login
+await auth0.loginWithRedirect();
+
+// With additional parameters
+await auth0.loginWithRedirect({
+  authorizationParams: {
+    audience: 'https://api.example.com',
+    scope: 'openid profile email read:data'
+  }
+});
+```
+
+### Handle Redirect Callback
+
+Call this on page load to process the redirect result after Auth0 returns the user:
+
+```js
+const query = new URLSearchParams(window.location.search);
+if ((query.has('code') || query.has('error')) && query.has('state')) {
+  try {
+    const result = await auth0.handleRedirectCallback();
+    // result.appState contains data you passed via loginWithRedirect
+    console.log('App state:', result.appState);
+  } catch (err) {
+    console.error('Redirect callback failed:', err);
+  }
+  // Clean up URL after processing
+  window.history.replaceState({}, document.title, window.location.pathname);
+}
+```
+
+### Login with Popup
+
+Use when you want to avoid a full-page redirect (must be triggered directly by a user click):
+
+```js
+document.getElementById('login-popup-btn').addEventListener('click', async () => {
+  try {
+    await auth0.loginWithPopup();
+    const user = await auth0.getUser();
+    console.log('Logged in:', user.name);
+  } catch (err) {
+    if (err.error !== 'popup_cancelled') {
+      console.error('Popup login failed:', err);
+    }
+  }
+});
+```
+
+---
+
+## Logout
+
+```js
+// Logout and return to app origin
+auth0.logout({
+  logoutParams: {
+    returnTo: window.location.origin
+  }
+});
+
+// Logout without redirect (clear local session only)
+auth0.logout({ openUrl: false });
+
+// Logout and redirect to custom URL
+auth0.logout({
+  logoutParams: {
+    returnTo: 'https://your-app.example.com/logged-out'
+  }
+});
+```
+
+---
+
+## User Profile
+
+```js
+// Check authentication state
+const isAuthenticated = await auth0.isAuthenticated();
+
+// Get user profile (returns undefined if not authenticated)
+const user = await auth0.getUser();
+if (user) {
+  console.log(user.sub);       // Auth0 user ID
+  console.log(user.name);      // Full name
+  console.log(user.email);     // Email address
+  console.log(user.picture);   // Profile picture URL
+  console.log(user.email_verified); // Boolean
+}
+```
+
+---
+
+## Protecting Content
+
+Show/hide content based on authentication state:
+
+```js
+async function updateUI() {
+  const isAuthenticated = await auth0.isAuthenticated();
+
+  // Toggle login/logout buttons
+  document.getElementById('btn-login').style.display = isAuthenticated ? 'none' : 'block';
+  document.getElementById('btn-logout').style.display = isAuthenticated ? 'block' : 'none';
+
+  // Show user profile section
+  const profileSection = document.getElementById('profile');
+  if (profileSection) {
+    profileSection.style.display = isAuthenticated ? 'block' : 'none';
+  }
+
+  if (isAuthenticated) {
+    const user = await auth0.getUser();
+    document.getElementById('user-name').textContent = user.name;
+    document.getElementById('user-email').textContent = user.email;
+    if (document.getElementById('user-picture')) {
+      document.getElementById('user-picture').src = user.picture;
+    }
+  }
+}
+
+// Call on page load and after auth state changes
+await updateUI();
+```
+
+---
+
+## Calling Protected APIs
+
+```js
+// Get access token silently (uses cache first, refreshes if expired)
+async function callApi(url) {
+  const accessToken = await auth0.getTokenSilently();
+
+  const response = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${accessToken}`
+    }
+  });
+
+  if (!response.ok) {
+    throw new Error(`API error: ${response.status}`);
+  }
+
+  return response.json();
+}
+
+// Usage
+document.getElementById('call-api-btn').addEventListener('click', async () => {
+  try {
+    const data = await callApi('https://your-api.example.com/private');
+    document.getElementById('result').textContent = JSON.stringify(data, null, 2);
+  } catch (err) {
+    console.error('API call failed:', err);
+  }
+});
+```
+
+### Get Detailed Token Response
+
+```js
+const { access_token, token_type, id_token, expires_in } = await auth0.getTokenSilently({
+  detailedResponse: true
+});
+```
+
+### Token for a Specific Audience
+
+```js
+const token = await auth0.getTokenSilently({
+  authorizationParams: {
+    audience: 'https://api.example.com',
+    scope: 'read:data write:data'
+  }
+});
+```
+
+---
+
+## Refresh Token Rotation
+
+Enable to maintain sessions across page refreshes without relying on third-party cookies (recommended for modern browsers):
+
+```js
+const auth0 = await createAuth0Client({
+  domain: import.meta.env.VITE_AUTH0_DOMAIN,
+  clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+  useRefreshTokens: true,
+  authorizationParams: {
+    redirect_uri: window.location.origin,
+    scope: 'openid profile email offline_access'  // offline_access required
+  }
+});
+```
+
+> **Note:** Enable **Allow Offline Access** on your Auth0 API in the Dashboard for `offline_access` scope to work.
+
+---
+
+## Organizations
+
+### Login to a Specific Organization
+
+```js
+await auth0.loginWithRedirect({
+  authorizationParams: {
+    organization: 'org_xxxxxxxxxxxx'  // or organization name
+  }
+});
+```
+
+### Initialize Client with Organization
+
+```js
+const auth0 = await createAuth0Client({
+  domain: import.meta.env.VITE_AUTH0_DOMAIN,
+  clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+  authorizationParams: {
+    redirect_uri: window.location.origin,
+    organization: 'org_xxxxxxxxxxxx'
+  }
+});
+```
+
+### Switch Organizations
+
+```js
+async function switchOrganization(orgId) {
+  await auth0.logout({ openUrl: false });
+  await auth0.loginWithRedirect({
+    authorizationParams: { organization: orgId }
+  });
+}
+```
+
+### Accept User Invitations
+
+```js
+const url = new URL(window.location.href);
+const organization = url.searchParams.get('organization');
+const invitation = url.searchParams.get('invitation');
+
+if (organization && invitation) {
+  await auth0.loginWithRedirect({
+    authorizationParams: { organization, invitation }
+  });
+}
+```
+
+---
+
+## MFA Handling
+
+Handle MFA when `getTokenSilently()` requires a second factor:
+
+```js
+import { MfaRequiredError } from '@auth0/auth0-spa-js';
+
+try {
+  const token = await auth0.getTokenSilently();
+} catch (error) {
+  if (error instanceof MfaRequiredError) {
+    // Trigger MFA challenge via popup or redirect
+    await auth0.loginWithPopup({
+      authorizationParams: {
+        mfa_token: error.mfa_token
+      }
+    });
+  }
+}
+```
+
+---
+
+## DPoP (Device-Bound Tokens)
+
+Enable DPoP to bind access tokens to the client's cryptographic key pair:
+
+```js
+const auth0 = await createAuth0Client({
+  domain: import.meta.env.VITE_AUTH0_DOMAIN,
+  clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+  useDpop: true,
+  authorizationParams: {
+    redirect_uri: window.location.origin
+  }
+});
+
+// Use createFetcher to automatically handle DPoP proof generation
+const fetcher = auth0.createFetcher({ dpopNonceId: 'my_api' });
+
+const response = await fetcher.fetchWithAuth('https://api.example.com/data', {
+  method: 'GET'
+});
+```
+
+---
+
+## Error Handling
+
+```js
+import {
+  AuthenticationError,
+  GenericError,
+  TimeoutError,
+  PopupTimeoutError,
+  PopupCancelledError,
+  PopupOpenError,
+  MfaRequiredError,
+  MissingRefreshTokenError
+} from '@auth0/auth0-spa-js';
+
+// Handle redirect callback errors
+try {
+  await auth0.handleRedirectCallback();
+} catch (err) {
+  if (err instanceof AuthenticationError) {
+    // Auth0 returned an error in the callback (e.g., access_denied)
+    console.error('Auth error:', err.error, err.error_description);
+  } else {
+    console.error('Unexpected error:', err);
+  }
+}
+
+// Handle token errors
+try {
+  const token = await auth0.getTokenSilently();
+} catch (err) {
+  if (err.error === 'login_required') {
+    // User needs to log in — redirect to login
+    await auth0.loginWithRedirect();
+  } else if (err instanceof MissingRefreshTokenError) {
+    // Refresh token missing — user needs to re-authenticate
+    await auth0.loginWithRedirect();
+  } else if (err instanceof TimeoutError) {
+    console.error('Request timed out');
+  } else {
+    console.error('Token error:', err);
+  }
+}
+
+// Handle popup errors
+try {
+  await auth0.loginWithPopup();
+} catch (err) {
+  if (err instanceof PopupOpenError) {
+    console.error('Popups are blocked. Please allow popups for this site.');
+  } else if (err instanceof PopupCancelledError) {
+    console.log('User closed the popup');
+  } else if (err instanceof PopupTimeoutError) {
+    console.error('Popup timed out');
+  }
+}
+```
+
+---
+
+## Authentication Flow
+
+```
+User clicks Login
+      ↓
+auth0.loginWithRedirect()
+      ↓
+Browser redirects to Auth0 Universal Login
+      ↓
+User enters credentials / social login
+      ↓
+Auth0 redirects back to redirect_uri?code=xxx&state=xxx
+      ↓
+auth0.handleRedirectCallback() — exchanges code for tokens
+      ↓
+Tokens stored in memory (or refresh token if useRefreshTokens: true)
+      ↓
+auth0.isAuthenticated() → true
+auth0.getUser() → user profile
+auth0.getTokenSilently() → access token
+```
+
+---
+
+## Testing Patterns
+
+### Test Authentication State
+
+```js
+describe('Auth0 integration', () => {
+  it('should show login button when not authenticated', async () => {
+    const isAuthenticated = await auth0.isAuthenticated();
+    expect(isAuthenticated).toBe(false);
+    expect(document.getElementById('btn-login').style.display).toBe('block');
+  });
+});
+```
+
+### Mock Auth0 Client in Tests
+
+```js
+// Vitest / Jest
+vi.mock('@auth0/auth0-spa-js', () => ({
+  createAuth0Client: vi.fn().mockResolvedValue({
+    isAuthenticated: vi.fn().mockResolvedValue(true),
+    getUser: vi.fn().mockResolvedValue({ name: 'Test User', email: 'test@example.com' }),
+    loginWithRedirect: vi.fn(),
+    logout: vi.fn(),
+    getTokenSilently: vi.fn().mockResolvedValue('mock-access-token'),
+    handleRedirectCallback: vi.fn().mockResolvedValue({ appState: null })
+  })
+}));
+```
+
+---
+
+# Auth0 SPA JS Setup Guide
+
+Complete setup instructions with automated scripts and manual configuration options.
+
+---
+
+## Quick Setup (Automated)
+
+**Never read the contents of `.env` at any point during setup.** The file may contain sensitive secrets that should not be exposed in the LLM context. If you determine you need to read the file for any reason, ask the user for explicit permission before doing so — do not proceed until the user confirms.
+
+**Before running any part of this setup that writes to `.env`, you must ask the user for explicit confirmation.** Follow the steps below precisely.
+
+### Step 1: Check for existing .env and confirm with user
+
+Before writing to `.env`, check whether the file already exists:
+
+```bash
+test -f .env && echo "EXISTS" || echo "NOT_FOUND"
+```
+
+Then ask the user for explicit confirmation before proceeding — do not continue until the user confirms:
+
+- If `.env` does **not** exist, ask:
+  - Question: "This setup will create a `.env` file containing Auth0 credentials (domain and client ID). Do you want to proceed?"
+  - Options: "Yes, create .env" / "No, I'll configure it manually"
+
+- If `.env` **already exists**, ask:
+  - Question: "A `.env` file already exists and may contain secrets unrelated to Auth0. This setup will append Auth0 credentials to it without modifying existing content. Do you want to proceed?"
+  - Options: "Yes, append to existing .env" / "No, I'll update it manually"
+
+**Do not proceed with writing to `.env` unless the user selects the confirmation option.**
+
+### Step 2: Run automated setup (only after confirmation)
+
+#### Bash Script (macOS/Linux)
+
+```bash
+#!/bin/bash
+
+# Install Auth0 CLI if needed
+if ! command -v auth0 &> /dev/null; then
+  echo "Installing Auth0 CLI..."
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    brew install auth0/auth0-cli/auth0
+  elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b /usr/local/bin
+  else
+    echo "Please install Auth0 CLI: https://github.com/auth0/auth0-cli#installation"
+    exit 1
+  fi
+fi
+
+# Check if logged in to Auth0
+if ! auth0 tenants list &> /dev/null; then
+  echo ""
+  echo "======================================"
+  echo "Auth0 Login Required"
+  echo "======================================"
+  read -p "Do you have an Auth0 account? (y/n): " HAS_ACCOUNT
+
+  if [[ "$HAS_ACCOUNT" != "y" ]]; then
+    echo ""
+    echo "Create a free account at: https://auth0.com/signup"
+    read -p "Press Enter when you've created your account..."
+  fi
+
+  auth0 login
+  if ! auth0 tenants list &> /dev/null; then
+    echo "❌ Login failed. Please try again."
+    exit 1
+  fi
+  echo "✅ Successfully logged in to Auth0!"
+fi
+
+# Detect env var prefix from project
+if grep -q '"vite"' package.json 2>/dev/null; then
+  PREFIX="VITE_AUTH0"
+elif grep -q '"react-scripts"' package.json 2>/dev/null; then
+  PREFIX="REACT_APP_AUTH0"
+else
+  PREFIX="VITE_AUTH0"  # Default to Vite
+fi
+
+# List apps and prompt for selection
+echo "Your Auth0 applications:"
+auth0 apps list
+
+read -p "Enter your Auth0 app ID (or press Enter to create a new one): " APP_ID
+
+if [ -z "$APP_ID" ]; then
+  echo "Creating new Auth0 SPA application..."
+  APP_NAME="${PWD##*/}-spa"
+  APP_ID=$(auth0 apps create \
+    --name "$APP_NAME" \
+    --type spa \
+    --auth-method None \
+    --callbacks "http://localhost:3000,http://localhost:5173" \
+    --logout-urls "http://localhost:3000,http://localhost:5173" \
+    --origins "http://localhost:3000,http://localhost:5173" \
+    --web-origins "http://localhost:3000,http://localhost:5173" \
+    --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+  echo "Created SPA app with ID: $APP_ID"
+fi
+
+# Get app details
+AUTH0_DOMAIN=$(auth0 apps show "$APP_ID" --json | grep -o '"domain":"[^"]*' | cut -d'"' -f4)
+AUTH0_CLIENT_ID=$(auth0 apps show "$APP_ID" --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+
+# Append to .env
+cat >> .env << EOF
+${PREFIX}_DOMAIN=$AUTH0_DOMAIN
+${PREFIX}_CLIENT_ID=$AUTH0_CLIENT_ID
+EOF
+
+echo "✅ Auth0 configuration complete!"
+echo "Appended to .env:"
+echo "  ${PREFIX}_DOMAIN=$AUTH0_DOMAIN"
+echo "  ${PREFIX}_CLIENT_ID=$AUTH0_CLIENT_ID"
+```
+
+#### PowerShell Script (Windows)
+
+```powershell
+# Install Auth0 CLI if not present
+if (!(Get-Command auth0 -ErrorAction SilentlyContinue)) {
+  Write-Host "Installing Auth0 CLI..."
+  scoop install auth0
+}
+
+# Check if logged in
+try {
+  auth0 tenants list | Out-Null
+} catch {
+  Write-Host "Auth0 Login Required"
+  $hasAccount = Read-Host "Do you have an Auth0 account? (y/n)"
+
+  if ($hasAccount -ne "y") {
+    Write-Host "Create a free account at: https://auth0.com/signup"
+    Read-Host "Press Enter when you've created your account"
+  }
+
+  auth0 login
+  Write-Host "✅ Successfully logged in to Auth0!"
+}
+
+# Detect env var prefix
+$prefix = if (Select-String -Path "package.json" -Pattern '"vite"' -Quiet) { "VITE_AUTH0" }
+          elseif (Select-String -Path "package.json" -Pattern '"react-scripts"' -Quiet) { "REACT_APP_AUTH0" }
+          else { "VITE_AUTH0" }
+
+# List and select app
+Write-Host "Your Auth0 applications:"
+auth0 apps list
+
+$appId = Read-Host "Enter your Auth0 app ID (or press Enter to create new)"
+
+if ([string]::IsNullOrEmpty($appId)) {
+  $appName = Split-Path -Leaf (Get-Location)
+  Write-Host "Creating new Auth0 SPA application..."
+  $appJson = auth0 apps create --name "$appName-spa" --type spa `
+    --auth-method None `
+    --callbacks "http://localhost:3000,http://localhost:5173" `
+    --logout-urls "http://localhost:3000,http://localhost:5173" `
+    --origins "http://localhost:3000,http://localhost:5173" `
+    --web-origins "http://localhost:3000,http://localhost:5173" `
+    --json
+
+  $appId = ($appJson | ConvertFrom-Json).client_id
+  Write-Host "Created app with ID: $appId"
+}
+
+# Get credentials
+$appDetails = auth0 apps show $appId --json | ConvertFrom-Json
+
+@"
+${prefix}_DOMAIN=$($appDetails.domain)
+${prefix}_CLIENT_ID=$($appDetails.client_id)
+"@ | Out-File -FilePath .env -Encoding UTF8 -Append
+
+Write-Host "✅ Auth0 configuration complete!"
+Write-Host "  ${prefix}_DOMAIN=$($appDetails.domain)"
+Write-Host "  ${prefix}_CLIENT_ID=$($appDetails.client_id)"
+```
+
+---
+
+## Manual Setup
+
+If you prefer manual setup or the scripts don't work:
+
+### Step 1: Install SDK
+
+```bash
+npm install @auth0/auth0-spa-js
+```
+
+### Step 2: Install Auth0 CLI
+
+**macOS:**
+```bash
+brew install auth0/auth0-cli/auth0
+```
+
+**Linux:**
+```bash
+curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh
+```
+
+**Windows:**
+```powershell
+scoop install auth0
+```
+
+### Step 3: Get Credentials
+
+```bash
+# Login to Auth0
+auth0 login
+
+# List your apps
+auth0 apps list
+
+# Get app details (replace <app-id>)
+auth0 apps show <app-id>
+```
+
+### Step 4: Create .env File
+
+**For Vite-based projects:**
+```bash
+VITE_AUTH0_DOMAIN=your-tenant.auth0.com
+VITE_AUTH0_CLIENT_ID=your-client-id
+```
+
+**For Create React App:**
+```bash
+REACT_APP_AUTH0_DOMAIN=your-tenant.auth0.com
+REACT_APP_AUTH0_CLIENT_ID=your-client-id
+```
+
+**For Webpack / plain HTML:**
+```bash
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_CLIENT_ID=your-client-id
+```
+
+---
+
+## Creating an Auth0 Application via Dashboard
+
+1. Go to [Auth0 Dashboard](https://manage.auth0.com)
+2. Navigate to **Applications** → **Applications**
+3. Click **Create Application**
+4. Choose:
+   - Name: Your app name
+   - Type: **Single Page Web Applications**
+5. Configure in the **Settings** tab:
+   - **Allowed Callback URLs**: `http://localhost:5173, http://localhost:3000`
+   - **Allowed Logout URLs**: `http://localhost:5173, http://localhost:3000`
+   - **Allowed Web Origins**: `http://localhost:5173, http://localhost:3000`
+   - **Allowed Origins (CORS)**: `http://localhost:5173, http://localhost:3000`
+6. Click **Save Changes**
+7. Copy your **Domain** and **Client ID**
+
+> **Important:** The **Allowed Web Origins** field is required for `getTokenSilently()` (silent authentication). Without it, users will be logged out on every page refresh.
+
+---
+
+## Secret Management
+
+SPAs do **not** use a `client_secret`. The Auth0 SPA application type explicitly sets the Token Endpoint Authentication Method to `None`. If you see a client secret anywhere in your code, remove it immediately.
+
+Your `.env` file contains only:
+- `AUTH0_DOMAIN` / `VITE_AUTH0_DOMAIN` — Not a secret (public)
+- `AUTH0_CLIENT_ID` / `VITE_AUTH0_CLIENT_ID` — Not a secret (public)
+
+Still, follow these practices:
+- Add `.env` to `.gitignore` (to avoid accidental commits with other sensitive env vars)
+- Use `.env.local` for Vite projects (auto-ignored by Vite's default `.gitignore`)
+- Never commit credential files to version control
+
+---
+
+## Troubleshooting Setup
+
+### Environment Variables Not Loading
+
+**Vite:**
+- Ensure variables start with `VITE_`
+- Restart the dev server after creating/editing `.env`
+- Use `import.meta.env.VITE_AUTH0_DOMAIN` (not `process.env`)
+
+**Create React App:**
+- Ensure variables start with `REACT_APP_`
+- Restart dev server after changes
+
+### Auth0 CLI Issues
+
+**Browser doesn't open for login:**
+```bash
+auth0 login --no-browser
+```
+
+**"Not logged in" error:**
+```bash
+auth0 login --force
+```
+
+---
+
+## Next Steps
+
+After setup is complete:
+1. Return to the main skill guide for integration steps
diff --git a/main/.mintlify/skills/auth0/references/framework-springboot-api/index.md b/main/.mintlify/skills/auth0/references/framework-springboot-api/index.md
new file mode 100644
index 0000000000..55b5e60d38
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-springboot-api/index.md
@@ -0,0 +1,1180 @@
+
+# Auth0 Spring Boot API Integration
+
+Protect Spring Boot API endpoints with JWT access token validation using `com.auth0:auth0-springboot-api`. Features auto-configuration, scope-based authorization, and built-in DPoP (RFC 9449) support.
+
+## Critical rules
+
+- **DPoP `dpop-mode`:** `ALLOWED` accepts both Bearer and DPoP tokens; `REQUIRED` accepts only DPoP tokens and rejects standard Bearer; `DISABLED` accepts standard Bearer only. Pick the mode deliberately — `REQUIRED` will 401 any plain Bearer request. See the DPoP Authentication section for full config.
+
+> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
+> ```bash
+> gh api repos/auth0/auth0-auth-java/releases/latest --jq '.tag_name'
+> ```
+> Use the returned version in all dependency lines instead of any hardcoded version below. If the API call fails (e.g., no releases yet), use `1.0.0-beta.1`.
+
+## Prerequisites
+
+- Java 17+ and Spring Boot 3.2+
+- Maven 3.6+ or Gradle 7+
+- Auth0 API configured (not Application — must be API resource)
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+| Use Case | Use Instead |
+|----------|------------------|
+| Server-rendered web applications (Spring MVC with sessions) | Use the Auth0 integration workflow for Spring Boot web apps with login UI (Regular Web Application) |
+| Single Page Applications | Use the Auth0 integration workflow for React, Vue, or Angular for client-side auth |
+| Mobile applications | Use the Auth0 integration workflow for Android or iOS/Swift for native mobile |
+| Non-Spring Java APIs | Use the Auth0 integration workflow for plain Spring Security |
+
+## Quick Start Workflow
+
+> **Agent instruction:** If the user's prompt already provides Auth0 credentials (domain, audience), use them directly — skip automatic setup and credential questions. Only offer setup options when credentials are missing.
+
+### 1. Install SDK
+
+**Gradle (build.gradle):**
+
+```groovy
+implementation 'com.auth0:auth0-springboot-api:1.0.0-beta.1'
+```
+
+**Maven (pom.xml):**
+
+```xml
+<dependency>
+    <groupId>com.auth0</groupId>
+    <artifactId>auth0-springboot-api</artifactId>
+    <version>1.0.0-beta.1</version>
+</dependency>
+```
+
+### 2. Create Auth0 API
+
+You need an **API** (not Application) in Auth0.
+
+> **STOP — ask the user before proceeding.**
+>
+> Ask exactly this question and wait for their answer before doing anything else:
+>
+> > "How would you like to create the Auth0 API resource?
+> > 1. **Automated** — I'll run Auth0 CLI scripts that create the resource and write the values to your application.yml automatically.
+> > 2. **Manual** — You create the API yourself in the Auth0 Dashboard (or via `auth0 apis create`) and provide me the Domain and Audience.
+> >
+> > Which do you prefer? (1 = Automated / 2 = Manual)"
+>
+> Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.
+
+**If the user chose Automated**, follow the Setup Guide section below for complete CLI scripts. The automated path writes `application.yml` for you — skip Step 3 below and proceed directly to Step 4.
+
+**If the user chose Manual**, follow the Setup Guide section below (Manual Setup). Then continue with Step 3.
+
+Quick reference for manual API creation:
+
+```bash
+# Using Auth0 CLI
+auth0 apis create \
+  --name "My Spring Boot API" \
+  --identifier https://my-springboot-api
+```
+
+Or create manually in Auth0 Dashboard → Applications → APIs
+
+### 3. Configure application.yml
+
+```yaml
+auth0:
+  domain: "your-tenant.auth0.com"
+  audience: "https://my-springboot-api"
+```
+
+**Important:** Domain must NOT include `https://`. The library constructs the issuer URL automatically.
+
+Or use `application.properties`:
+
+```properties
+auth0.domain=your-tenant.auth0.com
+auth0.audience=https://my-springboot-api
+```
+
+### 4. Configure Spring Security
+
+```java
+@Configuration
+@EnableMethodSecurity
+public class SecurityConfig {
+
+    @Bean
+    SecurityFilterChain apiSecurity(
+            HttpSecurity http,
+            Auth0AuthenticationFilter authFilter
+    ) throws Exception {
+        return http
+            .csrf(csrf -> csrf.disable())
+            .sessionManagement(session ->
+                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/api/public").permitAll()
+                .requestMatchers("/api/protected").authenticated()
+                .requestMatchers("/api/admin/**").hasAuthority("SCOPE_admin")
+                .anyRequest().authenticated())
+            .addFilterBefore(authFilter, UsernamePasswordAuthenticationFilter.class)
+            .build();
+    }
+}
+```
+
+### 5. Protect Endpoints
+
+```java
+@RestController
+@RequestMapping("/api")
+public class ApiController {
+
+    @GetMapping("/public")
+    public ResponseEntity<Map<String, Object>> publicEndpoint() {
+        return ResponseEntity.ok(Map.of("message", "Public endpoint - no token required"));
+    }
+
+    @GetMapping("/protected")
+    public ResponseEntity<Map<String, Object>> protectedEndpoint(Authentication authentication) {
+        Auth0AuthenticationToken token = (Auth0AuthenticationToken) authentication;
+        return ResponseEntity.ok(Map.of(
+            "user", authentication.getName(),
+            "email", token.getClaim("email"),
+            "scopes", token.getScopes()
+        ));
+    }
+}
+```
+
+### 6. Test API
+
+> **Agent instruction:** After writing all code, verify the build succeeds:
+> ```bash
+> ./gradlew bootRun
+> ```
+> or `./mvnw spring-boot:run`. If build fails, diagnose and fix. After 5-6 failed attempts, use `AskUserQuestion` to get help.
+
+Test public endpoint:
+
+```bash
+curl http://localhost:8080/api/public
+```
+
+Test protected endpoint (requires access token):
+
+```bash
+curl http://localhost:8080/api/protected \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+```
+
+Get a test token via Client Credentials flow or Auth0 Dashboard → APIs → Test tab.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Domain includes `https://` | Use `your-tenant.auth0.com` format only — no scheme prefix |
+| Audience doesn't match API Identifier | Must exactly match the API Identifier set in Auth0 Dashboard |
+| Created Application instead of API in Auth0 | Must create API resource in Auth0 Dashboard → Applications → APIs |
+| Missing `addFilterBefore` in SecurityConfig | `Auth0AuthenticationFilter` must be added before `UsernamePasswordAuthenticationFilter` |
+| Using ID token instead of access token | Must use **access token** for API auth, not ID token |
+| Checking `scope` claim in wrong format | Scopes map to `SCOPE_` prefixed authorities: use `hasAuthority("SCOPE_read:data")` |
+| Spring Boot env var binding | Use `AUTH0_DOMAIN` not `AUTH0_DOMAIN` with underscores inside property names; Spring removes dashes and is case-insensitive |
+
+## Scope-Based Authorization
+
+See the Integration Guide section below for defining and enforcing scope-based access control via filter chain, `@PreAuthorize`, or programmatic checks.
+
+## DPoP Support
+
+Built-in proof-of-possession token binding per RFC 9449. See the Integration Guide section below for configuration modes (DISABLED, ALLOWED, REQUIRED).
+
+## Related Capabilities
+
+- Basic Auth0 setup and account creation → set it up with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Spring Boot web apps with login UI (Regular Web Application) → the Auth0 integration workflow for Spring Boot web apps
+
+## Quick Reference
+
+**Configuration Properties (`application.yml`):**
+- `auth0.domain` — Auth0 tenant domain, no `https://` prefix (required)
+- `auth0.audience` — API Identifier from Auth0 API settings (required)
+- `auth0.dpop-mode` — DPoP mode: `DISABLED`, `ALLOWED` (default), `REQUIRED`
+- `auth0.dpop-iat-offset-seconds` — DPoP proof time window (default: 300)
+- `auth0.dpop-iat-leeway-seconds` — DPoP proof time leeway (default: 30)
+
+**User Claims (via `Auth0AuthenticationToken`):**
+- `authentication.getName()` — User ID (subject / `sub` claim)
+- `token.getClaim("email")` — Any specific claim by name
+- `token.getClaims()` — All JWT claims as `Map<String, Object>`
+- `token.getScopes()` — Scopes as `Set<String>`
+
+**Common Use Cases:**
+- Protect routes → `requestMatchers("/path").authenticated()` (see Step 4)
+- Scope enforcement → `hasAuthority("SCOPE_read:data")` or `@PreAuthorize` (see the Integration Guide section below)
+- DPoP token binding → see the Integration Guide section below
+- Complete API reference → see the API Reference section below
+
+## References
+
+- [Auth0 Java Spring Security API Quickstart](https://auth0.com/docs/quickstart/backend/java-spring-security5)
+- [SDK GitHub Repository](https://github.com/auth0/auth0-auth-java)
+- [Spring Security Documentation](https://docs.spring.io/spring-security/reference/)
+- [Access Tokens Guide](https://auth0.com/docs/secure/tokens/access-tokens)
+- [DPoP RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449)
+
+---
+
+# API Reference & Testing
+
+Complete reference for `com.auth0:auth0-springboot-api` configuration options and auto-configuration classes.
+
+---
+
+## Configuration Reference
+
+### application.yml Properties
+
+```yaml
+auth0:
+  domain: "your-tenant.auth0.com"        # Required: Auth0 tenant domain (no https://)
+  audience: "https://api.example.com"     # Required: API identifier / audience
+  dpop-mode: ALLOWED                      # Optional: DISABLED | ALLOWED | REQUIRED (default: ALLOWED)
+  dpop-iat-offset-seconds: 300            # Optional: DPoP proof time window (default: 300)
+  dpop-iat-leeway-seconds: 30             # Optional: DPoP proof time leeway (default: 30)
+```
+
+### application.properties Equivalent
+
+```properties
+auth0.domain=your-tenant.auth0.com
+auth0.audience=https://api.example.com
+auth0.dpopMode=ALLOWED
+auth0.dpopIatOffsetSeconds=300
+auth0.dpopIatLeewaySeconds=30
+```
+
+### Environment Variables
+
+```bash
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_AUDIENCE=https://api.example.com
+AUTH0_DPOPMODE=ALLOWED
+AUTH0_DPOPIATOFFSETSECONDS=300
+AUTH0_DPOPIATLEEWAYSECONDS=30
+```
+
+> **Note:** Spring Boot environment variable binding removes dashes and is case-insensitive. Do not use underscores to separate words within a property name (e.g., use `AUTH0_DPOPMODE`, not `AUTH0_DPOP_MODE`).
+
+---
+
+## Auth0Properties
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `domain` | `String` | Yes | — | Auth0 tenant domain. Format: `your-tenant.auth0.com` (no `https://` prefix) |
+| `audience` | `String` | Yes | — | API Identifier from Auth0 Dashboard |
+| `dpopMode` | `DPoPMode` | No | `ALLOWED` | Controls which token types are accepted |
+| `dpopIatOffsetSeconds` | `Long` | No | `300` | Maximum age of DPoP proof `iat` claim in seconds |
+| `dpopIatLeewaySeconds` | `Long` | No | `30` | Additional leeway for DPoP proof time validation |
+| `domains` | `List<String>` | No | — | Additional trusted Auth0 domains (for Multiple Custom Domains) |
+| `cacheMaxEntries` | `Integer` | No | — | Maximum entries in the JWKS cache |
+| `cacheTtlSeconds` | `Long` | No | — | TTL in seconds for JWKS cache entries |
+
+### Auto-Configuration Beans
+
+The SDK auto-configuration also supports custom beans:
+
+| Bean | Description |
+|------|-------------|
+| `DomainResolver` | Custom domain resolution for Multiple Custom Domains (MCD). Provide a `@Bean` of type `DomainResolver` to route requests to different Auth0 domains based on the request. |
+| `AuthCache` | Custom cache implementation for JWKS or token verification results. Provide a `@Bean` of type `AuthCache` to override the default in-memory cache. |
+
+### DPoPMode Enum
+
+| Value | Description |
+|-------|-------------|
+| `DPoPMode.DISABLED` | Standard JWT Bearer only — rejects DPoP tokens |
+| `DPoPMode.ALLOWED` | Accept both DPoP-bound and standard Bearer tokens (default) |
+| `DPoPMode.REQUIRED` | Only accept DPoP-bound tokens — rejects standard Bearer |
+
+---
+
+## Auto-Configuration Classes
+
+### Auth0AutoConfiguration
+
+Automatically creates `AuthOptions` and `AuthClient` beans from `Auth0Properties`.
+
+```java
+// AuthOptions bean — built from application.yml
+@Bean
+public AuthOptions authOptions(Auth0Properties properties) {
+    AuthOptions.Builder builder = new AuthOptions.Builder()
+        .domain(properties.getDomain())
+        .audience(properties.getAudience());
+
+    if (properties.getDpopMode() != null) {
+        builder.dpopMode(properties.getDpopMode());
+    }
+    if (properties.getDpopIatLeewaySeconds() != null) {
+        builder.dpopIatLeewaySeconds(properties.getDpopIatLeewaySeconds());
+    }
+    if (properties.getDpopIatOffsetSeconds() != null) {
+        builder.dpopIatOffsetSeconds(properties.getDpopIatOffsetSeconds());
+    }
+    return builder.build();
+}
+
+// AuthClient bean — main entry point for verifying HTTP requests
+@Bean
+@ConditionalOnMissingBean
+public AuthClient authClient(AuthOptions options) {
+    return AuthClient.from(options);
+}
+```
+
+### Auth0SecurityAutoConfiguration
+
+Automatically creates the `Auth0AuthenticationFilter` bean.
+
+```java
+@Bean
+@ConditionalOnMissingBean
+public Auth0AuthenticationFilter authAuthenticationFilter(
+        AuthClient authClient, Auth0Properties auth0Properties) {
+    return new Auth0AuthenticationFilter(authClient, auth0Properties);
+}
+```
+
+### Auth0AuthenticationFilter
+
+A `OncePerRequestFilter` that:
+1. Extracts the `Authorization` header
+2. Calls `AuthClient.verifyRequest()` to validate the JWT (and DPoP proof if present)
+3. Sets `Auth0AuthenticationToken` in the `SecurityContextHolder`
+4. On failure, returns appropriate HTTP status and `WWW-Authenticate` header
+
+---
+
+## Auth0AuthenticationToken
+
+Extends `AbstractAuthenticationToken`. Created after successful JWT validation.
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `getName()` | `String` | User ID (`sub` claim from JWT) |
+| `getClaims()` | `Map<String, Object>` | All JWT claims |
+| `getClaim(String claimName)` | `Object` | Specific claim value, or `null` |
+| `getScopes()` | `Set<String>` | Parsed scopes from `scope` claim |
+| `getAuthorities()` | `Collection<GrantedAuthority>` | `SCOPE_` prefixed authorities from JWT scopes |
+
+**Authority mapping:** The `scope` claim `"read:data write:data"` becomes authorities `SCOPE_read:data` and `SCOPE_write:data`. If no scopes are present, a default `ROLE_USER` authority is assigned.
+
+---
+
+## Claims Reference
+
+### Standard JWT Claims
+
+| Claim | Description | Access |
+|-------|-------------|--------|
+| `sub` | User ID (subject) | `authentication.getName()` or `token.getClaim("sub")` |
+| `scope` | Space-separated scopes | `token.getScopes()` or `token.getClaim("scope")` |
+| `aud` | Audience (API identifier) | `token.getClaim("aud")` |
+| `iss` | Issuer (Auth0 tenant URL) | `token.getClaim("iss")` |
+| `exp` | Expiration timestamp | `token.getClaim("exp")` |
+| `iat` | Issued-at timestamp | `token.getClaim("iat")` |
+
+### Auth0-Specific Claims
+
+| Claim | Description |
+|-------|-------------|
+| `permissions` | Array of RBAC permissions (if Enable RBAC is on) |
+| `email` | User email (if requested in scope) |
+| `https://example.com/*` | Custom claims added via Auth0 Actions (namespaced) |
+
+---
+
+## Complete Minimal Example
+
+```java
+// src/main/java/com/example/SecurityConfig.java
+@Configuration
+@EnableMethodSecurity
+public class SecurityConfig {
+
+    @Bean
+    SecurityFilterChain apiSecurity(
+            HttpSecurity http,
+            Auth0AuthenticationFilter authFilter
+    ) throws Exception {
+        return http
+            .csrf(csrf -> csrf.disable())
+            .sessionManagement(session ->
+                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/api/public").permitAll()
+                .requestMatchers("/api/admin/**").hasAuthority("SCOPE_admin")
+                .anyRequest().authenticated())
+            .addFilterBefore(authFilter, UsernamePasswordAuthenticationFilter.class)
+            .build();
+    }
+}
+
+// src/main/java/com/example/ApiController.java
+@RestController
+@RequestMapping("/api")
+public class ApiController {
+
+    @GetMapping("/public")
+    public ResponseEntity<Map<String, Object>> publicEndpoint() {
+        return ResponseEntity.ok(Map.of("message", "Public endpoint"));
+    }
+
+    @GetMapping("/protected")
+    public ResponseEntity<Map<String, Object>> protectedEndpoint(Authentication authentication) {
+        Auth0AuthenticationToken token = (Auth0AuthenticationToken) authentication;
+        return ResponseEntity.ok(Map.of(
+            "user", authentication.getName(),
+            "scopes", token.getScopes()
+        ));
+    }
+
+    @GetMapping("/admin/dashboard")
+    public ResponseEntity<Map<String, Object>> adminEndpoint(Authentication authentication) {
+        return ResponseEntity.ok(Map.of(
+            "message", "Admin access granted",
+            "user", authentication.getName()
+        ));
+    }
+}
+```
+
+```yaml
+# src/main/resources/application.yml
+auth0:
+  domain: "your-tenant.auth0.com"
+  audience: "https://my-springboot-api"
+
+spring:
+  application:
+    name: auth0-api
+```
+
+---
+
+## Testing Checklist
+
+1. **Public endpoint returns 200 without token:**
+   ```bash
+   curl http://localhost:8080/api/public
+   ```
+
+2. **Protected endpoint returns 401 without token:**
+   ```bash
+   curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/api/protected
+   # Expected: 401
+   ```
+
+3. **Protected endpoint returns 200 with valid token:**
+   ```bash
+   curl http://localhost:8080/api/protected \
+     -H "Authorization: Bearer $TOKEN"
+   ```
+   Capture the token into a shell variable and reference `$TOKEN` rather than
+   pasting the raw token inline — inline token values leak into shell history
+   and terminal scrollback. See [Testing with curl](#testing-with-curl) below.
+
+4. **Scope-protected endpoint returns 403 with insufficient scope:**
+   ```bash
+   curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/api/admin/dashboard \
+     -H "Authorization: Bearer TOKEN_WITHOUT_ADMIN_SCOPE"
+   # Expected: 403
+   ```
+
+5. **DPoP token accepted (if dpop-mode is `ALLOWED` or `REQUIRED`):**
+   ```bash
+   curl http://localhost:8080/api/protected \
+     -H "Authorization: DPoP YOUR_DPOP_TOKEN" \
+     -H "DPoP: YOUR_DPOP_PROOF"
+   ```
+
+---
+
+## Common Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| 401 `invalid_token` | Audience mismatch | Verify `auth0.audience` matches API Identifier exactly |
+| 401 `invalid_issuer` | Domain has `https://` prefix | Use `your-tenant.auth0.com` format only |
+| 403 Forbidden | Token missing required scope | Request token with correct scopes; check `hasAuthority` values |
+| No `Auth0AuthenticationFilter` bean | Missing auto-configuration | Ensure `auth0-springboot-api` is on classpath and `auth0.domain`/`auth0.audience` are set |
+| DPoP `invalid_dpop_proof` | Proof validation failed | Check DPoP proof format, `iat` claim within time window |
+| Token expired | Short-lived test token | Request a fresh token from Auth0 Dashboard or CLI |
+| Multiple Authorization headers | Duplicate header sent | Send exactly one `Authorization` header per request |
+
+---
+
+## Security Considerations
+
+- **No client secret needed** — This library validates JWTs via JWKS (public key), not client credentials
+- **Never hardcode domain or audience** — Use `application.yml` or environment variables
+- **Use HTTPS in production** — Auth0 requires HTTPS for token issuance; API should also use HTTPS
+- **Stateless sessions** — Always configure `SessionCreationPolicy.STATELESS` for API endpoints
+- **Use minimal scopes** — Only enforce scopes your API actually needs
+- **Keep packages updated** — Regularly update `auth0-springboot-api` for security patches
+- **DPoP for high-security APIs** — Enable `dpop-mode: REQUIRED` to prevent token theft
+
+---
+
+## References
+
+- [Auth0 Java Spring Security API Quickstart](https://auth0.com/docs/quickstart/backend/java-spring-security5)
+- [SDK GitHub Repository](https://github.com/auth0/auth0-auth-java)
+- [Spring Security Documentation](https://docs.spring.io/spring-security/reference/)
+- [DPoP RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449)
+
+---
+
+# Auth0 Spring Boot API Integration Patterns
+
+Advanced integration patterns for Spring Boot API applications using `auth0-springboot-api`.
+
+---
+
+## Scope-Based Authorization
+
+The library maps JWT scopes to Spring Security authorities with a `SCOPE_` prefix. A token with `scope: "read:messages write:messages"` produces authorities `SCOPE_read:messages` and `SCOPE_write:messages`.
+
+### Option 1: Security Filter Chain (Recommended)
+
+Define scope requirements in your security configuration:
+
+```java
+@Configuration
+public class SecurityConfig {
+
+    @Bean
+    SecurityFilterChain apiSecurity(
+            HttpSecurity http,
+            Auth0AuthenticationFilter authFilter
+    ) throws Exception {
+        return http
+            .csrf(csrf -> csrf.disable())
+            .sessionManagement(session ->
+                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/api/public").permitAll()
+                .requestMatchers("/api/admin/**").hasAuthority("SCOPE_admin")
+                .requestMatchers("/api/users/**").hasAuthority("SCOPE_read:users")
+                .anyRequest().authenticated())
+            .addFilterBefore(authFilter, UsernamePasswordAuthenticationFilter.class)
+            .build();
+    }
+}
+```
+
+### Option 2: Method-Level Security with @PreAuthorize
+
+Requires `@EnableMethodSecurity` on a configuration class:
+
+```java
+@Configuration
+@EnableMethodSecurity
+public class MethodSecurityConfig {
+    // Enables @PreAuthorize annotations
+}
+```
+
+```java
+@RestController
+@RequestMapping("/api/users")
+public class UserManagementController {
+
+    @GetMapping
+    @PreAuthorize("hasAuthority('SCOPE_read:users')")
+    public ResponseEntity<List<User>> getUsers() {
+        return ResponseEntity.ok(userService.getAllUsers());
+    }
+
+    @PostMapping
+    @PreAuthorize("hasAuthority('SCOPE_write:users')")
+    public ResponseEntity<User> createUser(@RequestBody User user) {
+        return ResponseEntity.ok(userService.createUser(user));
+    }
+
+    @DeleteMapping("/{id}")
+    @PreAuthorize("hasAuthority('SCOPE_delete:users')")
+    public ResponseEntity<Void> deleteUser(@PathVariable String id) {
+        userService.deleteUser(id);
+        return ResponseEntity.noContent().build();
+    }
+}
+```
+
+### Option 3: Programmatic Scope Check
+
+Use `getScopes()` on the token for custom logic:
+
+```java
+@GetMapping("/admin")
+public ResponseEntity<Map<String, Object>> adminEndpoint(Authentication authentication) {
+    if (authentication instanceof Auth0AuthenticationToken auth0Token) {
+        Set<String> scopes = auth0Token.getScopes();
+
+        if (!scopes.contains("admin") || !scopes.contains("read:admin")) {
+            return ResponseEntity.status(HttpStatus.FORBIDDEN)
+                .body(Map.of("error", "insufficient_scope"));
+        }
+
+        return ResponseEntity.ok(Map.of("message", "Admin access granted"));
+    }
+
+    return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
+}
+```
+
+### Define Permissions in Auth0
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Select your API
+3. Click the **Permissions** tab
+4. Add permissions matching your scope names (e.g., `read:users`, `write:users`)
+
+### Request Tokens with Scopes
+
+```bash
+curl -X POST https://your-tenant.auth0.com/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_id": "YOUR_CLIENT_ID",
+    "client_secret": "YOUR_CLIENT_SECRET",
+    "audience": "https://my-springboot-api",
+    "grant_type": "client_credentials",
+    "scope": "read:users write:users"
+  }'
+```
+
+---
+
+## DPoP Authentication
+
+[DPoP](https://www.rfc-editor.org/rfc/rfc9449.html) (Demonstrating Proof of Possession) binds tokens to a specific client key pair, preventing token theft.
+
+### Configuration Modes
+
+#### ALLOWED Mode (Default)
+
+Accepts both Bearer and DPoP tokens:
+
+```yaml
+auth0:
+  domain: "your-tenant.auth0.com"
+  audience: "https://my-springboot-api"
+  dpop-mode: ALLOWED
+```
+
+#### `REQUIRED` Mode
+
+Only accepts DPoP tokens — rejects standard Bearer:
+
+```yaml
+auth0:
+  domain: "your-tenant.auth0.com"
+  audience: "https://my-springboot-api"
+  dpop-mode: REQUIRED
+```
+
+#### DISABLED Mode
+
+Standard JWT Bearer only — rejects DPoP tokens:
+
+```yaml
+auth0:
+  domain: "your-tenant.auth0.com"
+  audience: "https://my-springboot-api"
+  dpop-mode: DISABLED
+```
+
+### Fine-Tuning DPoP Time Validation (Optional)
+
+The defaults work for most use cases. Only adjust these if you need to handle clock skew or network delays:
+
+```yaml
+auth0:
+  domain: "your-tenant.auth0.com"
+  audience: "https://my-springboot-api"
+  dpop-mode: ALLOWED
+  dpop-iat-offset-seconds: 300  # Optional: max age of DPoP proof (default: 300)
+  dpop-iat-leeway-seconds: 30   # Optional: additional time leeway (default: 30)
+```
+
+### How DPoP Works in Controllers
+
+DPoP validation is handled by the `Auth0AuthenticationFilter` before the request reaches your controller. Your controller code is the same regardless of whether the client used Bearer or DPoP:
+
+```java
+@GetMapping("/sensitive")
+public ResponseEntity<Map<String, Object>> sensitiveEndpoint(Authentication authentication) {
+    // Works the same for both Bearer and DPoP tokens
+    if (authentication instanceof Auth0AuthenticationToken auth0Token) {
+        return ResponseEntity.ok(Map.of(
+            "user", authentication.getName(),
+            "scopes", auth0Token.getScopes(),
+            "message", "Access granted"
+        ));
+    }
+    return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
+}
+```
+
+### DPoP WWW-Authenticate Headers
+
+The library automatically generates RFC-compliant `WWW-Authenticate` headers on failures:
+
+```http
+# ALLOWED mode (default)
+WWW-Authenticate: Bearer realm="api", DPoP algs="ES256"
+
+# REQUIRED mode
+WWW-Authenticate: DPoP algs="ES256"
+
+# DPoP-specific errors
+WWW-Authenticate: DPoP error="invalid_dpop_proof", error_description="DPoP proof validation failed"
+```
+
+### Enable DPoP on Auth0 API
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Select your API
+3. Enable DPoP binding requirement
+
+---
+
+## Accessing User Claims
+
+### From Controller Parameter
+
+```java
+@GetMapping("/profile")
+public ResponseEntity<Map<String, Object>> getUserProfile(Authentication authentication) {
+    if (authentication instanceof Auth0AuthenticationToken auth0Token) {
+        return ResponseEntity.ok(Map.of(
+            "sub", String.valueOf(auth0Token.getClaim("sub")),
+            "email", String.valueOf(auth0Token.getClaim("email")),
+            "scope", String.valueOf(auth0Token.getClaim("scope")),
+            "scopes", auth0Token.getScopes()
+        ));
+    }
+    return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
+}
+```
+
+### Common JWT Claims
+
+| Claim | Description |
+|-------|-------------|
+| `sub` | User ID (subject) |
+| `scope` | Space-separated list of granted scopes |
+| `aud` | Audience (your API identifier) |
+| `iss` | Issuer (your Auth0 tenant URL) |
+| `exp` | Expiration timestamp |
+| `iat` | Issued-at timestamp |
+
+Custom claims added via Auth0 Actions use namespaced keys, e.g., `https://example.com/role`.
+
+---
+
+## Error Handling
+
+### BaseAuthException Hierarchy
+
+The library uses `BaseAuthException` subclasses for different error conditions:
+
+| Exception | HTTP Status | Cause |
+|-----------|-------------|-------|
+| `MissingAuthorizationException` | 400 | No or multiple `Authorization` headers |
+| `VerifyAccessTokenException` | 401 | JWT validation failed (expired, bad signature, wrong audience) |
+| `InvalidAuthSchemeException` | 400 | Wrong auth scheme for configured DPoP mode |
+| `InvalidDpopProofException` | 400 | DPoP proof validation failed |
+| `InsufficientScopeException` | 403 | Valid token but missing required scope |
+
+The `Auth0AuthenticationFilter` handles all exceptions automatically, setting the appropriate HTTP status and `WWW-Authenticate` header. No custom exception handling is needed in controllers for auth errors.
+
+### Custom Error Responses
+
+For non-auth errors in your controllers, use standard Spring patterns:
+
+```java
+@ExceptionHandler(Exception.class)
+public ResponseEntity<Map<String, Object>> handleError(Exception e) {
+    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+        .body(Map.of("error", e.getMessage()));
+}
+```
+
+### Standard Error Responses
+
+| Status | Cause | Fix |
+|--------|-------|-----|
+| 401 | Missing or invalid token | Include valid `Authorization: Bearer <token>` header |
+| 401 | Expired token | Request a fresh access token |
+| 401 | Wrong audience | Token's `aud` claim must match your API Identifier |
+| 403 | Insufficient scope | Token must include required scopes |
+
+---
+
+## Mixed Public and Protected Endpoints
+
+```java
+@RestController
+@RequestMapping("/api")
+public class MixedController {
+
+    // Public - no auth needed
+    @GetMapping("/public")
+    public ResponseEntity<Map<String, Object>> publicEndpoint() {
+        return ResponseEntity.ok(Map.of("message", "Public endpoint"));
+    }
+
+    // Protected - requires valid JWT
+    @GetMapping("/private")
+    public ResponseEntity<Map<String, Object>> privateEndpoint(Authentication authentication) {
+        return ResponseEntity.ok(Map.of(
+            "message", "Private endpoint",
+            "user", authentication.getName()
+        ));
+    }
+
+    // Protected with scope
+    @GetMapping("/messages")
+    @PreAuthorize("hasAuthority('SCOPE_read:messages')")
+    public ResponseEntity<Map<String, Object>> messagesEndpoint() {
+        return ResponseEntity.ok(Map.of("messages", List.of("Hello", "World")));
+    }
+}
+```
+
+---
+
+## CORS Configuration
+
+For APIs consumed by browser-based SPAs, configure CORS **before** the auth filter:
+
+```java
+@Configuration
+public class SecurityConfig {
+
+    @Bean
+    SecurityFilterChain apiSecurity(
+            HttpSecurity http,
+            Auth0AuthenticationFilter authFilter
+    ) throws Exception {
+        return http
+            .cors(cors -> cors.configurationSource(corsConfigurationSource()))
+            .csrf(csrf -> csrf.disable())
+            .sessionManagement(session ->
+                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/api/public").permitAll()
+                .anyRequest().authenticated())
+            .addFilterBefore(authFilter, UsernamePasswordAuthenticationFilter.class)
+            .build();
+    }
+
+    @Bean
+    CorsConfigurationSource corsConfigurationSource() {
+        CorsConfiguration config = new CorsConfiguration();
+        config.setAllowedOrigins(List.of("http://localhost:3000"));
+        config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE"));
+        config.setAllowedHeaders(List.of("Authorization", "Content-Type", "DPoP"));
+        config.setAllowCredentials(true);
+
+        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+        source.registerCorsConfiguration("/api/**", config);
+        return source;
+    }
+}
+```
+
+---
+
+## Testing
+
+### Integration Testing with MockMvc
+
+```java
+@SpringBootTest
+@AutoConfigureMockMvc
+class ApiControllerTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Test
+    void publicEndpoint_returns200() throws Exception {
+        mockMvc.perform(get("/api/public"))
+            .andExpect(status().isOk());
+    }
+
+    @Test
+    void protectedEndpoint_withoutToken_returns401() throws Exception {
+        mockMvc.perform(get("/api/protected"))
+            .andExpect(status().isUnauthorized());
+    }
+}
+```
+
+### Testing with curl
+
+```bash
+# Get a test token
+TOKEN=$(auth0 test token --audience https://my-springboot-api --json | jq -r '.access_token')
+
+# Test protected endpoint
+curl http://localhost:8080/api/protected \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## Security Considerations
+
+- **Stateless sessions** — Always use `SessionCreationPolicy.STATELESS` for API endpoints
+- **No client secret** — This library validates JWTs via JWKS; no client secret is stored or needed
+- **CORS before auth** — Configure CORS middleware before the auth filter in the security chain
+- **Use HTTPS in production** — Auth0 requires HTTPS for token issuance
+- **Minimal scopes** — Only enforce scopes your API actually needs
+- **DPoP for high-security** — Enable `dpop-mode: REQUIRED` for APIs handling sensitive data
+
+---
+
+---
+
+# Auth0 Spring Boot API Setup Guide
+
+Setup instructions for Spring Boot API applications using `auth0-springboot-api`.
+
+---
+
+## Auth0 Configuration
+
+> **Agent instruction:**
+>
+> **Check if Auth0 domain and audience are already in the user's prompt first.**
+> If the prompt contains Auth0 domain and audience, use them directly — skip to "Write Configuration" below. Do NOT call `AskUserQuestion` to re-confirm.
+>
+> **If Auth0 configuration is NOT provided**, use `AskUserQuestion` to ask:
+> "How would you like to configure Auth0?"
+> - Option A: "Automatic setup using Auth0 CLI (recommended)"
+> - Option B: "Manual setup" — provide domain and audience manually
+>
+> **If Automatic Setup:**
+>
+> 1. **Pre-flight checks:**
+>    - Verify Auth0 CLI is installed: `auth0 --version`
+>    - Verify logged in: `auth0 tenants list --csv --no-input`
+>    - If any check fails, guide user to install/login, or fall back to manual setup
+>
+> 2. **Create the API resource using Auth0 CLI:**
+>    ```bash
+>    auth0 apis create --name "My Spring Boot API" --identifier https://my-springboot-api --json
+>    ```
+>    Then write the returned domain and audience to `application.yml`.
+>
+> **If Manual Setup:**
+>
+> Ask the user for:
+> - Auth0 Domain (e.g., `your-tenant.auth0.com`)
+> - API Audience / Identifier (e.g., `https://my-springboot-api`)
+>
+> Write the configuration file with provided values.
+
+---
+
+## Quick Setup (Automated)
+
+Uses the Auth0 CLI to create an Auth0 API resource and configure your project.
+
+### Step 1: Install Auth0 CLI and create API resource
+
+```bash
+# Install Auth0 CLI (macOS)
+brew install auth0/auth0-cli/auth0
+
+# Login
+auth0 login --no-input
+
+# Create an Auth0 API resource
+auth0 apis create \
+  --name "My Spring Boot API" \
+  --identifier https://my-springboot-api \
+  --json
+```
+
+Note the `identifier` value — this is your Audience.
+
+### Step 2: Get your domain
+
+```bash
+auth0 tenants list
+```
+
+Your domain is shown in the output (e.g., `your-tenant.auth0.com`).
+
+### Step 3: Write configuration
+
+Add to `src/main/resources/application.yml`:
+
+```yaml
+auth0:
+  domain: "your-tenant.auth0.com"
+  audience: "https://my-springboot-api"
+```
+
+Or `src/main/resources/application.properties`:
+
+```properties
+auth0.domain=your-tenant.auth0.com
+auth0.audience=https://my-springboot-api
+```
+
+---
+
+## Manual Setup
+
+### Install Dependency
+
+**Gradle (build.gradle):**
+
+```groovy
+implementation 'com.auth0:auth0-springboot-api:1.0.0-beta.1'
+```
+
+**Maven (pom.xml):**
+
+```xml
+<dependency>
+    <groupId>com.auth0</groupId>
+    <artifactId>auth0-springboot-api</artifactId>
+    <version>1.0.0-beta.1</version>
+</dependency>
+```
+
+### Create Auth0 API Resource
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Click **Create API**
+3. Set a **Name** and an **Identifier** (e.g., `https://my-springboot-api`)
+4. Note the Identifier — this is your `audience`
+
+### Configure application.yml
+
+```yaml
+auth0:
+  domain: "your-tenant.auth0.com"
+  audience: "https://my-springboot-api"
+```
+
+**Important:** Domain format is `your-tenant.auth0.com` — do NOT include `https://`.
+
+### Get Auth0 Configuration
+
+- **Domain:** Auth0 Dashboard → Settings → Domain (or `auth0 tenants list`)
+- **Audience:** The identifier you set when creating the API resource
+
+---
+
+## Post-Setup Steps
+
+1. **Verify audience matches** — The `auth0.audience` value must exactly match your API Identifier in Auth0 Dashboard
+2. **Add SecurityConfig** — Create a `SecurityConfig.java` class with `Auth0AuthenticationFilter` added before `UsernamePasswordAuthenticationFilter`
+3. **Build and test** — Run `./gradlew bootRun` (or `./mvnw spring-boot:run`) and test endpoints
+
+---
+
+## Environment-Specific Configuration
+
+This library validates JWTs via JWKS (public key verification). **No client secret is needed.**
+
+The `domain` and `audience` values are not secrets — they are public identifiers. However, they typically differ per environment:
+
+### Development
+
+Use `application.yml` or `application.properties` directly:
+
+```yaml
+auth0:
+  domain: "your-tenant.auth0.com"
+  audience: "https://my-springboot-api"
+```
+
+### Production
+
+Use environment variables (override `application.yml`):
+
+```bash
+export AUTH0_DOMAIN=your-tenant.auth0.com
+export AUTH0_AUDIENCE=https://my-springboot-api
+```
+
+Or use Spring profiles (`application-prod.yml`).
+
+---
+
+## Getting a Test Token
+
+### Via Auth0 Dashboard
+
+1. Go to Auth0 Dashboard → Applications → APIs
+2. Select your API
+3. Click the **Test** tab
+4. Click **Copy Token** to get a test access token
+
+### Via Auth0 CLI (Client Credentials)
+
+```bash
+auth0 test token \
+  --audience https://my-springboot-api
+```
+
+### Via curl (Client Credentials Flow)
+
+```bash
+curl -X POST https://your-tenant.auth0.com/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_id": "YOUR_CLIENT_ID",
+    "client_secret": "YOUR_CLIENT_SECRET",
+    "audience": "https://my-springboot-api",
+    "grant_type": "client_credentials"
+  }'
+```
+
+---
+
+## Verification
+
+1. Application starts without errors: `./gradlew bootRun`
+2. Public endpoint accessible without token: `curl http://localhost:8080/api/public`
+3. Protected endpoint returns 401 without token: `curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/api/protected`
+4. Protected endpoint returns 200 with valid token
+
+---
+
+## Troubleshooting
+
+**401 Unauthorized - "invalid_token":** Verify that the `auth0.audience` in config exactly matches your API Identifier in Auth0 Dashboard.
+
+**401 Unauthorized - "invalid_issuer":** Ensure `auth0.domain` does not include `https://` — use `your-tenant.auth0.com` format only.
+
+**No Auth0AuthenticationFilter bean found:** Ensure `auth0-springboot-api` dependency is on the classpath and both `auth0.domain` and `auth0.audience` are configured.
+
+**Token expired:** Test tokens from the Dashboard are short-lived. Request a fresh token.
+
+---
diff --git a/main/.mintlify/skills/auth0/references/framework-swift/index.md b/main/.mintlify/skills/auth0/references/framework-swift/index.md
new file mode 100644
index 0000000000..fc680ca8a4
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-swift/index.md
@@ -0,0 +1,2575 @@
+
+# Auth0 Swift Integration
+
+Auth0.swift is the official Auth0 SDK for Apple platforms (iOS, macOS, tvOS, watchOS, visionOS). This skill adds complete native authentication to Swift apps using Web Auth (system browser redirect), secure Keychain credential storage via `CredentialsManager`, and optional biometric protection.
+
+## Critical rules
+
+- **Credential privacy is IMPORTANT:** never echo Auth0 credentials (domain, client ID, client secret) in response text or terminal output. Instead, redirect Auth0 CLI output to a temp file and use the Read tool to extract values, then write them directly into config files (e.g. `Auth0.plist`) with the Write or Edit tool. When confirming the active tenant, mask the domain (e.g. `your-te****.us.auth0.com`).
+
+## When NOT to Use
+
+- **Android apps**: Use the Auth0 integration workflow for Android
+- **React Native apps**: Use the Auth0 integration workflow for React Native
+- **Flutter apps**: Use the native Flutter Auth0 SDK
+- **Web SPAs** (React, Angular, Vue): Use the Auth0 integration workflow for React, Angular, or Vue
+- **Node.js/Express servers**: Use the Auth0 integration workflow for Express
+
+## Prerequisites
+
+- **iOS** 14.0+ / **macOS** 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+
+- **Xcode** 16.x
+- **Swift** 6.0+
+- Auth0 account — [Sign up free](https://auth0.com/signup)
+- Auth0 CLI — `brew install auth0/auth0-cli/auth0` (for automated setup)
+
+## Quick Start Workflow
+
+> **Agent instruction:** Follow these steps in order. If you encounter an error at any step, attempt to fix it up to 5 times before calling `AskUserQuestion` to ask the user for guidance. Always search existing code first — if there are existing login/logout handlers, hook into them rather than creating new ones.
+>
+> **IMPORTANT — Credential privacy:** Never echo Auth0 credentials (domain, client ID, client secret) in your response text or terminal output. Write them directly into config files using the Write or Edit tool. When running Auth0 CLI commands that produce output containing these values, redirect output to a file and read it programmatically. For example:
+> ```bash
+> auth0 apps create ... --json --no-input > /tmp/auth0-output.json 2>&1
+> ```
+> Then use the Read tool on `/tmp/auth0-output.json` to extract needed values and write them directly into `Auth0.plist` or other config files — never echo them in response text or terminal. When confirming the active tenant with the user, use a masked format (e.g., `your-te****.us.auth0.com`).
+
+### Step 1 — Install SDK
+
+> **Agent instruction:** Check the project directory for an existing package manager file:
+> - `Podfile` present → **CocoaPods**
+> - `Cartfile` present → **Carthage**
+> - `Package.swift` present → **Swift Package Manager**
+>
+> If none are found, ask via `AskUserQuestion`: _"Which dependency manager does your project use — Swift Package Manager, CocoaPods, or Carthage?"_
+>
+> **Swift Package Manager — `Package.swift` project:** Run this command in the project root to add the dependency automatically, then add `"Auth0"` to the target's `dependencies` array in `Package.swift`:
+> ```bash
+> swift package add-dependency https://github.com/auth0/Auth0.swift --from 2.18.0
+> ```
+>
+> **Swift Package Manager — Xcode project (`.xcodeproj`, no `Package.swift`):** The CLI command does not apply. Instruct the user to add the package via Xcode: File → Add Package Dependencies → `https://github.com/auth0/Auth0.swift` → Up to Next Major Version from `2.18.0`.
+>
+> **CocoaPods or Carthage:** Follow the matching installation steps in the Setup Guide — SDK Installation section (below). Do not just show the instructions — perform the file edits and run the commands.
+
+### Step 2 — Configure Auth0
+
+> **Agent instruction:**
+> - **If an `Auth0.plist` file already exists in the project:** Read it to extract `ClientId` and `Domain`, then proceed to Step 3.
+> - **If no `Auth0.plist` exists:** Ask the user via `AskUserQuestion`: _"How would you like to configure Auth0?"_
+>   - **Automatic (Auth0 CLI)** — I'll create the application, set callback URLs, and configure everything using the Auth0 CLI.
+>   - **Manual** — You provide a pre-configured `Auth0.plist` file and I'll add it to your project.
+>
+> If the user chooses **automatic**: Follow the Setup Guide — Automated Setup via Auth0 CLI section (below).
+> If the user chooses **manual**: Follow the Setup Guide — Manual Setup section (below).
+>
+> **IMPORTANT — Never pass credentials in code:** Do NOT hardcode `clientId` or `domain` in Swift source, and do NOT pass them as arguments to `Auth0.webAuth()`, `Auth0.authentication()`, or any other SDK call. The SDK reads these values automatically from `Auth0.plist`. Always use the no-argument forms:
+> ```swift
+> Auth0.webAuth()           // ✓ reads Auth0.plist automatically
+> Auth0.authentication()    // ✓ reads Auth0.plist automatically
+>
+> Auth0.webAuth(clientId: "...", domain: "...")        // ✗ never do this
+> Auth0.authentication(clientId: "...", domain: "...") // ✗ never do this
+> ```
+> The explicit-credential forms are a rare escape hatch (see the API Reference below); when `Auth0.plist` is present, always prefer the no-argument forms.
+
+### Step 3 — Configure Callback URLs
+
+> **Agent instruction:**
+> 1. Read `Auth0.plist` to obtain `ClientId` and `Domain`.
+> 2. Extract the bundle identifier from `project.pbxproj`: search for `PRODUCT_BUNDLE_IDENTIFIER`, skip values containing `$(` or `Tests`.
+> 3. Ask the user via `AskUserQuestion`: _"Which callback URL scheme would you like to use?"_
+>    - **Custom scheme** (`{bundle}://`) — simpler, works on all Apple platforms
+>    - **HTTPS Universal Links** — recommended for production; prevents URL scheme hijacking
+>
+> Then follow **only** the matching path below.
+
+#### Path A — Custom Scheme
+
+> **Agent instruction:** Register the callback URLs using the Auth0 CLI (substitute real values for `CLIENT_ID`, `BUNDLE_ID`, `DOMAIN`).
+>
+> First, retrieve existing callback and logout URLs to avoid overwriting them:
+> ```bash
+> auth0 apps show CLIENT_ID --json --no-input > /tmp/auth0-app-info.json 2>&1
+> ```
+> Read `/tmp/auth0-app-info.json` to extract existing `callbacks` and `allowed_logout_urls` arrays.
+>
+> Then include any existing URLs as a comma-separated list alongside the new ones:
+> ```bash
+> auth0 apps update CLIENT_ID \
+>   --callbacks "EXISTING_CALLBACKS,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
+>   --logout-urls "EXISTING_LOGOUT_URLS,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
+>   --no-input > /dev/null 2>&1
+> ```
+> If there are no existing URLs, omit the `EXISTING_` prefix and use only the new URL.
+>
+> Then follow the URL scheme registration steps in the Setup Guide section (below) to register `$(PRODUCT_BUNDLE_IDENTIFIER)` as a URL type in Xcode.
+
+#### Path B — HTTPS Universal Links
+
+> **Agent instruction:** All four steps below are required — skipping any one will cause the callback redirect to fail silently after login.
+>
+> **Step B1 — Register callback URLs via Auth0 CLI:**
+> Register both HTTPS and custom scheme so the app works in all scenarios.
+>
+> First, retrieve existing callback and logout URLs to avoid overwriting them:
+> ```bash
+> auth0 apps show CLIENT_ID --json --no-input > /tmp/auth0-app-info.json 2>&1
+> ```
+> Read `/tmp/auth0-app-info.json` to extract existing `callbacks` and `allowed_logout_urls` arrays.
+>
+> Then include any existing URLs as a comma-separated list alongside the new ones:
+> ```bash
+> auth0 apps update CLIENT_ID \
+>   --callbacks "EXISTING_CALLBACKS,https://DOMAIN/ios/BUNDLE_ID/callback,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
+>   --logout-urls "EXISTING_LOGOUT_URLS,https://DOMAIN/ios/BUNDLE_ID/callback,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
+>   --no-input > /dev/null 2>&1
+> ```
+> If there are no existing URLs, omit the `EXISTING_` prefix and use only the new URLs.
+>
+> **Step B2 — Configure Device Settings via Auth0 CLI:**
+> Extract `DEVELOPMENT_TEAM` from `project.pbxproj` (10-character value, e.g. `ABC12DE34F`). If not found, ask via `AskUserQuestion`: _"What is your Apple Team ID? (developer.apple.com → Account → Membership Details)"_
+> ```bash
+> auth0 api patch applications/CLIENT_ID \
+>   --data '{"mobile":{"ios":{"team_id":"TEAM_ID","app_bundle_identifier":"BUNDLE_ID"}}}' \
+>   --no-input > /dev/null 2>&1
+> ```
+> Auth0 will now host the `apple-app-site-association` file automatically — required for Universal Links to work on device.
+>
+> **Step B3 — Add Associated Domains entitlement in Xcode:**
+> Add `com.apple.developer.associated-domains` to the app's `.entitlements` file with both `applinks:` and `webcredentials:` entries for the Auth0 domain. See the Setup Guide — Associated Domains section (below) for the complete entitlements XML, Xcode capability steps, and build settings verification.
+>
+> **Step B4 — Use `.useHTTPS()` in the SDK:**
+> ```swift
+> Auth0.webAuth().useHTTPS()
+> ```
+
+### Step 4 — Implement Authentication
+
+> **Agent instruction:** Search the project for `@main struct` (SwiftUI) or `AppDelegate`/`UIViewController` (UIKit) to detect the UI framework. If ambiguous, ask via `AskUserQuestion`: _"Does your app use SwiftUI or UIKit?"_ Then follow **only** the matching path below.
+
+#### SwiftUI
+
+> **Agent instruction:** Create `AuthenticationService.swift` as an `ObservableObject`, then wire it into the app entry point and root view. Search for the `@main` struct and `ContentView` (or equivalent root view) and update them as shown.
+
+```swift
+// AuthenticationService.swift
+import Auth0
+import Combine
+
+class AuthenticationService: ObservableObject {
+    @Published var isAuthenticated = false
+    private let credentialsManager = CredentialsManager(authentication: Auth0.authentication())
+
+    init() { isAuthenticated = credentialsManager.canRenew() }
+
+    func login() async {
+        do {
+            let credentials = try await Auth0
+                .webAuth()
+                .useHTTPS()
+                .scope("openid profile email offline_access")
+                .start()
+            _ = credentialsManager.store(credentials: credentials)
+            await MainActor.run { isAuthenticated = true }
+        } catch WebAuthError.userCancelled { }
+        catch { print("Login failed: \(error)") }
+    }
+
+    func logout() async {
+        do { try await Auth0.webAuth().useHTTPS().clearSession() }
+        catch { print("Logout failed: \(error)") }
+        _ = credentialsManager.clear()
+        await MainActor.run { isAuthenticated = false }
+    }
+}
+```
+
+```swift
+// @main App struct — inject AuthenticationService as environment object
+@StateObject private var auth = AuthenticationService()
+// In body: ContentView().environmentObject(auth)
+
+// Root ContentView — branch on authentication state
+@EnvironmentObject var auth: AuthenticationService
+// In body: if auth.isAuthenticated { HomeView() } else { LoginView() }
+```
+
+For complete SwiftUI app lifecycle wiring, see the Integration Patterns — SwiftUI App Lifecycle section (below).
+
+#### UIKit
+
+> **Agent instruction:** Create `AuthenticationService.swift` as a plain class, then add login/logout calls to the relevant `UIViewController`. Also check whether the app uses `SFSafariViewController` — if so, add `WebAuthentication.resume(with:)` to `AppDelegate`/`SceneDelegate` (see note below).
+
+```swift
+// AuthenticationService.swift
+import Auth0
+
+class AuthenticationService {
+    private let credentialsManager = CredentialsManager(authentication: Auth0.authentication())
+
+    var isAuthenticated: Bool { credentialsManager.canRenew() }
+
+    func login() async throws {
+        let credentials = try await Auth0
+            .webAuth()
+            .useHTTPS()
+            .scope("openid profile email offline_access")
+            .start()
+        _ = credentialsManager.store(credentials: credentials)
+    }
+
+    func logout() async throws {
+        try await Auth0.webAuth().useHTTPS().clearSession()
+        _ = credentialsManager.clear()
+    }
+}
+```
+
+```swift
+// In your UIViewController
+private let auth = AuthenticationService()
+
+@IBAction func loginTapped(_ sender: UIButton) {
+    Task {
+        do {
+            try await auth.login()
+            await MainActor.run { navigateToHome() }
+        } catch WebAuthError.userCancelled { }
+        catch { print("Login failed: \(error)") }
+    }
+}
+
+@IBAction func logoutTapped(_ sender: UIButton) {
+    Task {
+        do { try await auth.logout() }
+        catch { print("Logout failed: \(error)") }
+        await MainActor.run { navigateToLogin() }
+    }
+}
+```
+
+> **Note — SFSafariViewController only:** If the app uses `.provider(WebAuthentication.safariProvider())` instead of the default `ASWebAuthenticationSession`, add `WebAuthentication.resume(with: url)` to `AppDelegate.application(_:open:url:options:)` and `SceneDelegate.scene(_:openURLContexts:)`. See the Integration Patterns — UIKit App Lifecycle section (below) for the exact code.
+
+### Step 5 — Verify Build
+
+> **Agent instruction:** Run a build to verify the integration compiles without errors:
+> ```bash
+> xcodebuild build -scheme YOUR_SCHEME -destination "platform=iOS Simulator,name=iPhone 16"
+> ```
+> If the build fails, review error messages and fix up to 5 times before asking the user.
+
+## Detailed Documentation
+
+- **Setup Guide** (see the Setup Guide section below) — Auth0 CLI configuration, Auth0.plist, URL scheme registration, Associated Domains, CocoaPods/SPM/Carthage install
+- **Integration Patterns** (see the Integration Patterns section below) — Web Auth login/logout, CredentialsManager, biometric protection, MFA, organizations, error handling, SwiftUI/UIKit patterns
+- **API Reference & Testing** (see the API Reference & Testing section below) — Full API reference, configuration options, claims reference, testing checklist, troubleshooting
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Hardcoding `domain`/`clientId` in Swift source when they're in `Auth0.plist` | Write them into `Auth0.plist` and call `Auth0.webAuth()` / `Auth0.authentication()` with no arguments — the SDK reads the plist automatically |
+| Auth0 app type not set to **Native** | In Auth0 Dashboard, select "Native" when creating the application |
+| Missing callback URL in Auth0 Dashboard | Add both `https://` Universal Link and `{bundle}://` custom scheme to Allowed Callback URLs and Logout URLs |
+| `Auth0.plist` not added to Xcode target | Right-click file in Navigator → "Add Files to Target" → check your app target |
+| Missing `offline_access` scope | Add `"offline_access"` to scope string to receive a refresh token for silent renewal |
+| Tokens stored in `UserDefaults` | Always use `CredentialsManager` — it stores tokens in Keychain with access control |
+| Calling `credentialsManager.credentials()` before `store()` | Store credentials from login result before attempting to retrieve |
+| Opening `.xcodeproj` instead of `.xcworkspace` (CocoaPods) | Always open the `.xcworkspace` file after `pod install` |
+| Not calling `clearSession()` on logout | Always call `clearSession()` to remove the Auth0 session cookie from the browser |
+| Build error "No such module 'Auth0'" | Verify the package is added to the correct target; for CocoaPods, open `.xcworkspace` |
+
+## Related Capabilities
+
+- Auth0 setup — if Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Manage Auth0 resources from the terminal with the Auth0 CLI (`tooling-cli`)
+
+
+## References
+
+- [Auth0.swift GitHub](https://github.com/auth0/Auth0.swift)
+- [iOS/macOS Quickstart](https://auth0.com/docs/quickstart/native/ios-swift)
+- [Auth0.swift API Documentation](https://auth0.github.io/Auth0.swift/documentation/auth0/)
+- [Auth0 Dashboard](https://manage.auth0.com)
+- [EXAMPLES.md](https://github.com/auth0/Auth0.swift/blob/master/EXAMPLES.md)
+
+---
+
+# API Reference & Testing — Auth0 Swift
+
+## Configuration Reference
+
+### Auth0.plist Keys
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `ClientId` | String | Yes | Your Auth0 application Client ID |
+| `Domain` | String | Yes | Your Auth0 tenant domain (e.g., `tenant.auth0.com`) |
+
+### WebAuth Builder Options
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `.useHTTPS()` | — | Use Universal Links (HTTPS) for callback — recommended |
+| `.scope(_ scope: String)` | `String` | Space-separated OAuth scopes. Default: `"openid profile email"`. Add `"offline_access"` for refresh tokens |
+| `.audience(_ audience: String)` | `String` | API audience (resource identifier). Required for API access tokens |
+| `.parameters(_ params: [String: String])` | `[String: String]` | Additional authorize parameters (e.g., `["screen_hint": "signup"]`) |
+| `.organization(_ organization: String)` | `String` | Auth0 Organization ID or name |
+| `.invitationURL(_ url: URL)` | `URL` | Accept an organization invitation |
+| `.redirectURL(_ url: URL)` | `URL` | Override the callback URL |
+| `.provider(_ provider: WebAuthProvider)` | — | Use SFSafariViewController or custom provider |
+| `.ephemeralSession()` | — | Do not persist session cookies (no SSO) |
+| `.nonce(_ nonce: String)` | `String` | Override the auto-generated nonce |
+| `.maxAge(_ maxAge: Int)` | `Int` | Maximum age (seconds) of allowed authentication |
+| `.leeway(_ leeway: Int)` | `Int` | Clock skew tolerance in seconds for ID token validation |
+
+### CredentialsManager Options
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `CredentialsManager(authentication:)` | — | Standard initialization |
+| `CredentialsManager(authentication:maxRetries:)` | `Int` | Set retry attempts on transient errors |
+| `CredentialsManager(authentication:storeKey:)` | `String` | Custom Keychain key for multi-account support |
+| `.store(credentials:)` | `Bool` | Store credentials; returns `false` if Keychain write fails |
+| `.credentials()` | `Credentials` (async) | Retrieve valid credentials; auto-renews if expired |
+| `.credentials(minTTL:)` | `Credentials` (async) | Retrieve with minimum remaining TTL |
+| `.canRenew()` | `Bool` | Returns `true` if a refresh token is available |
+| `.hasValid(minTTL:)` | `Bool` | Returns `true` if access token is valid for at least `minTTL` seconds |
+| `.clear()` | `Bool` | Remove credentials from Keychain |
+| `.revoke(headers:)` | `Void` (async) | Revoke refresh token and clear credentials |
+| `.enableBiometrics(withTitle:)` | — | Prompt biometric authentication when retrieving credentials |
+| `.enableBiometrics(withTitle:policy:)` | — | Biometrics with custom `LAPolicy` |
+| `.clearBiometricSession()` | — | Clear cached biometric session |
+| `.isBiometricSessionValid()` | `Bool` | Check if biometric session is still valid |
+
+### Biometric Policy Options
+
+| Policy | Description |
+|--------|-------------|
+| `.default` | System manages prompts; allows reuse within a short window |
+| `.always` | Fresh biometric prompt every time credentials are retrieved |
+| `.session(timeoutInSeconds:)` | Reuse biometric auth for specified seconds (default 300) |
+| `.appLifecycle(timeoutInSeconds:)` | Reuse for app lifecycle (default 3600 seconds / 1 hour) |
+
+### Credentials Object
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `accessToken` | `String` | JWT access token for API calls |
+| `tokenType` | `String` | Token type, usually `"Bearer"` |
+| `idToken` | `String` | JWT ID token with user identity claims |
+| `refreshToken` | `String?` | Refresh token (requires `offline_access` scope) |
+| `expiresIn` | `Date` | Access token expiration date |
+| `scope` | `String?` | Granted scopes |
+
+---
+
+## Claims Reference
+
+### Standard OIDC Claims (from ID Token)
+
+| Claim | Type | Description |
+|-------|------|-------------|
+| `sub` | String | User ID (e.g., `"auth0|64abc123"`) |
+| `name` | String | Full display name |
+| `given_name` | String | First name |
+| `family_name` | String | Last name |
+| `email` | String | Email address |
+| `email_verified` | Bool | Whether email is verified |
+| `picture` | String | Profile picture URL |
+| `updated_at` | Date | Last profile update timestamp |
+| `iss` | String | Issuer — your Auth0 domain |
+| `aud` | String | Audience — your Client ID |
+| `exp` | Date | Expiration time |
+| `iat` | Date | Issued at time |
+
+### Auth0-Specific Claims
+
+| Claim | Type | Description |
+|-------|------|-------------|
+| `https://example.com/permissions` | `[String]` | User permissions (added via Auth0 Actions) |
+| `https://example.com/roles` | `[String]` | User roles (added via Auth0 Actions) |
+| `org_id` | String | Organization ID |
+| `org_name` | String | Organization name |
+
+### Reading User Profile Claims
+
+Read the user's profile from stored credentials with the `CredentialsManager`
+`user` property. It decodes the ID token and returns a `UserInfo?` whose
+properties expose the standard OIDC claims (`sub`, `name`, `email`, `picture`, …):
+
+```swift
+import Auth0
+
+// Reuse the existing credentialsManager instance
+if let user = credentialsManager.user {
+    print("User ID: \(user.sub)")
+    print("Name: \(user.name ?? "none")")
+    print("Email: \(user.email ?? "none")")
+}
+```
+
+To decode the ID token manually, use JWTDecode (bundled with Auth0.swift):
+
+```swift
+import JWTDecode
+
+if let jwt = try? decode(jwt: credentials.idToken) {
+    let email = jwt.claim(name: "email").string
+    let name = jwt.claim(name: "name").string
+    print("Email: \(email ?? "none"), Name: \(name ?? "none")")
+}
+```
+
+---
+
+## Testing Checklist
+
+> **Physical device note:** Web Auth (ASWebAuthenticationSession) works in the iOS Simulator, but biometric authentication (Face ID / Touch ID) requires a real device. Test biometric flows on a physical device before shipping. Simulator has limitations for camera-based Face ID and some Keychain access control scenarios.
+
+- [ ] `Auth0.plist` is present in the Xcode project and added to the app target
+- [ ] Both `https://` Universal Link and `{bundle}://` custom scheme URLs are in Auth0 Dashboard Callback URLs
+- [ ] App builds without errors: `xcodebuild build -scheme SCHEME -destination "platform=iOS Simulator,name=iPhone 16"`
+- [ ] Login opens system browser (ASWebAuthenticationSession) and redirects back to app
+- [ ] `credentialsManager.store(credentials:)` returns `true` after login
+- [ ] `credentialsManager.canRenew()` returns `true` after storing credentials with `offline_access`
+- [ ] `credentialsManager.credentials()` returns valid access token without re-login (token auto-refresh)
+- [ ] Logout clears session cookie (subsequent login shows login prompt, not silent SSO)
+- [ ] `credentialsManager.clear()` returns `true` after logout
+- [ ] Error cases are handled: `userCancelled`, `noCredentialsAvailable`, `failedToRenewCredentials`
+- [ ] Biometric prompt appears (if enabled) before credentials are returned
+- [ ] App state persists across launches (credentials survive app restart)
+
+---
+
+## Common Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `Auth0.plist not found` | File not added to target | Right-click `Auth0.plist` → Add Files → check app target |
+| `No such module 'Auth0'` | Package not installed or wrong target | Verify SPM package in Xcode → Package Dependencies; re-resolve |
+| `Redirect to app fails` | Callback URL mismatch | Ensure URL in Auth0 Dashboard matches bundle ID exactly |
+| `Cannot open URL` (iOS) | Missing URL scheme | Add `$(PRODUCT_BUNDLE_IDENTIFIER)` to URL Schemes in Info tab |
+| Login shows blank screen | Universal Links not configured | Use `.useHTTPS()` only if Universal Links are configured, else omit it |
+| Token not renewable | Missing `offline_access` scope | Add `"offline_access"` to `.scope()` call |
+| `biometricsFailed` error | No biometric enrolled or cancelled | Fall back to re-login |
+| `cannotAccessKeychainItem` | Keychain entitlements missing | Verify app has Keychain Sharing capability or correct entitlements |
+| Crash on macOS | Missing network entitlement | Add "Outgoing Connections (Client)" capability in Signing & Capabilities |
+| Build fails on Swift 6 | Concurrency issues | Ensure callbacks are dispatched on `@MainActor` for UI updates |
+
+---
+
+## Security Considerations
+
+- **No client secret**: Native apps use PKCE (Proof Key for Code Exchange) — no client secret is required or used. Do not add a client secret to `Auth0.plist`.
+- **Keychain storage**: Always use `CredentialsManager` for token storage. Never use `UserDefaults` or plain files. Tokens in `UserDefaults` are readable by other apps on jailbroken devices.
+- **Universal Links vs custom scheme**: Universal Links (`https://`) are recommended for production as they cannot be intercepted by malicious apps. Custom schemes (`{bundle}://`) are acceptable but less secure.
+- **Scope minimization**: Request only the scopes your app needs. Avoid requesting permissions you do not use.
+- **Refresh token rotation**: Enable Refresh Token Rotation in Auth0 Dashboard (Applications → Advanced Settings → OAuth) to detect token theft.
+- **Biometric storage**: When using `enableBiometrics()`, the Keychain entry uses `kSecAccessControlBiometryCurrentSet` which invalidates the entry if new biometrics are enrolled — protecting against biometric spoofing.
+- **Certificate pinning**: For extra security, use a custom `URLSession` with certificate pinning when calling your API with the access token.
+- **App Transport Security**: Ensure `NSAllowsArbitraryLoads` is not set to `true` in production builds.
+
+---
+
+## Related Capabilities
+
+- Auth0 authentication for Android/Kotlin apps — the Auth0 integration workflow for Android
+- Cross-platform iOS + Android authentication with Flutter — the Auth0 integration workflow for Flutter
+- Cross-platform iOS + Android authentication with React Native — the Auth0 integration workflow for React Native
+- Auth0 setup — if Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Multi-factor authentication — ask for MFA (feature:mfa)
+
+---
+
+# Integration Patterns — Auth0 Swift
+
+## Authentication Flow
+
+```text
+User taps "Log In"
+    ↓
+Auth0.webAuth().start()
+    ↓
+ASWebAuthenticationSession opens Auth0 Universal Login
+    ↓ (user authenticates)
+Auth0 redirects to {bundle}:// or https:// callback
+    ↓
+SDK exchanges code for tokens (PKCE)
+    ↓
+Credentials returned (accessToken, idToken, refreshToken)
+    ↓
+credentialsManager.store(credentials:) → Keychain
+```
+
+---
+
+## Web Auth Login & Logout
+
+### Basic Login (Async/Await)
+
+```swift
+import Auth0
+
+func login() async throws -> Credentials {
+    return try await Auth0
+        .webAuth()
+        .useHTTPS()                              // Use Universal Links callback
+        .scope("openid profile email offline_access")
+        .start()
+}
+```
+
+### Basic Login (Completion Handler)
+
+```swift
+Auth0
+    .webAuth()
+    .useHTTPS()
+    .scope("openid profile email offline_access")
+    .start { result in
+        switch result {
+        case .success(let credentials):
+            // Access token available at credentials.accessToken
+            credentialsManager.store(credentials: credentials)
+        case .failure(let error):
+            print("Login failed: \(error)")
+        }
+    }
+```
+
+### Logout
+
+```swift
+// Step 1: Clear the Auth0 session cookie (prevents silent re-login)
+try await Auth0
+    .webAuth()
+    .useHTTPS()
+    .clearSession()
+
+// Step 2: Clear locally stored credentials
+let credentialsManager = CredentialsManager(authentication: Auth0.authentication())
+_ = credentialsManager.clear()
+```
+
+### Sign Up (Direct to Registration Screen)
+
+```swift
+try await Auth0
+    .webAuth()
+    .useHTTPS()
+    .parameters(["screen_hint": "signup"])
+    .start()
+```
+
+### Custom Scopes and Audience
+
+```swift
+// Request an access token for your API
+try await Auth0
+    .webAuth()
+    .useHTTPS()
+    .audience("https://your-api.example.com")
+    .scope("openid profile email offline_access read:data")
+    .start()
+```
+
+### Ephemeral Session (No SSO, No Cookie Persistence)
+
+```swift
+// Each login shows the login page — no session cookie stored
+try await Auth0
+    .webAuth()
+    .useHTTPS()
+    .ephemeralSession()
+    .start()
+```
+
+---
+
+## CredentialsManager
+
+`CredentialsManager` handles secure Keychain storage and automatic token refresh.
+
+### Basic Setup
+
+```swift
+// Initialize once (e.g., as a property on your auth service)
+let credentialsManager = CredentialsManager(authentication: Auth0.authentication())
+```
+
+### Store After Login
+
+```swift
+let credentials = try await Auth0.webAuth().start()
+guard credentialsManager.store(credentials: credentials) else {
+    throw AuthError.keychainWriteFailed
+}
+```
+
+### Retrieve (Auto-Refreshes Expired Tokens)
+
+```swift
+do {
+    let credentials = try await credentialsManager.credentials()
+    callAPI(with: credentials.accessToken)
+} catch CredentialsManagerError.noCredentialsAvailable {
+    // No credentials stored — show login screen
+    await showLogin()
+} catch CredentialsManagerError.failedToRenewCredentials(let error) {
+    // Refresh token expired or revoked — force re-login
+    _ = credentialsManager.clear()
+    await showLogin()
+}
+```
+
+### Check Authentication State on Launch
+
+```swift
+func checkSession() -> Bool {
+    // Returns true if a valid refresh token is stored
+    return credentialsManager.canRenew()
+}
+
+// Check if access token is still valid without auto-refresh
+func hasValidToken(minTTL: Int = 60) -> Bool {
+    return credentialsManager.hasValid(minTTL: minTTL)
+}
+```
+
+### Force Token Renewal
+
+```swift
+do {
+    let credentials = try await credentialsManager.renew()
+    // Renewed token available at credentials.accessToken
+    _ = credentialsManager.store(credentials: credentials)
+} catch {
+    print("Renewal failed: \(error)")
+}
+```
+
+### Revoke Refresh Token
+
+```swift
+// Revokes the refresh token on Auth0 and clears local credentials
+try await credentialsManager.revoke()
+```
+
+---
+
+## Biometric Protection
+
+Protect credential retrieval with Face ID / Touch ID.
+
+> **Physical device note:** Biometric authentication (Face ID / Touch ID) requires a real device. The iOS Simulator supports simulated biometrics but physical device testing is required before shipping to verify actual hardware behavior.
+
+### Enable Biometrics
+
+```swift
+let credentialsManager = CredentialsManager(authentication: Auth0.authentication())
+
+// Basic — system-managed prompt reuse
+credentialsManager.enableBiometrics(withTitle: "Authenticate to access your account")
+
+// With session timeout (reuse for 5 minutes)
+credentialsManager.enableBiometrics(
+    withTitle: "Authenticate to access your account",
+    policy: .session(timeoutInSeconds: 300)
+)
+
+// Require fresh biometric every time
+credentialsManager.enableBiometrics(
+    withTitle: "Authenticate to access your account",
+    policy: .always
+)
+
+// App lifecycle (reset on app background/foreground)
+credentialsManager.enableBiometrics(
+    withTitle: "Authenticate to access your account",
+    policy: .appLifecycle(timeoutInSeconds: 3600)
+)
+```
+
+### Handle Biometric Errors
+
+```swift
+do {
+    let credentials = try await credentialsManager.credentials()
+    useCredentials(credentials)
+} catch CredentialsManagerError.biometricsFailed {
+    // Biometric auth failed — ask user to log in again
+    _ = credentialsManager.clear()
+    await login()
+} catch CredentialsManagerError.noCredentialsAvailable {
+    await login()
+}
+```
+
+### Info.plist Permission (Required)
+
+Add to your app's `Info.plist`:
+```xml
+<key>NSFaceIDUsageDescription</key>
+<string>Authenticate to access your account securely.</string>
+```
+
+---
+
+## Error Handling
+
+### Web Auth Errors
+
+```swift
+do {
+    let credentials = try await Auth0.webAuth().start()
+} catch WebAuthError.userCancelled {
+    // User tapped Cancel — no action needed, just return to UI
+} catch WebAuthError.noCredentialsAvailable {
+    print("No credentials available — unexpected after login")
+} catch WebAuthError.pkceNotAllowed {
+    print("PKCE not enabled — check Auth0 Dashboard → Application → Advanced Settings → OAuth")
+} catch {
+    // Other error (network, configuration)
+    print("Web Auth error: \(error)")
+}
+```
+
+### CredentialsManager Errors
+
+```swift
+do {
+    let credentials = try await credentialsManager.credentials()
+} catch CredentialsManagerError.noCredentialsAvailable {
+    // First launch or after logout
+    await showLoginScreen()
+} catch CredentialsManagerError.failedToRenewCredentials(let renewalError) {
+    // Refresh token expired — must re-authenticate
+    _ = credentialsManager.clear()
+    await showLoginScreen()
+} catch CredentialsManagerError.biometricsFailed {
+    // Face ID / Touch ID failed
+    await showBiometricFailureMessage()
+} catch CredentialsManagerError.cannotAccessKeychainItem {
+    // Keychain access denied (e.g., device locked, missing entitlements)
+    print("Keychain error: \(error)")
+}
+```
+
+### Authentication API Errors
+
+```swift
+Auth0
+    .authentication()
+    .login(usernameOrEmail: "user@example.com",
+           password: "password",
+           realmOrConnection: "Username-Password-Authentication",
+           scope: "openid profile email offline_access")
+    .start { result in
+        switch result {
+        case .success(let credentials):
+            // Access token available at credentials.accessToken
+            credentialsManager.store(credentials: credentials)
+        case .failure(let error) where error.isMultifactorRequired:
+            // Extract MFA token for MFA challenge flow
+            if let mfaPayload = error.mfaRequiredErrorPayload {
+                startMFAChallenge(mfaToken: mfaPayload.mfaToken)
+            }
+        case .failure(let error) where error.isNetworkError:
+            showNetworkError()
+        case .failure(let error):
+            print("Auth error code: \(error.code), description: \(error.localizedDescription)")
+        }
+    }
+```
+
+---
+
+## MFA (Multi-Factor Authentication)
+
+### Handling MFA Required Error
+
+```swift
+// When login returns isMultifactorRequired = true, challenge with OTP
+func verifyMFA(mfaToken: String, otp: String) async throws -> Credentials {
+    return try await Auth0
+        .authentication()
+        .multifactorChallenge(mfaToken: mfaToken, types: ["otp"])
+        .start()
+}
+```
+
+---
+
+## Organizations
+
+### Login to a Specific Organization
+
+```swift
+try await Auth0
+    .webAuth()
+    .useHTTPS()
+    .organization("YOUR_ORG_ID")
+    .start()
+```
+
+### Accept Organization Invitation
+
+```swift
+// Handle invitation URL from deep link
+func handleInvitation(url: URL) async {
+    try? await Auth0
+        .webAuth()
+        .useHTTPS()
+        .invitationURL(url)
+        .start()
+}
+```
+
+---
+
+## Platform-Specific Patterns
+
+### SwiftUI App Lifecycle (Recommended)
+
+```swift
+// MyApp.swift
+import SwiftUI
+import Auth0
+
+@main
+struct MyApp: App {
+    @StateObject private var auth = AuthenticationService()
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+                .environmentObject(auth)
+        }
+    }
+}
+
+// ContentView.swift
+struct ContentView: View {
+    @EnvironmentObject var auth: AuthenticationService
+
+    var body: some View {
+        Group {
+            if auth.isAuthenticated {
+                HomeView()
+            } else {
+                LoginView()
+            }
+        }
+        .onAppear {
+            auth.checkSession()
+        }
+    }
+}
+```
+
+### UIKit App Lifecycle
+
+```swift
+// AppDelegate.swift
+import UIKit
+import Auth0
+
+@UIApplicationMain
+class AppDelegate: UIResponder, UIApplicationDelegate {
+    func application(_ app: UIApplication,
+                     open url: URL,
+                     options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
+        // Required for SFSafariViewController or custom URL scheme
+        return WebAuthentication.resume(with: url)
+    }
+}
+
+// SceneDelegate.swift (if using scenes)
+class SceneDelegate: UIResponder, UIWindowSceneDelegate {
+    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
+        guard let url = URLContexts.first?.url else { return }
+        WebAuthentication.resume(with: url)
+    }
+}
+```
+
+### Using SFSafariViewController (Instead of ASWebAuthenticationSession)
+
+```swift
+// For apps that cannot use ASWebAuthenticationSession
+Auth0
+    .webAuth()
+    .provider(WebAuthentication.safariProvider())
+    .start { result in
+        switch result {
+        case .success(let credentials):
+            print("Login success")
+        case .failure(let error):
+            print("Login failed: \(error)")
+        }
+    }
+```
+
+> **Note:** SFSafariViewController requires `WebAuthentication.resume(with:)` to be called from `AppDelegate` or `SceneDelegate` (see UIKit pattern above).
+
+---
+
+## App Groups (Shared Keychain Access)
+
+To share credentials between your app and extensions (widgets, share extensions):
+
+```swift
+// Use a custom storeKey to write to a shared Keychain group
+let credentialsManager = CredentialsManager(
+    authentication: Auth0.authentication(),
+    storeKey: "com.yourcompany.sharedCredentials"
+)
+
+// Configure Keychain sharing in Xcode:
+// Target → Signing & Capabilities → + Capability → Keychain Sharing
+// Add a shared Keychain group name
+```
+
+---
+
+## Calling Your API with the Access Token
+
+```swift
+func fetchData() async throws -> [Item] {
+    let credentials = try await credentialsManager.credentials()
+
+    var request = URLRequest(url: URL(string: "https://your-api.example.com/items")!)
+    request.setValue("Bearer \(credentials.accessToken)", forHTTPHeaderField: "Authorization")
+
+    let (data, _) = try await URLSession.shared.data(for: request)
+    return try JSONDecoder().decode([Item].self, from: data)
+}
+```
+
+---
+
+# Setup Guide — Auth0 Swift
+
+## Auth0 Configuration
+
+> **Agent instruction:** Check whether an `Auth0.plist` already exists in the project directory.
+> - **If `Auth0.plist` exists:** Read it to extract `ClientId` and `Domain`, then proceed to "Post-Setup Steps".
+> - **If no `Auth0.plist` exists:** Ask the user via `AskUserQuestion` which setup path they prefer:
+>   - **Automatic (Auth0 CLI)** — creates the application, callback URLs, and database connection via the CLI.
+>   - **Manual** — the user provides a pre-configured `Auth0.plist` file from the Auth0 Dashboard.
+>
+> If the user chooses **manual**, follow [Manual Setup](#manual-setup-user-provided-auth0plist).
+> If the user chooses **automatic**, follow the section below.
+
+### Automated Setup via Auth0 CLI
+
+> **Agent instruction:** Run these pre-flight checks. Do NOT run `auth0 login` from the agent — it is interactive and will hang.
+>
+> **Credential privacy (see Critical rules at the top):** Never echo Auth0 credentials (domain, client ID, client secret) in your response text or terminal output. Write them directly into config files using the Write or Edit tool. When running Auth0 CLI commands, redirect output to a private temporary file (created with `mktemp` under a restrictive umask) rather than a predictable path:
+>
+> ```bash
+> umask 077
+> OUT=$(mktemp -t auth0-output)
+> auth0 <command> --json --no-input > "$OUT" 2>&1
+> echo "$OUT"   # note the path; do NOT print the file contents
+> ```
+>
+> Then use the Read tool to extract values from that path and write them directly into `Auth0.plist` or other config files — never echo them in response text or terminal. Delete the file with `rm -f "$OUT"` once you have finished reading it. When confirming the active tenant with the user, mask the domain (e.g., `your-te****.us.auth0.com`).
+>
+> **Pre-flight checks:**
+>
+> 1. **Check Auth0 CLI**: `command -v auth0`. If missing, install it: `brew install auth0/auth0-cli/auth0`.
+> 2. **Check Auth0 login**: `auth0 tenants list --csv --no-input > /tmp/auth0-tenants.txt 2>&1`. Read the file to check the result. If it fails or returns empty:
+>    - Tell the user: _"Please run `auth0 login` in your terminal and let me know when done."_
+>    - Wait for confirmation, then re-run the check. Retry up to 3 times before treating as a persistent failure.
+> 3. **Confirm active tenant**: Redirect tenant list output to a file and read it. Parse the `→` line to extract the domain. Tell the user using a masked format: _"Your active Auth0 tenant is: `your-te****.us.auth0.com`. Is this correct? (Recommend using a development/test tenant rather than production.)"_ — mask all but the first 7 characters of the subdomain.
+>    - If no, ask the user to run `auth0 tenants use <tenant-domain>`, then re-run step 2.
+>
+> **Detect project settings:**
+>
+> 4. **Extract bundle identifier** from `project.pbxproj`: search for `PRODUCT_BUNDLE_IDENTIFIER`, skip values containing `$(` or `Tests` or `NO`.
+> 5. **Extract Team ID** (optional): search for `DEVELOPMENT_TEAM` in `project.pbxproj` — a 10-character alphanumeric value (e.g. `ABC12DE34F`). If not found, proceed without it (will prompt later if needed for Universal Links).
+>
+> **Create the Auth0 application:**
+>
+> 6. **Create a Native application** with both HTTPS and custom scheme callback URLs:
+>    ```bash
+>    auth0 apps create \
+>      --name "BUNDLE_ID-ios" \
+>      --type native \
+>      --auth-method none \
+>      --callbacks "https://DOMAIN/ios/BUNDLE_ID/callback,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
+>      --logout-urls "https://DOMAIN/ios/BUNDLE_ID/callback,BUNDLE_ID://DOMAIN/ios/BUNDLE_ID/callback" \
+>      --json \
+>      --no-input > /tmp/auth0-app-created.json 2>&1
+>    ```
+>    Read `/tmp/auth0-app-created.json` to extract `client_id`. Do not display the file contents in the terminal.
+>
+> 7. **Set up database connection**: Check if `Username-Password-Authentication` already exists and has the new client enabled:
+>    ```bash
+>    auth0 api get connections --no-input > /tmp/auth0-connections.json 2>&1
+>    ```
+>    Read `/tmp/auth0-connections.json` to check existing connections.
+>    - If the connection does not exist, create it:
+>      ```bash
+>      auth0 api post connections \
+>        --data '{"strategy":"auth0","name":"Username-Password-Authentication","enabled_clients":["CLIENT_ID"]}' \
+>        --no-input > /dev/null 2>&1
+>      ```
+>    - If it exists but the client is not in `enabled_clients`, update it:
+>      ```bash
+>      auth0 api patch connections/CONNECTION_ID \
+>        --data '{"enabled_clients":["EXISTING_CLIENT_1","EXISTING_CLIENT_2","CLIENT_ID"]}' \
+>        --no-input > /dev/null 2>&1
+>      ```
+>    - If it exists and already includes the client, skip this step.
+>
+> 8. **Configure Device Settings** (for Universal Links — Auth0 hosts `apple-app-site-association`):
+>    If Team ID was detected in step 5:
+>    ```bash
+>    auth0 api patch applications/CLIENT_ID \
+>      --data '{"mobile":{"ios":{"team_id":"TEAM_ID","app_bundle_identifier":"BUNDLE_ID"}}}' \
+>      --no-input > /dev/null 2>&1
+>    ```
+>    If Team ID was not detected, inform the user: _"Set your Apple Team ID in Auth0 Dashboard → App Settings → Advanced → Device Settings, or provide it now."_
+>
+> 9. **Write `Auth0.plist`** to the project directory (see template below).
+>
+> 10. **Write or merge entitlements file** — see [Associated Domains Setup](#associated-domains-setup-https-universal-links) below.
+>
+> 11. **Inform user of remaining manual Xcode steps:**
+>     - Add `Auth0.plist` to the app target in Xcode (File Inspector → Target Membership).
+>     - Register URL scheme: target → Info tab → URL Types → add `$(PRODUCT_BUNDLE_IDENTIFIER)`.
+>     - If a new entitlements file was created, set `CODE_SIGN_ENTITLEMENTS` in Build Settings.
+>
+> If any CLI command fails due to session expiry, ask the user to run `auth0 login` again, then retry. Retry up to 3 times.
+> Only if the CLI keeps failing after retries: fall back to the [Manual Setup](#manual-setup-user-provided-auth0plist) path — ask the user to provide their `Auth0.plist` file.
+
+### Manual Setup (User-Provided Auth0.plist)
+
+> **Agent instruction:** Do NOT ask the user to type or paste credentials (domain, client ID) into the terminal. Instead:
+>
+> 1. Ask the user via `AskUserQuestion`: _"Please place your `Auth0.plist` file (containing your ClientId and Domain) in the project root directory and let me know when it's ready. You can download it from Auth0 Dashboard → Applications → your app → Settings → scroll to bottom → 'Download Auth0.plist'."_
+> 2. Once the user confirms, verify the file exists in the project directory. If not found, search common locations (`~/Downloads/Auth0.plist`, project root).
+> 3. Read the file to validate it contains both `ClientId` and `Domain` keys. If malformed, ask the user to re-download it.
+> 4. If the file is not already in the correct location (alongside the `.xcodeproj`), copy it there.
+> 5. Inform the user to add it to the Xcode target: _"Add Auth0.plist to your app target in Xcode: select the file in Navigator → File Inspector → check your app target under Target Membership."_
+> 6. Proceed to "Post-Setup Steps".
+
+Expected `Auth0.plist` format:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>ClientId</key>
+    <string>YOUR_AUTH0_CLIENT_ID</string>
+    <key>Domain</key>
+    <string>YOUR_AUTH0_DOMAIN</string>
+</dict>
+</plist>
+```
+
+---
+
+## Post-Setup Steps
+
+### Register URL Scheme (Required for Custom Scheme Callbacks)
+
+In Xcode, select your app target → **Info** tab → expand **URL Types** → click **+**:
+- **Identifier**: `auth0`
+- **URL Schemes**: `$(PRODUCT_BUNDLE_IDENTIFIER)`
+
+This allows the Auth0 browser to redirect back to your app using the `{bundle}://` scheme.
+
+### Associated Domains Setup (HTTPS Universal Links)
+
+> **Agent instruction:** Only follow this section if the user chose HTTPS Universal Links as their callback scheme. If they chose a custom scheme (`{bundle}://`), skip this section entirely.
+>
+> **Prerequisites:** Before configuring Xcode, Auth0 must be told your Apple Team ID and Bundle ID so it can host the `apple-app-site-association` file. Without this, Universal Links will not work even if the entitlements are correct.
+
+#### Step 1 — Configure Device Settings via Auth0 CLI
+
+> **Agent instruction:**
+> Extract `DEVELOPMENT_TEAM` from `project.pbxproj` (10-character value, e.g. `ABC12DE34F`). If not found, ask via `AskUserQuestion`: _"What is your Apple Team ID? (developer.apple.com → Account → Membership Details)"_
+>
+> ```bash
+> auth0 api patch applications/CLIENT_ID \
+>   --data '{"mobile":{"ios":{"team_id":"TEAM_ID","app_bundle_identifier":"BUNDLE_ID"}}}' \
+>   --no-input > /dev/null 2>&1
+> ```
+>
+> Auth0 will now automatically host the Apple App Site Association file at:
+> `https://YOUR_AUTH0_DOMAIN/.well-known/apple-app-site-association`
+>
+> Verify it lists your app by opening that URL — the response should contain `applinks` with your `appID` in the format `TEAMID.com.example.myapp`.
+>
+> Reference: [Enable Universal Links Support in Apple Xcode](https://auth0.com/docs/get-started/applications/enable-universal-links-support-in-apple-xcode)
+
+#### Step 2 — Add Associated Domains Entitlement in Xcode
+
+> **Agent instruction:**
+> 1. Find the app's `.entitlements` file (commonly `<AppName>.entitlements`). Search for `*.entitlements` in the project directory.
+> 2. If the file exists, add `com.apple.developer.associated-domains` to it. If it does not exist, create it at the project root alongside the `.xcodeproj`.
+> 3. Add both entries using the actual Auth0 domain:
+
+```xml
+<key>com.apple.developer.associated-domains</key>
+<array>
+    <string>applinks:YOUR_AUTH0_DOMAIN</string>
+    <string>webcredentials:YOUR_AUTH0_DOMAIN</string>
+</array>
+```
+
+> - `applinks:` — routes the Universal Link callback back to your app after login
+> - `webcredentials:` — enables Password AutoFill and credential handoff with Auth0
+>
+> 4. If `com.apple.developer.associated-domains` already exists in the file, append the two `<string>` entries to the existing array rather than replacing it.
+> 5. If the file was newly created, check that `CODE_SIGN_ENTITLEMENTS` in the target's build settings points to it. If not, inform the user to set it in Xcode under target → Build Settings → Code Signing Entitlements.
+> 6. Ensure `.useHTTPS()` is called on the `webAuth()` builder:
+>    ```swift
+>    Auth0.webAuth().useHTTPS()
+>    ```
+
+### Verify Auth0.plist Target Membership
+
+In Xcode Project Navigator:
+1. Click `Auth0.plist`
+2. Open File Inspector (right panel, first tab)
+3. Under **Target Membership**, ensure your app target checkbox is checked
+
+### macOS Additional Steps
+
+For macOS targets, also:
+1. Select your app target → **Signing & Capabilities** tab
+2. Click **+ Capability** → add **Outgoing Connections (Client)**
+3. Register macOS callback URLs in Auth0 Dashboard:
+   ```text
+   https://YOUR_DOMAIN/macos/YOUR_BUNDLE_ID/callback,
+   YOUR_BUNDLE_ID://YOUR_DOMAIN/macos/YOUR_BUNDLE_ID/callback
+   ```
+
+---
+
+## SDK Installation
+
+> **Agent instruction:** Before proceeding, check the project directory for signs of an existing package manager:
+> - `Podfile` present → use **CocoaPods**
+> - `Cartfile` present → use **Carthage**
+> - `Package.swift` present → use **Swift Package Manager**
+>
+> If none are found, ask the user via `AskUserQuestion`: _"Which dependency manager does your project use — Swift Package Manager, CocoaPods, or Carthage?"_ Then follow only the matching section below.
+
+### Swift Package Manager (Recommended)
+
+#### Package.swift project
+
+Run in the project root:
+
+```bash
+swift package add-dependency https://github.com/auth0/Auth0.swift --from 2.18.0
+```
+
+Then add `"Auth0"` to the target's `dependencies` array in `Package.swift`:
+
+```swift
+.target(
+    name: "YourTarget",
+    dependencies: ["Auth0"]
+)
+```
+
+#### Xcode project (`.xcodeproj`, no `Package.swift`)
+
+The `swift package add-dependency` command does not apply to Xcode projects. Add the package via the Xcode GUI:
+
+1. **File → Add Package Dependencies**
+2. Enter package URL: `https://github.com/auth0/Auth0.swift`
+3. Select **Up to Next Major Version** starting from `2.18.0`
+4. Click **Add Package**
+5. In the package product list, ensure **Auth0** is added to your app target
+
+### CocoaPods
+
+```ruby
+# Podfile
+target 'YourApp' do
+  use_frameworks!
+  pod 'Auth0', '~> 2.18'
+end
+```
+
+```bash
+pod install
+# IMPORTANT: Always open .xcworkspace after pod install
+open YourApp.xcworkspace
+```
+
+### Carthage
+
+```text
+# Cartfile
+github "auth0/Auth0.swift" ~> 2.18
+```
+
+```bash
+# Build frameworks
+carthage update --use-xcframeworks --platform iOS
+
+# Then in Xcode: Target → General → "Frameworks, Libraries, and Embedded Content"
+# Drag in Carthage/Build/iOS/Auth0.xcframework
+```
+
+---
+
+## Secret Management
+
+Auth0.swift **does not use a client secret**. Native apps use PKCE (Proof Key for Code Exchange), which is secure without a secret.
+
+- `ClientId` and `Domain` in `Auth0.plist` are **not secrets** — they are safe to commit to source control
+- Access tokens and refresh tokens are stored in the iOS/macOS **Keychain** by `CredentialsManager` — never in `UserDefaults` or plain files
+- No environment variables or `.env` files are needed for the Auth0 configuration
+
+---
+
+## Verification
+
+After completing setup, verify:
+
+```bash
+# 1. Build the project
+xcodebuild build -scheme YOUR_SCHEME -destination "platform=iOS Simulator,name=iPhone 16"
+
+# 2. Verify Auth0.plist is bundled
+# Run app in Simulator and check Xcode console for Auth0 initialization
+```
+
+- [ ] `Auth0.plist` is in the project and in the app target
+- [ ] URL scheme `$(PRODUCT_BUNDLE_IDENTIFIER)` is registered in Info tab
+- [ ] Callback URLs are saved in Auth0 Dashboard
+- [ ] App builds without errors
+- [ ] `import Auth0` resolves without errors in Swift files
+
+---
+
+
+---
+
+## Major Version Migration
+
+
+# Auth0.swift v3 Migration
+
+Migrates an existing Auth0.swift v2 integration to v3. Every code change is gated on a search that confirms the project actually calls the affected API — if the project never uses `CredentialsManager`, no `CredentialsManager` code is touched. Changes follow the project's existing architecture and Apple platform conventions.
+
+## When NOT to Use
+
+- **New Auth0 integration** (no existing Auth0.swift): Use the Auth0 integration workflow for Swift
+- **Minor/patch update** (e.g., 2.17 → 2.18): Run `pod update Auth0` or update SPM — no migration needed
+- **Android apps**: Use the Auth0 integration workflow for Android
+- **React Native / Expo**: Use the Auth0 integration workflow for React Native or Expo
+
+## Prerequisites
+
+- Existing Auth0.swift v2 integration
+- Xcode installed; project builds cleanly on the current version
+- Project under git version control with a clean working tree
+
+---
+
+## Migration Workflow
+
+> **Agent instruction:** Execute every step in order. The goal is a green build with the smallest correct changeset. Each code-change step is gated by the Step 4 file-reading audit — if the API was not found in the project's source files, skip the entire step for that area. Never add code the project doesn't already call.
+
+---
+
+### Step 1 — Pre-flight & Safety Backup
+
+```bash
+# 1a. Verify clean working tree — stop if there are uncommitted changes
+git status --porcelain
+```
+
+If the output is non-empty, ask the user:
+> *"You have uncommitted changes. Should I stash them before proceeding (`git stash`), or would you like to commit first?"*
+
+```bash
+# 1b. Create a safety branch the user can reset to at any time
+git checkout -b auth0-v3-migration-backup
+git checkout -
+```
+
+```bash
+# 1c. Pick an available simulator, then confirm the project builds before touching anything
+SIM=$(xcrun simctl list devices available -j \
+  | python3 -c "import sys,json; d=json.load(sys.stdin); \
+    phones=[dev for devs in d['devices'].values() for dev in devs \
+            if 'iPhone' in dev.get('name','') and dev.get('isAvailable')]; \
+    print(phones[0]['name'] if phones else 'iPhone 16')")
+xcodebuild build \
+  -scheme <SCHEME> \
+  -destination "platform=iOS Simulator,name=${SIM}" \
+  2>&1 | tail -5
+```
+
+If the build fails, stop. Ask the user to fix the existing issues first.
+
+---
+
+### Step 2 — Detect Current & Target Versions
+
+Detect the current Auth0.swift version from the project's dependency files:
+
+```bash
+# Check Package.resolved first (most reliable)
+find . -name "Package.resolved" | xargs grep -A3 '"auth0/Auth0.swift"\|Auth0.swift"' 2>/dev/null | grep '"version"'
+
+# Fallback: Podfile.lock
+grep "^  - Auth0 " Podfile.lock 2>/dev/null
+
+# Fallback: Cartfile.resolved
+grep "auth0/Auth0.swift" Cartfile.resolved 2>/dev/null
+
+# Fallback: Package.swift
+grep -A2 'auth0/Auth0.swift' Package.swift 2>/dev/null
+```
+
+**Resolve the target version.** There are two paths:
+
+**Path A — the user passed a target version argument (`$ARGUMENTS`):**
+
+Validate it against the published releases before using it. It must pass **all three** checks:
+
+```bash
+# List all published Auth0.swift v3 release tags
+curl -s https://api.github.com/repos/auth0/Auth0.swift/releases | python3 -c "
+import sys, json
+releases = json.load(sys.stdin)
+v3 = [r for r in releases if r['tag_name'].startswith('3') and not r['draft']]
+for r in v3:
+    print(r['tag_name'])
+"
+```
+
+1. **Exists** — the requested tag appears in the published release list above.
+2. **Correct major** — the tag is within the **v3** major line (starts with `3`). A `2.x` or any other major is not valid; reject it.
+3. **Not a downgrade** — the tag is newer than the version detected in the project.
+
+> **On any check failing, STOP and ask the user.** Do not silently fall back. For example:
+> - *"`3.9.9` isn't a published Auth0.swift release. Published v3 releases are: `3.0.0-beta.2`, … . Please pass a valid v3 tag, or omit the argument to auto-resolve the latest v3 release."*
+> - *"`2.10.0` is a v2 release, not v3. This skill migrates to v3. Pass a v3 tag (e.g. `3.0.0-beta.2`) or omit the argument."*
+> - *"`3.0.0-beta.1` is older than the `3.0.0-beta.2` already in your project — that's a downgrade. Pass a newer v3 tag or omit the argument."*
+
+**Path B — no argument: auto-resolve the latest v3 release (including pre-releases):**
+
+```bash
+# Newest v3.x release tag (stable or pre-release), most recent first
+curl -s https://api.github.com/repos/auth0/Auth0.swift/releases | python3 -c "
+import sys, json
+releases = json.load(sys.stdin)
+v3 = [r for r in releases if r['tag_name'].startswith('3') and not r['draft']]
+if v3:
+    print(v3[0]['tag_name'])
+else:
+    print('')
+"
+```
+
+Record the result as `<TARGET_TAG>` and use it in every subsequent step.
+
+> **If `<TARGET_TAG>` is a pre-release** (contains `-beta`, `-rc`, etc.), inform the user before continuing:
+> *"The latest v3 release is `<TARGET_TAG>` (a pre-release). I'll migrate to that. You can pin a different tag by passing it as an argument: `auth0-swift-major-migration <tag>`."*
+>
+> **If no v3 release exists** (the resolver returns empty), stop and tell the user there is no published v3 release to migrate to.
+
+
+---
+
+### Step 3 — Fetch & Read the v3 SDK Source
+
+Fetch the actual Swift source for the target tag. The signatures here are the authoritative reference for every change made in Step 6.
+
+```bash
+TAG=<TARGET_TAG>   # the version the developer chose in Step 2, e.g. 3.0.0-beta.2
+
+# List all public Swift files in the SDK
+curl -s "https://api.github.com/repos/auth0/Auth0.swift/git/trees/${TAG}?recursive=1" \
+  | python3 -c "
+import sys, json
+for item in json.load(sys.stdin).get('tree', []):
+    if item['path'].startswith('Auth0/') and item['path'].endswith('.swift'):
+        print(item['path'])
+"
+
+# Fetch core public API files
+for FILE in WebAuth.swift CredentialsManager.swift Authentication.swift \
+            Credentials.swift UserProfile.swift Requestable.swift \
+            CredentialsStorage.swift CredentialsManagerError.swift WebAuthError.swift; do
+    URL="https://raw.githubusercontent.com/auth0/Auth0.swift/${TAG}/Auth0/${FILE}"
+    CONTENT=$(curl -sf "$URL")
+    [ -n "$CONTENT" ] && echo "=== $FILE ===" && echo "$CONTENT"
+done
+
+# MFA files live in a subdirectory
+for FILE in MFA/MFAClient.swift MFA/MFAErrors.swift; do
+    URL="https://raw.githubusercontent.com/auth0/Auth0.swift/${TAG}/Auth0/${FILE}"
+    CONTENT=$(curl -sf "$URL")
+    [ -n "$CONTENT" ] && echo "=== $FILE ===" && echo "$CONTENT"
+done
+```
+
+Read the fetched source and note:
+- Every public method signature that changed (return type, parameters, `throws` added)
+- Types that were renamed or removed
+- Protocol requirements that changed
+- Default parameter values that changed
+
+This is the ground truth. Every change in Step 6 must match a real signature in these files.
+
+---
+
+### Step 4 — Audit Which Auth0 APIs the Project Uses
+
+**Find all Swift files that import Auth0 — these are the scope of the migration:**
+```bash
+grep -rl "import Auth0" --include="*.swift" .
+```
+
+**Read every file from that list.** Do not grep for specific API patterns — read the full source so you can see exactly how `Auth0`, `webAuth`, `authentication`, `credentialsManager`, and any Auth0 types are used, including calls with domain/clientId parameters, chained builder calls, and any custom conformances.
+
+For each file, identify:
+
+| What to look for | Why it matters |
+|---|---|
+| Any call to `webAuth()`, `webAuth(domain:)`, `webAuth(domain:clientId:)` | §6.1 – `clearSession` rename; §6.14 – default scope |
+| Any call to `.clearSession(` | §6.1 — rename to `logout` |
+| Switch/catch on `WebAuthError` with explicit case names | §6.2 — removed and new cases |
+| `DispatchQueue.main.async` or `MainActor.run` wrapping an Auth0 callback | §6.3 — removable in v3 |
+| Any stored `Request<…>` type annotation (not just chained `.start(…)`) | §6.4 — type changed to `Requestable` |
+| Test mocks conforming to `Authentication`, `MFAClient`, or `Requestable` | §6.4 — return type + `@MainActor` update |
+| Any call to `credentialsManager.store(` | §6.5 — Bool → throws |
+| Any call to `credentialsManager.clear()` or `credentialsManager.clear(forAudience:` | §6.6 — Bool → throws (both overloads) |
+| Any access to `credentialsManager.user` (property, not method) | §6.7 — replaced by `userProfile()` method |
+| Any call to `credentialsManager.revoke(` | §6.8 — new error paths |
+| Any type annotation or declaration using `UserInfo` | §6.9 — renamed to `UserProfile` |
+| Any access to `.expiresIn` on a `Credentials`-like object | §6.10 — renamed to `expiresAt` |
+| Any type conforming to `CredentialsStorage` | §6.11 — method signatures changed |
+| Any call to `Auth0.users(` or `Auth0.users(token:` | §6.12 — Management client removed |
+| `login(withOTP:`, `login(withOOBCode:`, `login(withRecoveryCode:`, `multifactorChallenge(` | §6.13 — MFA methods removed |
+| Any call to `webAuth()` that does **not** chain `.scope(` | §6.14 — default scope changed |
+| Any call to `credentialsManager.credentials(` without explicit `minTTL:` parameter | §6.15 — default minTTL changed from 0 to 60 seconds |
+
+Build a checklist: **"This project uses: [list]"** and **"This project does NOT use: [list]"**. Only work through the §6.x sections that appear in the "uses" list. Skip the rest entirely.
+
+---
+
+### Step 5 — Update the SDK Dependency
+
+Apply only the matching package manager.
+
+Use the `<TARGET_TAG>` chosen in Step 2. For stable releases (`3.x.y` with no suffix), use a range specifier. For pre-releases (`3.x.y-beta.z`), pin the exact tag — package managers treat pre-release versions as out-of-range for `~>` / `from:` rules.
+
+**Swift Package Manager (Package.swift):**
+```swift
+// Stable v3 — range specifier picks up all 3.x.y patches
+.package(url: "https://github.com/auth0/Auth0.swift", from: "3.0.0")
+
+// Pre-release / specific beta — exact tag required
+.package(url: "https://github.com/auth0/Auth0.swift", exact: "3.0.0-beta.2")
+```
+
+Then resolve:
+```bash
+swift package resolve
+```
+
+**CocoaPods (Podfile):**
+```ruby
+# Stable v3
+pod 'Auth0', '~> 3.0'
+
+# Pre-release / specific beta — pin the exact version
+pod 'Auth0', '3.0.0-beta.2'
+```
+
+Then:
+```bash
+pod update Auth0
+```
+
+**Carthage (Cartfile):**
+```plaintext
+# Stable v3
+github "auth0/Auth0.swift" ~> 3.0
+
+# Pre-release / specific beta — pin the exact tag
+github "auth0/Auth0.swift" "3.0.0-beta.2"
+```
+
+Then:
+```bash
+carthage update Auth0.swift --use-xcframeworks
+```
+
+**Xcode-managed SPM** (no `Package.swift` at root):
+- *Stable:* File → Packages → Update to Latest Package Versions, then verify the version rule is *Up to Next Major* from 3.0.0.
+- *Pre-release / specific beta:* File → Packages → Update to Latest Package Versions won't resolve a beta unless the dependency already pins an exact version. Tell the user to change the version rule to *Exact Version* and enter `3.0.0-beta.2` (or the chosen tag).
+
+Do **not** build yet — apply all known code changes first.
+
+---
+
+### Step 6 — Apply Breaking Changes
+
+> **Agent instruction:** Work through only the §6.x sections that matched during the Step 4 file-reading audit. Skip every section whose API the project does not use — do not touch those files.
+>
+> Apply each change exactly as shown. Do not alter surrounding code, rename variables, reformat, or modernise code that isn't being migrated. Match the project's existing style: completion handler → completion handler, async/await → async/await, Combine → Combine.
+
+---
+
+#### 6.1 — `WebAuth.clearSession()` → `WebAuth.logout()`
+
+**Applies if:** Step 4 found any call to `.clearSession(` in the project's source files.
+
+The `clearSession(federated:)` method was renamed to `logout(federated:)`. The parameter and its default value are unchanged.
+
+**Completion handler:**
+```swift
+// v2
+Auth0.webAuth().clearSession { result in
+    switch result {
+    case .success: handleLogoutSuccess()
+    case .failure(let error): handleError(error)
+    }
+}
+
+// v3
+Auth0.webAuth().logout { result in
+    switch result {
+    case .success: handleLogoutSuccess()
+    case .failure(let error): handleError(error)
+    }
+}
+```
+
+**async/await:**
+```swift
+// v2
+try await Auth0.webAuth().clearSession()
+
+// v3
+try await Auth0.webAuth().logout()
+```
+
+**Combine:**
+```swift
+// v2
+Auth0.webAuth().clearSession()
+    .sink(receiveCompletion: { ... }, receiveValue: { ... })
+    .store(in: &cancellables)
+
+// v3
+Auth0.webAuth().logout()
+    .sink(receiveCompletion: { ... }, receiveValue: { ... })
+    .store(in: &cancellables)
+```
+
+**With `federated: true`:** The parameter name is the same — just rename the method:
+```swift
+// v2
+try await Auth0.webAuth().clearSession(federated: true)
+
+// v3
+try await Auth0.webAuth().logout(federated: true)
+```
+
+---
+
+#### 6.2 — `WebAuthError` — removed and new cases in exhaustive `switch` statements
+
+**Applies if:** Step 4 found any `switch` or `catch` on `WebAuthError` with explicit case names in the project's source files.
+
+Two `WebAuthError` cases were **removed** in v3. If the project has an exhaustive `switch` over `WebAuthError` (or explicitly matches these cases), the build will fail.
+
+Three **new** cases were added to surface previously hidden failures.
+
+**Removed cases (will no longer compile if matched):**
+
+| v2 case | v3 behaviour |
+|---|---|
+| `.invalidInvitationURL` | Removed — now surfaces as `.unknown` |
+| `.pkceNotAllowed` | Removed — now surfaces as `.unknown` |
+
+**New cases (can now appear in `catch`/`switch` blocks):**
+
+| v3 case | When it fires |
+|---|---|
+| `.authenticationFailed` | Server-side failure: wrong password, MFA required, account locked, etc. |
+| `.codeExchangeFailed` | Token exchange failed: network issue, invalid grant, backend error |
+| `.credentialsManagerError` | Credentials manager failed to store or clear credentials after login/logout; access the underlying error via `.cause` |
+
+**Migration — remove the deleted cases from switch statements:**
+```swift
+// v2 — exhaustive switch including cases that no longer exist
+Auth0.webAuth().start { result in
+    switch result {
+    case .success(let credentials):
+        handle(credentials)
+    case .failure(let error):
+        switch error {
+        case .userCancelled:
+            break  // user dismissed — no action needed
+        case .pkceNotAllowed:
+            // ❌ compile error in v3 — remove this case
+            showConfigError("PKCE not allowed")
+        default:
+            showError(error)
+        }
+    }
+}
+
+// v3 — remove the deleted cases; handle the new ones where appropriate
+Auth0.webAuth().start { result in
+    switch result {
+    case .success(let credentials):
+        handle(credentials)
+    case .failure(let error):
+        switch error {
+        case .userCancelled:
+            break  // user dismissed — no action needed
+        case .authenticationFailed:
+            // server rejected the login — show an appropriate message
+            showError("Login failed. Please check your credentials.")
+        case .codeExchangeFailed:
+            // token exchange failed — network or server issue
+            showError("Something went wrong. Please try again.")
+        case .credentialsManagerError:
+            // login succeeded but credentials could not be stored
+            // the user is authenticated in memory but will need to log in again next launch
+            // access the underlying error via error.cause (WebAuthError.cause: Error?)
+            reportToMonitoring(error.cause)
+            showError("Could not save your session.")
+        default:
+            showError(error)
+        }
+    }
+}
+```
+
+**If the project uses async/await and catches specific cases:**
+```swift
+// v2
+do {
+    let credentials = try await Auth0.webAuth().start()
+    handle(credentials)
+} catch WebAuthError.userCancelled {
+    break
+} catch WebAuthError.pkceNotAllowed {
+    // ❌ compile error in v3 — remove this catch
+    showConfigError()
+} catch {
+    showError(error)
+}
+
+// v3 — remove deleted cases; add new ones if the project should handle them
+do {
+    let credentials = try await Auth0.webAuth().start()
+    handle(credentials)
+} catch WebAuthError.userCancelled {
+    break
+} catch WebAuthError.authenticationFailed {
+    showError("Login failed. Please check your credentials.")
+} catch WebAuthError.codeExchangeFailed {
+    showError("Something went wrong. Please try again.")
+} catch {
+    showError(error)
+}
+```
+
+> The new cases `.authenticationFailed` and `.codeExchangeFailed` are not required to be handled explicitly — a `default:` branch already catches them. Only add explicit cases if the project wants to show different UI or telemetry for those failures.
+
+---
+
+#### 6.3 — Remove redundant main-thread dispatch around WebAuth and CredentialsManager callbacks
+
+**Applies if:** Step 4 found `DispatchQueue.main.async` or `MainActor.run` wrapping an Auth0 callback body.
+
+In v3, all completion-handler callbacks, Combine publishers, and async/await methods deliver results on the main thread (they are `@MainActor`). Wrapping callback bodies in `DispatchQueue.main.async { }` or `await MainActor.run { }` is no longer necessary and can be removed.
+
+**Completion handler callback — remove the dispatch wrapper:**
+```swift
+// v2 — dispatch to main manually
+credentialsManager.credentials { result in
+    DispatchQueue.main.async {
+        switch result {
+        case .success(let credentials):
+            self.accessToken = credentials.accessToken
+            self.isAuthenticated = true
+        case .failure(let error):
+            self.authError = error
+        }
+    }
+}
+
+// v3 — callback already arrives on main thread
+credentialsManager.credentials { result in
+    switch result {
+    case .success(let credentials):
+        self.accessToken = credentials.accessToken
+        self.isAuthenticated = true
+    case .failure(let error):
+        self.authError = error
+    }
+}
+```
+
+**async/await — remove the MainActor.run wrapper:**
+```swift
+// v2
+let credentials = try await Auth0.webAuth().start()
+await MainActor.run {
+    self.isAuthenticated = true
+}
+
+// v3 — start() is @MainActor; already on main thread after the await
+let credentials = try await Auth0.webAuth().start()
+self.isAuthenticated = true
+```
+
+> Only remove dispatch wrappers that are **solely** protecting Auth0 callback bodies. If a `DispatchQueue.main.async` block also dispatches unrelated UI work, remove only what's attributable to the Auth0 callback.
+
+---
+
+#### 6.4 — `Authentication` / `MFAClient` methods return `Requestable` instead of `Request` — app code and test mocks
+
+**Applies if:** Step 4 found either (a) a stored `Request<…>` type annotation in app code, or (b) test/mock files with types conforming to `Authentication`, `MFAClient`, or `Requestable`.
+
+In v3, all `Authentication` and `MFAClient` methods return protocol types rather than the concrete `Request` struct:
+
+- **Credential-returning methods** (login, codeExchange, renew, ssoExchange, etc.) now return `any TokenRequestable<T, E>`
+- **All other methods** (signup, resetPassword, userInfo, jwks, etc.) now return `any Requestable<T, E>`
+
+**Impact on app code:** Call sites that chain directly to `.start(_:)` — the overwhelming majority — compile without any change. The only app code that breaks is a stored `Request<>` type annotation:
+
+```swift
+// v2 — storing the request in a typed variable
+let request: Request<Credentials, AuthenticationError> = Auth0
+    .authentication()
+    .login(usernameOrEmail: email, password: password,
+           realmOrConnection: "Username-Password-Authentication",
+           audience: audience, scope: scope)
+request.start { result in ... }
+
+// v3 — update the type annotation to the protocol type
+// For credential-returning methods:
+let request: any TokenRequestable<Credentials, AuthenticationError> = Auth0
+    .authentication()
+    .login(usernameOrEmail: email, password: password,
+           realmOrConnection: "Username-Password-Authentication",
+           audience: audience, scope: scope)
+request.start { result in ... }
+
+// For non-credential methods (signup, resetPassword, userInfo, jwks):
+let request: any Requestable<DatabaseUser, AuthenticationError> = Auth0
+    .authentication()
+    .signup(email: email, password: password, connection: connection)
+request.start { result in ... }
+
+// Most common pattern — chaining directly, no annotation needed, no change required:
+Auth0.authentication()
+    .login(usernameOrEmail: email, password: password,
+           realmOrConnection: "Username-Password-Authentication",
+           audience: audience, scope: scope)
+    .start { result in ... }  // ✅ unchanged
+```
+
+**Credential-returning methods that now return `any TokenRequestable` (full list):**
+- `login(email:code:audience:scope:)`
+- `login(phoneNumber:code:audience:scope:)`
+- `login(usernameOrEmail:password:realmOrConnection:audience:scope:)`
+- `loginDefaultDirectory(withUsername:password:audience:scope:)`
+- `login(appleAuthorizationCode:fullName:profile:audience:scope:)`
+- `login(facebookSessionAccessToken:profile:audience:scope:)`
+- `login(passkey:challenge:connection:audience:scope:organization:)` — two overloads (sign in + sign up with passkey)
+- `codeExchange(withCode:codeVerifier:redirectURI:)`
+- `renew(withRefreshToken:audience:scope:)`
+- `ssoExchange(withRefreshToken:)`
+- `customTokenExchange(subjectToken:subjectTokenType:audience:scope:organization:parameters:)`
+- `MFAClient.verify(otp:mfaToken:)`, `verify(oobCode:bindingCode:mfaToken:)`, `verify(recoveryCode:mfaToken:)`
+
+**Impact on test targets — custom `Authentication` mocks:**
+
+If the project's test target has a mock or stub conforming to the `Authentication` or `MFAClient` protocol, two changes are required:
+
+1. **Return type:** Change `Request<T, E>` to `any TokenRequestable<T, E>` (credential methods) or `any Requestable<T, E>` (other methods)
+2. **`start(_:)` callback:** Add `@MainActor` to match the updated `Requestable` protocol requirement
+
+```swift
+// v2 — mock Authentication conformance in tests
+class MockAuthentication: Authentication {
+    var credentialsResult: Result<Credentials, AuthenticationError> = .failure(.init(info: [:], statusCode: 0))
+
+    func login(usernameOrEmail username: String,
+               password: String,
+               realmOrConnection realm: String,
+               audience: String?,
+               scope: String) -> Request<Credentials, AuthenticationError> {
+        // ❌ compile error in v3 — Request is no longer the return type
+        return Request(session: URLSession.shared, ...) // v2 internal — no longer works
+    }
+}
+
+// v2 — mock Requestable used as stub
+struct MockRequest<T, E: Auth0Error>: Requestable {
+    let result: Result<T, E>
+    func start(_ callback: @escaping (Result<T, E>) -> Void) {
+        // ❌ @MainActor missing — does not conform to v3 Requestable
+        callback(result)
+    }
+}
+
+// v3 — updated mock
+struct MockRequest<T, E: Auth0Error>: Requestable {
+    let result: Result<T, E>
+    // ✅ Add @MainActor to match the protocol; dispatch via Task to satisfy @MainActor isolation
+    func start(_ callback: @escaping @MainActor (Result<T, E>) -> Void) {
+        Task { @MainActor in callback(result) }
+    }
+}
+
+// v3 — updated Authentication mock returning the correct protocol type
+class MockAuthentication: Authentication {
+    var credentialsResult: Result<Credentials, AuthenticationError> = .failure(.init(info: [:], statusCode: 0))
+
+    func login(usernameOrEmail username: String,
+               password: String,
+               realmOrConnection realm: String,
+               audience: String?,
+               scope: String) -> any TokenRequestable<Credentials, AuthenticationError> {
+        // ✅ Return MockTokenRequest, not Request
+        return MockTokenRequest(result: credentialsResult)
+    }
+}
+
+// v3 — TokenRequestable mock (for credential-returning methods)
+struct MockTokenRequest<T, E: Auth0Error>: TokenRequestable {
+    typealias ResultType = T
+    typealias ErrorType = E
+
+    let result: Result<T, E>
+
+    func start(_ callback: @escaping @MainActor (Result<T, E>) -> Void) {
+        Task { @MainActor in callback(result) }
+    }
+
+    // TokenRequestable adds these claim-validation builder methods — return self
+    func validateClaims() -> any TokenRequestable<T, E> { self }
+    func withLeeway(_ leeway: Int) -> any TokenRequestable<T, E> { self }
+    func withIssuer(_ issuer: String) -> any TokenRequestable<T, E> { self }
+    func withNonce(_ nonce: String?) -> any TokenRequestable<T, E> { self }
+    func withMaxAge(_ maxAge: Int?) -> any TokenRequestable<T, E> { self }
+    func withOrganization(_ organization: String?) -> any TokenRequestable<T, E> { self }
+}
+```
+
+> The `MockTokenRequest` stub above stubs out all `TokenRequestable` builder methods by returning `self`. In most tests, `validateClaims()` and the `with*` modifiers are never called, so returning `self` is correct. If a specific test verifies claim validation behaviour, implement those methods properly.
+
+---
+
+#### 6.5 — `CredentialsManager.store(credentials:)` — Bool return → throws
+
+**Applies if:** Step 4 found any call to `credentialsManager.store(credentials:` in the project's source files.
+
+`store(credentials:)` previously returned `Bool`. In v3 it throws on failure and returns `Void` on success.
+
+**If the project checked the return value:**
+```swift
+// v2
+if credentialsManager.store(credentials: credentials) {
+    print("Stored successfully")
+} else {
+    print("Store failed")
+}
+
+// v3 — use do-catch; map the error into the project's existing error handler
+do {
+    try credentialsManager.store(credentials: credentials)
+} catch {
+    // replace with whatever logging/error handling the project already uses
+    handleError(error)
+}
+```
+
+**If the project discarded the return value:**
+```swift
+// v2 — silently discarded
+_ = credentialsManager.store(credentials: credentials)
+
+// v3 — try? discards the error the same way; use if the project didn't handle failures before
+try? credentialsManager.store(credentials: credentials)
+```
+
+> Prefer `do-catch` over `try?` when the project has an error-handling pattern to route into. Use `try?` only to preserve intentional silent-discard behaviour.
+
+---
+
+#### 6.6 — `CredentialsManager.clear()` and `clear(forAudience:scope:)` — Bool return → throws
+
+**Applies if:** Step 4 found any call to `credentialsManager.clear()` or `credentialsManager.clear(forAudience:` in the project's source files.
+
+Both overloads previously returned `Bool`. In v3 both throw:
+- `clear() throws` — clears the main stored credentials
+- `clear(forAudience:scope:) throws` — clears API credentials for a specific audience
+
+```swift
+// v2
+_ = credentialsManager.clear()
+_ = credentialsManager.clear(forAudience: "https://api.example.com")
+
+// v3
+try? credentialsManager.clear()
+try? credentialsManager.clear(forAudience: "https://api.example.com")
+// or, if the project handles errors:
+do {
+    try credentialsManager.clear()
+} catch {
+    handleError(error)
+}
+```
+
+---
+
+#### 6.7 — `CredentialsManager.user` property → `userProfile()` throwing method
+
+**Applies if:** Step 4 found any access to `credentialsManager.user` as a property (not a method call) in the project's source files.
+
+The `user: UserInfo?` computed property was replaced by `userProfile() throws -> UserProfile?` (see also §6.9 for the type rename).
+
+```swift
+// v2 — property access, returns UserInfo?
+func currentUser() -> UserInfo? {
+    return credentialsManager.user
+}
+
+// v3 — method call that throws, returns UserProfile?
+func currentUser() -> UserProfile? {
+    return try? credentialsManager.userProfile()
+}
+
+// v3 — if the project needs to surface errors:
+func loadUser() throws {
+    let profile = try credentialsManager.userProfile()
+    self.userProfile = profile
+}
+```
+
+---
+
+#### 6.8 — `CredentialsManager` async methods — new error paths from throwing storage
+
+**Applies if:** Step 4 found any call to `credentialsManager.revoke(` in the project's source files.
+
+Because `CredentialsManager` storage methods now throw, several async methods gain new failure paths that were previously silently swallowed. The most significant is `revoke()`. Only update error-handling code that the project actually writes — call sites that already use a `default:` branch need no change.
+
+**New errors that can now surface from `revoke()`:**
+
+| New error | When it fires | What to do |
+|---|---|---|
+| `.noCredentials` | `getEntry` threw — no credentials in storage, nothing to revoke | Treat as already logged out; navigate to login |
+| `.revokeFailed` | Network call to revoke the refresh token failed | The token may still be active on the server; show an error |
+| `.clearFailed` | Revocation succeeded but Keychain delete failed | Treat as logged out — the token is no longer valid server-side |
+
+```swift
+// v2 — only .revokeFailed was possible; missing credentials returned .success silently
+credentialsManager.revoke { result in
+    switch result {
+    case .success:
+        navigateToLogin()
+    case .failure(let error):
+        showError(error)  // only .revokeFailed reached here
+    }
+}
+
+// v3 — new cases surface; update the switch if the project checks specific cases
+credentialsManager.revoke { result in
+    switch result {
+    case .success:
+        navigateToLogin()
+    case .failure(let error):
+        switch error {
+        case .noCredentials:
+            // nothing was stored — already effectively logged out
+            navigateToLogin()
+        case .revokeFailed:
+            // server revocation failed — refresh token may still be active
+            showError("Could not revoke your session. Please try again.")
+        case .clearFailed:
+            // token revoked server-side but Keychain delete failed
+            // treat as logged out — token is no longer valid
+            navigateToLogin()
+        default:
+            showError(error)
+        }
+    }
+}
+```
+
+**New errors that can now surface from `credentials()`, `renew()`, `apiCredentials()`, `ssoCredentials()`:**
+
+| New error | When it fires |
+|---|---|
+| `.noCredentials` | `getEntry` throws (e.g., Keychain item not found) — previously swallowed by `try?` |
+| `.renewFailed` | Refresh token renewal request failed — network error, invalid/expired refresh token |
+| `.storeFailed` | Keychain write fails when saving renewed credentials |
+
+These only matter if the project's existing `catch`/`failure` handler needs to distinguish these cases. If it uses a generic fallback, no change is needed.
+
+```swift
+// v3 — if the project wants to distinguish storage failures from network failures:
+credentialsManager.credentials { result in
+    switch result {
+    case .success(let credentials):
+        use(credentials)
+    case .failure(let error):
+        switch error {
+        case .noCredentials, .renewFailed:
+            // credentials missing or refresh failed — force re-login
+            navigateToLogin()
+        case .storeFailed:
+            // renewed successfully but couldn't save — credentials valid in memory this session
+            // user will be asked to log in again on next launch
+            reportToMonitoring(error)
+            use(/* last known credentials if available */)
+        default:
+            showError(error)
+        }
+    }
+}
+```
+
+> Only add these new `case` branches if the project currently has a `switch` on `CredentialsManagerError` that would benefit from handling them differently. A `default:` branch already handles them correctly without any change.
+
+---
+
+#### 6.9 — `UserInfo` → `UserProfile` type rename
+
+**Applies if:** Step 4 found any type annotation, function signature, or variable declaration referencing `UserInfo` in the project's source files.
+
+The `UserInfo` type was renamed to `UserProfile`. Update every type annotation, function signature, and variable declaration that references `UserInfo`.
+
+```swift
+// v2
+var currentUser: UserInfo?
+func showProfile(_ profile: UserInfo) { ... }
+func fetchUser() -> UserInfo? { ... }
+
+// v3
+var currentUser: UserProfile?
+func showProfile(_ profile: UserProfile) { ... }
+func fetchUser() -> UserProfile? { ... }
+```
+
+If the project calls `Auth0.authentication().userInfo(withAccessToken:)`, the method name is unchanged but the return type changed:
+```swift
+// v2 — returns Request<UserInfo, AuthenticationError>
+Auth0.authentication()
+    .userInfo(withAccessToken: accessToken)
+    .start { (result: Result<UserInfo, AuthenticationError>) in ... }
+
+// v3 — returns Request<UserProfile, AuthenticationError>
+Auth0.authentication()
+    .userInfo(withAccessToken: accessToken)
+    .start { (result: Result<UserProfile, AuthenticationError>) in ... }
+```
+
+---
+
+#### 6.10 — `Credentials.expiresIn` → `Credentials.expiresAt`
+
+**Applies if:** Step 4 found any access to `.expiresIn` on a `Credentials`, `APICredentials`, or `SSOCredentials` object.
+
+The `expiresIn: Date` property on `Credentials`, `APICredentials`, and `SSOCredentials` was renamed to `expiresAt: Date`. The underlying JSON key is unchanged; only the Swift property name changed.
+
+```swift
+// v2
+let expiry: Date = credentials.expiresIn
+
+// v3
+let expiry: Date = credentials.expiresAt
+```
+
+---
+
+#### 6.11 — `CredentialsStorage` custom implementation — methods now throw
+
+**Applies if:** Step 4 found a type conforming to `CredentialsStorage` in the project's source files. Skip if the project only passes a `SimpleKeychain` instance — the default storage needs no change.
+
+Only applies if the project provides a **custom** `CredentialsStorage` implementation (i.e., a type conforming to the protocol — not just using the default `SimpleKeychain`). Skip if the project only passes a `SimpleKeychain` instance.
+
+The protocol changed from Bool/Data? returns to throwing methods, and added a new required `deleteAllEntries()`.
+
+```swift
+// v2 — protocol conformance
+final class AppKeychain: CredentialsStorage {
+    func getEntry(forKey key: String) -> Data? {
+        return Keychain.shared.read(key: key)
+    }
+
+    func setEntry(_ data: Data, forKey key: String) -> Bool {
+        return Keychain.shared.write(data, forKey: key)
+    }
+
+    func deleteEntry(forKey key: String) -> Bool {
+        return Keychain.shared.delete(key: key)
+    }
+}
+
+// v3 — methods throw; deleteAllEntries() required
+final class AppKeychain: CredentialsStorage {
+    func getEntry(forKey key: String) throws -> Data {
+        guard let data = Keychain.shared.read(key: key) else {
+            throw CredentialsManagerError.noCredentials
+        }
+        return data
+    }
+
+    func setEntry(_ data: Data, forKey key: String) throws {
+        guard Keychain.shared.write(data, forKey: key) else {
+            throw CredentialsManagerError.storeFailed
+        }
+    }
+
+    func deleteEntry(forKey key: String) throws {
+        guard Keychain.shared.delete(key: key) else {
+            throw CredentialsManagerError.revokeFailed
+        }
+    }
+
+    func deleteAllEntries() throws {
+        Keychain.shared.deleteAll()
+    }
+}
+```
+
+> The `CredentialsStorage` protocol declares its methods as `throws` with no specific error type — you can throw any `Error`. The example above uses `CredentialsManagerError` cases for illustration only; your implementation should throw an error type that makes sense for your storage backend. Verify the `CredentialsManagerError` case names in the SDK source fetched in Step 3 if you choose to reuse them.
+
+---
+
+#### 6.12 — Management client removed
+
+**Applies if:** Step 4 found any call to `Auth0.users(` or `Auth0.users(token:` in the project's source files.
+
+`Auth0.users(token:)` and the entire `Users` management client were removed from the SDK in v3. Do **not** silently delete any call sites — add a `TODO` comment and surface this in the migration summary.
+
+```swift
+// v2 — direct Management API call in the app
+Auth0
+    .users(token: managementToken)
+    .patch(userId, userPatch: UserPatchAttributes(name: newName))
+    .start { result in
+        switch result {
+        case .success: print("Updated")
+        case .failure(let error): print(error)
+        }
+    }
+
+// v3 — Management client removed; add TODO and preserve intent
+// TODO: Auth0.swift v3 removed the Management client.
+// Replace this with a call to your own backend endpoint, which
+// calls the Auth0 Management API using a machine-to-machine token.
+// NEVER embed a Management API token in the client app.
+// See: https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens
+```
+
+This **requires backend work** — record it in the Step 9 summary.
+
+---
+
+#### 6.13 — MFA methods removed from `Authentication` → migrate to `MFAClient`
+
+**Applies if:** Step 4 found any call to `login(withOTP:`, `login(withOOBCode:`, `login(withRecoveryCode:`, or `multifactorChallenge(` — or test mocks conforming to `MFAClient` — in the project's source files.
+
+The four MFA methods on the `Authentication` protocol were removed in v3. They are replaced by the dedicated `MFAClient` protocol, accessible via `Auth0.mfa()`:
+
+| v2 (`Authentication`) | v3 (`MFAClient`) |
+|---|---|
+| `authentication().login(withOTP: otp, mfaToken: token)` | `mfa().verify(otp: otp, mfaToken: token)` |
+| `authentication().login(withOOBCode: code, mfaToken: token, bindingCode: binding)` | `mfa().verify(oobCode: code, bindingCode: binding, mfaToken: token)` |
+| `authentication().login(withRecoveryCode: code, mfaToken: token)` | `mfa().verify(recoveryCode: code, mfaToken: token)` |
+| `authentication().multifactorChallenge(mfaToken: token, types: types, authenticatorId: id)` | `mfa().challenge(with: id, mfaToken: token)` |
+
+**The `mfaToken` itself** still comes from the same place — an `AuthenticationError` where `error.isMultifactorRequired == true` returns the token via `error.mfaRequiredErrorPayload?.mfaToken`.
+
+---
+
+**OTP (TOTP authenticator app):**
+```swift
+// v2
+Auth0.authentication()
+    .login(withOTP: otpCode, mfaToken: mfaToken)
+    .start { result in
+        switch result {
+        case .success(let credentials): storeCredentials(credentials)
+        case .failure(let error): showError(error)
+        }
+    }
+
+// v3 — verify returns any TokenRequestable<Credentials, MFAVerifyError>
+Auth0.mfa()
+    .verify(otp: otpCode, mfaToken: mfaToken)
+    .start { result in
+        switch result {
+        case .success(let credentials): storeCredentials(credentials)
+        case .failure(let error): showError(error)
+        }
+    }
+
+// async/await
+let credentials = try await Auth0.mfa().verify(otp: otpCode, mfaToken: mfaToken).start()
+```
+
+---
+
+**OOB (SMS / email code):**
+```swift
+// v2
+Auth0.authentication()
+    .login(withOOBCode: oobCode, mfaToken: mfaToken, bindingCode: bindingCode)
+    .start { result in ... }
+
+// v3 — parameter order changed: oobCode first, bindingCode second
+Auth0.mfa()
+    .verify(oobCode: oobCode, bindingCode: bindingCode, mfaToken: mfaToken)
+    .start { result in ... }
+```
+
+---
+
+**Recovery code:**
+```swift
+// v2
+Auth0.authentication()
+    .login(withRecoveryCode: recoveryCode, mfaToken: mfaToken)
+    .start { result in ... }
+
+// v3
+Auth0.mfa()
+    .verify(recoveryCode: recoveryCode, mfaToken: mfaToken)
+    .start { result in ... }
+```
+
+---
+
+**MFA challenge (request an OOB code to be sent):**
+```swift
+// v2
+Auth0.authentication()
+    .multifactorChallenge(mfaToken: mfaToken,
+                          types: ["oob"],
+                          authenticatorId: authenticatorId)
+    .start { result in ... }
+
+// v3 — types parameter removed; pass authenticatorId directly
+Auth0.mfa()
+    .challenge(with: authenticatorId, mfaToken: mfaToken)
+    .start { result in ... }
+```
+
+---
+
+**Handling the MFA required error to obtain the mfaToken (unchanged between v2 and v3):**
+```swift
+Auth0.authentication()
+    .login(usernameOrEmail: email,
+           password: password,
+           realmOrConnection: "Username-Password-Authentication",
+           audience: audience,
+           scope: scope)
+    .start { result in
+        switch result {
+        case .success(let credentials):
+            storeCredentials(credentials)
+        case .failure(let error) where error.isMultifactorRequired:
+            // mfaToken extracted the same way in both v2 and v3
+            if let mfaToken = error.mfaRequiredErrorPayload?.mfaToken {
+                presentMFAChallenge(mfaToken: mfaToken)
+            }
+        case .failure(let error):
+            showError(error)
+        }
+    }
+```
+
+---
+
+**Error type changed: `AuthenticationError` → `MFAVerifyError`**
+
+The verify methods on `MFAClient` return `any TokenRequestable<Credentials, MFAVerifyError>`. If the project previously matched specific `AuthenticationError` cases in MFA failure handlers, map them onto `MFAVerifyError`:
+
+```swift
+// v2 — MFA failures came as AuthenticationError
+Auth0.authentication()
+    .login(withOTP: otp, mfaToken: mfaToken)
+    .start { result in
+        switch result {
+        case .success(let credentials): storeCredentials(credentials)
+        case .failure(let error as AuthenticationError):
+            if error.isMultifactorCodeInvalid {
+                showError("Invalid code. Please try again.")
+            } else {
+                showError(error.debugDescription)
+            }
+        }
+    }
+
+// v3 — failures come as MFAVerifyError; fetch MFAErrors.swift for all cases
+Auth0.mfa()
+    .verify(otp: otp, mfaToken: mfaToken)
+    .start { result in
+        switch result {
+        case .success(let credentials): storeCredentials(credentials)
+        case .failure(let error):
+            // Check the MFAVerifyError cases in Auth0/MFA/MFAErrors.swift
+            // for the exact case names available in the target SDK version
+            showError(error.debugDescription)
+        }
+    }
+```
+
+> Fetch `Auth0/MFA/MFAErrors.swift` from the target tag (Step 3) and read the `MFAVerifyError` cases to map any specific error handling the project currently does. Do not guess error case names — read them from the source.
+
+---
+
+**Test mocks for `MFAClient`:**
+
+If the project's test target has a mock conforming to `MFAClient`, update method return types and add `@MainActor` to `start(_:)` (same pattern as §6.4 for `Authentication` mocks):
+
+```swift
+// v3 — mock MFAClient in tests
+struct MockMFAClient: MFAClient {
+    var verifyResult: Result<Credentials, MFAVerifyError>
+
+    func verify(otp: String,
+                mfaToken: String) -> any TokenRequestable<Credentials, MFAVerifyError> {
+        return MockTokenRequest(result: verifyResult)
+    }
+
+    func verify(oobCode: String,
+                bindingCode: String?,
+                mfaToken: String) -> any TokenRequestable<Credentials, MFAVerifyError> {
+        return MockTokenRequest(result: verifyResult)
+    }
+
+    func verify(recoveryCode: String,
+                mfaToken: String) -> any TokenRequestable<Credentials, MFAVerifyError> {
+        return MockTokenRequest(result: verifyResult)
+    }
+
+    func challenge(with authenticatorId: String,
+                   mfaToken: String) -> any Requestable<MFAChallenge, MfaChallengeError> {
+        // Fetch MFAClient.swift from the target tag to find MFAChallenge's initializer,
+        // then construct a real fixture or return .failure for tests that don't exercise this path
+        return MockRequest(result: .failure(/* MfaChallengeError case from MFAErrors.swift */))
+    }
+    // implement remaining MFAClient requirements using the same pattern
+}
+```
+
+> Use the `MockTokenRequest` and `MockRequest` structs from §6.4. The `MFAClient` protocol also requires `getAuthenticators`, `enroll(mfaToken:phoneNumber:)`, `enroll(mfaToken:)`, and `enroll(mfaToken:email:)` — stub them the same way, using the return types from `MFAClient.swift`.
+
+List all migrated MFA flows in the Step 9 summary and ask the user to **re-test every MFA flow end-to-end** (OTP, OOB, recovery code, challenge request) against their tenant configuration.
+
+---
+
+#### 6.14 — Default scope now includes `offline_access`
+
+**Applies if:** Step 4 found any call to `webAuth()`, `webAuth(domain:)`, or `webAuth(domain:clientId:)` — but only for call chains that do **not** already have a `.scope(…)` modifier. Read the actual call site in the file to confirm whether `.scope(` is present; do not grep — the call chain may span multiple lines.
+
+In v3, the default scope changed from `"openid profile email"` to `"openid profile email offline_access"`. Apps that relied on the default and do **not** want a refresh token should add an explicit `.scope()` call:
+
+```swift
+// v2 — default scope: "openid profile email" (no refresh token)
+Auth0.webAuth()
+    .audience("https://api.example.com")
+    .start { result in ... }
+
+// v3 — default scope includes offline_access (refresh token returned)
+// If you want to keep the v2 behaviour (no refresh token), add .scope() explicitly:
+Auth0.webAuth()
+    .audience("https://api.example.com")
+    .scope("openid profile email")  // explicit — no offline_access
+    .start { result in ... }
+
+// If refresh tokens are welcome (recommended — enables silent renewal):
+// No change needed; the new default is intentional.
+```
+
+Surface this as a **behavioural change** in the Step 9 summary regardless of which path is chosen — the Auth0 tenant must permit offline access for this app if refresh tokens are to be issued.
+
+---
+
+#### 6.15 — `CredentialsManager.credentials()` — default `minTTL` changed from 0 to 60 seconds
+
+**Applies if:** Step 4 found any call to `credentialsManager.credentials(` without an explicit `minTTL:` parameter.
+
+In v3, `CredentialsManager.credentials(withScope:minTTL:parameters:headers:callback:)` defaults `minTTL` to `60` instead of `0`. This means the credentials manager will now consider tokens expired — and trigger a silent refresh — 60 seconds before their actual expiry, rather than only when they are already expired.
+
+This is a **silent behavioural change**: the app still compiles without changes, but token renewal now happens earlier than before.
+
+```swift
+// v2 — credentials() triggers renewal only when token is actually expired (minTTL default: 0)
+credentialsManager.credentials { result in
+    switch result {
+    case .success(let credentials): use(credentials)
+    case .failure(let error): handleError(error)
+    }
+}
+
+// v3 — credentials() triggers renewal 60 seconds before expiry (minTTL default: 60)
+// No code change needed if this behaviour is acceptable (recommended for most apps).
+// To restore the v2 behaviour explicitly:
+credentialsManager.credentials(minTTL: 0) { result in
+    switch result {
+    case .success(let credentials): use(credentials)
+    case .failure(let error): handleError(error)
+    }
+}
+```
+
+For most apps the new default is preferable — renewing tokens slightly before expiry avoids races where an in-flight request uses an access token that expires mid-request. Only set `minTTL: 0` explicitly if the app has a specific reason to renew only at exact expiry.
+
+Surface this as a **behavioural note** in the Step 9 summary.
+
+---
+
+### Step 7 — Update the Dependency & Build
+
+```bash
+# Attempt a build — expect errors for any remaining call sites
+xcodebuild build \
+  -scheme <SCHEME> \
+  -destination "platform=iOS Simulator,name=${SIM}" \
+  2>&1
+```
+
+For each error:
+
+1. Read the error and locate the source line
+2. Match it to one of the API changes in Step 6
+3. Verify the fix matches the actual SDK signature fetched in Step 3
+4. Apply the fix in keeping with the project's existing style
+5. Rebuild
+
+**Common error → cause mapping:**
+
+| Xcode error | Likely cause |
+|---|---|
+| `has no member 'clearSession'` | §6.1 — rename to `logout` |
+| `error enum element 'pkceNotAllowed' not found in type` or `'invalidInvitationURL' not found` | §6.2 — remove deleted `WebAuthError` cases from switch |
+| `cannot convert return expression of type 'Request<...>'` in mock | §6.4 — update mock return type to `any TokenRequestable<T,E>` or `any Requestable<T,E>` |
+| `does not conform to protocol 'Requestable'` (missing `@MainActor` on `start`) | §6.4 — add `@MainActor` to `start(_:)` callback in mock |
+| `has no member 'user'` on CredentialsManager | §6.7 — change to `userProfile()` |
+| `cannot find type 'UserInfo'` | §6.9 — rename to `UserProfile` |
+| `has no member 'expiresIn'` | §6.10 — rename to `expiresAt` |
+| `cannot convert value of type 'Bool'` on store/clear | §6.5/§6.6 — add do-catch or try? |
+| `does not conform to protocol 'CredentialsStorage'` | §6.11 — update protocol methods + add deleteAllEntries |
+| `call can throw, but is not marked with 'try'` | wrap in do-catch or add try? |
+| `sending '...' risks causing data races` | only appears when the project uses Swift 6 language mode or `SWIFT_STRICT_CONCURRENCY=complete`; resolve within the existing actor model — not a migration error |
+
+**Limit:** Up to **10 build-fix cycles**. If the build still fails after 10 attempts, stop and show the remaining errors to the user with context — do not guess.
+
+---
+
+### Step 8 — Run Tests & Verify
+
+```bash
+# Run the test suite if one exists (reuse $SIM from Step 1)
+xcodebuild test \
+  -scheme <SCHEME> \
+  -destination "platform=iOS Simulator,name=${SIM}" \
+  2>&1 | tail -30
+```
+
+Test failures caused by the same API changes (wrong type name, missing method) should be fixed using the same rules as Step 7. Test failures that require logic changes beyond API updates should be flagged for the user.
+
+```bash
+# Summarise the diff
+git diff --stat
+```
+
+---
+
+### Step 9 — Migration Summary
+
+Present a concise summary covering:
+
+**1. Changes applied** (grouped by API area; list files touched per area)
+
+**2. Needs manual review**
+- Every error-handling change — confirm the new error types are routed correctly
+- Every `try?` used to discard errors where the project previously discarded a `Bool` — ask if explicit error handling is wanted
+- The `offline_access` default scope change — confirm the tenant is configured to allow it, or confirm the explicit scope call is correct
+
+**3. Backend / configuration follow-up** (only if triggered)
+- **WebAuthError cases changed (§6.2):** List which removed cases were deleted from switch statements and which new cases were added. Note that `.authenticationFailed` and `.codeExchangeFailed` may benefit from user-facing copy changes.
+- **`Request` → `Requestable` in mocks (§6.4):** List which test mock files were updated. Note any `TokenRequestable` builder methods that were stubbed with `return self` — confirm this is correct for the tests involved.
+- **New error paths (§6.8):** List which CredentialsManager async methods the project calls and note the new errors that can now surface:
+  - `revoke()` — `.noCredentials` (nothing to revoke), `.revokeFailed` (server revocation failed), `.clearFailed` (token revoked but Keychain delete failed)
+  - `credentials()` / `renew()` / `apiCredentials()` / `ssoCredentials()` — `.noCredentials` (Keychain item not found), `.renewFailed` (refresh token renewal failed), `.storeFailed` (renewed credentials could not be saved)
+  - Confirm the failure handling for each case navigates or surfaces errors correctly.
+- **Management client removed (§6.12):** List the specific operations that were stubbed with `TODO`. Describe what the user must implement on a secure backend.
+- **MFA methods removed (§6.13):** List which MFA flows need updating to `MFAClient`. Ask the user to re-test MFA end-to-end.
+- **Default scope change (§6.14):** Note whether `.scope()` was added explicitly or the new `offline_access` default was accepted. Confirm the tenant is configured to allow offline access.
+- **Default minTTL change (§6.15):** Note that `credentialsManager.credentials()` now renews tokens 60 seconds before expiry instead of at exact expiry. Confirm this is acceptable or that `minTTL: 0` was set explicitly.
+
+**4. Optional improvements not applied** (list briefly; never auto-apply)
+- New `clearAll()` method on `CredentialsManager` — clears all credentials in one call
+- New `MFAClient` API — if the project uses MFA and the old methods were already removed
+- DPoP (Demonstrating Proof of Possession) support — if the API requires sender-constrained tokens
+- Passkey login/signup APIs (iOS 16.6+, macOS 13.5+)
+- `ssoCredentials()` — if SSO credential exchange is needed
+
+**5. Ask the user** if they'd like to commit the migration changes, explore any optional improvement, or step through specific files together.
+
+**Security reminder:** Never include tokens, secrets, client credentials, or Keychain values in the summary output.
+
+---
+
+## Detailed References
+
+- **Migration Process** (see the Migration Process section below) — Multi-version jumps, rollback, CocoaPods/Carthage edge cases, Swift version compatibility
+- **Security Checklist** (see the Security Checklist section below) — Invariants that must hold before and after migration
+
+## Common Mistakes
+
+| Mistake | Correct approach |
+|---|---|
+| Applying a §6.x section when Step 4 didn't find that API in the project | Step 4 file-reading is the gate. Not found = skip the section entirely |
+| Using grep alone to decide if an API is used | Grep misses multi-line call chains, calls with `domain:clientId:` params, and variable aliases. Read the actual files |
+| Touching `CredentialsManager` when the project doesn't use it | Only migrate what the project actually calls |
+| Removing `DispatchQueue.main` wrappers around non-Auth0 code | Only remove dispatch wrappers that are solely inside an Auth0 callback body |
+| Silently deleting Management API call sites | Add `// TODO:` and surface in the summary — removing the call breaks functionality |
+| Silently deleting old MFA call sites | Same as above — add `TODO` and note in the summary |
+| Applying changes based on assumed knowledge, not the fetched SDK source | Every fix must trace to a signature in the files fetched in Step 3 |
+| Pinning `from: "3.0.0"` when the developer chose a beta tag | Stable range specifiers won't resolve betas; use `exact: "<TAG>"` for pre-releases |
+| Starting migration on a dirty working tree | Always verify `git status --porcelain` is empty first |
+| Skipping straight to build without applying known changes first | Apply all known changes first, then build to catch remainders |
+| Continuing past 10 failed build cycles | Stop and show the user the remaining errors |
+| Skipping the migration summary | Always produce the full summary — the user needs it |
+
+## Related Capabilities
+
+- New Auth0.swift integration from scratch — the Auth0 integration workflow for Swift
+- Android native authentication — the Auth0 integration workflow for Android
+
+---
+
+## References
+
+- [Auth0.swift GitHub](https://github.com/auth0/Auth0.swift)
+- [Auth0.swift Releases](https://github.com/auth0/Auth0.swift/releases)
+- [Auth0.swift API Documentation](https://auth0.github.io/Auth0.swift/documentation/auth0/)
+
+> **Security:** Never echo tokens, client secrets, or credentials in build logs or terminal output. Never commit secrets to version control.
diff --git a/main/.mintlify/skills/auth0/references/framework-vue/index.md b/main/.mintlify/skills/auth0/references/framework-vue/index.md
new file mode 100644
index 0000000000..4e4362960c
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-vue/index.md
@@ -0,0 +1,1078 @@
+
+# Auth0 Vue.js Integration
+
+Add authentication to Vue.js 3 single-page applications using @auth0/auth0-vue.
+
+## Critical rules
+
+- Before running any setup step that writes to `.env`, you MUST ask the user for explicit confirmation and wait for their answer.
+- Never read the contents of `.env`; if you must, ask the user for explicit permission first.
+
+## Prerequisites
+
+- Vue 3+ application (Vite or Vue CLI)
+- Auth0 account and application configured
+- If Auth0 isn't set up yet, set it up first with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+
+## When NOT to Use
+
+- **Server-side rendered Vue apps** - See [Auth0 Nuxt.js guide](https://auth0.com/docs/quickstart/webapp/nuxt) for SSR patterns
+- **Vue 2 applications** - This SDK requires Vue 3+, use legacy @auth0/auth0-spa-js wrapper
+- **Embedded login** - This SDK uses Auth0 Universal Login (redirect-based)
+- **Backend API authentication** - Use express-openid-connect or JWT validation instead
+
+## Quick Start Workflow
+
+### 1. Install SDK
+
+```bash
+npm install @auth0/auth0-vue
+```
+
+### 2. Configure Environment
+
+**For automated setup with Auth0 CLI**, see the Setup Guide section below for complete scripts.
+
+**For manual setup:**
+
+Create `.env` file:
+
+```bash
+VITE_AUTH0_DOMAIN=your-tenant.auth0.com
+VITE_AUTH0_CLIENT_ID=your-client-id
+```
+
+### 3. Configure Auth0 Plugin
+
+Update `src/main.ts`:
+
+```typescript
+import { createApp } from 'vue';
+import { createAuth0 } from '@auth0/auth0-vue';
+import App from './App.vue';
+
+const app = createApp(App);
+
+app.use(
+  createAuth0({
+    domain: import.meta.env.VITE_AUTH0_DOMAIN,
+    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+    authorizationParams: {
+      redirect_uri: window.location.origin
+    }
+  })
+);
+
+app.mount('#app');
+```
+
+### 4. Add Authentication UI
+
+Create a login component:
+
+```vue
+<script setup lang="ts">
+import { useAuth0 } from '@auth0/auth0-vue';
+
+const { loginWithRedirect, logout, isAuthenticated, user, isLoading } = useAuth0();
+</script>
+
+<template>
+  <div>
+    <div v-if="isLoading">Loading...</div>
+
+    <div v-else-if="isAuthenticated">
+      <img :src="user?.picture" :alt="user?.name" />
+      <span>Welcome, {{ user?.name }}</span>
+      <button @click="logout({ logoutParams: { returnTo: window.location.origin }})">
+        Logout
+      </button>
+    </div>
+
+    <button v-else @click="loginWithRedirect()">
+      Login
+    </button>
+  </div>
+</template>
+```
+
+### 5. Test Authentication
+
+Start your dev server and test the login flow:
+
+```bash
+npm run dev
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Forgot to add redirect URI in Auth0 Dashboard | Add your application URL (e.g., `http://localhost:3000`, `https://app.example.com`) to Allowed Callback URLs in Auth0 Dashboard |
+| Using wrong env var prefix | Vite requires `VITE_` prefix, Vue CLI uses `VUE_APP_` |
+| Not handling loading state | Always check `isLoading` before rendering auth-dependent UI |
+| Storing tokens in localStorage | Never manually store tokens - SDK handles secure storage automatically |
+| Missing createAuth0 plugin registration | Must call `app.use(createAuth0({...}))` before mounting app |
+| Accessing auth before plugin loads | Wrap auth-dependent code in `v-if="!isLoading"` |
+
+## Related Capabilities
+
+- Initial Auth0 setup → set it up with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Migrating from another auth provider → ask for migration (migrate)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- Managing Auth0 resources from the terminal → the Auth0 CLI (`tooling-cli`)
+
+## Quick Reference
+
+**Core Composables:**
+- `useAuth0()` - Main authentication composable
+- `isAuthenticated` - Reactive check if user is logged in
+- `user` - Reactive user profile information
+- `loginWithRedirect()` - Initiate login
+- `logout()` - Log out user
+- `getAccessTokenSilently()` - Get access token for API calls
+
+**DPoP composables** (require `useDpop: true` in `createAuth0` config):
+- `createFetcher(config)` — returns a DPoP-aware `fetch`-compatible function
+- `generateDpopProof(params)` — manually generate a DPoP proof JWT
+- `getDpopNonce(id?)` / `setDpopNonce(nonce, id?)` — read/store the server DPoP nonce
+For full DPoP setup, ask for DPoP token binding (feature:dpop).
+
+**Common Use Cases:**
+- Login/Logout buttons → See Step 4 above
+- Protected routes with navigation guards → see the Protected Routes section below
+- API calls with tokens → see the Calling APIs section below
+- Error handling → see the Error Handling section below
+
+## References
+
+- [Auth0 Vue SDK Documentation](https://auth0.com/docs/libraries/auth0-vue)
+- [Auth0 Vue Quickstart](https://auth0.com/docs/quickstart/spa/vuejs)
+- [SDK GitHub Repository](https://github.com/auth0/auth0-vue)
+
+---
+
+## Common Patterns
+
+### Protected Route (Vue Router)
+
+**Install Vue Router:**
+```bash
+npm install vue-router
+```
+
+**Configure router (`src/router/index.ts`):**
+```typescript
+import { createRouter, createWebHistory } from 'vue-router';
+import { createAuthGuard } from '@auth0/auth0-vue';
+import Home from '../views/Home.vue';
+import Profile from '../views/Profile.vue';
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    {
+      path: '/',
+      name: 'Home',
+      component: Home
+    },
+    {
+      path: '/profile',
+      name: 'Profile',
+      component: Profile,
+      beforeEnter: createAuthGuard()  // Protect this route
+    }
+  ]
+});
+
+export default router;
+```
+
+**Alternative: Use the exported `authGuard` directly:**
+```typescript
+import { createRouter, createWebHistory } from 'vue-router';
+import { authGuard } from '@auth0/auth0-vue';
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    {
+      path: '/profile',
+      component: () => import('../views/Profile.vue'),
+      beforeEnter: authGuard  // Use the pre-configured guard
+    }
+  ]
+});
+```
+
+---
+
+### Get User Profile
+
+```vue
+<script setup lang="ts">
+import { useAuth0 } from '@auth0/auth0-vue';
+
+const { user, isAuthenticated } = useAuth0();
+</script>
+
+<template>
+  <div v-if="isAuthenticated">
+    <h1>Profile</h1>
+    <img :src="user?.picture" :alt="user?.name" />
+    <p>Name: {{ user?.name }}</p>
+    <p>Email: {{ user?.email }}</p>
+    <p>User ID: {{ user?.sub }}</p>
+  </div>
+  <div v-else>
+    <p>Please log in to view your profile</p>
+  </div>
+</template>
+```
+
+---
+
+### Call Protected API
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useAuth0 } from '@auth0/auth0-vue';
+
+const { getAccessTokenSilently } = useAuth0();
+const data = ref(null);
+const error = ref(null);
+
+const callApi = async () => {
+  try {
+    const token = await getAccessTokenSilently({
+      authorizationParams: {
+        audience: 'https://your-api-identifier',
+      }
+    });
+
+    const response = await fetch('https://api.example.com/data', {
+      headers: {
+        Authorization: `Bearer ${token}`
+      }
+    });
+
+    data.value = await response.json();
+  } catch (err) {
+    error.value = err.message;
+  }
+};
+</script>
+
+<template>
+  <div>
+    <button @click="callApi">Call API</button>
+    <div v-if="error">Error: {{ error }}</div>
+    <pre v-if="data">{{ JSON.stringify(data, null, 2) }}</pre>
+  </div>
+</template>
+```
+
+**Note:** If calling APIs, add `audience` to your plugin configuration:
+
+```typescript
+app.use(
+  createAuth0({
+    domain: import.meta.env.VITE_AUTH0_DOMAIN,
+    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+    authorizationParams: {
+      redirect_uri: window.location.origin,
+      audience: 'https://your-api-identifier'  // Add this
+    }
+  })
+);
+```
+
+---
+
+### Handle Loading and Error States
+
+```vue
+<script setup lang="ts">
+import { useAuth0 } from '@auth0/auth0-vue';
+
+const { isLoading, error, isAuthenticated, user } = useAuth0();
+</script>
+
+<template>
+  <div v-if="isLoading">
+    Loading authentication...
+  </div>
+
+  <div v-else-if="error">
+    Authentication error: {{ error.message }}
+  </div>
+
+  <div v-else>
+    <div v-if="isAuthenticated">
+      <h1>Welcome back, {{ user?.name }}!</h1>
+      <!-- Authenticated content -->
+    </div>
+    <div v-else>
+      <h1>Please log in</h1>
+      <button @click="loginWithRedirect()">Login</button>
+    </div>
+  </div>
+</template>
+```
+
+---
+
+### Composition API with Reactive State
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useAuth0 } from '@auth0/auth0-vue';
+
+const auth0 = useAuth0();
+
+const userName = computed(() => auth0.user.value?.name || 'Guest');
+const isLoggedIn = computed(() => auth0.isAuthenticated.value);
+</script>
+
+<template>
+  <div>
+    <p>{{ userName }}</p>
+    <p v-if="isLoggedIn">You are logged in</p>
+  </div>
+</template>
+```
+
+---
+
+## Configuration Options
+
+### Complete Plugin Configuration
+
+```typescript
+app.use(
+  createAuth0({
+    domain: 'your-tenant.auth0.com',
+    clientId: 'your-client-id',
+    authorizationParams: {
+      redirect_uri: window.location.origin,
+      audience: 'https://your-api-identifier',  // For API calls
+      scope: 'openid profile email',  // Default scopes
+    },
+    cacheLocation: 'localstorage',  // or 'memory' for stricter security
+    useRefreshTokens: true,  // Enable refresh tokens
+  })
+);
+```
+
+---
+
+## Testing
+
+1. Start your dev server: `npm run dev`
+2. Click "Login" button
+3. Complete Auth0 Universal Login
+4. Verify redirect back to your app with user authenticated
+5. Navigate to protected routes
+6. Click "Logout" and verify user is logged out
+
+---
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "Invalid state" error | Clear browser storage. Ensure `redirect_uri` matches configured callback URL in Auth0 |
+| User stuck on loading | Check Auth0 application has correct callback URLs configured |
+| API calls fail with 401 | Ensure `audience` is configured in plugin and matches your API identifier |
+| Logout doesn't work | Include `returnTo` URL in logout options and configure in Auth0 "Allowed Logout URLs" |
+| Router guard loops | Ensure auth guard checks `isLoading` before redirecting |
+
+---
+
+## Security Considerations
+
+- **Never expose client secret** - Vue is client-side, use only public client credentials
+- **Use PKCE** - Enabled by default with @auth0/auth0-vue
+- **Validate tokens on backend** - Never trust client-side token validation
+- **Use HTTPS in production** - Auth0 requires HTTPS for production redirect URLs
+- **Implement proper CORS** - Configure allowed origins in Auth0 application settings
+
+---
+
+## Related Capabilities
+
+- Initial Auth0 account setup → set it up with the Auth0 CLI (`auth0 login`, then `auth0 apps create`)
+- Migrating from another auth provider → ask for migration (migrate)
+- Multi-factor authentication → ask for MFA (feature:mfa)
+- B2B multi-tenancy support → ask for Organizations (feature:organizations)
+- Passkey authentication → ask for MFA/passkeys (feature:mfa)
+
+---
+
+## References
+
+- [Auth0 Vue SDK Documentation](https://auth0.com/docs/libraries/auth0-vue)
+- [Auth0 Vue SDK GitHub](https://github.com/auth0/auth0-vue)
+- [Auth0 Vue Quickstart](https://auth0.com/docs/quickstart/spa/vuejs)
+- [Vue Router Documentation](https://router.vuejs.org/)
+
+---
+
+# Auth0 Vue Integration Patterns
+
+Practical implementation patterns and examples for common use cases.
+
+---
+
+## Protected Routes
+
+### Navigation Guard
+
+Create a navigation guard to protect routes:
+
+```typescript
+// src/router/index.ts
+import { createRouter, createWebHistory } from 'vue-router';
+import { createAuthGuard } from '@auth0/auth0-vue';
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    {
+      path: '/',
+      component: () => import('../views/Home.vue')
+    },
+    {
+      path: '/profile',
+      component: () => import('../views/Profile.vue'),
+      beforeEnter: createAuthGuard(app)
+    }
+  ]
+});
+
+export default router;
+```
+
+### Alternative: Component-Level Guard
+
+```vue
+<script setup lang="ts">
+import { useAuth0 } from '@auth0/auth0-vue';
+import { watchEffect } from 'vue';
+import { useRouter } from 'vue-router';
+
+const { isAuthenticated, isLoading, loginWithRedirect } = useAuth0();
+const router = useRouter();
+
+watchEffect(() => {
+  if (!isLoading.value && !isAuthenticated.value) {
+    loginWithRedirect();
+  }
+});
+</script>
+
+<template>
+  <div v-if="isAuthenticated">
+    <!-- Protected content -->
+  </div>
+</template>
+```
+
+---
+
+## User Profile
+
+### Display User Information
+
+```vue
+<script setup lang="ts">
+import { useAuth0 } from '@auth0/auth0-vue';
+
+const { user, isAuthenticated } = useAuth0();
+</script>
+
+<template>
+  <div v-if="isAuthenticated">
+    <img :src="user?.picture" :alt="user?.name" />
+    <h2>{{ user?.name }}</h2>
+    <p>{{ user?.email }}</p>
+    <pre>{{ JSON.stringify(user, null, 2) }}</pre>
+  </div>
+</template>
+```
+
+---
+
+## Calling APIs
+
+### API Call with Access Token
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useAuth0 } from '@auth0/auth0-vue';
+
+const { getAccessTokenSilently } = useAuth0();
+const data = ref(null);
+const error = ref(null);
+const loading = ref(false);
+
+const callApi = async () => {
+  loading.value = true;
+  error.value = null;
+
+  try {
+    const token = await getAccessTokenSilently({
+      authorizationParams: {
+        audience: 'https://your-api-identifier'
+      }
+    });
+
+    const response = await fetch('https://api.example.com/data', {
+      headers: {
+        Authorization: `Bearer ${token}`
+      }
+    });
+
+    data.value = await response.json();
+  } catch (err) {
+    error.value = err.message;
+  } finally {
+    loading.value = false;
+  }
+};
+</script>
+
+<template>
+  <div>
+    <button @click="callApi" :disabled="loading">
+      {{ loading ? 'Loading...' : 'Call API' }}
+    </button>
+    <div v-if="error" class="error">{{ error }}</div>
+    <pre v-if="data">{{ JSON.stringify(data, null, 2) }}</pre>
+  </div>
+</template>
+```
+
+### Configure Plugin for API Calls
+
+When calling APIs, add `audience` to your plugin configuration:
+
+```typescript
+// src/main.ts
+app.use(
+  createAuth0({
+    domain: import.meta.env.VITE_AUTH0_DOMAIN,
+    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+    authorizationParams: {
+      redirect_uri: window.location.origin,
+      audience: 'https://your-api-identifier' // Add this
+    }
+  })
+);
+```
+
+---
+
+## Error Handling
+
+### Handle Loading and Error States
+
+```vue
+<script setup lang="ts">
+import { useAuth0 } from '@auth0/auth0-vue';
+
+const { isLoading, error, isAuthenticated, user } = useAuth0();
+</script>
+
+<template>
+  <div v-if="isLoading">Loading authentication...</div>
+
+  <div v-else-if="error">
+    <h2>Authentication Error</h2>
+    <p>{{ error.message }}</p>
+  </div>
+
+  <div v-else-if="isAuthenticated">
+    <h1>Welcome back, {{ user?.name }}!</h1>
+    <!-- Authenticated app content -->
+  </div>
+
+  <div v-else>
+    <h1>Please log in</h1>
+    <LoginButton />
+  </div>
+</template>
+```
+
+---
+
+## Composable Patterns
+
+### Custom Auth Composable
+
+Create a custom composable for common auth operations:
+
+```typescript
+// src/composables/useAuthHelper.ts
+import { computed } from 'vue';
+import { useAuth0 } from '@auth0/auth0-vue';
+
+export function useAuthHelper() {
+  const {
+    isAuthenticated,
+    user,
+    loginWithRedirect,
+    logout,
+    getAccessTokenSilently
+  } = useAuth0();
+
+  const userName = computed(() => user.value?.name || 'Guest');
+  const userEmail = computed(() => user.value?.email || '');
+
+  const login = () => {
+    loginWithRedirect();
+  };
+
+  const logoutUser = () => {
+    logout({ logoutParams: { returnTo: window.location.origin } });
+  };
+
+  const callProtectedApi = async (url: string) => {
+    const token = await getAccessTokenSilently();
+    return fetch(url, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+  };
+
+  return {
+    isAuthenticated,
+    userName,
+    userEmail,
+    login,
+    logoutUser,
+    callProtectedApi
+  };
+}
+```
+
+**Usage:**
+```vue
+<script setup lang="ts">
+import { useAuthHelper } from '@/composables/useAuthHelper';
+
+const { isAuthenticated, userName, login, logoutUser } = useAuthHelper();
+</script>
+
+<template>
+  <div>
+    <span v-if="isAuthenticated">Welcome, {{ userName }}</span>
+    <button v-if="isAuthenticated" @click="logoutUser">Logout</button>
+    <button v-else @click="login">Login</button>
+  </div>
+</template>
+```
+
+---
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "Invalid state" error | Clear browser storage and try again. Ensure `redirect_uri` matches configured callback URL |
+| User stuck on loading | Check Auth0 application settings have correct callback URLs configured |
+| API calls fail with 401 | Ensure `audience` is configured in plugin and matches your API identifier |
+| Logout doesn't work | Include `returnTo` URL in logout options and configure in Auth0 "Allowed Logout URLs" |
+| CORS errors | Add your application URL to "Allowed Web Origins" in Auth0 application settings |
+| Composables not reactive | Ensure you're accessing `.value` on refs returned from `useAuth0()` |
+
+---
+
+## Security Considerations
+
+### Client-Side Security
+
+- **Never expose client secret** - Vue runs client-side, use only public client credentials
+- **Use PKCE** - Enabled by default with @auth0/auth0-vue
+- **Validate tokens on backend** - Never trust client-side token validation
+- **Use HTTPS in production** - Auth0 requires HTTPS for production redirect URLs
+- **Implement proper CORS** - Configure allowed origins in Auth0 application settings
+
+### Token Storage
+
+The SDK stores tokens in memory by default (cleared on page refresh). To persist sessions:
+
+```typescript
+app.use(
+  createAuth0({
+    domain: import.meta.env.VITE_AUTH0_DOMAIN,
+    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
+    cacheLocation: 'localstorage', // or 'memory' for stricter security
+    useRefreshTokens: true
+  })
+);
+```
+
+---
+
+## Advanced Patterns
+
+### Custom Login with Options
+
+```typescript
+import { useAuth0 } from '@auth0/auth0-vue';
+
+const { loginWithRedirect } = useAuth0();
+
+// Login with specific connection
+await loginWithRedirect({
+  authorizationParams: {
+    connection: 'google-oauth2'
+  }
+});
+
+// Login with signup screen
+await loginWithRedirect({
+  authorizationParams: {
+    screen_hint: 'signup'
+  }
+});
+```
+
+### Handle Redirect Callback
+
+```vue
+<script setup lang="ts">
+import { onMounted } from 'vue';
+import { useAuth0 } from '@auth0/auth0-vue';
+import { useRouter } from 'vue-router';
+
+const { handleRedirectCallback } = useAuth0();
+const router = useRouter();
+
+onMounted(async () => {
+  if (window.location.search.includes('code=')) {
+    await handleRedirectCallback();
+    router.push('/');
+  }
+});
+</script>
+```
+
+---
+
+## Testing
+
+### Manual Testing Checklist
+
+1. **Login Flow**
+   - Start dev server: `npm run dev`
+   - Click "Login" button
+   - Complete Auth0 Universal Login
+   - Verify redirect back to app with user authenticated
+
+2. **Logout Flow**
+   - Click "Logout" button
+   - Verify user is logged out
+   - Verify redirect to correct page
+
+3. **Protected Routes**
+   - Navigate to protected route while logged out
+   - Verify redirect to Auth0 login
+   - After login, verify redirect back to protected route
+
+4. **API Calls**
+   - Call protected API endpoint
+   - Verify access token is included
+   - Verify API responds correctly
+
+---
+
+---
+
+# Auth0 Vue Setup Guide
+
+Complete setup instructions with automated scripts and manual configuration options.
+
+---
+
+## Quick Setup (Automated)
+
+**Never read the contents of `.env` at any point during setup.** The file may contain sensitive secrets that should not be exposed in the LLM context. If you determine you need to read the file for any reason, ask the user for explicit permission before doing so — do not proceed until the user confirms.
+
+**Before running any part of this setup that writes to `.env`, you must ask the user for explicit confirmation.** Follow the steps below precisely.
+
+### Step 1: Check for existing .env and confirm with user
+
+Before writing to `.env`, check whether the file already exists:
+
+```bash
+test -f .env && echo "EXISTS" || echo "NOT_FOUND"
+```
+
+Then ask the user for explicit confirmation before proceeding — do not continue until the user confirms:
+
+- If `.env` does **not** exist, ask:
+  - Question: "This setup will create a `.env` file containing Auth0 credentials (domain and client ID). Do you want to proceed?"
+  - Options: "Yes, create .env" / "No, I'll configure it manually"
+
+- If `.env` **already exists**, ask:
+  - Question: "A `.env` file already exists and may contain secrets unrelated to Auth0. This setup will append Auth0 credentials to it without modifying existing content. Do you want to proceed?"
+  - Options: "Yes, append to existing .env" / "No, I'll update it manually"
+
+**Do not proceed with writing to `.env` unless the user selects the confirmation option.**
+
+### Step 2: Run automated setup (only after confirmation)
+
+#### Bash Script (macOS/Linux)
+
+Run this script to automatically set up everything:
+
+```bash
+#!/bin/bash
+
+# Detect OS and install Auth0 CLI if needed
+if ! command -v auth0 &> /dev/null; then
+  echo "Installing Auth0 CLI..."
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    brew install auth0/auth0-cli/auth0
+  elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    # Download and review the install script before executing
+    curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh -o /tmp/auth0-install.sh
+    echo "⚠️  Review the install script at /tmp/auth0-install.sh before running"
+    sh /tmp/auth0-install.sh -b /usr/local/bin
+    rm /tmp/auth0-install.sh
+  fi
+fi
+
+# Check if logged in to Auth0
+if ! auth0 tenants list &> /dev/null; then
+  echo "======================================"
+  echo "Auth0 Login Required"
+  echo "======================================"
+  read -p "Do you have an Auth0 account? (y/n): " HAS_ACCOUNT
+
+  if [[ "$HAS_ACCOUNT" != "y" ]]; then
+    echo "Let's create your free Auth0 account!"
+    echo "1. Visit: https://auth0.com/signup"
+    echo "2. Sign up with your email or GitHub"
+    echo "3. Choose a tenant domain"
+    read -p "Press Enter when you've created your account..."
+  fi
+
+  auth0 login
+fi
+
+# List apps and prompt for selection
+echo "Your Auth0 applications:"
+auth0 apps list
+
+read -p "Enter your Auth0 app ID (or press Enter to create new): " APP_ID
+
+if [ -z "$APP_ID" ]; then
+  echo "Creating new Auth0 SPA application..."
+  APP_NAME="${PWD##*/}-vue-app"
+  APP_ID=$(auth0 apps create \
+    --name "$APP_NAME" \
+    --type spa \
+    --auth-method None \
+    --callbacks "http://localhost:5173,http://localhost:3000" \
+    --logout-urls "http://localhost:5173,http://localhost:3000" \
+    --origins "http://localhost:5173,http://localhost:3000" \
+    --web-origins "http://localhost:5173,http://localhost:3000" \
+    --metadata "created_by=agent_skills" \
+    --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+  echo "Created app with ID: $APP_ID"
+fi
+
+# Get app details and create .env file
+echo "Fetching Auth0 credentials..."
+AUTH0_DOMAIN=$(auth0 apps show "$APP_ID" --json | grep -o '"domain":"[^"]*' | cut -d'"' -f4)
+AUTH0_CLIENT_ID=$(auth0 apps show "$APP_ID" --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
+
+# Append Auth0 credentials to .env
+cat >> .env << EOF
+VITE_AUTH0_DOMAIN=$AUTH0_DOMAIN
+VITE_AUTH0_CLIENT_ID=$AUTH0_CLIENT_ID
+EOF
+
+echo "✅ Auth0 configuration complete!"
+echo "Appended to .env:"
+echo "  VITE_AUTH0_DOMAIN=$AUTH0_DOMAIN"
+echo "  VITE_AUTH0_CLIENT_ID=$AUTH0_CLIENT_ID"
+```
+
+#### PowerShell Script (Windows)
+
+```powershell
+# Install Auth0 CLI if not present
+if (!(Get-Command auth0 -ErrorAction SilentlyContinue)) {
+  Write-Host "Installing Auth0 CLI..."
+  scoop install auth0
+}
+
+# Check if logged in
+try {
+  auth0 tenants list | Out-Null
+} catch {
+  Write-Host "======================================"
+  Write-Host "Auth0 Login Required"
+  Write-Host "======================================"
+
+  $hasAccount = Read-Host "Do you have an Auth0 account? (y/n)"
+
+  if ($hasAccount -ne "y") {
+    Write-Host "Let's create your free Auth0 account!"
+    Write-Host "1. Visit: https://auth0.com/signup"
+    Write-Host "2. Sign up with your email or GitHub"
+    Read-Host "Press Enter when you've created your account"
+  }
+
+  auth0 login
+}
+
+# List and select app
+Write-Host "Your Auth0 applications:"
+auth0 apps list
+
+$appId = Read-Host "Enter your Auth0 app ID (or press Enter to create new)"
+
+if ([string]::IsNullOrEmpty($appId)) {
+  $appName = Split-Path -Leaf (Get-Location)
+  Write-Host "Creating new Auth0 SPA application..."
+  $appJson = auth0 apps create --name "$appName-vue-app" --type spa `
+    --auth-method None `
+    --callbacks "http://localhost:5173,http://localhost:3000" `
+    --logout-urls "http://localhost:5173,http://localhost:3000" `
+    --origins "http://localhost:5173,http://localhost:3000" `
+    --web-origins "http://localhost:5173,http://localhost:3000" `
+    --metadata "created_by=agent_skills" --json
+
+  $appId = ($appJson | ConvertFrom-Json).client_id
+  Write-Host "Created app with ID: $appId"
+}
+
+# Get credentials and create .env
+Write-Host "Fetching Auth0 credentials..."
+$appDetails = auth0 apps show $appId --json | ConvertFrom-Json
+
+@"
+VITE_AUTH0_DOMAIN=$($appDetails.domain)
+VITE_AUTH0_CLIENT_ID=$($appDetails.client_id)
+"@ | Out-File -FilePath .env -Encoding UTF8 -Append
+
+Write-Host "✅ Auth0 configuration complete!"
+Write-Host "Appended to .env:"
+Write-Host "  VITE_AUTH0_DOMAIN=$($appDetails.domain)"
+Write-Host "  VITE_AUTH0_CLIENT_ID=$($appDetails.client_id)"
+```
+
+---
+
+## Manual Setup
+
+### Step 1: Install SDK
+
+```bash
+npm install @auth0/auth0-vue
+```
+
+### Step 2: Install Auth0 CLI
+
+**macOS:**
+```bash
+brew install auth0/auth0-cli/auth0
+```
+
+**Linux (review script before executing):**
+```bash
+curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh -o /tmp/auth0-install.sh
+# Review the script before running: cat /tmp/auth0-install.sh
+sh /tmp/auth0-install.sh
+rm /tmp/auth0-install.sh
+```
+
+**Windows:**
+```powershell
+scoop install auth0
+```
+
+### Step 3: Get Credentials
+
+```bash
+# Login to Auth0
+auth0 login
+
+# List your apps
+auth0 apps list
+
+# Get app details
+auth0 apps show <app-id>
+```
+
+### Step 4: Create .env File
+
+```bash
+VITE_AUTH0_DOMAIN=<your-tenant>.auth0.com
+VITE_AUTH0_CLIENT_ID=<your-client-id>
+```
+
+---
+
+## Creating Auth0 Application via Dashboard
+
+1. Go to [Auth0 Dashboard](https://manage.auth0.com)
+2. Navigate to **Applications** → **Applications**
+3. Click **Create Application**
+4. Choose **Single Page Web Applications**
+5. Configure:
+   - **Allowed Callback URLs**: `http://localhost:5173, http://localhost:3000`
+   - **Allowed Logout URLs**: `http://localhost:5173, http://localhost:3000`
+   - **Allowed Web Origins**: `http://localhost:5173, http://localhost:3000`
+   - **Allowed Origins (CORS)**: `http://localhost:5173, http://localhost:3000`
+6. Copy your **Domain** and **Client ID**
+7. Create `.env` file as shown above
+
+---
+
+## Troubleshooting
+
+### Environment Variables Not Loading
+
+**Issue**: Variables not available in app
+
+**Solution:**
+- Ensure variables start with `VITE_` prefix
+- Restart dev server after creating `.env`
+- Check file is named exactly `.env` (not `.env.local`)
+- Vite only loads variables at build time, not runtime
+
+### Auth0 CLI Issues
+
+**Browser doesn't open:**
+```bash
+auth0 login --no-browser
+```
+
+**"Not logged in" error:**
+```bash
+auth0 login --force
+```
+
+### CORS Errors
+
+**Issue**: CORS errors when logging in
+
+**Solution:**
+- Add your app URL to "Allowed Web Origins" in Auth0 Dashboard
+- Ensure callback URLs include protocol (`http://` or `https://`)
+- For local dev, use `http://localhost:5173` (Vite default)
+
+---
+
+## Next Steps
+
+After setup is complete:
+1. Return to the main skill guide for integration steps
diff --git a/main/.mintlify/skills/auth0/references/framework-winforms/index.md b/main/.mintlify/skills/auth0/references/framework-winforms/index.md
new file mode 100644
index 0000000000..6ff0cdb49c
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-winforms/index.md
@@ -0,0 +1,254 @@
+# Auth0 WinForms
+
+> Ported from auth0/auth0-winforms skill.
+
+---
+
+
+# Auth0 WinForms Integration
+
+Add Auth0 authentication to Windows Forms (WinForms) desktop applications. This skill integrates the `Auth0.OidcClient.WinForms` NuGet package which uses WebView2 to display the Auth0 login page in a popup form for secure OIDC-based login and logout flows with PKCE.
+
+The SDK performs WebAuth (OIDC authorization code flow with PKCE) by opening the Auth0 Universal Login page inside a WebView2 control hosted in a WinForms Form. Unlike native mobile SDKs that require URL scheme registration in Info.plist or AndroidManifest.xml, the WinForms SDK handles the callback entirely within the WebView2 navigation events — no custom URL Types or protocol handlers are needed.
+
+> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
+> ```bash
+> gh api repos/auth0/auth0-oidc-client-net/releases --jq '[.[] | select(.tag_name | startswith("winforms-")) | .tag_name | ltrimstr("winforms-")] | .[0]'
+> ```
+> Use the returned version in all dependency lines instead of any hardcoded version below.
+
+## Prerequisites
+
+- .NET 6.0 SDK or later (WinForms requires Windows)
+- Visual Studio 2022 or JetBrains Rider with .NET desktop development workload
+- Windows 10 or later
+- Microsoft Edge WebView2 Runtime (included with Windows 11, installable on Windows 10)
+- Auth0 account with a Native application configured
+- Node.js 20+ (for Auth0 CLI automated setup)
+
+## When NOT to Use
+
+| Use Case | Use Instead |
+|----------|------------------|
+| .NET MAUI cross-platform app | the Auth0 integration workflow for .NET MAUI |
+| WPF desktop app | the Auth0 integration workflow for WPF |
+| ASP.NET Core server-side web app | the Auth0 integration workflow for ASP.NET Core |
+| ASP.NET Core Web API (JWT validation) | the Auth0 integration workflow for ASP.NET Core Web API |
+| iOS-only Swift app | the Auth0 integration workflow for iOS/Swift |
+| Android-only Kotlin app | the Auth0 integration workflow for Android |
+
+## Quick Start Workflow
+
+> **Agent instruction:** Before starting, examine the user's project:
+> 1. Identify the .NET version from the `.csproj` file (`TargetFramework`)
+> 2. Check if there is already an existing authentication provider in the codebase — search for existing `Auth0Client` or `WebViewBrowser` usage and reuse if found
+> 3. Note the project's namespace and directory conventions
+
+1. **Install SDK**: `dotnet add package Auth0.OidcClient.WinForms`
+2. **Configure Auth0**: See the Setup Guide section (below) for automatic or manual configuration.
+3. **Integrate authentication**: Add `Auth0Client` initialization and wire login/logout to button click handlers.
+4. **Build and verify**: `dotnet build`
+
+> **Agent instruction:** When writing the Auth0Client configuration:
+> - Use the exact code patterns from this skill's integration guide.
+> - The SDK uses WebView2 to show the login page in a popup form — no custom browser setup needed.
+> - The default callback URL is `https://{yourDomain}/mobile` — this must be added to Auth0 Dashboard Allowed Callback URLs and Allowed Logout URLs.
+> - Unlike native mobile SDKs that use `https://{domain}/ios/{bundleId}/callback` or similar platform-specific patterns, WinForms uses the simpler `https://{domain}/mobile` callback format.
+>
+> After writing configuration and code, verify the build succeeds:
+> ```bash
+> dotnet build
+> ```
+> If the build fails, attempt to fix the issue. After 5-6 failed attempts, ask the user for help.
+
+## Callback URL Configuration
+
+The WinForms SDK uses `https://{yourDomain}/mobile` as its default callback URL. This differs from mobile native SDKs:
+
+- **Mobile SDKs** use platform-specific callbacks like `https://{domain}/ios/{bundleId}/callback` or `https://{domain}/android/{packageName}/callback`
+- **WPF/WinForms** use the generic `https://{yourDomain}/mobile` callback
+
+The callback is intercepted by the WebView2 control's `NavigationStarting` event — no system-level URL scheme registration is required. You do NOT need to configure Info.plist, AndroidManifest.xml, or Windows protocol handlers.
+
+Configure in the Auth0 Dashboard:
+- **Allowed Callback URLs**: `https://{yourDomain}/mobile`
+- **Allowed Logout URLs**: `https://{yourDomain}/mobile`
+
+## Done When
+
+- [ ] `Auth0.OidcClient.WinForms` package installed
+- [ ] `Auth0Client` configured with Domain and ClientId
+- [ ] Login/logout flow working (WebView2 popup opens for authentication)
+- [ ] User profile claims accessible after login
+- [ ] Callback URL `https://{yourDomain}/mobile` registered in Auth0 Dashboard
+- [ ] Build succeeds with no errors
+- [ ] Tested on real device (physical Windows machine, not just remote desktop)
+
+## Detailed Documentation
+
+- **Setup Guide** (see below) — Auth0 tenant configuration, SDK installation, callback URL setup
+- **Integration Patterns** (see below) — Login/logout flows, token refresh, user profile, error handling
+- **API Reference & Testing** (see below) — Full `Auth0ClientOptions` reference, claims, testing checklist, troubleshooting
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| App type not set to **Native** in Auth0 Dashboard | Change application type to "Native" in Dashboard settings |
+| Missing callback URL in Auth0 Dashboard | Add `https://{yourDomain}/mobile` to both Allowed Callback URLs AND Allowed Logout URLs |
+| Using `https://` prefix in Domain config | Domain should be hostname only (e.g., `tenant.auth0.com`, not `https://tenant.auth0.com`) |
+| WebView2 Runtime not installed | Install Microsoft Edge WebView2 Runtime on Windows 10 (included with Windows 11) |
+| Not requesting `offline_access` scope for token refresh | Add `offline_access` to `Scope` in `Auth0ClientOptions` |
+| Storing ClientSecret in code | Native apps do NOT use a Client Secret — remove it |
+| Trying to register URL scheme in registry/manifest | WinForms uses WebView2 in-process — no URL scheme registration needed (unlike MAUI which needs AppxManifest) |
+
+## Testing Notes
+
+> **Agent instruction:** Remind the user to test on a physical device. Some WebView2 behaviors (popup windows, certificate handling) may differ in remote desktop or virtual machine environments vs. physical Windows machines. Test the full login → WebView2 → callback → token flow on real hardware before shipping.
+
+**Testing Checklist:**
+- Login flow: Click login → WebView2 popup opens → authenticate → popup closes → user info displayed
+- Logout flow: Click logout → WebView2 popup opens → session cleared → popup closes
+- Token refresh: `RefreshTokenAsync` with stored refresh token works
+- Cancel: User closes WebView2 form → app handles `UserCancel` gracefully
+- Physical device: Test on a real Windows machine (not just virtual environment)
+- Multiple logins: Verify login works after logout (no stale state)
+
+## Related Workflows
+
+- The Auth0 integration workflow for WPF desktop apps
+- The Auth0 integration workflow for .NET MAUI cross-platform apps
+- The Auth0 integration workflow for ASP.NET Core server-side web apps
+- The Auth0 integration workflow for ASP.NET Core Web API with JWT validation
+
+## Quick Reference
+
+```csharp
+using Auth0.OidcClient;
+using System.Diagnostics;
+
+// Initialize client
+var client = new Auth0Client(new Auth0ClientOptions
+{
+    Domain = "{yourDomain}",
+    ClientId = "{yourClientId}",
+    Scope = "openid profile email offline_access"
+});
+
+// Login — opens WebView2 popup form (WebAuth flow with PKCE)
+var loginResult = await client.LoginAsync();
+if (loginResult.IsError == false)
+{
+    var user = loginResult.User;
+    var name = user.FindFirst(c => c.Type == "name")?.Value;
+    var email = user.FindFirst(c => c.Type == "email")?.Value;
+    var picture = user.FindFirst(c => c.Type == "picture")?.Value;
+
+    Debug.WriteLine($"name: {name}");
+    Debug.WriteLine($"email: {email}");
+
+    foreach (var claim in loginResult.User.Claims)
+    {
+        Debug.WriteLine($"{claim.Type} = {claim.Value}");
+    }
+}
+
+// Logout
+await client.LogoutAsync();
+
+// Refresh token (requires offline_access scope)
+var refreshToken = loginResult.RefreshToken;
+var refreshResult = await client.RefreshTokenAsync(refreshToken);
+if (refreshResult.IsError == false)
+{
+    var newAccessToken = refreshResult.AccessToken;
+}
+```
+
+### Form1.cs (WinForms Complete Example)
+
+```csharp
+using Auth0.OidcClient;
+using System.Diagnostics;
+
+namespace MyApp;
+
+public partial class Form1 : Form
+{
+    private Auth0Client _client;
+    private Button loginButton;
+    private Button logoutButton;
+
+    public Form1()
+    {
+        InitializeComponent();
+
+        _client = new Auth0Client(new Auth0ClientOptions
+        {
+            Domain = "{yourDomain}",
+            ClientId = "{yourClientId}",
+            Scope = "openid profile email offline_access"
+        });
+
+        loginButton = new Button
+        {
+            Text = "Log In",
+            Width = 120,
+            Height = 40,
+            Left = (ClientSize.Width - 120) / 2,
+            Top = (ClientSize.Height - 40) / 2
+        };
+        loginButton.Click += loginButton_Click;
+        Controls.Add(loginButton);
+
+        logoutButton = new Button
+        {
+            Text = "Log Out",
+            Width = 120,
+            Height = 40,
+            Left = (ClientSize.Width - 120) / 2,
+            Top = (ClientSize.Height - 40) / 2 + 50
+        };
+        logoutButton.Click += logoutButton_Click;
+        Controls.Add(logoutButton);
+    }
+
+    private async void loginButton_Click(object sender, EventArgs e)
+    {
+        var loginResult = await _client.LoginAsync();
+
+        if (loginResult.IsError)
+        {
+            Debug.WriteLine($"Error: {loginResult.Error}");
+            Debug.WriteLine($"Description: {loginResult.ErrorDescription}");
+            return;
+        }
+
+        var user = loginResult.User;
+        var name = user.FindFirst(c => c.Type == "name")?.Value;
+        var email = user.FindFirst(c => c.Type == "email")?.Value;
+        var picture = user.FindFirst(c => c.Type == "picture")?.Value;
+
+        Debug.WriteLine($"name: {name}");
+        Debug.WriteLine($"email: {email}");
+
+        foreach (var claim in loginResult.User.Claims)
+        {
+            Debug.WriteLine($"{claim.Type} = {claim.Value}");
+        }
+    }
+
+    private async void logoutButton_Click(object sender, EventArgs e)
+    {
+        await _client.LogoutAsync();
+    }
+}
+```
+
+## References
+
+- [Auth0 WPF/WinForms Quickstart](https://auth0.com/docs/quickstart/native/wpf-winforms)
+- [GitHub Repository](https://github.com/auth0/auth0-oidc-client-net)
+- [NuGet Package](https://www.nuget.org/packages/Auth0.OidcClient.WinForms)
+- [SDK API Documentation](https://auth0.github.io/auth0-oidc-client-net/documentation/intro.html)
+- [Auth0 Native App Documentation](https://auth0.com/docs/get-started/auth0-overview/create-applications/native-apps)
diff --git a/main/.mintlify/skills/auth0/references/framework-wpf/index.md b/main/.mintlify/skills/auth0/references/framework-wpf/index.md
new file mode 100644
index 0000000000..3b907ce7cf
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/framework-wpf/index.md
@@ -0,0 +1,249 @@
+# Auth0 WPF
+
+> Ported from auth0/auth0-wpf skill.
+
+---
+
+
+# Auth0 WPF Integration
+
+Add Auth0 authentication to WPF (Windows Presentation Foundation) desktop applications. This skill integrates the `Auth0.OidcClient.WPF` NuGet package which uses WebView2 to display the Auth0 login page in a popup window for secure OIDC-based login and logout flows with PKCE.
+
+The SDK performs WebAuth (OIDC authorization code flow with PKCE) by opening the Auth0 Universal Login page inside a WebView2 control hosted in a WPF Window. Unlike native mobile SDKs that require URL scheme registration in Info.plist or AndroidManifest.xml, the WPF SDK handles the callback entirely within the WebView2 navigation events — no custom URL Types or protocol handlers are needed.
+
+> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
+> ```bash
+> gh api repos/auth0/auth0-oidc-client-net/releases --jq '[.[] | select(.tag_name | startswith("wpf-")) | .tag_name | ltrimstr("wpf-")] | .[0]'
+> ```
+> Use the returned version in all dependency lines instead of any hardcoded version below.
+
+## Prerequisites
+
+- .NET 6.0 SDK or later (WPF requires Windows)
+- Visual Studio 2022 or JetBrains Rider with .NET desktop development workload
+- Windows 10 or later
+- Microsoft Edge WebView2 Runtime (included with Windows 11, installable on Windows 10)
+- Auth0 account with a Native application configured
+- Node.js 20+ (for Auth0 CLI automated setup)
+
+## When NOT to Use
+
+| Use Case | Use Instead |
+|----------|------------------|
+| .NET MAUI cross-platform app | the Auth0 integration workflow for .NET MAUI |
+| Windows Forms desktop app | the Auth0 integration workflow for Windows Forms |
+| ASP.NET Core server-side web app | the Auth0 integration workflow for ASP.NET Core |
+| ASP.NET Core Web API (JWT validation) | the Auth0 integration workflow for ASP.NET Core Web API |
+| iOS-only Swift app | the Auth0 integration workflow for iOS/Swift |
+| Android-only Kotlin app | the Auth0 integration workflow for Android |
+
+## Quick Start Workflow
+
+> **Agent instruction:** Before starting, examine the user's project:
+> 1. Identify the .NET version from the `.csproj` file (`TargetFramework`)
+> 2. Check if there is already an existing authentication provider in the codebase — search for existing `Auth0Client` or `WebViewBrowser` usage and reuse if found
+> 3. Note the project's namespace and directory conventions
+
+1. **Install SDK**: `dotnet add package Auth0.OidcClient.WPF`
+2. **Configure Auth0**: See the Setup Guide section (below) for automatic or manual configuration.
+3. **Integrate authentication**: Add `Auth0Client` initialization and wire login/logout to XAML button click handlers.
+4. **Build and verify**: `dotnet build`
+
+> **Agent instruction:** When writing the Auth0Client configuration:
+> - Use the exact code patterns from this skill's integration guide.
+> - The SDK uses WebView2 to show the login page in a popup window — no custom browser setup needed.
+> - The default callback URL is `https://{yourDomain}/mobile` — this must be added to Auth0 Dashboard Allowed Callback URLs and Allowed Logout URLs.
+> - Unlike native mobile SDKs that use `https://{domain}/ios/{bundleId}/callback` or similar platform-specific patterns, WPF uses the simpler `https://{domain}/mobile` callback format.
+>
+> After writing configuration and code, verify the build succeeds:
+> ```bash
+> dotnet build
+> ```
+> If the build fails, attempt to fix the issue. After 5-6 failed attempts, ask the user for help.
+
+## Callback URL Configuration
+
+The WPF SDK uses `https://{yourDomain}/mobile` as its default callback URL. This differs from mobile native SDKs:
+
+- **Mobile SDKs** use platform-specific callbacks like `https://{domain}/ios/{bundleId}/callback` or `https://{domain}/android/{packageName}/callback`
+- **WPF/WinForms** use the generic `https://{yourDomain}/mobile` callback
+
+The callback is intercepted by the WebView2 control's `NavigationStarting` event — no system-level URL scheme registration is required. You do NOT need to configure Info.plist, AndroidManifest.xml, or Windows protocol handlers.
+
+Configure in the Auth0 Dashboard:
+- **Allowed Callback URLs**: `https://{yourDomain}/mobile`
+- **Allowed Logout URLs**: `https://{yourDomain}/mobile`
+
+## Done When
+
+- [ ] `Auth0.OidcClient.WPF` package installed
+- [ ] `Auth0Client` configured with Domain and ClientId
+- [ ] Login/logout flow working (WebView2 popup opens for authentication)
+- [ ] User profile claims accessible after login
+- [ ] Callback URL `https://{yourDomain}/mobile` registered in Auth0 Dashboard
+- [ ] Build succeeds with no errors
+- [ ] Tested on real device (physical Windows machine, not just remote desktop)
+
+## Detailed Documentation
+
+- **Setup Guide** (see below) — Auth0 tenant configuration, SDK installation, callback URL setup
+- **Integration Patterns** (see below) — Login/logout flows, token refresh, user profile, error handling
+- **API Reference & Testing** (see below) — Full `Auth0ClientOptions` reference, claims, testing checklist, troubleshooting
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| App type not set to **Native** in Auth0 Dashboard | Change application type to "Native" in Dashboard settings |
+| Missing callback URL in Auth0 Dashboard | Add `https://{yourDomain}/mobile` to both Allowed Callback URLs AND Allowed Logout URLs |
+| Using `https://` prefix in Domain config | Domain should be hostname only (e.g., `tenant.auth0.com`, not `https://tenant.auth0.com`) |
+| WebView2 Runtime not installed | Install Microsoft Edge WebView2 Runtime on Windows 10 (included with Windows 11) |
+| Not requesting `offline_access` scope for token refresh | Add `offline_access` to `Scope` in `Auth0ClientOptions` |
+| Storing ClientSecret in code | Native apps do NOT use a Client Secret — remove it |
+| Trying to register URL scheme in registry/manifest | WPF uses WebView2 in-process — no URL scheme registration needed (unlike MAUI which needs AppxManifest) |
+
+## Testing Notes
+
+> **Agent instruction:** Remind the user to test on a physical device. Some WebView2 behaviors (popup windows, certificate handling) may differ in remote desktop or virtual machine environments vs. physical Windows machines. Test the full login → WebView2 → callback → token flow on real hardware before shipping.
+
+**Testing Checklist:**
+- Login flow: Click login → WebView2 popup opens → authenticate → popup closes → user info displayed
+- Logout flow: Click logout → WebView2 popup opens → session cleared → popup closes
+- Token refresh: `RefreshTokenAsync` with stored refresh token works
+- Cancel: User closes WebView2 window → app handles `UserCancel` gracefully
+- Physical device: Test on a real Windows machine (not just virtual environment)
+- Multiple logins: Verify login works after logout (no stale state)
+
+## Related Workflows
+
+- The Auth0 integration workflow for Windows Forms desktop apps
+- The Auth0 integration workflow for .NET MAUI cross-platform apps
+- The Auth0 integration workflow for ASP.NET Core server-side web apps
+- The Auth0 integration workflow for ASP.NET Core Web API with JWT validation
+
+## Quick Reference
+
+```csharp
+using Auth0.OidcClient;
+using System.Diagnostics;
+
+// Initialize client
+var client = new Auth0Client(new Auth0ClientOptions
+{
+    Domain = "{yourDomain}",
+    ClientId = "{yourClientId}",
+    Scope = "openid profile email offline_access"
+});
+
+// Login — opens WebView2 popup window (WebAuth flow with PKCE)
+var loginResult = await client.LoginAsync();
+if (!loginResult.IsError)
+{
+    var user = loginResult.User;
+    var name = user.FindFirst(c => c.Type == "name")?.Value;
+    var email = user.FindFirst(c => c.Type == "email")?.Value;
+    var picture = user.FindFirst(c => c.Type == "picture")?.Value;
+
+    Debug.WriteLine($"name: {name}");
+    Debug.WriteLine($"email: {email}");
+
+    foreach (var claim in loginResult.User.Claims)
+    {
+        Debug.WriteLine($"{claim.Type} = {claim.Value}");
+    }
+}
+
+// Store the refresh token from login for later use
+var refreshToken = loginResult.RefreshToken;
+
+// Logout
+await client.LogoutAsync();
+
+// Refresh token (requires offline_access scope)
+var refreshResult = await client.RefreshTokenAsync(refreshToken);
+if (refreshResult.IsError == false)
+{
+    var newAccessToken = refreshResult.AccessToken;
+}
+```
+
+### MainWindow.xaml (WPF UI)
+
+```xml
+<Window x:Class="MyApp.MainWindow"
+        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+        Title="Auth0 WPF App" Height="450" Width="800">
+    <Grid>
+        <StackPanel HorizontalAlignment="Center" VerticalAlignment="Center">
+            <Button x:Name="LoginButton" Content="Login" Width="200" Height="40"
+                    Margin="10" Click="LoginButton_Click" FontSize="16"/>
+            <Button x:Name="LogoutButton" Content="Logout" Width="200" Height="40"
+                    Margin="10" Click="LogoutButton_Click" FontSize="16"/>
+        </StackPanel>
+    </Grid>
+</Window>
+```
+
+### MainWindow.xaml.cs (WPF Code-Behind)
+
+```csharp
+using Auth0.OidcClient;
+using System.Diagnostics;
+
+namespace MyApp;
+
+public partial class MainWindow : Window
+{
+    private Auth0Client _client;
+
+    public MainWindow()
+    {
+        InitializeComponent();
+
+        _client = new Auth0Client(new Auth0ClientOptions
+        {
+            Domain = "{yourDomain}",
+            ClientId = "{yourClientId}",
+            Scope = "openid profile email offline_access"
+        });
+    }
+
+    private async void LoginButton_Click(object sender, RoutedEventArgs e)
+    {
+        var loginResult = await _client.LoginAsync();
+
+        if (loginResult.IsError)
+        {
+            Debug.WriteLine($"An error occurred during login: {loginResult.Error}");
+            return;
+        }
+
+        var user = loginResult.User;
+        var name = user.FindFirst(c => c.Type == "name")?.Value;
+        var email = user.FindFirst(c => c.Type == "email")?.Value;
+        var picture = user.FindFirst(c => c.Type == "picture")?.Value;
+
+        Debug.WriteLine($"name: {name}");
+        Debug.WriteLine($"email: {email}");
+
+        foreach (var claim in loginResult.User.Claims)
+        {
+            Debug.WriteLine($"{claim.Type} = {claim.Value}");
+        }
+    }
+
+    private async void LogoutButton_Click(object sender, RoutedEventArgs e)
+    {
+        await _client.LogoutAsync();
+    }
+}
+```
+
+## References
+
+- [Auth0 WPF/WinForms Quickstart](https://auth0.com/docs/quickstart/native/wpf-winforms)
+- [GitHub Repository](https://github.com/auth0/auth0-oidc-client-net)
+- [NuGet Package](https://www.nuget.org/packages/Auth0.OidcClient.WPF)
+- [SDK API Documentation](https://auth0.github.io/auth0-oidc-client-net/documentation/intro.html)
+- [Auth0 Native App Documentation](https://auth0.com/docs/get-started/auth0-overview/create-applications/native-apps)
diff --git a/main/.mintlify/skills/auth0/references/pattern-common-errors/index.md b/main/.mintlify/skills/auth0/references/pattern-common-errors/index.md
new file mode 100644
index 0000000000..97c6b340c7
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/pattern-common-errors/index.md
@@ -0,0 +1,100 @@
+# Common Auth0 Errors and Fixes
+
+---
+
+## 401 Unauthorized from your API
+
+**Checklist:**
+1. Is the `Authorization: Bearer <token>` header being sent?
+2. Was the token requested with the correct `audience`? Must exactly match your API identifier.
+3. Is the token expired? Call `getAccessTokenSilently()` before every API call.
+4. Does your API's `audience` validation match the `aud` claim in the token?
+
+```javascript
+// React — always call getAccessTokenSilently, don't cache manually
+const token = await getAccessTokenSilently({
+  authorizationParams: { audience: process.env.REACT_APP_AUTH0_AUDIENCE }
+});
+```
+
+---
+
+## Callback URL mismatch
+
+**Error:** `Callback URL mismatch. The provided redirect_uri is not in the list of allowed callback URLs.`
+
+**Fix:** Add the exact URL to **Allowed Callback URLs** in Auth0 Dashboard → Applications → [your app]:
+```
+http://localhost:3000/callback
+https://yourapp.com/callback
+```
+
+URL must match exactly — including trailing slashes and path.
+
+---
+
+## CORS error
+
+**Error:** `Access to fetch at 'https://tenant.auth0.com' has been blocked by CORS policy`
+
+**Fix:** Add your frontend origin to **Allowed Web Origins** in Auth0 Dashboard:
+```
+http://localhost:3000
+https://yourapp.com
+```
+
+Origin only — no path, no trailing slash.
+
+---
+
+## Redirect loop / infinite redirect
+
+**Checklist:**
+1. Is the callback route unprotected? The `/callback` handler must not require authentication.
+2. Is the post-login redirect target in **Allowed Callback URLs**?
+3. Next.js: Is the auth route at `app/auth/[auth0]/route.js` or `pages/api/auth/[...auth0].js`?
+
+---
+
+## invalid_grant / token expired
+
+**Cause:** Refresh token rotation already consumed the token, or the session expired.
+
+**Fix:** Redirect to login. This is expected behavior when sessions expire legitimately.
+
+---
+
+## AUTH0_DOMAIN includes https://
+
+**Error:** `Invalid URL` or `getaddrinfo ENOTFOUND https://...`
+
+**Fix:**
+```bash
+# Wrong
+AUTH0_DOMAIN=https://your-tenant.auth0.com
+
+# Correct
+AUTH0_DOMAIN=your-tenant.auth0.com
+```
+
+---
+
+## Missing user profile data (null name/email)
+
+**Fix:** Request the correct scopes:
+```javascript
+loginWithRedirect({
+  authorizationParams: { scope: 'openid profile email' }
+});
+```
+
+---
+
+## logout doesn't clear the Auth0 session
+
+**Fix:** Pass `returnTo` so Auth0 clears its session cookie:
+```javascript
+logout({ logoutParams: { returnTo: window.location.origin } });
+```
+
+Add the `returnTo` URL to **Allowed Logout URLs** in Auth0 Dashboard.
diff --git a/main/.mintlify/skills/auth0/references/pattern-multi-tenant/index.md b/main/.mintlify/skills/auth0/references/pattern-multi-tenant/index.md
new file mode 100644
index 0000000000..0ba6e7baca
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/pattern-multi-tenant/index.md
@@ -0,0 +1,73 @@
+# Multi-Tenant Architecture with Auth0
+
+---
+
+## The two models
+
+### Model 1: Organizations (recommended for B2B SaaS)
+
+One Auth0 tenant, multiple Organizations. Each customer gets an Organization with their own:
+- User pool (members)
+- Login connections (their Okta, Google Workspace, etc.)
+- Per-org roles and permissions
+
+Best for: SaaS platforms serving business customers who want SSO and user management isolation.
+
+(Organizations implementation is in feature-organizations.md — the router loads both for architecture questions.)
+
+### Model 2: Multiple Auth0 tenants
+
+One Auth0 tenant per customer. Maximally isolated.
+
+Best for: Regulated industries requiring dedicated infrastructure, or customers needing separate Auth0 configuration that can't be modeled with Organizations.
+
+Downsides: Operational complexity, higher cost, no cross-tenant user insight.
+
+---
+
+## Routing users to their organization
+
+**1. Email domain routing:**
+```javascript
+function getOrgForEmail(email) {
+  const domain = email.split('@')[1];
+  return orgsByDomain[domain]; // look up in your DB
+}
+
+const orgId = getOrgForEmail(userEmail);
+loginWithRedirect({ authorizationParams: { organization: orgId } });
+```
+
+**2. Subdomain routing:**
+```javascript
+const subdomain = window.location.hostname.split('.')[0]; // acme.yourapp.com → acme
+const orgId = await lookupOrgBySlug(subdomain);
+loginWithRedirect({ authorizationParams: { organization: orgId } });
+```
+
+---
+
+## Protecting API data by org
+
+```javascript
+function requireOrg(orgId) {
+  return (req, res, next) => {
+    if (req.auth.payload.org_id !== orgId) {
+      return res.status(403).json({ error: 'Access denied: wrong organization' });
+    }
+    next();
+  };
+}
+```
+
+---
+
+## Per-org SSO connections
+
+Each Organization can have dedicated enterprise connections (Okta SAML, Azure AD, Google Workspace):
+
+```bash
+auth0 orgs connections add --org-id org_xxx --connection-id con_xxx
+```
+
+Users in that org authenticate through their company's IdP automatically.
diff --git a/main/.mintlify/skills/auth0/references/pattern-rate-limiting/index.md b/main/.mintlify/skills/auth0/references/pattern-rate-limiting/index.md
new file mode 100644
index 0000000000..c6449ee038
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/pattern-rate-limiting/index.md
@@ -0,0 +1,80 @@
+# Auth0 Rate Limits
+
+---
+
+## Why you're getting 429s
+
+Auth0 enforces rate limits on:
+- **Management API** — `POST /api/v2/*` calls (creating users, updating apps, etc.)
+- **Authentication API** — `/oauth/token`, `/authorize` calls
+
+The limit depends on your Auth0 plan. Free tier limits are much lower than paid plans.
+
+Check your current limits: Auth0 Dashboard → Tenant Settings → Advanced → Rate Limiting.
+
+---
+
+## Handling 429 in code
+
+Always implement exponential backoff when calling the Management API:
+
+```javascript
+async function callManagementApi(fn, maxRetries = 3) {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (err.statusCode === 429) {
+        const retryAfter = parseInt(err.headers?.['retry-after'] || '1', 10);
+        const delay = retryAfter * 1000 * Math.pow(2, attempt);
+        await new Promise(r => setTimeout(r, delay));
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw new Error('Max retries exceeded');
+}
+```
+
+The `retry-after` header tells you exactly how many seconds to wait.
+
+---
+
+## Bulk operations
+
+Use the bulk import API instead of individual user creation calls:
+
+```bash
+auth0 api post /api/v2/jobs/users-imports \
+  --data '{"users": [...], "connection_id": "con_xxx", "upsert": true}'
+```
+
+---
+
+## Reducing Management API calls
+
+- **Cache JWKS**: Your JWT library should cache the JWKS response (5–10 min TTL).
+- **Cache user profiles**: Don't call `/api/v2/users/{id}` on every request. Cache 1–5 min.
+- **Use ID token claims**: For basic user info (name, email, picture), read from ID token — no API call needed.
+
+---
+
+## M2M token caching
+
+Never request a new M2M token on every API call. Cache and reuse until expiry:
+
+```javascript
+let cachedToken = null;
+let tokenExpiry = 0;
+
+async function getM2MToken() {
+  if (cachedToken && Date.now() < tokenExpiry - 60000) {
+    return cachedToken;
+  }
+  const data = await fetchNewM2MToken();
+  cachedToken = data.access_token;
+  tokenExpiry = Date.now() + (data.expires_in * 1000);
+  return cachedToken;
+}
+```
diff --git a/main/.mintlify/skills/auth0/references/pattern-security/index.md b/main/.mintlify/skills/auth0/references/pattern-security/index.md
new file mode 100644
index 0000000000..f911497032
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/pattern-security/index.md
@@ -0,0 +1,95 @@
+# Auth0 Security Best Practices
+
+---
+
+## Token validation
+
+**Always validate access tokens on the backend.** Never trust a token sent from a client without verifying it.
+
+```javascript
+// Express — using express-oauth2-jwt-bearer
+import { auth } from 'express-oauth2-jwt-bearer';
+
+const checkJwt = auth({
+  audience: process.env.AUTH0_AUDIENCE,
+  issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}/`,
+  tokenSigningAlg: 'RS256',
+});
+
+app.get('/api/data', checkJwt, (req, res) => {
+  // Token is validated — req.auth.payload has claims
+});
+```
+
+Validate these claims on every request:
+- `iss` — must match your Auth0 domain (`https://YOUR_TENANT.auth0.com/`)
+- `aud` — must match your API identifier
+- `exp` — must not be expired
+- `alg` — must be RS256 (default) or the alg you configured
+
+---
+
+## Scopes and RBAC
+
+Scopes limit what an access token can do. Define them in your Auth0 API settings.
+
+```javascript
+const { requiredScopes } = require('express-oauth2-jwt-bearer');
+
+app.delete('/api/resource/:id',
+  checkJwt,
+  requiredScopes('delete:resource'),
+  (req, res) => { /* authorized */ }
+);
+```
+
+For Role-Based Access Control (RBAC), enable it on the Auth0 API and assign roles to users. Roles produce a `permissions` claim in access tokens.
+
+---
+
+## Token storage
+
+| Context | Recommended storage | Avoid |
+|---|---|---|
+| Browser SPA | In-memory (SDK default) | localStorage (XSS risk) |
+| Server-side session | Encrypted session cookie (HttpOnly) | Unencrypted cookies |
+| Mobile | Secure platform keychain/keystore | Plain storage |
+| CI/CD | Env var / secrets manager | Source code |
+
+Auth0 SDKs handle storage automatically in their default configurations.
+
+---
+
+## PKCE (required for public clients)
+
+All SPA and mobile clients must use PKCE. Auth0 SDKs enforce this by default. Do not disable it.
+
+---
+
+## Client secrets
+
+- Client secrets are for server-side apps only (Regular Web App, Machine-to-Machine).
+- SPAs and native apps must NOT have a client secret — they use PKCE instead.
+- Rotate secrets if compromised: Auth0 Dashboard → Applications → [app] → Rotate Secret.
+
+---
+
+## Allowed URLs
+
+Be specific with callback and logout URLs:
+
+```
+# Too broad:
+https://example.com/*
+
+# Correct:
+https://example.com/callback
+https://example.com
+```
+
+---
+
+## Refresh token rotation
+
+Enable refresh token rotation to limit blast radius of a stolen token:
+Auth0 Dashboard → Applications → [app] → Refresh Token Rotation → Enable.
diff --git a/main/.mintlify/skills/auth0/references/pattern-token-handling/index.md b/main/.mintlify/skills/auth0/references/pattern-token-handling/index.md
new file mode 100644
index 0000000000..2d2305a796
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/pattern-token-handling/index.md
@@ -0,0 +1,77 @@
+# Token Handling Patterns
+
+---
+
+## Access token vs ID token
+
+| Token | Purpose | Use for |
+|---|---|---|
+| **Access token** | Authorization for an API | Calling your backend API |
+| **ID token** | User identity assertion | Reading user profile in your frontend |
+
+**Never send the ID token to your API** — instead, send the access token and validate it there. Never use the access token to read user profile in your frontend; instead, read profile info from the ID token (or the `/userinfo` endpoint).
+
+---
+
+## Getting an access token
+
+```javascript
+// React
+const { getAccessTokenSilently } = useAuth0();
+const token = await getAccessTokenSilently({
+  authorizationParams: { audience: 'https://api.example.com' }
+});
+
+// Next.js (nextjs-auth0 v4)
+import { auth0 } from '@/lib/auth0';
+const { token } = await auth0.getAccessToken();
+
+// Express (server-side, from the session)
+const token = req.oidc.accessToken.access_token;
+```
+
+---
+
+## Calling an API with an access token
+
+```javascript
+const response = await fetch('https://api.example.com/data', {
+  headers: { Authorization: `Bearer ${accessToken}` }
+});
+```
+
+---
+
+## Token expiry and silent renewal
+
+Call `getAccessTokenSilently()` before every API call — the SDK renews silently if the token is expired. Never cache tokens manually.
+
+---
+
+## Audience
+
+Always set `audience` in `authorizationParams`:
+
+```javascript
+loginWithRedirect({
+  authorizationParams: {
+    audience: 'https://api.example.com',
+    scope: 'openid profile email read:data'
+  }
+});
+```
+
+If you omit `audience`, you get an opaque Management API token — not useful for your custom API.
+
+---
+
+## Opaque tokens vs JWTs
+
+| Token type | Format | Validation |
+|---|---|---|
+| JWT (access token) | `header.payload.sig` | Verify locally with JWKS |
+| Opaque (Management API) | Random string | Introspection endpoint |
+
+For custom APIs, always use JWTs — they validate locally without a network call.
+
+JWKS endpoint: `https://YOUR_TENANT.auth0.com/.well-known/jwks.json`
diff --git a/main/.mintlify/skills/auth0-cli/SKILL.md b/main/.mintlify/skills/auth0/references/tooling-cli/index.md
similarity index 61%
rename from main/.mintlify/skills/auth0-cli/SKILL.md
rename to main/.mintlify/skills/auth0/references/tooling-cli/index.md
index 07307de1a8..240851751d 100644
--- a/main/.mintlify/skills/auth0-cli/SKILL.md
+++ b/main/.mintlify/skills/auth0/references/tooling-cli/index.md
@@ -1,30 +1,13 @@
----
-name: auth0-cli
-description: Reference for Auth0 CLI commands — apps, apis, users, roles, organizations, actions, logs, custom domains, universal-login, terraform, raw API mode, and --json output. Use this skill whenever you need to run Auth0 CLI commands to create or manage applications, APIs, users, roles, organizations, actions, log streams, custom domains, or Universal Login configuration, or when you need to call the Auth0 Management API directly. Trigger on prompts like "create an Auth0 app", "list my Auth0 users", "assign a role", "set up an organization", "deploy an action", "configure a custom domain", "generate Terraform for Auth0", "stream Auth0 logs", "call the Management API", or any task involving the auth0 CLI tool.
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
-  version: '1.0.0'
-  openclaw:
-    emoji: "\U0001F510"
-    homepage: https://github.com/auth0/agent-skills
-    requires:
-      bins:
-        - auth0
-    os:
-      - darwin
-      - linux
-    install:
-      - id: brew
-        kind: brew
-        package: auth0/auth0-cli/auth0
-        bins: [auth0]
-        label: 'Install Auth0 CLI (brew)'
----
+# Auth0 CLI — Tenant Configuration
+
+Use the Auth0 CLI when the project has no Terraform infrastructure and no active MCP session.
+This is the default tooling. Install with: `brew install auth0/auth0-cli/auth0`
+
+Authenticate: `auth0 login`
 
 # Auth0 CLI — Command Reference
 
-The Auth0 CLI (`auth0`) lets you manage your tenant from the terminal. Install with `brew install auth0/auth0-cli/auth0`. For complete flag definitions and examples, see the [Full CLI Reference](references/cli.md).
+The Auth0 CLI (`auth0`) lets you manage your tenant from the terminal. Install it via Homebrew (`brew install auth0/auth0-cli/auth0`). For complete flag definitions and examples, see the Full CLI Reference section below.
 
 ---
 
@@ -33,10 +16,10 @@ The Auth0 CLI (`auth0`) lets you manage your tenant from the terminal. Install w
 ```bash
 auth0 login                          # interactive device-code login
 auth0 login --scopes "read:client_grants"  # request extra scopes if 403
-auth0 login --domain <tenant>.auth0.com --client-id <id> --client-secret <secret>  # CI/CD
+auth0 login --domain <tenant>.auth0.com --client-id <id> --client-secret "$AUTH0_CLIENT_SECRET"  # CI/CD
 ```
 
-See [Authentication Details](references/cli.md#authentication) for machine login with JWT, tenant management, and logout.
+See the Authentication Details section below for machine login with JWT, tenant management, and logout.
 
 ---
 
@@ -72,20 +55,19 @@ Create or inspect Auth0 applications (client ID, secret, callback URLs, app type
 
 ```bash
 auth0 apps create --name "My SPA" --type spa \
+  --auth-method None \
   --callbacks "http://localhost:3000" \
   --logout-urls "http://localhost:3000" \
   --origins "http://localhost:3000" --json
 
 auth0 apps list --json-compact
-auth0 apps show <client-id> --reveal-secrets --json
+auth0 apps show <client-id> --json
 auth0 apps update <client-id> --callbacks "http://localhost:3000,https://myapp.com" --json
 auth0 apps delete <client-id> --force
 ```
 
 App types: `spa`, `regular`, `m2m`, `native`, `resource_server`
 
-Full details: [Apps Reference](references/cli.md#apps)
-
 ### APIs — Manage API Resources
 
 Register backend APIs (Resource Servers) to protect with Auth0 tokens. Alias: `auth0 resource-servers`.
@@ -100,8 +82,6 @@ auth0 apis scopes list <api-id> --json
 
 **Key distinction:** `apps` = the client requesting tokens. `apis` = the resource accepting tokens.
 
-Full details: [APIs Reference](references/cli.md#apis)
-
 ### Users — Manage Users
 
 Create, search, inspect, import, and manage users in your tenant.
@@ -110,7 +90,7 @@ Create, search, inspect, import, and manage users in your tenant.
 auth0 users search --query "email:user@example.com" --json
 auth0 users search-by-email user@example.com --json-compact
 auth0 users create --connection-name "Username-Password-Authentication" \
-  --email "test@example.com" --password "SecureP@ss!" --json
+  --email "test@example.com" --password "$USER_PASSWORD" --json
 auth0 users show <user-id> --json
 auth0 users blocks list <email> --json
 auth0 users blocks unblock <email>
@@ -118,11 +98,11 @@ auth0 users import --connection-name "Username-Password-Authentication" \
   --users '[...]' --upsert --json
 ```
 
-Full details: [Users Reference](references/cli.md#users)
+**Note:** `--json` output for user commands returns full profiles (email, metadata) and import payloads carry password hashes — avoid piping to shared logs/CI output.
 
 ### Roles — Manage RBAC Roles
 
-Create roles, assign permissions, and assign roles to users. The CLI has dedicated commands for all role operations.
+Create roles, assign permissions, and assign roles to users.
 
 ```bash
 auth0 roles create --name "editor" --description "Can edit content" --json
@@ -131,8 +111,6 @@ auth0 users roles assign <user-id> --roles <role-id>
 auth0 users roles show <user-id> --json-compact
 ```
 
-Full details: [Roles Reference](references/cli.md#roles)
-
 ### Organizations — B2B Multi-Tenancy
 
 Manage organizations for B2B SaaS scenarios. Alias: `auth0 orgs`.
@@ -145,11 +123,9 @@ auth0 orgs invitations create --org-id <org-id> --invitee-email "new@acme.com" \
   --inviter-name "Admin" --client-id <id> --json
 ```
 
-Full details: [Organizations Reference](references/cli.md#organizations)
-
 ### Actions — Serverless Auth Pipeline
 
-Create and deploy serverless functions at auth pipeline trigger points. Replaces deprecated Rules.
+Create and deploy serverless functions at auth pipeline trigger points.
 
 ```bash
 auth0 actions create --name "Add Claims" --trigger "post-login" \
@@ -161,8 +137,6 @@ Triggers: `post-login`, `credentials-exchange`, `pre-user-registration`, `post-u
 
 **Important:** You must `deploy` after creating or updating for changes to take effect.
 
-Full details: [Actions Reference](references/cli.md#actions)
-
 ### Logs — Debugging & Monitoring
 
 ```bash
@@ -172,8 +146,6 @@ auth0 logs list --filter "type:f" --number 20 --json-compact  # historical
 
 Common codes: `s` (success), `f` (failed login), `slo` (logout), `fs` (silent auth failure)
 
-Full details: [Logs Reference](references/cli.md#logs)
-
 ### Domains — Custom Domains
 
 ```bash
@@ -181,8 +153,6 @@ auth0 domains create --domain "auth.myapp.com" --type "auth0_managed_certs" --js
 auth0 domains verify <domain-id> --json
 ```
 
-Full details: [Domains Reference](references/cli.md#domains)
-
 ### Universal Login — Branding
 
 ```bash
@@ -190,16 +160,12 @@ auth0 ul update --accent "#FF6600" --background "#FFFFFF" \
   --logo "https://myapp.com/logo.png" --json
 ```
 
-Full details: [Universal Login Reference](references/cli.md#universal-login)
-
 ### Terraform — Export as IaC
 
 ```bash
 auth0 terraform generate --output-dir ./terraform --resources "auth0_client,auth0_connection"
 ```
 
-Full details: [Terraform Reference](references/cli.md#terraform)
-
 ### Test — Verify Login Flows
 
 ```bash
@@ -207,8 +173,6 @@ auth0 test login <client-id>
 auth0 test login <client-id> --audience "https://api.myapp.com" --scopes "openid profile email"
 ```
 
-Full details: [Test Reference](references/cli.md#test)
-
 ### Attack Protection — Security Hardening
 
 ```bash
@@ -217,8 +181,6 @@ auth0 protection breached-password-detection update --enabled true
 auth0 protection bot-detection update --enabled true
 ```
 
-Full details: [Attack Protection Reference](references/cli.md#attack-protection)
-
 ### Log Streams — External Routing
 
 ```bash
@@ -229,8 +191,6 @@ auth0 logs streams list --json
 
 Supported: eventbridge, eventgrid, http, datadog, splunk, sumo
 
-Full details: [Log Streams Reference](references/cli.md#log-streams)
-
 ### Raw API Mode — Direct Management API Access
 
 When a dedicated command doesn't exist, `auth0 api` calls Management API v2 endpoints directly.
@@ -241,13 +201,11 @@ auth0 api post client-grants --data '{"client_id":"...","audience":"...","scope"
 auth0 api get stats/daily -q "from=20240101" -q "to=20240131"
 ```
 
-Full details: [Raw API Reference](references/cli.md#raw-api-mode)
-
 ---
 
 ## Output Formatting
 
-Always use `--json` or `--json-compact` for machine-readable output. Three modes (mutually exclusive):
+Always use `--json` or `--json-compact` for machine-readable output.
 
 | Flag | When to use |
 |------|-------------|
@@ -261,40 +219,6 @@ auth0 users show <user-id> --json-compact | jq '{id: .user_id, email: .email}'
 auth0 roles list --json-compact | jq '.[].name'
 ```
 
-Full details: [Output Formatting Reference](references/cli.md#output-formatting)
-
----
-
-## Reference Documentation
-
-Complete CLI reference with all flags, examples, and usage patterns:
-- [Setup Guide](references/setup.md) — installation, authentication, CI/CD configuration
-- [Authentication](references/cli.md#authentication) — login modes, tenant management, scopes
-- [Apps](references/cli.md#apps) — create, list, show, update, delete, session-transfer
-- [APIs](references/cli.md#apis) — create, scopes, token lifetime
-- [Users](references/cli.md#users) — search, create, import, blocks, roles
-- [Roles](references/cli.md#roles) — RBAC setup, permissions management
-- [Organizations](references/cli.md#organizations) — B2B, members, invitations
-- [Actions](references/cli.md#actions) — pipeline triggers, deploy workflow
-- [Logs](references/cli.md#logs) — tail, list, type codes
-- [Domains](references/cli.md#domains) — custom domains, verification
-- [Universal Login](references/cli.md#universal-login) — branding, templates, prompts
-- [Terraform](references/cli.md#terraform) — IaC export
-- [Test](references/cli.md#test) — login flow verification
-- [Attack Protection](references/cli.md#attack-protection) — brute-force, breach, bot detection
-- [Log Streams](references/cli.md#log-streams) — external service routing
-- [Raw API Mode](references/cli.md#raw-api-mode) — direct Management API access
-- [Output Formatting](references/cli.md#output-formatting) — --json, --json-compact, --csv
-- [Shared Flags](references/cli.md#shared-flags) — --tenant, --no-input, --debug
-
----
-
-## Related Skills
-
-- `auth0-quickstart` — Initial Auth0 setup, framework detection
-- `auth0-migration` — Migrate from other auth providers
-- `auth0-mfa` — Multi-Factor Authentication setup
-
 ---
 
 ## References
diff --git a/main/.mintlify/skills/auth0/references/tooling-mcp/index.md b/main/.mintlify/skills/auth0/references/tooling-mcp/index.md
new file mode 100644
index 0000000000..987099c503
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/tooling-mcp/index.md
@@ -0,0 +1,84 @@
+# Auth0 MCP Server — Tenant Configuration
+
+Use the Auth0 MCP server when it is active in the current agent session (i.e., Auth0 tools appear in the tool list).
+
+The hosted Auth0 MCP server exposes a subset of Management API operations as agent tools. No CLI install required.
+
+---
+
+## Check if MCP is active
+
+Auth0 MCP tools are prefixed `auth0_` (e.g. `auth0_list_applications`). Check the available tools list.
+If no Auth0 tools are present, this session has no active MCP server — use the Auth0 CLI for tenant configuration instead.
+
+---
+
+## What the MCP server can and cannot do
+
+The MCP server covers a **narrower** surface than the CLI or Terraform. It exposes tools for
+applications, resource servers (APIs), application grants, actions, forms, logs, and onboarding/quickstarts.
+It does **not** cover the tenant features listed as "No" below.
+
+| Task | MCP tool available? | If not, use |
+|---|---|---|
+| Create / update an application (client) | Yes | — |
+| Create / update a resource server (API), incl. DPoP | Yes | — |
+| Create an application grant | Yes | — |
+| Manage actions / forms / read logs | Yes | — |
+| **MFA / Guardian factors** | **No** | Auth0 CLI or Terraform |
+| **Universal Login branding** | **No** | Auth0 CLI or Terraform |
+| **Organizations** | **No** | Auth0 CLI or Terraform |
+| **Custom domains** | **No** | Auth0 CLI or Terraform |
+| **ACUL rendering config** | **No** | Auth0 CLI or Terraform |
+
+When a task needs one of the "No" rows, do not fabricate a tool — tell the user the MCP server does
+not expose it and fall back to the CLI (or Terraform if the project is IaC-managed).
+
+---
+
+## Common configuration operations
+
+### Create an application (client)
+```
+Tool: auth0_create_application
+Parameters:
+  name: "My App"
+  app_type: "spa" | "regular_web" | "native" | "non_interactive"
+  callbacks: ["http://localhost:3000/callback"]
+  allowed_logout_urls: ["http://localhost:3000"]
+  web_origins: ["http://localhost:3000"]
+```
+
+### Create a resource server (API)
+```
+Tool: auth0_create_resource_server
+Parameters:
+  name: "My API"
+  identifier: "https://api.example.com"
+  signing_alg: "RS256"
+```
+
+### DPoP (sender-constrained tokens) on a resource server
+The resource-server tools accept a `proof_of_possession` object, passed straight
+through to the Management API. Setting `mechanism: "dpop"` and `required: true`
+makes the API reject plain bearer tokens.
+```
+Tool: auth0_update_resource_server
+Parameters:
+  id: "<resource server id>"
+  proof_of_possession:
+    mechanism: "dpop"
+    required: true
+    required_for: "all_clients"
+```
+The client-side toggle (`require_proof_of_possession`) is **not** exposed by the
+application tools — set it via the Auth0 CLI or Terraform.
+
+---
+
+## Notes
+
+- MCP operations call the Auth0 Management API directly — changes take effect immediately.
+- For bulk operations or infrastructure-as-code, prefer the Auth0 Terraform provider.
+- For scripting or CI/CD without a live MCP session, prefer the Auth0 CLI.
+- For anything in the "No" rows above (MFA, branding, organizations, custom domains, ACUL), use the CLI or Terraform.
diff --git a/main/.mintlify/skills/auth0/references/tooling-terraform/index.md b/main/.mintlify/skills/auth0/references/tooling-terraform/index.md
new file mode 100644
index 0000000000..d923cd867a
--- /dev/null
+++ b/main/.mintlify/skills/auth0/references/tooling-terraform/index.md
@@ -0,0 +1,193 @@
+# Auth0 Terraform Provider — Tenant Configuration
+
+Use the Auth0 Terraform provider when the project has a `terraform/` directory or `*.tf` files.
+This keeps Auth0 configuration in version-controlled infrastructure-as-code.
+
+Provider: `auth0/auth0` on the Terraform Registry.
+
+---
+
+## Setup
+
+```hcl
+# terraform/versions.tf
+terraform {
+  required_providers {
+    auth0 = {
+      source  = "auth0/auth0"
+      version = "~> 1.0"
+    }
+  }
+}
+
+provider "auth0" {
+  domain        = var.auth0_domain
+  client_id     = var.auth0_client_id
+  client_secret = var.auth0_client_secret
+}
+```
+
+Authenticate using a Machine-to-Machine application with the Auth0 Management API audience.
+
+---
+
+## Common resources
+
+### Application (client)
+```hcl
+resource "auth0_client" "my_app" {
+  name     = "My App"
+  app_type = "spa"
+
+  callbacks              = ["https://example.com/callback"]
+  allowed_logout_urls    = ["https://example.com"]
+  web_origins            = ["https://example.com"]
+  allowed_origins        = ["https://example.com"]
+
+  jwt_configuration {
+    alg = "RS256"
+  }
+}
+```
+
+### API (resource server)
+```hcl
+resource "auth0_resource_server" "my_api" {
+  name        = "My API"
+  identifier  = "https://api.example.com"
+  signing_alg = "RS256"
+
+  enforce_policies     = true
+  token_dialect        = "access_token_authz"
+  allow_offline_access = true
+}
+```
+
+### Organization
+```hcl
+resource "auth0_organization" "acme" {
+  name         = "acme-corp"
+  display_name = "Acme Corp"
+}
+
+resource "auth0_organization_member" "acme_admin" {
+  organization_id = auth0_organization.acme.id
+  user_id         = auth0_user.admin.id
+}
+
+resource "auth0_organization_connections" "acme_connections" {
+  organization_id = auth0_organization.acme.id
+
+  enabled_connections {
+    connection_id              = auth0_connection.acme_enterprise.id
+    assign_membership_on_login = true
+  }
+}
+```
+
+### MFA (Guardian)
+```hcl
+resource "auth0_guardian" "mfa" {
+  policy = "all-applications"
+
+  otp    { enabled = true }
+  email  { enabled = true }
+  webauthn_roaming { enabled = true }
+}
+```
+
+### Branding
+```hcl
+resource "auth0_branding" "main" {
+  logo_url        = "https://example.com/logo.png"
+  favicon_url     = "https://example.com/favicon.ico"
+
+  colors {
+    primary         = "#eb5424"
+    page_background = "#000000"
+  }
+}
+```
+
+### Custom domain
+```hcl
+resource "auth0_custom_domain" "main" {
+  domain = "login.example.com"
+  type   = "auth0_managed_certs"
+}
+
+resource "auth0_custom_domain_verification" "main" {
+  custom_domain_id = auth0_custom_domain.main.id
+
+  timeouts {
+    create = "15m"
+  }
+}
+```
+
+### DPoP (sender-constrained tokens)
+DPoP is configured per resource server (the API that must reject bearer replay)
+and per client (whether proof-of-possession is mandatory). There is no
+tenant-wide DPoP toggle.
+
+```hcl
+resource "auth0_resource_server" "my_api" {
+  name       = "My API"
+  identifier = "https://api.example.com"
+
+  proof_of_possession {
+    mechanism    = "dpop"          # "dpop" or "mtls"
+    required     = true            # reject non-DPoP tokens
+    required_for = "all_clients"   # or "public_clients"
+  }
+}
+
+resource "auth0_client" "my_app" {
+  name = "My App"
+
+  require_proof_of_possession = true
+}
+```
+
+### ACUL (Advanced Customization for Universal Login)
+The Terraform provider sets a screen's **rendering mode** to `advanced` (this is
+what turns ACUL on for that screen) and configures head tags. Building the screen
+components themselves is a code task done in the app — Terraform does not scaffold
+or deploy component code.
+
+```hcl
+resource "auth0_prompt_screen_renderer" "login_id" {
+  prompt_type    = "login-id"
+  screen_name    = "login-id"
+  rendering_mode = "advanced"      # "standard" or "advanced" (ACUL)
+
+  head_tags = jsonencode([
+    {
+      tag        = "script"
+      attributes = { src = "https://cdn.example.com/login-id.js", defer = true }
+    }
+  ])
+}
+```
+
+---
+
+## Workflow
+
+```bash
+cd terraform/
+terraform init
+terraform plan -var-file="auth0.tfvars"
+terraform apply -var-file="auth0.tfvars"
+```
+
+---
+
+## Variable file pattern
+
+```hcl
+# auth0.tfvars (add to .gitignore — contains secrets)
+auth0_domain        = "your-tenant.auth0.com"
+auth0_client_id     = "your-m2m-client-id"
+auth0_client_secret = "<YOUR_M2M_CLIENT_SECRET>"
+```
diff --git a/main/.mintlify/skills/auth0/scripts/render_pdf.sh b/main/.mintlify/skills/auth0/scripts/render_pdf.sh
new file mode 100755
index 0000000000..e97052bd6c
--- /dev/null
+++ b/main/.mintlify/skills/auth0/scripts/render_pdf.sh
@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# render_pdf.sh — convert a styled HTML report into PDF.
+# Usage: render_pdf.sh <input.html> <output.pdf>
+# Tries headless Chrome first (zero install on macOS), then wkhtmltopdf, then weasyprint.
+
+set -euo pipefail
+
+if [[ $# -ne 2 ]]; then
+  echo "Usage: $0 <input.html> <output.pdf>" >&2
+  exit 2
+fi
+
+INPUT="$1"
+OUTPUT="$2"
+
+if [[ ! -f "$INPUT" ]]; then
+  echo "render_pdf: input file not found: $INPUT" >&2
+  exit 1
+fi
+
+# Resolve to absolute paths — Chrome's --print-to-pdf is picky about cwd.
+INPUT_ABS="$(cd "$(dirname "$INPUT")" && pwd)/$(basename "$INPUT")"
+
+OUTPUT_PARENT="$(dirname "$OUTPUT")"
+if [[ ! -d "$OUTPUT_PARENT" ]]; then
+  echo "render_pdf: output directory does not exist: $OUTPUT_PARENT" >&2
+  exit 1
+fi
+OUTPUT_DIR="$(cd "$OUTPUT_PARENT" && pwd)"
+OUTPUT_ABS="$OUTPUT_DIR/$(basename "$OUTPUT")"
+
+CHROME_CANDIDATES=(
+  # PATH lookups first — works on any system where Chrome is on $PATH
+  google-chrome
+  google-chrome-stable
+  chromium
+  chromium-browser
+  chrome
+  microsoft-edge
+  microsoft-edge-stable
+  brave-browser
+
+  # macOS app bundles
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+  "/Applications/Chromium.app/Contents/MacOS/Chromium"
+  "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
+  "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
+  "/Applications/Arc.app/Contents/MacOS/Arc"
+
+  # Linux package locations
+  /usr/bin/google-chrome
+  /usr/bin/google-chrome-stable
+  /usr/bin/chromium
+  /usr/bin/chromium-browser
+  /usr/bin/microsoft-edge
+  /usr/bin/microsoft-edge-stable
+  /usr/bin/brave-browser
+  /opt/google/chrome/google-chrome
+  /opt/google/chrome/chrome
+  /snap/bin/chromium
+  /snap/bin/chrome
+
+  # Windows / WSL fallbacks
+  "/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
+  "/mnt/c/Program Files (x86)/Google/Chrome/Application/chrome.exe"
+  "/mnt/c/Program Files/Microsoft/Edge/Application/msedge.exe"
+  "/c/Program Files/Google/Chrome/Application/chrome.exe"
+  "/c/Program Files (x86)/Google/Chrome/Application/chrome.exe"
+)
+
+resolve_chrome() {
+  local cand="$1"
+  if [[ "$cand" == /* ]] || [[ "$cand" == "./"* ]]; then
+    [[ -x "$cand" ]] && printf '%s' "$cand" && return 0
+    return 1
+  fi
+  command -v "$cand" 2>/dev/null && return 0
+  return 1
+}
+
+CHROME=""
+for cand in "${CHROME_CANDIDATES[@]}"; do
+  if resolved="$(resolve_chrome "$cand")"; then
+    CHROME="$resolved"
+    break
+  fi
+done
+
+if [[ -n "$CHROME" ]]; then
+  echo "render_pdf: using $CHROME" >&2
+  # Render to a temp file and only promote it on success — a stale PDF already
+  # sitting at OUTPUT_ABS must never be mistaken for a fresh, successful render.
+  TMP_PDF="$(mktemp -t render_pdf.XXXXXX 2>/dev/null || echo "${OUTPUT_ABS}.tmp.$$")"
+  "$CHROME" \
+    --headless=new \
+    --disable-gpu \
+    --no-pdf-header-footer \
+    --print-to-pdf="$TMP_PDF" \
+    "file://$INPUT_ABS" \
+    >/dev/null 2>&1 \
+    || "$CHROME" \
+      --headless \
+      --disable-gpu \
+      --print-to-pdf="$TMP_PDF" \
+      "file://$INPUT_ABS" \
+      >/dev/null 2>&1 || true
+  if [[ -s "$TMP_PDF" ]]; then
+    mv -f "$TMP_PDF" "$OUTPUT_ABS"
+    echo "render_pdf: wrote $OUTPUT_ABS" >&2
+    exit 0
+  fi
+  rm -f "$TMP_PDF"
+  echo "render_pdf: Chrome produced no output; trying other renderers" >&2
+fi
+
+if command -v wkhtmltopdf >/dev/null 2>&1; then
+  echo "render_pdf: using wkhtmltopdf" >&2
+  wkhtmltopdf --enable-local-file-access "$INPUT_ABS" "$OUTPUT_ABS"
+  exit $?
+fi
+
+if command -v weasyprint >/dev/null 2>&1; then
+  echo "render_pdf: using weasyprint" >&2
+  weasyprint "$INPUT_ABS" "$OUTPUT_ABS"
+  exit $?
+fi
+
+cat >&2 <<EOF
+render_pdf: no PDF renderer found.
+Tried: Chrome / Chromium / Edge / Brave / Arc on macOS, Linux, WSL paths,
+       plus wkhtmltopdf and weasyprint.
+
+Install one of:
+  - Google Chrome  https://www.google.com/chrome  (recommended; zero-config)
+  - Chromium       (Linux: \`apt install chromium\` / \`dnf install chromium\`)
+  - wkhtmltopdf    (macOS: \`brew install --cask wkhtmltopdf\` · Linux: \`apt install wkhtmltopdf\`)
+  - weasyprint     (\`pip install weasyprint\` plus system cairo + pango)
+
+The HTML report is still at: $INPUT_ABS
+EOF
+exit 1
diff --git a/main/.mintlify/skills/auth0/scripts/validate-skill.sh b/main/.mintlify/skills/auth0/scripts/validate-skill.sh
new file mode 100755
index 0000000000..dc82466c8c
--- /dev/null
+++ b/main/.mintlify/skills/auth0/scripts/validate-skill.sh
@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Resolve repo root from script location (safe to run from any directory)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../../../.." && pwd)"
+
+SKILL_MD="$REPO_ROOT/plugins/auth0/skills/auth0/SKILL.md"
+REFS_DIR="$REPO_ROOT/plugins/auth0/skills/auth0/references"
+
+# Sanity check
+if [ ! -f "$SKILL_MD" ]; then
+  echo "ERROR: SKILL.md not found at $SKILL_MD — is this the right repo?"
+  exit 1
+fi
+
+# Extract description line
+DESC=$(grep "^description:" "$SKILL_MD" | sed 's/^description: //')
+DESC_LEN=${#DESC}
+
+echo "Description length: $DESC_LEN chars (limit: 1024)"
+echo "SKILL.md line count: $(wc -l < "$SKILL_MD")"
+
+if [ "$DESC_LEN" -gt 1024 ]; then
+  echo "FAIL: description exceeds 1024 chars"
+  exit 1
+fi
+
+if [ "$(wc -l < "$SKILL_MD")" -gt 600 ]; then
+  echo "FAIL: SKILL.md exceeds 600 lines"
+  exit 1
+fi
+
+TOTAL=$(ls -d "$REFS_DIR"/*/ 2>/dev/null | wc -l)
+echo "Reference directories: $TOTAL"
+
+# Router checks
+if ! grep -q "Detect intent" "$SKILL_MD"; then
+  echo "FAIL: SKILL.md missing 'Detect intent' section"
+  exit 1
+fi
+if ! grep -q "Detect framework" "$SKILL_MD"; then
+  echo "FAIL: SKILL.md missing 'Detect framework' section"
+  exit 1
+fi
+if ! grep -q "Detect tooling" "$SKILL_MD"; then
+  echo "FAIL: SKILL.md missing 'Detect tooling' section"
+  exit 1
+fi
+if ! grep -q "tooling-terraform" "$SKILL_MD"; then
+  echo "FAIL: SKILL.md missing tooling-terraform routing"
+  exit 1
+fi
+if ! grep -q "pattern-common-errors" "$SKILL_MD"; then
+  echo "FAIL: SKILL.md missing debug routing"
+  exit 1
+fi
+
+# Framework file checks. Every reference is a directory whose index.md the
+# router opens by name, so this loop just asserts index.md exists for each
+# expected framework. This list is a smoke check only; the authoritative
+# "every routed framework has a file and every file is routed" guarantee is
+# enforced by scripts/check_router_reachability.py (run below), which derives
+# slugs from the router itself. Keep this list in sync when adding frameworks.
+EXPECTED_FRAMEWORKS="react nextjs vue angular spa-js nuxt express flask fastify fastify-api java-mvc aspnetcore-auth aspnetcore-api php php-api express-jwt fastapi-api springboot-api go react-native expo ionic-angular ionic-react ionic-vue android swift flutter-native flutter-web laravel laravel-api maui net-android net-ios winforms wpf"
+for fw in $EXPECTED_FRAMEWORKS; do
+  if [ ! -f "$REFS_DIR/framework-$fw/index.md" ]; then
+    echo "FAIL: missing references/framework-$fw/index.md"
+    exit 1
+  fi
+done
+
+# Old files must be gone
+OLD_PATTERNS=$(ls "$REFS_DIR/react-"*.md "$REFS_DIR/nextjs-"*.md "$REFS_DIR/vue-"*.md 2>/dev/null | wc -l || true)
+if [ "$OLD_PATTERNS" -gt 0 ]; then
+  echo "FAIL: old framework-type files still exist (found $OLD_PATTERNS)"
+  exit 1
+fi
+
+# Feature file checks
+EXPECTED_FEATURES="mfa branding custom-domains migration acul dpop"
+for feat in $EXPECTED_FEATURES; do
+  if [ ! -f "$REFS_DIR/feature-$feat/index.md" ]; then
+    echo "FAIL: missing references/feature-$feat/index.md"
+    exit 1
+  fi
+done
+OLD_FEATURE=$(ls "$REFS_DIR/mfa-"*.md "$REFS_DIR/branding-"*.md "$REFS_DIR/acul-"*.md 2>/dev/null | wc -l || true)
+if [ "$OLD_FEATURE" -gt 0 ]; then
+  echo "FAIL: old feature source files still exist ($OLD_FEATURE files)"
+  exit 1
+fi
+
+if [ ! -f "$REFS_DIR/feature-organizations/index.md" ]; then
+  echo "FAIL: missing references/feature-organizations/index.md"
+  exit 1
+fi
+ORG_LINES=$(wc -l < "$REFS_DIR/feature-organizations/index.md")
+if [ "$ORG_LINES" -lt 80 ]; then
+  echo "FAIL: feature-organizations/index.md too short ($ORG_LINES lines, need 80+)"
+  exit 1
+fi
+
+for t in cli mcp terraform; do
+  if [ ! -f "$REFS_DIR/tooling-$t/index.md" ]; then
+    echo "FAIL: missing references/tooling-$t/index.md"
+    exit 1
+  fi
+done
+
+for p in security token-handling multi-tenant rate-limiting common-errors; do
+  if [ ! -f "$REFS_DIR/pattern-$p/index.md" ]; then
+    echo "FAIL: missing references/pattern-$p/index.md"
+    exit 1
+  fi
+done
+
+# Router reachability + no intra-references .md links
+REACH="$REPO_ROOT/scripts/check_router_reachability.py"
+if [ -f "$REACH" ]; then
+  echo "Running router reachability check..."
+  python3 "$REACH" "$REPO_ROOT/plugins/auth0/skills/auth0" || {
+    echo "FAIL: router reachability check failed"; exit 1;
+  }
+fi
+
+# Routing evals — curated requests resolve to a Step 4 section + reference files
+EVALS="$REPO_ROOT/scripts/check_routing_evals.py"
+if [ -f "$EVALS" ]; then
+  echo "Running routing evals check..."
+  python3 "$EVALS" "$REPO_ROOT/plugins/auth0/skills/auth0" || {
+    echo "FAIL: routing evals check failed"; exit 1;
+  }
+fi
+
+echo "PASS"
diff --git a/main/.mintlify/skills/express-oauth2-jwt-bearer/SKILL.md b/main/.mintlify/skills/express-oauth2-jwt-bearer/SKILL.md
deleted file mode 100644
index 7752ac91b0..0000000000
--- a/main/.mintlify/skills/express-oauth2-jwt-bearer/SKILL.md
+++ /dev/null
@@ -1,208 +0,0 @@
----
-name: express-oauth2-jwt-bearer
-description: Use when adding Auth0 token validation to Express or Node.js APIs - integrates express-oauth2-jwt-bearer SDK to protect Node.js API endpoints with JWT Bearer authentication, scope-based RBAC, claim validation, and optional DPoP support
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
----
-
-# Node OAuth2 JWT Bearer Integration
-
-The `express-oauth2-jwt-bearer` package provides Express middleware for validating Auth0 JWT Bearer access tokens. It handles token extraction, signature verification, audience and issuer validation, and expiry checks per RFC 6750 — letting you focus on business logic rather than JWT parsing.
-
-> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
-> ```bash
-> gh api repos/auth0/node-oauth2-jwt-bearer/releases/latest --jq '.tag_name'
-> ```
-> Use the returned version in all `package.json` dependency lines instead of any hardcoded version below.
-
-## Prerequisites
-
-- **Node.js** 18+ (20+ recommended; required for bootstrap script automation)
-- **Express** 4.x or 5.x
-- **npm** or **yarn**
-- An **Auth0 account** with a configured API (Resource Server)
-- **Auth0 CLI** (for automatic setup): `npm install -g @auth0/auth0-cli`
-
-## When NOT to Use
-
-| Use Case | Recommended Skill |
-|----------|------------------|
-| Building a server-side web app with login UI (Express sessions) | `auth0-express` |
-| Building a Next.js app with server-side auth | `auth0-nextjs` |
-| Building a React/Angular/Vue SPA | `auth0-react`, `auth0-angular`, `auth0-vue` |
-| Building a React Native or mobile app | `auth0-react-native`, `auth0-android`, `auth0-swift` |
-| ASP.NET Core Web API | `auth0-aspnetcore-api` |
-| Go API with JWT middleware | `go-jwt-middleware` |
-| Python API (Flask/FastAPI) | `auth0-api-python` |
-| Node.js API using the older `express-jwt` package | `express-jwt` |
-
-## Quick Start Workflow
-
-> **Agent instruction:** Follow these steps to integrate `express-oauth2-jwt-bearer` into the user's Node.js API project.
->
-> 1. **Fetch latest version** (see instruction above).
->
-> 2. **Install the SDK:**
->    ```bash
->    npm install express-oauth2-jwt-bearer
->    ```
->
-> 3. **Configure Auth0** — follow `references/setup.md`. If the user already provided their Auth0 Domain and API Audience in the prompt, use them directly — skip the bootstrap script and do NOT call `AskUserQuestion` to re-confirm. Otherwise, offer automatic setup via bootstrap script or manual setup.
->
-> 4. **Set up middleware** — add to `app.js` or `server.js`:
->    ```javascript
->    import { auth } from 'express-oauth2-jwt-bearer';
->
->    const checkJwt = auth({
->      issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
->      audience: process.env.AUTH0_AUDIENCE,
->    });
->
->    app.use(checkJwt); // apply globally, or per-route
->    ```
->
-> 5. **Protect endpoints** — apply middleware globally or to specific routes:
->    ```javascript
->    // Global protection
->    app.use(checkJwt);
->
->    // Or per-route
->    app.get('/api/private', checkJwt, (req, res) => {
->      res.json({ sub: req.auth.payload.sub });
->    });
->    ```
->
-> 6. **Add RBAC** (optional) — use `requiredScopes()` or `claimIncludes()` for permission-based access:
->    ```javascript
->    import { auth, requiredScopes, claimIncludes } from 'express-oauth2-jwt-bearer';
->
->    app.get('/api/messages', checkJwt, requiredScopes('read:messages'), (req, res) => {
->      res.json({ messages: [] });
->    });
->    ```
->    > **Important:** `requiredScopes` accepts a single argument — a space-separated string or an array. Do NOT pass multiple string arguments: `requiredScopes('read:msg', 'write:msg')` silently ignores everything after the first. Use `requiredScopes('read:msg write:msg')` or `requiredScopes(['read:msg', 'write:msg'])` instead.
->
-> 7. **Verify the integration** — build and test:
->    ```bash
->    node server.js
->    curl http://localhost:3000/api/private         # should return 401
->    curl -H "Authorization: Bearer <token>" http://localhost:3000/api/private  # should return 200
->    ```
->
-> 8. **Failcheck:** If the server fails to start or tokens are rejected unexpectedly, check `references/api.md` for common issues. After 5-6 failed iterations, use `AskUserQuestion` to ask the user for more details about their environment.
-
-## Detailed Documentation
-
-- **[Setup Guide](./references/setup.md)** — Auth0 API registration, .env configuration, bootstrap script for automated setup, and secret management
-- **[Integration Patterns](./references/integration.md)** — Protected endpoints, RBAC with scopes and claims, DPoP, CORS setup, error handling, and testing with curl
-- **[API Reference & Testing](./references/api.md)** — Full configuration options, claims reference, complete code example, testing checklist, and common issues
-
-## Common Mistakes
-
-| Mistake | Symptom | Fix |
-|---------|---------|-----|
-| Created an **Application** instead of an **API** in Auth0 Dashboard | Token validation fails; wrong audience | Create a new **API** (Resource Server) in Auth0 Dashboard → APIs |
-| Audience doesn't match API identifier exactly | `401 Unauthorized` — "Audience mismatch" | Copy the exact API Identifier string from Auth0 Dashboard → APIs |
-| Domain includes `https://` prefix | `Error: Invalid URL` at startup | Use hostname only: `your-tenant.us.auth0.com`, not `https://...` |
-| Checking `scope` claim instead of `permissions` for RBAC | 403 always returned or permissions ignored | Use `requiredScopes()` for scope-based RBAC; use `claimIncludes('permissions', 'read:data')` for Auth0 RBAC permission claims |
-| CORS not configured before auth middleware | Preflight OPTIONS requests return 401 | Add `cors()` middleware before `auth()` in the middleware chain |
-| `.env` file not loaded | `undefined` for domain/audience | Add `import 'dotenv/config'` at the top of the entry file |
-| `req.auth` is undefined | `TypeError: Cannot read properties of undefined` | Verify `checkJwt` middleware runs before the handler |
-
-## Related Skills
-
-- **[auth0-express](../auth0-express)** — For Express web apps with login UI (sessions, cookies)
-- **[auth0-nextjs](../auth0-nextjs)** — For Next.js server-side web apps
-- **[auth0-aspnetcore-api](../auth0-aspnetcore-api)** — BACKEND_API reference implementation for .NET
-- **[go-jwt-middleware](../go-jwt-middleware)** — JWT middleware for Go APIs
-- **[auth0-api-python](../auth0-api-python)** — JWT validation for Python APIs (Flask/FastAPI)
-
-## Quick Reference
-
-### Core Middleware
-
-| Function | Description | Returns |
-|----------|-------------|---------|
-| `auth(options?)` | JWT Bearer validation middleware | `Handler` — 401 if token invalid/missing |
-| `requiredScopes(scopes)` | Validates token has all required scopes | `Handler` — 403 if scopes missing |
-| `scopeIncludesAny(scopes)` | Validates token has at least one scope | `Handler` — 403 if no match |
-| `claimEquals(claim, value)` | Validates a claim equals a value | `Handler` — 401 if mismatch |
-| `claimIncludes(claim, ...values)` | Validates claim includes all values | `Handler` — 401 if incomplete |
-| `claimCheck(fn, desc?)` | Custom claim validation function | `Handler` — 401 if fn returns false |
-
-### Configuration Options
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `issuerBaseURL` | `string` | Auth0 domain with `https://` (required unless using env vars) |
-| `audience` | `string` | API Identifier from Auth0 Dashboard (required unless using env vars) |
-| `tokenSigningAlg` | `string` | Signing algorithm (default: `RS256`; use `HS256` for symmetric) |
-| `authRequired` | `boolean` | Set `false` to make authentication optional (default: `true`) |
-| `clockTolerance` | `number` | Clock skew tolerance in seconds (no default; undefined unless set) |
-| `dpop` | `DPoPOptions` | DPoP configuration (see integration.md) |
-
-### Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `ISSUER_BASE_URL` | Auth0 domain with `https://` (auto-detected by SDK) |
-| `AUDIENCE` | API Identifier (auto-detected by SDK) |
-
-### Request Object
-
-After successful validation, `req.auth` contains:
-```typescript
-req.auth.payload    // Decoded JWT payload (sub, iss, aud, exp, permissions, etc.)
-req.auth.header     // JWT header (alg, typ, kid)
-req.auth.token      // Raw JWT string
-```
-
-## SDK Architecture
-
-The `node-oauth2-jwt-bearer` monorepo contains three packages:
-
-| Package | Purpose |
-|---------|---------|
-| `express-oauth2-jwt-bearer` | **Main package.** Express middleware for JWT Bearer validation. Published to npm. |
-| `access-token-jwt` | Low-level JWT verification utilities (used internally). |
-| `oauth2-bearer` | RFC 6750 Bearer token extraction (used internally). |
-
-In practice, you only install and import `express-oauth2-jwt-bearer`.
-
-## Auth Flow Comparison
-
-| Auth Pattern | SDK | When to Use |
-|-------------|-----|-------------|
-| JWT Bearer (stateless) | `express-oauth2-jwt-bearer` | APIs called by SPAs, mobile apps, M2M clients |
-| Session-based (stateful) | `@auth0/express-openid-connect` | Web apps with login UI and server-side sessions |
-
-## Testing Quick Reference
-
-```bash
-# Get test token from Auth0 Dashboard → APIs → your API → Test tab
-# Copy the token, then:
-
-# 1. Verify 401 on protected route (no token)
-curl -v http://localhost:3000/api/private
-
-# 2. Verify 200 with valid token
-curl -H "Authorization: Bearer <paste-token-here>" http://localhost:3000/api/private
-
-# 3. Verify 403 with valid token but missing scope
-curl -H "Authorization: Bearer <paste-token-here>" http://localhost:3000/api/admin
-
-# 4. Verify CORS preflight
-curl -v -X OPTIONS http://localhost:3000/api/private \
-  -H "Origin: http://localhost:5173" \
-  -H "Access-Control-Request-Method: GET" \
-  -H "Access-Control-Request-Headers: Authorization"
-```
-
-## References
-
-- [express-oauth2-jwt-bearer on npm](https://www.npmjs.com/package/express-oauth2-jwt-bearer)
-- [GitHub: auth0/node-oauth2-jwt-bearer](https://github.com/auth0/node-oauth2-jwt-bearer)
-- [Auth0 Node.js API Quickstart](https://auth0.com/docs/quickstart/backend/nodejs/interactive)
-- [Auth0 APIs Dashboard](https://manage.auth0.com/#/apis)
-- [RFC 6750 — Bearer Token Usage](https://datatracker.ietf.org/doc/html/rfc6750)
diff --git a/main/.mintlify/skills/go-jwt-middleware/SKILL.md b/main/.mintlify/skills/go-jwt-middleware/SKILL.md
deleted file mode 100644
index 5ec7aa0050..0000000000
--- a/main/.mintlify/skills/go-jwt-middleware/SKILL.md
+++ /dev/null
@@ -1,536 +0,0 @@
----
-name: go-jwt-middleware
-description: Use when securing Go HTTP API endpoints with JWT Bearer token validation, scope/permission checks, or stateless auth. Integrates github.com/auth0/go-jwt-middleware/v3 for REST APIs receiving access tokens from frontends or mobile apps. Also handles DPoP proof-of-possession token binding. Triggers on jwtmiddleware, go-jwt-middleware, Go API auth, JWT validation, CheckJWT.
-license: Apache-2.0
-metadata:
-  author: Auth0 <support@auth0.com>
-  version: '1.0.0'
-  openclaw:
-    emoji: "\U0001F510"
-    homepage: https://github.com/auth0/agent-skills
-    requires:
-      bins:
-        - go
-        - auth0
-        - gh
-    os:
-      - darwin
-      - linux
-    install:
-      - id: brew
-        kind: brew
-        package: auth0/auth0-cli/auth0
-        bins: [auth0]
-        label: 'Install Auth0 CLI (brew)'
-      - id: brew
-        kind: brew
-        package: gh
-        bins: [gh]
-        label: 'Install GitHub CLI (brew)'
----
-
-# Go JWT Middleware Integration
-
-Protect Go HTTP API endpoints with JWT access token validation using github.com/auth0/go-jwt-middleware/v3.
-
-> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running:
-> ```bash
-> gh api repos/auth0/go-jwt-middleware/releases/latest --jq '.tag_name'
-> ```
-> Use the returned version in all dependency lines instead of any hardcoded version below.
-
----
-
-## Prerequisites
-
-- Go 1.21 or higher
-- Auth0 API configured (not Application - must be API resource)
-- If you don't have Auth0 set up yet, use the `auth0-quickstart` skill first
-
-## When NOT to Use
-
-- **Go server-rendered web applications** - Use `go-auth0` for session-based web apps
-- **Single Page Applications** - Use `auth0-react`, `auth0-vue`, or `auth0-angular` for client-side auth
-- **Mobile applications** - Use `auth0-swift`, `auth0-android`, or `auth0-react-native`
-- **Non-Go backends** - Use `auth0-aspnetcore-api` for .NET, `express-jwt` for Node.js
-
----
-
-## Quick Start Workflow
-
-### 1. Install SDK
-
-```bash
-go get github.com/auth0/go-jwt-middleware/v3
-go get github.com/joho/godotenv
-```
-
-### 2. Create Auth0 API
-
-You need an **API** (not Application) in Auth0.
-
-> **Agent instruction:** If the user's prompt already provides Auth0 credentials (domain and audience), use them directly — skip the setup choice question below and proceed to Step 3 to write the `.env` file.
->
-> **STOP — ask the user before proceeding.**
->
-> Ask exactly this question and wait for their answer before doing anything else:
->
-> > "How would you like to create the Auth0 API resource?
-> > 1. **Automated** — I'll use the Auth0 CLI to create the API resource and write the exact values to your .env file automatically.
-> > 2. **Manual** — You create the API yourself in the Auth0 Dashboard (or via `auth0 apis create`) and provide me the Domain and Audience.
-> >
-> > Which do you prefer? (1 = Automated / 2 = Manual)"
->
-> Do NOT proceed to any setup steps until the user has answered. Do NOT default to manual.
-
-**If the user chose Automated**, follow the [Setup Guide](references/setup.md) for the "Initial Setup" section (steps 1–6). The automated path writes `.env` for you — skip Step 3 below and proceed directly to Step 4.
-
-> **Agent instruction (Automated path checkpoints):**
->
-> When following the automated path, you MUST complete these checkpoints in order. Do NOT skip any:
->
-> 1. **Check Auth0 CLI** — verify `auth0` is installed.
-> 2. **Check Auth0 login** — run `auth0 tenants list` to verify authentication.
-> 3. **Confirm active tenant** — show the user which tenant is active and ask: _"Your active Auth0 tenant is `<domain>`. Is this the correct tenant?"_ Wait for confirmation. If they say no, ask them to run `auth0 tenants use <tenant>` in their terminal.
-> 4. **Ask about API name and identifier** — use `AskUserQuestion`: _"What would you like to name your Auth0 API, and what identifier (audience) should it use? For example: Name: 'My Go API', Identifier: 'https://my-api.example.com'. The identifier is a logical URI that doesn't need to resolve — it just uniquely identifies your API."_ Wait for answer. If the user is unsure, suggest deriving the identifier from the project's module name in go.mod (e.g., `https://<module-name>`).
-> 5. **Ask about scopes** — use `AskUserQuestion`: _"What scopes (permissions) does your API need? For example: `read:users`, `write:users`, `read:products`. If you're not sure yet, I can start with common defaults and you can add more later."_ Wait for answer.
-> 6. **Check for existing API** — run `auth0 apis list` and check if an API with the intended identifier already exists. If it does, ask the user whether to reuse it or create a new one with a different identifier.
-> 7. **Create the API resource** — using the name, identifier, and scopes from steps 4–5.
-> 8. **Handle .env** — if a `.env` file already exists, ask before modifying it. Never read existing `.env` contents (may contain secrets). If no `.env` exists, write one with `AUTH0_DOMAIN` and `AUTH0_AUDIENCE`.
-> 9. **Add `.env` to `.gitignore`** — if not already present.
-> 10. **Proceed to code integration** — skip Step 3 (already done) and go directly to Step 4 to write the middleware code.
-
-**If the user chose Manual**, follow the [Setup Guide](references/setup.md) (Manual Setup section) for full instructions. Then continue with Step 3 below.
-
-Quick reference for manual API creation:
-
-```bash
-# Using Auth0 CLI
-auth0 apis create \
-  --name "My Go API" \
-  --identifier https://my-api.example.com
-```
-
-Or create manually in Auth0 Dashboard → Applications → APIs
-
-### 3. Configure .env
-
-```env
-AUTH0_DOMAIN=your-tenant.auth0.com
-AUTH0_AUDIENCE=https://my-api.example.com
-```
-
-**Important:** Domain must NOT include `https://`. The middleware constructs the issuer URL automatically.
-
-### 4. Configure main.go
-
-> **Agent instruction (integrating with existing code):**
->
-> Before writing code, determine whether you are:
-> - **A) Adding auth to an existing project** — the user already has a `main.go` with routes defined. In this case, do NOT replace their file with the template below. Instead:
->   1. Add the necessary imports (`jwtmiddleware`, `jwks`, `validator`, `godotenv`, `net/url`, `os`, `context`, `strings`).
->   2. Add the `CustomClaims` struct and methods.
->   3. Add the middleware setup code (issuer URL, JWKS provider, validator, middleware) near the top of `main()`.
->   4. Ask which endpoints to protect (see below).
->   5. Wrap the specified handlers with `middleware.CheckJWT()`.
->
-> - **B) Creating a new project from scratch** — use the full template below as a starting point.
->
-> **STOP — ask which endpoints to protect:**
->
-> If the user's request does NOT explicitly specify which endpoints to protect, ask:
->
-> > "Which endpoints should require authentication? For example:
-> > - **All except health/public** — protect everything, leave only specific public routes open
-> > - **Specific routes** — tell me which routes need auth
-> >
-> > Also, do any endpoints need specific scope/permission checks (e.g., `write:users` for POST/DELETE), or is a valid JWT sufficient for all?"
->
-> Wait for the answer. If the user says "all" or "everything except health", protect all routes except `/health` (or whatever they specify as public). If they specify scope requirements per endpoint, implement per-route scope checks using `customClaims.HasScope()`.
-
-```go
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"log"
-	"net/http"
-	"net/url"
-	"os"
-	"strings"
-
-	jwtmiddleware "github.com/auth0/go-jwt-middleware/v3"
-	"github.com/auth0/go-jwt-middleware/v3/jwks"
-	"github.com/auth0/go-jwt-middleware/v3/validator"
-	"github.com/joho/godotenv"
-)
-
-// CustomClaims contains custom data we want from the token.
-type CustomClaims struct {
-	Scope       string   `json:"scope"`
-	Permissions []string `json:"permissions"`
-}
-
-func (c CustomClaims) Validate(ctx context.Context) error {
-	return nil
-}
-
-func (c CustomClaims) HasScope(expectedScope string) bool {
-	for _, scope := range strings.Split(c.Scope, " ") {
-		if scope == expectedScope {
-			return true
-		}
-	}
-	return false
-}
-
-func main() {
-	if err := godotenv.Load(); err != nil {
-		log.Fatalf("Error loading .env file: %v", err)
-	}
-
-	issuerURL, err := url.Parse("https://" + os.Getenv("AUTH0_DOMAIN") + "/")
-	if err != nil {
-		log.Fatalf("Failed to parse issuer URL: %v", err)
-	}
-
-	provider, err := jwks.NewCachingProvider(
-		jwks.WithIssuerURL(issuerURL),
-	)
-	if err != nil {
-		log.Fatalf("Failed to set up JWKS provider: %v", err)
-	}
-
-	jwtValidator, err := validator.New(
-		validator.WithKeyFunc(provider.KeyFunc),
-		validator.WithAlgorithm(validator.RS256),
-		validator.WithIssuer(issuerURL.String()),
-		validator.WithAudience(os.Getenv("AUTH0_AUDIENCE")),
-		validator.WithCustomClaims(func() validator.CustomClaims {
-			return &CustomClaims{}
-		}),
-	)
-	if err != nil {
-		log.Fatalf("Failed to set up JWT validator: %v", err)
-	}
-
-	middleware, err := jwtmiddleware.New(
-		jwtmiddleware.WithValidator(jwtValidator),
-	)
-	if err != nil {
-		log.Fatalf("Failed to set up JWT middleware: %v", err)
-	}
-
-	mux := http.NewServeMux()
-
-	// Public endpoint - no authentication
-	mux.HandleFunc("/api/public", func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]string{"message": "Hello from a public endpoint!"})
-	})
-
-	// Protected endpoint - requires valid JWT
-	mux.Handle("/api/private", middleware.CheckJWT(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
-		if err != nil {
-			http.Error(w, `{"message":"Failed to get token claims."}`, http.StatusInternalServerError)
-			return
-		}
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]string{
-			"message": "Hello from a private endpoint!",
-			"userId":  claims.RegisteredClaims.Subject,
-		})
-	})))
-
-	// Protected + scoped endpoint - requires JWT with specific scope
-	mux.Handle("/api/private-scoped", middleware.CheckJWT(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
-		if err != nil {
-			http.Error(w, `{"message":"Failed to get token claims."}`, http.StatusInternalServerError)
-			return
-		}
-		customClaims := claims.CustomClaims.(*CustomClaims)
-		if !customClaims.HasScope("read:messages") {
-			w.Header().Set("Content-Type", "application/json")
-			w.WriteHeader(http.StatusForbidden)
-			json.NewEncoder(w).Encode(map[string]string{"message": "Insufficient scope."})
-			return
-		}
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]string{"message": "Hello from a scoped endpoint!"})
-	})))
-
-	log.Println("Server listening on :8080")
-	log.Fatal(http.ListenAndServe(":8080", mux))
-}
-```
-
-### 5. Protect Endpoints
-
-Use `middleware.CheckJWT()` to wrap handlers that require authentication:
-
-```go
-// Public endpoint - no authentication
-mux.HandleFunc("/api/public", publicHandler)
-
-// Protected endpoint - requires valid JWT
-mux.Handle("/api/private", middleware.CheckJWT(http.HandlerFunc(privateHandler)))
-
-// Protected + scoped - requires JWT with specific permission
-mux.Handle("/api/private-scoped", middleware.CheckJWT(http.HandlerFunc(privateScopedHandler)))
-```
-
-### 6. Test API
-
-> **Agent instruction:** After writing the code, verify the build compiles:
-> ```bash
-> go build ./...
-> ```
-> If compilation fails, diagnose the error and fix it. Repeat up to 5-6 times.
->
-> **Failcheck:** If the build still fails after 5-6 fix attempts, stop and ask the user using `AskUserQuestion`:
-> _"The build is still failing after several fix attempts. How would you like to proceed?"_
-> - **Let me continue fixing iteratively**
-> - **Fix it manually** — I'll show the remaining errors
-> - **Skip build verification** — proceed without a successful build
->
-> Repeat this check after every 5-6 iterations if errors persist.
-
-> **Agent instruction: STOP — ask after build succeeds.**
->
-> Once the build compiles successfully, ask the user:
->
-> > "Your API is set up and compiles successfully. Would you like me to help you set up testing?
-> > 1. **Yes** — I'll help you configure an M2M application to get test tokens.
-> > 2. **No** — I'm done for now.
-> >
-> > Which do you prefer?"
->
-> Do NOT proceed with testing setup unless the user says yes. If they say no, summarize what was done and stop.
-
-> **Agent instruction (M2M app setup — only if user wants testing):**
->
-> If the user chose to set up testing, ask:
->
-> > "To test your protected endpoints, you need a Machine-to-Machine (M2M) application authorized to request tokens for this API.
-> > 1. **Create new** — I'll create a new M2M application and authorize it for this API.
-> > 2. **Use existing** — You already have an M2M application. Provide the Client ID and I'll authorize it for this API.
-> >
-> > Which do you prefer? (1 = Create new / 2 = Use existing)"
->
-> Do NOT proceed until the user answers. Do NOT silently pick an existing application from the tenant.
->
-> **If the user chose "Create new":**
-> ```bash
-> auth0 apps create \
->   --name "<PROJECT_NAME> (Test App)" \
->   --type m2m \
->   --no-input --json
-> ```
-> Parse the JSON to extract `client_id`. Do NOT use `--reveal-secrets` — never expose client secrets in agent context.
-> Then create a client grant:
-> ```bash
-> auth0 api post "client-grants" --data '{
->   "client_id": "<CLIENT_ID>",
->   "audience": "<API_IDENTIFIER>",
->   "scope": ["<SCOPES>"]
-> }'
-> ```
->
-> **If the user chose "Use existing":**
-> Ask for the Client ID. Then create a client grant to authorize it for this API:
-> ```bash
-> auth0 api post "client-grants" --data '{
->   "client_id": "<USER_PROVIDED_CLIENT_ID>",
->   "audience": "<API_IDENTIFIER>",
->   "scope": ["<SCOPES>"]
-> }'
-> ```
-> If the grant already exists (409 conflict), that's fine — the app is already authorized.
-
-> **Agent instruction (TOKEN ISOLATION — CRITICAL):**
->
-> The agent MUST NEVER directly see or display access token values. Token security rules:
-> - Do NOT run `auth0 test token` on its own — it outputs the token to stdout
-> - Do NOT run `curl` commands to the `/oauth/token` endpoint on their own
-> - Do NOT ask the user to paste their token into the conversation
-> - Do NOT echo, print, or log the token value
-> - Do NOT store the token in a file
->
-> **Secure testing approach (single-command chain):**
->
-> If the user explicitly asks to test the protected endpoints, the agent MAY use a single-command chain that captures the token into a shell variable and immediately uses it — the token value is never printed or visible to the agent:
->
-> ```bash
-> TEST_TOKEN=$(auth0 test token <CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2> 2>/dev/null | grep -o 'ey[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*') && \
-> [ -n "$TEST_TOKEN" ] && echo "Token acquired (${#TEST_TOKEN} chars)" && \
-> curl -s http://localhost:8080/<ENDPOINT> -H "Authorization: Bearer $TEST_TOKEN"
-> ```
->
-> **Security guarantees of this approach:**
-> - `$(...)` captures stdout — the token is consumed into the variable, not displayed
-> - `grep -o` extracts only the JWT pattern (ey...) — no surrounding output leaks
-> - `echo "Token acquired (${#TEST_TOKEN} chars)"` confirms success by printing LENGTH only, never the value
-> - The shell variable `$TEST_TOKEN` exists only for the duration of that single command chain — it dies immediately after
-> - Agent sees only: `"Token acquired (834 chars)"` + the API response body (JSON)
-> - No file is written, no env is exported, nothing persists
->
-> **Rules for using this pattern:**
-> 1. ONLY use when the user explicitly asks to test (e.g., "test it", "run the tests", "verify endpoints work")
-> 2. Always chain token acquisition + curl in a SINGLE `&&` command — never separate them into two Bash calls
-> 3. To test multiple endpoints, chain multiple curls in the same command:
->    ```bash
->    TEST_TOKEN=$(auth0 test token <CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2> 2>/dev/null | grep -o 'ey[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*') && \
->    [ -n "$TEST_TOKEN" ] && echo "Token acquired (${#TEST_TOKEN} chars)" && \
->    echo "=== GET /users ===" && \
->    curl -s http://localhost:8080/users -H "Authorization: Bearer $TEST_TOKEN" && \
->    echo "" && echo "=== POST /users ===" && \
->    curl -s -X POST http://localhost:8080/users -H "Authorization: Bearer $TEST_TOKEN" -d '{"id":"99","name":"Test","email":"test@example.com"}' && \
->    echo "" && echo "=== GET /products ===" && \
->    curl -s http://localhost:8080/products -H "Authorization: Bearer $TEST_TOKEN"
->    ```
-> 4. NEVER add `echo $TEST_TOKEN`, `printf $TEST_TOKEN`, or any command that would print the raw token value
-> 5. If the token acquisition fails (empty variable), the `[ -n "$TEST_TOKEN" ]` check will halt the chain — report to the user that the M2M app may not be authorized
-> 6. **Client ID is REQUIRED** — the `auth0 test token` command requires a Client ID to be passed as the first argument. This MUST be the `client_id` obtained from the M2M app setup step (create new or use existing). If the M2M step has not been completed yet (no Client ID available), do NOT attempt to run the test token command. Instead, ask the user: _"I need an M2M application Client ID to get a test token. Would you like me to create one or do you have an existing one?"_ — then complete the M2M setup first.
->
-> **If the user does NOT ask to test**, just provide the commands for them to run manually:
->
-> ```
-> auth0 test token <CLIENT_ID> --audience <AUDIENCE> --scopes <SCOPE1,SCOPE2>
-> curl http://localhost:8080/<endpoint> -H "Authorization: Bearer <PASTE_TOKEN_HERE>"
-> ```
-
-After M2M setup is complete:
-1. Start the server with `go run .` in the background
-2. Verify public endpoints return 200 and protected endpoints return 401 (no token needed)
-3. If the user asked to test: use the secure single-command chain above for authenticated requests
-4. If the user did NOT ask to test: provide the manual commands and tell them to run in their terminal
-
-Test public endpoint:
-
-```bash
-curl http://localhost:8080/api/public
-```
-
-Test protected endpoint without token (should return 401):
-
-```bash
-curl http://localhost:8080/api/private
-```
-
-Test protected endpoint with token (secure single-command chain):
-
-```bash
-TEST_TOKEN=$(auth0 test token <M2M_CLIENT_ID> --audience https://my-api.example.com --scopes <SCOPE1,SCOPE2> 2>/dev/null | grep -o 'ey[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*') && \
-[ -n "$TEST_TOKEN" ] && echo "Token acquired (${#TEST_TOKEN} chars)" && \
-curl -s http://localhost:8080/api/private -H "Authorization: Bearer $TEST_TOKEN"
-```
-
----
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Created Application instead of API in Auth0 | Must create API resource in Auth0 Dashboard → Applications → APIs |
-| Audience doesn't match API Identifier | Must exactly match the API Identifier set in Auth0 Dashboard |
-| Domain includes `https://` | Use `your-tenant.auth0.com` format only - the issuer URL is constructed automatically |
-| Using v2 positional parameters instead of v3 options | v3 uses `validator.WithKeyFunc()`, `validator.WithAlgorithm()` etc. |
-| Missing trailing slash on issuer URL | Issuer must be `https://domain/` with trailing slash |
-| Checking `scope` claim instead of `permissions` for RBAC | Use custom claims struct with `Permissions []string` field |
-| Missing `godotenv.Load()` call | Add `github.com/joho/godotenv` and call `godotenv.Load()` before reading env vars |
-| Using `ContextKey{}` to access claims (v2 pattern) | Use `jwtmiddleware.GetClaims[T]()` type-safe generics instead |
-
----
-
-## Scope-Based Authorization
-
-See [Integration Guide](references/integration.md) for defining and enforcing scope and permission policies.
-
----
-
-## CORS Configuration
-
-For APIs called from browser-based SPAs, configure CORS before any auth middleware:
-
-```go
-func corsMiddleware(next http.Handler) http.Handler {
-	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Access-Control-Allow-Origin", "http://localhost:3000")
-		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
-		w.Header().Set("Access-Control-Allow-Headers", "Authorization, Content-Type")
-		if r.Method == "OPTIONS" {
-			w.WriteHeader(http.StatusNoContent)
-			return
-		}
-		next.ServeHTTP(w, r)
-	})
-}
-```
-
-Apply it as the outermost handler wrapping your mux:
-
-```go
-handler := corsMiddleware(mux)
-log.Fatal(http.ListenAndServe(":8080", handler))
-```
-
-See [Integration Guide](references/integration.md) for detailed CORS patterns.
-
----
-
-## DPoP Support
-
-Built-in proof-of-possession token binding per RFC 9449. See [Integration Guide](references/integration.md) for configuration.
-
----
-
-## Related Skills
-
-- `auth0-quickstart` - Basic Auth0 setup
-- `auth0-mfa` - Add Multi-Factor Authentication
-
----
-
-## Quick Reference
-
-**Configuration Options:**
-- `validator.WithKeyFunc(provider.KeyFunc)` - JWKS key function for signature verification (required)
-- `validator.WithAlgorithm(validator.RS256)` - Expected signing algorithm (required)
-- `validator.WithIssuer(url)` - Token issuer URL with trailing slash (required)
-- `validator.WithAudience(aud)` - API Identifier from Auth0 API settings (required)
-- `validator.WithCustomClaims(fn)` - Factory for custom claims struct
-- `validator.WithAllowedClockSkew(d)` - Clock skew tolerance
-
-**Claims Access:**
-- `jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())` - Type-safe claims retrieval
-- `claims.RegisteredClaims.Subject` - User ID (sub)
-- `claims.CustomClaims.(*CustomClaims).Scope` - Space-separated scopes
-- `claims.CustomClaims.(*CustomClaims).Permissions` - Permission strings
-
-**Common Use Cases:**
-- Protect routes → `middleware.CheckJWT(handler)` (see Step 5)
-- Permission enforcement → [Integration Guide](references/integration.md)
-- DPoP token binding → [Integration Guide](references/integration.md)
-- Framework adapters (Gin, Echo) → [Integration Guide](references/integration.md)
-- Advanced JWT config → [API Reference](references/api.md)
-
----
-
-## Detailed Documentation
-
-- **[Setup Guide](references/setup.md)** - Auth0 CLI setup, environment configuration
-- **[Integration Guide](references/integration.md)** - Scope policies, DPoP, framework adapters, error handling
-- **[API Reference](references/api.md)** - Complete configuration options and validator/middleware reference
-
----
-
-## References
-
-- [Auth0 Go API Quickstart](https://auth0.com/docs/quickstart/backend/golang/interactive)
-- [SDK GitHub Repository](https://github.com/auth0/go-jwt-middleware)
-- [Go Package Documentation](https://pkg.go.dev/github.com/auth0/go-jwt-middleware/v3)
-- [Access Tokens Guide](https://auth0.com/docs/secure/tokens/access-tokens)
-- [Migration Guide (v2 to v3)](https://github.com/auth0/go-jwt-middleware/blob/master/MIGRATION_GUIDE.md)
diff --git a/main/.mintlify/skills/go-jwt-middleware/references/api.md b/main/.mintlify/skills/go-jwt-middleware/references/api.md
deleted file mode 100644
index 637867665e..0000000000
--- a/main/.mintlify/skills/go-jwt-middleware/references/api.md
+++ /dev/null
@@ -1,310 +0,0 @@
-# Go JWT Middleware API Reference
-
-Complete reference for github.com/auth0/go-jwt-middleware/v3 configuration options.
-
----
-
-## Validator Options
-
-Create a validator with `validator.New()` using functional options:
-
-```go
-jwtValidator, err := validator.New(
-	validator.WithKeyFunc(provider.KeyFunc),
-	validator.WithAlgorithm(validator.RS256),
-	validator.WithIssuer(issuerURL.String()),
-	validator.WithAudience(os.Getenv("AUTH0_AUDIENCE")),
-)
-```
-
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `validator.WithKeyFunc(fn)` | `func(context.Context) (any, error)` | Yes | Key function for signature verification. Use `provider.KeyFunc` from JWKS provider. |
-| `validator.WithAlgorithm(alg)` | `validator.Algorithm` | Yes | Expected signing algorithm. Use `validator.RS256` for Auth0. |
-| `validator.WithIssuer(url)` | `string` | Yes | Token issuer URL. Must be `https://{domain}/` with trailing slash. |
-| `validator.WithAudience(aud)` | `string` | Yes | Expected audience. Must match API Identifier in Auth0 Dashboard. |
-| `validator.WithCustomClaims(fn)` | `func() validator.CustomClaims` | No | Factory function returning a custom claims struct. |
-| `validator.WithAllowedClockSkew(d)` | `time.Duration` | No | Clock skew tolerance for token expiration. Default: 0. |
-
----
-
-## Middleware Options
-
-Create middleware with `jwtmiddleware.New()` using functional options:
-
-```go
-middleware, err := jwtmiddleware.New(
-	jwtmiddleware.WithValidator(jwtValidator),
-)
-```
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `jwtmiddleware.WithValidator(v)` | `core.Validator` | JWT validator instance (required) |
-| `jwtmiddleware.WithErrorHandler(fn)` | `func(http.ResponseWriter, *http.Request, error)` | Custom error response handler |
-| `jwtmiddleware.WithCredentialsOptional(b)` | `bool` | Allow requests without tokens (default: false) |
-| `jwtmiddleware.WithTokenExtractor(fn)` | `jwtmiddleware.TokenExtractor` | Custom token extraction from request |
-| `jwtmiddleware.WithExclusionUrls(urls)` | `[]string` | URL paths to skip JWT validation |
-| `jwtmiddleware.WithLogger(l)` | `*slog.Logger` | Structured logger for validation events |
-| `jwtmiddleware.WithDPoPMode(mode)` | `jwtmiddleware.DPoPMode` | DPoP proof-of-possession mode |
-| `jwtmiddleware.WithStandardProxy()` | - | Trust X-Forwarded-* headers for DPoP behind reverse proxies |
-
----
-
-## JWKS Provider Options
-
-Create a caching JWKS provider with `jwks.NewCachingProvider()`:
-
-```go
-provider, err := jwks.NewCachingProvider(
-	jwks.WithIssuerURL(issuerURL),
-)
-```
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `jwks.WithIssuerURL(url)` | `*url.URL` | Auth0 issuer URL. Fetches JWKS from `{url}.well-known/jwks.json`. |
-
----
-
-## Claims Reference
-
-### Registered Claims
-
-Access via `claims.RegisteredClaims`:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `Subject` | `string` | User ID (`sub` claim) |
-| `Issuer` | `string` | Token issuer (`iss` claim) |
-| `Audience` | `[]string` | Audience list (`aud` claim) |
-| `Expiry` | `*time.Time` | Expiration time (`exp` claim) |
-| `IssuedAt` | `*time.Time` | Issue time (`iat` claim) |
-
-### Custom Claims
-
-Access via `claims.CustomClaims.(*YourType)`:
-
-```go
-claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
-if err != nil {
-	// handle error
-}
-
-// Registered claims
-userId := claims.RegisteredClaims.Subject
-
-// Custom claims (requires CustomClaims registered with validator)
-customClaims := claims.CustomClaims.(*CustomClaims)
-scope := customClaims.Scope
-permissions := customClaims.Permissions
-```
-
----
-
-## DPoP Modes
-
-| Mode | Value | Behavior |
-|------|-------|----------|
-| Disabled | `jwtmiddleware.DPoPDisabled` | Standard JWT Bearer only (default) |
-| Allowed | `jwtmiddleware.DPoPAllowed` | Accept both DPoP-bound and standard Bearer tokens |
-| Required | `jwtmiddleware.DPoPRequired` | Only accept DPoP-bound tokens; reject standard Bearer |
-
----
-
-## Token Extractors
-
-| Extractor | Usage | Description |
-|-----------|-------|-------------|
-| Default (Header) | Automatic | Extracts from `Authorization: Bearer <token>` |
-| Cookie | `jwtmiddleware.CookieTokenExtractor("name")` | Extracts from named cookie |
-| Parameter | `jwtmiddleware.ParameterTokenExtractor("param")` | Extracts from URL query parameter |
-| Multi | `jwtmiddleware.MultiTokenExtractor(e1, e2, ...)` | Tries multiple extractors in order |
-
----
-
-## Supported Algorithms
-
-| Family | Algorithms |
-|--------|-----------|
-| HMAC | `HS256`, `HS384`, `HS512` |
-| RSA | `RS256`, `RS384`, `RS512` |
-| RSA-PSS | `PS256`, `PS384`, `PS512` |
-| ECDSA | `ES256`, `ES384`, `ES512`, `ES256K` |
-| EdDSA | `EdDSA` |
-
-Auth0 uses **RS256** by default. Always use `validator.RS256` for Auth0 JWKS validation.
-
----
-
-## Complete Code Example
-
-```go
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"log"
-	"log/slog"
-	"net/http"
-	"net/url"
-	"os"
-	"strings"
-
-	jwtmiddleware "github.com/auth0/go-jwt-middleware/v3"
-	"github.com/auth0/go-jwt-middleware/v3/jwks"
-	"github.com/auth0/go-jwt-middleware/v3/validator"
-	"github.com/joho/godotenv"
-)
-
-type CustomClaims struct {
-	Scope       string   `json:"scope"`
-	Permissions []string `json:"permissions"`
-}
-
-func (c CustomClaims) Validate(ctx context.Context) error {
-	return nil
-}
-
-func (c CustomClaims) HasScope(expectedScope string) bool {
-	for _, scope := range strings.Split(c.Scope, " ") {
-		if scope == expectedScope {
-			return true
-		}
-	}
-	return false
-}
-
-func main() {
-	if err := godotenv.Load(); err != nil {
-		log.Fatalf("Error loading .env file: %v", err)
-	}
-
-	issuerURL, err := url.Parse("https://" + os.Getenv("AUTH0_DOMAIN") + "/")
-	if err != nil {
-		log.Fatalf("Failed to parse issuer URL: %v", err)
-	}
-
-	provider, err := jwks.NewCachingProvider(
-		jwks.WithIssuerURL(issuerURL),
-	)
-	if err != nil {
-		log.Fatalf("Failed to set up JWKS provider: %v", err)
-	}
-
-	jwtValidator, err := validator.New(
-		validator.WithKeyFunc(provider.KeyFunc),
-		validator.WithAlgorithm(validator.RS256),
-		validator.WithIssuer(issuerURL.String()),
-		validator.WithAudience(os.Getenv("AUTH0_AUDIENCE")),
-		validator.WithCustomClaims(func() validator.CustomClaims {
-			return &CustomClaims{}
-		}),
-	)
-	if err != nil {
-		log.Fatalf("Failed to set up JWT validator: %v", err)
-	}
-
-	middleware, err := jwtmiddleware.New(
-		jwtmiddleware.WithValidator(jwtValidator),
-		jwtmiddleware.WithErrorHandler(func(w http.ResponseWriter, r *http.Request, err error) {
-			w.Header().Set("Content-Type", "application/json")
-			if errors.Is(err, jwtmiddleware.ErrJWTMissing) {
-				w.WriteHeader(http.StatusUnauthorized)
-				json.NewEncoder(w).Encode(map[string]string{"message": "Missing authorization token."})
-				return
-			}
-			w.WriteHeader(http.StatusUnauthorized)
-			json.NewEncoder(w).Encode(map[string]string{"message": "Invalid token."})
-		}),
-		jwtmiddleware.WithLogger(slog.Default()),
-	)
-	if err != nil {
-		log.Fatalf("Failed to set up JWT middleware: %v", err)
-	}
-
-	mux := http.NewServeMux()
-
-	mux.HandleFunc("/api/public", func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]string{"message": "Hello from a public endpoint!"})
-	})
-
-	mux.Handle("/api/private", middleware.CheckJWT(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		claims, _ := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]string{
-			"message": "Hello from a private endpoint!",
-			"userId":  claims.RegisteredClaims.Subject,
-		})
-	})))
-
-	mux.Handle("/api/private-scoped", middleware.CheckJWT(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		claims, _ := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
-		customClaims := claims.CustomClaims.(*CustomClaims)
-		if !customClaims.HasScope("read:messages") {
-			w.Header().Set("Content-Type", "application/json")
-			w.WriteHeader(http.StatusForbidden)
-			json.NewEncoder(w).Encode(map[string]string{"message": "Insufficient scope."})
-			return
-		}
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]string{"message": "Hello from a scoped endpoint!"})
-	})))
-
-	server := &http.Server{
-		Addr:    ":8080",
-		Handler: mux,
-	}
-
-	log.Println("Server listening on :8080")
-	log.Fatal(server.ListenAndServe())
-}
-```
-
----
-
-## Testing Checklist
-
-| Test | Command | Expected |
-|------|---------|----------|
-| Public endpoint | `curl http://localhost:8080/api/public` | 200 with message |
-| Private without token | `curl http://localhost:8080/api/private` | 401 |
-| Private with token | `curl -H "Authorization: Bearer TOKEN" http://localhost:8080/api/private` | 200 with userId |
-| Scoped with token | `curl -H "Authorization: Bearer TOKEN" http://localhost:8080/api/private-scoped` | 200 (with scope) or 403 |
-| Invalid token | `curl -H "Authorization: Bearer invalid" http://localhost:8080/api/private` | 401 |
-
----
-
-## Common Issues
-
-| Issue | Cause | Fix |
-|-------|-------|-----|
-| 401 on all requests | Wrong issuer URL | Ensure trailing slash: `https://domain/` |
-| 401 invalid_token | Audience mismatch | `AUTH0_AUDIENCE` must exactly match API identifier |
-| panic: nil pointer | Missing error check | Always check `err` from `New()` functions |
-| JWKS fetch fails | Network/firewall | Check connectivity to `https://domain/.well-known/jwks.json` |
-| Claims type assertion fails | Wrong type parameter | Use `GetClaims[*validator.ValidatedClaims]`, not `ValidatedClaims` |
-| v2 code doesn't compile | Breaking API changes | See [Migration Guide](https://github.com/auth0/go-jwt-middleware/blob/master/MIGRATION_GUIDE.md) |
-
----
-
-## Security Considerations
-
-- **Never hardcode Domain or Audience** - Use `.env` for development, environment variables for production
-- **Use HTTPS in production** - Auth0 requires HTTPS for secure token validation
-- **Use minimal scopes** - Only request and enforce scopes your API actually needs
-- **Keep packages updated** - Run `go get -u github.com/auth0/go-jwt-middleware/v3` for security patches
-- **Set appropriate clock skew** - Use `validator.WithAllowedClockSkew()` in distributed environments
-- **Validate custom claims** - Implement non-trivial `Validate()` logic when business rules require it
-
----
-
-## References
-
-- [Auth0 Go API Quickstart](https://auth0.com/docs/quickstart/backend/golang/interactive)
-- [SDK GitHub Repository](https://github.com/auth0/go-jwt-middleware)
-- [Go Package Documentation](https://pkg.go.dev/github.com/auth0/go-jwt-middleware/v3)
-- [Migration Guide (v2 to v3)](https://github.com/auth0/go-jwt-middleware/blob/master/MIGRATION_GUIDE.md)
diff --git a/main/.mintlify/skills/go-jwt-middleware/references/integration.md b/main/.mintlify/skills/go-jwt-middleware/references/integration.md
deleted file mode 100644
index 8c279d6807..0000000000
--- a/main/.mintlify/skills/go-jwt-middleware/references/integration.md
+++ /dev/null
@@ -1,484 +0,0 @@
-# Go JWT Middleware Integration Patterns
-
-Advanced integration patterns for Go API applications using go-jwt-middleware v3.
-
----
-
-## Permission-Based Authorization
-
-### Define Custom Claims
-
-```go
-type CustomClaims struct {
-	Scope       string   `json:"scope"`
-	Permissions []string `json:"permissions"`
-}
-
-func (c CustomClaims) Validate(ctx context.Context) error {
-	return nil
-}
-
-func (c CustomClaims) HasScope(expectedScope string) bool {
-	for _, scope := range strings.Split(c.Scope, " ") {
-		if scope == expectedScope {
-			return true
-		}
-	}
-	return false
-}
-
-func (c CustomClaims) HasPermission(expectedPermission string) bool {
-	for _, p := range c.Permissions {
-		if p == expectedPermission {
-			return true
-		}
-	}
-	return false
-}
-```
-
-### Register Custom Claims with Validator
-
-```go
-jwtValidator, err := validator.New(
-	validator.WithKeyFunc(provider.KeyFunc),
-	validator.WithAlgorithm(validator.RS256),
-	validator.WithIssuer(issuerURL.String()),
-	validator.WithAudience(os.Getenv("AUTH0_AUDIENCE")),
-	validator.WithCustomClaims(func() validator.CustomClaims {
-		return &CustomClaims{}
-	}),
-)
-```
-
-### Check Permissions in Handlers
-
-```go
-func privateScopedHandler(w http.ResponseWriter, r *http.Request) {
-	claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
-	if err != nil {
-		w.Header().Set("Content-Type", "application/json")
-		http.Error(w, `{"message":"Failed to get token claims."}`, http.StatusInternalServerError)
-		return
-	}
-
-	customClaims := claims.CustomClaims.(*CustomClaims)
-	if !customClaims.HasScope("read:messages") {
-		w.Header().Set("Content-Type", "application/json")
-		w.WriteHeader(http.StatusForbidden)
-		json.NewEncoder(w).Encode(map[string]string{"message": "Insufficient scope."})
-		return
-	}
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]string{"message": "Hello from a scoped endpoint!"})
-}
-```
-
-### Define Permissions in Auth0
-
-1. Go to Auth0 Dashboard → Applications → APIs
-2. Select your API
-3. Click the **Permissions** tab
-4. Add permissions matching your scope names (e.g., `read:messages`, `write:messages`)
-
-### Request Tokens with Scopes
-
-Clients must request tokens that include the required scopes:
-
-```bash
-curl -X POST https://your-tenant.auth0.com/oauth/token \
-  -H "Content-Type: application/json" \
-  -d '{
-    "client_id": "YOUR_CLIENT_ID",
-    "client_secret": "YOUR_CLIENT_SECRET",
-    "audience": "https://my-api.example.com",
-    "grant_type": "client_credentials",
-    "scope": "read:messages write:messages"
-  }'
-```
-
----
-
-## CORS Configuration
-
-For APIs called from browser-based SPAs, configure CORS before the JWT middleware. CORS must handle preflight OPTIONS requests before auth:
-
-```go
-func corsMiddleware(next http.Handler) http.Handler {
-	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Access-Control-Allow-Origin", "http://localhost:3000")
-		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
-		w.Header().Set("Access-Control-Allow-Headers", "Authorization, Content-Type")
-		w.Header().Set("Access-Control-Max-Age", "86400")
-
-		if r.Method == "OPTIONS" {
-			w.WriteHeader(http.StatusNoContent)
-			return
-		}
-
-		next.ServeHTTP(w, r)
-	})
-}
-```
-
-Apply CORS before JWT middleware:
-
-```go
-mux := http.NewServeMux()
-mux.HandleFunc("/api/public", publicHandler)
-mux.Handle("/api/private", middleware.CheckJWT(http.HandlerFunc(privateHandler)))
-
-// CORS wraps the entire mux — must be outermost
-handler := corsMiddleware(mux)
-log.Fatal(http.ListenAndServe(":8080", handler))
-```
-
-For production, replace the hardcoded origin with your SPA domain. Use the `rs/cors` package for more advanced CORS configuration:
-
-```bash
-go get github.com/rs/cors
-```
-
-```go
-import "github.com/rs/cors"
-
-c := cors.New(cors.Options{
-	AllowedOrigins:   []string{"https://your-spa.example.com"},
-	AllowedMethods:   []string{"GET", "POST", "PUT", "DELETE"},
-	AllowedHeaders:   []string{"Authorization", "Content-Type"},
-	AllowCredentials: true,
-})
-
-handler := c.Handler(mux)
-```
-
----
-
-## DPoP Support
-
-DPoP (Demonstrating Proof of Possession, RFC 9449) binds tokens to a specific client key pair, preventing token theft.
-
-### Enable DPoP
-
-```go
-middleware, err := jwtmiddleware.New(
-	jwtmiddleware.WithValidator(jwtValidator),
-	jwtmiddleware.WithDPoPMode(jwtmiddleware.DPoPAllowed),
-)
-```
-
-### DPoP Required Mode
-
-To reject standard Bearer tokens and accept only DPoP-bound tokens:
-
-```go
-middleware, err := jwtmiddleware.New(
-	jwtmiddleware.WithValidator(jwtValidator),
-	jwtmiddleware.WithDPoPMode(jwtmiddleware.DPoPRequired),
-)
-```
-
-### DPoP Modes
-
-| Mode | Behavior |
-|------|----------|
-| `jwtmiddleware.DPoPDisabled` | Standard JWT Bearer only, DPoP disabled |
-| `jwtmiddleware.DPoPAllowed` | Accept both DPoP-bound and standard Bearer tokens |
-| `jwtmiddleware.DPoPRequired` | Only accept DPoP-bound tokens; reject standard Bearer |
-
-### Trusted Proxy Configuration
-
-For APIs behind a reverse proxy (e.g., nginx, AWS ALB):
-
-```go
-middleware, err := jwtmiddleware.New(
-	jwtmiddleware.WithValidator(jwtValidator),
-	jwtmiddleware.WithDPoPMode(jwtmiddleware.DPoPRequired),
-	jwtmiddleware.WithStandardProxy(),
-)
-```
-
----
-
-## Accessing Claims
-
-### Type-Safe Claims Retrieval (v3)
-
-```go
-claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
-if err != nil {
-	http.Error(w, "Failed to get claims", http.StatusInternalServerError)
-	return
-}
-
-userId := claims.RegisteredClaims.Subject
-issuer := claims.RegisteredClaims.Issuer
-customClaims := claims.CustomClaims.(*CustomClaims)
-```
-
-### Common JWT Claims
-
-| Claim | Go Access Pattern | Description |
-|-------|-------------------|-------------|
-| `sub` | `claims.RegisteredClaims.Subject` | User ID (subject) |
-| `iss` | `claims.RegisteredClaims.Issuer` | Token issuer (your Auth0 tenant URL) |
-| `aud` | `claims.RegisteredClaims.Audience` | Audience (your API identifier) |
-| `exp` | `claims.RegisteredClaims.Expiry` | Expiration timestamp |
-| `iat` | `claims.RegisteredClaims.IssuedAt` | Issued-at timestamp |
-| `scope` | `customClaims.Scope` | Space-separated list of granted scopes |
-| `permissions` | `customClaims.Permissions` | Permission strings (RBAC) |
-
-Custom claims added via Auth0 Actions use namespaced keys. Add them to your `CustomClaims` struct:
-
-```go
-type CustomClaims struct {
-	Scope       string   `json:"scope"`
-	Permissions []string `json:"permissions"`
-	Email       string   `json:"https://your-domain.com/email"`
-}
-```
-
----
-
-## Error Handling
-
-### Custom Error Handler
-
-```go
-func customErrorHandler(w http.ResponseWriter, r *http.Request, err error) {
-	w.Header().Set("Content-Type", "application/json")
-
-	if errors.Is(err, jwtmiddleware.ErrJWTMissing) {
-		w.WriteHeader(http.StatusUnauthorized)
-		json.NewEncoder(w).Encode(map[string]string{
-			"error":   "missing_token",
-			"message": "Authorization header with Bearer token is required.",
-		})
-		return
-	}
-
-	w.WriteHeader(http.StatusUnauthorized)
-	json.NewEncoder(w).Encode(map[string]string{
-		"error":   "invalid_token",
-		"message": "The provided token is invalid.",
-	})
-}
-
-middleware, err := jwtmiddleware.New(
-	jwtmiddleware.WithValidator(jwtValidator),
-	jwtmiddleware.WithErrorHandler(customErrorHandler),
-)
-```
-
-### Standard Error Responses
-
-| Status | Cause | Fix |
-|--------|-------|-----|
-| 401 | Missing or invalid token | Include valid `Authorization: Bearer <token>` header |
-| 401 | Expired token | Request a fresh access token |
-| 401 | Wrong audience | Token's `aud` claim must match your API Identifier |
-| 403 | Insufficient scope | Token must include required scopes/permissions |
-
----
-
-## Mixed Public and Protected Endpoints
-
-```go
-mux := http.NewServeMux()
-
-// Public - no auth needed
-mux.HandleFunc("/api/public", publicHandler)
-
-// Protected - requires valid JWT
-mux.Handle("/api/private", middleware.CheckJWT(http.HandlerFunc(privateHandler)))
-
-// Protected with scope - requires JWT + specific permission
-mux.Handle("/api/private-scoped", middleware.CheckJWT(http.HandlerFunc(privateScopedHandler)))
-```
-
----
-
-## Optional Credentials Mode
-
-Allow endpoints to work for both authenticated and unauthenticated users:
-
-```go
-middleware, err := jwtmiddleware.New(
-	jwtmiddleware.WithValidator(jwtValidator),
-	jwtmiddleware.WithCredentialsOptional(true),
-)
-```
-
-In your handler, check if claims exist:
-
-```go
-func handler(w http.ResponseWriter, r *http.Request) {
-	if jwtmiddleware.HasClaims(r.Context()) {
-		claims, _ := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
-		// Authenticated user
-	} else {
-		// Anonymous user
-	}
-}
-```
-
----
-
-## URL Exclusions
-
-Skip JWT validation for specific paths:
-
-```go
-middleware, err := jwtmiddleware.New(
-	jwtmiddleware.WithValidator(jwtValidator),
-	jwtmiddleware.WithExclusionUrls([]string{"/health", "/metrics", "/api/public"}),
-)
-```
-
----
-
-## Framework Adapters
-
-### Gin
-
-```go
-import "github.com/gin-gonic/gin"
-
-r := gin.Default()
-
-r.GET("/api/public", func(c *gin.Context) {
-	c.JSON(200, gin.H{"message": "public"})
-})
-
-r.GET("/api/private", gin.WrapH(middleware.CheckJWT(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-	claims, _ := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]string{"userId": claims.RegisteredClaims.Subject})
-}))))
-```
-
-### Echo
-
-```go
-import "github.com/labstack/echo/v4"
-
-e := echo.New()
-
-e.GET("/api/public", func(c echo.Context) error {
-	return c.JSON(200, map[string]string{"message": "public"})
-})
-
-e.GET("/api/private", echo.WrapHandler(middleware.CheckJWT(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-	claims, _ := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]string{"userId": claims.RegisteredClaims.Subject})
-}))))
-```
-
----
-
-## Structured Logging
-
-```go
-import "log/slog"
-
-middleware, err := jwtmiddleware.New(
-	jwtmiddleware.WithValidator(jwtValidator),
-	jwtmiddleware.WithLogger(slog.Default()),
-)
-```
-
----
-
-## Custom Token Extraction
-
-### From Cookie
-
-```go
-middleware, err := jwtmiddleware.New(
-	jwtmiddleware.WithValidator(jwtValidator),
-	jwtmiddleware.WithTokenExtractor(jwtmiddleware.CookieTokenExtractor("jwt")),
-)
-```
-
-### From Query Parameter
-
-```go
-middleware, err := jwtmiddleware.New(
-	jwtmiddleware.WithValidator(jwtValidator),
-	jwtmiddleware.WithTokenExtractor(jwtmiddleware.ParameterTokenExtractor("token")),
-)
-```
-
-### Multiple Sources
-
-```go
-middleware, err := jwtmiddleware.New(
-	jwtmiddleware.WithValidator(jwtValidator),
-	jwtmiddleware.WithTokenExtractor(jwtmiddleware.MultiTokenExtractor(
-		jwtmiddleware.AuthHeaderTokenExtractor,
-		jwtmiddleware.CookieTokenExtractor("jwt"),
-	)),
-)
-```
-
----
-
-## Testing
-
-### Unit Testing with httptest
-
-```go
-func TestPublicEndpoint_Returns200(t *testing.T) {
-	mux := setupRouter() // your function that sets up routes
-	req := httptest.NewRequest("GET", "/api/public", nil)
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusOK {
-		t.Errorf("expected 200, got %d", w.Code)
-	}
-}
-
-func TestPrivateEndpoint_WithoutToken_Returns401(t *testing.T) {
-	mux := setupRouter()
-	req := httptest.NewRequest("GET", "/api/private", nil)
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusUnauthorized {
-		t.Errorf("expected 401, got %d", w.Code)
-	}
-}
-```
-
-### Testing with a Real Token
-
-```bash
-# Get a token via Auth0 CLI (uses client credentials for M2M apps)
-TOKEN=$(auth0 test token <M2M_CLIENT_ID> --audience https://my-api.example.com --scopes "read:messages" --json | jq -r '.access_token')
-
-# Test private endpoint
-curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/private
-```
-
----
-
-## Security Considerations
-
-- **Never hardcode Domain or Audience** - Always use `.env` or environment variables
-- **Use HTTPS in production** - Auth0 requires HTTPS for token validation
-- **Use minimal scopes** - Only request and enforce scopes your API actually needs
-- **Set appropriate clock skew** - Use `validator.WithAllowedClockSkew()` for distributed systems
-- **Validate custom claims** - Implement the `Validate()` method on your custom claims struct
-- **Use DPoP for high-security APIs** - Prevents token theft and replay attacks
-- **Keep packages updated** - Run `go get -u github.com/auth0/go-jwt-middleware/v3` regularly
-
----
-
-## References
-
-- [API Reference](api.md)
-- [Setup Guide](setup.md)
-- [Main Skill](../SKILL.md)
diff --git a/main/.mintlify/skills/go-jwt-middleware/references/setup.md b/main/.mintlify/skills/go-jwt-middleware/references/setup.md
deleted file mode 100644
index 2c969de9c6..0000000000
--- a/main/.mintlify/skills/go-jwt-middleware/references/setup.md
+++ /dev/null
@@ -1,353 +0,0 @@
-# Go JWT Middleware Setup Guide
-
-Setup instructions for Go API applications.
-
----
-
-## Auth0 Configuration
-
-> **Agent instruction:**
->
-> **Credential check (always first):**
-> If the user's prompt already provides Auth0 credentials (domain and audience), use them directly. Write the `.env` file and proceed to integration. Do NOT call `AskUserQuestion` to re-confirm.
->
-> **If credentials are NOT in the prompt:**
->
-> Use `AskUserQuestion` to ask the user:
-> "How would you like to configure Auth0 for this project?"
-> - Option A: "Automatic setup (recommended)" — uses the Auth0 CLI to create the API resource
-> - Option B: "Manual setup" — provide Auth0 credentials manually
->
-> **If Automatic Setup:**
->
-> **Important:** Do NOT run `auth0 login` from the agent — it is interactive and will hang. If the user needs to log in, ask them to run it in their terminal.
->
-> ---
-> **INITIAL SETUP (steps 1–6) — always run during automated setup:**
->
-> 1. **Check Auth0 CLI**: Run `command -v auth0`. If missing, ask user to install (`brew install auth0/auth0-cli/auth0`) or switch to manual setup.
-> 2. **Check Auth0 login**: Run `auth0 tenants list --csv --no-input 2>&1`. If it fails or returns empty:
->    - Tell the user: _"Please run `auth0 login` in your terminal and let me know when done."_
->    - Wait for the user to confirm, then re-run the check to verify.
-> 3. **Confirm active tenant**: Parse the output to identify the active tenant domain. Tell the user: _"Your active Auth0 tenant is: `<domain>`. Is this the correct tenant?"_
->    - If yes, proceed.
->    - If no, ask the user to run `auth0 tenants use <tenant-domain>` in their terminal, then re-run step 2 to confirm the new active tenant.
-> 4. **Create the Auth0 API resource**: Ask for the API name, identifier, and scopes (see SKILL.md checkpoints 4–5 for exact prompts).
->    **Before creating**, check if an API with the same identifier already exists:
->    ```bash
->    auth0 apis list --json 2>&1 | grep -c "<INTENDED_IDENTIFIER>"
->    ```
->    If it already exists, ask the user: _"An API with identifier `<ID>` already exists. Would you like to reuse it, or should I create a new one with a different identifier?"_
->    If creating new:
->    ```bash
->    auth0 apis create \
->      --name "<API_NAME>" \
->      --identifier <API_IDENTIFIER> \
->      --scopes "<COMMA_SEPARATED_SCOPES>" \
->      --no-input --json
->    ```
->    If creation fails with a conflict/duplicate error, inform the user and ask how to proceed.
->    Parse the JSON output to extract the `identifier` (audience) value.
-> 5. **Write `.env` file**:
->    - **Never read the contents of an existing `.env` file** — it may contain sensitive secrets that should not be exposed in the LLM context.
->    - If a `.env` file already exists, ask the user for confirmation using `AskUserQuestion`: _"A `.env` file already exists in this project. Can I add the Auth0 configuration to it?"_
->    - If no `.env` exists, create it with `AUTH0_DOMAIN` (from the active tenant in step 3) and `AUTH0_AUDIENCE` (from step 4).
-> 6. **Add `.env` to `.gitignore`** if not already present.
->
-> After step 6, proceed to code integration (SKILL.md Step 4).
->
-> ---
-> **TESTING SETUP (steps 7–8) — only run when user agrees to test (SKILL.md Step 6):**
->
-> 7. **M2M application setup**: Use `AskUserQuestion` to ask:
->    _"Would you like me to create a new Machine-to-Machine application to test your API, or do you have an existing application you'd like to authorize?"_
->    - **Option A: "Create a new M2M app"** — Create a new M2M application and authorize it against the API:
->      ```bash
->      auth0 apps create \
->        --name "<PROJECT_NAME> (Test App)" \
->        --type m2m \
->        --no-input --json
->      ```
->      Parse the JSON output to extract the `client_id`. **Do NOT use `--reveal-secrets`** — the agent must never handle client secrets. Tell the user: _"Your M2M app has been created. To get the client secret, run `auth0 apps show <CLIENT_ID> --reveal-secrets` in your terminal."_
->      Then create a client grant to authorize the app for the API:
->      ```bash
->      auth0 api post "client-grants" --data '{
->        "client_id": "<CLIENT_ID>",
->        "audience": "<API_IDENTIFIER>",
->        "scope": ["<SCOPES>"]
->      }'
->      ```
->    - **Option B: "Use an existing application"** — Ask the user for the `client_id` of their existing application. Then create a client grant to authorize it for this API:
->      ```bash
->      auth0 api post "client-grants" --data '{
->        "client_id": "<CLIENT_ID>",
->        "audience": "<API_IDENTIFIER>",
->        "scope": ["<SCOPES>"]
->      }'
->      ```
->      If the grant already exists (409 conflict), that's fine — the app is already authorized.
->
-> 8. **Test endpoints (TOKEN ISOLATION — CRITICAL)**:
->    The agent MUST NEVER directly see or display access token values.
->
->    **If the user explicitly asks to test**, use the secure single-command chain pattern.
->    The token is captured into a shell variable via `$(...)`, never printed, and dies when the command ends:
->    ```bash
->    TEST_TOKEN=$(auth0 test token <CLIENT_ID> --audience <API_IDENTIFIER> --scopes <SCOPE1,SCOPE2> 2>/dev/null | grep -o 'ey[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*') && \
->    [ -n "$TEST_TOKEN" ] && echo "Token acquired (${#TEST_TOKEN} chars)" && \
->    curl -s http://localhost:8080/<ENDPOINT> -H "Authorization: Bearer $TEST_TOKEN"
->    ```
->    Security guarantees:
->    - Token goes into `$TEST_TOKEN` — stdout is consumed, not displayed
->    - Only the token LENGTH is echoed (e.g., "Token acquired (834 chars)")
->    - Shell variable dies at end of command chain — no persistence between calls
->    - Agent sees only: confirmation line + API response JSON
->    - No file written, no env exported
->
->    Rules:
->    - ONLY use when user explicitly asks to test
->    - Always chain token capture + all curls in a SINGLE `&&` command
->    - NEVER echo/print/log the raw token value
->    - NEVER split into multiple Bash calls (variable won't persist)
->    - **Client ID is REQUIRED** — `auth0 test token` needs the M2M app's `client_id` as the first argument. If the M2M setup step (step 7) has not been completed, do NOT attempt to run this. Complete M2M setup first to obtain the Client ID.
->
->    **If the user does NOT ask to test**, provide the manual commands:
->    ```bash
->    auth0 test token <CLIENT_ID> \
->      --audience <API_IDENTIFIER> \
->      --scopes <SCOPE1,SCOPE2>
->    ```
->    Then:
->    ```bash
->    curl -H "Authorization: Bearer <PASTE_TOKEN_HERE>" http://localhost:8080/<ENDPOINT>
->    ```
->
->    The agent MAY always verify unauthenticated behavior:
->    - Public/health endpoints return 200
->    - Protected endpoints return 401 without a token
->
-> ---
-> **If Manual Setup:**
->
-> Ask the user for:
-> - Auth0 Domain (e.g., `your-tenant.auth0.com`)
-> - API Audience (e.g., `https://my-api.example.com`)
->
-> Write the `.env` file with provided values.
-
-## Quick Setup (Automated)
-
-Below uses the Auth0 CLI to create an Auth0 API resource and retrieve your credentials.
-
-### Step 1: Install Auth0 CLI and create API resource
-
-```bash
-# Install Auth0 CLI (macOS)
-brew install auth0/auth0-cli/auth0
-
-# Login (opens browser for authentication)
-auth0 login
-
-# Create an Auth0 API resource
-auth0 apis create \
-  --name "My Go API" \
-  --identifier https://my-api.example.com \
-  --json
-```
-
-Note the `identifier` value - this is your Audience.
-
-### Step 1b: Create or authorize an application for token generation
-
-To test your API, you need an application authorized to request tokens for this API:
-
-```bash
-# Create a Machine-to-Machine application
-auth0 apps create \
-  --name "My Go API (Test App)" \
-  --type m2m \
-  --no-input --json
-```
-
-Note the `client_id` from the JSON output. Then authorize it for your API by creating a client grant:
-
-```bash
-auth0 api post "client-grants" --data '{
-  "client_id": "YOUR_M2M_CLIENT_ID",
-  "audience": "https://my-api.example.com",
-  "scope": ["read:messages"]
-}'
-```
-
-To retrieve the client secret for manual token requests, run in your terminal:
-```bash
-auth0 apps show YOUR_M2M_CLIENT_ID --reveal-secrets
-```
-
-If you already have an application you'd like to use, run the same `auth0 api post "client-grants"` command with your existing app's `client_id` to authorize it for this API.
-
-### Step 2: Add configuration
-
-Once you have your Domain and Audience, create a `.env` file in your project root:
-
-```env
-AUTH0_DOMAIN=your-tenant.auth0.com
-AUTH0_AUDIENCE=https://my-api.example.com
-```
-
-Replace `your-tenant.auth0.com` with your Auth0 tenant domain and `https://my-api.example.com` with the identifier you used when creating the API resource.
-
----
-
-## Manual Setup
-
-### Install Dependencies
-
-```bash
-go get github.com/auth0/go-jwt-middleware/v3
-go get github.com/joho/godotenv
-```
-
-### Create Auth0 API Resource
-
-1. Go to Auth0 Dashboard → Applications → APIs
-2. Click **Create API**
-3. Set a **Name** and an **Identifier** (e.g., `https://my-api.example.com`)
-4. Note the Identifier - this is your `Audience`
-
-### Configure .env
-
-```env
-AUTH0_DOMAIN=your-tenant.auth0.com
-AUTH0_AUDIENCE=https://my-api.example.com
-```
-
-**Important:** Domain format is `your-tenant.auth0.com` - do NOT include `https://`.
-
-### Get Auth0 Configuration
-
-- **Domain:** Auth0 Dashboard → Settings → Domain (or `auth0 tenants list`)
-- **Audience:** The identifier you set when creating the API resource
-
----
-
-## Post-Setup Steps
-
-> **Agent instruction:** After setup, verify:
-> 1. `.env` file exists with `AUTH0_DOMAIN` and `AUTH0_AUDIENCE`
-> 2. `go.mod` includes `github.com/auth0/go-jwt-middleware/v3` and `github.com/joho/godotenv`
-> 3. Run `go build ./...` to verify compilation
-
----
-
-## Secret Management
-
-For Go BACKEND_API projects:
-- **Development:** `.env` file loaded via `godotenv.Load()`
-- **Production:** Environment variables (`AUTH0_DOMAIN`, `AUTH0_AUDIENCE`)
-- **No client secret needed** - JWT validation uses JWKS public keys from Auth0's well-known endpoint
-
-Add `.env` to `.gitignore` to prevent committing credentials:
-
-```bash
-echo ".env" >> .gitignore
-```
-
----
-
-## Getting a Test Token
-
-To test your protected API, you need an access token issued for your API's audience. You can use an existing authorized application or create a new Machine-to-Machine (M2M) app.
-
-### Create an M2M Application (if you don't have one)
-
-```bash
-# Create a new M2M application
-auth0 apps create \
-  --name "My Go API (Test App)" \
-  --type m2m \
-  --no-input --json
-```
-
-Note the `client_id` from the output. To get the client secret, run `auth0 apps show <CLIENT_ID> --reveal-secrets` in your terminal. Then authorize the app for your API:
-
-```bash
-auth0 api post "client-grants" --data '{
-  "client_id": "YOUR_M2M_CLIENT_ID",
-  "audience": "https://my-api.example.com",
-  "scope": ["read:messages"]
-}'
-```
-
-### Via Auth0 CLI
-
-```bash
-auth0 test token <M2M_CLIENT_ID> \
-  --audience https://my-api.example.com \
-  --scopes read:messages,write:messages
-```
-
-For M2M apps, this uses the client credentials grant automatically and returns the access token.
-
-### Via curl (Client Credentials Flow)
-
-```bash
-curl -s -X POST https://your-tenant.auth0.com/oauth/token \
-  -H "Content-Type: application/json" \
-  -d '{
-    "client_id": "YOUR_M2M_CLIENT_ID",
-    "client_secret": "YOUR_M2M_CLIENT_SECRET",
-    "audience": "https://my-api.example.com",
-    "grant_type": "client_credentials"
-  }'
-```
-
-The response JSON contains an `access_token` field — use it in the `Authorization: Bearer <token>` header.
-
-### Via Auth0 Dashboard
-
-1. Go to Auth0 Dashboard → Applications → APIs
-2. Select your API
-3. Click the **Test** tab
-4. Click **Copy Token** to get a test access token
-
----
-
-## Verification
-
-```bash
-# Start server
-go run main.go
-
-# Test public endpoint (should return 200)
-curl http://localhost:8080/api/public
-
-# Test protected endpoint without token (should return 401)
-curl http://localhost:8080/api/private
-
-# Test protected endpoint with token (should return 200)
-curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-  http://localhost:8080/api/private
-```
-
----
-
-## Troubleshooting
-
-**401 Unauthorized - "invalid_token":** Verify that the `AUTH0_AUDIENCE` in .env exactly matches your API Identifier in Auth0 Dashboard.
-
-**401 Unauthorized - "invalid_issuer":** Ensure `AUTH0_DOMAIN` does not include `https://` - use `your-tenant.auth0.com` format only. Also ensure the issuer URL has a trailing slash (`https://domain/`).
-
-**JWKS fetch fails:** Check network connectivity to `https://your-tenant.auth0.com/.well-known/jwks.json`. Verify the domain is correct.
-
-**Token expired:** Test tokens from the Dashboard are short-lived. Request a fresh token.
-
-**panic: nil pointer:** Always check the `err` return value from `jwtmiddleware.New()`, `validator.New()`, and `jwks.NewCachingProvider()`.
-
----
-
-## Next Steps
-
-- [Integration Guide](integration.md)
-- [API Reference](api.md)
-- [Main Skill](../SKILL.md)