diff --git a/docs/LINKEDIN_OAUTH_SETUP_GUIDE.md b/docs/LINKEDIN_OAUTH_SETUP_GUIDE.md
new file mode 100644
index 0000000..2224879
--- /dev/null
+++ b/docs/LINKEDIN_OAUTH_SETUP_GUIDE.md
@@ -0,0 +1,54 @@
+# Setting up LinkedIn OAuth
+
+Covers the "Authenticate LinkedIn" button in Agent → MCP, and the exact
+error it produces when LinkedIn's app settings are out of sync with what
+MaskanX actually sends.
+
+## Two different LinkedIn login mechanisms exist in this codebase
+
+Don't mix them up — they use different callback URLs.
+
+| | Terminal script (legacy) | "Authenticate LinkedIn" button (current) |
+|---|---|---|
+| How it's run | `scripts/start-linkedin-oauth.ps1`, by hand | Click the button in Agent → MCP |
+| Callback URL | `http://localhost:44002/auth/linkedin/callback` | `http://127.0.0.1:8088/api/mcp/linkedin/oauth/callback` |
+| Who handles the callback | The `linkedin-mcp-server` npm package's own helper process | MaskanX's own backend, directly |
+
+**If you're using the button in the UI (the normal path), you need the
+second URL registered — not the first.**
+
+## One-time setup
+
+1. Add `LINKEDIN_CLIENT_ID` and `LINKEDIN_CLIENT_SECRET` in the LinkedIn
+   MCP client settings (Agent → MCP → LinkedIn).
+2. Open the **LinkedIn Developer Portal**
+   ([linkedin.com/developers/apps](https://www.linkedin.com/developers/apps)),
+   select the app matching that Client ID → **Auth** tab.
+3. Under **Authorized redirect URLs**, add:
+   ```
+   http://127.0.0.1:8088/api/mcp/linkedin/oauth/callback
+   ```
+   Adding this doesn't remove any URL already registered — LinkedIn allows
+   more than one.
+4. Click **Update**.
+5. Back in MaskanX, the MCP settings page shows the exact callback URL it
+   will use, labeled *"Add this callback URL in LinkedIn Developer
+   Portal."* If you ever run MaskanX on a different host or port than
+   `127.0.0.1:8088`, that label will show a different value — register
+   *that* one, not the one written above; the computed value always wins.
+6. Click **Authenticate LinkedIn**.
+
+## This is shared, not per-machine
+
+Unlike Google Cloud credentials, a LinkedIn app's registered redirect
+URLs apply everywhere that Client ID is used. Fix it once here and every
+computer using the same LinkedIn app is fixed — you don't need to repeat
+this per laptop, only per LinkedIn app.
+
+## Troubleshooting
+
+| You see | What it means | Fix |
+|---|---|---|
+| `Bummer, something went wrong. The redirect_uri does not match the registered value` | LinkedIn's authorized redirect URL list doesn't contain the exact URL MaskanX just sent. Check the MCP settings page for the exact value in use — it depends on the host/port MaskanX is running on. | Add that exact URL in the LinkedIn Developer Portal, Auth tab. |
+| `LinkedIn credentials are missing` | `LINKEDIN_CLIENT_ID` / `LINKEDIN_CLIENT_SECRET` aren't set for this MCP client. | Add them in Agent → MCP → LinkedIn. |
+| `Invalid OAuth state` | The login was started in one browser session/tab and completed in another, or it timed out. | Click Authenticate LinkedIn again and complete it in one go. |