diff --git a/.changeset/github-app-installation-setup.md b/.changeset/github-app-installation-setup.md
new file mode 100644
index 0000000000..4866bfd473
--- /dev/null
+++ b/.changeset/github-app-installation-setup.md
@@ -0,0 +1,6 @@
+---
+"@executor-js/sdk": patch
+"@executor-js/api": patch
+---
+
+Guide first-party GitHub connections through app installation and repository selection before user authorization. Keep the original authorization URL in an expiring, owner-scoped session so web, MCP, and reconnect flows share the same setup step.
diff --git a/apps/cloud/src/app-paths.test.ts b/apps/cloud/src/app-paths.test.ts
index dd9ff1af3c..5dd832e45c 100644
--- a/apps/cloud/src/app-paths.test.ts
+++ b/apps/cloud/src/app-paths.test.ts
@@ -78,6 +78,10 @@ describe("app-plane dispatch", () => {
     expect(servedByAppPlane("/api/oauth/callback", "POST")).toBe(false);
   });
 
+  it("leaves OAuth setup to Start for sign-in and organization selection", () => {
+    expect(servedByAppPlane("/api/oauth/setup", "GET")).toBe(false);
+  });
+
   const appPlane = [
     "/api/connections",
     "/api/tools",
diff --git a/apps/cloud/src/app-paths.ts b/apps/cloud/src/app-paths.ts
index 48e70a8c3a..5dcf83acdc 100644
--- a/apps/cloud/src/app-paths.ts
+++ b/apps/cloud/src/app-paths.ts
@@ -30,7 +30,7 @@ export const isAppOwnedPath = (pathname: string) =>
 //
 //   POST /api/sentry-tunnel  - `sentryTunnelMiddleware` forwards the envelope
 //                              to Sentry; the app has no such route.
-//   /api/oauth/callback      - `oauthCallbackSignInMiddleware` redirects a
+//   /api/oauth/{callback,setup} - `oauthBrowserSignInMiddleware` redirects a
 //                              signed-out visitor to /login, and start.ts
 //                              rewrites the org-scoped `state` before handing
 //                              off. Routing it early would drop both.
@@ -41,7 +41,10 @@ export const isAppOwnedPath = (pathname: string) =>
 // ---------------------------------------------------------------------------
 
 export const isStartOwnedApiPath = (pathname: string, method: string): boolean =>
-  (pathname === "/api/sentry-tunnel" && method === "POST") || pathname === "/api/oauth/callback";
+  (pathname === "/api/sentry-tunnel" && method === "POST") || isOAuthBrowserPath(pathname);
+
+export const isOAuthBrowserPath = (pathname: string): boolean =>
+  pathname === "/api/oauth/callback" || pathname === "/api/oauth/setup";
 
 export const servedByAppPlane = (pathname: string, method: string): boolean =>
   isApiPath(pathname) && !isStartOwnedApiPath(pathname, method);
diff --git a/apps/cloud/src/engine/first-party-oauth-clients.test.ts b/apps/cloud/src/engine/first-party-oauth-clients.test.ts
index 1ca3962d6b..967d0ecd28 100644
--- a/apps/cloud/src/engine/first-party-oauth-clients.test.ts
+++ b/apps/cloud/src/engine/first-party-oauth-clients.test.ts
@@ -83,6 +83,10 @@ describe("cloud first-party OAuth clients", () => {
         optional_scope: "content crm.objects.custom.read crm.schemas.custom.read",
       },
     });
+    expect(byName.get("github")).toMatchObject({
+      authorizationScopes: [],
+      authorizationSetup: { actionUrl: "https://github.com/apps/executor-sh/installations/new" },
+    });
     expect(byName.get("linear")).toMatchObject({ authorizationScopeSeparator: "," });
     expect(byName.get("microsoft")).toMatchObject({
       additionalAuthorizationScopes: ["offline_access"],
@@ -179,3 +183,13 @@ describe("cloud first-party Google app", () => {
     }
   });
 });
