Merge branch 'feature/cw-7495-llm' into feature/cw-7495-api

This improves the Captain overview by loading reporting metrics and FAQ
stats from separate endpoints. Range changes now refresh only the
metrics, while reopen-rate calculation reuses the resolved conversation
count to avoid redundant database queries.

## What changed

- Split Captain overview metrics and FAQ stats into separate APIs.
- Fetch FAQ stats independently from range-based metrics.
- Reuse resolved conversation totals when calculating reopen rate.
- Skip the reopen query when there are no resolved conversations.

VERSION_CW

@@ -1 +1 @@
-4.16.0
+4.16.1

app/builders/agent_builder.rb

@@ -2,6 +2,14 @@
 # It initializes with necessary attributes and provides a perform method
 # to create a user and account user in a transaction.
 class AgentBuilder
+  LIMIT_EXCEEDED_MESSAGE = 'Account limit exceeded. Please purchase more licenses'.freeze
+
+  class LimitExceededError < StandardError
+    def initialize
+      super(AgentBuilder::LIMIT_EXCEEDED_MESSAGE)
+    end
+  end
+
   # Initializes an AgentBuilder with necessary attributes.
   # @param email [String] the email of the user.
   # @param name [String] the name of the user.
@@ -14,15 +22,23 @@ class AgentBuilder
   # Creates a user and account user in a transaction.
   # @return [User] the created user.
   def perform
-    ActiveRecord::Base.transaction do
-      @user = find_or_create_user
-      create_account_user
+    account.with_lock do
+      raise LimitExceededError unless can_add_agent?
+
+      ActiveRecord::Base.transaction do
+        @user = find_or_create_user
+        create_account_user
+      end
     end
     @user
   end
 
   private
 
+  def can_add_agent?
+    account.usage_limits[:agents] > account.account_users.count
+  end
+
   # Finds a user by email or creates a new one with a temporary password.
   # @return [User] the found or created user.
   def find_or_create_user

app/controllers/api/v1/accounts/agents_controller.rb

@@ -1,8 +1,6 @@
 class Api::V1::Accounts::AgentsController < Api::V1::Accounts::BaseController
   before_action :fetch_agent, except: [:create, :index, :bulk_create]
   before_action :check_authorization
-  before_action :validate_limit, only: [:create]
-  before_action :validate_limit_for_bulk_create, only: [:bulk_create]
 
   def index
     @agents = agents
@@ -20,6 +18,8 @@ class Api::V1::Accounts::AgentsController < Api::V1::Accounts::BaseController
     )
 
     @agent = builder.perform
+  rescue AgentBuilder::LimitExceededError => e
+    render_payment_required(e.message)
   end
 
   def update
@@ -36,25 +36,13 @@ class Api::V1::Accounts::AgentsController < Api::V1::Accounts::BaseController
   def bulk_create
     emails = params[:emails]
 
-    emails.each do |email|
-      builder = AgentBuilder.new(
-        email: email,
-        name: email.split('@').first,
-        inviter: current_user,
-        account: Current.account
-      )
-      begin
-        builder.perform
-      rescue ActiveRecord::RecordInvalid => e
-        Rails.logger.info "[Agent#bulk_create] ignoring email #{email}, errors: #{e.record.errors}"
-      end
-    end
-
+    bulk_create_agents(emails)
     # This endpoint is used to bulk create agents during onboarding
     # onboarding_step key in present in Current account custom attributes, since this is a one time operation
-    Current.account.custom_attributes.delete('onboarding_step')
-    Current.account.save!
+    clear_onboarding_step
     head :ok
+  rescue AgentBuilder::LimitExceededError => e
+    render_payment_required(e.message)
   end
 
   private
@@ -87,22 +75,33 @@ class Api::V1::Accounts::AgentsController < Api::V1::Accounts::BaseController
     @agents ||= Current.account.users.order_by_full_name.includes(:account_users, { avatar_attachment: [:blob] })
   end
 
-  def validate_limit_for_bulk_create
-    limit_available = params[:emails].count <= available_agent_count
+  def bulk_create_agents(emails)
+    Current.account.with_lock do
+      raise AgentBuilder::LimitExceededError if emails.count > available_agent_count
 
-    render_payment_required('Account limit exceeded. Please purchase more licenses') unless limit_available
+      emails.each { |email| create_agent_from_email(email) }
+    end
   end
 
-  def validate_limit
-    render_payment_required('Account limit exceeded. Please purchase more licenses') unless can_add_agent?
+  def create_agent_from_email(email)
+    builder = AgentBuilder.new(
+      email: email,
+      name: email.split('@').first,
+      inviter: current_user,
+      account: Current.account
+    )
+    builder.perform
+  rescue ActiveRecord::RecordInvalid => e
+    Rails.logger.info "[Agent#bulk_create] ignoring email #{email}, errors: #{e.record.errors}"
+  end
+
+  def clear_onboarding_step
+    Current.account.custom_attributes.delete('onboarding_step')
+    Current.account.save!
   end
 
   def available_agent_count
-    Current.account.usage_limits[:agents] - agents.count
-  end
-
-  def can_add_agent?
-    available_agent_count.positive?
+    Current.account.usage_limits[:agents] - Current.account.account_users.count
   end
 
   def delete_user_record(agent)

app/controllers/api/v1/accounts/integrations/base_controller.rb

@@ -0,0 +1,9 @@
+class Api::V1::Accounts::Integrations::BaseController < Api::V1::Accounts::BaseController
+  private
+
+  # Managing an integration hook (create/update/destroy) is admin-only, enforced via HookPolicy.
+  # Subclasses opt in per action with `before_action :check_authorization, only: [...]`.
+  def check_authorization
+    authorize(:hook)
+  end
+end

app/controllers/api/v1/accounts/integrations/hooks_controller.rb

@@ -1,4 +1,4 @@
-class Api::V1::Accounts::Integrations::HooksController < Api::V1::Accounts::BaseController
+class Api::V1::Accounts::Integrations::HooksController < Api::V1::Accounts::Integrations::BaseController
   before_action :fetch_hook, except: [:create]
   before_action :check_authorization
 
@@ -35,10 +35,6 @@ class Api::V1::Accounts::Integrations::HooksController < Api::V1::Accounts::Base
     @hook = Current.account.hooks.find(params[:id])
   end
 
-  def check_authorization
-    authorize(:hook)
-  end
-
   def permitted_params
     params.require(:hook).permit(:app_id, :inbox_id, :status, settings: {})
   end

app/controllers/api/v1/accounts/integrations/linear_controller.rb

@@ -1,6 +1,7 @@
-class Api::V1::Accounts::Integrations::LinearController < Api::V1::Accounts::BaseController
+class Api::V1::Accounts::Integrations::LinearController < Api::V1::Accounts::Integrations::BaseController
   before_action :fetch_conversation, only: [:create_issue, :link_issue, :unlink_issue, :linked_issues]
   before_action :fetch_hook, only: [:destroy]
+  before_action :check_authorization, only: [:destroy]
 
   def destroy
     revoke_linear_token

app/controllers/api/v1/accounts/integrations/notion_controller.rb

@@ -1,5 +1,6 @@
-class Api::V1::Accounts::Integrations::NotionController < Api::V1::Accounts::BaseController
+class Api::V1::Accounts::Integrations::NotionController < Api::V1::Accounts::Integrations::BaseController
   before_action :fetch_hook, only: [:destroy]
+  before_action :check_authorization, only: [:destroy]
 
   def destroy
     @hook.destroy!

app/controllers/api/v1/accounts/integrations/shopify_controller.rb

@@ -1,7 +1,8 @@
-class Api::V1::Accounts::Integrations::ShopifyController < Api::V1::Accounts::BaseController
+class Api::V1::Accounts::Integrations::ShopifyController < Api::V1::Accounts::Integrations::BaseController
   include Shopify::IntegrationHelper
   before_action :setup_shopify_context, only: [:orders]
   before_action :fetch_hook, except: [:auth]
+  before_action :check_authorization, only: [:destroy]
   before_action :validate_contact, only: [:orders]
 
   def auth

app/javascript/dashboard/api/captain/assistant.js

@@ -26,13 +26,20 @@ class CaptainAssistant extends ApiClient {
     });
   }
 
