improvement(integrations): align setup controls and refresh search gu…

…ides
waleedlatif1 · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026
commit bc6e69b09b1f92b4b27c9c4d663ebded2dd56c8d
diff --git a/apps/docs/content/docs/search/confluence.mdx b/apps/docs/content/docs/search/confluence.mdx
@@ -51,7 +51,7 @@ Open **More options** for content type, labels, and metadata tags. The default i
 
 Select **Connect & Sync** to start indexing. Then open **Integrations** in the main sidebar and select **Connect** for Confluence. Authorize the configured site using the Atlassian email matching your verified Sim email.
 
-Each teammate completes this identity connection. Existing authorized accounts may already be connected. Its row shows your connection and indexing status.
+Each teammate completes this identity connection. An existing authorized account may already cover the site. Confluence appears once in Integrations, even with multiple sites; **Connect** or **Reconnect** appears when another authorization is needed.
 
 </Step>
 </Steps>
@@ -60,22 +60,22 @@ For workspace Search, start from **Search → Add source**. Available methods de
 
 ## Connect member accounts
 
-After an admin configures Confluence, select **Integrations → Confluence → Connect**. Authorize your account; you do not choose its spaces again.
+After an admin configures Confluence, open **Integrations** and select **Connect** beside Confluence. Authorize your account; you do not enter the site's domain or choose its spaces again.
 
-If Confluence is allowed but no source exists, select **Connect** beside Confluence. To add another site later, use **More → Add Confluence site**:
+If Confluence is allowed but no source exists, select **Connect** beside Confluence. To add another site later, open the Confluence row’s actions menu (**…**) and select **Add Confluence site**:
 
-1. Under **Your account**, select a saved account or choose **Connect account**. Authorize using the Atlassian email matching your verified Sim email.
-2. Enter the hostname under **Atlassian site**, then choose **Spaces**. Use **All** in the dropdown for the complete current list, or **Enter keys manually** for comma-separated keys. You can select up to 1,000 spaces in this form.
+1. Open **Your account** and select a saved account or **Connect Confluence account**. Authorize using the Atlassian email matching your verified Sim email.
+2. Enter the hostname under **Atlassian site**, then choose **Spaces**. Use **All** in the dropdown for the complete current list, or the arrows beside **Spaces** to enter comma-separated keys. You can select up to 1,000 spaces in this form.
 3. Select **Connect & Sync**. Sim saves the selected scope and starts indexing with your account.
 
 <Image className="mx-auto h-auto w-full max-w-md"
   src="/static/search/confluence-personal-setup.png"
   alt="Confluence personal source setup with a saved account, Atlassian site, and selected spaces"
-  width={501}
-  height={502}
+  width={515}
+  height={345}
 />
 
-Admins manage these sources under **Settings → Sources → Confluence**. When configuring a member-account connection, an **Account for browsing** populates the space picker; a saved personal Search account can be reused here. Choosing a browsing account does not enroll it for Search. Manual space keys work without a browsing account.
+To configure this method as an admin, open **Settings → Sources → Confluence → Add Confluence site** and choose **Sync using → Member accounts**. Enter the site and spaces, then select **Add Confluence site**. **Account for browsing** populates the space picker but does not connect that person to Search; manual space keys work without a browsing account. Teammates then connect from **Integrations**.
 
 ## Using a service account
 
@@ -103,7 +103,7 @@ read:group:confluence
 Use all 12 scopes for account validation, pickers, content, permissions, and directory reads. Central indexing does not need write scopes.
 
 4. Review and create the token, then copy it. Atlassian shows it only once.
-5. In Sim's source form, use **Service account** to add a service account. Paste the **API token**, enter **Site domain** (hostname only), and select **Add service account**. Continue in the source form with the same domain.
+5. In Sim's source form, open **Service account → Add service account**. Paste the **API token**, enter **Site domain** (hostname only), and select **Add service account**. Continue in the source form with the same domain.
 
 <Image className="mx-auto h-auto w-full max-w-md"
   src="/static/credentials/atlassian/admin-auth-type-picker.png"
@@ -132,6 +132,8 @@ Central sources combine space permissions, page and ancestor restrictions, and g
 
 Open **Settings → Sources → Confluence**, then a source's **Documents**, **Settings**, or **Sync history**. Invite teammates through **Settings → Members → Invite** or SSO, then have them connect through **Integrations**. **People → Request connections** only requests a provider connection; it does not invite people to the organization.
 
