docs(notifications): connect Teams from Nubi's welcome card, and newer Teams behaviour

doc-server/docs/integrations/Notifications/msteams.md

@@ -12,27 +12,45 @@ A [webhook target](./webhook_targets.md) posts notifications through the channel
 
 ## Set up Microsoft Teams
 
-Setup has three steps. The first is done once per workspace; the second once per team.
+Setup has three steps. You add Nubi once per team, and connect your Microsoft tenant once per workspace.
 
-### Step 1. Connect your Microsoft tenant
-
-1. In NudgeBee, go to **Admin → Integrations → Microsoft Teams** and click **Connect**.
-2. Sign in with your Microsoft work account. NudgeBee asks only to sign you in and read your basic profile (`openid`, `profile`, `User.Read`). It gets no access to your directory, chats or channels.
-
-This links your Microsoft 365 tenant to your NudgeBee workspace. A Microsoft tenant can be connected to one NudgeBee workspace at a time.
-
-### Step 2. Add Nubi to your teams
+### Step 1. Add Nubi to your teams
 
 1. In Teams, open **Apps**, search for **Nubi**, and click **Add**.
 2. Choose **Add to a team** and pick the team and channel. Nubi posts a welcome card there.
 3. Repeat for each team that should get notifications.
 
 If your organization manages which apps people can add, a Teams admin allows Nubi once in the **Teams admin center → Teams apps → Manage apps**.
 
+### Step 2. Connect your Microsoft tenant
+
+This links your Microsoft 365 tenant to your NudgeBee workspace. A Microsoft tenant can be connected to one NudgeBee workspace at a time. There are two ways to do it.
+
+#### From Nubi's welcome card (no Microsoft sign-in)
+
+Use this when your organization doesn't let people approve apps that ask them to sign in with Microsoft.
+
+1. On the welcome card Nubi posted in Step 1, click **Connect Microsoft Teams**.
+2. If NudgeBee asks you to sign in, sign in and then click the button on the card again.
+3. NudgeBee shows the team and your workspace. Click **Connect**.
+
+The button only works for someone who meets **both** of these conditions:
+- They **added Nubi to the team**, and are signed in to NudgeBee with the same email address they use to sign in to Microsoft.
+- They are **a NudgeBee admin**, or have a role that can manage messaging integrations.
+
+It works for 7 days. After that, or for anyone else, connect from NudgeBee instead (below).
+
+Some people who add Nubi get a welcome card that points to **Admin → Integrations** instead of a Connect button: guests, personal Microsoft accounts, and accounts on a public email domain or an `onmicrosoft.com` address.
+
+#### From NudgeBee, with Microsoft sign-in
+
+1. In NudgeBee, go to **Admin → Integrations → Microsoft Teams** and click **Connect**.
+2. Sign in with your Microsoft work account. NudgeBee asks only to sign you in and read your basic profile (`openid`, `profile`, `User.Read`). It gets no access to your directory, chats or channels.
+
 ### Step 3. Choose where notifications go
 
 1. In NudgeBee, go to **Admin → Integrations → Microsoft Teams → Channel-Account Mappings**.
-2. Map each channel to the cloud accounts whose alerts it should get. Only teams that have Nubi are listed.
+2. Map each channel to the cloud accounts whose alerts it should get. Only teams that have Nubi are listed. A team's default channel is listed as **General (default channel)**.
 3. Click **Test Notification** to check delivery.
 
 Use [Notification Rules](../../features/notifications.md) to fine-tune which alerts go where.
@@ -43,9 +61,18 @@ Use [Notification Rules](../../features/notifications.md) to fine-tune which ale
 
 ## Using Nubi in Teams
 
-- **Ask a question.** Mention `@Nubi` in a channel or a thread, or message Nubi directly. If you have access to more than one account, Nubi asks which one to use. In a channel mapped to an account, or in an alert's thread, it uses that account straight away.
+- **Ask a question.** Mention `@Nubi` in a channel or a thread, or message Nubi directly. If you have access to more than one account, Nubi asks which one to use. In a channel mapped to an account, it uses that account straight away. In an alert's thread, it always uses the alert's account; if you can't access that account, Nubi tells you instead of answering.
+- **Share a thread.** Each message in a thread is answered as the person who wrote it, with that person's access. Someone without access to the thread's account is told so.
 - **Act on alerts.** Alert cards have **Ask Nubi**, which posts an analysis in the card's thread, and **Suppress…**, which creates a suppression rule. Suppressing needs an account admin role.
