aws-samples
diff --git a/‎docs/getting-started/setup.md‎
Lines changed: 11 additions & 10 deletions b/‎docs/getting-started/setup.md‎
Lines changed: 11 additions & 10 deletions
diff --git a/‎docs/using-the-platform/git-integration.md‎
Lines changed: 15 additions & 11 deletions b/‎docs/using-the-platform/git-integration.md‎
Lines changed: 15 additions & 11 deletions
diff --git a/‎docs/using-the-platform/platform-settings.md‎
Lines changed: 1 addition & 1 deletion b/‎docs/using-the-platform/platform-settings.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎frontend/src/components/CreateProjectModal.test.tsx‎
Lines changed: 127 additions & 2 deletions b/‎frontend/src/components/CreateProjectModal.test.tsx‎
Lines changed: 127 additions & 2 deletions
@@ -98,7 +98,7 @@ The deployment takes 15-30 minutes. Neptune DB cluster creation takes the longes
 
 ### Bootstrap the first platform administrator
 
-The **Admin** page (user management, agent settings and default models, provider OAuth apps, GitHub auth mode, migrations) and workflow/building-block authoring require membership in the Cognito **`platform-admin`** group. Bootstrap the first administrator via the CLI (users must sign out and back in to pick up the group); afterwards, additional admins can be granted or revoked in the UI under **Admin → Users**:
+The **Admin** page (user management, agent settings and default models, provider OAuth/App configuration, migrations) and workflow/building-block authoring require membership in the Cognito **`platform-admin`** group. Bootstrap the first administrator via the CLI (users must sign out and back in to pick up the group); afterwards, additional admins can be granted or revoked in the UI under **Admin → Users**:
 
 ```bash
 aws cognito-idp admin-add-user-to-group \
@@ -115,12 +115,9 @@ For GitHub and GitLab a single OAuth app serves both the code host and that prov
 
 #### GitHub (code host + GitHub Issues)
 
-GitHub supports two platform-wide authentication modes, switchable at runtime in **Admin → Source Control → GitHub**:
+Configure OAuth and GitHub App independently. They remain enabled simultaneously, and each project chooses its authentication type.
 
-- **OAuth mode** (default): each user connects their own GitHub account; commits, PRs and comments are attributed to that user.
-- **GitHub App mode**: the platform authenticates as a GitHub App installation (a bot); users don't connect personal accounts, and the repo picker lists the repositories the App is installed on.
-
-For **OAuth mode**:
+For **GitHub OAuth**:
 
 1. Open [GitHub Developer Settings → OAuth Apps → New OAuth App](https://github.com/settings/developers).
    Choose an **OAuth App**, _not_ a GitHub App — this mode expects OAuth App semantics.
@@ -132,12 +129,16 @@ For **OAuth mode**:
 
 The connection requests `repo`, `workflow`, and `read:user`. Existing users must click **Reauthorize GitHub** after upgrading from a version that did not request `workflow`; GitHub requires that scope before the engine can push changes under `.github/workflows/`.
 
-For **GitHub App mode**:
+For **GitHub App**:
 
-1. Create a [GitHub App](https://github.com/settings/apps) with repository permissions **Contents: Read & write**, **Pull requests: Read & write**, **Workflows: Read & write**, and **Issues: Read-only**. No callback URL or webhook is needed.
+1. Create a [GitHub App](https://github.com/settings/apps) with repository permissions **Contents: Read & write**, **Pull requests: Read & write**, **Issues: Read & write**, and metadata read access. No callback URL or webhook is needed. **Workflows: Read & write** is recommended but optional — without it a binding still verifies, but the agent cannot create or modify files under `.github/workflows/` and the project settings page shows a warning.
 2. Generate a **private key** (PEM) and note the **App ID**.
-3. Install the App on the organization/repositories the platform should access, and note the **Installation ID** (the number at the end of the installation's settings URL).
-4. In the deployed app, open **Admin → Source Control → GitHub**, paste the App ID, Installation ID and private key, select **GitHub App (bot)** and click **Save**. The platform validates the configuration live against GitHub before the mode switches. Switching back to OAuth mode is the same toggle.
+3. Install the App on each personal account or organization whose repositories projects may bind.
+4. In the deployed app, open **Admin → Source Control → GitHub**, paste the App ID and private key, then click **Save**. Installation IDs are discovered per repository when a project is bound.
+
+### Project-bound source control
+
+Existing projects must be explicitly bound by an owner/admin before intents can run against their repositories. During a credential incident, invalidate the affected project bindings (or revoke the token at the provider) — unbound or invalid bindings block repository-backed starts via the launch guard.
 
 #### GitLab (code host + GitLab Issues)
 
 
@@ -5,7 +5,7 @@ AIDLC Collaborative integrates with external systems on two independent axes:
 - **Code host** — GitHub or GitLab. The repository is cloned into the agent workspace and all code changes flow back as a pull request (GitHub) or merge request (GitLab).
 - **Issue trackers** — GitHub Issues, GitLab Issues, and Jira Cloud. An intent can be started from any tracker issue; the issue's title, body, and comments become the intent's brief for the agent.
 
-A project can bind to _one_ code host and to _zero or more_ trackers. Both are configured per project in **Project Settings**.
+A project can attach one or more repositories and zero or more trackers. Repository authorization is configured explicitly per project in **Project Settings**.
 
 GitHub and GitLab each span both axes: a single connection serves as the code host **and** backs that provider's issue tracker (GitHub Issues / GitLab Issues), so you authenticate once per provider. Jira Cloud is a tracker only.
 
@@ -15,18 +15,21 @@ Before users can connect their accounts, an administrator registers OAuth apps w
 
 The status of each provider is visible in **Admin → Trackers**. Until a provider shows **Configured**, the corresponding **Connect** button in Project Settings stays disabled with a hint pointing back to the admin panel.
 
-### GitHub authentication mode
+### Project-bound authentication
 
-GitHub supports two platform-wide authentication modes, switchable at runtime by a platform admin in **Admin → Source Control → GitHub**:
+GitHub OAuth and GitHub App configuration remain available at the same time. There is no platform-wide runtime mode:
 
-- **OAuth mode** (default) — each user connects their own GitHub account (described below). All git activity is attributed to the individual user.
-- **GitHub App mode** — the platform authenticates as a GitHub App installation (a bot). Users don't connect personal GitHub accounts at all; the repo picker lists the repositories the App is installed on, and commits/PRs/comments are attributed to the App. Which repositories are reachable is controlled by the App installation on GitHub — installing/uninstalling repos there takes effect immediately.
+- A project owner or admin selects **GitHub OAuth** or **GitHub App** for that project's GitHub repositories.
+- A project may use only one GitHub authentication type, but different projects may choose differently.
+- OAuth delegation is explicit. The owner/admin can delegate only their own connected identity and must confirm that the project may act through it.
+- For GitHub App bindings, the platform discovers and stores the installation for each repository. No global installation ID is configured.
+- GitLab repositories use an explicitly delegated GitLab OAuth connection.
 
-Switching modes takes effect for new work right away; in-flight runs finish under the mode they started with. Switching to App mode is validated live against GitHub (App ID + installation + private key) before it lands, so a broken configuration can never strand the platform.
+Every repository is verified before any binding is written. Existing repository-backed projects remain unbound after upgrade and cannot start until an owner/admin completes this step. Repository-free projects are unaffected.
 
 ## Connecting your account
 
-Each user connects their own GitHub / GitLab / Atlassian account once; the connection is reused across every project that needs that provider. (In GitHub App mode there is nothing to connect for GitHub — the section below applies to OAuth mode.)
+Each user connects their own GitHub / GitLab / Atlassian account once. A personal connection is available for repository discovery, but a project uses it only after an owner/admin explicitly delegates it.
 
 - **GitHub**: from the dashboard (or the project-creation flow), click **Connect GitHub** and approve the OAuth flow. The connection requests `repo`, `workflow`, and `read:user` so the engine can also push workflow-file changes. After upgrading an older connection that lacks `workflow`, click **Reauthorize GitHub** when prompted. The button stays disabled if your administrator hasn't configured GitHub OAuth credentials yet.
 - **GitLab**: choose **GitLab** as the provider in the project-creation flow, then click **Connect GitLab** and approve the OAuth flow. The required `api` scope covers repository writes, including `.gitlab-ci.yml`; GitLab has no separate workflow-file scope. The button stays disabled until your administrator has configured GitLab OAuth credentials. GitLab access tokens are short-lived; the platform refreshes them automatically using the stored refresh token, so you don't need to reconnect periodically.
@@ -38,10 +41,11 @@ A connection is scoped to its provider: connecting GitHub does not satisfy a Git
 
 1. Click **Create new Project** in the project overview.
 2. Choose the code host — **GitHub** or **GitLab**.
-3. The platform checks for an active connection to that provider and prompts you to connect if one is missing.
-4. Pick the repository (GitHub) or project (GitLab) that should back the collaborative project.
+3. For GitHub, choose the authentication type: **GitHub App** (uses the platform App's installations — no personal connection needed) or **My GitHub OAuth identity** (delegates your own connection). GitLab always delegates your OAuth identity. On the OAuth paths the platform prompts you to connect if no active connection exists.
+4. Pick the repository (GitHub) or project (GitLab) that should back the collaborative project. On the App path the picker lists the repositories the App is installed on; on the OAuth paths it lists your own.
+5. Confirm the binding (OAuth delegation requires an explicit confirmation). If verification fails, the project is created unbound — rebind it in **Project Settings → Repositories** before starting intents.
 
-The repository is cloned into the agent workspace and becomes available to the agents while an intent executes. Additional repositories can be added later in **Project Settings → Source Control**.
+The repository is cloned into the agent workspace and becomes available to the agents while an intent executes. Additional repositories can be added later in **Project Settings → Repositories**; the project binding must then be reverified.
 
 ## Branches
 
@@ -81,7 +85,7 @@ The Jira and GitLab Issues integrations are **read-only** — the agent never wr
 
 ## Reconnecting a tracker
 
-If a provider refresh token is revoked (for example, a user logs out of Atlassian or GitLab, or a workspace admin revokes the app), the tracker panel surfaces a **Reconnect** banner for that provider. The binding is preserved — only the user's authentication needs renewing — so reconnecting restores access without losing the project↔tracker relationship.
+If an OAuth token or refresh token is revoked, every dependent project source-control binding is marked invalid. Reconnect the personal account, then have a project owner/admin explicitly rebind the affected repositories. Removing the delegating member or uninstalling a GitHub App installation also invalidates dependent bindings.
 
 For GitLab specifically, routine token expiry does **not** require reconnecting: access tokens are refreshed automatically from the stored refresh token. A reconnect is only needed if that refresh token itself is revoked.
 
 
@@ -22,7 +22,7 @@ Everything the agent runtime needs to run:
 
 Platform-wide code-host configuration:
 
-- **GitHub** — the OAuth app credentials plus the runtime-switchable **authentication mode**: **OAuth** (each user connects their own account; activity attributed to the user) or **GitHub App** (the platform acts as an App installation — a bot; users connect nothing). Switching to App mode is validated live against GitHub before it lands. See [Git integration → GitHub authentication mode](git-integration.md#github-authentication-mode).
+- **GitHub** — GitHub OAuth app status and GitHub App identity/private-key configuration are shown simultaneously. Projects choose OAuth or App independently; there is no global mode or installation ID. See [Git integration → Project-bound authentication](git-integration.md#project-bound-authentication).
 - **GitLab** — the GitLab OAuth app credentials.
 - **Default PR strategy** — **Intent PR** opens only the final intent-to-base review; **PR per unit** also opens draft unit-to-intent reviews and integrates them in dependency order. Projects may inherit or override this default. The default is **Intent PR**.
 
 
@@ -6,9 +6,11 @@ import userEvent from '@testing-library/user-event';
 // in jsdom without network or Radix portal complexity. The GitRepoSelect stub
 // exposes a button that selects one repo, standing in for the provider-backed
 // picker.
+// Per-test switch: the "App path without OAuth" test flips this to false.
+let oauthConnected = true;
 vi.mock('../hooks/useGitProviderStatus', () => ({
   useGitProviderStatus: () => ({
-    status: { connected: true },
+    status: { connected: oauthConnected },
     loading: false,
     error: null,
     refresh: () => {},
@@ -23,7 +25,10 @@ vi.mock('./GitRepoSelect', () => ({
   ),
 }));
 vi.mock('../services/projects', () => ({
-  projectsService: { create: vi.fn().mockResolvedValue({ id: 'p1' }) },
+  projectsService: {
+    create: vi.fn().mockResolvedValue({ id: 'p1' }),
+    delete: vi.fn().mockResolvedValue(undefined),
+  },
 }));
 vi.mock('../services/workflows', () => ({
   workflowsService: {
@@ -36,14 +41,39 @@ vi.mock('../services/workflows', () => ({
   },
 }));
 vi.mock('../services/trackers', () => ({ trackersService: { addToProject: vi.fn() } }));
+vi.mock('../services/gitProvider', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../services/gitProvider')>();
+  return {
+    ...actual,
+    githubAppService: {
+      getStatus: vi.fn().mockResolvedValue({ configured: true }),
+      listRepos: vi.fn().mockResolvedValue([]),
+    },
+  };
+});
+vi.mock('../services/sourceControl', () => ({
+  sourceControlService: {
+    bind: vi.fn().mockResolvedValue({ ready: true, repositories: [] }),
+  },
+}));
 
 import { CreateProjectModal } from './CreateProjectModal';
 import { projectsService } from '../services/projects';
+import { sourceControlService } from '../services/sourceControl';
 import { workflowsService } from '../services/workflows';
+import { githubAppService } from '../services/gitProvider';
 
 describe('CreateProjectModal', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    oauthConnected = true;
+    vi.mocked(projectsService.create).mockResolvedValue({ id: 'p1' } as never);
+    vi.mocked(projectsService.delete).mockResolvedValue(undefined as never);
+    vi.mocked(sourceControlService.bind).mockResolvedValue({
+      ready: true,
+      repositories: [],
+    });
+    vi.mocked(githubAppService.getStatus).mockResolvedValue({ configured: true });
   });
 
   // The workflow catalog loads on mount; flush that promise inside act so the
@@ -95,7 +125,102 @@ describe('CreateProjectModal', () => {
         repos: [{ url: 'acme/widgets', role: 'primary' }],
       }),
     );
+    expect(sourceControlService.bind).toHaveBeenCalledWith('p1', {
+      github: { authType: 'github-app' },
+    });
+    expect(onCreated).toHaveBeenCalled();
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it('requires explicit confirmation before delegating OAuth', async () => {
+    const user = userEvent.setup();
+    await renderModal(
+      <CreateProjectModal onClose={() => {}} onCreated={() => {}} initialProvider="github" />,
+    );
+
+    // Step 1: switch from the default App path to OAuth delegation.
+    await user.click(screen.getByRole('radio', { name: /My GitHub OAuth identity/ }));
+    await user.click(screen.getByRole('button', { name: 'Next' }));
+    await user.click(screen.getByRole('button', { name: 'select-repo' }));
+    await user.click(screen.getByRole('button', { name: 'Next' }));
+
+    const createButton = screen.getByRole('button', { name: 'Create Space' });
+    expect(createButton).toBeDisabled();
+    await user.click(
+      screen.getByRole('checkbox', {
+        name: /I confirm that this space may use my connected identity/,
+      }),
+    );
+    expect(createButton).toBeEnabled();
+    await user.click(createButton);
+
+    await waitFor(() =>
+      expect(sourceControlService.bind).toHaveBeenCalledWith('p1', {
+        github: { authType: 'github-oauth', confirmDelegation: true },
+      }),
+    );
+  });
+
+  it('lets an unconnected user create a space via the GitHub App path', async () => {
+    oauthConnected = false;
+    const user = userEvent.setup();
+    const onCreated = vi.fn();
+    await renderModal(
+      <CreateProjectModal onClose={() => {}} onCreated={onCreated} initialProvider="github" />,
+    );
+
+    // App is configured, so Next is enabled despite connected=false.
+    const nextButton = screen.getByRole('button', { name: 'Next' });
+    await waitFor(() => expect(nextButton).toBeEnabled());
+    await user.click(nextButton);
+    await user.click(screen.getByRole('button', { name: 'select-repo' }));
+    await user.click(screen.getByRole('button', { name: 'Next' }));
+    const createBtn = await screen.findByRole('button', { name: 'Create Space' });
+    await waitFor(() => expect(createBtn).toBeEnabled());
+    await user.click(createBtn);
+
+    await waitFor(() =>
+      expect(sourceControlService.bind).toHaveBeenCalledWith('p1', {
+        github: { authType: 'github-app' },
+      }),
+    );
     expect(onCreated).toHaveBeenCalled();
+  });
+
+  it('blocks the App path and falls back to OAuth when the App is unconfigured', async () => {
+    vi.mocked(githubAppService.getStatus).mockResolvedValue({ configured: false });
+    oauthConnected = false;
+    await renderModal(
+      <CreateProjectModal onClose={() => {}} onCreated={() => {}} initialProvider="github" />,
+    );
+
+    // App option disabled; selection fell back to OAuth, which is not
+    // connected — so Next stays disabled.
+    await waitFor(() => expect(screen.getByRole('radio', { name: /GitHub App/ })).toBeDisabled());
+    expect(screen.getByRole('radio', { name: /My GitHub OAuth identity/ })).toBeChecked();
+    expect(screen.getByRole('button', { name: 'Next' })).toBeDisabled();
+  });
+
+  it('keeps a newly created project (unbound) when binding verification fails', async () => {
+    vi.mocked(sourceControlService.bind).mockRejectedValueOnce(
+      new Error('GitHub App is not installed for acme/widgets'),
+    );
+    const user = userEvent.setup();
+    const onCreated = vi.fn();
+    const onClose = vi.fn();
+    await renderModal(
+      <CreateProjectModal onClose={onClose} onCreated={onCreated} initialProvider="github" />,
+    );
+
+    await user.click(screen.getByRole('button', { name: 'Next' }));
+    await user.click(screen.getByRole('button', { name: 'select-repo' }));
+    await user.click(screen.getByRole('button', { name: 'Next' }));
+    await user.click(await screen.findByRole('button', { name: 'Create Space' }));
+
+    // The project survives unbound; the launch guard blocks repository-backed
+    // starts until an owner rebinds it in project settings.
+    await waitFor(() => expect(onCreated).toHaveBeenCalled());
+    expect(projectsService.delete).not.toHaveBeenCalled();
     expect(onClose).toHaveBeenCalled();
   });
 });