Add link checker GitHub workflow

.github/workflows/link-check.yml

@@ -0,0 +1,95 @@
+name: Link Checker
+run-name: Link Checker (${{ github.event_name }} • ${{ github.ref_name }})
+
+on:
+  pull_request:
+    paths:
+    # Only run when docs files change in either site
+    - 'main/**/*.md'
+    - 'main/**/*.mdx'
+    - 'main/**/*.jsx'
+    - 'auth4genai/**/*.md'
+    - 'auth4genai/**/*.mdx'
+    - 'auth4genai/**/*.jsx'
+  workflow_dispatch: {} # Manual run (full scan for both sites)
+
+concurrency:
+  # One link-check run per ref; newer runs cancel older ones on the same branch/PR
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  link-check:
+    name: Link Checker (${{ matrix.site.name }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read # required by checkout and changed-files
+
+    strategy:
+      # If one site fails (auth0 vs auth0-genai), do not cancel the other
+      fail-fast: false
+      matrix:
+        site:
+        - name: auth0
+          path: main
+        - name: auth0-genai
+          path: auth4genai
+
+    steps:
+    - name: Checkout repo
+      # https://github.com/actions/checkout
+      # Pin to v6.0.0 tag commit for supply-chain safety
+      uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+
+    - name: Get changed files
+      # Only needed on PRs; for manual runs we always scan everything
+      if: github.event_name == 'pull_request'
+      id: changed
+      # https://github.com/yumemi-inc/changed-files
+      # Pin to v3.2.0 tag commit for supply-chain safety
+      uses: yumemi-inc/changed-files@50f2544ad88b4f274eace9689431b7281132304c # v3.2.0
+      with:
+        # Only consider docs files in the current site (from the matrix)
+        patterns: |
+          ${{ matrix.site.path }}/**/*.md
+          ${{ matrix.site.path }}/**/*.mdx
+          ${{ matrix.site.path }}/**/*.jsx
+        # Ignore deletions; we care about content that still exists
+        statuses: 'added|modified|renamed'
+        # Plain space-separated list, easier to feed into lychee args
+        format: 'plain'
+
+    - name: Decide Lychee targets
+      id: targets
+      # Run if:
+      # - not a PR (manual full scan), OR
+      # - PR with at least one changed file in this site
+      if: >
+        github.event_name != 'pull_request' ||
+        steps.changed.outputs.files != ''
+      run: |
+        # On PRs, use the list of changed files from the previous step.
+        # On manual runs, scan the whole docs tree for that site.
+        echo "targets=${{ github.event_name == 'pull_request' && steps.changed.outputs.files || format('''{0}/**/*.md'' ''{0}/**/*.mdx'' ''{0}/**/*.jsx''', matrix.site.path) }}" >> "$GITHUB_OUTPUT"
+
+    - name: Run Lychee on target
+      id: lychee
+      # Skip if we somehow ended up with no targets
+      if: steps.targets.outputs.targets != ''
+      # https://github.com/lycheeverse/lychee-action
+      # Pin to v2.7.0 tag commit
+      uses: lycheeverse/lychee-action@a8c4c7cb88f0c7386610c35eb25108e448569cb0 # v2.7.0
+      continue-on-error: true # let the job finish and report even if links are broken
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # used for GitHub API calls (e.g. rate limits, private links)
+      with:
+        fail: false # FIXME: Once the config, links, and fixes have stabilized, we should enable for hard block. For now this is just informative
+        # Important bits:
+        # - --root-dir ties file:// URLs to the correct site root
+        # - --format detailed + --verbose for useful CI logs
+        # - ${targets} is either changed files (PR) or whole tree (manual run)
+        args: >
+          --root-dir "$(pwd)/${{ matrix.site.path }}"
+          --format detailed
+          --verbose
+          ${{ steps.targets.outputs.targets }}

.gitignore

@@ -6,3 +6,5 @@ temp/
 *.py
 
 .vite
+
+.lycheecache

README.md

@@ -63,3 +63,56 @@ pnpm add -g mint
 - **Custom port**: `mint dev --port 3333`
 
 For more details, see the [Mintlify CLI documentation](https://mintlify.com/docs/installation).
+
+## Link Checking
+
+We use [Lychee](https://lychee.cli.rs/) to check for broken links across both documentation sites (`main/` and `auth4genai/`).  
+All configuration and exclusions live in [`lychee.toml`](lychee.toml), and both local runs and CI use the same rules.
+
+### Local Usage
+
+There are two recommended ways to check links locally, depending on what you want to validate.
+
+#### 1. Check links as they behave on auth0.com
+
+This mode asks Lychee to treat absolute paths like `/docs/...` as if they were being loaded from the live site.  
+It is useful when you want to confirm that public links resolve correctly through redirects, locale routing, or dynamically rendered pages.
+
+**Main docs:**
+```bash
+lychee --format detailed --verbose --base-url https://auth0.com \
+  'main/**/*.md' 'main/**/*.mdx' 'main/**/*.jsx'
+````
+
+**Auth0 for AI Agents docs:**
+
+```bash
+lychee --format detailed --verbose --base-url https://auth0.com/ai/docs \
+  'auth4genai/**/*.md' 'auth4genai/**/*.mdx' 'auth4genai/**/*.jsx'
+```
+
+#### 2. Check links against the local filesystem
+
+This mode validates only links that actually exist in the repo.
+It is useful when you’re working on local references (images, snippets, relative paths) and want to ensure nothing in the tree is broken.
+
+**Main docs:**
+
+```bash
+lychee --format detailed --verbose --root-dir "$(pwd)/main" \
+  'main/**/*.md' 'main/**/*.mdx' 'main/**/*.jsx'
+```
+
+**Auth0 for AI Agents docs:**
+
+```bash
+lychee --format detailed --verbose --root-dir "$(pwd)/auth4genai" \
+  'auth4genai/**/*.md' 'auth4genai/**/*.mdx' 'auth4genai/**/*.jsx'
+```
+
+### Notes
+
+* You can combine `--base-url` and glob patterns however you like; the examples above are the patterns used in CI.
+* Any URLs that need to be ignored should be added to `lychee.toml`, not passed on the command line.
+* Lychee caches results locally, so repeat runs are much faster.
+* Mintlify already checks internal routes during `mint dev`, so Lychee is mainly for external links and static references.

auth4genai/.vale/README.md

@@ -54,7 +54,7 @@ Vale parses `.mdx` files using `mdx2vast`. The parser automatically ignores:
 * JSX components and JSX blocks
 * fenced code blocks
 * inline backtick code
-* URLs (see [URL handling](https://vale.sh/docs/topics/urls))
+* URLs (see Vale’s URL handling notes: https://github.com/errata-ai/vale/issues/320)
 * single-line `{ ... }` JavaScript expressions
 
 These defaults help avoid false positives in pages that combine prose with examples, components, and structured metadata.

auth4genai/how-tos/analyze-strava-activities.mdx

@@ -4,7 +4,7 @@ description: Learn how to use Auth0 for AI Agents SDKs to analyze Strava activit
 mode: "wide"
 ---
 
-Use the [Vercel AI SDK](https://sdk.vercel./introduction), OpenAI GPT-4, and the Auth0 Next.js SDK to analyze user fitness activity from Strava.
+Use the [Vercel AI SDK](https://ai-sdk.dev/docs/introduction), OpenAI GPT-4, and the Auth0 Next.js SDK to analyze user fitness activity from Strava.
 
 <Card title="Prerequisites">
 Before using this example, make sure you:

auth4genai/how-tos/create-spotify-playlist.mdx

@@ -4,7 +4,7 @@ description: Learn how to use Auth0 for AI Agents SDKs to create a Spotify playl
 mode: "wide"
 ---
 
-Use the [Vercel AI SDK](https://sdk.vercel./introduction), OpenAI GPT-4, and the Auth0 Next.js SDK to create personalized Spotify playlists based on user input like mood, vibe, or activity.
+Use the [Vercel AI SDK](https://ai-sdk.dev/docs/introduction), OpenAI GPT-4, and the Auth0 Next.js SDK to create personalized Spotify playlists based on user input like mood, vibe, or activity.
 
 <Card title="Prerequisites">
 Before using this example, make sure you:

auth4genai/snippets/get-started/vercel-ai-next-js/user-authentication.mdx

@@ -67,7 +67,7 @@ Sign up for your application to create a new user account. You will then see a w
   >
 ### Install Auth0 Next.js SDK
 
-In the root directory of your project, install the [Auth0 Next.js SDK](http://next.js/):
+In the root directory of your project, install the [Auth0 Next.js SDK](https://github.com/auth0/nextjs-auth0):
 
 ```bash wrap lines
 npm i @auth0/nextjs-auth0@4