diff --git a/docs-site/docs/features/post-application-tracking.md b/docs-site/docs/features/post-application-tracking.md
index 1a6bd16..a4a67d9 100644
--- a/docs-site/docs/features/post-application-tracking.md
+++ b/docs-site/docs/features/post-application-tracking.md
@@ -52,6 +52,10 @@ GMAIL_OAUTH_REDIRECT_URI=https://your-domain.com/oauth/gmail/callback
 
 Then connect in UI via **Tracking Inbox → Connect Gmail**.
 
+Detailed setup guide:
+
+- [Gmail OAuth Setup](/docs/next/getting-started/gmail-oauth-setup)
+
 ## Using the inbox
 
 - Review pending items in Tracking Inbox
@@ -67,6 +71,7 @@ Confidence interpretation:
 ## Privacy and security
 
 - Scope requested: `gmail.readonly`
+- Full scope: `https://www.googleapis.com/auth/gmail.readonly`
 - Minimal metadata sent for matching
 - Email data stays local in your instance
 
@@ -78,8 +83,8 @@ Confidence interpretation:
 | POST   | `/api/post-application/inbox/:id/approve` | Approve message       |
 | POST   | `/api/post-application/inbox/:id/deny`    | Ignore message        |
 | GET    | `/api/post-application/runs`              | List sync runs        |
-| POST   | `/api/post-application/gmail/connect`     | Start OAuth flow      |
-| GET    | `/api/post-application/gmail/callback`    | OAuth callback        |
+| GET    | `/api/post-application/providers/gmail/oauth/start` | Start OAuth flow |
+| POST   | `/api/post-application/providers/gmail/oauth/exchange` | Exchange OAuth code |
 
 ## Common issues
 