+Syncing runs automatically. Admins can use **Sync now** for an immediate update, **Pause syncing** to stop scheduled syncs, or **Resume syncing** to restart them. **Full resync**, available for service-account connections, fetches unchanged content again and asks for confirmation. Successful manual syncs have a one-minute cooldown; failed syncs can be retried immediately.
+
 ## Troubleshooting
 
 | Problem | What to check |
@@ -145,7 +147,7 @@ Open **Settings → Sources → Confluence**, then a source's **Documents**, **S
 | Embedded content is missing | Index the referenced page separately; remote macro output is excluded. |
 | **Reconnect** or email mismatch | Authorize with the Atlassian account matching your verified Sim email and grant all requested permissions. |
 
-Open a missing page as the affected teammate. **Share → General access** shows its restrictions; a space admin can also inspect **Space settings → Content → Restricted**. On Premium, **Inspect permissions → Can view** helps locate denied access. Resolve the restriction, then sync again. See Atlassian's [content access](https://support.atlassian.com/confluence-cloud/docs/add-or-remove-page-restrictions/) and [permission inspection](https://support.atlassian.com/confluence-cloud/docs/inspect-a-users-permissions/) guides.
+Open a missing page as the affected teammate, check its space and page restrictions, then sync again after correcting access. See Atlassian's [content access](https://support.atlassian.com/confluence-cloud/docs/add-or-remove-page-restrictions/) and [permission inspection](https://support.atlassian.com/confluence-cloud/docs/inspect-a-users-permissions/) guides.
 
 ## Self-hosted operator setup
 

diff --git a/apps/docs/content/docs/search/connect-your-account.mdx b/apps/docs/content/docs/search/connect-your-account.mdx
@@ -27,7 +27,7 @@ Open **Integrations** in the main sidebar, find the integration, and select **Co
 
 Each integration appears once. Sources that share your account authorization reuse that connection; adding another repository does not require reconnecting. **Connect** appears when authorization is missing, and **Reconnect** appears when an existing account needs renewal. A sync failure alone does not require reconnecting. To add different content, open **More** and select **Add repository**, **Add Confluence site**, or **Add projects**.
 
-<Image className="mx-auto h-auto w-full max-w-xl" src="/static/search/connect-account.png" alt="Organization Integrations with search, personal connections, and Connect actions" width={692} height={409} />
+<Image className="mx-auto h-auto w-full max-w-xl" src="/static/search/connect-account.png" alt="Organization Integrations with search, personal connections, and Connect actions" width={692} height={435} />
 
 </Step>
 <Step>
@@ -78,6 +78,8 @@ Admins manage setup from **Settings → Sources**. Open an integration, then its
 
 Syncing runs automatically. Admins can use **Sync now** when they need an update; another manual run is available 60 seconds after a successful sync finishes. Failed or partial runs can be retried immediately. The connection header also offers **Pause syncing** or **Resume syncing**, and **Remove connection**. Where supported, **Full resync** fetches and reindexes all content and asks for confirmation first.
 
+Removing a Search connection also removes its indexed documents from Sim. The originals remain in the connected app.
+
 ## If you get stuck
 
 | Status | What to do |

