From 304bffefcf449cc21217c600048f58f0eaf1a2a6 Mon Sep 17 00:00:00 2001
From: George Djabarov <39195835+djabarovgeorge@users.noreply.github.com>
Date: Mon, 4 May 2026 10:49:33 +0300
Subject: [PATCH 1/6] feat(api-service,dashboard): automate MS Teams onboarding
 fixes NV-7387 (#10958)

---
 .../app/agents/agents-webhook.controller.ts   |    2 +-
 .../integrations/integrations.controller.ts   |  204 ++-
 .../azure-setup-oauth-callback.command.ts     |   20 +
 .../azure-setup-oauth-callback.usecase.ts     |  802 +++++++++
 .../msteams-oauth-callback.usecase.spec.ts    |  196 +--
 .../msteams-oauth-callback.usecase.ts         |   57 +-
 .../generate-azure-setup-oauth-url.command.ts |    8 +
 .../generate-azure-setup-oauth-url.usecase.ts |  120 ++
 .../generate-msteams-oauth-url.usecase.ts     |    4 +-
 .../generate-msteams-arm-template.command.ts  |    8 +
 .../generate-msteams-arm-template.usecase.ts  |   87 +
 .../get-msteams-arm-template.usecase.ts       |  250 +++
 .../src/app/integrations/usecases/index.ts    |   10 +
 .../msteams-health-check.command.ts           |   20 +
 .../msteams-health-check.usecase.ts           |  214 +++
 apps/dashboard/src/api/integrations.ts        |   48 +
 .../agents/agent-integrations-tab.tsx         |    3 +-
 .../components/agents/provider-dropdown.tsx   |    8 +-
 .../components/agents/teams-app-package.ts    |   69 +-
 .../components/agents/teams-setup-guide.tsx   | 1494 +++++++++++++++--
 apps/dashboard/src/utils/build-zip.ts         |   69 +
 .../src/utils/build-zip.ts                    |   86 +
 libs/application-generic/src/utils/index.ts   |    3 +-
 .../integration/integration.entity.ts         |   11 +
 .../integration/integration.schema.ts         |   10 +
 packages/shared/src/types/feature-flags.ts    |    2 +
 26 files changed, 3396 insertions(+), 409 deletions(-)
 create mode 100644 apps/api/src/app/integrations/usecases/azure-setup-oauth-callback/azure-setup-oauth-callback.command.ts
 create mode 100644 apps/api/src/app/integrations/usecases/azure-setup-oauth-callback/azure-setup-oauth-callback.usecase.ts
 create mode 100644 apps/api/src/app/integrations/usecases/generate-azure-setup-oauth-url/generate-azure-setup-oauth-url.command.ts
 create mode 100644 apps/api/src/app/integrations/usecases/generate-azure-setup-oauth-url/generate-azure-setup-oauth-url.usecase.ts
 create mode 100644 apps/api/src/app/integrations/usecases/generate-msteams-arm-template/generate-msteams-arm-template.command.ts
 create mode 100644 apps/api/src/app/integrations/usecases/generate-msteams-arm-template/generate-msteams-arm-template.usecase.ts
 create mode 100644 apps/api/src/app/integrations/usecases/generate-msteams-arm-template/get-msteams-arm-template.usecase.ts
 create mode 100644 apps/api/src/app/integrations/usecases/msteams-health-check/msteams-health-check.command.ts
 create mode 100644 apps/api/src/app/integrations/usecases/msteams-health-check/msteams-health-check.usecase.ts
 create mode 100644 apps/dashboard/src/utils/build-zip.ts
 create mode 100644 libs/application-generic/src/utils/build-zip.ts

diff --git a/apps/api/src/app/agents/agents-webhook.controller.ts b/apps/api/src/app/agents/agents-webhook.controller.ts
index 32abbfea6fa..7610d18cbea 100644
--- a/apps/api/src/app/agents/agents-webhook.controller.ts
+++ b/apps/api/src/app/agents/agents-webhook.controller.ts
@@ -94,7 +94,7 @@ export class AgentsWebhookController {
       if (err instanceof HttpException) {
         res.status(err.getStatus()).json(err.getResponse());
       } else {
-        res.status(HttpStatus.INTERNAL_SERVER_ERROR).json({ error: 'Internal server error' });
+        throw err;
       }
     }
   }
diff --git a/apps/api/src/app/integrations/integrations.controller.ts b/apps/api/src/app/integrations/integrations.controller.ts
index 40e7f6fdb66..c21826bdd5e 100644
--- a/apps/api/src/app/integrations/integrations.controller.ts
+++ b/apps/api/src/app/integrations/integrations.controller.ts
@@ -22,6 +22,7 @@ import {
   GetDecryptedIntegrations,
   IntegrationResponseDto,
   OtelSpan,
+  PinoLogger,
   RequirePermissions,
 } from '@novu/application-generic';
 import { CommunityOrganizationRepository } from '@novu/dal';
@@ -55,23 +56,35 @@ import { ChannelTypeLimitDto } from './dtos/get-channel-type-limit.sto';
 import { UpdateIntegrationRequestDto } from './dtos/update-integration.dto';
 import { AutoConfigureIntegrationCommand } from './usecases/auto-configure-integration/auto-configure-integration.command';
 import { AutoConfigureIntegration } from './usecases/auto-configure-integration/auto-configure-integration.usecase';
+import { AzureSetupOauthCallbackCommand } from './usecases/azure-setup-oauth-callback/azure-setup-oauth-callback.command';
+import { AzureSetupOauthCallback } from './usecases/azure-setup-oauth-callback/azure-setup-oauth-callback.usecase';
 import { ChatOauthCallbackCommand } from './usecases/chat-oauth-callback/chat-oauth-callback.command';
 import { ResponseTypeEnum } from './usecases/chat-oauth-callback/chat-oauth-callback.response';
 import { ChatOauthCallback } from './usecases/chat-oauth-callback/chat-oauth-callback.usecase';
 import { CreateIntegrationCommand } from './usecases/create-integration/create-integration.command';
 import { CreateIntegration } from './usecases/create-integration/create-integration.usecase';
+import { GenerateAzureSetupOauthUrlCommand } from './usecases/generate-azure-setup-oauth-url/generate-azure-setup-oauth-url.command';
+import { GenerateAzureSetupOauthUrl } from './usecases/generate-azure-setup-oauth-url/generate-azure-setup-oauth-url.usecase';
 import { GenerateChatOauthUrlCommand } from './usecases/generate-chat-oath-url/generate-chat-oauth-url.command';
 import { GenerateChatOauthUrl } from './usecases/generate-chat-oath-url/generate-chat-oauth-url.usecase';
 import { GenerateConnectOauthUrlCommand } from './usecases/generate-chat-oath-url/generate-connect-oauth-url.command';
 import { GenerateConnectOauthUrl } from './usecases/generate-chat-oath-url/generate-connect-oauth-url.usecase';
 import { GenerateLinkUserOauthUrlCommand } from './usecases/generate-chat-oath-url/generate-link-user-oauth-url.command';
 import { GenerateLinkUserOauthUrl } from './usecases/generate-chat-oath-url/generate-link-user-oauth-url.usecase';
+import { GenerateMsTeamsArmTemplateCommand } from './usecases/generate-msteams-arm-template/generate-msteams-arm-template.command';
+import { GenerateMsTeamsArmTemplate } from './usecases/generate-msteams-arm-template/generate-msteams-arm-template.usecase';
+import { GetMsTeamsArmTemplate } from './usecases/generate-msteams-arm-template/get-msteams-arm-template.usecase';
 import { GetInAppActivatedCommand } from './usecases/get-in-app-activated/get-in-app-activated.command';
 import { GetInAppActivated } from './usecases/get-in-app-activated/get-in-app-activated.usecase';
 import { GetIntegrationsCommand } from './usecases/get-integrations/get-integrations.command';
 import { GetIntegrations } from './usecases/get-integrations/get-integrations.usecase';
 import { GetWebhookSupportStatusCommand } from './usecases/get-webhook-support-status/get-webhook-support-status.command';
 import { GetWebhookSupportStatus } from './usecases/get-webhook-support-status/get-webhook-support-status.usecase';
+import { MsTeamsHealthCheckCommand } from './usecases/msteams-health-check/msteams-health-check.command';
+import {
+  MsTeamsHealthCheck,
+  MsTeamsHealthCheckResult,
+} from './usecases/msteams-health-check/msteams-health-check.usecase';
 import { RemoveIntegrationCommand } from './usecases/remove-integration/remove-integration.command';
 import { RemoveIntegration } from './usecases/remove-integration/remove-integration.usecase';
 import { SetIntegrationAsPrimaryCommand } from './usecases/set-integration-as-primary/set-integration-as-primary.command';
@@ -100,8 +113,16 @@ export class IntegrationsController {
     private generateConnectOauthUrlUsecase: GenerateConnectOauthUrl,
     private generateLinkUserOauthUrlUsecase: GenerateLinkUserOauthUrl,
     private chatOauthCallbackUsecase: ChatOauthCallback,
-    private featureFlagsService: FeatureFlagsService
-  ) {}
+    private featureFlagsService: FeatureFlagsService,
+    private generateMsTeamsArmTemplateUsecase: GenerateMsTeamsArmTemplate,
+    private getMsTeamsArmTemplateUsecase: GetMsTeamsArmTemplate,
+    private generateAzureSetupOauthUrlUsecase: GenerateAzureSetupOauthUrl,
+    private azureSetupOauthCallbackUsecase: AzureSetupOauthCallback,
+    private msTeamsHealthCheckUsecase: MsTeamsHealthCheck,
+    private logger: PinoLogger
+  ) {
+    this.logger.setContext(IntegrationsController.name);
+  }
 
   @Get('/')
   @ApiOkResponse({
@@ -412,6 +433,185 @@ export class IntegrationsController {
     );
   }
 
+  @Get('/:integrationId/msteams-arm-template/deploy-url')
+  @ApiOkResponse({
+    description: 'Signed Azure Portal "Deploy to Azure" URL for the MS Teams ARM template.',
+  })
+  @ApiOperation({
+    summary: 'Get MS Teams ARM template deploy URL',
+    description:
+      'Returns a short-lived signed URL that opens the Azure Portal with a pre-filled ARM template to create the Azure Bot resource and enable the MS Teams channel.',
+  })
+  @ApiExcludeEndpoint()
+  @RequireAuthentication()
+  @RequirePermissions(PermissionsEnum.INTEGRATION_WRITE)
+  async getMsTeamsArmTemplateDeployUrl(
+    @UserSession() user: UserSessionData,
+    @Param('integrationId') integrationId: string
+  ): Promise<{ deployUrl: string }> {
+    return this.generateMsTeamsArmTemplateUsecase.execute(
+      GenerateMsTeamsArmTemplateCommand.create({
+        userId: user._id,
+        organizationId: user.organizationId,
+        integrationId,
+      })
+    );
+  }
+
+  /**
+   * Public endpoint fetched by Azure Portal when the user clicks "Deploy to Azure".
+   * Protected by an HMAC-signed, time-expiring `sig` + `exp` query parameter pair —
+   * no session cookie is available because Azure's servers make this request, not the browser.
+   */
+  @Get('/:integrationId/msteams-arm-template')
+  @ApiExcludeEndpoint()
+  @ApiOperation({ summary: 'Serve MS Teams ARM template JSON (signed)' })
+  async getMsTeamsArmTemplateJson(
+    @Res() res: Response,
+    @Param('integrationId') integrationId: string,
+    @Query('sig') sig: string,
+    @Query('exp') exp: string
+  ): Promise<void> {
+    if (!sig || !exp) {
+      throw new BadRequestException('Missing required parameters: sig, exp');
+    }
+
+    const { template } = await this.getMsTeamsArmTemplateUsecase.execute(integrationId, sig, exp);
+
+    res.setHeader('Content-Type', 'application/json');
+    res.setHeader('Cache-Control', 'no-store');
+    res.send(JSON.stringify(template, null, 2));
+  }
+
+  /**
+   * Quick Setup: generate an Azure AD OAuth URL so Novu can create the App Registration
+   * on the user's behalf via Microsoft Graph.
+   */
+  @Get('/:integrationId/msteams-azure-setup/oauth-url')
+  @ApiOkResponse({
+    description: 'Azure AD OAuth URL for the Quick Setup flow (Novu creates the app registration).',
+  })
+  @ApiOperation({
+    summary: 'Get Azure Quick Setup OAuth URL',
+    description:
+      'Returns an Azure AD OAuth URL that authorizes Novu to create an App Registration and client secret on your behalf via Microsoft Graph.',
+  })
+  @ApiExcludeEndpoint()
+  @RequireAuthentication()
+  @RequirePermissions(PermissionsEnum.INTEGRATION_WRITE)
+  async getAzureSetupOauthUrl(
+    @UserSession() user: UserSessionData,
+    @Param('integrationId') integrationId: string
+  ): Promise<{ url: string }> {
+    const url = await this.generateAzureSetupOauthUrlUsecase.execute(
+      GenerateAzureSetupOauthUrlCommand.create({
+        userId: user._id,
+        organizationId: user.organizationId,
+        environmentId: user.environmentId,
+        integrationId,
+      })
+    );
+
+    return { url };
+  }
+
+  /**
+   * Health-check endpoint polled by the dashboard to determine if the saved MS Teams
+   * credentials, app catalog entry, and Graph permissions are ready after the Quick
+   * Setup OAuth flow.
+   */
+  @Get('/:integrationId/msteams-health')
+  @ApiOkResponse({
+    description: 'Per-checkpoint health status for an MS Teams integration after Quick Setup.',
+  })
+  @ApiOperation({
+    summary: 'Get MS Teams integration health status',
+    description:
+      'Returns the readiness status of the stored MS Teams credentials, app catalog entry, and Graph permissions. Poll this endpoint after the OAuth setup completes to determine when it is safe to proceed to admin consent.',
+  })
+  @ApiExcludeEndpoint()
+  @RequireAuthentication()
+  @RequirePermissions(PermissionsEnum.INTEGRATION_READ)
+  async getMsTeamsHealth(
+    @UserSession() user: UserSessionData,
+    @Param('integrationId') integrationId: string,
+    @Query('checks') checksParam?: string
+  ): Promise<MsTeamsHealthCheckResult> {
+    const checks = checksParam
+      ? checksParam
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : undefined;
+
+    return this.msTeamsHealthCheckUsecase.execute(
+      MsTeamsHealthCheckCommand.create({
+        environmentId: user.environmentId,
+        organizationId: user.organizationId,
+        integrationId,
+        checks,
+      })
+    );
+  }
+
+  /**
+   * Quick Setup callback: Azure AD redirects here after the user authorizes Novu.
+   * Creates the App Registration, secret, and service principal via Graph, saves
+   * credentials to the integration, then attempts to upload the Teams app to the catalog.
+   * Returns a self-closing script that posts a message to the opener tab and closes itself.
+   */
+  @Get('/chat/oauth/azure-setup/callback')
+  @ApiExcludeEndpoint()
+  @ApiOperation({ summary: 'Azure Quick Setup OAuth callback' })
+  async handleAzureSetupOauthCallback(
+    @Res() res: Response,
+    @Query('code') code?: string,
+    @Query('state') state?: string,
+    @Query('error') error?: string,
+    @Query('error_description') errorDescription?: string
+  ): Promise<void> {
+    res.setHeader('Content-Security-Policy', "default-src 'self'; script-src 'self' 'unsafe-inline'");
+
+    if (!state) {
+      res
+        .status(400)
+        .type('html')
+        .send(
+          AzureSetupOauthCallback.buildPopupHtml({
+            success: false,
+            errorMessage: 'Missing required OAuth parameter: state',
+          })
+        );
+
+      return;
+    }
+
+    try {
+      const result = await this.azureSetupOauthCallbackUsecase.execute(
+        AzureSetupOauthCallbackCommand.create({
+          state,
+          code,
+          error,
+          errorDescription,
+        })
+      );
+
+      res.type('html').send(result.html);
+    } catch (err: unknown) {
+      this.logger.error({ err }, 'Azure OAuth callback failed');
+
+      res
+        .status(200)
+        .type('html')
+        .send(
+          AzureSetupOauthCallback.buildPopupHtml({
+            success: false,
+            errorMessage: 'An unexpected error occurred while completing Azure setup.',
+          })
+        );
+    }
+  }
+
   /**
    * @deprecated Use POST /integrations/channel-connections/oauth or POST /integrations/channel-endpoints/oauth instead.
    */
diff --git a/apps/api/src/app/integrations/usecases/azure-setup-oauth-callback/azure-setup-oauth-callback.command.ts b/apps/api/src/app/integrations/usecases/azure-setup-oauth-callback/azure-setup-oauth-callback.command.ts
new file mode 100644
index 00000000000..911552e0d0e
--- /dev/null
+++ b/apps/api/src/app/integrations/usecases/azure-setup-oauth-callback/azure-setup-oauth-callback.command.ts
@@ -0,0 +1,20 @@
+import { BaseCommand } from '@novu/application-generic';
+import { IsNotEmpty, IsOptional, IsString } from 'class-validator';
+
+export class AzureSetupOauthCallbackCommand extends BaseCommand {
+  @IsNotEmpty()
+  @IsString()
+  readonly state: string;
+
+  @IsOptional()
+  @IsString()
+  readonly code?: string;
+
+  @IsOptional()
+  @IsString()
+  readonly error?: string;
+
+  @IsOptional()
+  @IsString()
+  readonly errorDescription?: string;
+}
diff --git a/apps/api/src/app/integrations/usecases/azure-setup-oauth-callback/azure-setup-oauth-callback.usecase.ts b/apps/api/src/app/integrations/usecases/azure-setup-oauth-callback/azure-setup-oauth-callback.usecase.ts
new file mode 100644
index 00000000000..e631970b59b
--- /dev/null
+++ b/apps/api/src/app/integrations/usecases/azure-setup-oauth-callback/azure-setup-oauth-callback.usecase.ts
@@ -0,0 +1,802 @@
+import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
+import { buildZip, createHash, encryptCredentials, PinoLogger } from '@novu/application-generic';
+import { AgentIntegrationRepository, EnvironmentRepository, IntegrationRepository } from '@novu/dal';
+import axios, { AxiosError } from 'axios';
+import {
+  AZURE_SETUP_OAUTH_SCOPES,
+  AzureSetupStateData,
+  GenerateAzureSetupOauthUrl,
+} from '../generate-azure-setup-oauth-url/generate-azure-setup-oauth-url.usecase';
+import { splitOAuthState } from '../generate-chat-oath-url/chat-oauth-state.util';
+import { AzureSetupOauthCallbackCommand } from './azure-setup-oauth-callback.command';
+
+const MS_GRAPH_BASE_URL = 'https://graph.microsoft.com/v1.0';
+const MS_LOGIN_BASE_URL = 'https://login.microsoftonline.com';
+const MS_ARM_BASE_URL = 'https://management.azure.com';
+const MS_ARM_API_VERSION = '2022-09-01';
+const MS_BOT_SERVICE_API_VERSION = '2023-09-15-preview';
+
+/**
+ * Graph permissions required on the customer's bot app registration.
+ * These match what the MS Teams integration manual setup documents.
+ */
+const REQUIRED_GRAPH_PERMISSIONS = [
+  { id: '7ab1d382-f21e-4acd-a863-ba3e13f7da61', type: 'Role' }, // Directory.Read.All
+  { id: '2280dda6-0bfd-44ee-a2f4-cb867cfc4c1e', type: 'Role' }, // Team.ReadBasic.All
+  { id: '59a6b24b-4225-4393-8165-ebaec5f55d7a', type: 'Role' }, // Channel.ReadBasic.All
+  { id: 'e12dae10-5a57-4817-b79d-dfbec5348930', type: 'Role' }, // AppCatalog.Read.All
+  { id: '9f67436c-5415-4e7f-8ac1-3014a7132630', type: 'Role' }, // TeamsAppInstallation.ReadWriteSelfForTeam.All
+  { id: '908de74d-f8b2-4d6b-a9ed-2a17b3b78179', type: 'Role' }, // TeamsAppInstallation.ReadWriteSelfForUser.All
+];
+
+/** Graph resource ID for Microsoft Graph (constant) */
+const GRAPH_RESOURCE_APP_ID = '00000003-0000-0000-c000-000000000000';
+
+export type AzureSetupResult = {
+  /** Script response for the browser popup. Posts a message to the opener and closes the tab. */
+  html: string;
+};
+
+type TokenResponse = {
+  accessToken: string;
+  refreshToken: string | null;
+};
+
+@Injectable()
+export class AzureSetupOauthCallback {
+  constructor(
+    private integrationRepository: IntegrationRepository,
+    private environmentRepository: EnvironmentRepository,
+    private agentIntegrationRepository: AgentIntegrationRepository,
+    private logger: PinoLogger
+  ) {
+    this.logger.setContext(AzureSetupOauthCallback.name);
+  }
+
+  async execute(command: AzureSetupOauthCallbackCommand): Promise<AzureSetupResult> {
+    if (command.error) {
+      this.logger.error(
+        `Azure OAuth callback returned an error: error=${command.error} description=${command.errorDescription ?? 'n/a'}`
+      );
+      throw new BadRequestException(
+        `Azure OAuth error: ${command.error}${command.errorDescription ? ` — ${command.errorDescription}` : ''}`
+      );
+    }
+
+    if (!command.code) {
+      throw new BadRequestException('Missing authorization code from Azure OAuth callback');
+    }
+
+    const stateData = await this.decodeAndVerifyState(command.state);
+
+    this.logger.info(
+      `Azure setup OAuth callback: creating app registration for integrationId=${stateData.integrationId} organizationId=${stateData.organizationId}`
+    );
+
+    const { accessToken, refreshToken } = await this.exchangeCodeForToken(command.code);
+
+    const { appId, secretValue, tenantId } = await this.createAppRegistration(accessToken, stateData);
+
+    this.logger.info(
+      `Azure setup: app registration created appId=${appId} tenantId=${tenantId} integrationId=${stateData.integrationId}`
+    );
+
+    await this.saveCredentials(stateData, appId, secretValue, tenantId);
+
+    this.logger.info(`Azure setup: credentials saved for integrationId=${stateData.integrationId}`);
+
+    await this.tryUploadTeamsApp(accessToken, appId, stateData);
+
+    // Fire-and-forget: deploy the Bot Service via ARM (health-check polling catches readiness)
+    if (refreshToken) {
+      void this.tryDeployBotService(refreshToken, appId, tenantId, stateData).catch((err) => {
+        this.logger.warn(
+          `Azure setup: ARM deployment failed (non-fatal, health check will reflect) integrationId=${stateData.integrationId} error="${this.axiosErrorMessage(err)}" responseBody=${JSON.stringify((err as AxiosError)?.response?.data ?? null)}`
+        );
+      });
+    } else {
+      this.logger.warn(
+        `Azure setup: no refresh token available, skipping ARM deployment integrationId=${stateData.integrationId}`
+      );
+      void this.writeProvisioning(stateData, {
+        status: 'failed',
+        completedAt: new Date().toISOString(),
+        errorMessage: 'No refresh token available — ARM deployment was skipped.',
+      });
+    }
+
+    return { html: AzureSetupOauthCallback.buildPopupHtml({ success: true }) };
+  }
+
+  static buildPopupHtml(_options: { success: boolean; errorMessage?: string }): string {
+    return `<!DOCTYPE html><html><body><script>window.close();\x3c/script></body></html>`;
+  }
+
+  private async decodeAndVerifyState(state: string): Promise<AzureSetupStateData> {
+    let preliminaryData: Partial<AzureSetupStateData>;
+
+    try {
+      const { payload } = splitOAuthState(state);
+      preliminaryData = JSON.parse(payload);
+    } catch {
+      throw new BadRequestException('Invalid Azure setup OAuth state');
+    }
+
+    if (!preliminaryData.environmentId || !preliminaryData.organizationId) {
+      throw new BadRequestException('Azure setup state missing required fields');
+    }
+
+    const environment = await this.environmentRepository.findOne({
+      _id: preliminaryData.environmentId,
+      _organizationId: preliminaryData.organizationId,
+    });
+
+    if (!environment?.apiKeys?.length) {
+      throw new NotFoundException(`Environment ${preliminaryData.environmentId} not found`);
+    }
+
+    const signingKey = environment.apiKeys[0].key;
+
+    try {
+      const { payload, signature } = splitOAuthState(state);
+      const expectedSignature = createHash(signingKey, payload);
+
+      if (signature !== expectedSignature) {
+        throw new Error('Signature mismatch');
+      }
+
+      const data = JSON.parse(payload) as AzureSetupStateData;
+
+      const FIFTEEN_MINUTES = 15 * 60 * 1000;
+
+      if (Date.now() - data.timestamp > FIFTEEN_MINUTES) {
+        throw new Error('State expired');
+      }
+
+      return data;
+    } catch {
+      throw new BadRequestException('Invalid or expired Azure setup OAuth state');
+    }
+  }
+
+  private async exchangeCodeForToken(code: string): Promise<TokenResponse> {
+    const clientId = process.env.NOVU_AZURE_CLIENT_ID;
+    const clientSecret = process.env.NOVU_AZURE_CLIENT_SECRET;
+
+    if (!clientId || !clientSecret) {
+      throw new NotFoundException('Azure Quick Setup is not configured on this Novu instance');
+    }
+
+    const graphScopes = AZURE_SETUP_OAUTH_SCOPES.filter((s) => s.startsWith('https://graph.microsoft.com/')).join(' ');
+
+    const params = new URLSearchParams({
+      grant_type: 'authorization_code',
+      client_id: clientId,
+      client_secret: clientSecret,
+      code,
+      redirect_uri: GenerateAzureSetupOauthUrl.buildRedirectUri(),
+      scope: graphScopes,
+    });
+
+    try {
+      const response = await axios.post<{ access_token: string; refresh_token?: string }>(
+        `${MS_LOGIN_BASE_URL}/organizations/oauth2/v2.0/token`,
+        params.toString(),
+        { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
+      );
+
+      return {
+        accessToken: response.data.access_token,
+        refreshToken: response.data.refresh_token ?? null,
+      };
+    } catch (error) {
+      throw new BadRequestException(`Failed to exchange authorization code: ${this.axiosErrorMessage(error)}`);
+    }
+  }
+
+  /**
+   * Exchanges a refresh token for an Azure Management API access token.
+   * The refresh token is obtained from the initial Graph token exchange (offline_access scope).
+   * Microsoft issues tokens per-resource, so a separate exchange is needed for management.azure.com.
+   */
+  private async exchangeRefreshTokenForManagementToken(refreshToken: string): Promise<string> {
+    const clientId = process.env.NOVU_AZURE_CLIENT_ID;
+    const clientSecret = process.env.NOVU_AZURE_CLIENT_SECRET;
+
+    if (!clientId || !clientSecret) {
+      throw new Error('Azure credentials not configured');
+    }
+
+    const params = new URLSearchParams({
+      grant_type: 'refresh_token',
+      client_id: clientId,
+      client_secret: clientSecret,
+      refresh_token: refreshToken,
+      scope: 'https://management.azure.com/.default offline_access',
+    });
+
+    const response = await axios.post<{ access_token: string }>(
+      `${MS_LOGIN_BASE_URL}/organizations/oauth2/v2.0/token`,
+      params.toString(),
+      { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
+    );
+
+    return response.data.access_token;
+  }
+
+  private async createAppRegistration(
+    accessToken: string,
+    stateData: AzureSetupStateData
+  ): Promise<{ appId: string; secretValue: string; tenantId: string }> {
+    const integration = await this.integrationRepository.findOne({
+      _id: stateData.integrationId,
+      _organizationId: stateData.organizationId,
+    });
+
+    const appName = integration?.name ?? 'Novu Bot';
+
+    const appBody = {
+      displayName: appName,
+      signInAudience: 'AzureADMyOrg',
+      requiredResourceAccess: [
+        {
+          resourceAppId: GRAPH_RESOURCE_APP_ID,
+          resourceAccess: REQUIRED_GRAPH_PERMISSIONS,
+        },
+      ],
+      web: {
+        redirectUris: [GenerateAzureSetupOauthUrl.buildRedirectUri().replace('/azure-setup/callback', '/callback')],
+      },
+    };
+
+    let appObjectId: string;
+    let appId: string;
+
+    try {
+      const appResponse = await axios.post<{ id: string; appId: string }>(
+        `${MS_GRAPH_BASE_URL}/applications`,
+        appBody,
+        { headers: this.graphHeaders(accessToken) }
+      );
+
+      appObjectId = appResponse.data.id;
+      appId = appResponse.data.appId;
+    } catch (error) {
+      throw new BadRequestException(`Failed to create App Registration: ${this.axiosErrorMessage(error)}`);
+    }
+
+    // Create service principal so the app appears in the tenant's app list
+    let tenantId: string;
+    let botServicePrincipalId: string | undefined;
+
+    try {
+      const spResponse = await axios.post<{ id: string; appOwnerOrganizationId: string }>(
+        `${MS_GRAPH_BASE_URL}/servicePrincipals`,
+        { appId },
+        { headers: this.graphHeaders(accessToken) }
+      );
+
+      botServicePrincipalId = spResponse.data.id;
+      tenantId = spResponse.data.appOwnerOrganizationId;
+    } catch (error) {
+      this.logger.warn(`Could not create service principal: ${this.axiosErrorMessage(error)}`);
+      // Attempt to retrieve tenantId via /organization as fallback
+      tenantId = await this.getTenantId(accessToken);
+    }
+
+    // Grant admin consent for all required Graph app roles so they appear as "Granted" in the portal
+    if (botServicePrincipalId) {
+      await this.grantAdminConsent(accessToken, botServicePrincipalId);
+    }
+
+    // Create client secret
+    let secretValue: string;
+
+    try {
+      const secretResponse = await axios.post<{ secretText: string }>(
+        `${MS_GRAPH_BASE_URL}/applications/${appObjectId}/addPassword`,
+        {
+          passwordCredential: {
+            displayName: 'Novu Bot Secret',
+            endDateTime: new Date(Date.now() + 2 * 365 * 24 * 60 * 60 * 1000).toISOString(), // 2 years
+          },
+        },
+        { headers: this.graphHeaders(accessToken) }
+      );
+
+      secretValue = secretResponse.data.secretText;
+    } catch (error) {
+      throw new BadRequestException(`Failed to create client secret: ${this.axiosErrorMessage(error)}`);
+    }
+
+    return { appId, secretValue, tenantId };
+  }
+
+  /**
+   * Grants admin consent for all REQUIRED_GRAPH_PERMISSIONS by creating appRoleAssignments
+   * on the bot's service principal. Without this step the permissions are declared but remain
+   * in the "Not granted" state in the Azure portal.
+   *
+   * Requires the AppRoleAssignment.ReadWrite.All scope, which is already included in
+   * AZURE_SETUP_OAUTH_SCOPES so the delegated access token has the necessary privilege.
+   */
+  private async grantAdminConsent(accessToken: string, botServicePrincipalId: string): Promise<void> {
+    // Resolve the Microsoft Graph service principal id in the customer's tenant
+    let graphServicePrincipalId: string;
+
+    try {
+      const graphSpResponse = await axios.get<{ value: Array<{ id: string }> }>(
+        `${MS_GRAPH_BASE_URL}/servicePrincipals?$filter=appId eq '${GRAPH_RESOURCE_APP_ID}'`,
+        { headers: this.graphHeaders(accessToken) }
+      );
+
+      const graphSp = graphSpResponse.data.value[0];
+
+      if (!graphSp) {
+        this.logger.warn('Could not find Microsoft Graph service principal in tenant — skipping admin consent grant');
+
+        return;
+      }
+
+      graphServicePrincipalId = graphSp.id;
+    } catch (error) {
+      this.logger.warn(`Failed to look up Microsoft Graph service principal: ${this.axiosErrorMessage(error)}`);
+
+      return;
+    }
+
+    // Assign each required app role — failures are non-fatal (e.g. already assigned)
+    for (const perm of REQUIRED_GRAPH_PERMISSIONS) {
+      try {
+        await axios.post(
+          `${MS_GRAPH_BASE_URL}/servicePrincipals/${botServicePrincipalId}/appRoleAssignments`,
+          {
+            principalId: botServicePrincipalId,
+            resourceId: graphServicePrincipalId,
+            appRoleId: perm.id,
+          },
+          { headers: this.graphHeaders(accessToken) }
+        );
+      } catch (error) {
+        this.logger.warn(`Failed to grant app role ${perm.id} (non-fatal): ${this.axiosErrorMessage(error)}`);
+      }
+    }
+
+    this.logger.info(
+      `Admin consent granted for ${REQUIRED_GRAPH_PERMISSIONS.length} Graph permissions on servicePrincipal=${botServicePrincipalId}`
+    );
+  }
+
+  private async getTenantId(accessToken: string): Promise<string> {
+    try {
+      const response = await axios.get<{ value: Array<{ id: string }> }>(`${MS_GRAPH_BASE_URL}/organization`, {
+        headers: this.graphHeaders(accessToken),
+      });
+
+      return response.data.value[0]?.id ?? '';
+    } catch {
+      return '';
+    }
+  }
+
+  private async saveCredentials(
+    stateData: AzureSetupStateData,
+    appId: string,
+    secretValue: string,
+    tenantId: string
+  ): Promise<void> {
+    const credentials = encryptCredentials({
+      clientId: appId,
+      secretKey: secretValue,
+      tenantId,
+    });
+
+    await this.integrationRepository.update(
+      {
+        _id: stateData.integrationId,
+        _organizationId: stateData.organizationId,
+      },
+      { $set: { credentials } }
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // ARM: Bot Service deployment (fire-and-forget, health-check polling detects readiness)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Deploys the Azure Bot resource + MsTeamsChannel into the user's Azure subscription
+   * using the ARM REST API and a management-scoped access token derived from the refresh token.
+   *
+   * Flow:
+   *   1. Exchange refresh token for management.azure.com access token
+   *   2. List subscriptions and pick the first one
+   *   3. Create resource group rg-{botName}
+   *   4. PUT Bot Service (SingleTenant, F0, messaging endpoint = Novu webhook)
+   *   5. PUT MsTeamsChannel on the Bot Service
+   *
+   * Writes integration.provisioning.status throughout so the health-check endpoint
+   * can answer "was the Azure Bot created?" without needing ARM credentials at query time.
+   * All errors are non-fatal — provisioning.status=failed is written and propagation continues.
+   */
+  private async tryDeployBotService(
+    refreshToken: string,
+    appId: string,
+    tenantId: string,
+    stateData: AzureSetupStateData
+  ): Promise<void> {
+    this.logger.info(`Azure setup: starting ARM bot deployment for integrationId=${stateData.integrationId}`);
+
+    await this.writeProvisioning(stateData, { status: 'pending', startedAt: new Date().toISOString() });
+
+    try {
+      let managementToken: string;
+
+      try {
+        managementToken = await this.exchangeRefreshTokenForManagementToken(refreshToken);
+        this.logger.info(`Azure setup: management token acquired integrationId=${stateData.integrationId}`);
+      } catch (error) {
+        throw new Error(
+          `ARM step [exchange-management-token] failed: ${this.axiosErrorMessage(error)} responseBody=${JSON.stringify((error as AxiosError)?.response?.data ?? null)}`
+        );
+      }
+
+      const subscriptionId = await this.getFirstSubscriptionId(managementToken);
+
+      if (!subscriptionId) {
+        this.logger.warn(
+          `Azure setup: no Azure subscription found — marking provisioning failed integrationId=${stateData.integrationId}`
+        );
+        await this.writeProvisioning(stateData, {
+          status: 'failed',
+          completedAt: new Date().toISOString(),
+          errorMessage: 'No enabled Azure subscription found in the account.',
+        });
+
+        return;
+      }
+
+      const integration = await this.integrationRepository.findOne({
+        _id: stateData.integrationId,
+        _organizationId: stateData.organizationId,
+      });
+
+      const botName = this.sanitizeBotName(integration?.name ?? 'NovuBot');
+      const displayName = integration?.name ?? 'Novu Bot';
+      const resourceGroupName = `rg-${botName}`;
+      const webhookEndpoint = await this.resolveWebhookEndpoint(stateData);
+
+      this.logger.info(
+        `Azure setup: ARM parameters integrationId=${stateData.integrationId} subscriptionId=${subscriptionId} resourceGroup=${resourceGroupName} botName=${botName} webhookEndpoint=${webhookEndpoint}`
+      );
+
+      const armHeaders = {
+        Authorization: `Bearer ${managementToken}`,
+        'Content-Type': 'application/json',
+      };
+
+      // 1. Create resource group
+      const rgUrl = `${MS_ARM_BASE_URL}/subscriptions/${subscriptionId}/resourceGroups/${resourceGroupName}?api-version=${MS_ARM_API_VERSION}`;
+
+      try {
+        await axios.put(
+          rgUrl,
+          { location: 'eastus', tags: { 'created-by': 'novu-quick-setup' } },
+          { headers: armHeaders }
+        );
+        this.logger.info(
+          `Azure setup: resource group created/ensured rg=${resourceGroupName} sub=${subscriptionId} integrationId=${stateData.integrationId}`
+        );
+      } catch (error) {
+        throw new Error(
+          `ARM step [create-resource-group] failed url=${rgUrl} error="${this.axiosErrorMessage(error)}" responseBody=${JSON.stringify((error as AxiosError)?.response?.data ?? null)}`
+        );
+      }
+
+      // 2. Create Bot Service
+      const botUrl = `${MS_ARM_BASE_URL}/subscriptions/${subscriptionId}/resourceGroups/${resourceGroupName}/providers/Microsoft.BotService/botServices/${botName}?api-version=${MS_BOT_SERVICE_API_VERSION}`;
+
+      try {
+        await axios.put(
+          botUrl,
+          {
+            location: 'global',
+            kind: 'azurebot',
+            sku: { name: 'F0' },
+            properties: {
+              displayName,
+              endpoint: webhookEndpoint,
+              msaAppId: appId,
+              msaAppTenantId: tenantId,
+              msaAppType: 'SingleTenant',
+            },
+          },
+          { headers: armHeaders }
+        );
+        this.logger.info(
+          `Azure setup: Bot Service created botName=${botName} appId=${appId} tenantId=${tenantId} integrationId=${stateData.integrationId}`
+        );
+      } catch (error) {
+        throw new Error(
+          `ARM step [create-bot-service] failed url=${botUrl} appId=${appId} tenantId=${tenantId} webhookEndpoint=${webhookEndpoint} error="${this.axiosErrorMessage(error)}" responseBody=${JSON.stringify((error as AxiosError)?.response?.data ?? null)}`
+        );
+      }
+
+      // 3. Enable Teams channel
+      const channelUrl = `${MS_ARM_BASE_URL}/subscriptions/${subscriptionId}/resourceGroups/${resourceGroupName}/providers/Microsoft.BotService/botServices/${botName}/channels/MsTeamsChannel?api-version=${MS_BOT_SERVICE_API_VERSION}`;
+
+      try {
+        await axios.put(
+          channelUrl,
+          {
+            location: 'global',
+            kind: 'azurebot',
+            properties: {
+              channelName: 'MsTeamsChannel',
+              location: 'global',
+              properties: { isEnabled: true, enableCalling: false, acceptedTerms: true },
+            },
+          },
+          { headers: armHeaders }
+        );
+        this.logger.info(
+          `Azure setup: Teams channel enabled botName=${botName} integrationId=${stateData.integrationId}`
+        );
+      } catch (error) {
+        throw new Error(
+          `ARM step [enable-teams-channel] failed url=${channelUrl} error="${this.axiosErrorMessage(error)}" responseBody=${JSON.stringify((error as AxiosError)?.response?.data ?? null)}`
+        );
+      }
+
+      await this.writeProvisioning(stateData, { status: 'ready', completedAt: new Date().toISOString() });
+
+      this.logger.info(
+        `Azure setup: ARM deployment complete integrationId=${stateData.integrationId} subscriptionId=${subscriptionId} resourceGroup=${resourceGroupName} botName=${botName}`
+      );
+    } catch (error) {
+      const errorMessage = this.axiosErrorMessage(error);
+
+      this.logger.warn(
+        `Azure setup: ARM deployment failed — marking provisioning failed integrationId=${stateData.integrationId} error="${errorMessage}"`
+      );
+
+      await this.writeProvisioning(stateData, {
+        status: 'failed',
+        completedAt: new Date().toISOString(),
+        errorMessage,
+      });
+
+      throw error;
+    }
+  }
+
+  private async writeProvisioning(
+    stateData: AzureSetupStateData,
+    provisioning: {
+      status: 'pending' | 'ready' | 'failed';
+      startedAt?: string;
+      completedAt?: string;
+      errorMessage?: string;
+      teamsAppCatalogId?: string;
+    }
+  ): Promise<void> {
+    try {
+      /*
+       * Use dot-notation $set so each call only updates the provided fields, not the whole
+       * provisioning sub-document. This preserves teamsAppCatalogId when subsequent calls
+       * (e.g. from tryDeployBotService) update status/completedAt without knowing the catalog ID.
+       */
+      const fields: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(provisioning)) {
+        if (value !== undefined) {
+          fields[`provisioning.${key}`] = value;
+        }
+      }
+
+      await this.integrationRepository.update(
+        { _id: stateData.integrationId, _organizationId: stateData.organizationId },
+        { $set: fields }
+      );
+    } catch (err) {
+      this.logger.warn(
+        `Azure setup: failed to write provisioning state integrationId=${stateData.integrationId} status=${provisioning.status} error="${(err as Error).message}"`
+      );
+    }
+  }
+
+  private async getFirstSubscriptionId(managementToken: string): Promise<string | null> {
+    try {
+      const response = await axios.get<{ value: Array<{ subscriptionId: string; state: string }> }>(
+        `${MS_ARM_BASE_URL}/subscriptions?api-version=${MS_ARM_API_VERSION}`,
+        { headers: { Authorization: `Bearer ${managementToken}` } }
+      );
+
+      const enabled = response.data.value.find((s) => s.state === 'Enabled') ?? response.data.value[0];
+
+      return enabled?.subscriptionId ?? null;
+    } catch (error) {
+      this.logger.warn(`Azure setup: failed to list subscriptions: ${this.axiosErrorMessage(error)}`);
+
+      return null;
+    }
+  }
+
+  private sanitizeBotName(name: string): string {
+    const sanitized = name
+      .toLowerCase()
+      .replace(/[^a-z0-9-]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '')
+      .slice(0, 64);
+
+    return sanitized.length < 2 ? 'novubot' : sanitized;
+  }
+
+  private async resolveWebhookEndpoint(stateData: AzureSetupStateData): Promise<string> {
+    const base = (process.env.API_ROOT_URL ?? 'https://api.novu.co').replace(/\/$/, '');
+
+    const link = await this.agentIntegrationRepository.findOne(
+      {
+        _integrationId: stateData.integrationId,
+        _environmentId: stateData.environmentId,
+        _organizationId: stateData.organizationId,
+      },
+      ['_agentId']
+    );
+
+    if (!link) {
+      return `${base}/v1/agents/unknown/webhook/${stateData.integrationId}`;
+    }
+
+    const integration = await this.integrationRepository.findOne({
+      _id: stateData.integrationId,
+      _organizationId: stateData.organizationId,
+    });
+
+    const integrationIdentifier = integration?.identifier ?? stateData.integrationId;
+
+    return `${base}/v1/agents/${link._agentId}/webhook/${integrationIdentifier}`;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Teams app catalog upload (best-effort, falls back gracefully)
+  // ---------------------------------------------------------------------------
+  /**
+   * Uploads the Teams app zip to the org catalog and returns the catalog's internal app ID,
+   * which differs from the Azure client ID (appId) and is required for the add-to-Teams deep link.
+   * Returns null on failure — the user will need to upload manually.
+   */
+  private async tryUploadTeamsApp(
+    accessToken: string,
+    appId: string,
+    stateData: AzureSetupStateData
+  ): Promise<string | null> {
+    this.logger.info(
+      `Azure setup: attempting automatic Teams app catalog upload for appId=${appId} integrationId=${stateData.integrationId}`
+    );
+
+    try {
+      const integration = await this.integrationRepository.findOne({
+        _id: stateData.integrationId,
+        _organizationId: stateData.organizationId,
+      });
+
+      const zip = await this.buildTeamsAppZip(appId, integration?.name ?? 'Novu Bot');
+
+      const response = await axios.post<{ id: string }>(`${MS_GRAPH_BASE_URL}/appCatalogs/teamsApps`, zip, {
+        headers: {
+          ...this.graphHeaders(accessToken),
+          'Content-Type': 'application/zip',
+        },
+      });
+
+      const catalogId = response.data?.id ?? null;
+
+      this.logger.info(
+        `Azure setup: Teams app uploaded to catalog successfully appId=${appId} catalogId=${catalogId} integrationId=${stateData.integrationId}`
+      );
+
+      if (catalogId) {
+        // Persist the catalog ID so the frontend can build the add-to-Teams deep link.
+        // Only teamsAppCatalogId is written here — status/startedAt are written by tryDeployBotService.
+        await this.writeProvisioning(stateData, {
+          status: 'pending',
+          teamsAppCatalogId: catalogId,
+        });
+      }
+
+      return catalogId;
+    } catch (error) {
+      const message = this.axiosErrorMessage(error);
+      const status =
+        error instanceof Error && 'response' in error
+          ? (error as { response?: { status?: number } }).response?.status
+          : undefined;
+
+      // Permission or policy failure — non-fatal; the user will fall back to manual upload
+      this.logger.warn(
+        `Azure setup: Teams app catalog upload failed (user must upload manually) appId=${appId} integrationId=${stateData.integrationId} httpStatus=${status ?? 'n/a'} error="${message}"`
+      );
+
+      return null;
+    }
+  }
+
+  private async buildTeamsAppZip(appId: string, agentName: string): Promise<Buffer> {
+    const manifest = this.buildManifest(appId, agentName);
+    const manifestBytes = Buffer.from(JSON.stringify(manifest, null, 2), 'utf-8');
+
+    // Minimal 1x1 transparent PNG placeholder icon (smallest valid PNG)
+    const transparentPng = Buffer.from(
+      'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==',
+      'base64'
+    );
+
+    return buildZip([
+      { name: 'manifest.json', data: manifestBytes },
+      { name: 'color.png', data: transparentPng },
+      { name: 'outline.png', data: transparentPng },
+    ]);
+  }
+
+  private buildManifest(appId: string, agentName: string): Record<string, unknown> {
+    const apiBaseUrl = (process.env.API_ROOT_URL ?? 'https://api.novu.co').replace(/\/$/, '');
+    let hostname = 'api.novu.co';
+
+    try {
+      hostname = new URL(apiBaseUrl).hostname;
+    } catch {
+      // keep default
+    }
+
+    return {
+      $schema: 'https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.schema.json',
+      manifestVersion: '1.16',
+      version: '1.0.0',
+      id: appId,
+      developer: {
+        name: 'Your Company',
+        websiteUrl: 'https://your-domain.com',
+        privacyUrl: 'https://your-domain.com/privacy',
+        termsOfUseUrl: 'https://your-domain.com/terms',
+      },
+      name: { short: agentName, full: `${agentName} — powered by Novu` },
+      description: { short: `${agentName} bot`, full: 'A conversational agent powered by Novu.' },
+      icons: { outline: 'outline.png', color: 'color.png' },
+      accentColor: '#FFFFFF',
+      bots: [
+        {
+          botId: appId,
+          scopes: ['personal', 'team', 'groupchat'],
+          supportsFiles: false,
+          isNotificationOnly: false,
+        },
+      ],
+      permissions: ['identity', 'messageTeamMembers'],
+      validDomains: [hostname],
+      webApplicationInfo: { id: appId, resource: `api://${hostname}/${appId}` },
+      authorization: {
+        permissions: {
+          resourceSpecific: [{ name: 'ChannelMessage.Read.Group', type: 'Application' }],
+        },
+      },
+    };
+  }
+
+  private graphHeaders(accessToken: string): Record<string, string> {
+    return {
+      Authorization: `Bearer ${accessToken}`,
+      'Content-Type': 'application/json',
+    };
+  }
+
+  private axiosErrorMessage(error: unknown): string {
+    if (error instanceof AxiosError) {
+      const detail = error.response?.data?.error?.message ?? error.message;
+
+      return detail as string;
+    }
+
+    return error instanceof Error ? error.message : String(error);
+  }
+}
diff --git a/apps/api/src/app/integrations/usecases/chat-oauth-callback/msteams-oauth-callback/msteams-oauth-callback.usecase.spec.ts b/apps/api/src/app/integrations/usecases/chat-oauth-callback/msteams-oauth-callback/msteams-oauth-callback.usecase.spec.ts
index 7b906d8a9dd..afa5dfc46f3 100644
--- a/apps/api/src/app/integrations/usecases/chat-oauth-callback/msteams-oauth-callback/msteams-oauth-callback.usecase.spec.ts
+++ b/apps/api/src/app/integrations/usecases/chat-oauth-callback/msteams-oauth-callback/msteams-oauth-callback.usecase.spec.ts
@@ -10,7 +10,6 @@ import { CreateChannelConnection } from '../../../../channel-connections/usecase
 import { CreateChannelEndpoint } from '../../../../channel-endpoints/usecases/create-channel-endpoint/create-channel-endpoint.usecase';
 import { encodeOAuthState } from '../../generate-chat-oath-url/chat-oauth-state.util';
 import { GenerateMsTeamsOauthUrl } from '../../generate-chat-oath-url/generate-msteams-oath-url/generate-msteams-oauth-url.usecase';
-import { ResponseTypeEnum } from '../chat-oauth-callback.response';
 import { MsTeamsOauthCallbackCommand } from './msteams-oauth-callback.command';
 import { MsTeamsOauthCallback } from './msteams-oauth-callback.usecase';
 
@@ -24,7 +23,6 @@ const MOCK_INTEGRATION_IDENTIFIER = 'msteams-integration';
 const MOCK_SUBSCRIBER_ID = 'subscriber-abc';
 const MOCK_AAD_OID = 'aad-object-id-xyz';
 const MOCK_API_ROOT_URL = 'https://api.novu.co';
-const MOCK_TEAMS_APP_ID = 'teams-internal-app-id';
 
 function buildMockIntegration(overrides: Record<string, unknown> = {}) {
   return {
@@ -85,13 +83,13 @@ describe('MsTeamsOauthCallback', () => {
       environmentRepository as any,
       createChannelConnection as any,
       createChannelEndpoint as any,
-      logger as any,
       msTeamsTokenService as any,
+      logger as any,
       generateMsTeamsOauthUrl as any
     );
 
     originalApiRootUrl = process.env.API_ROOT_URL;
-    process.env.API_ROOT_URL = MOCK_API_ROOT_URL;
+    Reflect.set(process.env, 'API_ROOT_URL', MOCK_API_ROOT_URL);
 
     environmentRepository.findOne.resolves({
       _id: MOCK_ENVIRONMENT_ID,
@@ -99,13 +97,16 @@ describe('MsTeamsOauthCallback', () => {
     } as any);
 
     integrationRepository.findOne.resolves(buildMockIntegration());
-
-    msTeamsTokenService.getGraphToken.resolves('mock-graph-token');
   });
 
   afterEach(() => {
     sinon.restore();
-    process.env.API_ROOT_URL = originalApiRootUrl;
+
+    if (originalApiRootUrl === undefined) {
+      Reflect.deleteProperty(process.env, 'API_ROOT_URL');
+    } else {
+      Reflect.set(process.env, 'API_ROOT_URL', originalApiRootUrl);
+    }
   });
 
   describe('admin consent (connect) mode', () => {
@@ -305,9 +306,6 @@ describe('MsTeamsOauthCallback', () => {
     beforeEach(() => {
       axiosPost = sinon.stub(axios, 'post');
       axiosGet = sinon.stub(axios, 'get');
-
-      axiosGet.resolves({ data: { value: [{ id: MOCK_TEAMS_APP_ID }] } });
-      axiosPost.onSecondCall().resolves({ status: 201, data: {} });
     });
 
     function buildLinkUserState(overrides: Record<string, unknown> = {}) {
@@ -327,8 +325,15 @@ describe('MsTeamsOauthCallback', () => {
       axiosPost.onFirstCall().resolves({ data: { id_token: idToken, access_token: 'at-123' } });
     }
 
-    it('should exchange code, install bot, and create an MS_TEAMS_USER endpoint on success', async () => {
+    function stubBotInstall() {
+      msTeamsTokenService.getGraphToken.resolves('graph-token-123');
+      axiosGet.resolves({ data: { value: [{ id: 'teams-app-id-123' }] } });
+      axiosPost.onSecondCall().resolves({});
+    }
+
+    it('should exchange code, install the bot, and create an MS_TEAMS_USER endpoint on success', async () => {
       stubTokenExchange();
+      stubBotInstall();
       createChannelEndpoint.execute.resolves({ identifier: 'ep-xyz' } as any);
 
       const command = MsTeamsOauthCallbackCommand.create({
@@ -338,124 +343,48 @@ describe('MsTeamsOauthCallback', () => {
 
       await usecase.execute(command);
 
-      expect(msTeamsTokenService.getGraphToken.calledOnce).to.be.true;
-
+      expect(msTeamsTokenService.getGraphToken.calledOnceWith(MOCK_CLIENT_ID, MOCK_SECRET_KEY, MOCK_TENANT_ID)).to.be
+        .true;
       expect(axiosGet.calledOnce).to.be.true;
-      const catalogUrl: string = axiosGet.firstCall.args[0];
-      expect(catalogUrl).to.include('/appCatalogs/teamsApps');
-      expect(catalogUrl).to.include(MOCK_CLIENT_ID);
-
       expect(axiosPost.callCount).to.equal(2);
-      const installUrl: string = axiosPost.secondCall.args[0];
-      expect(installUrl).to.include(`/users/${MOCK_AAD_OID}/teamwork/installedApps`);
 
       expect(createChannelEndpoint.execute.calledOnce).to.be.true;
       const callArg = createChannelEndpoint.execute.firstCall.args[0];
       expect(callArg.type).to.equal(ENDPOINT_TYPES.MS_TEAMS_USER);
-      expect(callArg.endpoint.userId).to.equal(MOCK_AAD_OID);
+      expect((callArg.endpoint as { userId: string }).userId).to.equal(MOCK_AAD_OID);
       expect(callArg.subscriberId).to.equal(MOCK_SUBSCRIBER_ID);
     });
 
-    it('should treat 409 (already installed) as success', async () => {
-      stubTokenExchange();
-      const conflict = Object.assign(new Error('Conflict'), {
-        isAxiosError: true,
-        response: { status: 409, data: {} },
-      });
-      sinon.stub(axios, 'isAxiosError').returns(true);
-      axiosPost.onSecondCall().rejects(conflict);
-      createChannelEndpoint.execute.resolves({ identifier: 'ep-xyz' } as any);
-
-      const command = MsTeamsOauthCallbackCommand.create({
-        providerCode: 'auth-code-abc',
-        state: buildLinkUserState(),
-      });
-
-      const result = await usecase.execute(command);
-
-      expect(createChannelEndpoint.execute.calledOnce).to.be.true;
-      expect(result).to.not.have.property('error');
-    });
-
-    it('should return error HTML and NOT create endpoint when install returns 403', async () => {
-      stubTokenExchange();
-      const forbidden = Object.assign(new Error('Forbidden'), {
-        isAxiosError: true,
-        response: { status: 403, data: {} },
-      });
-      sinon.stub(axios, 'isAxiosError').returns(true);
-      axiosPost.onSecondCall().rejects(forbidden);
-
-      const command = MsTeamsOauthCallbackCommand.create({
-        providerCode: 'auth-code-abc',
-        state: buildLinkUserState(),
-      });
-
-      const result = await usecase.execute(command);
-
-      expect(createChannelEndpoint.execute.called).to.be.false;
-      expect(result.result).to.include('MS Teams Bot Installation Failed');
-      expect(result.result).to.include('TeamsAppInstallation.ReadWriteSelfForUser.All');
-    });
-
-    it('should return error HTML and NOT create endpoint when install returns 404', async () => {
-      stubTokenExchange();
-      const notFound = Object.assign(new Error('Not Found'), {
-        isAxiosError: true,
-        response: { status: 404, data: {} },
-      });
-      sinon.stub(axios, 'isAxiosError').returns(true);
-      axiosPost.onSecondCall().rejects(notFound);
-
-      const command = MsTeamsOauthCallbackCommand.create({
-        providerCode: 'auth-code-abc',
-        state: buildLinkUserState(),
-      });
-
-      const result = await usecase.execute(command);
-
-      expect(createChannelEndpoint.execute.called).to.be.false;
-      expect(result.result).to.include('MS Teams Bot Installation Failed');
-    });
-
-    it('should return error HTML when app catalog returns no results', async () => {
-      stubTokenExchange();
-      axiosGet.resolves({ data: { value: [] } });
+    it('should throw if subscriberId is absent in link_user mode', async () => {
+      const state = buildLinkUserState({ subscriberId: undefined });
 
       const command = MsTeamsOauthCallbackCommand.create({
         providerCode: 'auth-code-abc',
-        state: buildLinkUserState(),
+        state,
       });
 
-      const result = await usecase.execute(command);
-
-      expect(createChannelEndpoint.execute.called).to.be.false;
-      expect(result.result).to.include('MS Teams Bot Installation Failed');
-      expect(result.result).to.include('catalog');
+      try {
+        await usecase.execute(command);
+        expect.fail('Expected an error');
+      } catch (err) {
+        expect(err).to.be.instanceOf(BadRequestException);
+        expect((err as BadRequestException).message).to.include('subscriberId is required for link_user mode');
+      }
     });
 
-    it('should return error HTML when catalog lookup returns 403', async () => {
-      stubTokenExchange();
-      const forbidden = Object.assign(new Error('Forbidden'), {
-        isAxiosError: true,
-        response: { status: 403, data: {} },
-      });
-      sinon.stub(axios, 'isAxiosError').returns(true);
-      axiosGet.rejects(forbidden);
-
-      const command = MsTeamsOauthCallbackCommand.create({
-        providerCode: 'auth-code-abc',
-        state: buildLinkUserState(),
-      });
-
-      const result = await usecase.execute(command);
+    it('should throw if providerCode is missing in link_user mode', async () => {
+      const command = MsTeamsOauthCallbackCommand.create({ state: buildLinkUserState() });
 
-      expect(createChannelEndpoint.execute.called).to.be.false;
-      expect(result.result).to.include('MS Teams Bot Installation Failed');
-      expect(result.result).to.include('AppCatalog.Read.All');
+      try {
+        await usecase.execute(command);
+        expect.fail('Expected an error');
+      } catch (err) {
+        expect(err).to.be.instanceOf(BadRequestException);
+        expect((err as BadRequestException).message).to.include('Missing authorization code for link_user mode');
+      }
     });
 
-    it('should return error HTML when id_token is missing from token response', async () => {
+    it('should throw if id_token is missing from token response', async () => {
       axiosPost.onFirstCall().resolves({ data: { access_token: 'at-123' } });
 
       const command = MsTeamsOauthCallbackCommand.create({
@@ -463,13 +392,16 @@ describe('MsTeamsOauthCallback', () => {
         state: buildLinkUserState(),
       });
 
-      const result = await usecase.execute(command);
-
-      expect(createChannelEndpoint.execute.called).to.be.false;
-      expect(result.result).to.include('MS Teams Bot Installation Failed');
+      try {
+        await usecase.execute(command);
+        expect.fail('Expected an error');
+      } catch (err) {
+        expect(err).to.be.instanceOf(BadRequestException);
+        expect((err as BadRequestException).message).to.include('missing id_token');
+      }
     });
 
-    it('should return error HTML when oid claim is absent from id_token', async () => {
+    it('should throw if oid claim is absent from id_token', async () => {
       const idToken = buildIdToken({ sub: 'sub-123', tid: MOCK_TENANT_ID });
       axiosPost.onFirstCall().resolves({ data: { id_token: idToken, access_token: 'at-123' } });
 
@@ -478,33 +410,13 @@ describe('MsTeamsOauthCallback', () => {
         state: buildLinkUserState(),
       });
 
-      const result = await usecase.execute(command);
-
-      expect(createChannelEndpoint.execute.called).to.be.false;
-      expect(result.result).to.include('MS Teams Bot Installation Failed');
-    });
-
-    it('should throw if subscriberId is absent in link_user mode', async () => {
-      const state = buildLinkUserState({ subscriberId: undefined });
-
-      const command = MsTeamsOauthCallbackCommand.create({
-        providerCode: 'auth-code-abc',
-        state,
-      });
-
-      const result = await usecase.execute(command);
-
-      expect(result.type).to.equal(ResponseTypeEnum.HTML);
-      expect(result.result).to.include('subscriberId is required for link_user mode');
-    });
-
-    it('should throw if providerCode is missing in link_user mode', async () => {
-      const command = MsTeamsOauthCallbackCommand.create({ state: buildLinkUserState() });
-
-      const result = await usecase.execute(command);
-
-      expect(result.type).to.equal(ResponseTypeEnum.HTML);
-      expect(result.result).to.include('Missing authorization code for link_user mode');
+      try {
+        await usecase.execute(command);
+        expect.fail('Expected an error');
+      } catch (err) {
+        expect(err).to.be.instanceOf(BadRequestException);
+        expect((err as BadRequestException).message).to.include('oid claim');
+      }
     });
   });
 });
diff --git a/apps/api/src/app/integrations/usecases/chat-oauth-callback/msteams-oauth-callback/msteams-oauth-callback.usecase.ts b/apps/api/src/app/integrations/usecases/chat-oauth-callback/msteams-oauth-callback/msteams-oauth-callback.usecase.ts
index 4bf4b826724..92cec0ce007 100644
--- a/apps/api/src/app/integrations/usecases/chat-oauth-callback/msteams-oauth-callback/msteams-oauth-callback.usecase.ts
+++ b/apps/api/src/app/integrations/usecases/chat-oauth-callback/msteams-oauth-callback/msteams-oauth-callback.usecase.ts
@@ -34,14 +34,18 @@ export class MsTeamsOauthCallback {
     private environmentRepository: EnvironmentRepository,
     private createChannelConnection: CreateChannelConnection,
     private createChannelEndpoint: CreateChannelEndpoint,
-    private logger: PinoLogger,
     private msTeamsTokenService: MsTeamsTokenService,
+    private logger: PinoLogger,
     private generateMsTeamsOauthUrl: GenerateMsTeamsOauthUrl
   ) {
     this.logger.setContext(MsTeamsOauthCallback.name);
   }
 
   async execute(command: MsTeamsOauthCallbackCommand): Promise<ChatOauthCallbackResult> {
+    this.logger.info(
+      `MS Teams OAuth callback received: mode=${command.adminConsent ? 'admin_consent' : 'link_user'} tenant=${command.tenant ?? 'n/a'}`
+    );
+
     const stateData = await this.decodeMsTeamsState(command.state);
     const integration = await this.getIntegration(stateData);
     const credentials = await this.getIntegrationCredentials(integration);
@@ -50,16 +54,23 @@ export class MsTeamsOauthCallback {
       try {
         await this.linkUserEndpoint(command, stateData, integration, credentials);
       } catch (error) {
-        const message =
-          error instanceof Error ? error.message : 'An unexpected error occurred during bot installation.';
+        const message = error instanceof Error ? error.message : String(error);
 
-        return {
-          type: ResponseTypeEnum.HTML,
-          result: this.buildErrorHtml(message),
-        };
+        if (message.includes('MS Teams bot installation failed')) {
+          return { type: ResponseTypeEnum.HTML, result: this.buildErrorHtml(message) };
+        }
+
+        throw error;
       }
+
+      this.logger.info(
+        `MS Teams link_user completed successfully: subscriberId=${stateData.subscriberId} integrationId=${integration._id}`
+      );
     } else {
       await this.createAdminConsentConnection(command, stateData, integration);
+      this.logger.info(
+        `MS Teams admin consent connection created: tenant=${command.tenant} integrationId=${integration._id} identifier=${stateData.identifier}`
+      );
 
       /*
        * After admin consent, if autoLinkUser is explicitly true and a subscriberId is
@@ -174,15 +185,21 @@ export class MsTeamsOauthCallback {
   private async installBotForUser(oid: string, credentials: ICredentialsEntity): Promise<void> {
     const { clientId, secretKey, tenantId } = credentials;
 
+    this.logger.info(`MS Teams bot install: acquiring graph token for clientId=${clientId} tenantId=${tenantId}`);
+
     const graphToken = await this.msTeamsTokenService.getGraphToken(
       clientId as string,
       secretKey as string,
       tenantId as string
     );
 
+    this.logger.info(`MS Teams bot install: resolving Teams app catalog ID for clientId=${clientId}`);
     const teamsAppId = await this.resolveTeamsAppId(graphToken, clientId as string);
 
+    this.logger.info(`MS Teams bot install: installing app teamsAppId=${teamsAppId} for userOid=${oid}`);
     await this.installAppForUser(graphToken, oid, teamsAppId);
+
+    this.logger.info(`MS Teams bot install: app installed successfully for userOid=${oid} teamsAppId=${teamsAppId}`);
   }
 
   private async resolveTeamsAppId(graphToken: string, azureClientId: string): Promise<string> {
@@ -208,9 +225,8 @@ export class MsTeamsOauthCallback {
     } catch (error) {
       if (axios.isAxiosError(error) && error.response?.status === 403) {
         throw new BadRequestException(
-          'MS Teams bot installation failed: missing Azure permissions. ' +
-            'Please grant AppCatalog.Read.All and TeamsAppInstallation.ReadWriteSelfForUser.All ' +
-            'application permissions in Azure Portal and re-run admin consent.'
+          'MS Teams bot installation failed: missing AppCatalog.Read.All permission. ' +
+            'Please grant AppCatalog.Read.All application permission in Azure Portal and re-run admin consent.'
         );
       }
 
@@ -257,14 +273,16 @@ export class MsTeamsOauthCallback {
         const status = error.response?.status;
 
         if (status === 409) {
+          this.logger.info(
+            `MS Teams bot install: app already installed for userOid=${userOid} (409 conflict — skipping)`
+          );
+
           return;
         }
 
         if (status === 403) {
           throw new BadRequestException(
-            'MS Teams bot installation failed: missing Azure permissions. ' +
-              'Please grant TeamsAppInstallation.ReadWriteSelfForUser.All ' +
-              'application permission in Azure Portal and re-run admin consent.'
+            'MS Teams bot installation failed: the TeamsAppInstallation.ReadWriteSelfForUser.All permission has not yet propagated.'
           );
         }
 
@@ -290,6 +308,16 @@ export class MsTeamsOauthCallback {
       .replace(/"/g, '&quot;')
       .replace(/'/g, '&#39;');
 
+    const isPermissionError =
+      message.includes('TeamsAppInstallation.ReadWriteSelfForUser.All') || message.includes('AppCatalog.Read.All');
+    const cachingNote = isPermissionError
+      ? `
+  <div class="cache-note">
+    <strong>Azure permission changes may take time to propagate.</strong>
+    If you have already granted the required permissions, Azure AD can take up to <strong>60 minutes</strong> to apply the changes. Wait a few minutes and then try to <strong>Link Teams Identity</strong> again.
+  </div>`
+      : '';
+
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -300,12 +328,13 @@ export class MsTeamsOauthCallback {
     .error-box { background: #fff3f3; border: 1px solid #f5c6c6; border-radius: 8px; padding: 1.5rem; max-width: 560px; }
     h2 { margin: 0 0 0.75rem; color: #c0392b; font-size: 1.1rem; }
     p { margin: 0; line-height: 1.5; }
+    .cache-note { margin-top: 1rem; padding: 0.75rem 1rem; background: #fffbe6; border: 1px solid #ffe58f; border-radius: 6px; font-size: 0.9rem; line-height: 1.5; color: #7a5c00; }
   </style>
 </head>
 <body>
   <div class="error-box">
     <h2>MS Teams Bot Installation Failed</h2>
-    <p>${escaped}</p>
+    <p>${escaped}</p>${cachingNote}
   </div>
 </body>
 </html>`;
diff --git a/apps/api/src/app/integrations/usecases/generate-azure-setup-oauth-url/generate-azure-setup-oauth-url.command.ts b/apps/api/src/app/integrations/usecases/generate-azure-setup-oauth-url/generate-azure-setup-oauth-url.command.ts
new file mode 100644
index 00000000000..a89de67bafb
--- /dev/null
+++ b/apps/api/src/app/integrations/usecases/generate-azure-setup-oauth-url/generate-azure-setup-oauth-url.command.ts
@@ -0,0 +1,8 @@
+import { IsNotEmpty, IsString } from 'class-validator';
+import { EnvironmentWithUserCommand } from '../../../shared/commands/project.command';
+
+export class GenerateAzureSetupOauthUrlCommand extends EnvironmentWithUserCommand {
+  @IsNotEmpty()
+  @IsString()
+  readonly integrationId: string;
+}
diff --git a/apps/api/src/app/integrations/usecases/generate-azure-setup-oauth-url/generate-azure-setup-oauth-url.usecase.ts b/apps/api/src/app/integrations/usecases/generate-azure-setup-oauth-url/generate-azure-setup-oauth-url.usecase.ts
new file mode 100644
index 00000000000..151bba66d97
--- /dev/null
+++ b/apps/api/src/app/integrations/usecases/generate-azure-setup-oauth-url/generate-azure-setup-oauth-url.usecase.ts
@@ -0,0 +1,120 @@
+import { Injectable, NotFoundException, UnauthorizedException } from '@nestjs/common';
+import { createHash } from '@novu/application-generic';
+import { EnvironmentRepository, IntegrationRepository } from '@novu/dal';
+import { ChatProviderIdEnum } from '@novu/shared';
+import { encodeOAuthState } from '../generate-chat-oath-url/chat-oauth-state.util';
+import { GenerateAzureSetupOauthUrlCommand } from './generate-azure-setup-oauth-url.command';
+
+/**
+ * Azure AD OAuth scopes for Novu to create an App Registration on behalf of the user.
+ *
+ * Application.ReadWrite.All is required because Application.ReadWrite.OwnedBy does not
+ * exist as a delegated permission — it is application-only. The delegated equivalent for
+ * creating app registrations via Graph is Application.ReadWrite.All, which requires
+ * admin consent on the customer's tenant.
+ */
+export const AZURE_SETUP_OAUTH_SCOPES = [
+  'openid',
+  'profile',
+  'offline_access',
+  'https://graph.microsoft.com/Application.ReadWrite.All',
+  'https://graph.microsoft.com/AppRoleAssignment.ReadWrite.All',
+  'https://graph.microsoft.com/AppCatalog.ReadWrite.All',
+  'https://management.azure.com/user_impersonation',
+] as const;
+
+export type AzureSetupStateData = {
+  integrationId: string;
+  environmentId: string;
+  organizationId: string;
+  userId: string;
+  timestamp: number;
+};
+
+@Injectable()
+export class GenerateAzureSetupOauthUrl {
+  private readonly AZURE_AUTHORIZE_URL = 'https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize';
+
+  constructor(
+    private integrationRepository: IntegrationRepository,
+    private environmentRepository: EnvironmentRepository
+  ) {}
+
+  async execute(command: GenerateAzureSetupOauthUrlCommand): Promise<string> {
+    const integration = await this.integrationRepository.findOne({
+      _id: command.integrationId,
+      _organizationId: command.organizationId,
+    });
+
+    if (!integration) {
+      throw new NotFoundException(`Integration ${command.integrationId} not found`);
+    }
+
+    if (integration.providerId !== ChatProviderIdEnum.MsTeams) {
+      throw new UnauthorizedException('Azure setup OAuth is only supported for MS Teams integrations');
+    }
+
+    const signingKey = await this.getEnvironmentApiKey(command.environmentId);
+
+    const stateData: AzureSetupStateData = {
+      integrationId: command.integrationId,
+      environmentId: command.environmentId,
+      organizationId: command.organizationId,
+      userId: command.userId,
+      timestamp: Date.now(),
+    };
+
+    const payload = JSON.stringify(stateData);
+    const signature = createHash(signingKey, payload);
+
+    if (!signature) {
+      throw new Error('Failed to create OAuth state signature');
+    }
+
+    const secureState = encodeOAuthState(payload, signature);
+
+    const params = new URLSearchParams({
+      client_id: this.getNovuAzureClientId(),
+      response_type: 'code',
+      redirect_uri: GenerateAzureSetupOauthUrl.buildRedirectUri(),
+      scope: AZURE_SETUP_OAUTH_SCOPES.join(' '),
+      state: secureState,
+      response_mode: 'query',
+      prompt: 'consent',
+    });
+
+    return `${this.AZURE_AUTHORIZE_URL}?${params.toString()}`;
+  }
+
+  static buildRedirectUri(): string {
+    if (!process.env.API_ROOT_URL) {
+      throw new Error('API_ROOT_URL environment variable is required');
+    }
+
+    const base = process.env.API_ROOT_URL.replace(/\/$/, '');
+
+    return `${base}/v1/integrations/chat/oauth/azure-setup/callback`;
+  }
+
+  private getNovuAzureClientId(): string {
+    const clientId = process.env.NOVU_AZURE_CLIENT_ID;
+
+    if (!clientId) {
+      throw new NotFoundException(
+        'Azure Quick Setup is not configured on this Novu instance (NOVU_AZURE_CLIENT_ID missing)'
+      );
+    }
+
+    return clientId;
+  }
+
+  private async getEnvironmentApiKey(environmentId: string): Promise<string> {
+    const apiKeys = await this.environmentRepository.getApiKeys(environmentId);
+
+    if (!apiKeys.length) {
+      throw new NotFoundException(`Environment ${environmentId} not found`);
+    }
+
+    return apiKeys[0].key;
+  }
+}
diff --git a/apps/api/src/app/integrations/usecases/generate-chat-oath-url/generate-msteams-oath-url/generate-msteams-oauth-url.usecase.ts b/apps/api/src/app/integrations/usecases/generate-chat-oath-url/generate-msteams-oath-url/generate-msteams-oauth-url.usecase.ts
index 129538f86e1..eead5978140 100644
--- a/apps/api/src/app/integrations/usecases/generate-chat-oath-url/generate-msteams-oath-url/generate-msteams-oauth-url.usecase.ts
+++ b/apps/api/src/app/integrations/usecases/generate-chat-oath-url/generate-msteams-oath-url/generate-msteams-oauth-url.usecase.ts
@@ -33,7 +33,7 @@ export class GenerateMsTeamsOauthUrl {
    * - Messages sent as bot/app identity, not as user
    * - Requires application permissions configured in Azure app registration:
    *   Team.ReadBasic.All, Channel.ReadBasic.All, AppCatalog.Read.All,
-   *   TeamsAppInstallation.ReadWriteSelfForTeam.All, TeamsAppInstallation.ReadWriteSelfForUser.All
+   *   TeamsAppInstallation.ReadWriteSelfForTeam.All
    */
   private readonly MS_TEAMS_ADMIN_CONSENT_URL = 'https://login.microsoftonline.com/organizations/v2.0/adminconsent?';
 
@@ -191,8 +191,8 @@ export class GenerateMsTeamsOauthUrl {
     if (!process.env.API_ROOT_URL) {
       throw new Error('API_ROOT_URL environment variable is required');
     }
-
     const baseUrl = process.env.API_ROOT_URL.replace(/\/$/, ''); // Remove trailing slash
+
     return `${baseUrl}${CHAT_OAUTH_CALLBACK_PATH}`;
   }
 
diff --git a/apps/api/src/app/integrations/usecases/generate-msteams-arm-template/generate-msteams-arm-template.command.ts b/apps/api/src/app/integrations/usecases/generate-msteams-arm-template/generate-msteams-arm-template.command.ts
new file mode 100644
index 00000000000..0109113b643
--- /dev/null
+++ b/apps/api/src/app/integrations/usecases/generate-msteams-arm-template/generate-msteams-arm-template.command.ts
@@ -0,0 +1,8 @@
+import { IsNotEmpty, IsString } from 'class-validator';
+import { OrganizationCommand } from '../../../shared/commands/organization.command';
+
+export class GenerateMsTeamsArmTemplateCommand extends OrganizationCommand {
+  @IsNotEmpty()
+  @IsString()
+  readonly integrationId: string;
+}
diff --git a/apps/api/src/app/integrations/usecases/generate-msteams-arm-template/generate-msteams-arm-template.usecase.ts b/apps/api/src/app/integrations/usecases/generate-msteams-arm-template/generate-msteams-arm-template.usecase.ts
new file mode 100644
index 00000000000..140e107280f
--- /dev/null
+++ b/apps/api/src/app/integrations/usecases/generate-msteams-arm-template/generate-msteams-arm-template.usecase.ts
@@ -0,0 +1,87 @@
+import { Injectable, NotFoundException, UnauthorizedException } from '@nestjs/common';
+import { GetDecryptedIntegrations } from '@novu/application-generic';
+import { EnvironmentRepository, IntegrationRepository } from '@novu/dal';
+import { ChatProviderIdEnum } from '@novu/shared';
+import { createHmac } from 'crypto';
+import { GenerateMsTeamsArmTemplateCommand } from './generate-msteams-arm-template.command';
+
+const ARM_TEMPLATE_EXPIRY_MS = 15 * 60 * 1000; // 15 minutes
+
+export type MsTeamsArmTemplateResult = {
+  /** Signed URL the dashboard can hand to the Azure Portal "Deploy to Azure" button */
+  deployUrl: string;
+};
+
+@Injectable()
+export class GenerateMsTeamsArmTemplate {
+  constructor(
+    private integrationRepository: IntegrationRepository,
+    private environmentRepository: EnvironmentRepository
+  ) {}
+
+  async execute(command: GenerateMsTeamsArmTemplateCommand): Promise<MsTeamsArmTemplateResult> {
+    const integration = await this.integrationRepository.findOne({
+      _id: command.integrationId,
+      _organizationId: command.organizationId,
+    });
+
+    if (!integration) {
+      throw new NotFoundException(`Integration ${command.integrationId} not found`);
+    }
+
+    if (integration.providerId !== ChatProviderIdEnum.MsTeams) {
+      throw new UnauthorizedException('ARM template is only supported for MS Teams integrations');
+    }
+
+    const decrypted = GetDecryptedIntegrations.getDecryptedCredentials(integration);
+    const { clientId: appId } = decrypted.credentials as Record<string, string>;
+
+    if (!appId) {
+      throw new NotFoundException('MS Teams integration missing App ID (clientId). Configure credentials first.');
+    }
+
+    const apiKeys = await this.environmentRepository.getApiKeys(integration._environmentId);
+
+    if (!apiKeys.length) {
+      throw new NotFoundException(`Environment for integration ${command.integrationId} not found`);
+    }
+
+    const signingKey = apiKeys[0].key;
+    const exp = Date.now() + ARM_TEMPLATE_EXPIRY_MS;
+
+    const payload = `${command.integrationId}:${exp}`;
+    const sig = createHmac('sha256', signingKey).update(payload).digest('hex');
+
+    const templateApiUrl = this.buildTemplateApiUrl(command.integrationId, sig, exp);
+    const deployUrl = `https://portal.azure.com/#create/Microsoft.Template/uri/${encodeURIComponent(templateApiUrl)}`;
+
+    return { deployUrl };
+  }
+
+  /**
+   * Validates a signed ARM template URL request.
+   * Returns the decoded integrationId on success, throws on failure.
+   *
+   * The route that serves the raw ARM JSON must call this before returning template content.
+   */
+  static async verifySignature(integrationId: string, sig: string, exp: string, signingKey: string): Promise<void> {
+    const expMs = Number(exp);
+
+    if (!Number.isFinite(expMs) || Date.now() > expMs) {
+      throw new UnauthorizedException('ARM template link has expired');
+    }
+
+    const payload = `${integrationId}:${expMs}`;
+    const expected = createHmac('sha256', signingKey).update(payload).digest('hex');
+
+    if (sig !== expected) {
+      throw new UnauthorizedException('Invalid ARM template signature');
+    }
+  }
+
+  private buildTemplateApiUrl(integrationId: string, sig: string, exp: number): string {
+    const base = (process.env.API_ROOT_URL ?? '').replace(/\/$/, '');
+
+    return `${base}/v1/integrations/${integrationId}/msteams-arm-template?sig=${sig}&exp=${exp}`;
+  }
+}
diff --git a/apps/api/src/app/integrations/usecases/generate-msteams-arm-template/get-msteams-arm-template.usecase.ts b/apps/api/src/app/integrations/usecases/generate-msteams-arm-template/get-msteams-arm-template.usecase.ts
new file mode 100644
index 00000000000..427acadbbeb
--- /dev/null
+++ b/apps/api/src/app/integrations/usecases/generate-msteams-arm-template/get-msteams-arm-template.usecase.ts
@@ -0,0 +1,250 @@
+import { Injectable, NotFoundException, UnauthorizedException } from '@nestjs/common';
+import { GetDecryptedIntegrations } from '@novu/application-generic';
+import { AgentIntegrationRepository, EnvironmentRepository, IntegrationRepository } from '@novu/dal';
+import { ChatProviderIdEnum } from '@novu/shared';
+import { GenerateMsTeamsArmTemplate } from './generate-msteams-arm-template.usecase';
+
+export type GetMsTeamsArmTemplateResult = {
+  template: Record<string, unknown>;
+};
+
+@Injectable()
+export class GetMsTeamsArmTemplate {
+  constructor(
+    private integrationRepository: IntegrationRepository,
+    private environmentRepository: EnvironmentRepository,
+    private agentIntegrationRepository: AgentIntegrationRepository
+  ) {}
+
+  async execute(integrationId: string, sig: string, exp: string): Promise<GetMsTeamsArmTemplateResult> {
+    /**
+     * Internal lookup by _id only — bypasses the EnforceEnvOrOrgIds constraint.
+     * Use only in contexts where the caller has already verified authorization
+     * through another mechanism (e.g. HMAC signature validation).
+     */
+    // @ts-expect-error EnforceEnvOrOrgIds: _id-only query is intentional here (see comment above).
+    const integration = await this.integrationRepository.findOne({ _id: integrationId });
+
+    if (!integration) {
+      throw new NotFoundException(`Integration ${integrationId} not found`);
+    }
+
+    if (integration.providerId !== ChatProviderIdEnum.MsTeams) {
+      throw new UnauthorizedException('ARM template is only supported for MS Teams integrations');
+    }
+
+    const apiKeys = await this.environmentRepository.getApiKeys(integration._environmentId);
+
+    if (!apiKeys.length) {
+      throw new NotFoundException(`Environment for integration ${integrationId} not found`);
+    }
+
+    await GenerateMsTeamsArmTemplate.verifySignature(integrationId, sig, exp, apiKeys[0].key);
+
+    const decrypted = GetDecryptedIntegrations.getDecryptedCredentials(integration);
+    const credentials = decrypted.credentials as Record<string, string>;
+    const appId = credentials.clientId ?? '';
+    const tenantId = credentials.tenantId ?? '';
+
+    const botName = this.sanitizeBotName(integration.name ?? 'NovuBot');
+    const displayName = integration.name ?? 'Novu Bot';
+    const agentId = await this.resolveLinkedAgentId(
+      integrationId,
+      integration._environmentId,
+      integration._organizationId
+    );
+    const endpoint = this.buildWebhookUrl(agentId, integration.identifier);
+
+    return { template: buildArmTemplate({ appId, tenantId, botName, displayName, endpoint }) };
+  }
+
+  /**
+   * Webhook routing resolves the agent via `findByIdForWebhook` — the path segment must be the agent document `_id`,
+   * not the human-readable `identifier` (same as the dashboard manual Teams setup instructions).
+   */
+  private async resolveLinkedAgentId(
+    integrationId: string,
+    environmentId: string,
+    organizationId: string
+  ): Promise<string | null> {
+    const link = await this.agentIntegrationRepository.findOne(
+      {
+        _integrationId: integrationId,
+        _environmentId: environmentId,
+        _organizationId: organizationId,
+      },
+      ['_agentId']
+    );
+
+    return link?._agentId ?? null;
+  }
+
+  private sanitizeBotName(name: string): string {
+    // Azure Bot resource names: 2-64 chars, alphanumeric and hyphens only
+    const sanitized = name
+      .toLowerCase()
+      .replace(/[^a-z0-9-]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '')
+      .slice(0, 64);
+
+    if (sanitized.length < 2) {
+      return 'bot';
+    }
+
+    return sanitized;
+  }
+
+  private buildWebhookUrl(agentId: string | null, integrationIdentifier: string): string {
+    const base = (process.env.API_ROOT_URL ?? '').replace(/\/$/, '');
+
+    if (!agentId) {
+      return `${base}/v1/agents/unknown/webhook/${integrationIdentifier}`;
+    }
+
+    return `${base}/v1/agents/${agentId}/webhook/${integrationIdentifier}`;
+  }
+}
+
+/**
+ * Builds a subscription-scoped ARM template that:
+ *   1. Creates a dedicated resource group (rg-{botName}) if it does not exist.
+ *   2. Deploys into that resource group:
+ *        - Microsoft.BotService/botServices  (SingleTenant Azure Bot, F0 free tier)
+ *        - Microsoft.BotService/botServices/channels/MsTeamsChannel  (Teams channel enabled)
+ *
+ * Using the subscription schema allows resource-group creation in a single "Deploy to Azure" click.
+ * Parameters with defaultValue are pre-filled so the Azure Portal form needs minimal manual input.
+ * The template contains NO secrets — appId is public, endpoint is a webhook URL.
+ */
+function buildArmTemplate({
+  appId,
+  tenantId,
+  botName,
+  displayName,
+  endpoint,
+}: {
+  appId: string;
+  tenantId: string;
+  botName: string;
+  displayName: string;
+  endpoint: string;
+}): Record<string, unknown> {
+  const resourceGroupName = `rg-${botName}`;
+
+  return {
+    $schema: 'https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#',
+    contentVersion: '1.0.0.0',
+    parameters: {
+      resourceGroupName: {
+        type: 'string',
+        defaultValue: resourceGroupName,
+        metadata: { description: 'Name of the resource group to create or use for the Azure Bot resources.' },
+      },
+      location: {
+        type: 'string',
+        defaultValue: 'eastus',
+        metadata: { description: 'Azure region for the resource group and bot resources.' },
+      },
+      botName: {
+        type: 'string',
+        defaultValue: botName,
+        metadata: { description: 'Resource name for the Azure Bot (2-64 chars, alphanumeric and hyphens).' },
+      },
+      displayName: {
+        type: 'string',
+        defaultValue: displayName,
+        metadata: { description: 'Human-readable display name for the bot.' },
+      },
+      msaAppId: {
+        type: 'string',
+        defaultValue: appId,
+        metadata: { description: 'The App ID (client ID) from your Azure App Registration.' },
+      },
+      msaAppTenantId: {
+        type: 'string',
+        defaultValue: tenantId,
+        metadata: { description: 'The Tenant ID of your Azure AD tenant.' },
+      },
+      botEndpoint: {
+        type: 'string',
+        defaultValue: endpoint,
+        metadata: { description: 'The messaging endpoint URL for your Novu agent webhook.' },
+      },
+    },
+    resources: [
+      {
+        type: 'Microsoft.Resources/resourceGroups',
+        apiVersion: '2022-09-01',
+        name: "[parameters('resourceGroupName')]",
+        location: "[parameters('location')]",
+        properties: {},
+      },
+      {
+        type: 'Microsoft.Resources/deployments',
+        apiVersion: '2022-09-01',
+        name: 'botDeployment',
+        resourceGroup: "[parameters('resourceGroupName')]",
+        dependsOn: ["[resourceId('Microsoft.Resources/resourceGroups', parameters('resourceGroupName'))]"],
+        properties: {
+          mode: 'Incremental',
+          expressionEvaluationOptions: { scope: 'inner' },
+          parameters: {
+            botName: { value: "[parameters('botName')]" },
+            displayName: { value: "[parameters('displayName')]" },
+            msaAppId: { value: "[parameters('msaAppId')]" },
+            msaAppTenantId: { value: "[parameters('msaAppTenantId')]" },
+            botEndpoint: { value: "[parameters('botEndpoint')]" },
+            location: { value: "[parameters('location')]" },
+          },
+          template: {
+            $schema: 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#',
+            contentVersion: '1.0.0.0',
+            parameters: {
+              botName: { type: 'string' },
+              displayName: { type: 'string' },
+              msaAppId: { type: 'string' },
+              msaAppTenantId: { type: 'string' },
+              botEndpoint: { type: 'string' },
+              location: { type: 'string' },
+            },
+            resources: [
+              {
+                type: 'Microsoft.BotService/botServices',
+                apiVersion: '2023-09-15-preview',
+                name: "[parameters('botName')]",
+                location: 'global',
+                kind: 'azurebot',
+                sku: { name: 'F0' },
+                properties: {
+                  displayName: "[parameters('displayName')]",
+                  endpoint: "[parameters('botEndpoint')]",
+                  msaAppId: "[parameters('msaAppId')]",
+                  msaAppTenantId: "[parameters('msaAppTenantId')]",
+                  msaAppType: 'SingleTenant',
+                },
+              },
+              {
+                type: 'Microsoft.BotService/botServices/channels',
+                apiVersion: '2023-09-15-preview',
+                name: "[concat(parameters('botName'), '/MsTeamsChannel')]",
+                location: 'global',
+                kind: 'azurebot',
+                dependsOn: ["[resourceId('Microsoft.BotService/botServices', parameters('botName'))]"],
+                properties: {
+                  channelName: 'MsTeamsChannel',
+                  location: 'global',
+                  properties: {
+                    isEnabled: true,
+                    enableCalling: false,
+                    acceptedTerms: true,
+                  },
+                },
+              },
+            ],
+          },
+        },
+      },
+    ],
+  };
+}
diff --git a/apps/api/src/app/integrations/usecases/index.ts b/apps/api/src/app/integrations/usecases/index.ts
index 1cf2ebe3111..0834e69314a 100644
--- a/apps/api/src/app/integrations/usecases/index.ts
+++ b/apps/api/src/app/integrations/usecases/index.ts
@@ -7,6 +7,7 @@ import {
   SelectIntegration,
 } from '@novu/application-generic';
 import { AutoConfigureIntegration } from './auto-configure-integration/auto-configure-integration.usecase';
+import { AzureSetupOauthCallback } from './azure-setup-oauth-callback/azure-setup-oauth-callback.usecase';
 import { ChatOauthCallback } from './chat-oauth-callback/chat-oauth-callback.usecase';
 import { MsTeamsOauthCallback } from './chat-oauth-callback/msteams-oauth-callback/msteams-oauth-callback.usecase';
 import { SlackOauthCallback } from './chat-oauth-callback/slack-oauth-callback/slack-oauth-callback.usecase';
@@ -14,14 +15,18 @@ import { CheckIntegration } from './check-integration/check-integration.usecase'
 import { CheckIntegrationEMail } from './check-integration/check-integration-email.usecase';
 import { CreateIntegration } from './create-integration/create-integration.usecase';
 import { CreateNovuIntegrations } from './create-novu-integrations/create-novu-integrations.usecase';
+import { GenerateAzureSetupOauthUrl } from './generate-azure-setup-oauth-url/generate-azure-setup-oauth-url.usecase';
 import { GenerateChatOauthUrl } from './generate-chat-oath-url/generate-chat-oauth-url.usecase';
 import { GenerateConnectOauthUrl } from './generate-chat-oath-url/generate-connect-oauth-url.usecase';
 import { GenerateLinkUserOauthUrl } from './generate-chat-oath-url/generate-link-user-oauth-url.usecase';
 import { GenerateMsTeamsOauthUrl } from './generate-chat-oath-url/generate-msteams-oath-url/generate-msteams-oauth-url.usecase';
 import { GenerateSlackOauthUrl } from './generate-chat-oath-url/generate-slack-oath-url/generate-slack-oauth-url.usecase';
+import { GenerateMsTeamsArmTemplate } from './generate-msteams-arm-template/generate-msteams-arm-template.usecase';
+import { GetMsTeamsArmTemplate } from './generate-msteams-arm-template/get-msteams-arm-template.usecase';
 import { GetInAppActivated } from './get-in-app-activated/get-in-app-activated.usecase';
 import { GetIntegrations } from './get-integrations/get-integrations.usecase';
 import { GetWebhookSupportStatus } from './get-webhook-support-status/get-webhook-support-status.usecase';
+import { MsTeamsHealthCheck } from './msteams-health-check/msteams-health-check.usecase';
 import { RemoveIntegration } from './remove-integration/remove-integration.usecase';
 import { SetIntegrationAsPrimary } from './set-integration-as-primary/set-integration-as-primary.usecase';
 import { UpdateIntegration } from './update-integration/update-integration.usecase';
@@ -49,7 +54,12 @@ export const USE_CASES = [
   GenerateLinkUserOauthUrl,
   GenerateSlackOauthUrl,
   GenerateMsTeamsOauthUrl,
+  GenerateMsTeamsArmTemplate,
+  GetMsTeamsArmTemplate,
+  AzureSetupOauthCallback,
+  GenerateAzureSetupOauthUrl,
   SlackOauthCallback,
   MsTeamsOauthCallback,
   ChatOauthCallback,
+  MsTeamsHealthCheck,
 ];
diff --git a/apps/api/src/app/integrations/usecases/msteams-health-check/msteams-health-check.command.ts b/apps/api/src/app/integrations/usecases/msteams-health-check/msteams-health-check.command.ts
new file mode 100644
index 00000000000..8680fbc9125
--- /dev/null
+++ b/apps/api/src/app/integrations/usecases/msteams-health-check/msteams-health-check.command.ts
@@ -0,0 +1,20 @@
+import { IsArray, IsNotEmpty, IsOptional, IsString } from 'class-validator';
+import { EnvironmentCommand } from '../../../shared/commands/project.command';
+
+export class MsTeamsHealthCheckCommand extends EnvironmentCommand {
+  @IsNotEmpty()
+  @IsString()
+  readonly integrationId: string;
+
+  /**
+   * Optional list of check names to run. When provided, only the listed checks execute;
+   * the rest are returned as `null` ("not requested").
+   * When omitted, all checks run (backward-compatible).
+   *
+   * Valid values: 'appRegistration' | 'azureBotCreated' | 'teamsAppCatalog' | 'permissions'
+   */
+  @IsOptional()
+  @IsArray()
+  @IsString({ each: true })
+  readonly checks?: string[];
+}
diff --git a/apps/api/src/app/integrations/usecases/msteams-health-check/msteams-health-check.usecase.ts b/apps/api/src/app/integrations/usecases/msteams-health-check/msteams-health-check.usecase.ts
new file mode 100644
index 00000000000..f914fb4ee85
--- /dev/null
+++ b/apps/api/src/app/integrations/usecases/msteams-health-check/msteams-health-check.usecase.ts
@@ -0,0 +1,214 @@
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { GetDecryptedIntegrations, MsTeamsTokenService, PinoLogger } from '@novu/application-generic';
+import { IntegrationEntity, IntegrationRepository } from '@novu/dal';
+import { ChatProviderIdEnum } from '@novu/shared';
+import axios from 'axios';
+import { MsTeamsHealthCheckCommand } from './msteams-health-check.command';
+
+export type HealthCheckStatus = 'ready' | 'pending' | 'failed';
+
+export interface MsTeamsHealthCheckResult {
+  appRegistration: HealthCheckStatus | null;
+  azureBotCreated: HealthCheckStatus | null;
+  teamsAppCatalog: HealthCheckStatus | null;
+  permissions: HealthCheckStatus | null;
+  allReady: boolean;
+}
+
+/**
+ * Verifies the MS Teams integration using credentials and provisioning state stored on the integration.
+ *
+ * Checkpoints:
+ *   1. appRegistration — bot can acquire a Graph token (app registration + secret work)
+ *   2. azureBotCreated — Azure Bot resource was successfully created via ARM during Quick Setup
+ *                        (reads integration.provisioning.status; missing -> pending because manual setup is untracked)
+ *   3. teamsAppCatalog — app found in org catalog via Graph (AppCatalog.Read.All)
+ *   4. permissions     — required appRoleAssignments present on the service principal
+ *
+ * Status meanings:
+ *   ready   — check passed
+ *   pending — transient failure (token error, 404) — likely Azure propagation delay
+ *   failed  — permanent failure (no credentials, misconfiguration)
+ */
+@Injectable()
+export class MsTeamsHealthCheck {
+  private readonly MS_GRAPH_BASE_URL = 'https://graph.microsoft.com/v1.0';
+
+  /**
+   * The Graph app roles we expect to find granted on the bot's service principal.
+   * These match REQUIRED_GRAPH_PERMISSIONS in azure-setup-oauth-callback.usecase.ts.
+   */
+  private readonly EXPECTED_ROLE_IDS = new Set([
+    '7ab1d382-f21e-4acd-a863-ba3e13f7da61', // Directory.Read.All
+    '2280dda6-0bfd-44ee-a2f4-cb867cfc4c1e', // Team.ReadBasic.All
+    '59a6b24b-4225-4393-8165-ebaec5f55d7a', // Channel.ReadBasic.All
+    'e12dae10-5a57-4817-b79d-dfbec5348930', // AppCatalog.Read.All
+    '9f67436c-5415-4e7f-8ac1-3014a7132630', // TeamsAppInstallation.ReadWriteSelfForTeam.All
+    '908de74d-f8b2-4d6b-a9ed-2a17b3b78179', // TeamsAppInstallation.ReadWriteSelfForUser.All
+  ]);
+
+  constructor(
+    private integrationRepository: IntegrationRepository,
+    private msTeamsTokenService: MsTeamsTokenService,
+    private logger: PinoLogger
+  ) {
+    this.logger.setContext(MsTeamsHealthCheck.name);
+  }
+
+  async execute(command: MsTeamsHealthCheckCommand): Promise<MsTeamsHealthCheckResult> {
+    const integration = await this.integrationRepository.findOne({
+      _id: command.integrationId,
+      _environmentId: command.environmentId,
+      _organizationId: command.organizationId,
+    });
+
+    if (!integration) {
+      throw new NotFoundException(`Integration ${command.integrationId} not found`);
+    }
+
+    if (integration.providerId !== ChatProviderIdEnum.MsTeams) {
+      throw new NotFoundException('Health check is only supported for MS Teams integrations');
+    }
+
+    const decrypted = GetDecryptedIntegrations.getDecryptedCredentials(integration);
+    const credentials = decrypted.credentials as Record<string, string>;
+    const clientId = credentials.clientId ?? '';
+    const secretKey = credentials.secretKey ?? '';
+    const tenantId = credentials.tenantId ?? '';
+
+    if (!clientId || !secretKey || !tenantId) {
+      const failedStatus = (name: string): HealthCheckStatus | null =>
+        !command.checks || command.checks.includes(name) ? 'failed' : null;
+
+      return {
+        appRegistration: failedStatus('appRegistration'),
+        azureBotCreated: failedStatus('azureBotCreated'),
+        teamsAppCatalog: failedStatus('teamsAppCatalog'),
+        permissions: failedStatus('permissions'),
+        allReady: false,
+      };
+    }
+
+    const shouldRun = (name: string): boolean => !command.checks || command.checks.includes(name);
+
+    // Run only the requested checks in parallel — skipped checks resolve to null immediately
+    const [appRegistration, azureBotCreated, teamsAppCatalog, permissions] = await Promise.all([
+      shouldRun('appRegistration') ? this.checkAppRegistration(clientId, secretKey, tenantId) : Promise.resolve(null),
+      shouldRun('azureBotCreated') ? Promise.resolve(this.checkAzureBotCreated(integration)) : Promise.resolve(null),
+      shouldRun('teamsAppCatalog') ? this.checkTeamsAppCatalog(clientId, secretKey, tenantId) : Promise.resolve(null),
+      shouldRun('permissions') ? this.checkPermissions(clientId, secretKey, tenantId) : Promise.resolve(null),
+    ]);
+
+    // allReady only considers non-null (requested) fields
+    const allReady = [appRegistration, azureBotCreated, teamsAppCatalog, permissions]
+      .filter((s) => s !== null)
+      .every((s) => s === 'ready');
+
+    this.logger.debug(
+      `Health check result integrationId=${command.integrationId} appRegistration=${appRegistration} azureBotCreated=${azureBotCreated} teamsAppCatalog=${teamsAppCatalog} permissions=${permissions} allReady=${allReady}`
+    );
+
+    return { appRegistration, azureBotCreated, teamsAppCatalog, permissions, allReady };
+  }
+
+  /**
+   * Check 1: Can the bot acquire a Graph token?
+   * If yes, the App Registration, client secret, and service principal all work.
+   */
+  private async checkAppRegistration(
+    clientId: string,
+    secretKey: string,
+    tenantId: string
+  ): Promise<HealthCheckStatus> {
+    try {
+      const token = await this.msTeamsTokenService.getGraphToken(clientId, secretKey, tenantId);
+
+      return token ? 'ready' : 'pending';
+    } catch (error) {
+      this.logger.warn(`Health check: appRegistration failed clientId=${clientId} error="${(error as Error).message}"`);
+
+      return 'pending';
+    }
+  }
+
+  /**
+   * Check 2: Was the Azure Bot resource created during Quick Setup?
+   * Reads integration.provisioning.status written by tryDeployBotService.
+   * Missing provisioning means Quick Setup has not produced a tracked Azure Bot deployment.
+   */
+  private checkAzureBotCreated(integration: IntegrationEntity): HealthCheckStatus {
+    return integration.provisioning?.status ?? 'pending';
+  }
+
+  /**
+   * Check 3: Is the Teams app published to the org catalog?
+   * Queries Graph for the app by externalId (the bot's clientId) with org distribution.
+   */
+  private async checkTeamsAppCatalog(
+    clientId: string,
+    secretKey: string,
+    tenantId: string
+  ): Promise<HealthCheckStatus> {
+    try {
+      const graphToken = await this.msTeamsTokenService.getGraphToken(clientId, secretKey, tenantId);
+
+      if (!graphToken) {
+        return 'pending';
+      }
+
+      const filter = encodeURIComponent(`externalId eq '${clientId}' and distributionMethod eq 'organization'`);
+      const response = await axios.get<{ value: unknown[] }>(
+        `${this.MS_GRAPH_BASE_URL}/appCatalogs/teamsApps?$filter=${filter}`,
+        { headers: { Authorization: `Bearer ${graphToken}` }, timeout: 10_000 }
+      );
+
+      return response.data.value.length > 0 ? 'ready' : 'pending';
+    } catch (error) {
+      this.logger.warn(`Health check: teamsAppCatalog failed clientId=${clientId} error="${(error as Error).message}"`);
+
+      return 'pending';
+    }
+  }
+
+  /**
+   * Check 4: Are the required Graph appRoleAssignments propagated on the service principal?
+   * Looks up the SP by appId then checks its appRoleAssignments.
+   */
+  private async checkPermissions(clientId: string, secretKey: string, tenantId: string): Promise<HealthCheckStatus> {
+    try {
+      const graphToken = await this.msTeamsTokenService.getGraphToken(clientId, secretKey, tenantId);
+
+      if (!graphToken) {
+        return 'pending';
+      }
+
+      // Resolve service principal for the bot's app
+      const spFilter = encodeURIComponent(`appId eq '${clientId}'`);
+      const spResponse = await axios.get<{ value: Array<{ id: string }> }>(
+        `${this.MS_GRAPH_BASE_URL}/servicePrincipals?$filter=${spFilter}&$select=id`,
+        { headers: { Authorization: `Bearer ${graphToken}` }, timeout: 10_000 }
+      );
+
+      const spId = spResponse.data.value[0]?.id;
+
+      if (!spId) {
+        return 'pending';
+      }
+
+      // Check appRoleAssignments on the service principal
+      const assignmentsResponse = await axios.get<{ value: Array<{ appRoleId: string }> }>(
+        `${this.MS_GRAPH_BASE_URL}/servicePrincipals/${spId}/appRoleAssignments`,
+        { headers: { Authorization: `Bearer ${graphToken}` }, timeout: 10_000 }
+      );
+
+      const grantedRoleIds = new Set(assignmentsResponse.data.value.map((a) => a.appRoleId));
+      const allGranted = [...this.EXPECTED_ROLE_IDS].every((id) => grantedRoleIds.has(id));
+
+      return allGranted ? 'ready' : 'pending';
+    } catch (error) {
+      this.logger.warn(`Health check: permissions failed clientId=${clientId} error="${(error as Error).message}"`);
+
+      return 'pending';
+    }
+  }
+}
diff --git a/apps/dashboard/src/api/integrations.ts b/apps/dashboard/src/api/integrations.ts
index cc7676cb02c..878287e99bc 100644
--- a/apps/dashboard/src/api/integrations.ts
+++ b/apps/dashboard/src/api/integrations.ts
@@ -1,6 +1,16 @@
 import { ChannelTypeEnum, IEnvironment, IIntegration } from '@novu/shared';
 import { del, get, post, put } from './api.client';
 
+export type HealthCheckStatus = 'ready' | 'pending' | 'failed';
+
+export type MsTeamsHealthCheckResult = {
+  appRegistration: HealthCheckStatus | null;
+  azureBotCreated: HealthCheckStatus | null;
+  teamsAppCatalog: HealthCheckStatus | null;
+  permissions: HealthCheckStatus | null;
+  allReady: boolean;
+};
+
 export type CreateIntegrationData = {
   providerId: string;
   channel: ChannelTypeEnum;
@@ -80,3 +90,41 @@ export async function updateIntegration(integrationId: string, data: UpdateInteg
     environment: environment,
   });
 }
+
+export async function getMsTeamsArmTemplateDeployUrl(
+  integrationId: string,
+  environment: IEnvironment
+): Promise<{ deployUrl: string }> {
+  const { data } = await get<{ data: { deployUrl: string } }>(
+    `/integrations/${integrationId}/msteams-arm-template/deploy-url`,
+    { environment }
+  );
+
+  return data;
+}
+
+export async function getAzureSetupOauthUrl(
+  integrationId: string,
+  environment: IEnvironment
+): Promise<{ url: string }> {
+  const { data } = await get<{ data: { url: string } }>(
+    `/integrations/${integrationId}/msteams-azure-setup/oauth-url`,
+    { environment }
+  );
+
+  return data;
+}
+
+export async function getMsTeamsHealthCheck(
+  integrationId: string,
+  environment: IEnvironment,
+  checks?: string[]
+): Promise<MsTeamsHealthCheckResult> {
+  const params = checks?.length ? `?checks=${checks.join(',')}` : '';
+  const { data } = await get<{ data: MsTeamsHealthCheckResult }>(
+    `/integrations/${integrationId}/msteams-health${params}`,
+    { environment }
+  );
+
+  return data;
+}
diff --git a/apps/dashboard/src/components/agents/agent-integrations-tab.tsx b/apps/dashboard/src/components/agents/agent-integrations-tab.tsx
index cb5a77a6eb2..4615316b43d 100644
--- a/apps/dashboard/src/components/agents/agent-integrations-tab.tsx
+++ b/apps/dashboard/src/components/agents/agent-integrations-tab.tsx
@@ -13,9 +13,9 @@ import {
 } from '@/api/agents';
 import { NovuApiError } from '@/api/api.client';
 import { ProviderIcon } from '@/components/integrations/components/provider-icon';
+import { InlineToast } from '@/components/primitives/inline-toast';
 import { Skeleton } from '@/components/primitives/skeleton';
 import { showErrorToast, showSuccessToast } from '@/components/primitives/sonner-helpers';
-import { InlineToast } from '@/components/primitives/inline-toast';
 import { requireEnvironment, useEnvironment } from '@/context/environment/hooks';
 import { useHasPermission } from '@/hooks/use-has-permission';
 import { useTelemetry } from '@/hooks/use-telemetry';
@@ -489,6 +489,7 @@ export function AgentIntegrationsTab({ agent, integrationIdentifier }: AgentInte
                 {!readOnly && (
                   <ProviderDropdown
                     agentIdentifier={agent.identifier}
+                    agentName={agent.name}
                     selectedIntegrationId={selectedIntegration?.integration._id}
                     linkedIntegrationIds={linkedIntegrationIdSet}
                     excludeLinked
diff --git a/apps/dashboard/src/components/agents/provider-dropdown.tsx b/apps/dashboard/src/components/agents/provider-dropdown.tsx
index d769a0f8ecf..202d39c4690 100644
--- a/apps/dashboard/src/components/agents/provider-dropdown.tsx
+++ b/apps/dashboard/src/components/agents/provider-dropdown.tsx
@@ -1,4 +1,5 @@
 import {
+  ChannelTypeEnum,
   CONVERSATIONAL_PROVIDERS,
   type ConversationalProvider,
   EmailProviderIdEnum,
@@ -58,6 +59,8 @@ type ProviderDropdownProps = {
   fallbackProviderId?: string;
   onSelect: (providerId: string, integration?: IIntegration) => void;
   agentIdentifier: string;
+  /** Agent display name — used to derive the integration name for chat providers (e.g. "My Agent Bot"). */
+  agentName?: string;
   /** Integration IDs already linked to the agent — selecting one of these skips the link API call. */
   linkedIntegrationIds?: Set<string>;
   /** When true, hide integrations whose _id is in `linkedIntegrationIds` from the list. */
@@ -151,6 +154,7 @@ export function ProviderDropdown({
   fallbackProviderId,
   onSelect,
   agentIdentifier,
+  agentName,
   linkedIntegrationIds,
   excludeLinked = false,
   renderTrigger,
@@ -331,8 +335,8 @@ export function ProviderDropdown({
         onSelect(item.providerId, item.integration);
         setOpen(false);
       } else {
-        const sameProviderCount = (integrations ?? []).filter((i) => i.providerId === item.providerId).length;
-        const uniqueName = sameProviderCount > 0 ? `${item.displayName} ${sameProviderCount + 1}` : item.displayName;
+        const channel = PROVIDER_ID_TO_CHANNEL_MAP[item.providerId];
+        const uniqueName = channel === ChannelTypeEnum.CHAT && agentName ? `${agentName} - Bot` : item.displayName;
 
         const created = await createIntegrationMutation.mutateAsync({
           providerId: item.providerId,
diff --git a/apps/dashboard/src/components/agents/teams-app-package.ts b/apps/dashboard/src/components/agents/teams-app-package.ts
index f371ec44e3f..01d530d0a0a 100644
--- a/apps/dashboard/src/components/agents/teams-app-package.ts
+++ b/apps/dashboard/src/components/agents/teams-app-package.ts
@@ -5,6 +5,8 @@
  * Uses store-only zip (no compression) since PNGs are already compressed and the JSON is tiny.
  */
 
+import { buildZip } from '@/utils/build-zip';
+
 function generateIconBlob(size: number, letter: string, style: 'color' | 'outline'): Promise<Blob> {
   const canvas = document.createElement('canvas');
   canvas.width = size;
@@ -41,73 +43,6 @@ function generateIconBlob(size: number, letter: string, style: 'color' | 'outlin
   });
 }
 
-// ---------------------------------------------------------------------------
-// Minimal ZIP builder (store-only, no compression)
-// ---------------------------------------------------------------------------
-
-function crc32(data: Uint8Array): number {
-  let crc = 0xffffffff;
-
-  for (let i = 0; i < data.length; i++) {
-    crc ^= data[i];
-    for (let j = 0; j < 8; j++) {
-      crc = crc & 1 ? (crc >>> 1) ^ 0xedb88320 : crc >>> 1;
-    }
-  }
-
-  return (crc ^ 0xffffffff) >>> 0;
-}
-
-function buildZip(files: { name: string; data: Uint8Array }[]): Blob {
-  const parts: Uint8Array[] = [];
-  const centralEntries: Uint8Array[] = [];
-  let offset = 0;
-
-  for (const file of files) {
-    const nameBytes = new TextEncoder().encode(file.name);
-    const crc = crc32(file.data);
-
-    const local = new ArrayBuffer(30 + nameBytes.length);
-    const lv = new DataView(local);
-    lv.setUint32(0, 0x04034b50, true);
-    lv.setUint16(4, 20, true);
-    lv.setUint16(8, 0, true);
-    lv.setUint32(14, crc, true);
-    lv.setUint32(18, file.data.length, true);
-    lv.setUint32(22, file.data.length, true);
-    lv.setUint16(26, nameBytes.length, true);
-    new Uint8Array(local).set(nameBytes, 30);
-
-    parts.push(new Uint8Array(local), file.data);
-
-    const central = new ArrayBuffer(46 + nameBytes.length);
-    const cv = new DataView(central);
-    cv.setUint32(0, 0x02014b50, true);
-    cv.setUint16(4, 20, true);
-    cv.setUint16(6, 20, true);
-    cv.setUint32(16, crc, true);
-    cv.setUint32(20, file.data.length, true);
-    cv.setUint32(24, file.data.length, true);
-    cv.setUint16(28, nameBytes.length, true);
-    cv.setUint32(42, offset, true);
-    new Uint8Array(central).set(nameBytes, 46);
-
-    centralEntries.push(new Uint8Array(central));
-    offset += 30 + nameBytes.length + file.data.length;
-  }
-
-  const centralSize = centralEntries.reduce((s, e) => s + e.length, 0);
-  const eocd = new ArrayBuffer(22);
-  const ev = new DataView(eocd);
-  ev.setUint32(0, 0x06054b50, true);
-  ev.setUint16(8, files.length, true);
-  ev.setUint16(10, files.length, true);
-  ev.setUint32(12, centralSize, true);
-  ev.setUint32(16, offset, true);
-
-  return new Blob([...parts, ...centralEntries, new Uint8Array(eocd)], { type: 'application/zip' });
-}
-
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
diff --git a/apps/dashboard/src/components/agents/teams-setup-guide.tsx b/apps/dashboard/src/components/agents/teams-setup-guide.tsx
index 617e12ae6d8..fc123684e67 100644
--- a/apps/dashboard/src/components/agents/teams-setup-guide.tsx
+++ b/apps/dashboard/src/components/agents/teams-setup-guide.tsx
@@ -1,19 +1,37 @@
 import { useUser } from '@clerk/clerk-react';
-import { MsTeamsConnectButton, NovuProvider } from '@novu/react';
-import { ChatProviderIdEnum } from '@novu/shared';
+import { MsTeamsConnectButton, MsTeamsLinkUser, NovuProvider, useNovu } from '@novu/react';
+import { ChatProviderIdEnum, FeatureFlagsKeysEnum } from '@novu/shared';
+import { useQueryClient } from '@tanstack/react-query';
 import { Download } from 'lucide-react';
 import { AnimatePresence, motion } from 'motion/react';
-import { useCallback, useEffect, useMemo, useState } from 'react';
-import { RiArrowDownSLine, RiKey2Line } from 'react-icons/ri';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  RiArrowDownSLine,
+  RiCheckLine,
+  RiCloseLine,
+  RiFlashlightLine,
+  RiKey2Line,
+  RiListCheck2,
+  RiLoader4Line,
+} from 'react-icons/ri';
 import type { AgentResponse } from '@/api/agents';
+import {
+  getAzureSetupOauthUrl,
+  getMsTeamsArmTemplateDeployUrl,
+  getMsTeamsHealthCheck,
+  type HealthCheckStatus,
+  type MsTeamsHealthCheckResult,
+} from '@/api/integrations';
 import { ProviderIcon } from '@/components/integrations/components/provider-icon';
 import { CodeBlock } from '@/components/primitives/code-block';
 import { CopyButton } from '@/components/primitives/copy-button';
 import { InlineToast } from '@/components/primitives/inline-toast';
 import { API_HOSTNAME } from '@/config';
 import { useEnvironment } from '@/context/environment/hooks';
+import { useFeatureFlag } from '@/hooks/use-feature-flag';
 import { useFetchIntegrations } from '@/hooks/use-fetch-integrations';
 import { apiHostnameManager } from '@/utils/api-hostname-manager';
+import { QueryKeys } from '@/utils/query-keys';
 import { cn } from '@/utils/ui';
 import { IntegrationCredentialsSidebar, ListeningStatus, SetupButton, SetupStep } from './setup-guide-primitives';
 import { deriveStepStatus } from './setup-guide-step-utils';
@@ -27,6 +45,14 @@ export type TeamsSetupGuideProps = {
   embedded?: boolean;
 };
 
+type IntegrationProvisioningState = {
+  status: HealthCheckStatus;
+  startedAt?: string;
+  completedAt?: string;
+  errorMessage?: string;
+  teamsAppCatalogId?: string;
+};
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -43,10 +69,6 @@ function getApiHostname(): string {
   }
 }
 
-function buildWebhookUrl(agentId: string, integrationIdentifier: string): string {
-  return `${getApiBaseUrl()}/v1/agents/${agentId}/webhook/${integrationIdentifier}`;
-}
-
 function buildOAuthCallbackUrl(): string {
   return `${getApiBaseUrl()}/v1/integrations/chat/oauth/callback`;
 }
@@ -112,10 +134,10 @@ function RedirectUriSection({ redirectUri }: { redirectUri: string }) {
   );
 }
 
-function WebhookUrlSection({ webhookUrl }: { webhookUrl: string }) {
+function WebhookEndpointSection({ webhookUrl }: { webhookUrl: string }) {
   return (
     <div className="flex flex-col gap-1.5">
-      <p className="text-text-sub text-label-xs font-medium leading-5">Messaging endpoint</p>
+      <p className="text-text-sub text-label-xs font-medium leading-5">Messaging endpoint (webhook URL)</p>
       <div className="border-stroke-soft bg-bg-white flex h-7 items-center overflow-hidden rounded-md border shadow-xs">
         <input
           type="text"
@@ -162,6 +184,490 @@ function ManifestPreview({ manifestJson }: { manifestJson: string }) {
   );
 }
 
+function ManualBotDeployFallback({ webhookUrl }: { webhookUrl: string }) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div className="flex min-w-0 flex-col gap-2">
+      <button
+        type="button"
+        aria-expanded={open}
+        className="text-text-sub hover:text-text-strong flex items-center gap-1 self-start transition-colors"
+        onClick={() => setOpen((v) => !v)}
+      >
+        <RiArrowDownSLine className={cn('size-3.5 transition-transform duration-200', open && 'rotate-180')} />
+        <span className="text-label-xs font-medium">
+          {open ? 'Hide manual instructions' : 'Can\'t use "Deploy to Azure"? Follow manual steps'}
+        </span>
+      </button>
+
+      <AnimatePresence initial={false}>
+        {open && (
+          <motion.div
+            initial={{ height: 0, opacity: 0 }}
+            animate={{ height: 'auto', opacity: 1 }}
+            exit={{ height: 0, opacity: 0 }}
+            transition={{ duration: 0.2, ease: 'easeInOut' }}
+            className="min-w-0 overflow-hidden"
+          >
+            <div className="border-stroke-soft bg-bg-weak flex flex-col gap-3 rounded-lg border p-4">
+              <p className="text-text-sub text-label-xs font-medium">Manual Azure Bot deployment</p>
+              <ol className="text-text-sub flex flex-col gap-1.5 pl-4 text-[12px] leading-5 [list-style:decimal]">
+                <li>
+                  Go to the{' '}
+                  <a
+                    href="https://portal.azure.com"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="text-primary underline underline-offset-2"
+                  >
+                    Azure Portal
+                  </a>{' '}
+                  and click <strong>+ Create a resource</strong> in the top-left.
+                </li>
+                <li>
+                  Search for <strong>Azure Bot</strong> and select it from the results, then click{' '}
+                  <strong>Create</strong>.
+                </li>
+                <li>
+                  Fill in the form:
+                  <ul className="mt-1 flex flex-col gap-1 pl-4 [list-style:disc]">
+                    <li>
+                      <strong>Bot handle:</strong> a unique name (e.g., your agent name)
+                    </li>
+                    <li>
+                      <strong>Subscription:</strong> select your Azure subscription
+                    </li>
+                    <li>
+                      <strong>Resource group:</strong> create new or select existing
+                    </li>
+                    <li>
+                      <strong>Pricing tier:</strong> F0 (Free)
+                    </li>
+                    <li>
+                      <strong>Type of App:</strong> Single Tenant
+                    </li>
+                    <li>
+                      <strong>Creation type:</strong> Use existing app registration
+                    </li>
+                    <li>
+                      <strong>Microsoft App ID:</strong> paste the App ID from Step 1
+                    </li>
+                    <li>
+                      <strong>Microsoft App Tenant ID:</strong> paste the Tenant ID from Step 1
+                    </li>
+                  </ul>
+                </li>
+                <li>
+                  Click <strong>Review + create</strong>, review the summary, then click <strong>Create</strong>. Wait
+                  for the deployment to complete (usually 1–2 minutes).
+                </li>
+                <li>
+                  Once deployed, click <strong>Go to resource</strong> to open the Azure Bot.
+                </li>
+                <li>
+                  In the left sidebar, under <strong>Settings</strong>, click <strong>Configuration</strong>. In the{' '}
+                  <strong>Messaging endpoint</strong> field, paste the URL below, then click <strong>Apply</strong>.
+                </li>
+              </ol>
+              <WebhookEndpointSection webhookUrl={webhookUrl} />
+              <ol
+                className="text-text-sub flex flex-col gap-1.5 pl-4 text-[12px] leading-5 [list-style:decimal]"
+                start={7}
+              >
+                <li>
+                  In the left sidebar, click <strong>Channels</strong>. Click <strong>Microsoft Teams</strong> in the
+                  available channels list, accept the terms, and click <strong>Apply</strong> to enable the Teams
+                  channel.
+                </li>
+              </ol>
+            </div>
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Setup mode toggle
+// ---------------------------------------------------------------------------
+
+type SetupMode = 'quick' | 'manual';
+
+function SetupModeToggle({ mode, onChange }: { mode: SetupMode; onChange: (m: SetupMode) => void }) {
+  return (
+    <div className="flex items-center gap-1 rounded-lg border border-stroke-soft bg-bg-weak p-1">
+      <button
+        type="button"
+        onClick={() => onChange('quick')}
+        className={cn(
+          'flex items-center gap-1.5 rounded-md px-3 py-1.5 text-label-xs font-medium transition-colors',
+          mode === 'quick' ? 'bg-bg-white text-text-strong shadow-xs' : 'text-text-sub hover:text-text-strong'
+        )}
+      >
+        <RiFlashlightLine className="size-3.5" />
+        Quick Setup
+      </button>
+      <button
+        type="button"
+        onClick={() => onChange('manual')}
+        className={cn(
+          'flex items-center gap-1.5 rounded-md px-3 py-1.5 text-label-xs font-medium transition-colors',
+          mode === 'manual' ? 'bg-bg-white text-text-strong shadow-xs' : 'text-text-sub hover:text-text-strong'
+        )}
+      >
+        <RiListCheck2 className="size-3.5" />
+        Manual Setup
+      </button>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Health-check constants and components
+// ---------------------------------------------------------------------------
+
+const HEALTH_POLL_INTERVAL_MS = 10_000;
+
+const CHECKPOINT_LABELS: Record<keyof Omit<MsTeamsHealthCheckResult, 'allReady'>, string> = {
+  appRegistration: 'App Registration',
+  azureBotCreated: 'Azure Bot Created',
+  teamsAppCatalog: 'Teams App Catalog',
+  permissions: 'Permission Propagation',
+};
+
+function CheckpointRow({ label, status }: { label: string; status: HealthCheckStatus }) {
+  return (
+    <div className="flex items-center gap-2.5">
+      <div className="flex size-5 shrink-0 items-center justify-center rounded-full border border-stroke-soft bg-bg-weak">
+        {status === 'ready' && <RiCheckLine className="size-3 text-success-base" />}
+        {status === 'pending' && <RiLoader4Line className="size-3 animate-spin text-text-sub" />}
+        {status === 'failed' && <RiCloseLine className="size-3 text-error-base" />}
+      </div>
+      <span
+        className={cn(
+          'text-label-xs',
+          status === 'ready' && 'text-text-strong',
+          status === 'pending' && 'text-text-sub',
+          status === 'failed' && 'text-error-base'
+        )}
+      >
+        {label}
+      </span>
+    </div>
+  );
+}
+
+type HealthCheckViewProps = {
+  integrationId: string;
+  /** True while the Azure setup popup is still open — polling is suspended until credentials are saved */
+  waitingForSetup: boolean;
+  onReady: () => void;
+};
+
+function HealthCheckView({ integrationId, waitingForSetup, onReady }: HealthCheckViewProps) {
+  const { currentEnvironment } = useEnvironment();
+  const [status, setStatus] = useState<MsTeamsHealthCheckResult | null>(null);
+  const pollRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const onReadyRef = useRef(onReady);
+  onReadyRef.current = onReady;
+
+  const stopPolling = useCallback(() => {
+    if (pollRef.current !== null) {
+      clearInterval(pollRef.current);
+      pollRef.current = null;
+    }
+  }, []);
+
+  const poll = useCallback(async () => {
+    if (!currentEnvironment || waitingForSetup) return;
+
+    try {
+      const result = await getMsTeamsHealthCheck(integrationId, currentEnvironment);
+      setStatus(result);
+
+      if (result.allReady) {
+        stopPolling();
+        onReadyRef.current();
+
+        return;
+      }
+    } catch {
+      // ignore transient errors — keep polling
+    }
+  }, [currentEnvironment, integrationId, waitingForSetup, stopPolling]);
+
+  useEffect(() => {
+    void poll();
+    pollRef.current = setInterval(() => void poll(), HEALTH_POLL_INTERVAL_MS);
+
+    return stopPolling;
+  }, [poll, stopPolling]);
+
+  const allPending: HealthCheckStatus = 'pending';
+  const checkpoints = (Object.keys(CHECKPOINT_LABELS) as Array<keyof typeof CHECKPOINT_LABELS>).map((key) => ({
+    key,
+    label: CHECKPOINT_LABELS[key],
+    status: (status ? (status[key] ?? allPending) : allPending) as HealthCheckStatus,
+  }));
+
+  const hasFailed = status?.appRegistration === 'failed' || status?.azureBotCreated === 'failed';
+
+  return (
+    <div className="flex flex-col gap-4">
+      <p className="text-text-sub text-paragraph-sm">
+        {waitingForSetup
+          ? 'Complete authorization in the popup window. Teams readiness will be verified once setup finishes.'
+          : 'Verifying that the Teams app, bot credentials, and permissions are ready. This usually takes 1–3 minutes; permissions can take up to 60 minutes to propagate.'}
+      </p>
+
+      <div className="flex flex-col gap-2.5 rounded-lg border border-stroke-soft bg-bg-weak p-4">
+        {checkpoints.map(({ key, label, status: s }) => (
+          <CheckpointRow key={key} label={label} status={s} />
+        ))}
+      </div>
+
+      {!waitingForSetup && hasFailed && (
+        <InlineToast
+          variant="error"
+          title="Setup error"
+          description="App Registration or Azure Bot could not be verified. Please retry the Azure setup step."
+        />
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// ConnectAndLinkSection
+// ---------------------------------------------------------------------------
+
+const ENDPOINT_POLL_INTERVAL_MS = 3_000;
+const ENDPOINT_POLL_GRACE_MS = 30_000;
+
+type ConnectAndLinkSectionProps = {
+  integrationIdentifier: string;
+  connectionIdentifier: string;
+  connectLabel: string;
+  onFullyConnected: () => void;
+};
+
+/**
+ * Renders inside a NovuProvider so it can access the Novu SDK instance.
+ * Shows the MsTeamsConnectButton. After admin consent succeeds, polls for
+ * the channel-endpoint (link_user leg). If the endpoint appears within the
+ * grace window both steps complete silently. If it times out, a
+ * MsTeamsLinkUser recovery button is surfaced as a required follow-up action.
+ */
+function ConnectAndLinkSection({
+  integrationIdentifier,
+  connectionIdentifier,
+  connectLabel,
+  onFullyConnected,
+}: ConnectAndLinkSectionProps) {
+  const novu = useNovu();
+  const [needsLinkUser, setNeedsLinkUser] = useState(false);
+  const [isPollingEndpoint, setIsPollingEndpoint] = useState(false);
+  const pollIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const pollStartedAtRef = useRef<number>(0);
+
+  const stopPolling = useCallback(() => {
+    if (pollIntervalRef.current !== null) {
+      clearInterval(pollIntervalRef.current);
+      pollIntervalRef.current = null;
+    }
+  }, []);
+
+  useEffect(() => {
+    return () => stopPolling();
+  }, [stopPolling]);
+
+  // On mount, check if the workspace is already connected but the user link is
+  // still missing (e.g. the user refreshed before completing the link step).
+  // Admin consent creates a channelConnection; the link_user step creates a
+  // channelEndpoint of type ms_teams_user. We need to check both.
+  useEffect(() => {
+    if (!integrationIdentifier || !connectionIdentifier) {
+      return;
+    }
+
+    let cancelled = false;
+
+    (async () => {
+      try {
+        const connResponse = await novu.channelConnections.get({ identifier: connectionIdentifier });
+        if (cancelled || !connResponse.data) return;
+
+        const epResponse = await novu.channelEndpoints.list({ integrationIdentifier, connectionIdentifier });
+        if (cancelled) return;
+
+        const hasUserEndpoint = epResponse.data?.some((ep: { type: string }) => ep.type === 'ms_teams_user') ?? false;
+
+        if (hasUserEndpoint) {
+          onFullyConnected();
+        } else {
+          setNeedsLinkUser(true);
+        }
+      } catch {
+        // ignore — will be surfaced after the next connect attempt
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [novu, integrationIdentifier, connectionIdentifier, onFullyConnected]);
+
+  const startEndpointPoll = useCallback(() => {
+    stopPolling();
+    setIsPollingEndpoint(true);
+    pollStartedAtRef.current = Date.now();
+
+    pollIntervalRef.current = setInterval(async () => {
+      try {
+        const response = await novu.channelEndpoints.list({
+          integrationIdentifier,
+          connectionIdentifier,
+        });
+        const found = response.data?.find((ep: { type: string }) => ep.type === 'ms_teams_user') ?? null;
+
+        if (found) {
+          stopPolling();
+          setIsPollingEndpoint(false);
+          onFullyConnected();
+
+          return;
+        }
+      } catch {
+        // ignore transient errors during polling
+      }
+
+      if (Date.now() - pollStartedAtRef.current >= ENDPOINT_POLL_GRACE_MS) {
+        stopPolling();
+        setIsPollingEndpoint(false);
+        setNeedsLinkUser(true);
+      }
+    }, ENDPOINT_POLL_INTERVAL_MS);
+  }, [novu, integrationIdentifier, connectionIdentifier, onFullyConnected, stopPolling]);
+
+  const handleConnectSuccess = useCallback(() => {
+    startEndpointPoll();
+  }, [startEndpointPoll]);
+
+  const handleLinkSuccess = useCallback(() => {
+    setNeedsLinkUser(false);
+    onFullyConnected();
+  }, [onFullyConnected]);
+
+  return (
+    <div className="flex min-w-0 flex-col gap-3">
+      {/* container={undefined} satisfies the Pick<NovuUIOptions, 'container' | 'appearance'> requirement */}
+      <MsTeamsConnectButton
+        integrationIdentifier={integrationIdentifier}
+        connectionIdentifier={connectionIdentifier}
+        connectLabel={connectLabel}
+        connectedLabel="Connected to MS Teams"
+        onConnectSuccess={handleConnectSuccess}
+        container={undefined}
+      />
+
+      {isPollingEndpoint && (
+        <p className="text-text-soft flex items-center gap-1.5 text-label-xs">
+          <RiLoader4Line className="size-3 shrink-0 animate-spin" aria-hidden />
+          Verifying user link…
+        </p>
+      )}
+
+      <AnimatePresence initial={false}>
+        {needsLinkUser && (
+          <motion.div
+            initial={{ height: 0, opacity: 0, y: -4 }}
+            animate={{ height: 'auto', opacity: 1, y: 0 }}
+            exit={{ height: 0, opacity: 0, y: -4 }}
+            transition={{ duration: 0.2, ease: 'easeInOut' }}
+            className="overflow-hidden"
+          >
+            <div className="flex min-w-0 flex-col gap-3">
+              <InlineToast
+                className="w-full"
+                variant="warning"
+                title="One more step required"
+                description="Workspace connected, but we couldn't link your Teams identity automatically. This can fail because of Azure caching, so try linking again after some time if it doesn't work right away."
+              />
+              <MsTeamsLinkUser
+                integrationIdentifier={integrationIdentifier}
+                connectionIdentifier={connectionIdentifier}
+                linkLabel="Link your Teams identity ↗"
+                onLinkSuccess={handleLinkSuccess}
+                container={undefined}
+              />
+            </div>
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Manual flow health-check polling hook
+// ---------------------------------------------------------------------------
+
+const MANUAL_HEALTH_CHECKS = ['teamsAppCatalog', 'permissions'] as const;
+
+type ManualHealthState = Pick<MsTeamsHealthCheckResult, 'azureBotCreated' | 'teamsAppCatalog' | 'permissions'>;
+
+function useManualHealthPoll(integrationId: string, enabled: boolean): ManualHealthState | null {
+  const { currentEnvironment } = useEnvironment();
+  const [state, setState] = useState<ManualHealthState | null>(null);
+  const pollRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const stopPolling = useCallback(() => {
+    if (pollRef.current !== null) {
+      clearInterval(pollRef.current);
+      pollRef.current = null;
+    }
+  }, []);
+
+  const poll = useCallback(async () => {
+    if (!currentEnvironment || !enabled) return;
+
+    try {
+      const result = await getMsTeamsHealthCheck(integrationId, currentEnvironment, [...MANUAL_HEALTH_CHECKS]);
+      const next: ManualHealthState = {
+        azureBotCreated: null,
+        teamsAppCatalog: result.teamsAppCatalog,
+        permissions: result.permissions,
+      };
+
+      setState(next);
+
+      if (next.teamsAppCatalog === 'ready' && next.permissions === 'ready') {
+        stopPolling();
+      }
+    } catch {
+      // ignore transient errors — keep polling
+    }
+  }, [currentEnvironment, enabled, integrationId, stopPolling]);
+
+  useEffect(() => {
+    if (!enabled) {
+      stopPolling();
+      setState(null);
+
+      return stopPolling;
+    }
+
+    void poll();
+    pollRef.current = setInterval(() => void poll(), HEALTH_POLL_INTERVAL_MS);
+
+    return stopPolling;
+  }, [enabled, poll, stopPolling]);
+
+  return state;
+}
+
 // ---------------------------------------------------------------------------
 // Main component
 // ---------------------------------------------------------------------------
@@ -175,18 +681,34 @@ export function TeamsSetupGuide({
 }: TeamsSetupGuideProps) {
   const { user } = useUser();
   const { currentEnvironment } = useEnvironment();
+  const queryClient = useQueryClient();
+  const isQuickSetupEnabled = useFeatureFlag(FeatureFlagsKeysEnum.IS_MSTEAMS_QUICK_SETUP_ENABLED, false);
   const [isCredentialsSidebarOpen, setIsCredentialsSidebarOpen] = useState(false);
   const [isConnected, setIsConnected] = useState(false);
-
-  // biome-ignore lint/correctness/useExhaustiveDependencies: reset when the watched integration changes
-  useEffect(() => {
-    setIsConnected(false);
-  }, [integrationId]);
-
-  const handleConnected = useCallback(() => {
-    setIsConnected(true);
-    onStepsCompleted?.();
-  }, [onStepsCompleted]);
+  const [isDeploying, setIsDeploying] = useState(false);
+  const [hasDeployedBot, setHasDeployedBot] = useState(
+    () => sessionStorage.getItem(`novu:bot-deployed:${integrationId}`) === 'true'
+  );
+  const [isConnectingAzure, setIsConnectingAzure] = useState(false);
+  const [setupMode, setSetupMode] = useState<SetupMode>('quick');
+  const [teamsAppUploaded, setTeamsAppUploaded] = useState<boolean | null>(null);
+  /**
+   * Whether the health-check gate has been cleared.
+   * Set to `true` once the health-check poll confirms Teams readiness.
+   * On page load with existing credentials we run a one-time check; if it passes immediately
+   * we skip the polling UI — if not, we show the full HealthCheckView.
+   */
+  const [healthCheckCleared, setHealthCheckCleared] = useState(false);
+  /**
+   * Whether the health-check polling view is actively running.
+   * Set to `true` by the OAuth popup completing, OR on mount when credentials exist but
+   * the initial health check has not yet confirmed all resources are ready.
+   */
+  const [showHealthCheck, setShowHealthCheck] = useState(false);
+  const azurePopupRef = useRef<Window | null>(null);
+  const hasCheckedOnMountRef = useRef(false);
+  const [initialCheckLoading, setInitialCheckLoading] = useState(false);
+  const activeSetupMode = isQuickSetupEnabled ? setupMode : 'manual';
 
   const { integrations } = useFetchIntegrations();
 
@@ -196,11 +718,68 @@ export function TeamsSetupGuide({
   );
 
   const integrationIdentifier = selectedIntegration?.identifier ?? '';
+  const provisioning = (selectedIntegration as { provisioning?: IntegrationProvisioningState } | undefined)
+    ?.provisioning;
   const credentials = selectedIntegration?.credentials as Record<string, string> | undefined;
   const appId = credentials?.clientId ?? '';
+  // teamsAppCatalogId is retained for future use (e.g. restoring an "Open in Teams" deep link once catalog propagation is confirmed)
+  const teamsAppCatalogId = provisioning?.teamsAppCatalogId ?? null;
   const hasCredentials = Boolean(appId && credentials?.secretKey && credentials?.tenantId);
+  const hasQuickSetupProvisioning = Boolean(provisioning);
+  const isExistingManualSetup = hasCredentials && !hasQuickSetupProvisioning;
+
+  useEffect(() => {
+    setIsConnected(false);
+    setHealthCheckCleared(false);
+    // Seed from provisioning: if a catalog ID already exists, the upload previously succeeded.
+    setTeamsAppUploaded(teamsAppCatalogId !== null ? true : null);
+    setShowHealthCheck(false);
+    hasCheckedOnMountRef.current = false;
+    setHasDeployedBot(sessionStorage.getItem(`novu:bot-deployed:${integrationId}`) === 'true');
+  }, [integrationId, teamsAppCatalogId]);
+
+  // On page load (or when credentials first appear), run a one-time health check.
+  // If the Teams health check passes immediately we silently mark the gate cleared.
+  // If any check is still pending/failed we show the HealthCheckView so the user
+  // sees live status rather than a falsely-completed step.
+  useEffect(() => {
+    if (!isQuickSetupEnabled || !hasCredentials || !currentEnvironment || hasCheckedOnMountRef.current) {
+      return;
+    }
+
+    if (!hasQuickSetupProvisioning) {
+      setShowHealthCheck(false);
+      setHealthCheckCleared(false);
+
+      return;
+    }
+
+    hasCheckedOnMountRef.current = true;
+    setInitialCheckLoading(true);
+
+    (async () => {
+      try {
+        const result = await getMsTeamsHealthCheck(integrationId, currentEnvironment);
+
+        if (result.allReady) {
+          setHealthCheckCleared(true);
+        } else {
+          setShowHealthCheck(true);
+        }
+      } catch {
+        // If the check itself fails, show the health-check view so polling can retry.
+        setShowHealthCheck(true);
+      } finally {
+        setInitialCheckLoading(false);
+      }
+    })();
+  }, [hasCredentials, hasQuickSetupProvisioning, currentEnvironment, integrationId, isQuickSetupEnabled]);
+
+  const handleConnected = useCallback(() => {
+    setIsConnected(true);
+    onStepsCompleted?.();
+  }, [onStepsCompleted]);
 
-  const webhookUrl = buildWebhookUrl(agent._id, integrationIdentifier || 'YOUR_INTEGRATION_IDENTIFIER');
   const manifestJson = JSON.stringify(buildManifest(appId, agent.name), null, 2);
 
   const canDownload = Boolean(appId);
@@ -213,10 +792,69 @@ export function TeamsSetupGuide({
     void downloadTeamsAppPackage(manifestJson, agent.name);
   }, [canDownload, manifestJson, agent.name]);
 
+  const handleDeployToAzure = useCallback(async () => {
+    if (!currentEnvironment || !hasCredentials || isDeploying) {
+      return;
+    }
+
+    setIsDeploying(true);
+
+    try {
+      const { deployUrl } = await getMsTeamsArmTemplateDeployUrl(integrationId, currentEnvironment);
+      window.open(deployUrl, '_blank', 'noopener,noreferrer');
+      sessionStorage.setItem(`novu:bot-deployed:${integrationId}`, 'true');
+      setHasDeployedBot(true);
+    } finally {
+      setIsDeploying(false);
+    }
+  }, [currentEnvironment, hasCredentials, integrationId, isDeploying]);
+
+  const handleConnectToAzure = useCallback(async () => {
+    if (!currentEnvironment || isConnectingAzure) {
+      return;
+    }
+
+    const popup = window.open('', '_blank');
+    azurePopupRef.current = popup;
+    setIsConnectingAzure(true);
+    // Show health-check checkpoints immediately so the user can see what's happening
+    setShowHealthCheck(true);
+    setHealthCheckCleared(false);
+
+    try {
+      const { url } = await getAzureSetupOauthUrl(integrationId, currentEnvironment);
+
+      if (popup && !popup.closed) {
+        popup.location.href = url;
+      } else {
+        window.open(url, '_blank');
+      }
+    } catch (error) {
+      popup?.close();
+      azurePopupRef.current = null;
+      // Reset health-check state if we couldn't even get the OAuth URL
+      setShowHealthCheck(false);
+      throw error;
+    } finally {
+      setIsConnectingAzure(false);
+    }
+  }, [currentEnvironment, integrationId, isConnectingAzure]);
+
   const base = stepOffset;
 
+  // Manual flow: poll only the checks needed to drive steps 4-6 once credentials are saved.
+  const manualHealth = useManualHealthPoll(integrationId, hasCredentials && activeSetupMode === 'manual');
+
+  // Build the webhook URL used in the manual Bot deployment instructions.
+  const webhookUrl = `${getApiBaseUrl()}/v1/agents/${agent._id}/webhook/${integrationIdentifier}`;
+
+  // Steps: App Reg + Redirect URI (base+0), Graph perms (base+1),
+  //        Credentials (base+2), Deploy to Azure (base+3), Download pkg (base+4), Upload (base+5), Connect (base+6)
+  //
+  // Steps 1-3 are gated by hasCredentials (saving valid credentials = steps 1-3 done).
+  // Steps 4-7 advance automatically as the health-check reports resources ready.
   const firstIncomplete = useMemo(() => {
-    if (isConnected) {
+    if (isConnected && manualHealth?.teamsAppCatalog === 'ready') {
       return base + 7;
     }
 
@@ -224,105 +862,476 @@ export function TeamsSetupGuide({
       return base;
     }
 
-    return base + 6;
-  }, [base, hasCredentials, isConnected]);
+    // Step 4 (Deploy Azure Bot) is current until the user has clicked "Deploy to Azure".
+    if (!hasDeployedBot) {
+      return base + 3;
+    }
 
-  const steps = (
+    if (manualHealth?.teamsAppCatalog === 'ready') {
+      return base + 6;
+    }
+
+    // Step 6 (upload) becomes active once bot is deployed.
+    return base + 5;
+  }, [base, hasCredentials, hasDeployedBot, isConnected, manualHealth]);
+
+  // Quick Setup: step 0 = Set Up Azure, step 1 = health-check gate, step 2 = Add bot to Teams, step 3 = Connect MS Teams
+  //
+  // The health-check gate (step 1) is active when:
+  //   - The OAuth popup just completed this session and we're waiting for Azure propagation, OR
+  //   - The page loaded with existing credentials but the initial health check found resources not yet ready.
+  // Once `healthCheckCleared` is true (either via polling or immediate pass on mount) we advance to step 2.
+  const healthGateActive = showHealthCheck && !healthCheckCleared;
+
+  const quickFirstIncomplete = useMemo(() => {
+    if (isConnected) return base + 4;
+    if (!hasCredentials) return base; // no credentials yet: start at step 0
+    if (isExistingManualSetup) return base; // credentials exist, but Quick Setup provisioning has not run
+    if (initialCheckLoading) return base + 1; // credentials exist but initial check still in-flight
+    if (healthCheckCleared) return base + 2; // check confirmed all resources ready
+    if (showHealthCheck) return base + 1; // health-check actively running (polling)
+
+    return base + 1; // has credentials but neither cleared nor actively showing — shouldn't happen in practice
+  }, [
+    base,
+    hasCredentials,
+    healthCheckCleared,
+    showHealthCheck,
+    isConnected,
+    initialCheckLoading,
+    isExistingManualSetup,
+  ]);
+
+  let quickReadinessTitle = 'Verify Teams Readiness';
+  let quickReadinessDescription =
+    'After Azure setup completes, Novu will verify the Teams app, Azure Bot, and permissions.';
+
+  if (isExistingManualSetup) {
+    quickReadinessTitle = 'Quick Setup Not Verified';
+    quickReadinessDescription =
+      'This integration was configured manually or outside Quick Setup, so Novu cannot verify Azure Bot provisioning from the setup record.';
+  } else if (healthGateActive || initialCheckLoading) {
+    quickReadinessDescription = 'Verifying the Teams app catalog entry, Azure Bot, and Graph permissions.';
+  } else if (healthCheckCleared) {
+    quickReadinessTitle = 'Teams Readiness Verified';
+    quickReadinessDescription = 'Teams app, Azure Bot, and permissions are ready.';
+  }
+
+  const quickSteps = (
     <>
+      {/* Step 1: Single "Set Up Azure" button — creates App Registration + Bot Service */}
       <SetupStep
         index={base}
-        status={deriveStepStatus(base, firstIncomplete)}
-        title="Create an Azure Bot resource"
-        description="In the Azure Portal, create a new Azure Bot (Single Tenant). Choose F0 (free) pricing for testing. Once created, note your App ID from the Bot Configuration page."
+        status={deriveStepStatus(base, quickFirstIncomplete)}
+        title="Set Up Azure"
+        description={
+          isExistingManualSetup ? (
+            <span>
+              {
+                'This integration already has manually saved credentials. Run Quick Setup if you want Novu to create and track the Azure resources automatically.'
+              }
+            </span>
+          ) : (
+            <span>
+              {'Authorize Novu to create an '}
+              <strong>App Registration</strong>
+              {', deploy an '}
+              <strong>Azure Bot Service</strong>
+              {
+                ", and enable the Teams channel — all in one click. Novu will also attempt to upload the Teams app to your org's app catalog automatically."
+              }
+            </span>
+          )
+        }
         rightContent={
-          <SetupButton
-            href="https://portal.azure.com/#create/Microsoft.AzureBot"
-            leadingIcon={
-              <ProviderIcon
-                providerId={ChatProviderIdEnum.MsTeams}
-                providerDisplayName="MS Teams"
-                className="size-4 shrink-0"
-              />
+          <div className="flex min-w-0 flex-col gap-3">
+            <SetupButton
+              leadingIcon={
+                isConnectingAzure ? null : (
+                  <ProviderIcon
+                    providerId={ChatProviderIdEnum.MsTeams}
+                    providerDisplayName="MS Teams"
+                    className="size-4 shrink-0"
+                  />
+                )
+              }
+              onClick={handleConnectToAzure}
+              disabled={isConnectingAzure}
+            >
+              {isConnectingAzure ? 'Opening Azure…' : 'Set Up Azure'}
+            </SetupButton>
+          </div>
+        }
+        extraContent={
+          <InlineToast
+            className="mt-2 w-full"
+            variant="tip"
+            title={isExistingManualSetup ? 'Manual setup detected:' : 'What Novu does automatically:'}
+            description={
+              isExistingManualSetup ? (
+                <span>
+                  {
+                    'Novu cannot confirm Azure Bot creation from manual setup history. Continue with Manual setup to verify the catalog and permissions, or run Quick Setup to create a tracked provisioning record.'
+                  }
+                </span>
+              ) : (
+                <span>
+                  {
+                    'Creates the App Registration, Bot Service resource, enables the Teams channel, and grants the required Graph permissions — no manual Azure Portal steps needed.'
+                  }
+                </span>
+              )
             }
-          >
-            Open Azure Portal
-          </SetupButton>
+          />
         }
       />
 
+      {/* Health-check gate: runs on mount when credentials exist, and after the OAuth popup completes */}
       <SetupStep
         index={base + 1}
-        status={deriveStepStatus(base + 1, firstIncomplete)}
-        title="Add Microsoft Graph API permissions"
+        status={deriveStepStatus(base + 1, quickFirstIncomplete)}
+        title={quickReadinessTitle}
+        description={quickReadinessDescription}
+        rightContent={
+          isExistingManualSetup ? (
+            <SetupButton onClick={() => setSetupMode('manual')}>Continue manual setup</SetupButton>
+          ) : initialCheckLoading ? (
+            <p className="text-text-soft flex items-center gap-1.5 text-label-xs">
+              <RiLoader4Line className="size-3 shrink-0 animate-spin" aria-hidden />
+              Checking Teams readiness…
+            </p>
+          ) : healthGateActive ? (
+            <HealthCheckView
+              integrationId={integrationId}
+              waitingForSetup={!hasCredentials || !hasQuickSetupProvisioning}
+              onReady={() => {
+                setHealthCheckCleared(true);
+                setShowHealthCheck(false);
+                queryClient.invalidateQueries({ queryKey: [QueryKeys.fetchIntegrations] });
+              }}
+            />
+          ) : undefined
+        }
+      />
+
+      {/* Step 3: Add bot in Teams */}
+      <SetupStep
+        index={base + 2}
+        status={deriveStepStatus(base + 2, quickFirstIncomplete)}
+        title="Add the bot to Microsoft Teams"
         description={
-          <span>
-            {'In your App Registration, go to '}
-            <strong>API permissions</strong>
-            {' → '}
-            <strong>Add a permission</strong>
-            {' → '}
-            <strong>Microsoft Graph</strong>
-            {' → '}
-            <strong>Application permissions</strong>
-            {'. Search for and add: '}
-            <code className="font-code text-[11px]">Team.ReadBasic.All</code>
-            {', '}
-            <code className="font-code text-[11px]">Channel.ReadBasic.All</code>
-            {', '}
-            <code className="font-code text-[11px]">AppCatalog.Read.All</code>
-            {'. Then click '}
-            <strong>Grant admin consent</strong>
-            {' for your organization.'}
-          </span>
+          <ol className="flex flex-col gap-1.5 pl-4 [list-style:decimal]">
+            <li className="text-paragraph-xs text-text-sub">
+              Click <strong>Download app package</strong> on the right to save the{' '}
+              <code className="font-code text-[11px]">.zip</code> file.
+            </li>
+            <li className="text-paragraph-xs text-text-sub">
+              Open{' '}
+              <a
+                href="https://teams.microsoft.com"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="underline underline-offset-2"
+              >
+                Microsoft Teams
+              </a>
+              .
+            </li>
+            <li className="text-paragraph-xs text-text-sub">
+              Click <strong>Apps</strong> in the left sidebar.
+            </li>
+            <li className="text-paragraph-xs text-text-sub">
+              Click <strong>Manage your apps</strong> at the bottom of the panel.
+            </li>
+            <li className="text-paragraph-xs text-text-sub">
+              Click <strong>Upload an app</strong>, then select <strong>Upload a custom app</strong>.
+            </li>
+            <li className="text-paragraph-xs text-text-sub">
+              Choose the downloaded <code className="font-code text-[11px]">.zip</code> file, then click{' '}
+              <strong>Add</strong> in the app modal.
+            </li>
+          </ol>
         }
         rightContent={
-          <SetupButton href="https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps">
-            Open App Registrations
-          </SetupButton>
+          <div className="flex min-w-0 flex-col gap-3">
+            <div className="self-start">
+              <SetupButton
+                leadingIcon={<Download className="size-3.5" />}
+                onClick={handleDownload}
+                disabled={!canDownload}
+              >
+                Download app package
+              </SetupButton>
+            </div>
+            <ManifestPreview manifestJson={manifestJson} />
+          </div>
+        }
+        extraContent={
+          teamsAppUploaded !== true ? (
+            <InlineToast
+              className="mt-2 w-full"
+              variant="tip"
+              title="Organization-wide deployment:"
+              description={
+                <span>
+                  {'For org-wide rollout, use the '}
+                  <a
+                    href="https://admin.teams.microsoft.com/"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="underline underline-offset-2"
+                  >
+                    Teams Admin Center
+                  </a>
+                  {' → Teams apps → Manage apps → Upload new app, then users can find the bot in their app store.'}
+                </span>
+              }
+            />
+          ) : null
+        }
+      />
+
+      {/* Step 4: Connect Novu to MS Teams */}
+      <SetupStep
+        index={base + 3}
+        status={deriveStepStatus(base + 3, quickFirstIncomplete)}
+        title="Connect Novu to MS Teams"
+        description="Grant admin consent and verify the connection by signing in with a Microsoft account that has Teams admin permissions."
+        rightContent={
+          <div className="flex min-w-0 flex-col gap-3">
+            {/* teamsAppCatalogId is available here for future use (e.g. an "Open in Teams" deep link once catalog propagation is confirmed) */}
+            {hasCredentials && user?.externalId && currentEnvironment?.identifier ? (
+              <NovuProvider
+                subscriber={{
+                  subscriberId: `${user.externalId}:agent-quickstart:${agent._id}`,
+                  firstName: user.firstName ?? '',
+                  lastName: user.lastName ?? '',
+                  avatar: user.imageUrl ?? '',
+                }}
+                applicationIdentifier={currentEnvironment.identifier}
+                apiUrl={apiHostnameManager.getHostname()}
+                socketUrl={apiHostnameManager.getWebSocketHostname()}
+              >
+                <ConnectAndLinkSection
+                  integrationIdentifier={integrationIdentifier}
+                  connectionIdentifier={`${user.externalId}:agent-quickstart:${agent._id}`}
+                  connectLabel={`Connect ${agent.name} ↗`}
+                  onFullyConnected={handleConnected}
+                />
+              </NovuProvider>
+            ) : (
+              <>
+                <SetupButton disabled>{`Connect ${agent.name} ↗`}</SetupButton>
+                {!hasCredentials && <p className="text-text-soft text-label-xs">Complete step {base} first.</p>}
+                {healthGateActive && <p className="text-text-soft text-label-xs">Waiting for Teams readiness.</p>}
+              </>
+            )}
+          </div>
         }
         extraContent={
           <InlineToast
             className="mt-2 w-full"
             variant="tip"
-            title="Required permissions:"
+            title="How your users connect:"
             description={
-              <span>
-                {'These Graph permissions let your bot discover Teams and channels. Optionally add '}
-                <code className="font-code text-[11px]">TeamsAppInstallation.ReadWriteSelfForTeam.All</code>
-                {' and '}
-                <code className="font-code text-[11px]">TeamsAppInstallation.ReadWriteSelfForUser.All</code>
-                {' to enable programmatic app installation.'}
-              </span>
+              <>
+                {'A '}
+                <strong>Teams admin</strong>
+                {' must connect once using '}
+                <code className="font-code text-[12px] tracking-[-0.24px]">{'<MsTeamsConnectButton />'}</code>
+                {' to grant tenant-wide consent. Each '}
+                <strong>end user</strong>
+                {' then links their personal Teams identity using '}
+                <code className="font-code text-[12px] tracking-[-0.24px]">{'<MsTeamsLinkUser />'}</code>
+                {' so Novu can deliver notifications directly to them. '}
+                <a
+                  href="https://docs.novu.co"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-text-sub underline"
+                >
+                  Read docs
+                </a>
+              </>
             }
           />
         }
       />
+    </>
+  );
 
+  const steps = (
+    <>
+      {/* Step 1: Create an App Registration */}
       <SetupStep
-        index={base + 2}
-        status={deriveStepStatus(base + 2, firstIncomplete)}
-        title="Add Novu's redirect URI"
+        index={base}
+        status={deriveStepStatus(base, firstIncomplete)}
+        title="Create an App Registration"
+        description={
+          <ol className="flex flex-col gap-1.5 pl-4 [list-style:decimal]">
+            <li>
+              Click <strong>Open App Registrations</strong> to go to the Azure Portal. Sign in with your Microsoft
+              account if prompted.
+            </li>
+            <li>
+              Click <strong>+ New registration</strong> near the top of the page.
+            </li>
+            <li>
+              In the <strong>Name</strong> field, enter a name for your bot (e.g., "{agent.name}").
+            </li>
+            <li>
+              Under <strong>Supported account types</strong>, select{' '}
+              <strong>Accounts in this organizational directory only (Single tenant)</strong>.
+            </li>
+            <li>
+              Under <strong>Redirect URI</strong>, choose <strong>Web</strong> from the platform dropdown, then paste
+              the OAuth callback URL shown below into the URL field.
+            </li>
+            <li>
+              Click <strong>Register</strong> at the bottom.
+            </li>
+            <li>
+              On the <strong>Overview</strong> page that opens, copy the <strong>Application (client) ID</strong> — you
+              will need it in Step 3.
+            </li>
+            <li>
+              On the same page, copy the <strong>Directory (tenant) ID</strong> — you will need it in Step 3.
+            </li>
+            <li>
+              In the left sidebar, scroll to the <strong>Manage</strong> section and click{' '}
+              <strong>Certificates &amp; secrets</strong>.
+            </li>
+            <li>
+              Click <strong>+ New client secret</strong>. Enter a description (e.g., "Novu Bot Secret"), choose an
+              expiry period, then click <strong>Add</strong>.
+            </li>
+            <li>
+              In the <strong>Value</strong> column of the new secret, click the copy icon immediately — this value is
+              only shown once and will be hidden after you navigate away. Save it for Step 3.
+            </li>
+          </ol>
+        }
+        rightContent={
+          <div className="flex min-w-0 flex-col gap-3">
+            <SetupButton
+              href="https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps"
+              leadingIcon={
+                <ProviderIcon
+                  providerId={ChatProviderIdEnum.MsTeams}
+                  providerDisplayName="MS Teams"
+                  className="size-4 shrink-0"
+                />
+              }
+            >
+              Open App Registrations
+            </SetupButton>
+            <RedirectUriSection redirectUri={buildOAuthCallbackUrl()} />
+          </div>
+        }
+      />
+
+      {/* Step 2: Add Microsoft Graph API permissions */}
+      <SetupStep
+        index={base + 1}
+        status={deriveStepStatus(base + 1, firstIncomplete)}
+        title="Add Microsoft Graph API permissions"
         description={
-          <span>
-            {'In your App Registration, go to '}
-            <strong>Authentication</strong>
-            {' → '}
-            <strong>Add a platform</strong>
-            {' → '}
-            <strong>Web</strong>
-            {'. Paste the URL below as the Redirect URI, then click '}
-            <strong>Configure</strong>
-            {'. This is where Microsoft sends the user after they grant admin consent.'}
-          </span>
+          <ol className="flex flex-col gap-1.5 pl-4 [list-style:decimal]">
+            <li>
+              If your App Registration is still open in the Azure Portal, in the left sidebar scroll to the{' '}
+              <strong>Manage</strong> section and click <strong>API permissions</strong>. Otherwise, click{' '}
+              <strong>Open App Registrations</strong>, find the app you just created (e.g., "{agent.name}"), click on
+              it, then in the left sidebar scroll to <strong>Manage</strong> and click <strong>API permissions</strong>.
+            </li>
+            <li>
+              Click <strong>+ Add a permission</strong>.
+            </li>
+            <li>
+              Select <strong>Microsoft Graph</strong>, then choose <strong>Application permissions</strong>.
+            </li>
+            <li>
+              Search for and check the <strong>required</strong> permissions, then click{' '}
+              <strong>Add permissions</strong>:
+              <ul className="mt-1.5 flex flex-col gap-1 pl-4 [list-style:disc]">
+                <li>
+                  <code className="font-code text-[11px]">Team.ReadBasic.All</code>
+                </li>
+                <li>
+                  <code className="font-code text-[11px]">Channel.ReadBasic.All</code>
+                </li>
+                <li>
+                  <code className="font-code text-[11px]">AppCatalog.Read.All</code>
+                </li>
+              </ul>
+            </li>
+            <li>
+              <strong>Recommended:</strong> While still in <strong>Application permissions</strong>, also search for and
+              add these two optional permissions before clicking <strong>Add permissions</strong>:
+              <ul className="mt-1.5 flex flex-col gap-1 pl-4 [list-style:disc]">
+                <li>
+                  <code className="font-code text-[11px]">TeamsAppInstallation.ReadWriteSelfForTeam.All</code>
+                  <span className="text-text-soft">
+                    {' '}
+                    — allows the bot to install itself into Teams channels automatically. Without it, users must add the
+                    bot to each channel manually.
+                  </span>
+                </li>
+                <li>
+                  <code className="font-code text-[11px]">TeamsAppInstallation.ReadWriteSelfForUser.All</code>
+                  <span className="text-text-soft">
+                    {' '}
+                    — allows the bot to install itself for individual users automatically. Without it, users must
+                    manually install the bot before they can receive direct messages.
+                  </span>
+                </li>
+              </ul>
+            </li>
+            <li>
+              Back on the API permissions page, click <strong>Grant admin consent for [your organization]</strong> and
+              confirm when prompted.{' '}
+              <span className="text-text-soft">
+                (Requires Global Admin or Privileged Role Administrator rights — ask your IT admin if you don't see this
+                button.)
+              </span>
+            </li>
+            <li>
+              Verify that all permissions show a green checkmark under the <strong>Status</strong> column.
+            </li>
+          </ol>
+        }
+        rightContent={
+          <SetupButton href="https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps">
+            Open App Registrations
+          </SetupButton>
         }
-        rightContent={<RedirectUriSection redirectUri={buildOAuthCallbackUrl()} />}
       />
 
+      {/* Step 3: Configure credentials */}
       <SetupStep
-        index={base + 3}
-        status={deriveStepStatus(base + 3, firstIncomplete)}
+        index={base + 2}
+        status={deriveStepStatus(base + 2, firstIncomplete)}
         title="Configure credentials"
-        description="Copy the App ID, Client Secret, and Tenant ID from your Azure Bot registration into the integration."
+        description={
+          <ol className="flex flex-col gap-1.5 pl-4 [list-style:decimal]">
+            <li>
+              Click the <strong>Configure credentials</strong> button to open the credentials panel.
+            </li>
+            <li>
+              Paste the <strong>Application (client) ID</strong> from Step 1 into the <strong>Microsoft App ID</strong>{' '}
+              field.
+            </li>
+            <li>
+              Paste the <strong>Client Secret value</strong> from Step 1 into the <strong>Client Secret</strong> field.
+            </li>
+            <li>
+              Paste the <strong>Directory (tenant) ID</strong> from Step 1 into the{' '}
+              <strong>Directory (tenant) ID</strong> field.
+            </li>
+            <li>
+              Click <strong>Save Changes</strong>.
+            </li>
+          </ol>
+        }
         rightContent={
           <SetupButton
             leadingIcon={<RiKey2Line className="size-3.5" />}
@@ -331,29 +1340,90 @@ export function TeamsSetupGuide({
             Configure credentials
           </SetupButton>
         }
+      />
+
+      {/* Step 4: Deploy the Azure Bot */}
+      <SetupStep
+        index={base + 3}
+        status={deriveStepStatus(base + 3, firstIncomplete)}
+        title="Deploy the Azure Bot to your subscription"
+        description={
+          <div className="flex flex-col gap-3">
+            <ol className="flex flex-col gap-1.5 pl-4 [list-style:decimal]">
+              <li>
+                Click <strong>Deploy to Azure</strong> — this opens the Azure Portal with a pre-filled deployment
+                template.
+              </li>
+              <li>
+                Select the <strong>Subscription</strong> you want to deploy the bot into.
+              </li>
+              <li>
+                Review the pre-filled parameters: resource group, bot name, App ID, Tenant ID, and messaging endpoint.
+                They are already populated from the credentials you saved.
+              </li>
+              <li>
+                Click <strong>Review + create</strong>, check the summary, then click <strong>Create</strong>.
+              </li>
+              <li>Wait for the deployment to complete (usually 1–2 minutes), then return here.</li>
+            </ol>
+            <ManualBotDeployFallback webhookUrl={webhookUrl} />
+          </div>
+        }
+        rightContent={
+          <div className="flex min-w-0 flex-col gap-3">
+            <SetupButton
+              leadingIcon={
+                isDeploying ? null : (
+                  <ProviderIcon
+                    providerId={ChatProviderIdEnum.MsTeams}
+                    providerDisplayName="MS Teams"
+                    className="size-4 shrink-0"
+                  />
+                )
+              }
+              onClick={handleDeployToAzure}
+              disabled={!hasCredentials || isDeploying}
+            >
+              {isDeploying ? 'Opening Azure Portal…' : 'Deploy to Azure'}
+            </SetupButton>
+            {!hasCredentials && (
+              <p className="text-text-soft text-label-xs">Configure credentials in step {base + 2} first.</p>
+            )}
+            {hasDeployedBot && <CheckpointRow label="Azure Bot deployment initiated" status="ready" />}
+          </div>
+        }
         extraContent={
           <InlineToast
             className="mt-2 w-full"
             variant="tip"
-            title="Where to find these:"
-            description="App ID is on the Bot Configuration page. For the secret, click Manage Password → Certificates & secrets → New client secret and copy the Value immediately — it's only shown once. Tenant ID is on the App Registration Overview page."
+            title="What this deploys:"
+            description="An Azure Bot resource (F0 free tier, Single Tenant) with your messaging endpoint pre-filled and the Microsoft Teams channel enabled. Your App ID and Tenant ID are pre-populated from the credentials you saved."
           />
         }
       />
 
+      {/* Step 5: Download the Teams app package */}
       <SetupStep
         index={base + 4}
         status={deriveStepStatus(base + 4, firstIncomplete)}
-        title="Set the messaging endpoint and enable Teams"
-        description="In your Azure Bot, go to Configuration → paste the endpoint below. Then go to Channels → enable Microsoft Teams."
-        rightContent={<WebhookUrlSection webhookUrl={webhookUrl} />}
-      />
-
-      <SetupStep
-        index={base + 5}
-        status={deriveStepStatus(base + 5, firstIncomplete)}
         title="Download the Teams app package"
-        description="We've generated a ready-to-upload app package with your manifest and placeholder icons. Before deploying to production, replace the icons and update the developer fields in manifest.json with your company info."
+        description={
+          <ol className="flex flex-col gap-1.5 pl-4 [list-style:decimal]">
+            <li>
+              Click <strong>Download app package</strong> to save the{' '}
+              <code className="font-code text-[11px]">.zip</code> file to your computer.
+            </li>
+            <li>
+              <span className="text-text-soft">
+                (For production) Unzip the file and replace <code className="font-code text-[11px]">color.png</code>{' '}
+                (192×192 px) and <code className="font-code text-[11px]">outline.png</code> (32×32 px) with your company
+                icons, and update the <code className="font-code text-[11px]">developer</code> fields in{' '}
+                <code className="font-code text-[11px]">manifest.json</code> with your company name and URLs. Re-zip the
+                three files before uploading.
+              </span>
+            </li>
+          </ol>
+        }
         rightContent={
           <div className="flex min-w-0 flex-col gap-3 self-stretch">
             <div className="self-start">
@@ -378,94 +1448,154 @@ export function TeamsSetupGuide({
         }
       />
 
+      {/* Step 6: Upload to Teams and verify */}
       <SetupStep
-        index={base + 6}
-        status={deriveStepStatus(base + 6, firstIncomplete)}
+        index={base + 5}
+        status={deriveStepStatus(base + 5, firstIncomplete)}
         title="Upload to Teams and verify"
         description={
-          <div className="flex flex-col gap-2">
-            <p>
-              {'In Teams, click '}
-              <strong>Apps</strong>
-              {' in the sidebar → '}
-              <strong>Manage your apps</strong>
-              {' → '}
-              <strong>Upload an app</strong>
-              {' → '}
-              <strong>Upload a custom app</strong>
-              {' and select the downloaded '}
-              <code className="font-code text-[11px]">.zip</code>
-              {' file. Then use the button to grant admin consent and verify the connection.'}
-            </p>
-          </div>
-        }
-        rightContent={
-          user?.externalId && currentEnvironment?.identifier ? (
-            <NovuProvider
-              subscriber={{
-                subscriberId: `${user.externalId}:agent-quickstart:${agent._id}`,
-                firstName: user.firstName ?? '',
-                lastName: user.lastName ?? '',
-                avatar: user.imageUrl ?? '',
-              }}
-              applicationIdentifier={currentEnvironment.identifier}
-              apiUrl={apiHostnameManager.getHostname()}
-              socketUrl={apiHostnameManager.getWebSocketHostname()}
-            >
-              <MsTeamsConnectButton
-                integrationIdentifier={integrationIdentifier}
-                connectionIdentifier={`${user.externalId}:agent-quickstart:${agent._id}`}
-                connectLabel={`Connect ${agent.name} ↗`}
-                connectedLabel="Connected to MS Teams"
-                onConnectSuccess={handleConnected}
-              />
-            </NovuProvider>
-          ) : null
-        }
-        extraContent={
-          <div className="mt-2 flex flex-col gap-2">
-            <InlineToast
-              className="w-full"
-              variant="tip"
-              title="Organization-wide:"
-              description={
-                <span>
-                  {'For org deployment, use the '}
+          <div className="flex flex-col gap-4">
+            <div className="flex flex-col gap-2">
+              <p className="text-text-strong text-label-xs font-medium">
+                Option A — Organization-wide (recommended for production)
+              </p>
+              <ol className="flex flex-col gap-1.5 pl-4 [list-style:decimal]">
+                <li>
+                  Go to the{' '}
                   <a
                     href="https://admin.teams.microsoft.com/"
                     target="_blank"
                     rel="noopener noreferrer"
-                    className="underline underline-offset-2"
+                    className="text-primary underline underline-offset-2"
                   >
                     Teams Admin Center
                   </a>
-                  {' → Teams apps → Manage apps → Upload new app.'}
-                </span>
-              }
-            />
-            <InlineToast
-              className="w-full"
-              variant="tip"
-              title="Link individual users:"
-              description={
-                <>
-                  {'Novu provides a '}
-                  <code className="font-code text-[12px] tracking-[-0.24px]">{'<MsTeamsLinkUser />'}</code>
-                  {' component to let your subscribers link their Teams identity for direct-message notifications. '}
-                  <a
-                    href="https://docs.novu.co"
-                    target="_blank"
-                    rel="noopener noreferrer"
-                    className="underline underline-offset-2"
-                  >
-                    Read docs
-                  </a>
-                </>
-              }
-            />
+                  .
+                </li>
+                <li>
+                  In the left sidebar, expand <strong>Teams apps</strong> and click <strong>Manage apps</strong>.
+                </li>
+                <li>
+                  Click <strong>Actions</strong>, then click <strong>Upload new app</strong> (or{' '}
+                  <strong>+ Upload</strong> depending on the portal version).
+                </li>
+                <li>
+                  Click <strong>Upload</strong>, then select the downloaded{' '}
+                  <code className="font-code text-[11px]">.zip</code> file.
+                </li>
+                <li>
+                  Wait for the upload to finish. It can take some time, and a success modal appears when it completes.
+                </li>
+                <li>
+                  Find the app in the list. If it is not already unblocked, select it and set its{' '}
+                  <strong>Status</strong> to <strong>Unblocked</strong>.
+                </li>
+              </ol>
+            </div>
+            <div className="flex flex-col gap-2">
+              <p className="text-text-strong text-label-xs font-medium">
+                Option B — Personal sideload (for testing only)
+              </p>
+              <ol className="flex flex-col gap-1.5 pl-4 [list-style:decimal]">
+                <li>Open Microsoft Teams.</li>
+                <li>
+                  Click <strong>Apps</strong> in the left sidebar.
+                </li>
+                <li>
+                  Click <strong>Manage your apps</strong> at the bottom of the panel.
+                </li>
+                <li>
+                  Click <strong>Upload an app</strong>, then select <strong>Upload a custom app</strong>.
+                </li>
+                <li>
+                  Choose the downloaded <code className="font-code text-[11px]">.zip</code> file.
+                </li>
+                <li>
+                  In the app modal, click <strong>Add</strong>.
+                </li>
+              </ol>
+            </div>
+            {manualHealth?.teamsAppCatalog != null && (
+              <CheckpointRow
+                label={
+                  manualHealth.teamsAppCatalog === 'ready'
+                    ? 'App found in Teams catalog'
+                    : 'Waiting for app in Teams catalog…'
+                }
+                status={manualHealth.teamsAppCatalog}
+              />
+            )}
           </div>
         }
       />
+
+      {/* Step 7: Connect Novu to MS Teams */}
+      <SetupStep
+        index={base + 6}
+        status={deriveStepStatus(base + 6, firstIncomplete)}
+        title="Connect Novu to MS Teams"
+        description="Grant admin consent and verify the connection by signing in with a Microsoft account that has Teams admin permissions."
+        rightContent={
+          <div className="flex min-w-0 flex-col gap-3">
+            {hasCredentials && user?.externalId && currentEnvironment?.identifier ? (
+              <NovuProvider
+                subscriber={{
+                  subscriberId: `${user.externalId}:agent-quickstart:${agent._id}`,
+                  firstName: user.firstName ?? '',
+                  lastName: user.lastName ?? '',
+                  avatar: user.imageUrl ?? '',
+                }}
+                applicationIdentifier={currentEnvironment.identifier}
+                apiUrl={apiHostnameManager.getHostname()}
+                socketUrl={apiHostnameManager.getWebSocketHostname()}
+              >
+                <ConnectAndLinkSection
+                  integrationIdentifier={integrationIdentifier}
+                  connectionIdentifier={`${user.externalId}:agent-quickstart:${agent._id}`}
+                  connectLabel={`Connect ${agent.name} ↗`}
+                  onFullyConnected={handleConnected}
+                />
+              </NovuProvider>
+            ) : (
+              <>
+                <SetupButton disabled>{`Connect ${agent.name} ↗`}</SetupButton>
+                {!hasCredentials && <p className="text-text-soft text-label-xs">Complete step {base + 2} first.</p>}
+                {manualHealth?.teamsAppCatalog !== 'ready' && (
+                  <p className="text-text-soft text-label-xs">Complete step {base + 5} first.</p>
+                )}
+              </>
+            )}
+          </div>
+        }
+        extraContent={
+          <InlineToast
+            className="mt-2 w-full"
+            variant="tip"
+            title="How your users connect:"
+            description={
+              <>
+                {'A '}
+                <strong>Teams admin</strong>
+                {' must connect once using '}
+                <code className="font-code text-[12px] tracking-[-0.24px]">{'<MsTeamsConnectButton />'}</code>
+                {' to grant tenant-wide consent. Each '}
+                <strong>end user</strong>
+                {' then links their personal Teams identity using '}
+                <code className="font-code text-[12px] tracking-[-0.24px]">{'<MsTeamsLinkUser />'}</code>
+                {' so Novu can deliver notifications directly to them. '}
+                <a
+                  href="https://docs.novu.co"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-text-sub underline"
+                >
+                  Read docs
+                </a>
+              </>
+            }
+          />
+        }
+      />
     </>
   );
 
@@ -489,9 +1619,18 @@ export function TeamsSetupGuide({
     />
   );
 
+  const modeToggle = (
+    <div className="mb-2 flex items-start">
+      <SetupModeToggle mode={setupMode} onChange={setSetupMode} />
+    </div>
+  );
+
+  const activeSteps = activeSetupMode === 'quick' ? quickSteps : steps;
+
   if (embedded) {
     return (
       <div className="flex flex-col gap-0">
+        {isQuickSetupEnabled && <div className="px-6 pt-4 pb-2">{modeToggle}</div>}
         <div className={cn('relative flex flex-col gap-10 py-6 pb-3 pl-8 pr-6')}>
           <div
             className="absolute bottom-0 left-[22px] top-0 w-px"
@@ -499,7 +1638,7 @@ export function TeamsSetupGuide({
               background: 'linear-gradient(to bottom, transparent 0%, #E1E4EA 10%, #E1E4EA 90%, transparent 100%)',
             }}
           />
-          {steps}
+          {activeSteps}
         </div>
         {listening}
         {credentialsSidebar}
@@ -509,7 +1648,8 @@ export function TeamsSetupGuide({
 
   return (
     <>
-      {steps}
+      {isQuickSetupEnabled && modeToggle}
+      {activeSteps}
       {listening}
       {credentialsSidebar}
     </>
diff --git a/apps/dashboard/src/utils/build-zip.ts b/apps/dashboard/src/utils/build-zip.ts
new file mode 100644
index 00000000000..0195e53daa0
--- /dev/null
+++ b/apps/dashboard/src/utils/build-zip.ts
@@ -0,0 +1,69 @@
+/**
+ * Minimal store-only ZIP builder for the browser (no compression, no dependencies).
+ * Uses Uint8Array / DataView / Blob — works in all modern browsers.
+ */
+
+function crc32(data: Uint8Array): number {
+  let crc = 0xffffffff;
+
+  for (let i = 0; i < data.length; i++) {
+    crc ^= data[i];
+    for (let j = 0; j < 8; j++) {
+      crc = crc & 1 ? (crc >>> 1) ^ 0xedb88320 : crc >>> 1;
+    }
+  }
+
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+export type BrowserZipEntry = { name: string; data: Uint8Array };
+
+export function buildZip(files: BrowserZipEntry[]): Blob {
+  const parts: Uint8Array[] = [];
+  const centralEntries: Uint8Array[] = [];
+  let offset = 0;
+
+  for (const file of files) {
+    const nameBytes = new TextEncoder().encode(file.name);
+    const crc = crc32(file.data);
+
+    const local = new ArrayBuffer(30 + nameBytes.length);
+    const lv = new DataView(local);
+    lv.setUint32(0, 0x04034b50, true);
+    lv.setUint16(4, 20, true);
+    lv.setUint16(8, 0, true);
+    lv.setUint32(14, crc, true);
+    lv.setUint32(18, file.data.length, true);
+    lv.setUint32(22, file.data.length, true);
+    lv.setUint16(26, nameBytes.length, true);
+    new Uint8Array(local).set(nameBytes, 30);
+
+    parts.push(new Uint8Array(local), file.data);
+
+    const central = new ArrayBuffer(46 + nameBytes.length);
+    const cv = new DataView(central);
+    cv.setUint32(0, 0x02014b50, true);
+    cv.setUint16(4, 20, true);
+    cv.setUint16(6, 20, true);
+    cv.setUint32(16, crc, true);
+    cv.setUint32(20, file.data.length, true);
+    cv.setUint32(24, file.data.length, true);
+    cv.setUint16(28, nameBytes.length, true);
+    cv.setUint32(42, offset, true);
+    new Uint8Array(central).set(nameBytes, 46);
+
+    centralEntries.push(new Uint8Array(central));
+    offset += 30 + nameBytes.length + file.data.length;
+  }
+
+  const centralSize = centralEntries.reduce((s, e) => s + e.length, 0);
+  const eocd = new ArrayBuffer(22);
+  const ev = new DataView(eocd);
+  ev.setUint32(0, 0x06054b50, true);
+  ev.setUint16(8, files.length, true);
+  ev.setUint16(10, files.length, true);
+  ev.setUint32(12, centralSize, true);
+  ev.setUint32(16, offset, true);
+
+  return new Blob([...parts, ...centralEntries, new Uint8Array(eocd)] as BlobPart[], { type: 'application/zip' });
+}
diff --git a/libs/application-generic/src/utils/build-zip.ts b/libs/application-generic/src/utils/build-zip.ts
new file mode 100644
index 00000000000..994480f5054
--- /dev/null
+++ b/libs/application-generic/src/utils/build-zip.ts
@@ -0,0 +1,86 @@
+/**
+ * Minimal store-only ZIP builder (no compression).
+ * Suitable for small payloads where the files are already compressed (e.g. PNGs)
+ * or the JSON is tiny enough that compression adds no value.
+ */
+
+function crc32(data: Buffer): number {
+  let crc = 0xffffffff;
+
+  for (let i = 0; i < data.length; i++) {
+    crc ^= data[i];
+    for (let j = 0; j < 8; j++) {
+      crc = crc & 1 ? (crc >>> 1) ^ 0xedb88320 : crc >>> 1;
+    }
+  }
+
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+export interface ZipEntry {
+  name: string;
+  data: Buffer;
+}
+
+export function buildZip(files: ZipEntry[]): Buffer {
+  const parts: Buffer[] = [];
+  const centralEntries: Buffer[] = [];
+  let offset = 0;
+
+  for (const file of files) {
+    const nameBytes = Buffer.from(file.name, 'utf-8');
+    const crc = crc32(file.data);
+
+    const local = Buffer.allocUnsafe(30 + nameBytes.length);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0, 6);
+    local.writeUInt16LE(0, 8);
+    local.writeUInt16LE(0, 10);
+    local.writeUInt16LE(0, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(file.data.length, 18);
+    local.writeUInt32LE(file.data.length, 22);
+    local.writeUInt16LE(nameBytes.length, 26);
+    local.writeUInt16LE(0, 28);
+    nameBytes.copy(local, 30);
+
+    parts.push(local, file.data);
+
+    const central = Buffer.allocUnsafe(46 + nameBytes.length);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE(20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(0, 8);
+    central.writeUInt16LE(0, 10);
+    central.writeUInt16LE(0, 12);
+    central.writeUInt16LE(0, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(file.data.length, 20);
+    central.writeUInt32LE(file.data.length, 24);
+    central.writeUInt16LE(nameBytes.length, 28);
+    central.writeUInt16LE(0, 30);
+    central.writeUInt16LE(0, 32);
+    central.writeUInt16LE(0, 34);
+    central.writeUInt16LE(0, 36);
+    central.writeUInt32LE(0, 38);
+    central.writeUInt32LE(offset, 42);
+    nameBytes.copy(central, 46);
+
+    centralEntries.push(central);
+    offset += 30 + nameBytes.length + file.data.length;
+  }
+
+  const centralSize = centralEntries.reduce((s, e) => s + e.length, 0);
+  const eocd = Buffer.allocUnsafe(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(files.length, 8);
+  eocd.writeUInt16LE(files.length, 10);
+  eocd.writeUInt32LE(centralSize, 12);
+  eocd.writeUInt32LE(offset, 16);
+  eocd.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...parts, ...centralEntries, eocd]);
+}
diff --git a/libs/application-generic/src/utils/index.ts b/libs/application-generic/src/utils/index.ts
index 221488ab899..66e9f25805e 100644
--- a/libs/application-generic/src/utils/index.ts
+++ b/libs/application-generic/src/utils/index.ts
@@ -2,7 +2,7 @@ export * from './base62';
 export * from './bridge';
 export * from './build-slug';
 export * from './build-variables';
-export * from './slugify-or-random';
+export * from './build-zip';
 export * from './buildBridgeEndpointUrl';
 export * from './compute-workflow-status';
 export * from './create-schema';
@@ -30,6 +30,7 @@ export * from './object';
 export * from './parse-payload-schema';
 export * from './parse-step-variables';
 export * from './sanitize-control-values';
+export * from './slugify-or-random';
 export * from './ssrf-url-validation';
 export * from './step-resolver-control-state';
 export * from './step-type-to-control.mapper';
diff --git a/libs/dal/src/repositories/integration/integration.entity.ts b/libs/dal/src/repositories/integration/integration.entity.ts
index ff1224a21d6..8e5495adf67 100644
--- a/libs/dal/src/repositories/integration/integration.entity.ts
+++ b/libs/dal/src/repositories/integration/integration.entity.ts
@@ -8,6 +8,15 @@ export type ICredentialsEntity = ICredentials;
 
 export type ConfigConfigurationEntity = IConfigurations;
 
+export interface IProvisioningState {
+  status: 'pending' | 'ready' | 'failed';
+  startedAt?: string;
+  completedAt?: string;
+  errorMessage?: string;
+  /** Internal Teams app catalog ID returned by Graph POST /appCatalogs/teamsApps. Used to build the add-to-Teams deep link. */
+  teamsAppCatalogId?: string;
+}
+
 export class IntegrationEntity {
   _id: string;
 
@@ -23,6 +32,8 @@ export class IntegrationEntity {
 
   configurations?: ConfigConfigurationEntity;
 
+  provisioning?: IProvisioningState;
+
   active: boolean;
 
   name: string;
diff --git a/libs/dal/src/repositories/integration/integration.schema.ts b/libs/dal/src/repositories/integration/integration.schema.ts
index e26cc1b226f..312ab4b9e96 100644
--- a/libs/dal/src/repositories/integration/integration.schema.ts
+++ b/libs/dal/src/repositories/integration/integration.schema.ts
@@ -79,6 +79,16 @@ const integrationSchema = new Schema<IntegrationDBModel>(
       configurationSetName: Schema.Types.String,
       inboxCount: Schema.Types.String,
     },
+    provisioning: {
+      status: {
+        type: Schema.Types.String,
+        enum: ['pending', 'ready', 'failed'],
+      },
+      startedAt: Schema.Types.String,
+      completedAt: Schema.Types.String,
+      errorMessage: Schema.Types.String,
+      teamsAppCatalogId: Schema.Types.String,
+    },
     active: {
       type: Schema.Types.Boolean,
       default: false,
diff --git a/packages/shared/src/types/feature-flags.ts b/packages/shared/src/types/feature-flags.ts
index 9669fd53c6a..45504e6cf2c 100644
--- a/packages/shared/src/types/feature-flags.ts
+++ b/packages/shared/src/types/feature-flags.ts
@@ -93,6 +93,8 @@ export enum FeatureFlagsKeysEnum {
   IS_ACTION_STEP_RESOLVER_ENABLED = 'IS_ACTION_STEP_RESOLVER_ENABLED',
   /** Enable conversational Agents UI in the dashboard; create the boolean in LaunchDarkly for cloud, or set `VITE_IS_CONVERSATIONAL_AGENTS_ENABLED` when self-hosted. */
   IS_CONVERSATIONAL_AGENTS_ENABLED = 'IS_CONVERSATIONAL_AGENTS_ENABLED',
+  /** Enable Microsoft Teams Quick Setup in the dashboard; create the boolean in LaunchDarkly for cloud, or set `VITE_IS_MSTEAMS_QUICK_SETUP_ENABLED` when self-hosted. */
+  IS_MSTEAMS_QUICK_SETUP_ENABLED = 'IS_MSTEAMS_QUICK_SETUP_ENABLED',
   /** Enable the Domains management page in the dashboard. */
   IS_DOMAINS_PAGE_ENABLED = 'IS_DOMAINS_PAGE_ENABLED',
   /** Enable Domain Connect auto-configuration for inbound email domains. */

From 0684c0a738b449dd54b742abd9779fd15d1b0867 Mon Sep 17 00:00:00 2001
From: "cursor[bot]" <206951365+cursor[bot]@users.noreply.github.com>
Date: Mon, 4 May 2026 10:55:59 +0300
Subject: [PATCH 2/6] fix(root): resolve high @clerk/clerk-react &
 @clerk/shared vulnerability fixes NV-7470 (#10965)

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Dima Grossman <dima@grossman.io>
---
 apps/dashboard/package.json |  2 +-
 package.json                |  2 +-
 pnpm-lock.yaml              | 25 ++++++++++++-------------
 3 files changed, 14 insertions(+), 15 deletions(-)

diff --git a/apps/dashboard/package.json b/apps/dashboard/package.json
index e3c0cc98b81..be0976e3510 100644
--- a/apps/dashboard/package.json
+++ b/apps/dashboard/package.json
@@ -29,7 +29,7 @@
     "@ai-sdk/react": "^3.0.51",
     "@better-auth/sso": "^1.3.0",
     "@calcom/embed-react": "1.5.2",
-    "@clerk/clerk-react": "^5.59.3",
+    "@clerk/clerk-react": "^5.61.6",
     "@codemirror/autocomplete": "^6.18.3",
     "@codemirror/lang-html": "^6.4.9",
     "@codemirror/lang-liquid": "^6.2.3",
diff --git a/package.json b/package.json
index 922306d798f..57f5e097827 100644
--- a/package.json
+++ b/package.json
@@ -274,7 +274,7 @@
       "esbuild@<0.25.0": "^0.25.0",
       "follow-redirects@<=1.15.11": "^1.16.0",
       "@clerk/shared@>=2.20.17 <2.22.1": "^2.22.1",
-      "@clerk/shared@>=3.0.0-canary.v20250225091530 <3.47.4": "^3.47.4",
+      "@clerk/shared@>=3.0.0-canary.v20250225091530 <3.47.5": "^3.47.5",
       "protobufjs@<7.5.5": "^7.5.5",
       "protobufjs@>=8.0.0 <8.0.1": "^8.0.1",
       "newrelic": "13.18.0"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8437317ddc6..13d7590be90 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -126,7 +126,7 @@ overrides:
   esbuild@<0.25.0: ^0.25.0
   follow-redirects@<=1.15.11: ^1.16.0
   '@clerk/shared@>=2.20.17 <2.22.1': ^2.22.1
-  '@clerk/shared@>=3.0.0-canary.v20250225091530 <3.47.4': ^3.47.4
+  '@clerk/shared@>=3.0.0-canary.v20250225091530 <3.47.5': ^3.47.5
   protobufjs@<7.5.5: ^7.5.5
   protobufjs@>=8.0.0 <8.0.1: ^8.0.1
   newrelic: 13.18.0
@@ -720,8 +720,8 @@ importers:
         specifier: 1.5.2
         version: 1.5.2(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       '@clerk/clerk-react':
-        specifier: ^5.59.3
-        version: 5.59.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+        specifier: ^5.61.6
+        version: 5.61.6(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       '@codemirror/autocomplete':
         specifier: ^6.18.3
         version: 6.18.3(@codemirror/language@6.11.1)(@codemirror/state@6.4.1)(@codemirror/view@6.34.3)(@lezer/common@1.2.3)
@@ -6271,10 +6271,9 @@ packages:
     resolution: {integrity: sha512-habBg77Nss4xhN+hvw3pbNxjRdEdKIUINpLRo2kHrvg7ZcKIux+75H283yQPE728hTwaKGxUnIEISgH4NLjeQw==}
     engines: {node: '>=18.17.0'}
 
-  '@clerk/clerk-react@5.59.3':
-    resolution: {integrity: sha512-r1gmAYxhXs+QkXjDwj5Eqvm0Io8PtJ4FKkA45khiAzIQXcaQLFq/wFy7d1K8OSIYAIdFbuO0bnIOU/FdgWOc+A==}
+  '@clerk/clerk-react@5.61.6':
+    resolution: {integrity: sha512-OiyBlrnkRr9IhZtPd7EwlzhYScBpvNKJ8lgg7Uw6JElzJYz854IeQaez5mAfpiib3LcW/Dn53E2PQhagcuLJ3Q==}
     engines: {node: '>=18.17.0'}
-    deprecated: 'This package is no longer supported. Please use @clerk/react instead. See the upgrade guide for more info: https://clerk.com/docs/guides/development/upgrading/upgrade-guides/core-3'
     peerDependencies:
       react: ^18.0.0 || ~19.0.3 || ~19.1.4 || ~19.2.3 || ~19.3.0-0
       react-dom: ^18.0.0 || ~19.0.3 || ~19.1.4 || ~19.2.3 || ~19.3.0-0
@@ -6297,8 +6296,8 @@ packages:
       react-dom:
         optional: true
 
-  '@clerk/shared@3.47.4':
-    resolution: {integrity: sha512-0O5/zgB5SO26PKarAIw7uj4j+4JsnT2/uiJ7SPI3LQMb62sM+AjDlVadcXuYc+4sY6w1szrAIVepI5Bkv57hnQ==}
+  '@clerk/shared@3.47.5':
+    resolution: {integrity: sha512-rDVe73/VN2NZXhtrLRHshkUpQDrevAqDRxeXUl2M0IBEBkcl+VMHlV7fep53cVWo0b3gIqLk82pmmi+WoyF/xg==}
     engines: {node: '>=18.17.0'}
     peerDependencies:
       react: ^18.0.0 || ~19.0.3 || ~19.1.4 || ~19.2.3 || ~19.3.0-0
@@ -31471,7 +31470,7 @@ snapshots:
 
   '@clerk/backend@1.25.2(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
     dependencies:
-      '@clerk/shared': 3.47.4(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@clerk/shared': 3.47.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       '@clerk/types': 4.48.0
       cookie: 1.0.2
       snakecase-keys: 8.0.1
@@ -31480,9 +31479,9 @@ snapshots:
       - react
       - react-dom
 
-  '@clerk/clerk-react@5.59.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
+  '@clerk/clerk-react@5.61.6(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
     dependencies:
-      '@clerk/shared': 3.47.4(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@clerk/shared': 3.47.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       react: 19.2.3
       react-dom: 19.2.3(react@19.2.3)
       tslib: 2.8.1
@@ -31490,7 +31489,7 @@ snapshots:
   '@clerk/express@1.3.53(express@5.0.1)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
     dependencies:
       '@clerk/backend': 1.25.2(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
-      '@clerk/shared': 3.47.4(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@clerk/shared': 3.47.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       '@clerk/types': 4.48.0
       express: 5.0.1
       tslib: 2.4.1
@@ -31510,7 +31509,7 @@ snapshots:
       react: 19.2.3
       react-dom: 19.2.3(react@19.2.3)
 
-  '@clerk/shared@3.47.4(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
+  '@clerk/shared@3.47.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
     dependencies:
       csstype: 3.1.3
       dequal: 2.0.3

From 6d5fd3701f96b0b7bf593d978b14a54669bf0f3b Mon Sep 17 00:00:00 2001
From: "cursor[bot]" <206951365+cursor[bot]@users.noreply.github.com>
Date: Mon, 4 May 2026 10:56:15 +0300
Subject: [PATCH 3/6] fix(api-service): treat context.dev 'Domain branding not
 present' as not_available fixes NV-7472 (#10966)

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Dima Grossman <dima@grossman.io>
---
 .../brand-retrieval.service.spec.ts           | 104 ++++++++++++++++++
 .../brand-retrieval.service.ts                |  28 ++++-
 2 files changed, 131 insertions(+), 1 deletion(-)
 create mode 100644 apps/api/src/app/organization/usecases/enrich-organization-brand/brand-retrieval.service.spec.ts

diff --git a/apps/api/src/app/organization/usecases/enrich-organization-brand/brand-retrieval.service.spec.ts b/apps/api/src/app/organization/usecases/enrich-organization-brand/brand-retrieval.service.spec.ts
new file mode 100644
index 00000000000..2ebd1da72c5
--- /dev/null
+++ b/apps/api/src/app/organization/usecases/enrich-organization-brand/brand-retrieval.service.spec.ts
@@ -0,0 +1,104 @@
+import { expect } from 'chai';
+import ContextDev from 'context.dev';
+import { restore, stub } from 'sinon';
+
+import { BrandRetrievalService } from './brand-retrieval.service';
+
+describe('BrandRetrievalService', () => {
+  let service: BrandRetrievalService;
+  let loggerMock: {
+    setContext: sinon.SinonStub;
+    info: sinon.SinonStub;
+    warn: sinon.SinonStub;
+  };
+  let retrieveStub: sinon.SinonStub;
+
+  beforeEach(() => {
+    loggerMock = {
+      setContext: stub(),
+      info: stub(),
+      warn: stub(),
+    };
+
+    retrieveStub = stub();
+    service = new BrandRetrievalService(loggerMock as any);
+    // Wire a fake client directly since `initialize()` is gated on an env var
+    // and the live SDK's retrieve behaviour is what we want to exercise here.
+    (service as any).client = { brand: { retrieve: retrieveStub } };
+  });
+
+  afterEach(() => restore());
+
+  it('returns an empty result when context.dev responds with "Domain branding not present"', async () => {
+    const apiError = Object.create(ContextDev.APIError.prototype);
+    apiError.status = 400;
+    apiError.message = '400 Domain branding not present [example.com]';
+    retrieveStub.rejects(apiError);
+
+    const result = await service.retrieveBrand('example.com');
+
+    expect(result).to.deep.equal({});
+    expect(loggerMock.info.calledOnce).to.equal(true);
+  });
+
+  it('returns an empty result when context.dev responds with DNS-resolution variant', async () => {
+    const apiError = Object.create(ContextDev.APIError.prototype);
+    apiError.status = 400;
+    apiError.message = '400 Domain branding not present (DNS resolution failed) [example.com]';
+    retrieveStub.rejects(apiError);
+
+    const result = await service.retrieveBrand('example.com');
+
+    expect(result).to.deep.equal({});
+  });
+
+  it('rethrows unrelated APIError responses (e.g. auth)', async () => {
+    const apiError = Object.create(ContextDev.APIError.prototype);
+    apiError.status = 401;
+    apiError.message = '401 Unauthorized';
+    retrieveStub.rejects(apiError);
+
+    let caught: unknown;
+    try {
+      await service.retrieveBrand('example.com');
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).to.equal(apiError);
+  });
+
+  it('rethrows non-APIError errors (e.g. network)', async () => {
+    const networkError = new Error('Network down');
+    retrieveStub.rejects(networkError);
+
+    let caught: unknown;
+    try {
+      await service.retrieveBrand('example.com');
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).to.equal(networkError);
+  });
+
+  it('returns the brand when the provider has a record', async () => {
+    retrieveStub.resolves({
+      brand: {
+        title: 'Acme',
+        description: 'Acme Inc.',
+        industries: {
+          eic: [{ industry: 'Software', subindustry: 'SaaS' }],
+        },
+        logos: [],
+        colors: [],
+      },
+    });
+
+    const result = await service.retrieveBrand('acme.example');
+
+    expect(result.companyTitle).to.equal('Acme');
+    expect(result.companyDescription).to.equal('Acme Inc.');
+    expect(result.industry).to.deep.equal([{ industry: 'Software', subindustry: 'SaaS' }]);
+  });
+});
diff --git a/apps/api/src/app/organization/usecases/enrich-organization-brand/brand-retrieval.service.ts b/apps/api/src/app/organization/usecases/enrich-organization-brand/brand-retrieval.service.ts
index 4030ae584a0..e124b7b5df4 100644
--- a/apps/api/src/app/organization/usecases/enrich-organization-brand/brand-retrieval.service.ts
+++ b/apps/api/src/app/organization/usecases/enrich-organization-brand/brand-retrieval.service.ts
@@ -13,6 +13,20 @@ export interface BrandData {
 
 const LOG_CONTEXT = 'BrandRetrievalService';
 
+// context.dev returns HTTP 400 with this message when the submitted domain is
+// not present in its database. This is an expected outcome for long-tail signup
+// domains — not an error worth paging on — so we treat it like an empty result.
+const BRAND_NOT_PRESENT_MARKER = 'domain branding not present';
+
+function isBrandNotPresentError(error: unknown): boolean {
+  if (!(error instanceof ContextDev.APIError)) return false;
+  if (error.status !== 400) return false;
+
+  const message = typeof error.message === 'string' ? error.message.toLowerCase() : '';
+
+  return message.includes(BRAND_NOT_PRESENT_MARKER);
+}
+
 const LOGO_TYPES = new Set<IBrandLogo['type']>(['icon', 'logo']);
 const LOGO_MODES = new Set<IBrandLogo['mode']>(['light', 'dark', 'has_opaque_background']);
 
@@ -55,7 +69,19 @@ export class BrandRetrievalService {
       return {};
     }
 
-    const response = await this.client.brand.retrieve({ domain });
+    let response;
+    try {
+      response = await this.client.brand.retrieve({ domain });
+    } catch (error) {
+      if (isBrandNotPresentError(error)) {
+        this.logger.info({ domain }, 'Brand enrichment unavailable for domain — not in provider database');
+
+        return {};
+      }
+
+      throw error;
+    }
+
     const brand = response?.brand;
 
     if (!brand) return {};

From b5365d79ec866099b53f9b045c6bfc6f360d854e Mon Sep 17 00:00:00 2001
From: "cursor[bot]" <206951365+cursor[bot]@users.noreply.github.com>
Date: Mon, 4 May 2026 13:39:16 +0200
Subject: [PATCH 4/6] chore(root): remove 5 unused files (#10968)

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Adam Chmara <adam.chmara1@gmail.com>
---
 .../auto-configure-integration-request.dto.ts |  1 -
 .../subscriber-notification-action.dto.ts     | 14 ----
 .../workflows-v2/dtos/base-step-issue.dto.ts  | 14 ----
 .../components/icons/retry-verification.tsx   | 80 -------------------
 .../src/hooks/use-diagnose-domain.ts          | 17 ----
 5 files changed, 126 deletions(-)
 delete mode 100644 apps/api/src/app/integrations/dtos/auto-configure-integration-request.dto.ts
 delete mode 100644 apps/api/src/app/subscribers-v2/dtos/subscriber-notification-action.dto.ts
 delete mode 100644 apps/api/src/app/workflows-v2/dtos/base-step-issue.dto.ts
 delete mode 100644 apps/dashboard/src/components/icons/retry-verification.tsx
 delete mode 100644 apps/dashboard/src/hooks/use-diagnose-domain.ts

diff --git a/apps/api/src/app/integrations/dtos/auto-configure-integration-request.dto.ts b/apps/api/src/app/integrations/dtos/auto-configure-integration-request.dto.ts
deleted file mode 100644
index 2b59ca68a06..00000000000
--- a/apps/api/src/app/integrations/dtos/auto-configure-integration-request.dto.ts
+++ /dev/null
@@ -1 +0,0 @@
-export class AutoConfigureIntegrationRequestDto {}
diff --git a/apps/api/src/app/subscribers-v2/dtos/subscriber-notification-action.dto.ts b/apps/api/src/app/subscribers-v2/dtos/subscriber-notification-action.dto.ts
deleted file mode 100644
index 96cc994fa7c..00000000000
--- a/apps/api/src/app/subscribers-v2/dtos/subscriber-notification-action.dto.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { ApiProperty } from '@nestjs/swagger';
-import { ButtonTypeEnum } from '@novu/shared';
-import { IsDefined, IsEnum } from 'class-validator';
-
-export class SubscriberNotificationActionDto {
-  @IsEnum(ButtonTypeEnum)
-  @IsDefined()
-  @ApiProperty({
-    description: 'The type of action button (primary or secondary)',
-    enum: ButtonTypeEnum,
-    example: ButtonTypeEnum.PRIMARY,
-  })
-  readonly actionType: ButtonTypeEnum;
-}
diff --git a/apps/api/src/app/workflows-v2/dtos/base-step-issue.dto.ts b/apps/api/src/app/workflows-v2/dtos/base-step-issue.dto.ts
deleted file mode 100644
index 2de20af4e6f..00000000000
--- a/apps/api/src/app/workflows-v2/dtos/base-step-issue.dto.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { ApiProperty } from '@nestjs/swagger';
-import { BaseIssueDto } from '@novu/application-generic';
-import { ContentIssueEnum, IntegrationIssueEnum } from '@novu/shared';
-import { IsEnum } from 'class-validator';
-
-export class StepIssueDto extends BaseIssueDto<ContentIssueEnum | IntegrationIssueEnum> {
-  @ApiProperty({
-    description: 'Type of step issue',
-    enum: [...Object.values(ContentIssueEnum), ...Object.values(IntegrationIssueEnum)],
-    enumName: 'ContentIssueEnum | IntegrationIssueEnum',
-  })
-  @IsEnum([...Object.values(ContentIssueEnum), ...Object.values(IntegrationIssueEnum)])
-  issueType: ContentIssueEnum | IntegrationIssueEnum;
-}
diff --git a/apps/dashboard/src/components/icons/retry-verification.tsx b/apps/dashboard/src/components/icons/retry-verification.tsx
deleted file mode 100644
index dea0bd881aa..00000000000
--- a/apps/dashboard/src/components/icons/retry-verification.tsx
+++ /dev/null
@@ -1,80 +0,0 @@
-import { useId } from 'react';
-
-export const RetryVerificationIcon = (props: React.ComponentPropsWithoutRef<'svg'>) => {
-  const id = useId();
-  const m1 = `${id}-m1`;
-  const m2 = `${id}-m2`;
-  const m3 = `${id}-m3`;
-  const m4 = `${id}-m4`;
-
-  return (
-    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg" {...props}>
-      <mask id={m1} fill="white">
-        <path
-          fillRule="evenodd"
-          clipRule="evenodd"
-          d="M6.24528 0.760607C6.41673 0.956551 6.39687 1.25438 6.20093 1.42583L5.14608 2.34883L6.20093 3.27182C6.39687 3.44327 6.41673 3.7411 6.24528 3.93704C6.07383 4.13299 5.77599 4.15285 5.58005 3.98139L4.11973 2.70361C4.01742 2.61409 3.95874 2.48477 3.95874 2.34883C3.95874 2.21288 4.01742 2.08356 4.11973 1.99404L5.58005 0.716258C5.77599 0.544808 6.07383 0.564663 6.24528 0.760607Z"
-        />
-      </mask>
-      <path
-        d="M6.24528 0.760607L6.99787 0.102115L6.99785 0.102095L6.24528 0.760607ZM6.20093 1.42583L5.54244 0.673244L5.54243 0.673253L6.20093 1.42583ZM5.14608 2.34883L4.48757 1.59625L3.62749 2.34883L4.48757 3.1014L5.14608 2.34883ZM6.20093 3.27182L5.54243 4.0244L5.54244 4.02441L6.20093 3.27182ZM6.24528 3.93704L6.99785 4.59556L6.99787 4.59554L6.24528 3.93704ZM5.58005 3.98139L6.23857 3.22882L6.23855 3.22881L5.58005 3.98139ZM4.11973 2.70361L3.46122 3.45619L3.46123 3.45619L4.11973 2.70361ZM4.11973 1.99404L3.46123 1.24146L3.46122 1.24146L4.11973 1.99404ZM5.58005 0.716258L6.23856 1.46884L6.23856 1.46883L5.58005 0.716258ZM6.24528 0.760607L5.49269 1.4191C5.30049 1.19943 5.32271 0.865496 5.54244 0.673244L6.20093 1.42583L6.85943 2.17841C7.47104 1.64327 7.53297 0.713675 6.99787 0.102115L6.24528 0.760607ZM6.20093 1.42583L5.54243 0.673253L4.48757 1.59625L5.14608 2.34883L5.80459 3.1014L6.85944 2.1784L6.20093 1.42583ZM5.14608 2.34883L4.48757 3.1014L5.54243 4.0244L6.20093 3.27182L6.85944 2.51925L5.80459 1.59625L5.14608 2.34883ZM6.20093 3.27182L5.54244 4.02441C5.32272 3.83216 5.30048 3.49822 5.4927 3.27855L6.24528 3.93704L6.99787 4.59554C7.53297 3.98398 7.47103 3.05438 6.85943 2.51924L6.20093 3.27182ZM6.24528 3.93704L5.49271 3.27853C5.68492 3.05886 6.01885 3.03657 6.23857 3.22882L5.58005 3.98139L4.92154 4.73396C5.53314 5.26912 6.46273 5.20711 6.99785 4.59556L6.24528 3.93704ZM5.58005 3.98139L6.23855 3.22881L4.77823 1.95104L4.11973 2.70361L3.46123 3.45619L4.92155 4.73397L5.58005 3.98139ZM4.11973 2.70361L4.77823 1.95104C4.89295 2.05142 4.95874 2.19642 4.95874 2.34883H3.95874H2.95874C2.95874 2.77312 3.14189 3.17677 3.46122 3.45619L4.11973 2.70361ZM3.95874 2.34883H4.95874C4.95874 2.50123 4.89295 2.64624 4.77823 2.74661L4.11973 1.99404L3.46122 1.24146C3.14189 1.52088 2.95874 1.92454 2.95874 2.34883H3.95874ZM4.11973 1.99404L4.77823 2.74661L6.23856 1.46884L5.58005 0.716258L4.92155 -0.0363192L3.46123 1.24146L4.11973 1.99404ZM5.58005 0.716258L6.23856 1.46883C6.01886 1.66107 5.68493 1.6388 5.49271 1.41912L6.24528 0.760607L6.99785 0.102095C6.46272 -0.509473 5.53313 -0.571453 4.92155 -0.0363184L5.58005 0.716258Z"
-        fill="#525866"
-        mask={`url(#${m1})`}
-      />
-      <mask id={m2} fill="white">
-        <path
-          fillRule="evenodd"
-          clipRule="evenodd"
-          d="M4.54285 2.38451C4.54285 2.12415 4.75391 1.91309 5.01428 1.91309H7.03182C9.2082 1.91309 10.9619 3.6992 10.9619 5.88929V6.03532C10.9619 6.29568 10.7508 6.50675 10.4905 6.50675C10.2301 6.50675 10.0191 6.29568 10.0191 6.03532V5.88929C10.0191 4.20811 8.67574 2.85594 7.03182 2.85594H5.01428C4.75391 2.85594 4.54285 2.64488 4.54285 2.38451Z"
-        />
-      </mask>
-      <path
-        fillRule="evenodd"
-        clipRule="evenodd"
-        d="M4.54285 2.38451C4.54285 2.12415 4.75391 1.91309 5.01428 1.91309H7.03182C9.2082 1.91309 10.9619 3.6992 10.9619 5.88929V6.03532C10.9619 6.29568 10.7508 6.50675 10.4905 6.50675C10.2301 6.50675 10.0191 6.29568 10.0191 6.03532V5.88929C10.0191 4.20811 8.67574 2.85594 7.03182 2.85594H5.01428C4.75391 2.85594 4.54285 2.64488 4.54285 2.38451Z"
-        fill="#0E121B"
-      />
-      <path
-        d="M4.54285 2.38451H5.54285C5.54285 2.67643 5.30619 2.91309 5.01428 2.91309V1.91309V0.913086C4.20162 0.913086 3.54285 1.57186 3.54285 2.38451H4.54285ZM5.01428 1.91309V2.91309H7.03182V1.91309V0.913086H5.01428V1.91309ZM7.03182 1.91309V2.91309C8.64302 2.91309 9.96191 4.23851 9.96191 5.88929H10.9619H11.9619C11.9619 3.15989 9.77337 0.913086 7.03182 0.913086V1.91309ZM10.9619 5.88929H9.96191V6.03532H10.9619H11.9619V5.88929H10.9619ZM10.9619 6.03532H9.96191C9.96191 5.74333 10.1986 5.50675 10.4905 5.50675V6.50675V7.50675C11.303 7.50675 11.9619 6.84804 11.9619 6.03532H10.9619ZM10.4905 6.50675V5.50675C10.7824 5.50675 11.0191 5.74345 11.0191 6.03532H10.0191H9.01906C9.01906 6.84792 9.67775 7.50675 10.4905 7.50675V6.50675ZM10.0191 6.03532H11.0191V5.88929H10.0191H9.01906V6.03532H10.0191ZM10.0191 5.88929H11.0191C11.0191 3.66775 9.23988 1.85594 7.03182 1.85594V2.85594V3.85594C8.1116 3.85594 9.01906 4.74847 9.01906 5.88929H10.0191ZM7.03182 2.85594V1.85594H5.01428V2.85594V3.85594H7.03182V2.85594ZM5.01428 2.85594V1.85594C5.30619 1.85594 5.54285 2.0926 5.54285 2.38451H4.54285H3.54285C3.54285 3.19716 4.20162 3.85594 5.01428 3.85594V2.85594Z"
-        fill="#525866"
-        mask={`url(#${m2})`}
-      />
-      <mask id={m3} fill="white">
-        <path
-          fillRule="evenodd"
-          clipRule="evenodd"
-          d="M5.82771 8.06236C5.99916 7.86642 6.29699 7.84657 6.49294 8.01801L7.95326 9.29577C8.05557 9.38535 8.11425 9.5146 8.11425 9.65055C8.11425 9.78649 8.05557 9.91583 7.95326 10.0054L6.49294 11.2831C6.29699 11.4546 5.99916 11.4348 5.82771 11.2388C5.65626 11.0429 5.67611 10.745 5.87206 10.5736L6.92691 9.65055L5.87206 8.72757C5.67611 8.55614 5.65626 8.25831 5.82771 8.06236Z"
-        />
-      </mask>
-      <path
-        fillRule="evenodd"
-        clipRule="evenodd"
-        d="M5.82771 8.06236C5.99916 7.86642 6.29699 7.84657 6.49294 8.01801L7.95326 9.29577C8.05557 9.38535 8.11425 9.5146 8.11425 9.65055C8.11425 9.78649 8.05557 9.91583 7.95326 10.0054L6.49294 11.2831C6.29699 11.4546 5.99916 11.4348 5.82771 11.2388C5.65626 11.0429 5.67611 10.745 5.87206 10.5736L6.92691 9.65055L5.87206 8.72757C5.67611 8.55614 5.65626 8.25831 5.82771 8.06236Z"
-        fill="#0E121B"
-      />
-      <path
-        d="M5.82771 8.06236L5.07514 7.40385L5.07512 7.40387L5.82771 8.06236ZM6.49294 8.01801L7.15143 7.26543L7.15143 7.26543L6.49294 8.01801ZM7.95326 9.29577L8.61198 8.54339L8.61176 8.54319L7.95326 9.29577ZM7.95326 10.0054L8.61175 10.758L8.61198 10.7578L7.95326 10.0054ZM6.49294 11.2831L7.15139 12.0358L7.15143 12.0357L6.49294 11.2831ZM5.82771 11.2388L5.07512 11.8973L5.07514 11.8973L5.82771 11.2388ZM5.87206 10.5736L6.53051 11.3262L6.53058 11.3262L5.87206 10.5736ZM6.92691 9.65055L7.58544 10.4031L8.44548 9.65051L7.5854 8.89796L6.92691 9.65055ZM5.87206 8.72757L6.53055 7.97499L6.53053 7.97497L5.87206 8.72757ZM5.82771 8.06236L6.58027 8.72088C6.38804 8.94056 6.05413 8.96282 5.83444 8.7706L6.49294 8.01801L7.15143 7.26543C6.53986 6.73032 5.61028 6.79228 5.07514 7.40385L5.82771 8.06236ZM6.49294 8.01801L5.83444 8.7706L7.29476 10.0484L7.95326 9.29577L8.61176 8.54319L7.15143 7.26543L6.49294 8.01801ZM7.95326 9.29577L7.29454 10.0482C7.18018 9.94804 7.11425 9.80315 7.11425 9.65055H8.11425H9.11425C9.11425 9.22605 8.93096 8.82265 8.61198 8.54339L7.95326 9.29577ZM8.11425 9.65055H7.11425C7.11425 9.49814 7.18003 9.35327 7.29454 9.25301L7.95326 10.0054L8.61198 10.7578C8.9311 10.4784 9.11425 10.0748 9.11425 9.65055H8.11425ZM7.95326 10.0054L7.29476 9.25282L5.83444 10.5306L6.49294 11.2831L7.15143 12.0357L8.61175 10.758L7.95326 10.0054ZM6.49294 11.2831L5.83448 10.5305C6.054 10.3385 6.38791 10.3605 6.58027 10.5803L5.82771 11.2388L5.07514 11.8973C5.61041 12.5091 6.53998 12.5707 7.15139 12.0358L6.49294 11.2831ZM5.82771 11.2388L6.58029 10.5803C6.77248 10.8 6.7503 11.1339 6.53051 11.3262L5.87206 10.5736L5.2136 9.82099C4.60192 10.3561 4.54004 11.2858 5.07512 11.8973L5.82771 11.2388ZM5.87206 10.5736L6.53058 11.3262L7.58544 10.4031L6.92691 9.65055L6.26838 8.89799L5.21353 9.82105L5.87206 10.5736ZM6.92691 9.65055L7.5854 8.89796L6.53055 7.97499L5.87206 8.72757L5.21356 9.48016L6.26841 10.4031L6.92691 9.65055ZM5.87206 8.72757L6.53053 7.97497C6.75029 8.16724 6.77249 8.50119 6.58029 8.72086L5.82771 8.06236L5.07512 7.40387C4.54003 8.01542 4.60194 8.94503 5.21358 9.48018L5.87206 8.72757Z"
-        fill="#525866"
-        mask={`url(#${m3})`}
-      />
-      <mask id={m4} fill="white">
-        <path
-          fillRule="evenodd"
-          clipRule="evenodd"
-          d="M1.50951 5.56445C1.76988 5.56445 1.98094 5.77552 1.98094 6.03588V6.18191C1.98094 7.86309 3.32424 9.21528 4.96817 9.21528H6.98572C7.24608 9.21528 7.45715 9.42631 7.45715 9.68671C7.45715 9.94702 7.24608 10.1581 6.98572 10.1581H4.96817C2.79177 10.1581 1.03809 8.372 1.03809 6.18191V6.03588C1.03809 5.77552 1.24915 5.56445 1.50951 5.56445Z"
-        />
-      </mask>
-      <path
-        fillRule="evenodd"
-        clipRule="evenodd"
-        d="M1.50951 5.56445C1.76988 5.56445 1.98094 5.77552 1.98094 6.03588V6.18191C1.98094 7.86309 3.32424 9.21528 4.96817 9.21528H6.98572C7.24608 9.21528 7.45715 9.42631 7.45715 9.68671C7.45715 9.94702 7.24608 10.1581 6.98572 10.1581H4.96817C2.79177 10.1581 1.03809 8.372 1.03809 6.18191V6.03588C1.03809 5.77552 1.24915 5.56445 1.50951 5.56445Z"
-        fill="#0E121B"
-      />
-      <path
-        d="M1.50951 5.56445V6.56445C1.2176 6.56445 0.980943 6.3278 0.980943 6.03588H1.98094H2.98094C2.98094 5.22323 2.32216 4.56445 1.50951 4.56445V5.56445ZM1.98094 6.03588H0.980943V6.18191H1.98094H2.98094V6.03588H1.98094ZM1.98094 6.18191H0.980943C0.980943 8.40343 2.76009 10.2153 4.96817 10.2153V9.21528V8.21528C3.88839 8.21528 2.98094 7.32275 2.98094 6.18191H1.98094ZM4.96817 9.21528V10.2153H6.98572V9.21528V8.21528H4.96817V9.21528ZM6.98572 9.21528V10.2153C6.69386 10.2153 6.45715 9.97866 6.45715 9.68671H7.45715H8.45715C8.45715 8.87396 7.7983 8.21528 6.98572 8.21528V9.21528ZM7.45715 9.68671H6.45715C6.45715 9.3948 6.69374 9.15814 6.98572 9.15814V10.1581V11.1581C7.79842 11.1581 8.45715 10.4992 8.45715 9.68671H7.45715ZM6.98572 10.1581V9.15814H4.96817V10.1581V11.1581H6.98572V10.1581ZM4.96817 10.1581V9.15814C3.35696 9.15814 2.03809 7.83271 2.03809 6.18191H1.03809H0.0380859C0.0380859 8.91129 2.22659 11.1581 4.96817 11.1581V10.1581ZM1.03809 6.18191H2.03809V6.03588H1.03809H0.0380859V6.18191H1.03809ZM1.03809 6.03588H2.03809C2.03809 6.3278 1.80143 6.56445 1.50951 6.56445V5.56445V4.56445C0.696865 4.56445 0.0380859 5.22323 0.0380859 6.03588H1.03809Z"
-        fill="#525866"
-        mask={`url(#${m4})`}
-      />
-    </svg>
-  );
-};
diff --git a/apps/dashboard/src/hooks/use-diagnose-domain.ts b/apps/dashboard/src/hooks/use-diagnose-domain.ts
deleted file mode 100644
index 4d17dbea1a1..00000000000
--- a/apps/dashboard/src/hooks/use-diagnose-domain.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-import { useMutation } from '@tanstack/react-query';
-import { diagnoseDomain } from '@/api/domains';
-import { useEnvironment } from '@/context/environment/hooks';
-
-export function useDiagnoseDomain(domain: string | undefined) {
-  const { currentEnvironment } = useEnvironment();
-
-  return useMutation({
-    mutationFn: () => {
-      if (!domain || !currentEnvironment) {
-        throw new Error('Diagnose requires a domain and environment.');
-      }
-
-      return diagnoseDomain(domain, currentEnvironment);
-    },
-  });
-}

From 4d19e77797b3e02b479e29d02cf4eb971129288a Mon Sep 17 00:00:00 2001
From: Adam Chmara <adam.chmara1@gmail.com>
Date: Mon, 4 May 2026 14:41:25 +0200
Subject: [PATCH 5/6] fix(dashboard): apply row hover background to agent list
 actions cell (#10976)

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
---
 apps/dashboard/src/components/agents/agents-table.tsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/apps/dashboard/src/components/agents/agents-table.tsx b/apps/dashboard/src/components/agents/agents-table.tsx
index 68b4b3b35df..f9ea7dbf7f5 100644
--- a/apps/dashboard/src/components/agents/agents-table.tsx
+++ b/apps/dashboard/src/components/agents/agents-table.tsx
@@ -220,11 +220,11 @@ export function AgentsTable({ agents, isLoading, onRequestDelete, paginationProp
                 >
                   <span className="text-label-sm">{formatDateSimple(agent.updatedAt)}</span>
                 </AgentNavTableCell>
-                <TableCell className="p-3 text-right align-middle">
+                <AgentNavTableCell className="w-1 p-3 text-right align-middle">
                   {canWrite ? (
                     <DropdownMenu>
                       <DropdownMenuTrigger asChild>
-                        <CompactButton size="md" variant="ghost" icon={RiMore2Fill} className="z-10" disabled={readOnly}>
+                        <CompactButton variant="ghost" icon={RiMore2Fill} className="z-10 h-8 w-8 p-0" disabled={readOnly}>
                           <span className="sr-only">Open menu</span>
                         </CompactButton>
                       </DropdownMenuTrigger>
@@ -240,7 +240,7 @@ export function AgentsTable({ agents, isLoading, onRequestDelete, paginationProp
                       </DropdownMenuContent>
                     </DropdownMenu>
                   ) : null}
-                </TableCell>
+                </AgentNavTableCell>
               </TableRow>
             );
           })}

From 2d613629f839b0f35ee835c0da1c6d027e5dbe3e Mon Sep 17 00:00:00 2001
From: Adam Chmara <adam.chmara1@gmail.com>
Date: Mon, 4 May 2026 15:11:19 +0200
Subject: [PATCH 6/6] fix(cli): use agent identifier as scaffolded file name
 fixes NV-7479 (#10972)

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
---
 .../novu/src/commands/init/templates/index.ts | 29 ++++++++++++-------
 1 file changed, 19 insertions(+), 10 deletions(-)

diff --git a/packages/novu/src/commands/init/templates/index.ts b/packages/novu/src/commands/init/templates/index.ts
index a4747f873f8..724a3fe78d3 100644
--- a/packages/novu/src/commands/init/templates/index.ts
+++ b/packages/novu/src/commands/init/templates/index.ts
@@ -66,6 +66,13 @@ export const installTemplate = async ({
     copySource.push(mode === 'ts' ? 'tailwind.config.ts' : '!tailwind.config.js', '!postcss.config.cjs');
   }
 
+  const renameAgent = template === TemplateTypeEnum.APP_AGENT && agentIdentifier;
+  if (renameAgent && !/^[a-z0-9]+(?:[-_][a-z0-9]+)*$/.test(agentIdentifier)) {
+    throw new Error(
+      `Invalid agent identifier: "${agentIdentifier}". Must be a lowercase slug (a-z, 0-9, hyphens, underscores).`
+    );
+  }
+
   await copy(copySource, root, {
     parents: true,
     cwd: templatePath,
@@ -82,6 +89,9 @@ export const installTemplate = async ({
         case 'README-template.md': {
           return 'README.md';
         }
+        case 'support-agent.tsx': {
+          return renameAgent ? `${agentIdentifier}.tsx` : name;
+        }
         default: {
           return name;
         }
@@ -89,16 +99,15 @@ export const installTemplate = async ({
     },
   });
 
-  if (template === TemplateTypeEnum.APP_AGENT && agentIdentifier) {
-    if (!/^[a-z0-9]+(?:[-_][a-z0-9]+)*$/.test(agentIdentifier)) {
-      throw new Error(
-        `Invalid agent identifier: "${agentIdentifier}". Must be a lowercase slug (a-z, 0-9, hyphens, underscores).`
-      );
-    }
-    const agentFile = path.join(root, 'app', 'novu', 'agents', 'support-agent.tsx');
-    await fs.writeFile(
-      agentFile,
-      (await fs.readFile(agentFile, 'utf8')).replace("agent('support-agent',", `agent('${agentIdentifier}',`)
+  if (renameAgent) {
+    const camelName = agentIdentifier.replace(/[-_]([a-z0-9])/g, (_, c) => c.toUpperCase());
+    const files = await glob('**/*.{tsx,ts,md}', { cwd: root, absolute: true, followSymbolicLinks: false });
+    await Promise.all(
+      files.map(async (file) => {
+        const before = await fs.readFile(file, 'utf8');
+        const after = before.replace(/supportAgent/g, camelName).replace(/support-agent/g, agentIdentifier);
+        if (after !== before) await fs.writeFile(file, after);
+      })
     );
   }