diff --git a/content/docs/configure-and-extend/index.mdx b/content/docs/configure-and-extend/index.mdx
index ce46a4c..18898c0 100644
--- a/content/docs/configure-and-extend/index.mdx
+++ b/content/docs/configure-and-extend/index.mdx
@@ -94,7 +94,7 @@ team, or local workflow needs.
 - Agent tools are missing or too broad: start with
   [Connections and MCP](/configure-and-extend/connections-and-mcp), then check
   [Connection Scope and Overrides](/web/guides/connection-scope-and-overrides).
-- Repo is visible but cannot trigger hosted work: start with
+- A repo is missing or cannot trigger hosted work: start with
   [GitHub](/integrations/github) and [Installations](/web/installations).
 - Sandbox launch reports missing access: start with
   [Plans & Billing](/plans-and-billing), then confirm repo settings in
diff --git a/content/docs/guides/common-use-cases.mdx b/content/docs/guides/common-use-cases.mdx
index a5b50d4..376b10d 100644
--- a/content/docs/guides/common-use-cases.mdx
+++ b/content/docs/guides/common-use-cases.mdx
@@ -171,8 +171,8 @@ Check in this order:
    or [Automations](/web/automations)
 5. [Observability](/web/observability), but only after a run actually exists
 
-If the repo is only visible through OAuth, hosted GitHub routing will not be
-healthy yet. Fix App coverage first.
+If the repo owner's GitHub App installation is not linked to you, hosted GitHub
+routing will not be healthy yet. Fix App coverage first.
 
 ## Use the hosted API
 
diff --git a/content/docs/guides/index.mdx b/content/docs/guides/index.mdx
index aacbe64..44a9c19 100644
--- a/content/docs/guides/index.mdx
+++ b/content/docs/guides/index.mdx
@@ -65,7 +65,7 @@ known, but the sequence still matters.
   <Card
     title="GitHub App Coverage"
     href="/web/guides/github-app-coverage"
-    description="Debug the difference between OAuth repo visibility and GitHub App triggerability."
+    description="Debug the difference between GitHub sign-in and GitHub App coverage, and check that the right installation is linked to you."
   />
   <Card
     title="GitHub Mention Routing"
diff --git a/content/docs/guides/sandbox-setup-checklist.mdx b/content/docs/guides/sandbox-setup-checklist.mdx
index 0f86685..8d704e3 100644
--- a/content/docs/guides/sandbox-setup-checklist.mdx
+++ b/content/docs/guides/sandbox-setup-checklist.mdx
@@ -18,7 +18,7 @@ contract before changing agents, prompts, routes, or models.
 
 | Check | Why it matters |
 | --- | --- |
-| GitHub App coverage | Hosted work needs installation-backed repo access, not only OAuth visibility |
+| GitHub App coverage | Hosted work needs repo access from a GitHub App installation linked to you; GitHub sign-in alone grants none |
 | Repo import state | Mogplex needs a repo record before it can launch workspace or API runs |
 | Root directory | Monorepos need the exact app/package path instead of repo root |
 | Install command | Dependency setup should match the package manager and workspace path |
diff --git a/content/docs/guides/troubleshooting.mdx b/content/docs/guides/troubleshooting.mdx
index 009dd8a..118ef3e 100644
--- a/content/docs/guides/troubleshooting.mdx
+++ b/content/docs/guides/troubleshooting.mdx
@@ -13,8 +13,8 @@ work started.
 
 | Symptom | Most likely layer |
 | --- | --- |
-| Repo is missing or stale | account sync or Projects |
-| Repo is visible but GitHub events do not fire | GitHub App coverage |
+| Repo is missing or stale | installation not linked to you, repo not shared to your team, or repo sync |
+| GitHub events do not fire for a repo | linked installation or route binding |
 | Mention does not route | agent slug, default mention route, or route enabled state |
 | Slack mention replies but does not start repo work | Slack channel link, user mapping, repo-agent enabled state, or workspace limits |
 | Route exists but no run appears | route source, coverage, enabled state, or published automation |
@@ -41,12 +41,15 @@ work started.
 9. Check [Worktrees](/web/worktrees) when a planned coding task uses an
    isolated checkout.
 
-## Repo is visible but events do not fire
+## GitHub events do not fire
 
-Visibility and triggerability are different.
+Events start work only for repos covered by an installation linked to you, and
+only through a route bound to that installation or repo.
 
 1. Open [Installations](/web/installations).
-2. Confirm the repo owner is covered by the Mogplex GitHub App.
+2. Confirm the repo owner's Mogplex GitHub App installation is linked to you.
+   If an org you belong to is missing, see
+   [An org you belong to does not appear](/web/installations#an-org-you-belong-to-does-not-appear).
 3. Confirm the route is on the same installation or repo that owns the event.
 4. Confirm the route is enabled, or the automation is published.
 5. If work starts, continue into [Observability](/web/observability).
diff --git a/content/docs/index.mdx b/content/docs/index.mdx
index 67b6f68..39d94e0 100644
--- a/content/docs/index.mdx
+++ b/content/docs/index.mdx
@@ -299,7 +299,8 @@ finish, then drill into the product surface that owns it.
 After the first hour, these should all be true:
 
 - Mogplex can see the repos you expect.
-- The repo owner has GitHub App coverage, not only OAuth visibility.
+- The repo owner's GitHub App installation is linked to you, or the repo is
+  shared to your Mogplex team.
 - At least one reusable agent is configured the way you expect.
 - One local CLI run completes successfully.
 - You know whether the next job belongs in Triggers, Assignments, or
diff --git a/content/docs/integrations/github.mdx b/content/docs/integrations/github.mdx
index 11e8562..f87d3b9 100644
--- a/content/docs/integrations/github.mdx
+++ b/content/docs/integrations/github.mdx
@@ -7,50 +7,69 @@ GitHub is the first integration most Mogplex accounts need.
 
 It does two separate jobs:
 
-- identity and repo discovery through GitHub OAuth
-- webhook-backed routing through the Mogplex GitHub App
+- the GitHub connection (GitHub OAuth) identifies your GitHub account and reads
+  your org memberships
+- the Mogplex GitHub App gives Mogplex access to repositories and sends the
+  webhooks that start work
 
-Keep those separate while debugging. A repo can be visible in
-[Projects](/web/spaces) and still fail to trigger hosted work if the owner does
-not have GitHub App coverage.
+Repository access comes from a Mogplex GitHub App installation that is linked
+to you, or from repositories a teammate has shared to your Mogplex team. Neither
+GitHub sign-in nor the GitHub connection grants repository access on its own.
 
 ## Setup order
 
-1. Open [Settings](/web/settings) and connect GitHub.
-2. Install the Mogplex GitHub App for the user or org that owns the repos.
-3. Confirm installation coverage in [Installations](/web/installations).
-4. Sync or import repos in [Projects](/web/spaces).
+1. Open **Settings → Account** and select **Install GitHub App**. If your
+   GitHub account is not connected yet, GitHub asks you to authorize Mogplex
+   first.
+2. Install the App on your personal account, or on an org where you are an org
+   owner. Mogplex links the installation when GitHub returns you to Mogplex.
+3. Confirm the installation under **Settings → Account** (see
+   [Installations](/web/installations)).
+4. Sync repos in [Projects](/web/spaces).
 5. Choose the routing surface that matches the work:
    [Triggers](/web/triggers), [Assignments](/web/assignments), or
    [Automations](/web/automations).
 6. Verify the first run in [Observability](/web/observability).
 
-## OAuth vs GitHub App coverage
+## Repository access
 
-| State | What it unlocks | What it does not unlock yet |
-| --- | --- | --- |
-| GitHub disconnected | Nothing GitHub-backed | Repo import, repo creation, webhook routing |
-| OAuth connected | Account identity and repo import | Webhook-backed routing |
-| App installed | Repo coverage for GitHub events | Synced repos until import or sync completes |
-| App installed and repos synced | Full GitHub-backed setup | N/A |
+| State | What you can use |
+| --- | --- |
+| GitHub connected, no installation linked | No repositories, except repositories shared to your Mogplex team |
+| Installation linked | Every repository in that installation, for repo work, webhooks, triggers, and automations |
+| Installation linked and repos synced | Full GitHub-backed setup |
 
-Use [GitHub App Coverage](/web/guides/github-app-coverage) when a repo is
-visible but [Triggers](/web/triggers) or [Automations](/web/automations) cannot
-route work into it.
+The rules that decide this:
+
+- You can link an installation on your own personal account, or on an org where
+  you are an org owner. Linking gives you the installation's whole repository
+  set.
+- Org members who are not owners do not link the org installation. They use
+  team-shared repositories instead. See
+  [Who can link an installation](/web/installations#who-can-link-an-installation).
+- If an installation is uninstalled or suspended on GitHub, your access to its
+  repositories ends. See
+  [When an installation is removed](/web/installations#when-an-installation-is-removed).
+
+For how linking happens, see
+[How an installation gets linked](/web/installations#how-an-installation-gets-linked).
+If an org you belong to is missing, see
+[An org you belong to does not appear](/web/installations#an-org-you-belong-to-does-not-appear).
+
+Self-hosted deployments without a GitHub App work differently: there, the GitHub
+OAuth app lists and imports repositories. See
+[Self-hosted GitHub App](/self-hosting/github-app).
 
 ## Repository creation
 
 Creating a repository from Mogplex has its own requirements:
 
-- **In an organization**, the App must be installed there and an organization
-  owner must accept the App's Repository creation permission on GitHub. If
-  Mogplex says the App "cannot create repositories yet", the request is still
-  pending or the organization's repository creation policy blocks it. If you
-  self-host, see also
+- **In an organization**, you must be an org owner, and the org's installation
+  must be linked to you. An org owner must also accept the App's Repository
+  creation permission on GitHub. If Mogplex says the App "cannot create
+  repositories yet", the request is still pending or the organization's
+  repository creation policy blocks it. If you self-host, see also
   [GitHub App troubleshooting](/self-hosting/github-app#repository-creation-failures).
-
-  Separately, only organization owners can create organization repositories
-  from Mogplex. That is a Mogplex rule, not a GitHub setting.
 - **In your personal account**, the App must be installed on your account, so
   Mogplex can work in the new repository. Then select **Authorize GitHub** when
   Mogplex asks. Mogplex creates personal repositories with your own GitHub
@@ -89,8 +108,8 @@ rules, including entry-agent behavior in automations.
 ## Where to check state
 
 - [Settings](/web/settings): GitHub connection state and account-level setup
-- [Installations](/web/installations): App coverage, repo eligibility, and
-  synced repo state
+- [Installations](/web/installations): linked installations, repo eligibility,
+  and synced repo state
 - [Projects](/web/spaces): imported repo list, repo settings, and workspace
   entry points
 - [Observability](/web/observability): run status and failure trail after a
@@ -98,8 +117,10 @@ rules, including entry-agent behavior in automations.
 
 ## Common failures
 
-- **Repo is visible but triggers are empty**: OAuth is connected, but App
-  coverage is missing for the repo owner.
+- **An org you belong to does not appear**: the org's installation is not
+  linked to you. An org owner installs or configures the App; see
+  [An org you belong to does not appear](/web/installations#an-org-you-belong-to-does-not-appear).
+- **Triggers are empty**: no installation is linked to you for the repo owner.
 - **Mention does not wake the expected agent**: the comment may be bare
   `@mogplex` when it needed `@mogplex/<agent-slug>`, or the wrong route is
   marked default.
diff --git a/content/docs/platform/how-mogplex-fits-together.mdx b/content/docs/platform/how-mogplex-fits-together.mdx
index 9b7f621..f1088a3 100644
--- a/content/docs/platform/how-mogplex-fits-together.mdx
+++ b/content/docs/platform/how-mogplex-fits-together.mdx
@@ -27,7 +27,7 @@ Each object answers a different question.
 | Object | Owns | Start here when |
 | --- | --- | --- |
 | Account state | Identity, managed model and sandbox access, CLI tokens, model defaults, Slack installs, connections, MCP definitions | sign-in, model, billing, token, Slack, or connection state looks wrong |
-| GitHub installation | App-backed coverage for one GitHub user or org | repos are visible but GitHub events do not trigger work |
+| GitHub installation | App-backed coverage for one GitHub user or org | repos are missing or GitHub events do not trigger work |
 | Repo | Imported repository state and repo-specific settings | the target repo is missing, duplicated, hidden, or needs runtime settings |
 | Agent | Reusable behavior, slug, prompt, model, skills, rules, and context | the worker itself behaves wrong or a mention slug does not resolve |
 | Route | The rule that decides what wakes work | the wrong event, repo, or workflow starts work |
@@ -60,13 +60,16 @@ Each object answers a different question.
 
 ### Visibility vs triggerability
 
-Repo visibility means Mogplex can see a repo through account sync.
+Repo visibility means Mogplex lists a repo. With a GitHub App, Mogplex lists
+repos from installations linked to you and repos shared to your team.
 
-Triggerability means the owning GitHub user or org has App-backed coverage, so
-GitHub webhook events can start hosted work.
+Triggerability means the owning GitHub user or org has App-backed coverage, and
+a route is bound to that installation or repo, so GitHub webhook events can
+start hosted work.
 
-A repo can be visible without being triggerable. When that happens, fix
-[GitHub App coverage](/web/guides/github-app-coverage) before editing routes.
+If a repo is missing, fix [GitHub App coverage](/web/guides/github-app-coverage).
+If a listed repo does not trigger, check the route's installation binding
+before editing the agent.
 
 ### Agent definition vs route binding
 
diff --git a/content/docs/quickstart.mdx b/content/docs/quickstart.mdx
index 7ea6a97..b286e5d 100644
--- a/content/docs/quickstart.mdx
+++ b/content/docs/quickstart.mdx
@@ -22,9 +22,11 @@ needs before it can do useful work:
 - Slack workspace and channel links if work should start from Slack
 - shared connections and MCP definitions, if the repo needs external tools
 
-If a repo is visible through OAuth but not covered by the GitHub App, hosted
-routing will still fail later. Use [Installations](/web/installations) to
-confirm coverage before debugging triggers or automations. The
+GitHub sign-in alone does not give Mogplex repository access. The repo owner's
+GitHub App installation must be linked to you: install the App on your personal
+account, or on an org where you are an org owner. Use
+[Installations](/web/installations) to confirm coverage before debugging
+triggers or automations. The
 [GitHub integration guide](/integrations/github) explains the full setup model.
 
 ## 2. Open the repo
diff --git a/content/docs/reference/glossary.mdx b/content/docs/reference/glossary.mdx
index fba1f00..4804cfb 100644
--- a/content/docs/reference/glossary.mdx
+++ b/content/docs/reference/glossary.mdx
@@ -85,9 +85,10 @@ Read next: [Custom Slash Commands](/configure-and-extend/custom-slash-commands).
 The state that lets Mogplex receive webhook-backed GitHub events for a user or
 organization.
 
-OAuth visibility can make repos visible in the app, but GitHub App coverage is
-what makes hosted routing healthy for Triggers and Automations. If a repo is
-visible but events do not start work, check App coverage first.
+GitHub sign-in identifies you but grants no repository access. GitHub App
+coverage, from an installation linked to you, is what gives Mogplex repo access
+and makes hosted routing healthy for Triggers and Automations. If a repo is
+missing or events do not start work, check App coverage first.
 
 Read next: [GitHub App Coverage](/web/guides/github-app-coverage).
 
@@ -153,11 +154,12 @@ Read next: [Projects](/web/spaces).
 
 ## Repo visibility
 
-Whether Mogplex can see a repo through account sync.
+Whether a repo appears in Projects for you.
 
-Visibility is not the same as triggerability. A repo can be visible through
-OAuth but still unable to start hosted GitHub-event work until the owning user
-or organization has GitHub App coverage.
+Visibility is not the same as triggerability. With a GitHub App, Mogplex lists
+repos from installations linked to you and repos shared to your team. Only a
+self-hosted deployment without a GitHub App lists repos through GitHub OAuth,
+and those repos cannot start hosted GitHub-event work.
 
 Read next: [GitHub](/integrations/github).
 
@@ -222,11 +224,11 @@ Read next: [Triggers](/web/triggers).
 
 ## Triggerability
 
-Whether a visible repo can actually start hosted GitHub-event work.
+Whether a repo can actually start hosted GitHub-event work.
 
-Triggerability requires the right GitHub App coverage. If a repo appears in
-Projects but Triggers or Automations do not fire, debug triggerability before
-changing the agent.
+Triggerability requires the right GitHub App coverage and a route bound to the
+installation that owns the event. If Triggers or Automations do not fire for a
+repo, debug triggerability before changing the agent.
 
 Read next: [Coverage and Triggerability](/web/installations/coverage-and-triggerability).
 
diff --git a/content/docs/reference/security-and-data-handling.mdx b/content/docs/reference/security-and-data-handling.mdx
index e80550d..d610b1b 100644
--- a/content/docs/reference/security-and-data-handling.mdx
+++ b/content/docs/reference/security-and-data-handling.mdx
@@ -13,8 +13,8 @@ when debugging.
 
 Mogplex crosses several systems:
 
-- GitHub OAuth and the Mogplex GitHub App for identity, repo discovery, and
-  webhook-backed routing
+- GitHub OAuth for identity and org membership, and the Mogplex GitHub App for
+  repository access and webhook-backed routing
 - managed sandbox access for preview runtimes
 - managed model access for hosted execution
 - Slack OAuth and webhooks for Slack conversations and repo-agent starts
diff --git a/content/docs/self-hosting/database-and-auth.mdx b/content/docs/self-hosting/database-and-auth.mdx
index 047455b..a7120ae 100644
--- a/content/docs/self-hosting/database-and-auth.mdx
+++ b/content/docs/self-hosting/database-and-auth.mdx
@@ -97,8 +97,11 @@ ID and secret are set.
 | Microsoft | `AUTH_MICROSOFT_CLIENT_ID`, `AUTH_MICROSOFT_CLIENT_SECRET`, `AUTH_MICROSOFT_TENANT_ID` (default `common`) | `https://<domain>/api/auth/callback/microsoft` |
 | Email and password | Resend (below) | None |
 
-GitHub sign-in is identity only. Repository access comes from a separate GitHub
-OAuth app and your [GitHub App](/self-hosting/github-app).
+GitHub sign-in is identity only. Org membership, which Mogplex uses to find and
+link installations, comes from the GitHub connection through the separate
+GitHub OAuth app (`GITHUB_CLIENT_*`). Repository access comes from your
+[GitHub App](/self-hosting/github-app) installations. A deployment without a
+GitHub App lists repositories through a separate GitHub OAuth app instead.
 
 ## Email
 
diff --git a/content/docs/self-hosting/environment-variables.mdx b/content/docs/self-hosting/environment-variables.mdx
index c491347..54a2b30 100644
--- a/content/docs/self-hosting/environment-variables.mdx
+++ b/content/docs/self-hosting/environment-variables.mdx
@@ -66,7 +66,7 @@ See [Database and auth](/self-hosting/database-and-auth#use-a-least-privilege-ru
 | `GITHUB_APP_NAME` | GitHub App slug, as in `github.com/apps/<slug>`. |
 | `GITHUB_APP_PRIVATE_KEY` | PEM. Write newlines as `\n` in single-line env files. |
 | `GITHUB_WEBHOOK_SECRET` | Must match the App's webhook secret. |
-| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | Classic GitHub OAuth app for repository listing and reauthorization. The GitHub App's own client credentials do not work here. |
+| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | Classic GitHub OAuth app for user identity, org membership, and reauthorization. Without a GitHub App, it also lists repositories. The GitHub App's own client credentials do not work here. |
 | `GITHUB_APP_CLIENT_ID`, `GITHUB_APP_CLIENT_SECRET` | Optional. The App's own OAuth client credentials, used only to create repositories in personal accounts. App service only; Trigger.dev does not need them. Callback: `/api/auth/github/app-user/callback`. See [GitHub App](/self-hosting/github-app#client-credentials-for-personal-repositories). |
 | `MOGPLEX_SETUP_ENABLED` | `1` enables `/admin/setup/github` in production while the GitHub App is unconfigured. Remove it after setup. |
 
diff --git a/content/docs/self-hosting/github-app.mdx b/content/docs/self-hosting/github-app.mdx
index 5466fc6..bc5210e 100644
--- a/content/docs/self-hosting/github-app.mdx
+++ b/content/docs/self-hosting/github-app.mdx
@@ -13,7 +13,7 @@ GitHub has two separate jobs in Mogplex. Configure both:
 | Piece | What it unlocks | Variables |
 | --- | --- | --- |
 | GitHub App | Installation-backed repo access, webhooks, check runs, PR reviews, triggers, and automations | `GITHUB_APP_ID`, `GITHUB_APP_NAME`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_WEBHOOK_SECRET`, and optionally `GITHUB_APP_CLIENT_ID` and `GITHUB_APP_CLIENT_SECRET` |
-| GitHub OAuth app | Repository listing and import, and reauthorization when a token needs new scopes | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` |
+| GitHub OAuth app | User identity and org membership, used to find and link installations, and reauthorization when a token needs new scopes. Without a GitHub App, it also lists and imports repositories | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` |
 
 GitHub *sign-in* (`AUTH_GITHUB_*`) is a third, identity-only setting. See
 [Database and auth](/self-hosting/database-and-auth#sign-in-providers).
@@ -155,15 +155,17 @@ Open **Developer settings → OAuth Apps → New OAuth App**.
 | Homepage URL | `https://<domain>` |
 | Authorization callback URL | `https://<domain>/api/auth/github/callback` |
 
-Mogplex requests the `repo`, `read:org`, `read:user`, and `user:email` scopes.
-Store the credentials:
+With a GitHub App configured, Mogplex requests the `read:org`, `read:user`, and
+`user:email` scopes. Repository access comes only from App installations. In a
+deployment without a GitHub App, Mogplex also requests `repo` so it can list and
+import repositories. Store the credentials:
 
 ```bash
 GITHUB_CLIENT_ID=...
 GITHUB_CLIENT_SECRET=...
 ```
 
-<Callout title="One OAuth app for sign-in and repo access">
+<Callout title="One OAuth app for sign-in and the GitHub connection">
   GitHub accepts any redirect path under an OAuth app's callback URL. If you set
   the callback URL to `https://<domain>/api/auth`, one OAuth app serves both
   `/api/auth/github/callback` and GitHub sign-in at
@@ -174,9 +176,14 @@ GITHUB_CLIENT_SECRET=...
 ## 4. Install and verify
 
 1. Redeploy so the app reads the new variables.
-2. Sign in, open **Settings → Account**, and connect GitHub. This installs the
-   App on the accounts or organizations that own your repositories.
-3. Open [Installations](/web/installations) and confirm coverage. Then sync
+2. Sign in, open **Settings → Account**, and select **Install GitHub App**.
+   Install the App on your personal account, or on an organization where you
+   are an owner. Mogplex links the installation when GitHub returns you to the
+   deployment. Organization members who are not owners cannot link the org
+   installation. See
+   [Who can link an installation](/web/installations#who-can-link-an-installation).
+3. Check the linked installations under **Settings → Account** (see
+   [Installations](/web/installations)) and confirm coverage. Then sync
    repositories in **Settings → Repositories** (see [Projects](/web/spaces)).
 4. In the App's **Advanced → Recent deliveries**, confirm that deliveries return
    `2xx`. A `401` means `GITHUB_WEBHOOK_SECRET` does not match the App's
@@ -187,7 +194,8 @@ GITHUB_CLIENT_SECRET=...
 | Symptom | Check |
 | --- | --- |
 | **Connect GitHub** opens an OAuth screen instead of the App install | One of `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, or `GITHUB_APP_NAME` is missing. |
-| Repos are listed but triggers never fire | The App is not installed on that owner, or the webhook URL points somewhere else. |
+| Repos are listed but triggers never fire | The webhook URL points somewhere else, or webhook deliveries fail. Check **Advanced → Recent deliveries**. |
+| An organization does not appear after install | The installation is not linked. An organization owner installs or configures the App so the callback links it. See [An org you belong to does not appear](/web/installations#an-org-you-belong-to-does-not-appear). |
 | `invalid_state` after the GitHub redirect | The callback reached a different domain than the one that started the flow. Make `NEXT_PUBLIC_APP_URL` match the public URL. |
 | New permissions have no effect | Each installation must accept the new permissions on GitHub. For repository creation, see [Repository creation failures](#repository-creation-failures). |
 | Creating a repository in an organization fails with "cannot create repositories yet" | GitHub returned `Resource not accessible by integration`. See [Repository creation failures](#repository-creation-failures). |
diff --git a/content/docs/support.mdx b/content/docs/support.mdx
index 60ce8e9..a075e05 100644
--- a/content/docs/support.mdx
+++ b/content/docs/support.mdx
@@ -14,7 +14,7 @@ repo coverage, routing, execution, and local CLI state.
 | Symptom | Start here |
 | --- | --- |
 | A charge, invoice, credit balance, payment method, or due date looks wrong | [Plans & Billing](/plans-and-billing), then email [support@mogplex.com](mailto:support@mogplex.com) |
-| Repo is visible but GitHub events do not start work | [GitHub](/integrations/github) and [Installations](/web/installations) |
+| A repo is missing or GitHub events do not start work | [GitHub](/integrations/github) and [Installations](/web/installations) |
 | A model is missing from a picker or CLI run | [Available Models](/web/models) and [Model Selection and Cost](/guides/model-selection-and-cost) |
 | Hosted run cannot call an external service | [Connections and MCP](/configure-and-extend/connections-and-mcp) and [Connection Scope and Overrides](/web/guides/connection-scope-and-overrides) |
 | Slack mention does not start repo work | [Slack](/integrations/slack), [Settings](/web/settings#slack), and [Observability Runbook](/guides/observability-runbook) |
diff --git a/content/docs/web/guides/choose-routing-surface.mdx b/content/docs/web/guides/choose-routing-surface.mdx
index 2b5851c..6bcbcb8 100644
--- a/content/docs/web/guides/choose-routing-surface.mdx
+++ b/content/docs/web/guides/choose-routing-surface.mdx
@@ -17,8 +17,7 @@ Answer these questions first:
 
 1. is the source of truth a GitHub App installation event, one repo, or a
    workflow graph?
-2. does the repo owner already have GitHub App coverage, or is it only synced
-   through OAuth?
+2. is the repo owner's GitHub App installation linked to you yet?
 3. do you need draft and publish control, or should the route be live as soon
    as it is created?
 4. is this standing responsibility for one repo, or policy for an installation?
@@ -49,8 +48,8 @@ Use Triggers when you want the smallest routing surface that still works.
 Two prerequisite details matter:
 
 - Triggers are installation-scoped, so GitHub App coverage is required.
-- Seeing a repo in [Projects](/web/spaces) is not enough if that repo is only
-  synced through OAuth.
+- GitHub sign-in alone is not enough. The installation for the repo owner must
+  be linked to you.
 
 If the trigger form has no usable installations, stop and fix App coverage
 before debugging the agent.
@@ -94,7 +93,7 @@ If you need branching, publish control, or a workflow that spans multiple
 steps, use Automations.
 
 The setup nuance is the same as Triggers: Automations are installation-scoped
-and need GitHub App coverage, not just synced repos.
+and need GitHub App coverage on the installation that owns the event.
 
 The operating nuance is different: the draft graph is not the live route until
 you publish it.
diff --git a/content/docs/web/guides/github-app-coverage.mdx b/content/docs/web/guides/github-app-coverage.mdx
index a241cca..4437823 100644
--- a/content/docs/web/guides/github-app-coverage.mdx
+++ b/content/docs/web/guides/github-app-coverage.mdx
@@ -1,32 +1,35 @@
 ---
 title: GitHub App Coverage
-description: Understand the difference between GitHub OAuth and GitHub App coverage, and verify why a repo is or is not triggerable.
+description: Understand the difference between GitHub sign-in and GitHub App coverage, and verify why a repo is or is not triggerable.
 ---
 
 Most confusion in Mogplex setup comes from mixing up two different GitHub
 states:
 
-- **GitHub connected** through OAuth
-- **GitHub App installed** for the account or org that owns the repo
+- **GitHub connected** through GitHub sign-in
+- **GitHub App installed** for the account or org that owns the repo, with the
+  installation linked to you
 
 They are related, but they do different jobs.
 
-## OAuth vs App coverage
+## Sign-in vs App coverage
 
-GitHub OAuth gives Mogplex your user identity and basic account connection.
+The GitHub connection (GitHub OAuth) gives Mogplex your GitHub identity and
+your org memberships. It does not grant repository access.
+Signing in to Mogplex with GitHub is a separate step that only identifies you.
 
-GitHub App coverage determines which repos Mogplex can treat as triggerable for
-webhook-backed work such as [Triggers](/web/triggers) and
-[Automations](/web/automations).
-
-That means a repo can be visible in [Projects](/web/spaces) but still not be
-usable for triggered routing if the App is not installed for that owner.
+GitHub App coverage determines which repos Mogplex can access, and which it can
+treat as triggerable for webhook-backed work such as [Triggers](/web/triggers)
+and [Automations](/web/automations). Coverage comes from an installation linked
+to you: on your personal account, or on an org where you are an org owner. Org
+members who are not owners use team-shared repositories instead. See
+[Who can link an installation](/web/installations#who-can-link-an-installation).
 
 ## Common symptoms of missing App coverage
 
 - Triggers is empty even though GitHub is connected
 - Automations cannot find the installation or repo you expect
-- A repo appears in Projects, but GitHub-backed routing is unavailable
+- An org you belong to is missing from Settings
 - Settings shows GitHub connected, but installation coverage is missing or for
   the wrong owner
 
@@ -45,14 +48,17 @@ confirm the App is installed where you think it is.
 
 ## What to do next
 
-If GitHub is connected but the App is not installed for the repo owner:
+If GitHub is connected but no installation is linked to you for the repo owner:
 
-1. Install the Mogplex GitHub App for that owner
+1. Install or configure the Mogplex GitHub App for that owner. For an org, an
+   org owner must do this. See
+   [An org you belong to does not appear](/web/installations#an-org-you-belong-to-does-not-appear).
 2. Return to [Settings](/web/settings) and refresh the installation state
 3. Go back to [Projects](/web/spaces) and sync repos again
 4. Re-check [Triggers](/web/triggers) or [Automations](/web/automations)
 
 ## Rule of thumb
 
-If the question is "why can Mogplex see this repo but not route webhook work
-for it?", the answer is usually App coverage, not OAuth.
+If the question is "why can't Mogplex use this repo or route webhook work for
+it?", the answer is usually an installation that is not linked to you, not
+GitHub sign-in.
diff --git a/content/docs/web/guides/index.mdx b/content/docs/web/guides/index.mdx
index e655e4d..d54f296 100644
--- a/content/docs/web/guides/index.mdx
+++ b/content/docs/web/guides/index.mdx
@@ -20,7 +20,7 @@ not just route-by-route descriptions.
   <Card
     title="GitHub App Coverage"
     href="/web/guides/github-app-coverage"
-    description="Understand OAuth vs App coverage, why repos can be visible but not triggerable, and how to verify the right install."
+    description="Understand GitHub sign-in vs App coverage, who can link an installation, and how to verify the right install."
   />
   <Card
     title="Choose the Right Routing Surface"
diff --git a/content/docs/web/guides/project-workflow.mdx b/content/docs/web/guides/project-workflow.mdx
index e0ad74d..4077337 100644
--- a/content/docs/web/guides/project-workflow.mdx
+++ b/content/docs/web/guides/project-workflow.mdx
@@ -18,9 +18,13 @@ If you do those in the right order, setup gets much easier to reason about.
 
 Start in [Settings](/web/settings) and connect GitHub.
 
-That establishes your account identity and is enough to start importing repos.
+That establishes your account identity. It does not give Mogplex access to
+repos.
 
-It is **not** the same thing as GitHub App coverage.
+It is **not** the same thing as GitHub App coverage. Repo access comes from a
+GitHub App installation linked to you: on your personal account, or on an org
+where you are an org owner. See
+[Who can link an installation](/web/installations#who-can-link-an-installation).
 
 That distinction matters because Mogplex treats these setup states
 differently:
@@ -28,15 +32,19 @@ differently:
 | State | What it unlocks | What it does not unlock yet |
 | --- | --- | --- |
 | Disconnected | Nothing GitHub-backed | Repo import, repo creation, trigger routing |
-| OAuth connected | Repo import and repo creation | Webhook-backed routing |
-| App install pending | Repo import can still work if OAuth is already connected | Trigger-ready coverage until the install completes |
+| OAuth only | Account identity and team-shared repositories | Your own repo import, repo creation, webhook-backed routing |
+| App install pending | Account identity and team-shared repositories | Trigger-ready coverage until the installation is linked to you |
 | App installed, no synced repos yet | Installation coverage exists | Repos will not show up in Projects until they are synced or imported |
 | App installed with synced repos | Full GitHub-backed setup | N/A |
 
+In a self-hosted deployment without a GitHub App, `OAuth only` still lists and
+imports repos through OAuth. Those repos cannot start App-backed work.
+
 If you only remember one rule, use this one:
 
-- GitHub connection lets Mogplex see repos
-- GitHub App coverage lets Mogplex route webhook-backed work into them
+- GitHub sign-in tells Mogplex who you are
+- a linked GitHub App installation lets Mogplex use repos and route
+  webhook-backed work into them
 
 ## 2. Confirm App coverage
 
@@ -75,17 +83,18 @@ From [Projects](/web/spaces), you can:
 
 - import repos into the default imported project
 - create additional projects to group repos
-- create a new GitHub repo inside a project when GitHub is already connected
+- create a new GitHub repo inside a project when the owner's installation is
+  linked to you
 - add sub-project repos for monorepo targets
 - configure repo-specific settings such as sandbox behavior, env sync, and
   linked Vercel project state
 
 Two practical nuances matter here:
 
-- If GitHub is connected through OAuth, you can still import repos before the
-  App install is finished.
-- Once installation-backed sync is active, covered repos become the preferred
-  source of truth in Projects, which helps avoid stale OAuth-only duplicates.
+- Repo import needs a linked installation. GitHub sign-in alone does not
+  import repos.
+- Once installation-backed sync is active, Projects lists only repos covered by
+  a linked installation, which hides stale `Synced only` rows.
 
 ## 5. Confirm managed sandbox access if you plan to launch workspaces
 
@@ -129,10 +138,10 @@ Once the repo is imported, choose the lightest surface that matches the job:
 - Use [Automations](/web/automations) when you need branching, multiple steps,
   or publish control
 
-For webhook-backed routing, make sure the repo is App-covered, not just synced.
-
-That is the most common setup miss when a repo looks available in Projects but
-still will not wake Triggers or Automations.
+For webhook-backed routing, confirm the route is bound to the installation or
+repo that owns the event. A repo can be covered while the route points at a
+different installation, or at a stale installation id. See
+[Repo Sync and Rebinding](/web/installations/repo-sync-and-rebinding).
 
 ## 8. Watch it in Observability
 
diff --git a/content/docs/web/index.mdx b/content/docs/web/index.mdx
index 03ad356..f280585 100644
--- a/content/docs/web/index.mdx
+++ b/content/docs/web/index.mdx
@@ -143,12 +143,13 @@ For the full redirect map, use [Legacy Routes](/web/guides/legacy-routes).
 
 ## Common “where do I fix this?” questions
 
-- **Why is Triggers empty?** Usually because GitHub OAuth is connected but the
-  Mogplex GitHub App is not installed for the owner that holds the repo. Check
-  [Installations](/web/installations).
-- **Why can I see repos but not launch the kind of work I want?** Repo sync and
-  webhook coverage are separate concerns. Projects can show synced repos before
-  they are fully triggerable.
+- **Why is Triggers empty?** Usually because GitHub is connected but no Mogplex
+  GitHub App installation is linked to you for the owner that holds the repo.
+  Check [Installations](/web/installations).
+- **Why is a repo missing from Projects, or why do Triggers not fire for it?**
+  The repo owner's installation is not linked to you, or the repo is not shared
+  to your Mogplex team. If the repo is listed but a route does not fire, check
+  that the route is bound to the installation that owns the event.
 - **Where do I set up models and external tools?** Use
   [Settings](/web/settings) for account access,
   [Connections](/configure-and-extend/connections-and-mcp) for external services, and
diff --git a/content/docs/web/installations/coverage-and-triggerability.mdx b/content/docs/web/installations/coverage-and-triggerability.mdx
index 13e208e..32c93bf 100644
--- a/content/docs/web/installations/coverage-and-triggerability.mdx
+++ b/content/docs/web/installations/coverage-and-triggerability.mdx
@@ -1,31 +1,30 @@
 ---
 title: Coverage and Triggerability
-description: Learn why GitHub OAuth is not the same as GitHub App coverage, how Mogplex labels connection state, and what makes a repo actually trigger-ready.
+description: Learn why GitHub sign-in is not the same as GitHub App coverage, how Mogplex labels connection state, and what makes a repo actually trigger-ready.
 ---
 
 Most setup confusion in Mogplex comes from mixing up three different states:
 
 - GitHub account connected
-- repo visible in Mogplex
+- installation linked to you
 - repo triggerable for webhook-backed work
 
 Those are related, but they are not the same thing.
 
-## OAuth is not enough
+## Sign-in is not enough
 
-GitHub OAuth can be enough to connect an account and discover repositories.
+The GitHub connection (GitHub OAuth) identifies your GitHub account and reads
+your org memberships. It does not give Mogplex access to repositories.
+Signing in to Mogplex with GitHub is a separate step that only identifies you.
 
-But webhook-backed routing depends on GitHub App coverage.
+Repository access and webhook-backed routing both come from a GitHub App
+installation linked to you. Until one is linked, you can use only repositories
+shared to your Mogplex team. See
+[Who can link an installation](/web/installations#who-can-link-an-installation).
 
-That means a repo can still:
-
-- appear in [Projects](/web/spaces)
-- belong to the right user
-- even be synced already
-
-and still not be eligible for [Triggers](/web/triggers) or
-[Automations](/web/automations) if the GitHub App is not installed for the
-owner that controls that repo.
+Self-hosted deployments without a GitHub App are the exception: there, GitHub
+OAuth lists and imports repositories, but webhook-backed routing is not
+available.
 
 ## What "triggerable" actually means
 
@@ -51,8 +50,8 @@ The account connection can show up in states like:
 
 | State | Meaning |
 | --- | --- |
-| `OAuth only` | GitHub is connected, but routing still needs App coverage |
-| `Install pending` | The App install was started, but GitHub still needs to finish it |
+| `OAuth only` | The GitHub connection exists, but no installation is linked to you. With a GitHub App, you have no repository access of your own yet. In a self-hosted deployment without a GitHub App, this is the normal connected state: repos are listed and imported through OAuth, but none of them can start hosted GitHub-event work. |
+| `Install pending` | The App install was started, but no installation is linked to you yet. If it stays here after you finish on GitHub, see [An org you belong to does not appear](/web/installations#an-org-you-belong-to-does-not-appear). |
 | `App installed` | Coverage exists, but no covered repos are synced into Projects yet |
 | `Ready` | App coverage is active and covered repos are already synced |
 
@@ -60,13 +59,26 @@ These are account signals, not repo signals.
 
 ### Repo-level coverage state
 
-Each repo effectively falls into one of these buckets:
+Mogplex tracks each repo's coverage as one of these states:
 
-| Repo label | Meaning |
+| State | Meaning |
 | --- | --- |
-| `Trigger-ready` | The repo has a `github_installation_id` and can participate in App-backed routing |
-| `Synced only` | The repo is visible in Projects, but has no App coverage yet |
-| `Not covered` | The App is installed somewhere for the user, but not for this repo's owner or scope |
+| `Trigger-ready` | The repo has a `github_installation_id`, from an installation linked to you or from the teammate who shared the repo to your team, and can participate in App-backed routing |
+| `Synced only` | The repo has no installation id, and no installation is linked to you |
+| `Not covered` | An installation is linked to you, but the repo has no installation id |
+
+Projects does not show these labels. It uses them to decide what to list. Once
+an installation is linked to you, Projects lists only repos that have an
+installation id, whether it comes from your own installation or from the
+teammate who shared the repo. Repos without one stay out of the list.
+If none of your repos has an installation id yet, for example before the first
+sync after an install, Projects shows all your repos so the list is not empty.
+If a repo you expect is missing, add it to the
+installation on GitHub, or install the App on the account that owns it.
+
+While no installation is linked to you, Projects lists every repo you can use,
+including `Synced only` repos. That is the normal state in a self-hosted
+deployment without a GitHub App.
 
 This is the state that matters when the question is "will this route wake up?"
 
@@ -88,13 +100,16 @@ Each installation surfaces:
 If installation metadata is incomplete, Mogplex will try to refresh it from
 GitHub before presenting the final view.
 
-## Reconciliation can fill in missing installation state
+## Discovery can fill in missing installation state
 
-Mogplex does not only rely on the user manually refreshing setup pages.
+Mogplex does not only rely on the install callback.
 
-If the app has GitHub App config and knows your GitHub username, the hosted
-surfaces can attempt to reconcile installation state when the current install
-list is still empty.
+Each time you open **Settings → Account**, Mogplex looks for installations on
+your own account and on your GitHub orgs, and links the ones you own. Orgs that
+restrict third-party OAuth apps are not visible to discovery. A GitHub webhook
+can also link an installation when you install the App or, as the account or
+org owner, add repositories to it. See
+[How an installation gets linked](/web/installations#how-an-installation-gets-linked).
 
 That is why these pages can sometimes "heal" after an install finishes in
 GitHub even if you did not manually resync every step yourself.
@@ -105,16 +120,16 @@ When coverage is missing or wrong, users usually see one of these:
 
 - Triggers is empty
 - Automations cannot find the installation they expect
-- a repo shows up in Projects but cannot participate in webhook routing
+- an org you belong to is missing from Settings
 - Settings says GitHub is connected, but the status is still `OAuth only`
-- Settings shows an App installation, but the repo you care about is still
-  `Synced only` or `Not covered`
+- Settings shows an App installation, but the repo you care about is missing
+  from Projects
 
 ## Mental model
 
 Use this rule:
 
-- OAuth answers "who are you?"
+- GitHub sign-in answers "who are you?"
 - installation coverage answers "which owners and repos can Mogplex automate?"
 
 If the question is about routing, coverage is the thing that matters.
@@ -122,10 +137,12 @@ If the question is about routing, coverage is the thing that matters.
 ## Good troubleshooting order
 
 1. Check [Settings](/web/settings) and read the current GitHub status label
-2. Confirm the expected owner or org appears in [Installations](/web/installations)
-3. Check whether the repo is actually `Trigger-ready`, not just visible in
-   [Projects](/web/spaces)
-4. If the App install recently changed, let Mogplex reconcile or rerun repo
-   sync
+2. Confirm the expected owner or org appears under **Settings → Account** (see
+   [Installations](/web/installations))
+3. Check that the repo is listed in [Projects](/web/spaces), then use
+   [Repo-level coverage state](#repo-level-coverage-state) to read what the
+   list tells you
+4. If the App install recently changed, reopen **Settings → Account** so
+   discovery runs, or rerun repo sync
 5. Retry the exact GitHub event you expect, then confirm it in
    [Observability](/web/observability)
diff --git a/content/docs/web/installations/index.mdx b/content/docs/web/installations/index.mdx
index 7ae7547..0865001 100644
--- a/content/docs/web/installations/index.mdx
+++ b/content/docs/web/installations/index.mdx
@@ -1,6 +1,6 @@
 ---
 title: Overview
-description: Understand GitHub App installations, how Mogplex maps repos to them, and why installation coverage is different from simple repo visibility.
+description: Understand GitHub App installations, who can link one to Mogplex, how linking happens, and how Mogplex maps repos to them.
 ---
 
 Installations are the GitHub App coverage layer behind Mogplex repo automation.
@@ -10,18 +10,17 @@ docs section describes the GitHub App installation state surfaced in
 [Settings](/web/settings) and consumed by [Projects](/web/spaces),
 [Triggers](/web/triggers), and [Automations](/web/automations).
 
-## The distinction to keep explicit
+## The GitHub connection and installations do different jobs
 
-For most setup problems, there are three states a repo can be in:
+- **The GitHub connection** (GitHub OAuth, made when you choose **Connect
+  GitHub** or **Install GitHub App**) identifies your GitHub account and reads
+  your org memberships. It never grants repository access when Mogplex uses a
+  GitHub App. Signing in to Mogplex with GitHub is a separate step that only identifies you.
+- **A linked GitHub App installation** gives you its repositories and sends the
+  webhooks that start work for the installed account or org.
 
-1. **not visible at all**
-2. **visible through GitHub OAuth**
-3. **covered by a Mogplex GitHub App installation**
-
-Only the third state is fully eligible for App-backed routing and automation.
-
-That is why Installations deserves its own docs section even though the product
-does not currently expose it as a standalone top-level dashboard page.
+You can use a repo only when it belongs to an installation linked to you, or
+when it is shared to your Mogplex team.
 
 ## Why installations matter
 
@@ -30,54 +29,102 @@ An installation answers two different questions:
 1. which account or org has granted the Mogplex GitHub App access
 2. which repos are therefore eligible for App-backed behavior
 
-That second point is the important one. A repo can be visible through OAuth and
-still not be triggerable.
+When the right installation is linked, Mogplex can:
+
+- list and sync the installation's repos
+- receive webhook events for the installed owner
+- offer that installation as a routing target in [Triggers](/web/triggers)
+- reconnect synced repos to the correct owner and installation metadata
+
+## Who can link an installation
 
-## OAuth vs installation coverage
+You can link an installation on:
 
-Keep this distinction explicit:
+- your own personal GitHub account
+- an org where you are an active org owner
 
-- **GitHub OAuth** gives Mogplex an authenticated user identity and supports
-  repo discovery
-- **GitHub App installation** gives Mogplex webhook-backed coverage for the
-  installed account or org
+Linking gives you the installation's whole repository set. That set can include
+repositories GitHub hides from ordinary org members, so org members who are not
+owners do not link the org installation. They use team-shared repositories:
+repositories that a teammate with the linked installation has shared to the
+Mogplex team. Joining a team does not add your teammates' personal repositories
+to it.
 
-That is why a repo can appear in [Projects](/web/spaces) yet still fail to
-participate in [Triggers](/web/triggers) or installation-backed automations.
+Team members can work on a team-shared repository in Projects and agent runs.
+[Triggers](/web/triggers) and [Automations](/web/automations) are different:
+each one belongs to an installation linked to the person who creates it. To
+add a trigger or an automation for an org's repositories, ask an org owner who
+has linked the org installation to create it.
 
-## What “covered” unlocks in practice
+## How an installation gets linked
 
-When the right installation exists, Mogplex can do more than just list repos.
+Mogplex links an installation to you in three ways:
 
-It can:
+1. **Install callback.** When you install or configure the App, GitHub returns
+   you to Mogplex and Mogplex links the installation. This works whether you
+   started from **Settings → Account** or directly on GitHub.
+2. **Discovery.** Each time you open **Settings → Account**, Mogplex looks for
+   installations on your own account and on your GitHub orgs, and links the
+   ones you own. Orgs that restrict third-party OAuth apps are not visible to
+   discovery.
+3. **Webhook.** When you install the App, accept new permissions, unsuspend an
+   installation, or add repositories to it, GitHub sends a webhook. Mogplex
+   links the installation to the Mogplex user who made the change, if that user
+   owns the account. A repository admin who adds one repository is not linked.
 
-- receive webhook events for the installed owner
-- offer that installation as a routing target in [Triggers](/web/triggers)
-- treat repos under that owner as eligible for App-backed workflows
-- reconnect synced repos to the correct owner and installation metadata
+After the install callback, Mogplex shows a message that says whether the
+installation was linked, or why it was not.
+
+## An org you belong to does not appear
+
+If an org is missing from **Settings → Account**, its installation is not linked
+to you. Common causes:
+
+- the App is not installed on the org yet
+- you are a member of the org, not an org owner
+- the org restricts third-party OAuth apps, so discovery cannot see it
+
+To fix it, an org owner installs or configures the App:
+
+- from Mogplex: open **Settings → Account** and select **Install GitHub App**
+  or **Add org or personal install**, then pick the org on GitHub
+- on GitHub: open the org's **Settings → GitHub Apps → Mogplex →
+  Configure**, then select **Save**
+
+GitHub returns the owner to Mogplex, and the install callback links the
+installation. Mogplex checks ownership with the App's own installation token,
+so an org's third-party OAuth app restriction does not block this.
+
+If you are not an org owner, ask an owner to link the installation and share
+the repositories you need with your Mogplex team.
+
+## When an installation is removed
+
+If an installation is uninstalled, suspended, or loses access to a repository,
+your access to those repositories ends. Mogplex fails closed: it never falls
+back to an older GitHub OAuth grant to reach them. Your stored workspaces,
+drafts, and history are kept.
 
 ## What the app surfaces show
 
-Inside [Settings](/web/settings), each installation can show:
+**Settings → Account** shows each linked installation under **Installed
+scopes**:
 
 - the account or org name
 - whether the scope is personal or org
 - the synced repos Mogplex currently associates with that installation
 - how many repos are mapped to it
-- a direct manage link back to GitHub
+- a **Manage on GitHub** link
 
 This is the fastest way to answer the real operator question:
 
-**Do I have the right App installed on the right owner, or am I only seeing
-repos through OAuth?**
+**Is the App installed on the right owner, and is that installation linked to
+me?**
 
 ## How Mogplex keeps installation state fresh
 
-The installations API is a little self-healing.
-
-If Mogplex has GitHub App config and your GitHub username, but there are no
-stored installations yet, it can reconcile against GitHub again and hydrate the
-local installation records before returning the Settings view.
+Discovery runs each time you open **Settings → Account**, not only when you have
+no installations yet. Mogplex skips accounts that are already linked.
 
 It can also refresh incomplete installation metadata, such as missing account
 login or target type, and then derive:
@@ -90,21 +137,22 @@ without asking you to reconnect everything manually.
 
 ## The most reliable workflow
 
-1. Connect GitHub in [Settings](/web/settings).
-2. Confirm the expected personal account or org appears in the installation
-   list.
+1. In **Settings → Account**, select **Install GitHub App**, or **Add org or
+   personal install** if you already have an installation. Install the App on
+   your personal account or on an org you own.
+2. Confirm the expected personal account or org appears under **Installed
+   scopes**.
 3. Sync repos into [Projects](/web/spaces).
 4. Only after that, debug [Triggers](/web/triggers) or
    [Automations](/web/automations).
 
 If you skip step 2, you can spend time debugging a routing problem that is
-really just missing GitHub App coverage.
+really just an installation that is not linked to you.
 
 ## Common symptoms of missing coverage
 
-- the repo appears in [Projects](/web/spaces), but [Triggers](/web/triggers)
-  offers no useful installations
-- mention or PR-triggered work never fires even though the repo is visible
+- [Triggers](/web/triggers) offers no useful installations
+- mention or PR-triggered work never fires for a repo you expect
 - webhook-backed automation looks empty or unavailable for the owner you need
 - the app appears connected, but Mogplex still behaves as if the repo is
   “outside” the GitHub App boundary
@@ -112,7 +160,7 @@ really just missing GitHub App coverage.
 ## In this section
 
 - [Coverage and Triggerability](/web/installations/coverage-and-triggerability)
-  explains the “repo is visible but not triggerable” setup model
+  explains the connection status labels and what makes a repo trigger-ready
 - [Repo Sync and Rebinding](/web/installations/repo-sync-and-rebinding)
   explains how repos are attached to installations and how stale bindings get
   repaired
diff --git a/content/docs/web/installations/repo-sync-and-rebinding.mdx b/content/docs/web/installations/repo-sync-and-rebinding.mdx
index c45ba37..ace07d0 100644
--- a/content/docs/web/installations/repo-sync-and-rebinding.mdx
+++ b/content/docs/web/installations/repo-sync-and-rebinding.mdx
@@ -14,28 +14,25 @@ That means sync has two jobs at once:
 
 ## Installation-backed sync
 
-When GitHub App configuration is available, Mogplex prefers installation-scoped
-repo sync.
+When GitHub App configuration is available, Mogplex syncs repos only from the
+installations linked to you. GitHub sign-in does not add repos to the
+inventory.
 
-That matters because installation-backed sync gives Mogplex a real
-`github_installation_id` for the repo instead of just an OAuth-discovered repo
-record.
+Installation-backed sync gives Mogplex a real `github_installation_id` for each
+repo. That id is the source of truth for repo access and automation routing.
 
-In practice, that means covered repos become the preferred source of truth for
-automation routing.
-
-## OAuth sync vs installation sync
+## Sync paths
 
 These paths look similar in the UI, but they behave differently:
 
 | Sync path | What it does | What it avoids doing |
 | --- | --- | --- |
-| OAuth-only sync | Imports repos Mogplex can discover through the connected GitHub user | Does not overwrite an existing App installation id on a repo |
+| OAuth-only sync | Self-hosted deployments without a GitHub App only. Imports repos the connected GitHub user can access | Does not overwrite an existing App installation id on a repo |
 | Installation sync | Imports the repos GitHub says belong to a specific App installation and records that installation id | Does not guess across multiple installations |
 | Webhook reconciliation | Reacts to install, uninstall, repo add/remove, rename, transfer, and delete events | Does not rely on manual resync to stay current |
 
-That separation is deliberate. An OAuth import is useful for visibility, but it
-is not allowed to silently clobber App-backed routing state.
+That separation is deliberate. An OAuth import is not allowed to silently
+clobber App-backed routing state.
 
 ## What Mogplex updates and what it preserves
 
@@ -56,8 +53,15 @@ structure or installation coverage.
 Older OAuth-only repo rows can linger after a user moves to installation-backed
 GitHub access.
 
-When installation-backed sync is active, Mogplex prefers covered repos in
-Projects so stale OAuth-only rows do not crowd the active list.
+Once an installation is linked to you, the repo inventory includes only repos
+the linked installations currently grant. Repos left over from an earlier OAuth
+sync, or transferred out of an installation, are excluded. Their stored
+workspaces, drafts, and history are kept. An installation with no repos never
+brings back the old OAuth-only rows.
+
+Team inventory works the same way. Each team-shared repo is checked against the
+installation of the teammate who shared it. Team members use those repos
+without linking their own installation.
 
 ## Metadata refresh
 
@@ -72,6 +76,8 @@ underlying row started incomplete.
 
 When installation state changes from GitHub webhooks, Mogplex can:
 
+- link the installation to the Mogplex user who made the change, if that user
+  owns the account
 - upsert installation rows
 - resync repos for affected users
 - add installation coverage to newly added repos
@@ -90,6 +96,14 @@ The important webhook-backed update paths are:
 - `repository` events such as create, rename, transfer, visibility changes, and
   delete
 
+Some of these events also link an installation: `installation` events for
+`created`, `new_permissions_accepted`, and `unsuspend`, and
+`installation_repositories` events for `added`. Each one links the installation
+to the Mogplex user who made the change, if that user owns the account. A
+repository admin who adds one repo to an org installation does not own the org,
+so that event does not link the installation. See
+[How an installation gets linked](/web/installations#how-an-installation-gets-linked).
+
 ## Rebinding stale trigger and automation state
 
 Automations and triggers are installation-scoped too.
@@ -130,8 +144,9 @@ sync or binding problem, not a prompt problem.
 
 1. Check [Settings](/web/settings) to confirm the right installation exists for
    the repo owner
-2. Check [Projects](/web/spaces) to confirm the repo is App-covered, not just
-   visible
+2. Check [Projects](/web/spaces) to confirm the repo is listed. With a GitHub
+   App, a listed repo is covered by an installation linked to you, or by the
+   installation of the teammate who shared it
 3. Re-run repo sync if coverage recently changed
 4. Re-test the exact GitHub event that should wake the route
 5. Use [Observability](/web/observability) to confirm whether the event reached
diff --git a/content/docs/web/settings.mdx b/content/docs/web/settings.mdx
index cf573e4..fa388d1 100644
--- a/content/docs/web/settings.mdx
+++ b/content/docs/web/settings.mdx
@@ -57,8 +57,8 @@ If the question is “what should run for this repo?”, use
 For a new account, the most reliable order is:
 
 1. connect GitHub
-2. install the Mogplex GitHub App for the personal account or orgs that own the
-   repos you want to use
+2. install the Mogplex GitHub App on your personal account, or on an org where
+   you are an org owner, so the installation is linked to you
 3. confirm the account plan includes the model and sandbox access you need
 4. add shared connections or MCP servers after the account basics are working
 5. generate CLI or API access tokens only when the CLI or scripts need to
@@ -96,13 +96,15 @@ The **Account** page shows:
 
 Two distinctions matter here:
 
-- **GitHub OAuth** is about account identity and repo discovery
-- **GitHub App coverage** is what makes repos triggerable for reviews,
-  automations, and webhook-backed routing
+- **The GitHub connection** (GitHub OAuth) identifies your GitHub account and
+  reads your org memberships. It does not grant repository access.
+  Signing in to Mogplex with GitHub is a separate step that only identifies you.
+- **A linked GitHub App installation** gives you its repositories and makes
+  them triggerable for reviews, automations, and webhook-backed routing.
 
-If a repo shows up in [Projects](/web/spaces) but still cannot participate in
-[Triggers](/web/triggers) or automation, the usual cause is missing App
-coverage for that owner.
+You can link an installation on your personal account or on an org where you
+are an org owner. If an org you belong to is missing, see
+[An org you belong to does not appear](/web/installations#an-org-you-belong-to-does-not-appear).
 
 ## Run checks
 
@@ -180,10 +182,8 @@ For each installation, Mogplex can show:
 - a GitHub manage link when one can be derived
 - the list of synced repos under that installation
 
-This is the fastest way to answer a common setup problem:
-
-**Can Mogplex merely see this repo, or is it actually covered for App-backed
-work?**
+Use it to confirm that the App is installed on the right owner and that the
+installation is linked to you.
 
 ## Connections
 
@@ -359,8 +359,8 @@ models, and repo-level exclusions.
 
 ## Fast troubleshooting map
 
-- **Triggers page is empty**: GitHub OAuth may be connected, but App coverage is
-  missing for the repo owner.
+- **Triggers page is empty**: GitHub may be connected, but no installation is
+  linked to you for the repo owner.
 - **The CLI signs in but no shared models or MCP entries appear**: the Mogplex
   account exists, but the hosted account may still lack model access or shared
   connection setup.
@@ -371,9 +371,9 @@ models, and repo-level exclusions.
   Slack section of **Connections**.
 - **Sandbox launch says access is unavailable**: check the account plan and
   entitlement state before changing repo settings.
-- **The repo is visible, but webhook-backed work still does not fire**:
-  visibility and App-backed coverage are different states. Check the
-  installation list here first.
+- **A repo is missing, or webhook-backed work does not fire for it**: the repo
+  owner's installation may not be linked to you. Check the installation list
+  here first.
 
 ## Why Settings matters
 
diff --git a/content/docs/web/spaces.mdx b/content/docs/web/spaces.mdx
index 03afc48..a67b316 100644
--- a/content/docs/web/spaces.mdx
+++ b/content/docs/web/spaces.mdx
@@ -107,9 +107,9 @@ when you need to choose between Sandbox compute and a task Worktree.
 
 ## Failure modes that matter
 
-- **Repo is visible but trigger-backed features do not work**:
-  GitHub OAuth is connected, but the correct GitHub App installation is
-  missing.
+- **A repo is missing, or trigger-backed features do not work**:
+  the repo owner's GitHub App installation is not linked to you. See
+  [Installations](/web/installations).
 - **The first mission on a repo feels slow**:
   the repo probably needs its sandbox created or installed first.
 - **Sandbox launch says access is unavailable**:
@@ -117,9 +117,10 @@ when you need to choose between Sandbox compute and a task Worktree.
 - **Preview opens the wrong app in a monorepo**:
   set the root directory, dev command, and dev port in the **General** tab.
 - **Creating a new repository fails**:
-  an organization owner must accept the GitHub App's Repository creation
-  permission. A personal account needs the App installed and **Authorize
-  GitHub** once. See
+  in an organization, you must be an org owner with the org's installation
+  linked to you, and an org owner must accept the GitHub App's Repository
+  creation permission. A personal account needs the App installed and
+  **Authorize GitHub** once. See
   [Repository creation](/integrations/github#repository-creation).
 - **A repo disappeared from the project picker**:
   it may be removed. Restore it from **Settings → Repositories → Show
diff --git a/content/docs/web/triggers.mdx b/content/docs/web/triggers.mdx
index 1429c38..6009daf 100644
--- a/content/docs/web/triggers.mdx
+++ b/content/docs/web/triggers.mdx
@@ -62,14 +62,20 @@ Current trigger events are:
 
 Triggers only work for repos covered by an installed GitHub App.
 
-GitHub OAuth on its own is not enough. If the page is empty, or the creation
+GitHub sign-in on its own is not enough. If the page is empty, or the creation
 form says no installations are available, check
 [Installations](/web/installations) and confirm the correct user or org has the
-Mogplex GitHub App installed.
+Mogplex GitHub App installed and the installation is linked to you.
+
+A trigger belongs to an installation linked to the person who creates it.
+Org members who are not org owners cannot link the org installation, so they
+cannot create triggers for its repositories, even for repositories shared to
+their team. Ask an org owner who has linked the installation to create the
+trigger.
 
 The creation form searches installations by both account scope and synced repos,
-so this page is often the fastest way to notice that repos are synced but still
-not webhook-covered.
+so this page is often the fastest way to notice that a repo is in Projects but
+no linked installation covers it.
 
 ## How to create a good trigger
 
@@ -164,7 +170,7 @@ multiple steps, use [Automations](/web/automations).
 ## Common mistakes
 
 - writing `@mogplex triage` instead of `@mogplex/triage`
-- expecting OAuth-synced repos to appear before GitHub App coverage exists
+- expecting repos to appear before a GitHub App installation is linked to you
 - using Triggers when the logic really belongs to one repo and should be an
   [Assignment](/web/assignments)
 - assuming bare `@mogplex` will route anywhere without a default mention route