-- **Approve workflows.** An approval card has one button per option the automation offers (a choice list and **Submit** when there are more than three). You need edit access to the account. An already-answered request shows *This approval was already answered.*; an expired one shows *This approval request has expired.*
+- **When Ask Nubi can't analyze.** If the alert's last analysis failed, **Ask Nubi** runs it again. When it still can't finish, the thread says why and the card shows *Nubi couldn't analyze this alert*:
+  - the analysis failed: there's a link to the alert, where **Refresh investigation** runs it again;
+  - your workspace's AI budget is used up: see [Budgets and limits](../../features/ai/budgets-and-limits.md#when-a-limit-is-reached);
+  - the alert no longer exists;
+  - Nubi is busy with other alerts.
+
+  An analysis on hold says what it's waiting for. One that is still running after 20 minutes gets a link to follow it in NudgeBee.
+- **Approve workflows.** An approval card has one button per option the automation offers (a choice list and **Submit** when there are more than three). Your click is recorded as you, so you need edit access to the account or permission to run workflows on it. An already-answered request shows *This approval was already answered.*; an expired one shows *This approval request has expired.*
+- **Post a message.** Ask Nubi to post a message to a Teams channel. Nubi shows you the exact message to approve first, then posts it signed *Sent by <your name> via Nubi*. These messages appear in [Delivery history](../../features/notifications.md#delivery-history) as sent from Nubi.
 - **Suppress durations.** **Suppress…** offers this alert for 1 h, 4 h, 24 h or 7 days, or every alert of the type for 4 h, 24 h or 7 days.
 - **Rate answers** with **👍 Helpful** / **👎 Not helpful**. Very long analyses are cut, with a link to the full one in NudgeBee.
 - **Cards expire.** Buttons on a card more than 7 days old no longer work; open the alert in NudgeBee instead.
@@ -104,7 +131,7 @@ MS_TEAMS_BOT_TENANT_ID: The Directory (tenant) ID from Step 1, the bot's home te
 MS_TEAMS_ACTION_SIGNING_KEY: A random string that signs the data on card buttons, for example the output of `openssl rand -hex 32`.
 ```
 
-Without `MS_TEAMS_ACTION_SIGNING_KEY`, cards are sent without buttons. Restart the NudgeBee server pods after updating the secrets.
+Without `MS_TEAMS_ACTION_SIGNING_KEY`, cards are sent without buttons, and the welcome card has no **Connect Microsoft Teams** button, so connect from **Admin → Integrations** instead. Restart the NudgeBee server pods after updating the secrets.
 
 ### Step 4. Create the Teams app package
 
@@ -123,24 +150,34 @@ Then follow [Set up Microsoft Teams](#set-up-microsoft-teams) above.
 
 ### 2. Connect fails with "This Microsoft tenant is already connected to another workspace"
 * **Root Cause**: A Microsoft tenant can be connected to only one NudgeBee workspace.
-* **Remediation**: Disconnect Microsoft Teams in the other workspace first, then connect again.
+* **Remediation**: Disconnect Microsoft Teams in the other workspace first, then connect again. From the welcome card, the same case shows *This Microsoft tenant is connected to another NudgeBee workspace. Contact support to move it.*
 
 ---
 
 ### 3. A team or channel is missing from the channel picker
 * **Root Cause**: Nubi hasn't been added to that team, or the channel is private or shared.
-* **Remediation**: Add Nubi to the team (Step 2), then reload the page. Use a standard channel.
+* **Remediation**: Add Nubi to the team (Step 1), then reload the page. Use a standard channel.
+
+---
+
+### 4. The welcome card's Connect button doesn't connect
+* **Symptom**: After clicking **Connect Microsoft Teams** on Nubi's welcome card, NudgeBee shows one of these:
+  * *This link is for the person who added Nubi to this team.* You're signed in to NudgeBee with a different email from the person who added Nubi. Sign in with their account, or [connect from NudgeBee](#from-nudgebee-with-microsoft-sign-in).
+  * *Only a NudgeBee admin can connect Microsoft Teams.* Ask a NudgeBee admin to connect, or to give you a role that can manage messaging integrations.
+  * *This link has expired.* The button works for 7 days. [Connect from NudgeBee](#from-nudgebee-with-microsoft-sign-in) instead.
+  * *Your workspace changed in another tab.* Click the button on the card again.
+* **No button on the card**: the person who added Nubi is a guest, uses a personal Microsoft account, or uses a public email domain or an `onmicrosoft.com` address. On-prem, the server may also be missing `MS_TEAMS_ACTION_SIGNING_KEY`. [Connect from NudgeBee](#from-nudgebee-with-microsoft-sign-in) instead.
 
 ---
 
-### 4. Sign-In Fails with `Redirect URI Mismatch` (AADSTS50011), on-prem
+### 5. Sign-In Fails with `Redirect URI Mismatch` (AADSTS50011), on-prem
 * **Symptom**: Connecting returns `AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application`.
 * **Root Cause**: The redirect URI in Microsoft Entra ID doesn't match the public HTTPS base URL of your NudgeBee server.
 * **Remediation**: In Entra ID **App registrations → Authentication → Web Redirect URIs**, make sure the URI is exactly `https://<your-nudgebee-server>/api/integrations/ms-teams/callback`, with no trailing slash and the same protocol.
 
 ---
 
-### 5. Notifications Stopped Working / Expired Client Secret, on-prem
+### 6. Notifications Stopped Working / Expired Client Secret, on-prem
 * **Symptom**: Notifications were working but now fail, and the logs show `401 Unauthorized` from Microsoft.
 * **Root Cause**: The app registration's client secret expired.
 * **Remediation**: