diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 41712e4a9..e22833c03 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -8,11 +8,18 @@ on:
       - 'wiki/**'
       - 'mkdocs.yml'
       - '.github/workflows/docs.yml'
+  # Push only deploys GitHub Pages, and `mkdocs.yml` sets `docs_dir: wiki` — so the
+  # sources that matter here are wiki/ and mkdocs.yml, NOT docs/ (that is the
+  # Next.js site, which Vercel deploys through its own Git integration).
+  #
+  # wiki/** was missing, so a merge touching only wiki/ never triggered this
+  # workflow and the published Pages site silently went stale. docs/** was present
+  # but mkdocs never reads it, so it only bought a no-op Pages rebuild.
   push:
     branches:
       - main
     paths:
-      - 'docs/**'
+      - 'wiki/**'
       - 'mkdocs.yml'
       - '.github/workflows/docs.yml'
   workflow_dispatch:
@@ -99,32 +106,13 @@ jobs:
       - name: Build and deploy
         run: mkdocs gh-deploy --force
 
-  deploy-vercel:
-    name: Deploy Vercel Docs
-    if: >-
-      github.event_name != 'pull_request'
-      && github.ref == 'refs/heads/main'
-      && github.repository_owner == 'headroomlabs-ai'
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: '20'
-          cache: npm
-          cache-dependency-path: docs/package-lock.json
-
-      - name: Install dependencies
-        run: npm ci
-        working-directory: docs
-
-      - name: Deploy to Vercel
-        run: npx vercel deploy --prod --token=${{ secrets.VERCEL_TOKEN }}
-        working-directory: docs
-        env:
-          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
-          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+# The Next.js docs site is deployed by Vercel's own Git integration, so there is no
+# deploy job for it here. A `deploy-vercel` job used to run `npx vercel deploy
+# --prod` on every push to main, but VERCEL_TOKEN / VERCEL_ORG_ID /
+# VERCEL_PROJECT_ID are not configured as secrets (repo or org), so it invoked the
+# CLI with an empty `--token=` and exited 1. It therefore never deployed anything:
+# 30 failed runs on main between 2026-07-14 and 2026-08-04. `deploy-github-pages`
+# succeeded in those same runs — only this job failed — so the red was pure noise.
+#
+# `Validate Next.js build` above still guards docs/** on pull requests, so a broken
+# MDX change is caught before merge.