improvement(search): simplify integration setup and connection actions (#7761)

* improvement(search): simplify integration connections and sync actions

* improvement(integrations): align setup controls and refresh search guides

* fix(search): expose incomplete connection checks and update setup tests

Author: waleedlatif1

apps/docs/content/docs/search/confluence.mdx

@@ -49,9 +49,9 @@ Open **More options** for content type, labels, and metadata tags. The default i
 
 ### Sync and connect your identity
 
-Select **Connect & Sync** to start indexing. Then open **Integrations** in the main sidebar and select **Connect** on the Confluence source. Authorize the configured site using the Atlassian email matching your verified Sim email.
+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. Integrations shows indexing status and your searchable document count.
+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 allows Confluence, open **Integrations → Connect**. For an existing source, 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 no source exists, or you choose **Connect a different site or content scope**:
+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
 

apps/docs/content/docs/search/connect-your-account.mdx

@@ -23,11 +23,13 @@ For a central Google source, use your primary Workspace email and open **Search*
 
 ## Open Integrations
 
-Open **Integrations** in the main sidebar, find the provider or source, and select **Connect**. First-time setup can also ask which content to index. For [Confluence](/search/confluence) and [Jira](/search/jira), connect your Atlassian account first, then choose the site and spaces or projects and select **Connect & Sync**. [GitHub](/search/github) asks for a repository. If the provider is missing, ask an organization admin to add it under **Settings → Sources → Add source**.
+Open **Integrations** in the main sidebar, find the integration, and select **Connect**. If an admin has configured its content, you only authorize your account. If no source exists yet, [Confluence](/search/confluence) and [Jira](/search/jira) ask you to connect your Atlassian account, choose the site and spaces or projects, and select **Connect & Sync**. [GitHub](/search/github) asks for a repository. If the provider is missing, ask an organization admin to add it under **Settings → Sources → Add source**.
 
-To connect another supported repository, site, or project scope, find the provider row labeled **Connect a different site or content scope** and select **Connect**. Connecting an existing source does not ask you to configure it again.
+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 the row’s actions menu (**…**) 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={704} height={495} />
+If you see **More connections to check**, select **Check connections** to check the next set of sources. Sim shows **Connect** or **Reconnect** when it finds an account that needs authorization.
+
+<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>
@@ -43,7 +45,7 @@ The authorization tab closes when the connection completes and Integrations upda
 
 ## Start searching
 
-The source row shows indexing status and how many documents are available to you. Open **Search** in the organization sidebar and search for something you can already open in the source. Use **Home** to ask the assistant about your connected documents. The first sync may take time, especially for large accounts.
+Your integration row shows its connection and indexing status. Admins manage individual repositories, sites, and other content under **Settings → Sources**. Open **Search** in the organization sidebar and search for something you can already open in the source. Use **Home** to ask the assistant about your connected documents. The first sync may take time, especially for large accounts.
 
 </Step>
 </Steps>
@@ -58,9 +60,9 @@ For a source configured inside a workspace, join that workspace and connect thro
 | GitHub App installation | Connect GitHub once for this Sim organization. The App handles indexing; your account establishes which repositories you may search. |
 | Confluence service account | Connect Confluence to verify your identity; the service account handles the crawl. |
 | Google Workspace service account (Gmail, Calendar, Drive) | No personal connection is needed for that source. Your verified Sim email identifies your mailbox and calendar view, or is matched to Drive permissions. |
-| GitLab instance administrator | No personal connection is needed. Your verified Sim email must match the confirmed primary GitLab email. |
+| GitLab | No personal connection is needed. For an administrator token, your verified Sim email must match your confirmed primary GitLab email. For a non-admin token, it must match the uploaded user mapping and have a project grant. |
 
-Gmail, Calendar, and Drive are separate Search sources. Connecting one Google service does not connect all of them. A central source can be searchable without a personal connection row in **Integrations**.
+Gmail, Calendar, and Drive are separate Search sources. Connecting one Google service does not connect all of them. Central Google and GitLab sources remain searchable without a personal account connection.
 
 ## If you received a connection request
 
@@ -72,10 +74,14 @@ An account connection request does not invite you into the Sim organization. You
 
 ## Manage your connected accounts
 
-On the main **Integrations** page, use **Reconnect** beside an expired connection to renew it. To withdraw an account, open its row's actions menu and select **Disconnect**, then confirm. If several accounts are connected, choose the account to disconnect. Disconnecting stops that account from being used for organization indexing and workflows, and removes Search access that depends on it.
+On the main **Integrations** page, select **Reconnect** beside the integration if your account has expired. To withdraw an account, open its actions menu and select **Disconnect**, then confirm. If several accounts are connected, choose the account to disconnect. Disconnecting stops that account from being used for organization indexing and workflows, and removes Search access that depends on it.
 
 Admins manage setup from **Settings → Sources**. Open an integration, then its connection to see **Documents**, **Settings**, and **Sync history**. **People** shows account contributors across integrations and supports filtering by integration. This does not grant the admin access to every document.
 
+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 |