diff --git a/apps/docs/content/docs/search/github.mdx b/apps/docs/content/docs/search/github.mdx
@@ -17,6 +17,8 @@ The repository must contain at least one commit. Each person needs a verified Gi
 
 On Sim Cloud, connect through the Sim Search GitHub App in the setup flow below. If you self-host Sim, a deployment administrator must first [configure GitHub Search](/platform/self-hosting/integrations-oauth#github-search).
 
+The App needs read-only access to repository **Contents**, **Metadata**, and account **Email addresses**. No write permissions are needed. These are GitHub App permissions, not a list of OAuth scopes to paste into Sim.
+
 To connect an installation for central indexing, you must be a Sim organization admin and either own the GitHub personal account or be an owner of the GitHub organization where the App is installed. You must also be able to read the repository you add.
 
 ## Add a repository
@@ -37,14 +39,14 @@ In **Sync documents with**, choose **Connect GitHub App** to index through an in
 
 1. Select **Connect your GitHub account** if prompted. Finish authorization in the new tab, then return and select **Refresh**.
 
-<Image className="mx-auto h-auto w-full max-w-md" src="/static/search/github-installation-connect.jpg" alt="Connect GitHub App dialog requiring a personal GitHub connection to verify manageable installations" width={402} height={172} />
+<Image className="mx-auto h-auto w-full max-w-md" src="/static/search/github-installation-connect.jpg" alt="Connect GitHub App dialog requiring a personal GitHub connection to verify manageable installations" width={515} height={234} />
 
 2. Select **Install GitHub App**. Choose your GitHub account or organization and the repositories to include. If it is already installed, check its repository selection.
 3. Return to Sim and select **Refresh**. Choose the installation and select **Use installation**. Only installations on your own account or organizations you own are available.
 
-<Image className="mx-auto h-auto w-full max-w-md" src="/static/search/github-installation-select.jpg" alt="GitHub App installation chooser with Install GitHub App, Refresh, and Use installation controls; account name redacted" width={402} height={180} />
+<Image className="mx-auto h-auto w-full max-w-md" src="/static/search/github-installation-select.jpg" alt="GitHub App installation chooser with Install GitHub App, Refresh, and Use installation controls with an example organization" width={515} height={245} />
 
-The installation is now selected under **Sync documents with**. You can reuse it when adding another repository source in the same Sim organization.
+The installation is now selected under **Sync documents with**. Reuse it when adding another repository in the same Sim organization.
 
 Alternatively, leave **Connected members** selected to use members' accounts for indexing. To use a dedicated indexing account, select it under **Sync documents with**, or choose **Connect GitHub account** to add one. Each method still requires teammates to connect their own accounts for Search access.
 
@@ -71,7 +73,7 @@ Open **More options** if you need a different branch, path or extension filters,
 
 ### Connect your account
 
-Open **Integrations** in the main sidebar, select **Connect** for GitHub, and authorize the App. Teammates repeat this step after joining the Sim organization. For private repositories, both the person's account and the App installation must have access. GitHub also permits App user tokens to read public repositories without an installation; see [GitHub's permission rules](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app).
+Invite teammates through **Settings → Members → Invite** using their Sim email addresses. They accept, then open **Integrations** in the main sidebar, select **Connect** for GitHub, and authorize the App. If GitHub is already connected, they do not need to connect again for each repository. For private repositories, both the person's account and the App installation must have access. GitHub also permits App user tokens to read public repositories without an installation; see [GitHub's permission rules](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app).
 
 An App installation or dedicated indexing account can start syncing after the source is saved. With **Connected members**, indexing begins after someone connects. Each teammate still connects before searching. An existing GitHub connection in the same Sim organization is reused across its GitHub sources.
 
@@ -88,13 +90,12 @@ GitHub App installation access supplies file contents for indexing. Each reader'
 
 For installation-indexed sources, Sim checks the installation's current status and verifies repository content access with the reader's GitHub account before returning results or opening indexed content. If GitHub cannot confirm access, that repository's content is withheld. Removing a person's repository access, disconnecting their account, or removing the repository from the App's access prevents subsequent reads once GitHub reflects the change. File edits still appear after background indexing.
 
-This is an installation plus personal authorization flow. GitHub Search does not impersonate everyone in an email domain. [Google Drive delegation and GitLab administrator indexing](/search#choose-the-right-connection-method) use different supported identity and permission models.
-
 ## Troubleshooting
 
 | Problem | Next step |
 |---|---|
-| GitHub is unavailable in Search | Ask your Sim organization admin to enable GitHub under **Settings → Sources**. For self-hosted Sim, also check the [GitHub App configuration](/platform/self-hosting/integrations-oauth#github-search). |
+| GitHub is missing or deactivated | Ask your Sim organization admin to add GitHub through **Settings → Sources → Add source**, or open its existing Sources row and select **Activate**. |
+| GitHub says it is unavailable in this deployment | Check the [GitHub App configuration](/platform/self-hosting/integrations-oauth#github-search) with your deployment administrator, or contact Sim support on Sim Cloud. Activating the integration cannot fix missing deployment credentials. |
 | Repository cannot be read | Confirm the App is installed on that repository and your GitHub account has access. For SAML organizations, establish your GitHub SSO session before reconnecting. |
 | A teammate cannot authorize the App | Check the GitHub organization's App policies and required approvals. Self-hosted deployments must allow the teammate's account in their App visibility settings. |
 | No eligible installations found | Finish connecting your own GitHub account, install the configured App on your account or an organization you own, then select **Refresh**. An installation of a different App or one you only have repository access to cannot be selected. |