-  getStats({ assistantId, range, signal }) {
+  getMetrics({ assistantId, range, signal }) {
     const requestConfig = {
       params: { range, timezone_offset: getTimezoneOffset() },
     };
     if (signal) requestConfig.signal = signal;
 
-    return axios.get(`${this.url}/${assistantId}/stats`, requestConfig);
+    return axios.get(`${this.url}/${assistantId}/metrics`, requestConfig);
+  }
+
+  getFaqStats({ assistantId, signal }) {
+    const requestConfig = {};
+    if (signal) requestConfig.signal = signal;
+
+    return axios.get(`${this.url}/${assistantId}/faq_stats`, requestConfig);
   }
 
   getSummary({ assistantId, range, stats }) {

app/javascript/dashboard/components/ui/ContextMenu.vue

@@ -77,6 +77,15 @@ const handleClose = () => {
   emit('close');
 };
 
+const handleFocusOut = event => {
+  // Keep the menu open while focus stays inside it (e.g. the label search
+  // input); close it once focus leaves the menu entirely.
+  if (menuRef.value?.contains(event.relatedTarget)) {
+    return;
+  }
+  handleClose();
+};
+
 onUnmounted(() => {
   isLocked.value = false;
 });
@@ -89,7 +98,7 @@ onUnmounted(() => {
       class="fixed outline-none z-[9999] cursor-pointer"
       :style="position"
       tabindex="0"
-      @blur="handleClose"
+      @focusout="handleFocusOut"
     >
       <slot />
     </div>

app/javascript/dashboard/components/widgets/WootWriter/FullEditor.vue

@@ -8,6 +8,8 @@ import {
   EditorState,
   Selection,
   imageResizeView,
+  toggleMark,
+  wrapInList,
 } from '@chatwoot/prosemirror-schema';
 import {
   suggestionsPlugin,
@@ -17,8 +19,6 @@ import imagePastePlugin from '@chatwoot/prosemirror-schema/src/plugins/image';
 import embedPreviewPlugin from '@chatwoot/prosemirror-schema/src/plugins/embedPreview';
 import trailingParagraphPlugin from '@chatwoot/prosemirror-schema/src/plugins/trailingParagraph';
 import { embeds as markdownEmbeds } from 'dashboard/helper/markdownEmbeds';
-import { toggleMark } from 'prosemirror-commands';
-import { wrapInList } from 'prosemirror-schema-list';
 import { toggleBlockType } from '@chatwoot/prosemirror-schema/src/menu/common';
 import { checkFileSizeLimit } from 'shared/helpers/FileHelper';
 import { isEscape } from 'shared/helpers/KeyboardHelpers';

app/javascript/dashboard/components/widgets/conversation/MessagesView.vue

@@ -33,9 +33,7 @@ import {
 // constants
 import { BUS_EVENTS } from 'shared/constants/busEvents';
 import { REPLY_POLICY } from 'shared/constants/links';
-import wootConstants, {
-  META_RESTRICTION_STATUS_URL,
-} from 'dashboard/constants/globals';
+import wootConstants from 'dashboard/constants/globals';
 import { LOCAL_STORAGE_KEYS } from 'dashboard/constants/localStorage';
 import { INBOX_TYPES } from 'dashboard/helper/inbox';
 
@@ -95,7 +93,6 @@ export default {
       currentUserId: 'getCurrentUserID',
       listLoadingStatus: 'getAllMessagesLoaded',
       currentAccountId: 'getCurrentAccountId',
-      isOnChatwootCloud: 'globalConfig/isOnChatwootCloud',
     }),
     isOpen() {
       return this.currentChat?.status === wootConstants.STATUS_TYPE.OPEN;
@@ -173,13 +170,6 @@ export default {
         instagramInbox
       );
     },
-    isInstagramRestrictionBannerVisible() {
-      return this.isOnChatwootCloud && this.isAnInstagramChannel;
-    },
-    instagramRestrictionStatusUrl() {
-      return META_RESTRICTION_STATUS_URL;
-    },
-
     replyWindowBannerMessage() {
       if (this.isAWhatsAppChannel) {
         return this.$t('CONVERSATION.TWILIO_WHATSAPP_CAN_REPLY');
@@ -464,15 +454,7 @@ export default {
   >
     <div ref="topBannerRef">
       <Banner
-        v-if="isInstagramRestrictionBannerVisible"
-        color-scheme="warning"
-        class="mx-2 mt-2 overflow-hidden rounded-lg"
-        :banner-message="$t('CONVERSATION.INSTAGRAM_RESTRICTION_BANNER')"
-        :href-link="instagramRestrictionStatusUrl"
-        :href-link-text="$t('CONVERSATION.INSTAGRAM_RESTRICTION_STATUS_LINK')"
-      />
-      <Banner
-        v-else-if="!currentChat.can_reply"
+        v-if="!currentChat.can_reply"
         color-scheme="alert"
         class="mx-2 mt-2 overflow-hidden rounded-lg"
         :banner-message="replyWindowBannerMessage"

app/javascript/dashboard/components/widgets/conversation/contextMenu/Index.vue

@@ -7,10 +7,13 @@ import {
   getSortedAgentsByAvailability,
   getAgentsByUpdatedPresence,
 } from 'dashboard/helper/agentHelper.js';
+import { picoSearch } from '@scmmishra/pico-search';
 import MenuItem from './menuItem.vue';
 import MenuItemWithSubmenu from './menuItemWithSubmenu.vue';
 import wootConstants from 'dashboard/constants/globals';
 import AgentLoadingPlaceholder from './agentLoadingPlaceholder.vue';
+import NextInput from 'dashboard/components-next/input/Input.vue';
+import Icon from 'dashboard/components-next/icon/Icon.vue';
 
 const MENU = {
   MARK_AS_READ: 'mark-as-read',
@@ -31,6 +34,8 @@ export default {
     MenuItem,
     MenuItemWithSubmenu,
     AgentLoadingPlaceholder,
+    NextInput,
+    Icon,
   },
   props: {
     chatId: {
@@ -87,6 +92,7 @@ export default {
   data() {
     return {
       MENU,
+      labelSearchQuery: '',
       STATUS_TYPE: wootConstants.STATUS_TYPE,
       readOption: {
         label: this.$t('CONVERSATION.CARD_CONTEXT_MENU.MARK_AS_READ'),
@@ -216,6 +222,14 @@ export default {
       // Don't show snooze if the conversation is already snoozed/resolved/pending
       return this.status === wootConstants.STATUS_TYPE.OPEN;
     },
+    filteredLabels() {
+      const labels = this.labelSearchQuery
+        ? picoSearch(this.labels, this.labelSearchQuery, ['title'])
+        : this.labels;
+      // Assigned labels first, keeping each group's existing order.
+      const isAssigned = label => this.conversationLabels.includes(label.title);
+      return [...labels].sort((a, b) => isAssigned(b) - isAssigned(a));
+    },
   },
   mounted() {
     this.$store.dispatch('inboxAssignableAgents/fetch', [this.inboxId]);
@@ -335,21 +349,49 @@ export default {
         :option="labelMenuConfig"
         :sub-menu-available="!!labels.length"
       >
-        <MenuItem
-          v-for="label in labels"
-          :key="label.id"
-          :option="generateMenuLabelConfig(label, 'label')"
-          :variant="
-            conversationLabels.includes(label.title)
-              ? 'label-assigned'
-              : 'label'
-          "
-          @click.stop="
-            conversationLabels.includes(label.title)
-              ? $emit('removeLabel', label)
-              : $emit('assignLabel', label)
-          "
-        />
+        <div class="pb-1 w-[12.5rem]">
+          <NextInput
+            v-model="labelSearchQuery"
+            type="search"
+            size="sm"
+            class="w-full"
+            custom-input-class="!ps-8 !text-xs"
+            :placeholder="$t('CONVERSATION.CARD_CONTEXT_MENU.SEARCH_LABELS')"
+            @click.stop
+            @keydown.stop
+          >
+            <template #prefix>
+              <Icon
+                icon="i-lucide-search"
+                class="absolute z-10 -translate-y-1/2 pointer-events-none size-3.5 text-n-slate-10 top-1/2 start-2"
+              />
+            </template>
+          </NextInput>
+        </div>
+        <div class="overflow-x-hidden overflow-y-auto max-h-[12.5rem]">
+          <MenuItem
+            v-for="label in filteredLabels"
+            :key="label.id"
+            :option="generateMenuLabelConfig(label, 'label')"
+            :variant="
+              conversationLabels.includes(label.title)
+                ? 'label-assigned'
+                : 'label'
+            "
+            @mousedown.prevent
+            @click.stop="
+              conversationLabels.includes(label.title)
+                ? $emit('removeLabel', label)
+                : $emit('assignLabel', label)
+            "
+          />
+          <p
+            v-if="!filteredLabels.length"
+            class="px-2 py-2 m-0 text-xs text-center text-n-slate-11"
+          >
+            {{ $t('CONVERSATION.CARD_CONTEXT_MENU.NO_LABELS_FOUND') }}
+          </p>
+        </div>
       </MenuItemWithSubmenu>
       <MenuItemWithSubmenu
         v-if="isAllowed([MENU.AGENT])"

app/javascript/dashboard/components/widgets/conversation/contextMenu/menuItem.vue

@@ -15,7 +15,7 @@ defineProps({
 </script>
 
 <template>
-  <div class="menu text-n-slate-12 min-h-7 min-w-0" role="button">
+  <div class="menu group text-n-slate-12 min-h-7 min-w-0" role="button">
     <fluent-icon
       v-if="variant === 'icon' && option.icon"
       :icon="option.icon"
@@ -52,7 +52,7 @@ defineProps({
     <Icon
       v-if="variant === 'label-assigned'"
       icon="i-lucide-check"
-      class="flex-shrink-0 size-3.5 mr-1"
+      class="flex-shrink-0 size-3.5 text-n-brand group-hover:text-white"
     />
   </div>
 </template>

app/javascript/dashboard/constants/globals.js

@@ -78,5 +78,3 @@ export default {
   },
 };
 export const DEFAULT_REDIRECT_URL = '/app/';
-export const META_RESTRICTION_STATUS_URL =
-  'https://status.chatwoot.com/incident/948346';

app/javascript/dashboard/helper/editorHelper.js

@@ -1,4 +1,6 @@
 import {
+  InputRule,
+  inputRules,
   MessageMarkdownSerializer,
   MessageMarkdownTransformer,
   messageSchema,
@@ -9,7 +11,6 @@ import * as Sentry from '@sentry/vue';
 import camelcaseKeys from 'camelcase-keys';
 import { FORMATTING, MARKDOWN_PATTERNS } from 'dashboard/constants/editor';
 import { INBOX_TYPES, TWILIO_CHANNEL_MEDIUM } from 'dashboard/helper/inbox';
-import { InputRule, inputRules } from 'prosemirror-inputrules';
 
 /**
  * Extract text from markdown, and remove all images, code blocks, links, headers, bold, italic, lists etc.

app/javascript/dashboard/i18n/locale/en/conversation.json

@@ -44,8 +44,6 @@
     "TWILIO_WHATSAPP_CAN_REPLY": "You can only reply to this conversation using a template message due to",
     "TWILIO_WHATSAPP_24_HOURS_WINDOW": "24 hour message window restriction",
     "OLD_INSTAGRAM_INBOX_REPLY_BANNER": "This Instagram account was migrated to the new Instagram channel inbox. All new messages will show up there. You won’t be able to send messages from this conversation anymore.",
-    "INSTAGRAM_RESTRICTION_BANNER": "Instagram is currently restricted. Some messages or actions may be delayed or unavailable while we restore full support.",
-    "INSTAGRAM_RESTRICTION_STATUS_LINK": "View status update",
     "REPLYING_TO": "You are replying to:",
     "REMOVE_SELECTION": "Remove Selection",
     "DOWNLOAD": "Download",
@@ -195,6 +193,8 @@
       },
       "ASSIGN_AGENT": "Assign agent",
       "ASSIGN_LABEL": "Assign label",
+      "SEARCH_LABELS": "Search labels",
+      "NO_LABELS_FOUND": "No labels found",
       "AGENTS_LOADING": "Loading agents...",
       "ASSIGN_TEAM": "Assign team",
       "DELETE": "Delete conversation",

app/javascript/dashboard/i18n/locale/en/inboxMgmt.json

@@ -58,9 +58,7 @@
         "ERROR_MESSAGE": "There was an error connecting to Instagram, please try again",
         "ERROR_AUTH": "There was an error connecting to Instagram, please try again",
         "NEW_INBOX_SUGGESTION": "This Instagram account was previously linked to a different inbox and has now been migrated here. All new messages will appear here. The old inbox will no longer be able to send or receive messages for this account.",
-        "DUPLICATE_INBOX_BANNER": "This Instagram account was migrated to the new Instagram channel inbox. You won’t be able to send/receive Instagram messages from this inbox anymore.",
-        "SETTINGS_RESTRICTED_WARNING": "Instagram is currently restricted. Some messages or actions may be delayed or unavailable while we restore full support.",
-        "STATUS_LINK": "View status update"
+        "DUPLICATE_INBOX_BANNER": "This Instagram account was migrated to the new Instagram channel inbox. You won’t be able to send/receive Instagram messages from this inbox anymore."
       },
       "TIKTOK": {
         "CONTINUE_WITH_TIKTOK": "Continue with TikTok",

app/javascript/dashboard/routes/dashboard/captain/assistants/overview/Index.vue

@@ -26,25 +26,28 @@ const canDrilldown = computed(() => checkPermissions(['administrator']));
 const selectedRange = ref('this_month');
 
 const assistantId = computed(() => route.params.assistantId);
-const stats = ref(null);
-const isFetching = ref(false);
+const metricStats = ref(null);
+const faqStats = ref(null);
+const isFetchingMetrics = ref(false);
 
 // Increments on every fetch so a response (or retry) from a superseded
 // range/assistant can't clobber the latest request's state.
-let fetchToken = 0;
-let abortController = null;
+let metricsFetchToken = 0;
+let faqStatsFetchToken = 0;
+let metricsAbortController = null;
+let faqStatsAbortController = null;
 
-const fetchStats = async () => {
-  fetchToken += 1;
-  const token = fetchToken;
-  abortController?.abort();
-  abortController = new AbortController();
-  const { signal } = abortController;
-  stats.value = null;
-  isFetching.value = true;
+const fetchMetrics = async () => {
+  metricsFetchToken += 1;
+  const token = metricsFetchToken;
+  metricsAbortController?.abort();
+  metricsAbortController = new AbortController();
+  const { signal } = metricsAbortController;
+  metricStats.value = null;
+  isFetchingMetrics.value = true;
 
-  const requestStats = () =>
-    CaptainAssistant.getStats({
+  const requestMetrics = () =>
+    CaptainAssistant.getMetrics({
       assistantId: assistantId.value,
       range: selectedRange.value,
       signal,
@@ -52,25 +55,54 @@ const fetchStats = async () => {
 
   let data = null;
   try {
-    ({ data } = await requestStats());
+    ({ data } = await requestMetrics());
   } catch {
     // One silent retry before giving up, unless the request was aborted.
     try {
-      if (token === fetchToken && !signal.aborted)
-        ({ data } = await requestStats());
+      if (token === metricsFetchToken && !signal.aborted)
+        ({ data } = await requestMetrics());
     } catch {
       data = null;
     }
   }
 
-  if (token !== fetchToken || signal.aborted) return;
-  stats.value = data;
-  isFetching.value = false;
+  if (token !== metricsFetchToken || signal.aborted) return;
+  metricStats.value = data;
+  isFetchingMetrics.value = false;
 };
 
-onUnmounted(() => abortController?.abort());
+const fetchFaqStats = async () => {
+  faqStatsFetchToken += 1;
+  const token = faqStatsFetchToken;
+  faqStatsAbortController?.abort();
+  faqStatsAbortController = new AbortController();
+  const { signal } = faqStatsAbortController;
+  faqStats.value = null;
 
-watch([selectedRange, assistantId], fetchStats, { immediate: true });
+  try {
+    const { data } = await CaptainAssistant.getFaqStats({
+      assistantId: assistantId.value,
+      signal,
+    });
+    if (token === faqStatsFetchToken && !signal.aborted) faqStats.value = data;
+  } catch {
+    if (token === faqStatsFetchToken && !signal.aborted) faqStats.value = null;
+  }
+};
+
+const summaryStats = computed(() => {
+  if (!metricStats.value || !faqStats.value) return null;
+
+  return { ...metricStats.value, knowledge: faqStats.value };
+});
+
+onUnmounted(() => {
+  metricsAbortController?.abort();
+  faqStatsAbortController?.abort();
+});
+
+watch([selectedRange, assistantId], fetchMetrics, { immediate: true });
+watch(assistantId, fetchFaqStats, { immediate: true });
 
 // `direction` says whether a rising trend is good ('up'), bad ('down'), or
 // neutral, so we can colour the delta independently of its sign.
@@ -90,7 +122,7 @@ const formatDuration = hours =>
   hours >= 100 ? `${Math.round(hours / 24)}d` : `${hours}h`;
 
 const metricFor = (statKey, formatValue, direction, trendKind = 'percent') => {
-  const data = stats.value?.[statKey];
+  const data = metricStats.value?.[statKey];
   if (!data) return { value: '—', trend: '', trendGood: null };
 
   const sign = data.trend > 0 ? '+' : '';
@@ -184,9 +216,9 @@ const closeDrilldown = () => {
       <div class="flex flex-col gap-6 pb-8">
         <InboxBanner />
 
-        <CoverageBanner :knowledge="stats?.knowledge" />
+        <CoverageBanner :knowledge="faqStats ?? undefined" />
 
-        <WelcomeCard :range="selectedRange" :stats="stats" />
+        <WelcomeCard :range="selectedRange" :stats="summaryStats" />
 
         <div
           class="grid grid-cols-1 gap-px overflow-hidden border rounded-xl sm:grid-cols-2 lg:grid-cols-3 bg-n-weak border-n-weak"
@@ -199,13 +231,15 @@ const closeDrilldown = () => {
             :trend="metric.trend"
             :hint="metric.hint"
             :trend-good="metric.trendGood"
-            :loading="isFetching"
-            :clickable="canDrilldown && Boolean(metric.metric) && !isFetching"
+            :loading="isFetchingMetrics"
+            :clickable="
+              canDrilldown && Boolean(metric.metric) && !isFetchingMetrics
+            "
             @click="openDrilldown(metric)"
           />
         </div>
 
-        <KnowledgeCard :knowledge="stats?.knowledge" />
+        <KnowledgeCard :knowledge="faqStats ?? undefined" />
 
         <QuickLinks />
       </div>

app/javascript/dashboard/routes/dashboard/settings/inbox/Settings.vue

@@ -4,8 +4,6 @@ import { shouldBeUrl } from 'shared/helpers/Validators';
 import { useAlert } from 'dashboard/composables';
 import { useVuelidate } from '@vuelidate/core';
 import Avatar from 'next/avatar/Avatar.vue';
-import Banner from 'dashboard/components-next/banner/Banner.vue';
-import Icon from 'dashboard/components-next/icon/Icon.vue';
 import SettingIntroBanner from 'dashboard/components/widgets/SettingIntroBanner.vue';
 import SettingsToggleSection from 'dashboard/components-next/Settings/SettingsToggleSection.vue';
 import SettingsFieldSection from 'dashboard/components-next/Settings/SettingsFieldSection.vue';
@@ -46,11 +44,9 @@ import SelectInput from 'dashboard/components-next/select/Select.vue';
 import Widget from 'dashboard/modules/widget-preview/components/Widget.vue';
 import AccessToken from 'dashboard/routes/dashboard/settings/profile/AccessToken.vue';
 import { copyTextToClipboard } from 'shared/helpers/clipboard';
-import { META_RESTRICTION_STATUS_URL } from 'dashboard/constants/globals';
 
 export default {
   components: {
-    Banner,
     BotConfiguration,
     CollaboratorsPage,
     ConfigurationPage,
@@ -84,7 +80,6 @@ export default {
     WhatsappManualMigrationBanner,
     Widget,
     AccessToken,
-    Icon,
   },
   mixins: [inboxMixin],
   setup() {
@@ -348,12 +343,6 @@ export default {
     instagramUnauthorized() {
       return this.isAnInstagramChannel && this.inbox.reauthorization_required;
     },
-    showInstagramRestrictionSettingsBanner() {
-      return this.isOnChatwootCloud && this.isAnInstagramChannel;
-    },
-    metaRestrictionStatusUrl() {
-      return META_RESTRICTION_STATUS_URL;
-    },
     tiktokUnauthorized() {
       return this.isATiktokChannel && this.inbox.reauthorization_required;
     },
@@ -820,29 +809,6 @@ export default {
           :class="bannerMaxWidth"
           @start="openWhatsAppManualMigrationDialog"
         />
-        <Banner
-          v-if="showInstagramRestrictionSettingsBanner"
-          color="amber"
-          class="mx-6 mb-4 max-w-4xl"
-        >
-          <div class="flex items-start gap-3 text-start">
-            <Icon
-              icon="i-lucide-triangle-alert"
-              class="flex-shrink-0 size-4 mt-0.5"
-            />
-            <span>
-              {{ $t('INBOX_MGMT.ADD.INSTAGRAM.SETTINGS_RESTRICTED_WARNING') }}
-              <a
-                :href="metaRestrictionStatusUrl"
-                class="link underline"
-                rel="noopener noreferrer nofollow"
-                target="_blank"
-              >
-                {{ $t('INBOX_MGMT.ADD.INSTAGRAM.STATUS_LINK') }}
-              </a>
-            </span>
-          </div>
-        </Banner>
 
         <div
           v-if="selectedTabKey === 'inbox-settings'"

app/javascript/widget/components/ChatFooter.vue

@@ -11,6 +11,8 @@ import { IFrameHelper } from '../helpers/utils';
 import { CHATWOOT_ON_START_CONVERSATION } from '../constants/sdkEvents';
 import { emitter } from 'shared/helpers/mitt';
 
+const TRANSCRIPT_COOLDOWN_MS = 15000;
+
 export default {
   components: {
     ChatInputWrap,
@@ -24,6 +26,9 @@ export default {
   data() {
     return {
       inReplyTo: null,
+      isSendingTranscript: false,
+      transcriptCooldown: false,
+      transcriptCooldownTimer: null,
     };
   },
   computed: {
@@ -57,6 +62,9 @@ export default {
   mounted() {
     emitter.on(BUS_EVENTS.TOGGLE_REPLY_TO_MESSAGE, this.toggleReplyTo);
   },
+  beforeUnmount() {
+    clearTimeout(this.transcriptCooldownTimer);
+  },
   methods: {
     ...mapActions('conversation', ['sendMessage', 'sendAttachment']),
     ...mapActions('conversationAttributes', ['getAttributes']),
@@ -90,19 +98,35 @@ export default {
     toggleReplyTo(message) {
       this.inReplyTo = message;
     },
+    startTranscriptCooldown() {
+      this.transcriptCooldown = true;
+      clearTimeout(this.transcriptCooldownTimer);
+      this.transcriptCooldownTimer = setTimeout(() => {
+        this.transcriptCooldown = false;
+      }, TRANSCRIPT_COOLDOWN_MS);
+    },
     async sendTranscript() {
-      if (this.hasEmail) {
-        try {
-          await sendEmailTranscript();
-          emitter.emit(BUS_EVENTS.SHOW_ALERT, {
-            message: this.$t('EMAIL_TRANSCRIPT.SEND_EMAIL_SUCCESS'),
-            type: 'success',
-          });
-        } catch (error) {
-          emitter.$emit(BUS_EVENTS.SHOW_ALERT, {
-            message: this.$t('EMAIL_TRANSCRIPT.SEND_EMAIL_ERROR'),
-          });
-        }
+      if (
+        !this.hasEmail ||
+        this.isSendingTranscript ||
+        this.transcriptCooldown
+      ) {
+        return;
+      }
+      this.isSendingTranscript = true;
+      try {
+        await sendEmailTranscript();
+        this.startTranscriptCooldown();
+        emitter.emit(BUS_EVENTS.SHOW_ALERT, {
+          message: this.$t('EMAIL_TRANSCRIPT.SEND_EMAIL_SUCCESS'),
+          type: 'success',
+        });
+      } catch (error) {
+        emitter.emit(BUS_EVENTS.SHOW_ALERT, {
+          message: this.$t('EMAIL_TRANSCRIPT.SEND_EMAIL_ERROR'),
+        });
+      } finally {
+        this.isSendingTranscript = false;
       }
     },
   },
@@ -144,6 +168,7 @@ export default {
       v-if="showEmailTranscriptButton"
       type="clear"
       class="font-normal"
+      :disabled="isSendingTranscript || transcriptCooldown"
       @click="sendTranscript"
     >
       {{ $t('EMAIL_TRANSCRIPT.BUTTON_TEXT') }}

config/app.yml

@@ -1,5 +1,5 @@
 shared: &shared
-  version: '4.16.0'
+  version: '4.16.1'
 
 development:
   <<: *shared

config/llm.yml

@@ -143,6 +143,20 @@ features:
         gemini-3-pro,
       ]
     default: gpt-5.2
+  conversation_faq_matching:
+    models:
+      [
+        gpt-4.1-mini,
+        gpt-5-mini,
+        gpt-4.1,
+        gpt-5.1,
+        gpt-5.2,
+        claude-haiku-4.5,
+        claude-sonnet-4.5,
+        gemini-3-flash,
+        gemini-3-pro,
+      ]
+    default: gpt-4.1-mini
   pdf_faq_generation:
     models: [gpt-4.1-mini, gpt-5-mini, gpt-4.1, gpt-5.1, gpt-5.2]
     default: gpt-4.1-mini

config/locales/en.yml

@@ -626,6 +626,7 @@ en:
         label_suggestion: 'Label suggestion'
         document_faq_generation: 'Document FAQ generation'
         conversation_faq_generation: 'Conversation FAQ generation'
+        conversation_faq_matching: 'Conversation FAQ matching'
         help_center_article_generation: 'Help center article generation'
         onboarding_content_generation: 'Onboarding content generation'
         help_center_query_translation: 'Help center query translation'

config/routes.rb

@@ -66,7 +66,8 @@ Rails.application.routes.draw do
             resources :assistants do
               member do
                 post :playground
-                get :stats
+                get :metrics
+                get :faq_stats
                 get :summary
                 get :drilldown
               end
@@ -78,6 +79,10 @@ Rails.application.routes.draw do
             end
             resources :agent_sessions, only: [:show]
             resources :assistant_responses
+            resources :faq_suggestions, only: [:index, :show, :update] do
+              post :approve, on: :member
+              post :dismiss, on: :member
+            end
             resources :message_reports, only: [:create]
             resources :bulk_actions, only: [:create]
             resources :copilot_threads, only: [:index, :create] do

enterprise/app/builders/captain/assistant_stats_builder.rb

@@ -37,6 +37,23 @@ class Captain::AssistantStatsBuilder
     build_metrics(current, previous)
   end
 
+  # Approved/pending FAQ counts and the document total in a single round trip.
+  def faq_stats
+    approved, pending, documents = Captain::AssistantResponse.by_assistant(assistant.id).reorder(nil).pick(
+      Arel.sql("COUNT(*) FILTER (WHERE status = #{Captain::AssistantResponse.statuses['approved']})"),
+      Arel.sql("COUNT(*) FILTER (WHERE status = #{Captain::AssistantResponse.statuses['pending']})"),
+      Arel.sql("(SELECT COUNT(*) FROM captain_documents WHERE assistant_id = #{assistant.id.to_i})")
+    )
+    total = approved + pending
+
+    {
+      approved: approved,
+      pending: pending,
+      documents: documents,
+      coverage: total.zero? ? 0 : (approved.to_f / total * 100).round
+    }
+  end
+
   private
 
   attr_reader :window
@@ -56,8 +73,7 @@ class Captain::AssistantStatsBuilder
       handoff_rate: pack(current[:handoff], previous[:handoff], :point),
       hours_saved: pack(current[:hours_saved], previous[:hours_saved], :percent),
       reopen_rate: pack(current[:reopen], previous[:reopen], :point),
-      conversation_depth: pack(current[:depth], previous[:depth], :absolute),
-      knowledge: knowledge
+      conversation_depth: pack(current[:depth], previous[:depth], :absolute)
     }
   end
 
@@ -73,7 +89,7 @@ class Captain::AssistantStatsBuilder
       auto_resolution: rate(resolution[:resolved], handled),
       handoff: rate(resolution[:handoff], handled),
       hours_saved: (public_count * SECONDS_SAVED_PER_REPLY / 3600.0).round,
-      reopen: reopen_rate(range),
+      reopen: reopen_rate(range, resolution[:resolved]),
       depth: depth_conversations.zero? ? 0 : (public_count.to_f / depth_conversations).round(1)
     }
   end
@@ -158,7 +174,9 @@ class Captain::AssistantStatsBuilder
   # derived from the assistant's handled conversations (not current inbox membership) so a later
   # inbox reassignment doesn't drop historical resolves, and covers both the evaluated (inference)
   # and time-based (bot) resolve paths so the denominator matches auto_resolution_rate.
-  def reopen_rate(range)
+  def reopen_rate(range, resolved_count)
+    return 0 if resolved_count.zero?
+
     resolved_scope = account.reporting_events
                             .where(name: RESOLVED_EVENT_NAMES, created_at: range,
                                    conversation_id: handled_scope(range).select(:conversation_id))
@@ -178,24 +196,7 @@ class Captain::AssistantStatsBuilder
                              'ON resolves.conversation_id = reporting_events.conversation_id ' \
                              'AND reporting_events.event_end_time >= resolves.event_end_time')
                       .distinct.count('reporting_events.conversation_id')
-    rate(reopened, resolved_scope.distinct.count(:conversation_id))
-  end
-
-  # Approved/pending FAQ counts and the document total in a single round trip.
-  def knowledge
-    approved, pending, documents = Captain::AssistantResponse.by_assistant(assistant.id).reorder(nil).pick(
-      Arel.sql("COUNT(*) FILTER (WHERE status = #{Captain::AssistantResponse.statuses['approved']})"),
-      Arel.sql("COUNT(*) FILTER (WHERE status = #{Captain::AssistantResponse.statuses['pending']})"),
-      Arel.sql("(SELECT COUNT(*) FROM captain_documents WHERE assistant_id = #{assistant.id.to_i})")
-    )
-    total = approved + pending
-
-    {
-      approved: approved,
-      pending: pending,
-      documents: documents,
-      coverage: total.zero? ? 0 : (approved.to_f / total * 100).round
-    }
+    rate(reopened, resolved_count)
   end
 
   def rate(numerator, denominator)

enterprise/app/controllers/api/v1/accounts/captain/assistants_controller.rb

@@ -1,7 +1,7 @@
 class Api::V1::Accounts::Captain::AssistantsController < Api::V1::Accounts::BaseController
   before_action -> { check_authorization(Captain::Assistant) }
 
-  before_action :set_assistant, only: [:show, :update, :destroy, :playground, :stats, :summary, :drilldown]
+  before_action :set_assistant, only: [:show, :update, :destroy, :playground, :metrics, :faq_stats, :summary, :drilldown]
 
   def index
     @assistants = account_assistants.ordered
@@ -42,10 +42,14 @@ class Api::V1::Accounts::Captain::AssistantsController < Api::V1::Accounts::Base
     @tools = assistant.available_agent_tools
   end
 
-  def stats
+  def metrics
     render json: Captain::AssistantStatsBuilder.new(@assistant, params[:range], params[:timezone_offset]).metrics
   end
 
+  def faq_stats
+    render json: Captain::AssistantStatsBuilder.new(@assistant).faq_stats
+  end
+
   def summary
     window = Captain::AssistantStatsWindow.new(params[:range], params[:timezone_offset])
     result = cached_or_generated_summary(window, summary_stats)

enterprise/app/controllers/api/v1/accounts/captain/faq_suggestions_controller.rb

@@ -0,0 +1,80 @@
+class Api::V1::Accounts::Captain::FaqSuggestionsController < Api::V1::Accounts::BaseController
+  before_action :current_account
+  before_action -> { check_authorization(Captain::FaqSuggestion) }
+  before_action :set_accessible_suggestions
+  before_action :set_suggestion, except: [:index]
+
+  RESULTS_PER_PAGE = 25
+  SOURCE_PREVIEW_LIMIT = 50
+
+  def index
+    @current_page = permitted_params[:page] || 1
+    filtered_query = apply_filters(@suggestions)
+    @suggestions_count = filtered_query.count
+    @suggestions = filtered_query.page(@current_page).per(RESULTS_PER_PAGE)
+  end
+
+  def show
+    @observations = @suggestion.observations
+                               .where(conversation_id: accessible_conversations.select(:id))
+                               .includes(:conversation)
+                               .order(created_at: :desc)
+                               .limit(SOURCE_PREVIEW_LIMIT)
+  end
+
+  def update
+    @suggestion.with_lock do
+      raise ActiveRecord::RecordNotFound unless @suggestion.open?
+
+      @suggestion.update!(suggestion_params)
+    end
+  end
+
+  def approve
+    attributes = params[:faq_suggestion].present? ? suggestion_params : {}
+    @response = Captain::FaqSuggestionApprovalService.new(@suggestion, attributes).perform
+  end
+
+  def dismiss
+    @suggestion.with_lock do
+      raise ActiveRecord::RecordNotFound unless @suggestion.open?
+
+      @suggestion.dismissed!
+    end
+  end
+
+  private
+
+  def apply_filters(base_query)
+    base_query = base_query.where(assistant_id: permitted_params[:assistant_id]) if permitted_params[:assistant_id].present?
+    base_query = base_query.where(status: permitted_params[:status]) if permitted_params[:status].present?
+
+    if permitted_params[:search].present?
+      # TODO: Move FAQ suggestion search to Elasticsearch when the records are indexed there.
+      search_term = "%#{permitted_params[:search]}%"
+      base_query = base_query.where('question ILIKE :search OR answer ILIKE :search', search: search_term)
+    end
+
+    base_query
+  end
+
+  def set_accessible_suggestions
+    @suggestions = Captain::FaqSuggestionFinder.new(Current.user, Current.account).perform.includes(:assistant).ordered
+  end
+
+  def set_suggestion
+    @suggestion = @suggestions.find(permitted_params[:id])
+  end
+
+  def accessible_conversations
+    Conversations::PermissionFilterService.new(Current.account.conversations, Current.user, Current.account).perform
+  end
+
+  def permitted_params
+    params.permit(:id, :assistant_id, :page, :status, :search)
+  end
+
+  def suggestion_params
+    params.require(:faq_suggestion).permit(:question, :answer)
+  end
+end

enterprise/app/controllers/enterprise/api/v1/accounts/agents_controller.rb

@@ -1,6 +1,8 @@
 module Enterprise::Api::V1::Accounts::AgentsController
   def create
     super
+    return if @agent.blank?
+
     associate_agent_with_custom_role
   end
 

enterprise/app/finders/captain/faq_suggestion_finder.rb

@@ -0,0 +1,26 @@
+class Captain::FaqSuggestionFinder
+  def initialize(current_user, current_account)
+    @current_user = current_user
+    @current_account = current_account
+  end
+
+  def perform
+    suggestions = @current_account.captain_faq_suggestions
+    return suggestions if account_user&.administrator?
+
+    accessible_suggestion_ids = Captain::FaqObservation
+                                .where(conversation_id: accessible_conversations.select(:id))
+                                .select(:faq_suggestion_id)
+    suggestions.where(id: accessible_suggestion_ids)
+  end
+
+  private
+
+  def accessible_conversations
+    Conversations::PermissionFilterService.new(@current_account.conversations, @current_user, @current_account).perform
+  end
+
+  def account_user
+    @account_user ||= @current_account.account_users.find_by(user_id: @current_user.id)
+  end
+end

enterprise/app/jobs/captain/llm/conversation_faq_job.rb

@@ -0,0 +1,30 @@
+class Captain::Llm::ConversationFaqJob < MutexApplicationJob
+  queue_as :low
+
+  LOCK_TIMEOUT = 10.minutes
+
+  retry_on_lock_conflict wait: 30.seconds, attempts: 30
+
+  def perform(conversation, assistant)
+    inbox = conversation.inbox
+
+    return unless conversation.resolved?
+    return unless inbox.captain_active?
+
+    return if assistant.config['feature_faq'].blank?
+
+    with_lock(lock_key(assistant, conversation), LOCK_TIMEOUT) do
+      Captain::Llm::ConversationFaqService.new(assistant, conversation).generate_suggestions
+    end
+  end
+
+  private
+
+  def lock_key(assistant, conversation)
+    format(
+      ::Redis::Alfred::CAPTAIN_CONVERSATION_FAQ_MUTEX,
+      assistant_id: assistant.id,
+      language: Captain::Llm::ConversationFaqService.language_for(conversation)
+    )
+  end
+end

enterprise/app/listeners/captain_listener.rb

@@ -8,6 +8,6 @@ class CaptainListener < BaseListener
     return unless conversation.inbox.captain_active?
 
     Captain::Llm::ContactNotesService.new(assistant, conversation).generate_and_update_notes if assistant.config['feature_memory'].present?
-    Captain::Llm::ConversationFaqService.new(assistant, conversation).generate_and_deduplicate if assistant.config['feature_faq'].present?
+    Captain::Llm::ConversationFaqJob.perform_later(conversation, assistant) if assistant.config['feature_faq'].present?
   end
 end

enterprise/app/policies/captain/assistant_policy.rb

@@ -7,7 +7,11 @@ class Captain::AssistantPolicy < ApplicationPolicy
     true
   end
 
-  def stats?
+  def metrics?
+    true
+  end
+
+  def faq_stats?
     true
   end
 
@@ -31,6 +35,14 @@ class Captain::AssistantPolicy < ApplicationPolicy
     @account_user.administrator?
   end
 
+  def approve?
+    update?
+  end
+
+  def dismiss?
+    update?
+  end
+
   def destroy?
     @account_user.administrator?
   end

enterprise/app/policies/captain/faq_suggestion_policy.rb

@@ -0,0 +1,21 @@
+class Captain::FaqSuggestionPolicy < ApplicationPolicy
+  def index?
+    true
+  end
+
+  def show?
+    true
+  end
+
+  def update?
+    true
+  end
+
+  def approve?
+    true
+  end
+
+  def dismiss?
+    true
+  end
+end

enterprise/app/services/captain/faq_suggestion_approval_service.rb

@@ -0,0 +1,26 @@
+class Captain::FaqSuggestionApprovalService
+  def initialize(suggestion, attributes = {})
+    @suggestion = suggestion
+    @attributes = attributes
+  end
+
+  def perform
+    suggestion.with_lock do
+      raise ActiveRecord::RecordNotFound unless suggestion.open?
+
+      suggestion.update!(attributes) if attributes.present?
+
+      response = suggestion.assistant.responses.create!(
+        question: suggestion.question,
+        answer: suggestion.answer,
+        status: :approved
+      )
+      suggestion.approved!
+      response
+    end
+  end
+
+  private
+
+  attr_reader :suggestion, :attributes
+end

enterprise/app/services/captain/llm/conversation_faq_content_service.rb

@@ -0,0 +1,66 @@
+class Captain::Llm::ConversationFaqContentService
+  def initialize(assistant, conversation)
+    @assistant = assistant
+    @conversation = conversation
+  end
+
+  def generate
+    [
+      'Business Context:',
+      JSON.pretty_generate(business_context),
+      "Conversation ID: ##{conversation.display_id}",
+      "Channel: #{conversation.inbox.channel.name}",
+      'Message History:',
+      conversation_messages
+    ].join("\n")
+  end
+
+  private
+
+  attr_reader :assistant, :conversation
+
+  def conversation_messages
+    messages = conversation
+               .messages
+               .where(message_type: %i[incoming outgoing], private: false)
+               .order(created_at: :asc)
+
+    return "No messages in this conversation\n" if messages.empty?
+
+    messages.filter_map { |message| format_message(message) }.join
+  end
+
+  def format_message(message)
+    return unless source_message?(message)
+
+    message_content = message.content_for_llm
+    return if message_content.blank?
+
+    sender = human_support_reply?(message) ? 'Support Agent' : 'User'
+    "#{sender}: #{message_content}\n"
+  end
+
+  def source_message?(message)
+    return true if message.incoming? && message.sender_type == 'Contact'
+
+    human_support_reply?(message)
+  end
+
+  def human_support_reply?(message)
+    return false unless message.outgoing?
+    return false if message.content_attributes['automation_rule_id'].present?
+    return false if message.additional_attributes['campaign_id'].present?
+
+    message.sender_type == 'User' || message.content_attributes['external_echo'].present?
+  end
+
+  def business_context
+    {
+      product_name: assistant.config['product_name'],
+      assistant_description: assistant.description,
+      instructions: assistant.config['instructions'],
+      response_guidelines: assistant.response_guidelines,
+      guardrails: assistant.guardrails
+    }.compact
+  end
+end

enterprise/app/services/captain/llm/conversation_faq_prompts_service.rb

@@ -0,0 +1,75 @@
+class Captain::Llm::ConversationFaqPromptsService
+  class << self
+    def generator(language = 'english')
+      <<~PROMPT
+        You create high-quality FAQ candidates from resolved support conversations.
+        Only generate an FAQ when the conversation contains durable, reusable knowledge that would help many future customers.
+
+        ## Source rules
+        - The input starts with trusted business context. Use it to reject conversations about other businesses or topics, but never use it as the source of an FAQ answer.
+        - The conversation history contains only customer messages and human support agent messages.
+        - Base every FAQ strictly on information stated in the human support agent messages. Do not infer, generalize, or add external knowledge.
+        - A human support agent must state every fact used in the FAQ answer. Customer messages cannot supply missing answer facts.
+        - The human support agent must provide the final answer. If the agent only greets, asks clarifying questions, asks for contact details, promises to check, shares an attachment, or transfers the conversation, return: `{"faqs":[]}`.
+        - For each FAQ, identify the human support agent message or messages that together provide a complete public answer to the same question. Combine facts only across related agent messages; never combine separate questions or unrelated topics. If those messages do not provide a complete public answer, remove that FAQ.
+
+        ## Decision gate
+        Return `{"faqs":[]}` unless every generated FAQ can pass all of these checks:
+        1. The answer is fully stated by a human support agent, not by the customer.
+        2. The answer is a public, durable rule or procedure, not a private account action, manual review, troubleshooting session, quote, file, link, or follow-up.
+        3. The answer can be written without private identifiers, customer-specific facts, direct URLs, attachments, invoices, screenshots, or support-ticket steps.
+        4. The question would still make sense in a help center if the original conversation, customer, and agent did not exist.
+        Do not rescue a rejected conversation by rewriting it as a generic support question.
+
+        ## Return no FAQ for
+        - Spam, scams, advertisements, SEO/link-building pitches, adult/gambling/financial promotions, gibberish, abusive content, or conversations unrelated to the business being supported.
+        - Account-specific, order-specific, payment-specific, subscription-specific, login/access, verification, delivery, certificate, or troubleshooting issues, even if they could be rewritten as a general support question.
+        - Conversations that mainly hand off to a human, ask the customer to wait, request private identifiers or contact details, collect screenshots, attachments, or documents, or tell the customer to contact support for case review.
+        - Temporary workarounds, one-off exceptions, unclear answers, unresolved problems, wrong-service conversations, complaints, greetings, or abandoned conversations.
+        - Internal support workflow details, chat session rules, escalation mechanics, ticket-routing instructions, or "someone will get back to you" messages.
+        - Answers that are just a direct/private link, attachment, file, invoice, one-off quote or estimate, account-specific URL, or instructions to open a support ticket.
+        - Questions whose useful answer is "contact support", "wait for the team", "share your details", "we will check", or "this needs manual review".
+        - Questions about whether support can help with a private issue, third-party service, transaction, payment, delivery, or account problem.
+        - Pricing, policy, availability, roadmap, deadline, or legal claims unless the human support agent gives a clear and stable answer in the conversation.
+        - Questions already answered only by asking the customer for more information.
+
+        ## FAQ quality rules
+        - Prefer returning no FAQ over a weak or narrow FAQ.
+        - A good candidate teaches a generally reusable product, service, policy, setup, or process rule that another customer could use without contacting support.
+        - Generate at most one FAQ unless the human agent clearly answered multiple distinct, reusable questions.
+        - Do not create duplicate or overlapping FAQs in the same response.
+        - Questions must be general enough for a help center, not personalized to the current customer.
+        - Remove customer names, order numbers, invoice numbers, IDs, private URLs, phone numbers, emails, screenshots, attachments, and other personal or transaction-specific details.
+        - Answers must be complete, self-contained, and supported by the human agent's messages.
+
+        ## Examples
+        - Customer mentions a price or procedure, then the human agent only greets or says they will check: return `{"faqs":[]}`.
+        - Human agent shares only a private link, file, invoice, quote, screenshot, or attachment: return `{"faqs":[]}`.
+        - Human agent clearly states a public rule, such as which purchases are allowed for a program or service: generate one general FAQ.
+
+        Generate the FAQs only in the #{language}, use no other language.
+        If no suitable reusable FAQ is available, return: `{"faqs":[]}`.
+
+        Return only valid JSON in this exact structure:
+        ```json
+        { "faqs": [ { "question": "", "answer": "" } ] }
+        ```
+      PROMPT
+    end
+
+    def same_faq
+      <<~PROMPT
+        Decide whether the new FAQ and existing FAQ are the same.
+
+        Return `same_faq` as true only when both questions ask the same thing and both answers give the same guidance.
+        Wording, grammar, level of detail, and examples may differ. Return false when either FAQ adds, removes, contradicts, or changes a condition,
+        policy, procedure, audience, product, plan, time frame, or outcome. Related FAQs are not the same FAQ. When uncertain, return false.
+
+        Return only valid JSON in this exact structure:
+        ```json
+        { "same_faq": true }
+        ```
+      PROMPT
+    end
+  end
+end

enterprise/app/services/captain/llm/conversation_faq_service.rb

@@ -1,167 +1,208 @@
 class Captain::Llm::ConversationFaqService < Llm::BaseAiService
   include Integrations::LlmInstrumentation
 
+  class SuggestionChangedError < StandardError; end
+
   DISTANCE_THRESHOLD = 0.3
+  MATCH_LIMIT = 5
   LLM_FEATURE = 'conversation_faq_generation'.freeze
 
+  def self.language_for(conversation)
+    language = conversation.language.presence || conversation.account.locale.presence || I18n.default_locale.to_s
+    normalize_language(language)
+  end
+
+  def self.normalize_language(language)
+    language.to_s.tr('-', '_').split('_').first.downcase
+  end
+
+  private_class_method :normalize_language
+
   def initialize(assistant, conversation)
     super(feature: LLM_FEATURE, account: conversation.account, fallback_model: Llm::Models.default_model_for(LLM_FEATURE))
     @assistant = assistant
     @conversation = conversation
-    @content = conversation_faq_content
+    @content = Captain::Llm::ConversationFaqContentService.new(assistant, conversation).generate
+    @embedding_service = Captain::Llm::EmbeddingService.new(account_id: conversation.account_id)
   end
 
-  # Generates and deduplicates FAQs from conversation content
-  # Skips processing if there was no human interaction
-  def generate_and_deduplicate
+  def generate_suggestions
     return [] if no_human_interaction?
 
-    new_faqs = generate
-    return [] if new_faqs.empty?
-
-    duplicate_faqs, unique_faqs = find_and_separate_duplicates(new_faqs)
-    save_new_faqs(unique_faqs)
-    log_duplicate_faqs(duplicate_faqs) if Rails.env.development?
+    generate.map { |faq| route_candidate(faq) }
   end
 
   private
 
-  attr_reader :content, :conversation, :assistant
-
-  def conversation_faq_content
-    [
-      "Conversation ID: ##{conversation.display_id}",
-      "Channel: #{conversation.inbox.channel.name}",
-      'Message History:',
-      conversation_faq_messages
-    ].join("\n")
-  end
-
-  def conversation_faq_messages
-    messages = conversation
-               .messages
-               .where(message_type: %i[incoming outgoing], private: false)
-               .order(created_at: :asc)
-
-    return "No messages in this conversation\n" if messages.empty?
-
-    messages.filter_map { |message| format_conversation_faq_message(message) }.join
-  end
-
-  def format_conversation_faq_message(message)
-    return unless faq_source_message?(message)
-
-    content = message.content_for_llm
-    return if content.blank?
-
-    sender = human_support_reply?(message) ? 'Support Agent' : 'User'
-    "#{sender}: #{content}\n"
-  end
-
-  def faq_source_message?(message)
-    return true if message.incoming? && message.sender_type == 'Contact'
-
-    human_support_reply?(message)
-  end
-
-  def human_support_reply?(message)
-    return false unless message.outgoing?
-    return false if message.content_attributes['automation_rule_id'].present?
-    return false if message.additional_attributes['campaign_id'].present?
-
-    message.sender_type == 'User' || message.content_attributes['external_echo'].present?
-  end
+  attr_reader :content, :conversation, :assistant, :embedding_service
 
   def no_human_interaction?
     conversation.first_reply_created_at.nil?
   end
 
-  def find_and_separate_duplicates(faqs)
-    duplicate_faqs = []
-    unique_faqs = []
+  def route_candidate(faq)
+    embedding = embedding_service.get_embedding(candidate_text(faq))
 
-    faqs.each do |faq|
-      combined_text = "#{faq['question']}: #{faq['answer']}"
-      embedding = Captain::Llm::EmbeddingService.new(account_id: @conversation.account_id).get_embedding(combined_text)
-      similar_faqs = find_similar_faqs(embedding)
+    return discard_observation(faq) if matching_record(approved_faqs, faq, embedding)
+    return discard_observation(faq) if matching_record(dismissed_suggestions_for_language, faq, embedding)
 
-      if similar_faqs.any?
-        duplicate_faqs << { faq: faq, similar_faqs: similar_faqs }
-      else
-        unique_faqs << faq
-      end
+    suggestion = matching_record(open_suggestions_for_language, faq, embedding)
+    matched_content = suggestion&.slice('question', 'answer')
+    suggestion ||= assistant.faq_suggestions.create!(
+      question: faq.fetch('question'),
+      answer: faq.fetch('answer'),
+      embedding: embedding,
+      language: faq_language
+    )
+
+    attach_observation(suggestion, faq, matched_content)
+  end
+
+  def matching_record(relation, faq, embedding)
+    likely_matches(relation, embedding).find { |record| same_faq?(faq, record) }
+  end
+
+  def likely_matches(relation, embedding)
+    return [] unless relation.exists?
+
+    ApplicationRecord.transaction do
+      # Force an exact search because IVFFlat can miss matches after relation filters.
+      # SET LOCAL keeps the planner change scoped to this transaction.
+      ApplicationRecord.connection.execute('SET LOCAL enable_indexscan = off')
+      relation
+        .nearest_neighbors(:embedding, embedding, distance: 'cosine')
+        .limit(MATCH_LIMIT)
+        .select { |record| record.neighbor_distance < DISTANCE_THRESHOLD }
+    end
+  end
+
+  def same_faq?(candidate, existing_record)
+    comparison = {
+      candidate: candidate.slice('question', 'answer'),
+      existing: { question: existing_record.question, answer: existing_record.answer }
+    }
+    prompt = Captain::Llm::ConversationFaqPromptsService.same_faq
+    faq_match_model = Llm::FeatureRouter.resolve(feature: 'conversation_faq_matching', account: conversation.account)[:model]
+    response = instrument_llm_call(match_instrumentation_params(prompt, comparison, faq_match_model)) do
+      chat(model: faq_match_model)
+        .with_params(response_format: { type: 'json_object' })
+        .with_instructions(prompt)
+        .ask(comparison.to_json)
     end
 
-    [duplicate_faqs, unique_faqs]
+    same_faq = JSON.parse(sanitize_json_response(response.content)).fetch('same_faq')
+    raise TypeError, 'same_faq must be a boolean' unless [true, false].include?(same_faq)
+
+    same_faq
+  rescue JSON::ParserError, KeyError, TypeError, RubyLLM::Error => e
+    Rails.logger.error "FAQ match failed: #{e.message}"
+    raise
   end
 
-  def find_similar_faqs(embedding)
-    similar_faqs = assistant
-                   .responses
-                   .nearest_neighbors(:embedding, embedding, distance: 'cosine')
-    Rails.logger.debug(similar_faqs.map { |faq| [faq.question, faq.neighbor_distance] })
-    similar_faqs.select { |record| record.neighbor_distance < DISTANCE_THRESHOLD }
-  end
+  def attach_observation(suggestion, faq, matched_content)
+    suggestion.with_lock do
+      next unless suggestion.open?
+      raise SuggestionChangedError if matched_content && suggestion.slice('question', 'answer') != matched_content
 
-  def save_new_faqs(faqs)
-    faqs.map do |faq|
-      assistant.responses.create!(
-        question: faq['question'],
-        answer: faq['answer'],
-        status: 'pending',
-        documentable: conversation
+      existing_observation = suggestion.observations.find_by(conversation: conversation)
+      next existing_observation if existing_observation
+
+      observation = suggestion.observations.create!(
+        conversation: conversation,
+        generated_question: faq.fetch('question'),
+        generated_answer: faq.fetch('answer'),
+        language: faq_language,
+        status: :attached
       )
+      suggestion.update!(source_count: suggestion.source_count + 1)
+      observation
     end
   end
 
-  def log_duplicate_faqs(duplicate_faqs)
-    return if duplicate_faqs.empty?
+  def discard_observation(faq)
+    Captain::FaqObservation.find_or_create_by!(
+      conversation: conversation,
+      generated_question: faq.fetch('question'),
+      generated_answer: faq.fetch('answer'),
+      language: faq_language,
+      status: :discarded
+    )
+  end
 
-    Rails.logger.info "Found #{duplicate_faqs.length} duplicate FAQs:"
-    duplicate_faqs.each do |duplicate|
-      Rails.logger.info(
-        "Q: #{duplicate[:faq]['question']}\n" \
-        "A: #{duplicate[:faq]['answer']}\n\n" \
-        "Similar existing FAQs: #{duplicate[:similar_faqs].map { |f| "Q: #{f.question} A: #{f.answer}" }.join(', ')}"
-      )
-    end
+  def open_suggestions_for_language
+    assistant.faq_suggestions.where(account_id: conversation.account_id).open.by_language(faq_language)
+  end
+
+  def dismissed_suggestions_for_language
+    assistant.faq_suggestions.where(account_id: conversation.account_id).dismissed.by_language(faq_language)
+  end
+
+  def approved_faqs
+    assistant.responses.approved
+  end
+
+  def candidate_text(faq)
+    "#{faq.fetch('question')}: #{faq.fetch('answer')}"
   end
 
   def generate
-    response = instrument_llm_call(instrumentation_params) do
+    response = instrument_llm_call(generation_instrumentation_params) do
       chat
         .with_params(response_format: { type: 'json_object' })
         .with_instructions(system_prompt)
-        .ask(@content)
+        .ask(content)
     end
-    parse_response(response.content)
+    parse_generation_response(response.content)
   rescue RubyLLM::Error => e
     Rails.logger.error "LLM API Error: #{e.message}"
     []
   end
 
-  def instrumentation_params
+  def generation_instrumentation_params
     {
       span_name: 'llm.captain.conversation_faq',
-      model: @model,
-      temperature: @temperature,
-      account_id: @conversation.account_id,
-      conversation_id: @conversation.display_id,
+      model: model,
+      temperature: temperature,
+      account_id: conversation.account_id,
+      conversation_id: conversation.display_id,
       feature_name: 'conversation_faq',
       messages: [
         { role: 'system', content: system_prompt },
-        { role: 'user', content: @content }
+        { role: 'user', content: content }
       ],
-      metadata: { assistant_id: @assistant.id }
+      metadata: { assistant_id: assistant.id, language: faq_language }
+    }
+  end
+
+  def match_instrumentation_params(prompt, comparison, faq_match_model)
+    {
+      span_name: 'llm.captain.faq_match',
+      model: faq_match_model,
+      temperature: temperature,
+      account_id: conversation.account_id,
+      conversation_id: conversation.display_id,
+      feature_name: 'conversation_faq_match',
+      messages: [
+        { role: 'system', content: prompt },
+        { role: 'user', content: comparison.to_json }
+      ],
+      metadata: { assistant_id: assistant.id, language: faq_language }
     }
   end
 
   def system_prompt
-    account_language = @conversation.account.locale_english_name
-    Captain::Llm::SystemPromptsService.conversation_faq_generator(account_language)
+    Captain::Llm::ConversationFaqPromptsService.generator(language_name(faq_language))
   end
 
-  def parse_response(response)
+  def faq_language
+    @faq_language ||= self.class.language_for(conversation)
+  end
+
+  def language_name(language)
+    ISO_639.find(language)&.english_name&.downcase || 'english'
+  end
+
+  def parse_generation_response(response)
     return [] if response.nil?
 
     JSON.parse(sanitize_json_response(response)).fetch('faqs', [])

enterprise/app/services/captain/llm/system_prompts_service.rb

@@ -51,62 +51,6 @@ class Captain::Llm::SystemPromptsService
       PROMPT
     end
 
-    def conversation_faq_generator(language = 'english')
-      <<~SYSTEM_PROMPT_MESSAGE
-        You create high-quality FAQ candidates from resolved support conversations.
-        Only generate an FAQ when the conversation contains durable, reusable knowledge that would help many future customers.
-
-        ## Source rules
-        - The conversation history contains only customer messages and human support agent messages.
-        - Base every FAQ strictly on information stated in the human support agent messages. Do not infer, generalize, or add external knowledge.
-        - A human support agent must state every fact used in the FAQ answer. Customer messages cannot supply missing answer facts.
-        - The human support agent must provide the final answer. If the agent only greets, asks clarifying questions, asks for contact details, promises to check, shares an attachment, or transfers the conversation, return: `{"faqs":[]}`.
-        - For each FAQ, first identify the exact human support agent message that fully answers it. If no single human agent message gives a complete public answer, remove that FAQ.
-
-        ## Decision gate
-        Return `{"faqs":[]}` unless every generated FAQ can pass all of these checks:
-        1. The answer is fully stated by a human support agent, not by the customer.
-        2. The answer is a public, durable rule or procedure, not a private account action, manual review, troubleshooting session, quote, file, link, or follow-up.
-        3. The answer can be written without private identifiers, customer-specific facts, direct URLs, attachments, invoices, screenshots, or support-ticket steps.
-        4. The question would still make sense in a help center if the original conversation, customer, and agent did not exist.
-        Do not rescue a rejected conversation by rewriting it as a generic support question.
-
-        ## Return no FAQ for
-        - Spam, scams, advertisements, SEO/link-building pitches, adult/gambling/financial promotions, gibberish, abusive content, or conversations unrelated to the business being supported.
-        - Account-specific, order-specific, payment-specific, subscription-specific, login/access, verification, delivery, certificate, or troubleshooting issues, even if they could be rewritten as a general support question.
-        - Conversations that mainly hand off to a human, ask the customer to wait, request private identifiers or contact details, collect screenshots, attachments, or documents, or tell the customer to contact support for case review.
-        - Temporary workarounds, one-off exceptions, unclear answers, unresolved problems, wrong-service conversations, complaints, greetings, or abandoned conversations.
-        - Internal support workflow details, chat session rules, escalation mechanics, ticket-routing instructions, or "someone will get back to you" messages.
-        - Answers that are just a direct/private link, attachment, file, invoice, one-off quote or estimate, account-specific URL, or instructions to open a support ticket.
-        - Questions whose useful answer is "contact support", "wait for the team", "share your details", "we will check", or "this needs manual review".
-        - Questions about whether support can help with a private issue, third-party service, transaction, payment, delivery, or account problem.
-        - Pricing, policy, availability, roadmap, deadline, or legal claims unless the human support agent gives a clear and stable answer in the conversation.
-        - Questions already answered only by asking the customer for more information.
-
-        ## FAQ quality rules
-        - Prefer returning no FAQ over a weak or narrow FAQ.
-        - A good candidate teaches a generally reusable product, service, policy, setup, or process rule that another customer could use without contacting support.
-        - Generate at most one FAQ unless the human agent clearly answered multiple distinct, reusable questions.
-        - Do not create duplicate or overlapping FAQs in the same response.
-        - Questions must be general enough for a help center, not personalized to the current customer.
-        - Remove customer names, order numbers, invoice numbers, IDs, private URLs, phone numbers, emails, screenshots, attachments, and other personal or transaction-specific details.
-        - Answers must be complete, self-contained, and supported by the human agent's messages.
-
-        ## Examples
-        - Customer mentions a price or procedure, then the human agent only greets or says they will check: return `{"faqs":[]}`.
-        - Human agent shares only a private link, file, invoice, quote, screenshot, or attachment: return `{"faqs":[]}`.
-        - Human agent clearly states a public rule, such as which purchases are allowed for a program or service: generate one general FAQ.
-
-        Generate the FAQs only in the #{language}, use no other language.
-        If no suitable reusable FAQ is available, return: `{"faqs":[]}`.
-
-        Return only valid JSON in this exact structure:
-        ```json
-        { "faqs": [ { "question": "", "answer": "" } ] }
-        ```
-      SYSTEM_PROMPT_MESSAGE
-    end
-
     def notes_generator(language = 'english')
       <<~SYSTEM_PROMPT_MESSAGE
         You are a note taker looking to convert the conversation with a contact into actionable notes for the CRM.

enterprise/app/views/api/v1/accounts/captain/faq_suggestions/approve.json.jbuilder

@@ -0,0 +1 @@
+json.partial! 'api/v1/models/captain/assistant_response', formats: [:json], resource: @response

enterprise/app/views/api/v1/accounts/captain/faq_suggestions/dismiss.json.jbuilder

@@ -0,0 +1 @@
+json.partial! 'api/v1/models/captain/faq_suggestion', formats: [:json], resource: @suggestion

enterprise/app/views/api/v1/accounts/captain/faq_suggestions/index.json.jbuilder

@@ -0,0 +1,10 @@
+json.payload do
+  json.array! @suggestions do |suggestion|
+    json.partial! 'api/v1/models/captain/faq_suggestion', formats: [:json], resource: suggestion
+  end
+end
+
+json.meta do
+  json.total_count @suggestions_count
+  json.page @current_page
+end

enterprise/app/views/api/v1/accounts/captain/faq_suggestions/show.json.jbuilder

@@ -0,0 +1,6 @@
+json.partial! 'api/v1/models/captain/faq_suggestion', formats: [:json], resource: @suggestion
+json.observations do
+  json.array! @observations do |observation|
+    json.partial! 'api/v1/models/captain/faq_observation', formats: [:json], resource: observation
+  end
+end

enterprise/app/views/api/v1/accounts/captain/faq_suggestions/update.json.jbuilder

@@ -0,0 +1 @@
+json.partial! 'api/v1/models/captain/faq_suggestion', formats: [:json], resource: @suggestion

enterprise/app/views/api/v1/models/captain/_faq_observation.json.jbuilder

@@ -0,0 +1,10 @@
+json.id resource.id
+json.generated_question resource.generated_question
+json.generated_answer resource.generated_answer
+json.language resource.language
+json.status resource.status
+json.created_at resource.created_at.to_i
+json.conversation do
+  json.id resource.conversation.id
+  json.display_id resource.conversation.display_id
+end

enterprise/app/views/api/v1/models/captain/_faq_suggestion.json.jbuilder

@@ -0,0 +1,12 @@
+json.id resource.id
+json.account_id resource.account_id
+json.question resource.question
+json.answer resource.answer
+json.language resource.language
+json.source_count resource.source_count
+json.status resource.status
+json.created_at resource.created_at.to_i
+json.updated_at resource.updated_at.to_i
+json.assistant do
+  json.partial! 'api/v1/models/captain/assistant', formats: [:json], resource: resource.assistant
+end

lib/redis/redis_keys.rb

@@ -89,6 +89,7 @@ module Redis::RedisKeys
   WHATSAPP_MESSAGE_MUTEX = 'WHATSAPP_MESSAGE_CREATE_LOCK::%<inbox_id>s::%<sender_id>s'.freeze
   CRM_PROCESS_MUTEX = 'CRM_PROCESS_MUTEX::%<hook_id>s'.freeze
   CAPTAIN_DOCUMENT_SYNC_MUTEX = 'CAPTAIN_DOCUMENT_SYNC_LOCK::%<document_id>s'.freeze
+  CAPTAIN_CONVERSATION_FAQ_MUTEX = 'CAPTAIN_CONVERSATION_FAQ_LOCK::%<assistant_id>s::%<language>s'.freeze
 
   ## Auto Assignment Keys
   # Track conversation assignments to agents for rate limiting

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatwoot/chatwoot",
-  "version": "4.16.0",
+  "version": "4.16.1",
   "license": "MIT",
   "scripts": {
     "eslint": "eslint app/**/*.{js,vue}",
@@ -34,7 +34,7 @@
     "@amplitude/analytics-browser": "^2.11.10",
     "@breezystack/lamejs": "^1.2.7",
     "@chatwoot/ninja-keys": "1.2.3",
-    "@chatwoot/prosemirror-schema": "1.3.22",
+    "@chatwoot/prosemirror-schema": "1.3.23",
     "@chatwoot/utils": "^0.0.56",
     "@formkit/core": "^1.7.2",
     "@formkit/vue": "^1.7.2",
@@ -86,9 +86,6 @@
     "mitt": "^3.0.1",
     "opus-recorder": "^8.0.5",
     "pinia": "^3.0.4",
-    "prosemirror-commands": "^1.7.1",
-    "prosemirror-inputrules": "^1.4.0",
-    "prosemirror-schema-list": "^1.5.1",
     "qrcode": "^1.5.4",
     "semver": "7.6.3",
     "snakecase-keys": "^8.0.1",

pnpm-lock.yaml

@@ -25,8 +25,8 @@ importers:
         specifier: 1.2.3
         version: 1.2.3
       '@chatwoot/prosemirror-schema':
-        specifier: 1.3.22
-        version: 1.3.22
+        specifier: 1.3.23
+        version: 1.3.23
       '@chatwoot/utils':
         specifier: ^0.0.56
         version: 0.0.56
@@ -180,15 +180,6 @@ importers:
       pinia:
         specifier: ^3.0.4
         version: 3.0.4(typescript@5.6.2)(vue@3.5.12(typescript@5.6.2))
-      prosemirror-commands:
-        specifier: ^1.7.1
-        version: 1.7.1
-      prosemirror-inputrules:
-        specifier: ^1.4.0
-        version: 1.4.0
-      prosemirror-schema-list:
-        specifier: ^1.5.1
-        version: 1.5.1
       qrcode:
         specifier: ^1.5.4
         version: 1.5.4
@@ -461,8 +452,8 @@ packages:
   '@chatwoot/ninja-keys@1.2.3':
     resolution: {integrity: sha512-xM8d9P5ikDMZm2WbaCTk/TW5HFauylrU3cJ75fq5je6ixKwyhl/0kZbVN/vbbZN4+AUX/OaSIn6IJbtCgIF67g==}
 
-  '@chatwoot/prosemirror-schema@1.3.22':
-    resolution: {integrity: sha512-0r+PT8xhQLCKCpoV9k9XVTTRECs/0Nr37wbcLsRS7yvc7WkF9FY05z2hGCRJReWmTOcmmshHtb042LVP+MyB/w==}
+  '@chatwoot/prosemirror-schema@1.3.23':
+    resolution: {integrity: sha512-jGxbWELCdlVI64BJiE1wT84ekJHYDXXKiluQIKT3aKPEjPwMR48umKF3A0yHjKoR7IIxCC9oM77TvXOA0ebLtw==}
 
   '@chatwoot/utils@0.0.56':
     resolution: {integrity: sha512-A6dmPLfTSrW4qYNY73btyi4PqpfzcXRSaucscZTQdzNqF6G/QUdgnBmHtho8HeiYby/kSHXaSxLJj+0dx3yEQQ==}
@@ -4001,9 +3992,6 @@ packages:
   prosemirror-tables@1.5.0:
     resolution: {integrity: sha512-VMx4zlYWm7aBlZ5xtfJHpqa3Xgu3b7srV54fXYnXgsAcIGRqKSrhiK3f89omzzgaAgAtDOV4ImXnLKhVfheVNQ==}
 
-  prosemirror-transform@1.10.0:
-    resolution: {integrity: sha512-9UOgFSgN6Gj2ekQH5CTDJ8Rp/fnKR2IkYfGdzzp5zQMFsS4zDllLVx/+jGcX86YlACpG7UR5fwAXiWzxqWtBTg==}
-
   prosemirror-transform@1.12.0:
     resolution: {integrity: sha512-GxboyN4AMIsoHNtz5uf2r2Ru551i5hWeCMD6E2Ib4Eogqoub0NflniaBPVQ4MrGE5yZ8JV9tUHg9qcZTTrcN4w==}
 
@@ -5136,7 +5124,7 @@ snapshots:
       hotkeys-js: 3.8.7
       lit: 2.2.6
 
-  '@chatwoot/prosemirror-schema@1.3.22':
+  '@chatwoot/prosemirror-schema@1.3.23':
     dependencies:
       markdown-it-sup: 2.0.0
       prosemirror-commands: 1.7.1
@@ -9035,7 +9023,7 @@ snapshots:
     dependencies:
       prosemirror-model: 1.22.3
       prosemirror-state: 1.4.3
-      prosemirror-transform: 1.10.0
+      prosemirror-transform: 1.12.0
 
   prosemirror-state@1.4.3:
     dependencies:
@@ -9051,10 +9039,6 @@ snapshots:
       prosemirror-transform: 1.12.0
       prosemirror-view: 1.34.1
 
-  prosemirror-transform@1.10.0:
-    dependencies:
-      prosemirror-model: 1.22.3
-
   prosemirror-transform@1.12.0:
     dependencies:
       prosemirror-model: 1.22.3

spec/builders/agent_builder_spec.rb

@@ -23,6 +23,12 @@ RSpec.describe AgentBuilder, type: :model do
   end
 
   describe '#perform' do
+    it 'locks the account while checking and creating the agent' do
+      expect(account).to receive(:with_lock).and_call_original
+
+      agent_builder.perform
+    end
+
     context 'when user does not exist' do
       it 'creates a new user' do
         expect { agent_builder.perform }.to change(User, :count).by(1)
@@ -67,5 +73,17 @@ RSpec.describe AgentBuilder, type: :model do
         expect(user.encrypted_password).not_to be_empty
       end
     end
+
+    context 'when the account has reached its agent limit' do
+      before do
+        allow(account).to receive(:usage_limits).and_return({ agents: account.account_users.count })
+      end
+
+      it 'raises a limit exceeded error without creating a user' do
+        expect { agent_builder.perform }.to raise_error(described_class::LimitExceededError, described_class::LIMIT_EXCEEDED_MESSAGE)
+
+        expect(User.from_email(email)).to be_nil
+      end
+    end
   end
 end

spec/controllers/api/v1/accounts/integrations/linear_controller_spec.rb

@@ -13,7 +13,9 @@ RSpec.describe 'Linear Integration API', type: :request do
   end
 
   describe 'DELETE /api/v1/accounts/:account_id/integrations/linear' do
-    it 'deletes the linear integration' do
+    let(:admin) { create(:user, account: account, role: :administrator) }
+
+    it 'deletes the linear integration when the user is an administrator' do
       # Stub the HTTP call to Linear's revoke endpoint
       allow(HTTParty).to receive(:post).with(
         'https://api.linear.app/oauth/revoke',
@@ -21,11 +23,19 @@ RSpec.describe 'Linear Integration API', type: :request do
       ).and_return(instance_double(HTTParty::Response, success?: true))
 
       delete "/api/v1/accounts/#{account.id}/integrations/linear",
-             headers: agent.create_new_auth_token,
+             headers: admin.create_new_auth_token,
              as: :json
       expect(response).to have_http_status(:ok)
       expect(account.hooks.count).to eq(0)
     end
+
+    it 'returns unauthorized for an agent and keeps the integration' do
+      delete "/api/v1/accounts/#{account.id}/integrations/linear",
+             headers: agent.create_new_auth_token,
+             as: :json
+      expect(response).to have_http_status(:unauthorized)
+      expect(account.hooks.count).to eq(1)
+    end
   end
 
   describe 'GET /api/v1/accounts/:account_id/integrations/linear/teams' do

spec/controllers/api/v1/accounts/integrations/shopify_controller_spec.rb

@@ -159,15 +159,17 @@ RSpec.describe 'Shopify Integration API', type: :request do
   end
 
   describe 'DELETE /api/v1/accounts/:account_id/integrations/shopify' do
+    let(:admin) { create(:user, account: account, role: :administrator) }
+
     before do
       create(:integrations_hook, :shopify, account: account)
     end
 
-    context 'when it is an authenticated user' do
+    context 'when it is an administrator' do
       it 'deletes the shopify integration' do
         expect do
           delete "/api/v1/accounts/#{account.id}/integrations/shopify",
-                 headers: agent.create_new_auth_token,
+                 headers: admin.create_new_auth_token,
                  as: :json
         end.to change { account.hooks.count }.by(-1)
 
@@ -175,6 +177,18 @@ RSpec.describe 'Shopify Integration API', type: :request do
       end
     end
 
+    context 'when it is an agent' do
+      it 'returns unauthorized and keeps the integration' do
+        expect do
+          delete "/api/v1/accounts/#{account.id}/integrations/shopify",
+                 headers: agent.create_new_auth_token,
+                 as: :json
+        end.not_to(change { account.hooks.count })
+
+        expect(response).to have_http_status(:unauthorized)
+      end
+    end
+
     context 'when it is an unauthenticated user' do
       it 'returns unauthorized' do
         delete "/api/v1/accounts/#{account.id}/integrations/shopify",

spec/enterprise/builders/captain/assistant_stats_builder_spec.rb

@@ -27,7 +27,7 @@ RSpec.describe Captain::AssistantStatsBuilder do
 
       expect(metrics.keys).to contain_exactly(
         :conversations_handled, :auto_resolution_rate, :handoff_rate,
-        :hours_saved, :reopen_rate, :conversation_depth, :knowledge
+        :hours_saved, :reopen_rate, :conversation_depth
       )
       expect(metrics[:conversations_handled]).to include(:current, :previous, :trend)
     end
@@ -229,7 +229,7 @@ RSpec.describe Captain::AssistantStatsBuilder do
     end
   end
 
-  describe '#metrics knowledge' do
+  describe '#faq_stats' do
     before do
       create_list(:captain_assistant_response, 3, assistant: assistant, account: account, status: :approved)
       create(:captain_assistant_response, assistant: assistant, account: account, status: :pending)
@@ -237,7 +237,7 @@ RSpec.describe Captain::AssistantStatsBuilder do
     end
 
     it 'returns approved, pending, document counts and coverage' do
-      knowledge = described_class.new(assistant, '30').metrics[:knowledge]
+      knowledge = described_class.new(assistant).faq_stats
 
       expect(knowledge).to eq(approved: 3, pending: 1, documents: 2, coverage: 75)
     end
@@ -245,7 +245,7 @@ RSpec.describe Captain::AssistantStatsBuilder do
     it 'reports zero coverage when there are no responses' do
       Captain::AssistantResponse.where(assistant: assistant).delete_all
 
-      knowledge = described_class.new(assistant, '30').metrics[:knowledge]
+      knowledge = described_class.new(assistant).faq_stats
 
       expect(knowledge[:coverage]).to eq(0)
     end

spec/enterprise/controllers/api/v1/accounts/agents_controller_spec.rb

@@ -21,6 +21,27 @@ RSpec.describe 'Agents API', type: :request do
         expect(response).to have_http_status(:payment_required)
         expect(response.body).to include('Account limit exceeded. Please purchase more licenses')
       end
+
+      it 'prevents adding an agent if the last seat is consumed before creation' do
+        account.update!(limits: { agents: account.account_users.count + 1 })
+        competing_agent_created = false
+
+        allow(AgentBuilder).to receive(:new).and_wrap_original do |method, *args|
+          unless competing_agent_created
+            create(:user, account: account, role: :agent)
+            competing_agent_created = true
+          end
+
+          method.call(*args)
+        end
+
+        post "/api/v1/accounts/#{account.id}/agents", params: params, headers: admin.create_new_auth_token, as: :json
+
+        expect(response).to have_http_status(:payment_required)
+        expect(response.body).to include('Account limit exceeded. Please purchase more licenses')
+        expect(User.from_email(params[:email])).to be_nil
+        expect(account.account_users.count).to eq(account.usage_limits[:agents])
+      end
     end
   end
 

spec/enterprise/controllers/api/v1/accounts/captain/faq_suggestions_controller_spec.rb

@@ -0,0 +1,216 @@
+require 'rails_helper'
+
+RSpec.describe 'Api::V1::Accounts::Captain::FaqSuggestions', type: :request do
+  let(:account) { create(:account, locale: 'en') }
+  let(:assistant) { create(:captain_assistant, account: account) }
+  let(:admin) { create(:user, account: account, role: :administrator) }
+  let(:agent) { create(:user, account: account, role: :agent) }
+  let(:inbox) { create(:inbox, account: account) }
+  let(:conversation) { create(:conversation, account: account, inbox: inbox) }
+  let(:suggestion) do
+    assistant.faq_suggestions.create!(
+      question: 'How do I enable the feature?',
+      answer: 'Turn it on in settings.',
+      source_count: 1
+    )
+  end
+
+  before do
+    suggestion.observations.create!(
+      conversation: conversation,
+      generated_question: suggestion.question,
+      generated_answer: suggestion.answer,
+      language: suggestion.language
+    )
+  end
+
+  describe 'GET /api/v1/accounts/:account_id/captain/faq_suggestions' do
+    it 'returns suggestions and their count to an administrator' do
+      get "/api/v1/accounts/#{account.id}/captain/faq_suggestions",
+          params: { assistant_id: assistant.id },
+          headers: admin.create_new_auth_token,
+          as: :json
+
+      expect(response).to have_http_status(:success)
+      expect(response.parsed_body['payload']).to contain_exactly(
+        include('id' => suggestion.id, 'question' => suggestion.question, 'status' => 'open')
+      )
+      expect(response.parsed_body['meta']).to include('total_count' => 1)
+    end
+
+    it 'returns only suggestions backed by conversations the agent can access' do
+      create(:inbox_member, user: agent, inbox: inbox)
+      hidden_inbox = create(:inbox, account: account)
+      hidden_conversation = create(:conversation, account: account, inbox: hidden_inbox)
+      hidden_suggestion = assistant.faq_suggestions.create!(question: 'Hidden question', answer: 'Hidden answer')
+      hidden_suggestion.observations.create!(
+        conversation: hidden_conversation,
+        generated_question: hidden_suggestion.question,
+        generated_answer: hidden_suggestion.answer,
+        language: hidden_suggestion.language
+      )
+
+      get "/api/v1/accounts/#{account.id}/captain/faq_suggestions",
+          params: { assistant_id: assistant.id },
+          headers: agent.create_new_auth_token,
+          as: :json
+
+      expect(response).to have_http_status(:success)
+      expect(response.parsed_body['payload'].pluck('id')).to contain_exactly(suggestion.id)
+      expect(response.parsed_body['meta']).to include('total_count' => 1)
+    end
+  end
+
+  describe 'GET /api/v1/accounts/:account_id/captain/faq_suggestions/:id' do
+    it 'returns the suggestion with its source conversation' do
+      get "/api/v1/accounts/#{account.id}/captain/faq_suggestions/#{suggestion.id}",
+          headers: admin.create_new_auth_token,
+          as: :json
+
+      expect(response).to have_http_status(:success)
+      expect(response.parsed_body).to include('id' => suggestion.id, 'question' => suggestion.question)
+      expect(response.parsed_body['observations']).to contain_exactly(
+        include('conversation' => include('id' => conversation.id, 'display_id' => conversation.display_id))
+      )
+    end
+
+    it 'returns only source conversations the agent can access' do
+      create(:inbox_member, user: agent, inbox: inbox)
+      hidden_conversation = create(:conversation, account: account, inbox: create(:inbox, account: account))
+      suggestion.observations.create!(
+        conversation: hidden_conversation,
+        generated_question: suggestion.question,
+        generated_answer: suggestion.answer,
+        language: suggestion.language
+      )
+
+      get "/api/v1/accounts/#{account.id}/captain/faq_suggestions/#{suggestion.id}",
+          headers: agent.create_new_auth_token,
+          as: :json
+
+      expect(response).to have_http_status(:success)
+      expect(response.parsed_body['observations'].pluck('conversation').pluck('id')).to contain_exactly(conversation.id)
+    end
+  end
+
+  describe 'PATCH /api/v1/accounts/:account_id/captain/faq_suggestions/:id' do
+    it 'lets an administrator edit an open suggestion' do
+      patch "/api/v1/accounts/#{account.id}/captain/faq_suggestions/#{suggestion.id}",
+            params: { faq_suggestion: { question: 'Updated question' } },
+            headers: admin.create_new_auth_token,
+            as: :json
+
+      expect(response).to have_http_status(:success)
+      expect(response.parsed_body['question']).to eq('Updated question')
+      expect(suggestion.reload.question).to eq('Updated question')
+    end
+
+    it 'lets an agent edit an accessible suggestion' do
+      create(:inbox_member, user: agent, inbox: inbox)
+
+      patch "/api/v1/accounts/#{account.id}/captain/faq_suggestions/#{suggestion.id}",
+            params: { faq_suggestion: { question: 'Updated question' } },
+            headers: agent.create_new_auth_token,
+            as: :json
+
+      expect(response).to have_http_status(:success)
+      expect(suggestion.reload.question).to eq('Updated question')
+    end
+
+    it 'does not let an agent edit an inaccessible suggestion' do
+      patch "/api/v1/accounts/#{account.id}/captain/faq_suggestions/#{suggestion.id}",
+            params: { faq_suggestion: { question: 'Updated question' } },
+            headers: agent.create_new_auth_token,
+            as: :json
+
+      expect(response).to have_http_status(:not_found)
+      expect(suggestion.reload.question).to eq('How do I enable the feature?')
+    end
+  end
+
+  describe 'POST /api/v1/accounts/:account_id/captain/faq_suggestions/:id/approve' do
+    it 'lets an administrator approve an edited suggestion as an FAQ' do
+      expect do
+        post "/api/v1/accounts/#{account.id}/captain/faq_suggestions/#{suggestion.id}/approve",
+             params: { faq_suggestion: { answer: 'Enable it in account settings.' } },
+             headers: admin.create_new_auth_token,
+             as: :json
+      end.to change(assistant.responses.approved, :count).by(1)
+
+      expect(response).to have_http_status(:success)
+      expect(response.parsed_body['answer']).to eq('Enable it in account settings.')
+      expect(suggestion.reload).to be_approved
+      expect(suggestion.observations.pluck(:conversation_id)).to contain_exactly(conversation.id)
+    end
+
+    it 'lets an agent approve an accessible suggestion' do
+      create(:inbox_member, user: agent, inbox: inbox)
+
+      expect do
+        post "/api/v1/accounts/#{account.id}/captain/faq_suggestions/#{suggestion.id}/approve",
+             headers: agent.create_new_auth_token,
+             as: :json
+      end.to change(assistant.responses.approved, :count).by(1)
+
+      expect(response).to have_http_status(:success)
+      expect(suggestion.reload).to be_approved
+    end
+
+    it 'approves a suggestion written in a language other than the account locale' do
+      suggestion.update!(language: 'pt')
+
+      expect do
+        post "/api/v1/accounts/#{account.id}/captain/faq_suggestions/#{suggestion.id}/approve",
+             headers: admin.create_new_auth_token,
+             as: :json
+      end.to change(assistant.responses.approved, :count).by(1)
+
+      expect(response).to have_http_status(:success)
+      expect(suggestion.reload).to be_approved
+    end
+
+    it 'does not let an agent approve an inaccessible suggestion' do
+      expect do
+        post "/api/v1/accounts/#{account.id}/captain/faq_suggestions/#{suggestion.id}/approve",
+             headers: agent.create_new_auth_token,
+             as: :json
+      end.not_to change(assistant.responses, :count)
+
+      expect(response).to have_http_status(:not_found)
+      expect(suggestion.reload).to be_open
+    end
+  end
+
+  describe 'POST /api/v1/accounts/:account_id/captain/faq_suggestions/:id/dismiss' do
+    it 'lets an administrator dismiss an open suggestion without creating an FAQ' do
+      expect do
+        post "/api/v1/accounts/#{account.id}/captain/faq_suggestions/#{suggestion.id}/dismiss",
+             headers: admin.create_new_auth_token,
+             as: :json
+      end.not_to change(assistant.responses, :count)
+
+      expect(response).to have_http_status(:success)
+      expect(suggestion.reload).to be_dismissed
+    end
+
+    it 'lets an agent dismiss an accessible suggestion' do
+      create(:inbox_member, user: agent, inbox: inbox)
+
+      post "/api/v1/accounts/#{account.id}/captain/faq_suggestions/#{suggestion.id}/dismiss",
+           headers: agent.create_new_auth_token,
+           as: :json
+
+      expect(response).to have_http_status(:success)
+      expect(suggestion.reload).to be_dismissed
+    end
+
+    it 'does not let an agent dismiss an inaccessible suggestion' do
+      post "/api/v1/accounts/#{account.id}/captain/faq_suggestions/#{suggestion.id}/dismiss",
+           headers: agent.create_new_auth_token,
+           as: :json
+
+      expect(response).to have_http_status(:not_found)
+      expect(suggestion.reload).to be_open
+    end
+  end
+end

spec/enterprise/jobs/captain/llm/conversation_faq_job_spec.rb

@@ -0,0 +1,57 @@
+require 'rails_helper'
+
+RSpec.describe Captain::Llm::ConversationFaqJob, type: :job do
+  let(:account) { create(:account) }
+  let(:inbox) { create(:inbox, account: account) }
+  let(:assistant) { create(:captain_assistant, account: account, config: { feature_faq: true }) }
+  let(:conversation) { create(:conversation, account: account, inbox: inbox, first_reply_created_at: Time.zone.now) }
+  let(:faq_service) { instance_double(Captain::Llm::ConversationFaqService, generate_suggestions: []) }
+  let(:lock_manager) { instance_double(Redis::LockManager, lock: true, unlock: true) }
+  let(:lock_key) { "CAPTAIN_CONVERSATION_FAQ_LOCK::#{assistant.id}::en" }
+
+  before do
+    create(:captain_inbox, inbox: inbox, captain_assistant: assistant)
+    conversation.update!(status: :resolved)
+    allow(Redis::LockManager).to receive(:new).and_return(lock_manager)
+    allow(Captain::Llm::ConversationFaqService).to receive(:new).and_return(faq_service)
+  end
+
+  describe '#perform' do
+    it 'uses the assistant captured when the job was enqueued' do
+      replacement_assistant = create(:captain_assistant, account: account, config: { feature_faq: true })
+      inbox.captain_inbox.update!(captain_assistant: replacement_assistant)
+
+      expect(inbox.reload.captain_assistant).to eq(replacement_assistant)
+      expect(Captain::Llm::ConversationFaqService).to receive(:new)
+        .with(assistant, conversation)
+        .and_return(faq_service)
+      expect(faq_service).to receive(:generate_suggestions)
+
+      described_class.perform_now(conversation, assistant)
+    end
+
+    it 'locks FAQ grouping for the assistant and normalized language' do
+      conversation.update!(additional_attributes: { conversation_language: 'pt-BR' })
+      expected_key = "CAPTAIN_CONVERSATION_FAQ_LOCK::#{assistant.id}::pt"
+
+      expect(lock_manager).to receive(:lock).with(expected_key, described_class::LOCK_TIMEOUT).and_return(true)
+      expect(lock_manager).to receive(:unlock).with(expected_key)
+
+      described_class.perform_now(conversation, assistant)
+    end
+
+    context 'when another job holds the grouping lock' do
+      before do
+        allow(lock_manager).to receive(:lock).with(lock_key, described_class::LOCK_TIMEOUT).and_return(false)
+      end
+
+      it 'does not generate suggestions concurrently' do
+        expect(Captain::Llm::ConversationFaqService).not_to receive(:new)
+
+        expect do
+          described_class.new.perform(conversation, assistant)
+        end.to raise_error(MutexApplicationJob::LockAcquisitionError)
+      end
+    end
+  end
+end

spec/enterprise/listeners/captain_listener_spec.rb

@@ -29,7 +29,7 @@ describe CaptainListener do
           .to receive(:new)
           .with(assistant, conversation)
           .and_return(instance_double(Captain::Llm::ContactNotesService, generate_and_update_notes: nil))
-        expect(Captain::Llm::ConversationFaqService).not_to receive(:new)
+        expect(Captain::Llm::ConversationFaqJob).not_to receive(:perform_later)
 
         listener.conversation_resolved(event)
       end
@@ -42,11 +42,8 @@ describe CaptainListener do
         assistant.save!
       end
 
-      it 'generates and deduplicates FAQs' do
-        expect(Captain::Llm::ConversationFaqService)
-          .to receive(:new)
-          .with(assistant, conversation)
-          .and_return(instance_double(Captain::Llm::ConversationFaqService, generate_and_deduplicate: false))
+      it 'enqueues FAQ suggestion generation' do
+        expect(Captain::Llm::ConversationFaqJob).to receive(:perform_later).with(conversation, assistant)
         expect(Captain::Llm::ContactNotesService).not_to receive(:new)
 
         listener.conversation_resolved(event)

spec/enterprise/policies/captain/assistant_policy_spec.rb

@@ -12,7 +12,7 @@ RSpec.describe Captain::AssistantPolicy, type: :policy do
   let(:administrator_context) { { user: administrator, account: account, account_user: account.account_users.first } }
   let(:agent_context) { { user: agent, account: account, account_user: account.account_users.first } }
 
-  permissions :index?, :show?, :playground? do
+  permissions :index?, :show?, :playground?, :metrics?, :faq_stats? do
     context 'when administrator' do
       it { expect(assistant_policy).to permit(administrator_context, assistant) }
     end

spec/enterprise/services/captain/llm/conversation_faq_prompts_service_spec.rb

@@ -0,0 +1,13 @@
+require 'rails_helper'
+
+RSpec.describe Captain::Llm::ConversationFaqPromptsService do
+  describe '.generator' do
+    it 'allows a complete FAQ answer to use several related agent messages' do
+      prompt = described_class.generator
+
+      expect(prompt).to include('message or messages that together provide a complete public answer')
+      expect(prompt).to include('Combine facts only across related agent messages')
+      expect(prompt).not_to include('no single human agent message')
+    end
+  end
+end

spec/enterprise/services/captain/llm/conversation_faq_service_spec.rb

@@ -2,7 +2,7 @@ require 'rails_helper'
 
 RSpec.describe Captain::Llm::ConversationFaqService do
   let(:captain_assistant) { create(:captain_assistant) }
-  let(:conversation) { create(:conversation, first_reply_created_at: Time.zone.now) }
+  let(:conversation) { create(:conversation, account: captain_assistant.account, first_reply_created_at: Time.zone.now) }
   let(:service) { described_class.new(captain_assistant, conversation) }
   let(:embedding_service) { instance_double(Captain::Llm::EmbeddingService) }
   let(:mock_chat) { instance_double(RubyLLM::Chat) }
@@ -15,6 +15,8 @@ RSpec.describe Captain::Llm::ConversationFaqService do
   let(:mock_response) do
     instance_double(RubyLLM::Message, content: { faqs: sample_faqs }.to_json)
   end
+  let(:embedding_one) { [1.0] + Array.new(1535, 0.0) }
+  let(:embedding_two) { [0.0, 1.0] + Array.new(1534, 0.0) }
 
   before do
     create(:installation_config, name: 'CAPTAIN_OPEN_AI_API_KEY', value: 'test-key')
@@ -26,11 +28,10 @@ RSpec.describe Captain::Llm::ConversationFaqService do
     allow(mock_chat).to receive(:ask).and_return(mock_response)
   end
 
-  describe '#generate_and_deduplicate' do
+  describe '#generate_suggestions' do
     context 'when successful' do
       before do
-        allow(embedding_service).to receive(:get_embedding).and_return([0.1, 0.2, 0.3])
-        allow(captain_assistant.responses).to receive(:nearest_neighbors).and_return([])
+        allow(embedding_service).to receive(:get_embedding).and_return(embedding_one, embedding_two)
       end
 
       it 'uses the conversation FAQ generation feature model' do
@@ -38,7 +39,7 @@ RSpec.describe Captain::Llm::ConversationFaqService do
           model: Llm::Models.default_model_for('conversation_faq_generation')
         ).and_return(mock_chat)
 
-        described_class.new(captain_assistant, conversation).generate_and_deduplicate
+        described_class.new(captain_assistant, conversation).generate_suggestions
       end
 
       it 'uses the conversation FAQ default ahead of the legacy global installation model' do
@@ -48,7 +49,7 @@ RSpec.describe Captain::Llm::ConversationFaqService do
           model: Llm::Models.default_model_for('conversation_faq_generation')
         ).and_return(mock_chat)
 
-        described_class.new(captain_assistant, conversation).generate_and_deduplicate
+        described_class.new(captain_assistant, conversation).generate_suggestions
       end
 
       it 'keeps account conversation FAQ model overrides ahead of the feature default' do
@@ -57,7 +58,7 @@ RSpec.describe Captain::Llm::ConversationFaqService do
 
         expect(RubyLLM).to receive(:chat).with(model: 'gpt-4.1-mini').and_return(mock_chat)
 
-        described_class.new(captain_assistant, conversation).generate_and_deduplicate
+        described_class.new(captain_assistant, conversation).generate_suggestions
       end
 
       it 'resolves the feature model from the conversation account' do
@@ -66,7 +67,7 @@ RSpec.describe Captain::Llm::ConversationFaqService do
           account: conversation.account
         ).and_call_original
 
-        described_class.new(captain_assistant, conversation).generate_and_deduplicate
+        described_class.new(captain_assistant, conversation).generate_suggestions
       end
 
       it 'sends only customer and human support agent messages to the LLM' do
@@ -84,7 +85,7 @@ RSpec.describe Captain::Llm::ConversationFaqService do
         create(:message, conversation: conversation, account: conversation.account, inbox: conversation.inbox,
                          message_type: :activity, content: 'Activity message')
 
-        service.generate_and_deduplicate
+        service.generate_suggestions
 
         expected_content = satisfy do |content|
           content.include?('User: Customer question') &&
@@ -104,7 +105,7 @@ RSpec.describe Captain::Llm::ConversationFaqService do
                          sender: nil, message_type: :outgoing, content: 'Human replied from the native app',
                          content_attributes: { external_echo: true })
 
-        service.generate_and_deduplicate
+        service.generate_suggestions
 
         expected_content = satisfy do |content|
           content.include?('User: Customer asks in a native channel') &&
@@ -133,22 +134,27 @@ RSpec.describe Captain::Llm::ConversationFaqService do
           block.call
         end
 
-        service.generate_and_deduplicate
+        service.generate_suggestions
       end
 
-      it 'creates new FAQs for valid conversation content' do
+      it 'creates suggestions instead of trusted FAQs for valid conversation content' do
         expect do
-          service.generate_and_deduplicate
-        end.to change(captain_assistant.responses, :count).by(2)
+          service.generate_suggestions
+        end.to change(captain_assistant.faq_suggestions, :count).by(2)
+        expect(Captain::FaqObservation.count).to eq(2)
+        expect(captain_assistant.responses.count).to be_zero
       end
 
-      it 'saves FAQs with pending status linked to conversation' do
-        service.generate_and_deduplicate
+      it 'saves open suggestions with one attached source each' do
+        service.generate_suggestions
         expect(
-          captain_assistant.responses.pluck(:question, :answer, :status, :documentable_id)
+          captain_assistant.faq_suggestions.pluck(:question, :answer, :status, :source_count, :language)
         ).to contain_exactly(
-          ['What is the purpose?', 'To help users.', 'pending', conversation.id],
-          ['How does it work?', 'Through AI.', 'pending', conversation.id]
+          ['What is the purpose?', 'To help users.', 'open', 1, 'en'],
+          ['How does it work?', 'Through AI.', 'open', 1, 'en']
+        )
+        expect(Captain::FaqObservation.attached.pluck(:conversation_id, :language)).to contain_exactly(
+          [conversation.id, 'en'], [conversation.id, 'en']
         )
       end
     end
@@ -157,37 +163,309 @@ RSpec.describe Captain::Llm::ConversationFaqService do
       let(:conversation) { create(:conversation) }
 
       it 'returns an empty array without generating FAQs' do
-        expect(service.generate_and_deduplicate).to eq([])
+        expect(service.generate_suggestions).to eq([])
       end
 
       it 'does not call the LLM API' do
         expect(RubyLLM).not_to receive(:chat)
-        service.generate_and_deduplicate
+        service.generate_suggestions
       end
     end
 
     context 'when finding duplicates' do
       let(:existing_response) do
-        create(:captain_assistant_response, assistant: captain_assistant, question: 'Similar question', answer: 'Similar answer')
+        create(:captain_assistant_response, assistant: captain_assistant, account: captain_assistant.account,
+                                            question: 'Similar question', answer: 'Similar answer', embedding: embedding_one)
       end
-      let(:similar_neighbor) do
-        OpenStruct.new(
-          id: 1,
-          question: existing_response.question,
-          answer: existing_response.answer,
-          neighbor_distance: 0.1
-        )
+      let(:match_response) { instance_double(RubyLLM::Message, content: { same_faq: true }.to_json) }
+
+      before do
+        existing_response
+        allow(embedding_service).to receive(:get_embedding).and_return(embedding_one)
+        allow(mock_chat).to receive(:ask) do |input|
+          input.start_with?('{') ? match_response : mock_response
+        end
+      end
+
+      it 'discards candidates the LLM confirms are covered by an approved FAQ' do
+        expect do
+          service.generate_suggestions
+        end.to change(Captain::FaqObservation.discarded, :count).by(2)
+        expect(captain_assistant.faq_suggestions.count).to be_zero
+      end
+
+      it 'uses the conversation FAQ matching feature model' do
+        expect(RubyLLM).to receive(:chat).with(
+          model: Llm::Models.default_model_for('conversation_faq_matching')
+        ).at_least(:once).and_return(mock_chat)
+
+        service.generate_suggestions
+      end
+
+      it 'uses the account model override for conversation FAQ matching' do
+        conversation.account.update!(captain_models: { 'conversation_faq_matching' => 'gpt-5-mini' })
+
+        expect(RubyLLM).to receive(:chat).with(model: 'gpt-5-mini').at_least(:once).and_return(mock_chat)
+
+        service.generate_suggestions
+      end
+
+      it 'resolves the matching feature model from the conversation account' do
+        allow(Llm::FeatureRouter).to receive(:resolve).and_call_original
+        expect(Llm::FeatureRouter).to receive(:resolve).with(
+          feature: 'conversation_faq_matching',
+          account: conversation.account
+        ).and_call_original
+
+        service.generate_suggestions
+      end
+    end
+
+    context 'when FAQ comparison cannot be completed' do
+      let(:existing_response) do
+        create(:captain_assistant_response, assistant: captain_assistant, account: captain_assistant.account,
+                                            question: 'Similar question', answer: 'Similar answer', embedding: embedding_one)
+      end
+      let(:comparison_response) { instance_double(RubyLLM::Message, content: comparison_response_content) }
+      let(:comparison_response_content) { 'invalid json' }
+
+      before do
+        existing_response
+        allow(embedding_service).to receive(:get_embedding).and_return(embedding_one)
+        allow(mock_chat).to receive(:ask) do |input|
+          input.start_with?('{') ? comparison_response : mock_response
+        end
+        allow(Rails.logger).to receive(:error)
+      end
+
+      it 'raises when the comparison response is malformed' do
+        expect do
+          service.generate_suggestions
+        end.to raise_error(JSON::ParserError)
+        expect(captain_assistant.faq_suggestions.count).to be_zero
+      end
+
+      context 'when the response omits the comparison result' do
+        let(:comparison_response_content) { {}.to_json }
+
+        it 'raises instead of treating the response as a non-match' do
+          expect do
+            service.generate_suggestions
+          end.to raise_error(KeyError)
+          expect(captain_assistant.faq_suggestions.count).to be_zero
+        end
+      end
+
+      context 'when the comparison result is not a boolean' do
+        let(:comparison_response_content) { { same_faq: 'false' }.to_json }
+
+        it 'raises instead of treating the response as a non-match' do
+          expect do
+            service.generate_suggestions
+          end.to raise_error(TypeError, 'same_faq must be a boolean')
+          expect(captain_assistant.faq_suggestions.count).to be_zero
+        end
+      end
+
+      context 'when the comparison provider fails' do
+        before do
+          allow(mock_chat).to receive(:ask) do |input|
+            raise RubyLLM::Error.new(nil, 'API Error') if input.start_with?('{')
+
+            mock_response
+          end
+        end
+
+        it 'raises instead of treating the failure as a non-match' do
+          expect do
+            service.generate_suggestions
+          end.to raise_error(RubyLLM::Error)
+          expect(captain_assistant.faq_suggestions.count).to be_zero
+        end
+      end
+    end
+
+    context 'when the classifier confirms a non-match' do
+      let(:sample_faqs) { [{ 'question' => 'How can I use the feature?', 'answer' => 'Enable it in settings.' }] }
+      let(:match_response) { instance_double(RubyLLM::Message, content: { same_faq: false }.to_json) }
+
+      before do
+        create(:captain_assistant_response, assistant: captain_assistant, account: captain_assistant.account,
+                                            question: 'How do I enable the feature?', answer: 'Turn it on in settings.',
+                                            embedding: embedding_one)
+        allow(embedding_service).to receive(:get_embedding).and_return(embedding_one)
+        allow(mock_chat).to receive(:ask) do |input|
+          input.start_with?('{') ? match_response : mock_response
+        end
+      end
+
+      it 'creates a new suggestion' do
+        expect do
+          service.generate_suggestions
+        end.to change(captain_assistant.faq_suggestions, :count).by(1)
+      end
+    end
+
+    context 'when an open suggestion is the same FAQ' do
+      let(:sample_faqs) { [{ 'question' => 'How can I use the feature?', 'answer' => 'Enable it in settings.' }] }
+      let(:existing_suggestion) do
+        captain_assistant.faq_suggestions.create!(
+          question: 'How do I enable the feature?',
+          answer: 'Turn it on in settings.',
+          embedding: embedding_one
+        ).tap do |suggestion|
+          suggestion.observations.create!(
+            conversation: create(:conversation, account: captain_assistant.account),
+            generated_question: suggestion.question,
+            generated_answer: suggestion.answer,
+            language: suggestion.language
+          )
+          suggestion.update!(source_count: suggestion.observations.attached.count)
+        end
+      end
+      let(:match_response) { instance_double(RubyLLM::Message, content: { same_faq: true }.to_json) }
+
+      before do
+        existing_suggestion
+        allow(embedding_service).to receive(:get_embedding).and_return(embedding_one)
+        allow(mock_chat).to receive(:ask) do |input|
+          input.start_with?('{') ? match_response : mock_response
+        end
+      end
+
+      it 'attaches the observation and increments the source count' do
+        expect do
+          service.generate_suggestions
+        end.to change(existing_suggestion.observations, :count).by(1)
+        expect(existing_suggestion.reload.source_count).to eq(2)
+        expect(captain_assistant.faq_suggestions.count).to eq(1)
+      end
+
+      it 'does not attach the observation when the suggestion changes after classification' do
+        allow(mock_chat).to receive(:ask) do |input|
+          if input.start_with?('{')
+            existing_suggestion.update!(question: 'Edited after classification started')
+            match_response
+          else
+            mock_response
+          end
+        end
+
+        expect do
+          service.generate_suggestions
+        end.to raise_error(described_class::SuggestionChangedError)
+        expect(existing_suggestion.observations.count).to eq(1)
+        expect(existing_suggestion.reload.source_count).to eq(1)
+      end
+    end
+
+    context 'when a similar open suggestion uses another language' do
+      let(:sample_faqs) { [{ 'question' => 'Como ativo o recurso?', 'answer' => 'Ative nas configuracoes.' }] }
+      let!(:existing_suggestion) do
+        captain_assistant.faq_suggestions.create!(question: 'How do I enable the feature?', answer: 'Turn it on in settings.',
+                                                  embedding: embedding_one, language: 'en', source_count: 1)
       end
 
       before do
-        allow(embedding_service).to receive(:get_embedding).and_return([0.1, 0.2, 0.3])
-        allow(captain_assistant.responses).to receive(:nearest_neighbors).and_return([similar_neighbor])
+        conversation.update!(additional_attributes: { conversation_language: 'pt-BR' })
+        allow(embedding_service).to receive(:get_embedding).and_return(embedding_one)
       end
 
-      it 'filters out duplicate FAQs based on embedding similarity' do
+      it 'creates a separate suggestion in the conversation language' do
         expect do
-          service.generate_and_deduplicate
-        end.not_to change(captain_assistant.responses, :count)
+          service.generate_suggestions
+        end.to change(captain_assistant.faq_suggestions, :count).by(1)
+
+        expect(captain_assistant.faq_suggestions.pluck(:language)).to contain_exactly('en', 'pt')
+        expect(existing_suggestion.reload.source_count).to eq(1)
+      end
+    end
+
+    context 'when an open suggestion uses another locale variant of the same language' do
+      let(:account) { create(:account, locale: 'pt_BR') }
+      let(:captain_assistant) { create(:captain_assistant, account: account) }
+      let(:conversation) { create(:conversation, account: account, first_reply_created_at: Time.zone.now) }
+      let(:sample_faqs) { [{ 'question' => 'Como ativo o recurso?', 'answer' => 'Ative nas configuracoes.' }] }
+      let(:existing_suggestion) do
+        captain_assistant.faq_suggestions.create!(
+          question: 'Como habilito o recurso?',
+          answer: 'Ative nas configuracoes.',
+          embedding: embedding_one,
+          language: 'pt',
+          source_count: 1
+        )
+      end
+      let(:match_response) { instance_double(RubyLLM::Message, content: { same_faq: true }.to_json) }
+
+      before do
+        existing_suggestion
+        allow(embedding_service).to receive(:get_embedding).and_return(embedding_one)
+        allow(mock_chat).to receive(:ask) do |input|
+          input.start_with?('{') ? match_response : mock_response
+        end
+      end
+
+      it 'attaches the observation to the existing base-language suggestion' do
+        expect do
+          service.generate_suggestions
+        end.to change(existing_suggestion.observations, :count).by(1)
+
+        expect(existing_suggestion.reload.source_count).to eq(2)
+        expect(captain_assistant.faq_suggestions.count).to eq(1)
+        expect(existing_suggestion.observations.last.language).to eq('pt')
+      end
+    end
+
+    context 'when a similar approved FAQ uses another language' do
+      let(:sample_faqs) { [{ 'question' => 'Como ativo o recurso?', 'answer' => 'Ative nas configuracoes.' }] }
+      let(:match_response) { instance_double(RubyLLM::Message, content: { same_faq: true }.to_json) }
+
+      before do
+        create(:captain_assistant_response, assistant: captain_assistant, account: captain_assistant.account,
+                                            question: 'How do I enable the feature?', answer: 'Turn it on in settings.',
+                                            embedding: embedding_one)
+        conversation.update!(additional_attributes: { conversation_language: 'pt-BR' })
+        allow(embedding_service).to receive(:get_embedding).and_return(embedding_one)
+        allow(mock_chat).to receive(:ask) do |input|
+          input.start_with?('{') ? match_response : mock_response
+        end
+      end
+
+      it 'deduplicates against the approved FAQ' do
+        expect do
+          service.generate_suggestions
+        end.to change(Captain::FaqObservation.discarded, :count).by(1)
+        expect(captain_assistant.faq_suggestions.count).to be_zero
+      end
+    end
+
+    context 'when conversation and account locales share a base language' do
+      let(:account) { create(:account, locale: 'pt_BR') }
+      let(:captain_assistant) { create(:captain_assistant, account: account) }
+      let(:conversation) do
+        create(:conversation, account: account, first_reply_created_at: Time.zone.now,
+                              additional_attributes: { conversation_language: 'pt' })
+      end
+      let!(:existing_response) do
+        create(:captain_assistant_response, assistant: captain_assistant, account: account,
+                                            question: 'Como ativo o recurso?', answer: 'Ative nas configuracoes.',
+                                            embedding: embedding_one)
+      end
+      let(:match_response) { instance_double(RubyLLM::Message, content: { same_faq: true }.to_json) }
+
+      before do
+        existing_response
+        allow(embedding_service).to receive(:get_embedding).and_return(embedding_one)
+        allow(mock_chat).to receive(:ask) do |input|
+          input.start_with?('{') ? match_response : mock_response
+        end
+      end
+
+      it 'deduplicates against approved FAQs in the same base language' do
+        expect do
+          service.generate_suggestions
+        end.to change(Captain::FaqObservation.discarded, :count).by(2)
+        expect(captain_assistant.faq_suggestions.count).to be_zero
       end
     end
 
@@ -199,7 +477,7 @@ RSpec.describe Captain::Llm::ConversationFaqService do
 
       it 'returns empty array and logs the error' do
         expect(Rails.logger).to receive(:error).with('LLM API Error: API Error')
-        expect(service.generate_and_deduplicate).to eq([])
+        expect(service.generate_suggestions).to eq([])
       end
     end
 
@@ -214,7 +492,7 @@ RSpec.describe Captain::Llm::ConversationFaqService do
 
       it 'handles JSON parsing errors gracefully' do
         expect(Rails.logger).to receive(:error).with(/Error in parsing GPT processed response:/)
-        expect(service.generate_and_deduplicate).to eq([])
+        expect(service.generate_suggestions).to eq([])
       end
     end
 
@@ -228,7 +506,7 @@ RSpec.describe Captain::Llm::ConversationFaqService do
       end
 
       it 'returns empty array' do
-        expect(service.generate_and_deduplicate).to eq([])
+        expect(service.generate_suggestions).to eq([])
       end
     end
   end
@@ -236,22 +514,44 @@ RSpec.describe Captain::Llm::ConversationFaqService do
   describe 'language handling' do
     context 'when conversation has different language' do
       let(:account) { create(:account, locale: 'fr') }
+      let(:captain_assistant) { create(:captain_assistant, account: account) }
       let(:conversation) do
         create(:conversation, account: account, first_reply_created_at: Time.zone.now)
       end
 
       before do
-        allow(embedding_service).to receive(:get_embedding).and_return([0.1, 0.2, 0.3])
-        allow(captain_assistant.responses).to receive(:nearest_neighbors).and_return([])
+        allow(embedding_service).to receive(:get_embedding).and_return(embedding_one, embedding_two)
       end
 
       it 'uses account language for system prompt' do
-        expect(Captain::Llm::SystemPromptsService).to receive(:conversation_faq_generator)
+        expect(Captain::Llm::ConversationFaqPromptsService).to receive(:generator)
           .with('french')
           .at_least(:once)
           .and_call_original
 
-        service.generate_and_deduplicate
+        service.generate_suggestions
+      end
+    end
+
+    context 'when conversation language differs from account language' do
+      let(:account) { create(:account, locale: 'en') }
+      let(:captain_assistant) { create(:captain_assistant, account: account) }
+      let(:conversation) do
+        create(:conversation, account: account, first_reply_created_at: Time.zone.now,
+                              additional_attributes: { conversation_language: 'pt-BR' })
+      end
+
+      before do
+        allow(embedding_service).to receive(:get_embedding).and_return(embedding_one, embedding_two)
+      end
+
+      it 'uses the conversation language for the system prompt' do
+        expect(Captain::Llm::ConversationFaqPromptsService).to receive(:generator)
+          .with('portuguese')
+          .at_least(:once)
+          .and_call_original
+
+        service.generate_suggestions
       end
     end
   end

spec/lib/llm/models_spec.rb

@@ -26,9 +26,10 @@ RSpec.describe Llm::Models do
       end
     end
 
-    it 'routes document and conversation FAQ generation independently' do
+    it 'routes each FAQ operation independently' do
       expect(described_class.default_model_for('document_faq_generation')).to eq('gpt-4.1-mini')
       expect(described_class.default_model_for('conversation_faq_generation')).to eq('gpt-5.2')
+      expect(described_class.default_model_for('conversation_faq_matching')).to eq('gpt-4.1-mini')
     end
   end