Merge branch 'codex/cw-7431-document-usage' into codex/cw-7498-document-conversation-usage

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/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-next/captain/assistant/DocumentCard.vue

@@ -70,6 +70,10 @@ const props = defineProps({
     type: Number,
     default: 0,
   },
+  usedInConversationsCount: {
+    type: Number,
+    default: 0,
+  },
   isSelected: {
     type: Boolean,
     default: false,
@@ -150,6 +154,11 @@ const createdAtLabel = computed(() => dynamicTime(props.createdAt));
 const responsesCountLabel = computed(() =>
   t('CAPTAIN.DOCUMENTS.FAQ_COUNT', { n: props.responsesCount })
 );
+const usedInConversationsCountLabel = computed(() =>
+  t('CAPTAIN.DOCUMENTS.USED_IN_CONVERSATIONS', {
+    n: props.usedInConversationsCount,
+  })
+);
 
 const displayLink = computed(() =>
   isPdf.value
@@ -216,7 +225,7 @@ const handleRetry = () => {
         </div>
       </div>
     </div>
-    <div class="flex gap-4 justify-between items-center w-full">
+    <div class="flex flex-wrap gap-4 justify-between items-center w-full">
       <span
         class="flex gap-1 items-center text-sm truncate shrink-0 text-n-slate-11"
       >
@@ -246,6 +255,9 @@ const handleRetry = () => {
       <span class="text-sm shrink-0 text-n-slate-11">
         {{ responsesCountLabel }}
       </span>
+      <span class="text-sm shrink-0 text-n-slate-11">
+        {{ usedInConversationsCountLabel }}
+      </span>
       <DocumentSyncStatus
         v-if="showSyncStatus"
         :status="syncStatus"

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/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",

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/i18n/locale/en/integrations.json

@@ -819,6 +819,7 @@
       "HEADER": "Documents",
       "ADD_NEW": "Create a new document",
       "FAQ_COUNT": "{n} FAQ | {n} FAQs",
+      "USED_IN_CONVERSATIONS": "Used in {n} conversation | Used in {n} conversations",
       "SELECTED": "{count} selected",
       "SELECT_ALL": "Select all ({count})",
       "UNSELECT_ALL": "Unselect all ({count})",

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/captain/documents/Index.vue

@@ -417,6 +417,7 @@ onUnmounted(() => {
           :sync-in-progress="doc.sync_in_progress"
           :sync-stale-after-hours="syncIntervalHours"
           :responses-count="doc.responses_count"
+          :used-in-conversations-count="doc.used_in_conversations_count"
           :is-selected="canManageDocuments && bulkSelectedIds.has(doc.id)"
           :selectable="canManageDocuments"
           :show-selection-control="shouldShowSelectionControl(doc.id)"

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'"

config/app.yml

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

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

db/migrate/20260721100000_create_captain_message_sources.rb

@@ -0,0 +1,17 @@
+class CreateCaptainMessageSources < ActiveRecord::Migration[7.1]
+  def change
+    create_table :captain_message_sources do |t|
+      t.references :account, null: false, index: true
+      t.references :assistant, null: false, index: true
+      t.references :conversation, null: false, index: true
+      t.references :message, null: false, index: true
+      t.references :document, null: false, index: true
+      t.bigint :assistant_response_id, null: false
+
+      t.timestamps
+    end
+
+    add_index :captain_message_sources, [:message_id, :assistant_response_id],
+              unique: true, name: 'idx_captain_message_sources_on_message_and_response'
+  end
+end

db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[7.1].define(version: 2026_07_13_184351) do
+ActiveRecord::Schema[7.1].define(version: 2026_07_21_100000) do
   # These extensions should be enabled to support this database
   enable_extension "pg_stat_statements"
   enable_extension "pg_trgm"
@@ -477,6 +477,23 @@ ActiveRecord::Schema[7.1].define(version: 2026_07_13_184351) do
     t.index ["user_id"], name: "index_captain_message_reports_on_user_id"
   end
 
+  create_table "captain_message_sources", force: :cascade do |t|
+    t.bigint "account_id", null: false
+    t.bigint "assistant_id", null: false
+    t.bigint "conversation_id", null: false
+    t.bigint "message_id", null: false
+    t.bigint "document_id", null: false
+    t.bigint "assistant_response_id", null: false
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+    t.index ["account_id"], name: "index_captain_message_sources_on_account_id"
+    t.index ["assistant_id"], name: "index_captain_message_sources_on_assistant_id"
+    t.index ["conversation_id"], name: "index_captain_message_sources_on_conversation_id"
+    t.index ["document_id"], name: "index_captain_message_sources_on_document_id"
+    t.index ["message_id", "assistant_response_id"], name: "idx_captain_message_sources_on_message_and_response", unique: true
+    t.index ["message_id"], name: "index_captain_message_sources_on_message_id"
+  end
+
   create_table "captain_scenarios", force: :cascade do |t|
     t.string "title"
     t.text "description"

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/documents_controller.rb

@@ -11,7 +11,7 @@ class Api::V1::Accounts::Captain::DocumentsController < Api::V1::Accounts::BaseC
     @documents = filtered_documents
     @documents_count = @documents.count
     @sync_interval_hours = current_sync_interval&.in_hours&.to_i
-    @documents = with_responses_count(@documents).page(@current_page).per(RESULTS_PER_PAGE)
+    @documents = with_document_usage(@documents).page(@current_page).per(RESULTS_PER_PAGE)
   end
 
   def show; end
@@ -61,14 +61,23 @@ class Api::V1::Accounts::Captain::DocumentsController < Api::V1::Accounts::BaseC
     apply_sort(documents, permitted_params[:sort])
   end
 
-  def with_responses_count(scope)
-    scope.left_joins(:responses)
-         .select('captain_documents.*, COUNT(captain_assistant_responses.id) AS responses_count')
-         .group('captain_documents.id')
+  def with_document_usage(scope)
+    response_counts = Captain::AssistantResponse.where(documentable_type: 'Captain::Document')
+                                                .group(:documentable_id)
+                                                .select('documentable_id AS document_id, COUNT(*) AS responses_count')
+    source_counts = Captain::MessageSource.group(:document_id).select(
+      'document_id, COUNT(DISTINCT message_id) AS used_in_answers_count, COUNT(DISTINCT conversation_id) AS used_in_conversations_count'
+    )
+
+    scope.joins("LEFT JOIN (#{response_counts.to_sql}) response_counts ON response_counts.document_id = captain_documents.id")
+         .joins("LEFT JOIN (#{source_counts.to_sql}) source_counts ON source_counts.document_id = captain_documents.id")
+         .select('captain_documents.*, COALESCE(response_counts.responses_count, 0) AS responses_count, ' \
+                 'COALESCE(source_counts.used_in_answers_count, 0) AS used_in_answers_count, ' \
+                 'COALESCE(source_counts.used_in_conversations_count, 0) AS used_in_conversations_count')
   end
 
   def set_document
-    @document = @documents.find(permitted_params[:id])
+    @document = with_document_usage(@documents).find(permitted_params[:id])
   end
 
   def set_assistant

enterprise/app/jobs/captain/conversation/response_builder_job.rb

@@ -68,7 +68,7 @@ class Captain::Conversation::ResponseBuilderJob < ApplicationJob
         # left is the customer-facing follow-up message.
         process_v2_handoff
       end
-      capture_assistant_session(result_message: @handoff_message, credits_consumed: 0.0)
+      capture_assistant_session(result_message: @handoff_message, credits_consumed: 0.0, capture_message_sources: false)
     elsif v1_handoff_requested?
       # V1 only signals via the response string — no state has been touched yet. If
       # the conversation isn't pending anymore, a human took over mid-run; bail out
@@ -83,7 +83,7 @@ class Captain::Conversation::ResponseBuilderJob < ApplicationJob
         Rails.logger.info("[CAPTAIN][ResponseBuilderJob] Incrementing response usage for #{account.id}")
         account.increment_response_usage
       end
-      capture_assistant_session(result_message: message, credits_consumed: 1.0)
+      capture_assistant_session(result_message: message, credits_consumed: 1.0, capture_message_sources: captain_v2_enabled?)
     end
   end
 
@@ -142,9 +142,10 @@ class Captain::Conversation::ResponseBuilderJob < ApplicationJob
   # Capture runs outside the delivery transaction and never raises (the service
   # swallows its own failures): a session-logging bug must never roll back the
   # customer reply or trigger the top-level handle_error handoff on top of it.
-  def capture_assistant_session(result_message:, credits_consumed:)
+  def capture_assistant_session(result_message:, credits_consumed:, capture_message_sources:)
     Captain::Assistant::SessionCaptureService.new(assistant: @assistant, conversation: @conversation, run_result: @run_result,
-                                                  result_message: result_message, credits_consumed: credits_consumed).capture
+                                                  result_message: result_message, credits_consumed: credits_consumed,
+                                                  capture_message_sources: capture_message_sources).capture
   end
 
   def handle_error(error)

enterprise/app/models/captain/document.rb

@@ -34,6 +34,7 @@ class Captain::Document < ApplicationRecord
 
   belongs_to :assistant, class_name: 'Captain::Assistant'
   has_many :responses, class_name: 'Captain::AssistantResponse', dependent: :destroy, as: :documentable
+  has_many :message_sources, class_name: 'Captain::MessageSource', dependent: :destroy_async
   belongs_to :account
   has_one_attached :pdf_file
   store_accessor :metadata, :content_fingerprint, :last_sync_error_code, :sync_step, :openai_file_id

enterprise/app/models/captain/message_source.rb

@@ -0,0 +1,33 @@
+# == Schema Information
+#
+# Table name: captain_message_sources
+#
+#  id                    :bigint           not null, primary key
+#  created_at            :datetime         not null
+#  updated_at            :datetime         not null
+#  account_id            :bigint           not null
+#  assistant_id          :bigint           not null
+#  assistant_response_id :bigint           not null
+#  conversation_id       :bigint           not null
+#  document_id           :bigint           not null
+#  message_id            :bigint           not null
+#
+# Indexes
+#
+#  idx_captain_message_sources_on_message_and_response  (message_id,assistant_response_id) UNIQUE
+#  index_captain_message_sources_on_account_id          (account_id)
+#  index_captain_message_sources_on_assistant_id        (assistant_id)
+#  index_captain_message_sources_on_conversation_id     (conversation_id)
+#  index_captain_message_sources_on_document_id         (document_id)
+#  index_captain_message_sources_on_message_id          (message_id)
+#
+class Captain::MessageSource < ApplicationRecord
+  self.table_name = 'captain_message_sources'
+
+  belongs_to :account
+  belongs_to :assistant, class_name: 'Captain::Assistant'
+  belongs_to :conversation, class_name: '::Conversation'
+  belongs_to :message
+  belongs_to :document, class_name: 'Captain::Document'
+  belongs_to :assistant_response, class_name: 'Captain::AssistantResponse', optional: true
+end

enterprise/app/models/enterprise/concerns/account.rb

@@ -16,6 +16,7 @@ module Enterprise::Concerns::Account
     has_many :captain_documents, dependent: :destroy_async, class_name: 'Captain::Document'
     has_many :captain_custom_tools, dependent: :destroy_async, class_name: 'Captain::CustomTool'
     has_many :captain_agent_sessions, dependent: :destroy_async, class_name: 'Captain::AgentSession'
+    has_many :captain_message_sources, dependent: :destroy_async, class_name: 'Captain::MessageSource'
 
     has_many :copilot_threads, dependent: :destroy_async
     has_many :companies, dependent: :destroy_async

enterprise/app/models/enterprise/concerns/message.rb

@@ -4,5 +4,6 @@ module Enterprise::Concerns::Message
   included do
     has_one :call, dependent: :nullify
     has_many :message_reports, class_name: 'Captain::MessageReport', dependent: :destroy_async
+    has_many :captain_message_sources, class_name: 'Captain::MessageSource', dependent: :destroy_async
   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
 

enterprise/app/services/captain/assistant/session_capture_service.rb

@@ -1,12 +1,13 @@
 class Captain::Assistant::SessionCaptureService
   SCENARIO_AGENT_REGEX = /\A#{Captain::Scenario::HANDOFF_KEY_PREFIX}_(\d+)_/
 
-  def initialize(assistant:, conversation:, run_result:, result_message:, credits_consumed:)
+  def initialize(assistant:, conversation:, run_result:, result_message:, **options)
     @assistant = assistant
     @conversation = conversation
     @run_result = run_result
     @result_message = result_message
-    @credits_consumed = credits_consumed
+    @credits_consumed = options.fetch(:credits_consumed)
+    @capture_message_sources = options.fetch(:capture_message_sources, false)
   end
 
   def capture
@@ -23,7 +24,7 @@ class Captain::Assistant::SessionCaptureService
   def capture!
     model = @assistant.agent_model
 
-    Captain::AgentSession.create!(
+    session = Captain::AgentSession.create!(
       assistant: @assistant,
       session_type: :assistant,
       subject: @conversation,
@@ -35,6 +36,8 @@ class Captain::Assistant::SessionCaptureService
       scenario_ids: scenario_ids,
       run_context: current_turn_history
     )
+    capture_message_sources(metadata) if @capture_message_sources
+    session
   end
 
   private
@@ -70,6 +73,42 @@ class Captain::Assistant::SessionCaptureService
     ids & @assistant.scenarios.where(id: ids).pluck(:id)
   end
 
+  def capture_message_sources(metadata)
+    sources = Array(metadata[:message_sources])
+    return if sources.empty?
+
+    document_ids = @assistant.documents.where(id: sources.pluck(:document_id)).pluck(:id)
+    return if document_ids.empty?
+
+    insert_message_sources(message_source_rows(sources, document_ids))
+  end
+
+  def message_source_rows(sources, document_ids)
+    timestamp = Time.current
+    sources.filter_map do |source|
+      next unless document_ids.include?(source[:document_id])
+
+      {
+        account_id: @assistant.account_id,
+        assistant_id: @assistant.id,
+        conversation_id: @conversation.id,
+        message_id: @result_message.id,
+        document_id: source[:document_id],
+        assistant_response_id: source[:assistant_response_id],
+        created_at: timestamp,
+        updated_at: timestamp
+      }
+    end
+  end
+
+  def insert_message_sources(rows)
+    return if rows.empty?
+
+    # rubocop:disable Rails/SkipsModelValidations
+    Captain::MessageSource.insert_all(rows, unique_by: :idx_captain_message_sources_on_message_and_response)
+    # rubocop:enable Rails/SkipsModelValidations
+  end
+
   # Trim to the current turn: the last user message and everything after it
   # (assistant replies, tool calls/results, handoff hops).
   def current_turn_history

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

@@ -11,6 +11,10 @@ json.file_size resource.file_size
 json.pdf_document resource.pdf_document?
 responses_count = resource.respond_to?(:responses_count) ? resource.responses_count : resource.responses.count
 json.responses_count responses_count.to_i
+used_in_answers_count = resource.respond_to?(:used_in_answers_count) ? resource.used_in_answers_count : resource.message_sources.distinct.count(:message_id)
+json.used_in_answers_count used_in_answers_count.to_i
+used_in_conversations_count = resource.respond_to?(:used_in_conversations_count) ? resource.used_in_conversations_count : resource.message_sources.distinct.count(:conversation_id)
+json.used_in_conversations_count used_in_conversations_count.to_i
 json.id resource.id
 json.name resource.name
 json.status resource.status

enterprise/lib/captain/tools/faq_lookup_tool.rb

@@ -26,8 +26,17 @@ class Captain::Tools::FaqLookupTool < Captain::Tools::BasePublicTool
     metadata = tool_context.state[:cw_metadata] ||= {}
     metadata[:faq_ids] = Array(metadata[:faq_ids]) | responses.map(&:id)
 
-    document_ids = responses.filter_map { |response| response.documentable_id if response.documentable_type == 'Captain::Document' }
+    document_ids = document_responses(responses).map(&:documentable_id)
     metadata[:document_ids] = Array(metadata[:document_ids]) | document_ids
+    metadata[:message_sources] = Array(metadata[:message_sources]) | message_sources(document_responses(responses))
+  end
+
+  def document_responses(responses)
+    responses.select { |response| response.documentable_type == 'Captain::Document' }
+  end
+
+  def message_sources(responses)
+    responses.map { |response| { assistant_response_id: response.id, document_id: response.documentable_id } }
   end
 
   def format_responses(responses)

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/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/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