diff --git a/docs-site/docs/getting-started/gmail-oauth-setup.md b/docs-site/docs/getting-started/gmail-oauth-setup.md
new file mode 100644
index 0000000..93ec413
--- /dev/null
+++ b/docs-site/docs/getting-started/gmail-oauth-setup.md
@@ -0,0 +1,96 @@
+---
+id: gmail-oauth-setup
+title: Gmail OAuth Setup
+description: Step-by-step Google Cloud setup for JobOps Gmail tracking, with exact scopes and callback configuration.
+sidebar_position: 2
+---
+
+## What it is
+
+This guide configures Google OAuth so JobOps can read recruitment emails from Gmail for the Tracking Inbox.
+
+## Why it exists
+
+Gmail OAuth setup is easy to misconfigure (wrong redirect URI, missing refresh token, or unnecessary scopes). This page documents the exact defaults JobOps expects.
+
+## How to use it
+
+### 1) Create Google Cloud credentials
+
+In [Google Cloud Console](https://console.cloud.google.com/):
+
+1. Create (or select) a project.
+2. Open **APIs & Services → Library** and enable **Gmail API**.
+3. Open **APIs & Services → OAuth consent screen** and configure your app.
+4. Open **APIs & Services → Credentials** and create **OAuth client ID**.
+5. Choose **Web application**.
+6. Add at least one authorized redirect URI:
+  - Local: `http://localhost:3005/oauth/gmail/callback`
+  - Production: `https://your-domain.com/oauth/gmail/callback`
+
+Notes:
+
+- If you set `GMAIL_OAUTH_REDIRECT_URI`, it must exactly match a redirect URI in Google Cloud.
+- JobOps does not require JavaScript origins for this flow.
+
+### 2) Set environment variables
+
+Configure:
+
+```bash
+GMAIL_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GMAIL_OAUTH_CLIENT_SECRET=your-client-secret
+# Optional (recommended in production)
+GMAIL_OAUTH_REDIRECT_URI=https://your-domain.com/oauth/gmail/callback
+```
+
+Then restart the container/app.
+
+### 3) Connect Gmail in JobOps
+
+1. Open **Tracking Inbox**.
+2. Click **Connect Gmail**.
+3. Complete Google consent.
+
+JobOps starts OAuth with:
+
+- Scope: `https://www.googleapis.com/auth/gmail.readonly`
+- `access_type=offline` (requests refresh token)
+- `prompt=consent` (forces consent screen so refresh token is returned reliably)
+
+### 4) Scope reference (required vs not required)
+
+Required by JobOps:
+
+- `https://www.googleapis.com/auth/gmail.readonly`
+
+Not required for JobOps Gmail ingestion:
+
+- `https://www.googleapis.com/auth/gmail.modify`
+- `openid`
+- `https://www.googleapis.com/auth/userinfo.email`
+- `https://www.googleapis.com/auth/userinfo.profile`
+
+## Common problems
+
+### Redirect URI mismatch
+
+- Symptom: Google returns `redirect_uri_mismatch`.
+- Fix: ensure the exact callback URL in `GMAIL_OAUTH_REDIRECT_URI` is also present in the OAuth client redirect URIs.
+
+### No refresh token returned
+
+- Symptom: connect fails after OAuth exchange.
+- Fix: remove app access in your Google account, then reconnect so consent is re-granted.
+
+### Gmail connects but no inbox results
+
+- Check that your account actually has recruitment/application emails.
+- Trigger a sync and increase `searchDays` if needed.
+
+## Related pages
+
+- [Self-Hosting (Docker Compose)](/docs/next/getting-started/self-hosting)
+- [Post-Application Tracking](/docs/next/features/post-application-tracking)
+- [Post-Application Workflow](/docs/next/workflows/post-application-workflow)
+- [Common Problems](/docs/next/troubleshooting/common-problems)
diff --git a/docs-site/docs/getting-started/self-hosting.md b/docs-site/docs/getting-started/self-hosting.md
index 1143c61..7884ab5 100644
--- a/docs-site/docs/getting-started/self-hosting.md
+++ b/docs-site/docs/getting-started/self-hosting.md
@@ -67,6 +67,10 @@ In Google Cloud:
 - Restart container
 - Open Tracking Inbox and click **Connect Gmail**
 
+For a full step-by-step setup, exact scope requirements, and troubleshooting, see:
+
+- [Gmail OAuth Setup](/docs/next/getting-started/gmail-oauth-setup)
+
 ## Email-to-job matching overview
 
 ```mermaid
diff --git a/docs-site/docs/workflows/post-application-workflow.md b/docs-site/docs/workflows/post-application-workflow.md
index c4d8e8f..c6e87bc 100644
--- a/docs-site/docs/workflows/post-application-workflow.md
+++ b/docs-site/docs/workflows/post-application-workflow.md
@@ -62,6 +62,10 @@ GMAIL_OAUTH_CLIENT_SECRET=...
 GMAIL_OAUTH_REDIRECT_URI=https://your-domain.com/oauth/gmail/callback
 ```
 
+For exact Google Cloud steps and scope requirements, see:
+
+- [Gmail OAuth Setup](/docs/next/getting-started/gmail-oauth-setup)
+
 Then in app:
 
 1. Open Tracking Inbox / provider controls.
diff --git a/docs-site/sidebars.ts b/docs-site/sidebars.ts
index 25f615c..d6e36a4 100644
--- a/docs-site/sidebars.ts
+++ b/docs-site/sidebars.ts
@@ -6,7 +6,10 @@ const sidebars: SidebarsConfig = {
     {
       type: "category",
       label: "Getting Started",
-      items: ["getting-started/self-hosting"],
+      items: [
+        "getting-started/self-hosting",
+        "getting-started/gmail-oauth-setup",
+      ],
     },
     {
       type: "category",
@@ -51,6 +54,7 @@ const sidebars: SidebarsConfig = {
       label: "Self-Hosting & Ops",
       items: [
         "getting-started/self-hosting",
+        "getting-started/gmail-oauth-setup",
         "getting-started/database-backups",
         "troubleshooting/common-problems",
       ],
diff --git a/orchestrator/README.md b/orchestrator/README.md
index 6ef8f3e..4ad818b 100644
--- a/orchestrator/README.md
+++ b/orchestrator/README.md
@@ -86,8 +86,8 @@ orchestrator/
 | POST | `/api/post-application/inbox/:id/approve` | Approve and link to job |
 | POST | `/api/post-application/inbox/:id/deny` | Ignore message |
 | GET | `/api/post-application/runs` | List sync run history |
-| POST | `/api/post-application/gmail/connect` | Initiate Gmail OAuth flow |
-| GET | `/api/post-application/gmail/callback` | Gmail OAuth callback |
+| GET | `/api/post-application/providers/gmail/oauth/start` | Initiate Gmail OAuth flow |
+| POST | `/api/post-application/providers/gmail/oauth/exchange` | Exchange OAuth code |
 
 ## Daily Flow