+
+it("uses the installation page for the deployment's GitHub App", () => {
+  const github = firstPartyOAuthClientsFor({
+    ...completeEnv,
+    FIRST_PARTY_GITHUB_INSTALLATION_URL: "https://github.com/apps/custom-app/installations/new",
+  }).find((client) => client.name === "github");
+  expect(github?.authorizationSetup?.actionUrl).toBe(
+    "https://github.com/apps/custom-app/installations/new",
+  );
+});
diff --git a/apps/cloud/src/engine/first-party-oauth-clients.ts b/apps/cloud/src/engine/first-party-oauth-clients.ts
index 12b0748627..0b8ca1ff56 100644
--- a/apps/cloud/src/engine/first-party-oauth-clients.ts
+++ b/apps/cloud/src/engine/first-party-oauth-clients.ts
@@ -30,6 +30,7 @@ export interface FirstPartyOAuthClientEnv {
   readonly FIRST_PARTY_GITHUB_CLIENT_SECRET?: string;
   readonly FIRST_PARTY_GITHUB_AUTHORIZE_URL?: string;
   readonly FIRST_PARTY_GITHUB_TOKEN_URL?: string;
+  readonly FIRST_PARTY_GITHUB_INSTALLATION_URL?: string;
   readonly FIRST_PARTY_GITLAB_CLIENT_ID?: string;
   readonly FIRST_PARTY_GITLAB_CLIENT_SECRET?: string;
   readonly FIRST_PARTY_GOOGLE_CLIENT_ID?: string;
@@ -269,6 +270,15 @@ export const firstPartyOAuthClientsFor = (
     authorizationUrl:
       env.FIRST_PARTY_GITHUB_AUTHORIZE_URL ?? "https://github.com/login/oauth/authorize",
     tokenUrl: env.FIRST_PARTY_GITHUB_TOKEN_URL ?? "https://github.com/login/oauth/access_token",
+    authorizationSetup: {
+      title: "Connect GitHub",
+      description:
+        "Install the GitHub App on your account or organization and choose the repositories Executor can access. Authorizing your account alone does not grant private repository access. Organization access may require an owner's approval.",
+      actionLabel: "Install or configure GitHub App",
+      actionUrl:
+        env.FIRST_PARTY_GITHUB_INSTALLATION_URL ??
+        "https://github.com/apps/executor-sh/installations/new",
+    },
     integrations: [IntegrationSlug.make("github_rest")],
     // GitHub App user access tokens do not use classic OAuth scopes; their
     // capabilities come from the app's registered permissions.
diff --git a/apps/cloud/src/env-augment.d.ts b/apps/cloud/src/env-augment.d.ts
index 715991f394..cd31a85008 100644
--- a/apps/cloud/src/env-augment.d.ts
+++ b/apps/cloud/src/env-augment.d.ts
@@ -89,6 +89,8 @@ declare global {
       // production (the real github.com endpoints are the defaults).
       FIRST_PARTY_GITHUB_AUTHORIZE_URL?: string;
       FIRST_PARTY_GITHUB_TOKEN_URL?: string;
+      // Override when deploying with a different GitHub App registration.
+      FIRST_PARTY_GITHUB_INSTALLATION_URL?: string;
       FIRST_PARTY_GITLAB_CLIENT_ID?: string;
       FIRST_PARTY_GITLAB_CLIENT_SECRET?: string;
       FIRST_PARTY_GOOGLE_CLIENT_ID?: string;
diff --git a/apps/cloud/src/start.ts b/apps/cloud/src/start.ts
index aaadc1a521..70855273f9 100644
--- a/apps/cloud/src/start.ts
+++ b/apps/cloud/src/start.ts
@@ -1,7 +1,7 @@
 import { createMiddleware, createStart } from "@tanstack/react-start";
 import { decodeOAuthCallbackState } from "@executor-js/sdk/shared";
 
-import { isAppOwnedPath } from "./app-paths";
+import { isAppOwnedPath, isOAuthBrowserPath } from "./app-paths";
 import { authGateMiddleware } from "./auth/doc-gate";
 import { parseCookie } from "./auth/cookies";
 import { ORG_SELECTOR_HEADER } from "./auth/organization";
@@ -48,9 +48,8 @@ const getApp = async (): Promise<NonNullable<typeof app>> =>
   (app ??= (await import("./app")).cloudApiHandler());
 
 const SESSION_COOKIE = "wos-session";
-const OAUTH_CALLBACK_PATH = "/api/oauth/callback";
 
-const oauthCallbackOrgScopedRequest = (request: Request): Request => {
+const oauthBrowserOrgScopedRequest = (request: Request): Request => {
   const url = new URL(request.url);
   const callbackState = decodeOAuthCallbackState(url.searchParams.get("state"));
   if (callbackState === null) return request;
@@ -61,12 +60,9 @@ const oauthCallbackOrgScopedRequest = (request: Request): Request => {
   return new Request(rewritten, { headers });
 };
 
-const oauthCallbackSignInMiddleware = createMiddleware({ type: "request" }).server(
+const oauthBrowserSignInMiddleware = createMiddleware({ type: "request" }).server(
   ({ pathname, request, next }) => {
-    if (
-      pathname !== OAUTH_CALLBACK_PATH ||
-      (request.method !== "GET" && request.method !== "HEAD")
-    ) {
+    if (!isOAuthBrowserPath(pathname) || (request.method !== "GET" && request.method !== "HEAD")) {
       return next();
     }
     const sealed = parseCookie(request.headers.get("cookie"), SESSION_COOKIE);
@@ -89,8 +85,9 @@ const oauthCallbackSignInMiddleware = createMiddleware({ type: "request" }).serv
 const appRequestMiddleware = createMiddleware({ type: "request" }).server(
   async ({ pathname, request, next }) => {
     if (isAppOwnedPath(pathname)) {
-      const scopedRequest =
-        pathname === OAUTH_CALLBACK_PATH ? oauthCallbackOrgScopedRequest(request) : request;
+      const scopedRequest = isOAuthBrowserPath(pathname)
+        ? oauthBrowserOrgScopedRequest(request)
+        : request;
       return (await getApp()).handler(prepareMcpOrgScope(scopedRequest));
     }
     return next();
@@ -113,7 +110,7 @@ export const startInstance = createStart(() => ({
     docsProxyMiddleware,
     sentryTunnelMiddleware,
     posthogProxyMiddleware,
-    oauthCallbackSignInMiddleware,
+    oauthBrowserSignInMiddleware,
     appRequestMiddleware,
     authGateMiddleware,
   ],
diff --git a/e2e/scenarios/first-party-oauth.test.ts b/e2e/scenarios/first-party-oauth.test.ts
index bee0c78daa..967768c692 100644
--- a/e2e/scenarios/first-party-oauth.test.ts
+++ b/e2e/scenarios/first-party-oauth.test.ts
@@ -4,11 +4,9 @@
 //
 //   1. Listing: `oauth.listClients` surfaces `first-party:github` with a
 //      `first_party` origin and its public client id — no create call ever ran.
-//   2. Flow: `oauth.start` through the first-party slug redirects to the
-//      provider's authorize endpoint carrying the env-configured client id and
-//      this platform's `/api/oauth/callback` — proof the config-resolved
-//      identity (not a stored row) drives the flow. The redirect is asserted,
-//      never followed: github.com is not visited.
+//   2. Flow: the returned URL opens installation guidance, then preserves the
+//      original provider authorization URL, PKCE and organization routing.
+//      GitHub's links are checked without contacting the live provider.
 //   3. Guardrails: the reserved `first-party:` namespace is rejected by
 //      createClient, so no org can shadow the host's app with its own row.
 import { randomBytes } from "node:crypto";
@@ -93,7 +91,7 @@ const googleShapedIntegrationSpec = (scopes: readonly string[]) => ({
 });
 
 scenario(
-  "First-party OAuth · the host-declared GitHub app is listed and drives the authorize redirect",
+  "First-party OAuth · GitHub setup includes installation before authorization",
   {},
   Effect.scoped(
     Effect.gen(function* () {
@@ -103,6 +101,7 @@ scenario(
       // their own OAuth apps through its existing registration flow.
       if (target.name !== "cloud") return;
       const { client: makeApiClient } = yield* Api;
+      const browser = yield* Browser;
       const identity = yield* target.newIdentity();
       const client = yield* makeApiClient(api, identity);
 
@@ -116,6 +115,9 @@ scenario(
       // 2. A start through the first-party slug builds GitHub's authorize URL
       //    from the config identity and this platform's served callback.
       const integration = IntegrationSlug.make(unique("fpgh"));
+      yield* Effect.addFinalizer(() =>
+        client.openapi.removeSpec({ params: { slug: integration } }).pipe(Effect.ignore),
+      );
       yield* client.openapi.addSpec({
         payload: { ...githubShapedIntegrationSpec, slug: integration },
       });
@@ -129,16 +131,67 @@ scenario(
           template: AuthTemplateSlug.make("oauth"),
         },
       });
-      expect(started.status, "oauth.start redirects to the provider").toBe("redirect");
-      const authorizationUrl = started.status === "redirect" ? started.authorizationUrl : "";
-      const authorize = new URL(authorizationUrl);
-      expect(authorize.origin + authorize.pathname).toBe(
-        "https://github.com/login/oauth/authorize",
+      expect(started.status, "oauth.start opens setup").toBe("redirect");
+      if (started.status !== "redirect") return yield* Effect.die("expected redirect");
+      yield* Effect.addFinalizer(() =>
+        client.oauth.cancel({ payload: { state: started.state } }).pipe(Effect.ignore),
       );
-      expect(authorize.searchParams.get("client_id")).toBe("e2e-first-party-github");
-      expect(authorize.searchParams.get("redirect_uri")).toBe(
-        new URL("/api/oauth/callback", target.baseUrl).toString(),
+      const setupUrl = new URL(started.authorizationUrl);
+      expect(setupUrl.origin + setupUrl.pathname).toBe(
+        new URL("/api/oauth/setup", target.baseUrl).toString(),
       );
+      // A URL supplied by a caller must never replace the saved continuation.
+      setupUrl.searchParams.set("authorization_url", "https://example.invalid/phishing");
+      yield* browser.session(identity, async ({ page, step }) => {
+        await step("Open GitHub setup and find repository installation", async () => {
+          const response = await page.goto(setupUrl.toString());
+          expect(response?.status()).toBe(200);
+          expect(response?.headers()["cache-control"]).toBe("no-store");
+          await page.getByRole("heading", { name: "Connect GitHub", exact: true }).waitFor();
+          const install = page.getByRole("link", { name: "Install or configure GitHub App" });
+          expect(await install.getAttribute("href")).toBe(
+            "https://github.com/apps/executor-sh/installations/new",
+          );
+          expect(await install.getAttribute("target")).toBe("_blank");
+          const authorize = new URL(
+            (await page
+              .getByRole("link", { name: "Continue to authorization" })
+              .getAttribute("href"))!,
+          );
+          expect(authorize.origin + authorize.pathname).toBe(
+            "https://github.com/login/oauth/authorize",
+          );
+          expect(authorize.searchParams.get("client_id")).toBe("e2e-first-party-github");
+          expect(authorize.searchParams.get("redirect_uri")).toBe(
+            new URL("/api/oauth/callback", target.baseUrl).toString(),
+          );
+          expect(authorize.searchParams.get("state")).toBe(setupUrl.searchParams.get("state"));
+          expect(authorize.searchParams.get("code_challenge_method")).toBe("S256");
+          expect(authorize.searchParams.get("code_challenge")).toMatch(/^[A-Za-z0-9_-]{43}$/);
+          expect(authorize.searchParams.has("scope")).toBe(false);
+        });
+        await step("Read setup in light mode", async () => {
+          await page.emulateMedia({ colorScheme: "light" });
+        });
+        await step("Choose access on a narrow screen", async () => {
+          await page.setViewportSize({ width: 390, height: 844 });
+          expect(
+            await page.locator("body").evaluate((body) => body.scrollWidth <= window.innerWidth),
+          ).toBe(true);
+        });
+        await step("Read setup in dark mode on a narrow screen", async () => {
+          await page.emulateMedia({ colorScheme: "dark" });
+        });
+        await step("Cancel setup and reopen the expired link", async () => {
+          await Effect.runPromise(client.oauth.cancel({ payload: { state: started.state } }));
+          const response = await page.goto(setupUrl.toString());
+          expect(response?.status()).toBe(410);
+          await page.getByRole("heading", { name: "Connection setup unavailable" }).waitFor();
+          expect(await page.getByRole("link", { name: "Continue to authorization" }).count()).toBe(
+            0,
+          );
+        });
+      });
 
       // 3. The reserved namespace cannot be shadowed by a stored row. The
       //    server rejects with a StorageError, which the HTTP edge scrubs to an
diff --git a/packages/core/api/src/handlers/oauth.ts b/packages/core/api/src/handlers/oauth.ts
index eb4b1f939b..805c7c1a68 100644
--- a/packages/core/api/src/handlers/oauth.ts
+++ b/packages/core/api/src/handlers/oauth.ts
@@ -11,6 +11,7 @@ import { HttpServerResponse } from "effect/unstable/http";
 import { Effect, Option, Schema } from "effect";
 
 import { runOAuthCallback, type PopupErrorMessage } from "../oauth-popup";
+import { oauthSetupDocument, oauthSetupUnavailableDocument } from "../oauth-setup";
 import {
   OAUTH_POPUP_MESSAGE_TYPE,
   OAuthCompleteError,
@@ -20,6 +21,7 @@ import {
   OAuthState,
   type Connection,
   type ConnectResult,
+  decodeOAuthCallbackState,
 } from "@executor-js/sdk";
 
 import { ExecutorApi } from "../api";
@@ -173,6 +175,29 @@ export const OAuthHandlers = HttpApiBuilder.group(ExecutorApi, "oauth", (handler
         }),
       ),
     )
+    .handle("setup", ({ query }) =>
+      capture(
+        Effect.gen(function* () {
+          const executor = yield* ExecutorService;
+          const state = decodeOAuthCallbackState(query.state)?.state ?? query.state;
+          const setup = yield* executor.oauth.getSetup(OAuthState.make(state));
+          return HttpServerResponse.text(oauthSetupDocument(setup), {
+            contentType: "text/html; charset=utf-8",
+            headers: { "cache-control": "no-store", "referrer-policy": "no-referrer" },
+          });
+        }).pipe(
+          Effect.catchTag("OAuthSessionNotFoundError", () =>
+            Effect.succeed(
+              HttpServerResponse.text(oauthSetupUnavailableDocument(), {
+                contentType: "text/html; charset=utf-8",
+                status: 410,
+                headers: { "cache-control": "no-store" },
+              }),
+            ),
+          ),
+        ),
+      ),
+    )
     .handle("complete", ({ payload }) =>
       capture(
         Effect.gen(function* () {
diff --git a/packages/core/api/src/html-escape.ts b/packages/core/api/src/html-escape.ts
new file mode 100644
index 0000000000..9c2dfed0b5
--- /dev/null
+++ b/packages/core/api/src/html-escape.ts
@@ -0,0 +1,8 @@
+/** Escape text and quoted attribute values in server-rendered HTML. */
+export const escapeHtml = (value: string): string =>
+  value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
diff --git a/packages/core/api/src/oauth-popup.ts b/packages/core/api/src/oauth-popup.ts
index 9bfcdfda2d..b3cd241161 100644
--- a/packages/core/api/src/oauth-popup.ts
+++ b/packages/core/api/src/oauth-popup.ts
@@ -12,6 +12,8 @@
 
 import { Cause, Effect } from "effect";
 
+import { escapeHtml } from "./html-escape";
+
 import {
   decodeOAuthCallbackState,
   OAUTH_POPUP_MESSAGE_TYPE,
@@ -48,14 +50,6 @@ export const setOAuthCompletionListener = (listener: OAuthCompletionListener | n
 // HTML generation
 // ---------------------------------------------------------------------------
 
-const escapeHtml = (value: string): string =>
-  value
-    .replaceAll("&", "&amp;")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;")
-    .replaceAll('"', "&quot;")
-    .replaceAll("'", "&#39;");
-
 /**
  * Serialize for embedding inside a `<script>` tag. Escapes the characters
  * that could prematurely terminate the script or mislead an HTML parser
diff --git a/packages/core/api/src/oauth-setup.test.ts b/packages/core/api/src/oauth-setup.test.ts
new file mode 100644
index 0000000000..004691325d
--- /dev/null
+++ b/packages/core/api/src/oauth-setup.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from "@effect/vitest";
+
+import { oauthSetupDocument } from "./oauth-setup";
+
+const setup = {
+  title: "Connect GitHub",
+  description: "Choose repositories.",
+  actionLabel: "Install GitHub App",
+  actionUrl: "https://github.com/apps/example/installations/new",
+};
+
+describe("OAuth setup document", () => {
+  it("escapes host text and query parameters without exposing markup or a referrer", () => {
+    const html = oauthSetupDocument({
+      setup: { ...setup, title: '<script>alert("title")</script>', description: "<img src=x>" },
+      authorizationUrl: "https://github.com/login/oauth/authorize?state=a&client_id=b",
+    });
+    expect(html).not.toContain("<script>");
+    expect(html).not.toContain("<img");
+    expect(html).toContain("&lt;script&gt;");
+    expect(html).toContain("?state=a&amp;client_id=b");
+    expect(html).toContain('name="referrer" content="no-referrer"');
+    expect(html).toMatch(/target="_blank"\s+rel="noopener noreferrer"/);
+  });
+
+  it("refuses executable or malformed link targets", () => {
+    for (const url of ["javascript:alert(1)", "data:text/html,hello", "not a URL"]) {
+      expect(
+        oauthSetupDocument({
+          setup: { ...setup, actionUrl: url },
+          authorizationUrl: "https://github.com/",
+        }),
+      ).toContain("Connection setup unavailable");
+      expect(oauthSetupDocument({ setup, authorizationUrl: url })).toContain(
+        "Connection setup unavailable",
+      );
+    }
+  });
+});
diff --git a/packages/core/api/src/oauth-setup.ts b/packages/core/api/src/oauth-setup.ts
new file mode 100644
index 0000000000..ce3ad612be
--- /dev/null
+++ b/packages/core/api/src/oauth-setup.ts
@@ -0,0 +1,190 @@
+import type { OAuthSetupResult } from "@executor-js/sdk";
+
+import { escapeHtml } from "./html-escape";
+
+const httpUrl = (value: string): string | null => {
+  const url = URL.parse(value);
+  return url?.protocol === "https:" || url?.protocol === "http:" ? url.href : null;
+};
+
+// Kept independent of the React app, like the OAuth callback document: this
+// page also opens from MCP links and hosts that only serve the HTTP API.
+const setupStyles = `
+  :root {
+    color-scheme: light dark;
+    font-family: system-ui, -apple-system, sans-serif;
+    background: #fafafa;
+    color: #18181b;
+  }
+
+  * {
+    box-sizing: border-box;
+  }
+
+  body {
+    margin: 0;
+    min-height: 100svh;
+    display: grid;
+    place-items: center;
+    padding: 24px;
+  }
+
+  main {
+    width: 100%;
+    max-width: 480px;
+  }
+
+  h1 {
+    font-size: 24px;
+    line-height: 1.25;
+    letter-spacing: -0.03em;
+    margin: 0 0 24px;
+    font-weight: 600;
+  }
+
+  h2 {
+    font-size: 16px;
+    line-height: 1.4;
+    margin: 0 0 8px;
+    font-weight: 600;
+  }
+
+  p {
+    font-size: 14px;
+    line-height: 1.6;
+    color: #52525b;
+    margin: 0 0 16px;
+  }
+
+  section + section {
+    border-top: 1px solid #e4e4e7;
+    margin-top: 24px;
+    padding-top: 24px;
+  }
+
+  a {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-height: 40px;
+    border: 1px solid #d4d4d8;
+    border-radius: 8px;
+    padding: 8px 14px;
+    font-size: 14px;
+    font-weight: 500;
+    text-decoration: none;
+    color: inherit;
+    text-align: center;
+  }
+
+  a:focus-visible {
+    outline: 2px solid #7c3aed;
+    outline-offset: 3px;
+  }
+
+  a:hover {
+    background: #f4f4f5;
+  }
+
+  a.primary {
+    background: #18181b;
+    border-color: #18181b;
+    color: #fafafa;
+  }
+
+  a.primary:hover {
+    background: #3f3f46;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      background: #09090b;
+      color: #fafafa;
+    }
+
+    p {
+      color: #a1a1aa;
+    }
+
+    section + section {
+      border-color: #27272a;
+    }
+
+    a {
+      border-color: #3f3f46;
+    }
+
+    a:hover {
+      background: #18181b;
+    }
+
+    a.primary {
+      background: #fafafa;
+      border-color: #fafafa;
+      color: #18181b;
+    }
+
+    a.primary:hover {
+      background: #e4e4e7;
+    }
+  }
+`;
+
+const renderDocument = (title: string, content: string): string => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="referrer" content="no-referrer" />
+    <title>${escapeHtml(title)}</title>
+    <style>${setupStyles}</style>
+  </head>
+  <body>
+    <main>${content}</main>
+  </body>
+</html>`;
+
+/** The provider URL comes from the owner-scoped session, never query-string
+ *  input. Installation stays in a separate tab so the PKCE flow can continue
+ *  in this window without relying on a provider's optional setup callback. */
+export const oauthSetupDocument = ({ setup, authorizationUrl }: OAuthSetupResult): string => {
+  const actionUrl = httpUrl(setup.actionUrl);
+  const continuation = httpUrl(authorizationUrl);
+  if (actionUrl === null || continuation === null) return oauthSetupUnavailableDocument();
+  return renderDocument(
+    setup.title,
+    `
+      <h1>${escapeHtml(setup.title)}</h1>
+      <section aria-labelledby="setup-heading">
+        <h2 id="setup-heading">1. Configure access</h2>
+        <p>${escapeHtml(setup.description)}</p>
+        <a
+          href="${escapeHtml(actionUrl)}"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          ${escapeHtml(setup.actionLabel)}
+        </a>
+      </section>
+      <section aria-labelledby="authorize-heading">
+        <h2 id="authorize-heading">2. Authorize your account</h2>
+        <p>Return here after setup, or continue if you've already configured access.</p>
+        <a class="primary" href="${escapeHtml(continuation)}" rel="noreferrer">
+          Continue to authorization
+        </a>
+      </section>
+    `,
+  );
+};
+
+export const oauthSetupUnavailableDocument = (): string =>
+  renderDocument(
+    "Connection setup unavailable",
+    `
+      <h1>Connection setup unavailable</h1>
+      <p>
+        This setup link has expired or is no longer available.
+        Close this window and start connecting again.
+      </p>
+    `,
+  );
diff --git a/packages/core/api/src/oauth/api.ts b/packages/core/api/src/oauth/api.ts
index 5d0eee3d41..4ce40e1d35 100644
--- a/packages/core/api/src/oauth/api.ts
+++ b/packages/core/api/src/oauth/api.ts
@@ -310,6 +310,13 @@ export const OAuthApi = HttpApiGroup.make("oauth")
       error: [InternalError, OAuthStart, OrgWriteDeniedError],
     }),
   )
+  .add(
+    HttpApiEndpoint.get("setup", "/oauth/setup", {
+      query: Schema.Struct({ state: Schema.String }),
+      success: HtmlResponse,
+      error: InternalError,
+    }),
+  )
   .add(
     HttpApiEndpoint.post("complete", "/oauth/complete", {
       payload: CompletePayload,
diff --git a/packages/core/sdk/src/index.ts b/packages/core/sdk/src/index.ts
index 627d3de1de..3b787c5f18 100644
--- a/packages/core/sdk/src/index.ts
+++ b/packages/core/sdk/src/index.ts
@@ -323,6 +323,8 @@ export {
   firstPartyOAuthClientSlug,
   isFirstPartyOAuthClientSlug,
   type FirstPartyOAuthClientConfig,
+  type OAuthAuthorizationSetup,
+  type OAuthSetupResult,
   type OAuthClientOrigin,
   type OAuthGrant,
   type OAuthAuthentication,
diff --git a/packages/core/sdk/src/oauth-client.ts b/packages/core/sdk/src/oauth-client.ts
index 8778205014..cde8f30207 100644
--- a/packages/core/sdk/src/oauth-client.ts
+++ b/packages/core/sdk/src/oauth-client.ts
@@ -185,6 +185,19 @@ export const isFirstPartyOAuthClientSlug = (slug: string): boolean =>
 export const firstPartyOAuthClientSlug = (name: string): OAuthClientSlug =>
   OAuthClientSlug.make(`${FIRST_PARTY_OAUTH_CLIENT_PREFIX}${name}`);
 
+/** Host-provided guidance for access that must be configured separately from OAuth consent. */
+export interface OAuthAuthorizationSetup {
+  readonly title: string;
+  readonly description: string;
+  readonly actionLabel: string;
+  readonly actionUrl: string;
+}
+
+export interface OAuthSetupResult {
+  readonly setup: OAuthAuthorizationSetup;
+  readonly authorizationUrl: string;
+}
+
 /** A first-party OAuth app the HOST declares at composition time — the
  *  deployment operator's own registered app for a provider. The secret comes
  *  from host env/config and stays in memory: it is never written to a
@@ -211,6 +224,10 @@ export interface FirstPartyOAuthClientConfig {
    *  GitHub Apps, whose capabilities are configured on the app and whose OAuth
    *  user-token flow does not use scopes. Omit for normal OAuth clients. */
   readonly authorizationScopes?: readonly string[];
+  /** Show host-provided installation guidance before authorization. The HTTP
+   *  host must serve the shared /oauth/setup route beside its callback. This
+   *  guides consent; opening the setup link does not prove installation. */
+  readonly authorizationSetup?: OAuthAuthorizationSetup;
   /** Scopes the host always adds to the integration-declared set. Use this for
    *  provider lifecycle scopes such as Atlassian and Microsoft
    *  `offline_access`; unlike `authorizationScopes`, this preserves the
@@ -540,6 +557,11 @@ export interface OAuthService {
   readonly start: (
     input: OAuthStartInput,
   ) => Effect.Effect<ConnectResult, OAuthStartError | OrgWriteDeniedError | StorageFailure>;
+  /** Resolve setup guidance and the original provider URL for a live,
+   *  owner-scoped session. Never accepts a caller-supplied continuation URL. */
+  readonly getSetup: (
+    state: OAuthState,
+  ) => Effect.Effect<OAuthSetupResult, OAuthSessionNotFoundError | StorageFailure>;
   readonly complete: (
     input: OAuthCompleteInput,
     options?: OAuthCompleteOptions,
diff --git a/packages/core/sdk/src/oauth-first-party.test.ts b/packages/core/sdk/src/oauth-first-party.test.ts
index 8a2be1cc3d..f49b2fec9d 100644
--- a/packages/core/sdk/src/oauth-first-party.test.ts
+++ b/packages/core/sdk/src/oauth-first-party.test.ts
@@ -7,6 +7,9 @@ import {
   ConnectionName,
   IntegrationSlug,
   OAuthClientSlug,
+  OAuthState,
+  Subject,
+  Tenant,
   ToolAddress,
   ToolName,
 } from "./ids";
@@ -15,6 +18,8 @@ import {
   type FirstPartyOAuthClientConfig,
   type OAuthStartError,
 } from "./oauth-client";
+import { createExecutor } from "./executor";
+import { decodeOAuthCallbackState } from "./oauth";
 import { definePlugin } from "./plugin";
 import { makeTestWorkspaceHarness, memoryCredentialsPlugin } from "./test-config";
 import { scopesFromAuthorizeUrl, serveOAuthTestServer } from "./testing/oauth-test-server";
@@ -550,3 +555,146 @@ describe("first-party oauth clients", () => {
     ),
   );
 });
+
+describe("first-party authorization setup", () => {
+  const setup = {
+    title: "Connect GitHub",
+    description: "Choose repositories before authorizing your account.",
+    actionLabel: "Install GitHub App",
+    actionUrl: "https://github.com/apps/example/installations/new",
+  };
+  const firstParty: FirstPartyOAuthClientConfig = {
+    name: "acme",
+    authorizationUrl: "https://github.com/login/oauth/authorize",
+    tokenUrl: "https://github.com/login/oauth/access_token",
+    clientId: "test-client",
+    clientSecret: "test-secret",
+    authorizationScopes: [],
+    authorizationSetup: setup,
+  };
+  const startInput = {
+    owner: "user" as const,
+    client: FIRST_PARTY,
+    clientOwner: "org" as const,
+    name: ConnectionName.make("setup"),
+    integration: INTEG,
+    template: TEMPLATE,
+  };
+
+  it.effect(
+    "keeps PKCE, organization routing and custom callbacks through setup and reconnect",
+    () =>
+      Effect.scoped(
+        Effect.gen(function* () {
+          const { executor } = yield* makeTestWorkspaceHarness({
+            plugins,
+            firstPartyOAuthClients: [firstParty],
+            redirectUri: "https://executor.example/api/oauth/callback",
+            oauthCallbackStateOrgSlug: "example-org",
+          });
+          yield* executor.acme.seed(["repo"]);
+          // The default (no newConnection flag) is also the reconnect path.
+          const started = yield* executor.oauth.start({
+            ...startInput,
+            redirectUri: "https://client.example/custom-callback",
+          });
+          expect(started.status).toBe("redirect");
+          if (started.status !== "redirect") return;
+          const setupUrl = new URL(started.authorizationUrl);
+          expect(setupUrl.origin + setupUrl.pathname).toBe(
+            "https://executor.example/api/oauth/setup",
+          );
+          expect(decodeOAuthCallbackState(setupUrl.searchParams.get("state"))).toEqual({
+            state: started.state,
+            orgSlug: "example-org",
+          });
+          const resolved = yield* executor.oauth.getSetup(started.state);
+          expect(resolved.setup).toEqual(setup);
+          const provider = new URL(resolved.authorizationUrl);
+          expect(provider.origin + provider.pathname).toBe(firstParty.authorizationUrl);
+          expect(provider.searchParams.get("client_id")).toBe("test-client");
+          expect(provider.searchParams.get("redirect_uri")).toBe(
+            "https://client.example/custom-callback",
+          );
+          expect(provider.searchParams.get("state")).toBe(setupUrl.searchParams.get("state"));
+          expect(provider.searchParams.get("code_challenge_method")).toBe("S256");
+          expect(provider.searchParams.get("code_challenge")).toMatch(/^[A-Za-z0-9_-]{43}$/);
+          expect(provider.searchParams.has("scope")).toBe(false);
+          expect(JSON.stringify(resolved)).not.toContain("test-secret");
+          // Reading guidance does not consume the authorization session.
+          expect(yield* executor.oauth.getSetup(started.state)).toEqual(resolved);
+          yield* executor.oauth.cancel(started.state);
+          expect(
+            Predicate.isTagged(
+              yield* executor.oauth.getSetup(started.state).pipe(Effect.flip),
+              "OAuthSessionNotFoundError",
+            ),
+          ).toBe(true);
+        }),
+      ),
+  );
+
+  it.effect(
+    "does not disclose another user's or tenant's continuation and rejects expired sessions",
+    () =>
+      Effect.scoped(
+        Effect.gen(function* () {
+          const { executor, config } = yield* makeTestWorkspaceHarness({
+            plugins,
+            firstPartyOAuthClients: [firstParty],
+          });
+          yield* executor.acme.seed();
+          const started = yield* executor.oauth.start(startInput);
+          if (started.status !== "redirect") return yield* Effect.die("expected redirect");
+          for (const scope of [
+            { subject: Subject.make("another-user") },
+            { tenant: Tenant.make("another-tenant") },
+          ]) {
+            const other = yield* createExecutor({ ...config, ...scope });
+            yield* Effect.addFinalizer(() => other.close().pipe(Effect.ignore));
+            expect(
+              Predicate.isTagged(
+                yield* other.oauth.getSetup(started.state).pipe(Effect.flip),
+                "OAuthSessionNotFoundError",
+              ),
+            ).toBe(true);
+          }
+          expect(
+            Predicate.isTagged(
+              yield* executor.oauth.getSetup(OAuthState.make("unknown")).pipe(Effect.flip),
+              "OAuthSessionNotFoundError",
+            ),
+          ).toBe(true);
+          yield* Effect.promise(() =>
+            config.db.updateMany("oauth_session", {
+              where: (b) => b("state", "=", String(started.state)),
+              set: { expires_at: Date.now() - 1 },
+            }),
+          );
+          expect(
+            Predicate.isTagged(
+              yield* executor.oauth.getSetup(started.state).pipe(Effect.flip),
+              "OAuthSessionNotFoundError",
+            ),
+          ).toBe(true);
+        }),
+      ),
+  );
+
+  it.effect("requires a host callback to serve setup even with a caller-provided callback", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const { executor } = yield* makeTestWorkspaceHarness({
+          plugins,
+          firstPartyOAuthClients: [firstParty],
+          redirectUri: null,
+        });
+        yield* executor.acme.seed();
+        const error = yield* executor.oauth
+          .start({ ...startInput, redirectUri: "https://client.example/callback" })
+          .pipe(Effect.flip);
+        expect(Predicate.isTagged(error, "OAuthStartError")).toBe(true);
+      }),
+    ),
+  );
+});
diff --git a/packages/core/sdk/src/oauth-service.ts b/packages/core/sdk/src/oauth-service.ts
index 7d8d7d46ea..39fb237554 100644
--- a/packages/core/sdk/src/oauth-service.ts
+++ b/packages/core/sdk/src/oauth-service.ts
@@ -2088,33 +2088,8 @@ export const makeOAuthService = (deps: OAuthServiceDeps): OAuthService => {
           ),
         );
 
-      yield* deps.fuma.use("oauth_session.create", (db) =>
-        looseDb(db).create("oauth_session", {
-          tenant: keys.tenant,
-          owner: keys.owner,
-          subject: keys.subject,
-          state: String(state),
-          client_slug: String(input.client),
-          integration: String(input.integration),
-          name: String(name),
-          template: String(input.template),
-          redirect_url: flowRedirectUri,
-          pkce_verifier: verifier,
-          identity_label: input.identityLabel ?? null,
-          // Persist the requested scope set (declared ∪ client, filtered to the
-          // authorization-code flow) so `complete`'s recorded-scope fallback
-          // reflects exactly what was requested when the AS omits `scope`,
-          // without re-resolving the integration's declared scopes at completion.
-          payload: {
-            owner: input.owner,
-            clientOwner: input.clientOwner,
-            requestedScopes: completeRequestedScopes,
-          },
-          expires_at: expiresAt,
-          created_at: now,
-        }),
-      );
-
+      // Build before persisting: setup must resume this exact authorization
+      // request, including its PKCE challenge and organization-scoped state.
       const authorizationUrl = yield* Effect.try({
         try: () =>
           buildAuthorizationUrl({
@@ -2145,9 +2120,73 @@ export const makeOAuthService = (deps: OAuthServiceDeps): OAuthService => {
           }),
       });
 
+      if (firstParty?.authorizationSetup !== undefined && redirectUri === null) {
+        return yield* new OAuthStartError({
+          message: "OAuth setup requires a configured host redirectUri.",
+        });
+      }
+
+      yield* deps.fuma.use("oauth_session.create", (db) =>
+        looseDb(db).create("oauth_session", {
+          tenant: keys.tenant,
+          owner: keys.owner,
+          subject: keys.subject,
+          state: String(state),
+          client_slug: String(input.client),
+          integration: String(input.integration),
+          name: String(name),
+          template: String(input.template),
+          redirect_url: flowRedirectUri,
+          pkce_verifier: verifier,
+          identity_label: input.identityLabel ?? null,
+          // Persist the requested scope set (declared ∪ client, filtered to the
+          // authorization-code flow) so `complete`'s recorded-scope fallback
+          // reflects exactly what was requested when the AS omits `scope`,
+          // without re-resolving the integration's declared scopes at completion.
+          payload: {
+            owner: input.owner,
+            clientOwner: input.clientOwner,
+            requestedScopes: completeRequestedScopes,
+            ...(firstParty?.authorizationSetup !== undefined ? { authorizationUrl } : {}),
+          },
+          expires_at: expiresAt,
+          created_at: now,
+        }),
+      );
+
+      if (firstParty?.authorizationSetup !== undefined && redirectUri !== null) {
+        const setupUrl = new URL("setup", redirectUri);
+        setupUrl.searchParams.set("state", providerState);
+        return { status: "redirect", authorizationUrl: setupUrl.toString(), state } as const;
+      }
+
       return { status: "redirect", authorizationUrl, state } as const;
     });
 
+  const getSetup: OAuthService["getSetup"] = (state) =>
+    Effect.gen(function* () {
+      const row = yield* deps.fuma.use("oauth_session.setup", (db) =>
+        looseDb(db).findFirst("oauth_session", {
+          where: (b: any) => b("state", "=", String(state)),
+        }),
+      );
+      if (!row || Number(row.expires_at) <= Date.now()) {
+        return yield* new OAuthSessionNotFoundError({ state });
+      }
+      const setup = firstPartyBySlug.get(String(row.client_slug))?.authorizationSetup;
+      const payload = row.payload;
+      if (
+        setup === undefined ||
+        typeof payload !== "object" ||
+        payload === null ||
+        !("authorizationUrl" in payload) ||
+        typeof payload.authorizationUrl !== "string"
+      ) {
+        return yield* new OAuthSessionNotFoundError({ state });
+      }
+      return { setup, authorizationUrl: payload.authorizationUrl };
+    });
+
   // -----------------------------------------------------------------------
   // complete — redeem the session, exchange the code, mint the connection.
   // -----------------------------------------------------------------------
@@ -2579,6 +2618,7 @@ export const makeOAuthService = (deps: OAuthServiceDeps): OAuthService => {
     registerDynamicClient,
     listClients,
     start,
+    getSetup,
     complete,
     cancel,
     probe,
diff --git a/packages/core/sdk/src/shared.ts b/packages/core/sdk/src/shared.ts
index 391c12e3fa..f6e812e5a9 100644
--- a/packages/core/sdk/src/shared.ts
+++ b/packages/core/sdk/src/shared.ts
@@ -163,6 +163,8 @@ export {
   type TokenEndpointAuthMethod,
   isTokenEndpointAuthMethod,
   type FirstPartyOAuthClientConfig,
+  type OAuthAuthorizationSetup,
+  type OAuthSetupResult,
   type OAuthGrant,
   type OAuthAuthentication,
   type OAuthClient,