rails_error_dashboard 0.6.3 → 0.7.0

data/app/views/rails_error_dashboard/errors/_sidebar_metadata.html.erb

@@ -35,37 +35,49 @@
           <div class="mb-3">
             <small class="metadata-label d-block mb-1">Severity Level</small>
             <% severity = error.severity %>
-            <% if severity == :critical %>
-              <span class="badge bg-danger fs-6">CRITICAL</span>
-            <% elsif severity == :high %>
-              <span class="badge bg-warning text-dark fs-6">HIGH</span>
-            <% elsif severity == :medium %>
-              <span class="badge bg-info text-dark fs-6">MEDIUM</span>
-            <% else %>
-              <span class="badge bg-secondary fs-6">LOW</span>
+            <%= link_to errors_path(severity: severity, unresolved: '0'), class: "text-decoration-none", title: "View all #{severity} errors" do %>
+              <% if severity == :critical %>
+                <span class="badge bg-danger fs-6">CRITICAL</span>
+              <% elsif severity == :high %>
+                <span class="badge bg-warning text-dark fs-6">HIGH</span>
+              <% elsif severity == :medium %>
+                <span class="badge bg-info text-dark fs-6">MEDIUM</span>
+              <% else %>
+                <span class="badge bg-secondary fs-6">LOW</span>
+              <% end %>
             <% end %>
           </div>
 
           <div class="mb-3">
             <small class="metadata-label d-block mb-1">Platform</small>
-            <% if error.platform == 'iOS' %>
-              <span class="badge badge-ios"><i class="bi bi-apple"></i> iOS</span>
-            <% elsif error.platform == 'Android' %>
-              <span class="badge badge-android"><i class="bi bi-android2"></i> Android</span>
-            <% elsif error.platform == 'Web' %>
-              <span class="badge badge-web"><i class="bi bi-globe"></i> Web</span>
+            <% if error.platform.present? %>
+              <%= link_to errors_path(platform: error.platform, unresolved: '0'), class: "text-decoration-none", title: "View all #{error.platform} errors" do %>
+                <% if error.platform == 'iOS' %>
+                  <span class="badge badge-ios"><i class="bi bi-apple"></i> iOS</span>
+                <% elsif error.platform == 'Android' %>
+                  <span class="badge badge-android"><i class="bi bi-android2"></i> Android</span>
+                <% elsif error.platform == 'Web' %>
+                  <span class="badge badge-web"><i class="bi bi-globe"></i> Web</span>
+                <% else %>
+                  <span class="badge badge-api"><i class="bi bi-server"></i> <%= error.platform %></span>
+                <% end %>
+              <% end %>
             <% else %>
-              <span class="badge badge-api"><i class="bi bi-server"></i> <%= error.platform || 'API' %></span>
+              <span class="badge badge-api"><i class="bi bi-server"></i> API</span>
             <% end %>
           </div>
 
           <div class="mb-3">
             <small class="metadata-label d-block mb-1">User</small>
             <% if error.respond_to?(:user) && error.user %>
-              <strong><%= error.user.email %></strong><br>
-              <small class="text-muted">ID: <%= error.user_id %></small>
+              <%= link_to errors_path(user_id: error.user_id, unresolved: '0'), class: "text-decoration-none", title: "View all errors for this user" do %>
+                <strong><%= error.user.email %></strong><br>
+                <small class="text-muted">ID: <%= error.user_id %></small>
+              <% end %>
             <% elsif error.user_id %>
-              <span class="text-muted">User ID: <%= error.user_id %></span>
+              <%= link_to errors_path(user_id: error.user_id, unresolved: '0'), class: "text-decoration-none text-muted", title: "View all errors for this user" do %>
+                User ID: <%= error.user_id %>
+              <% end %>
             <% else %>
               <span class="text-muted">Guest / Unauthenticated</span>
             <% end %>
@@ -249,7 +261,9 @@
               <% if error.app_version.present? %>
                 <div class="mb-1">
                   <small class="text-muted">App Version:</small>
-                  <code class="ms-1"><%= error.app_version %></code>
+                  <%= link_to errors_path(app_version: error.app_version, unresolved: '0'), class: "ms-1 text-decoration-none", title: "View all errors in #{error.app_version}" do %>
+                    <code><%= error.app_version %></code>
+                  <% end %>
                 </div>
               <% end %>
 

data/app/views/rails_error_dashboard/errors/_timeline.html.erb

@@ -78,8 +78,7 @@
                         <% if error.resolution_comment.present? %>
                           data-bs-toggle="tooltip"
                           data-bs-placement="top"
-                          data-bs-html="true"
-                          title="<strong>Resolution Notes:</strong><br><%= error.resolution_comment.truncate(150).gsub('"', '&quot;') %>"
+                          title="Resolution Notes: <%= error.resolution_comment.truncate(150) %>"
                         <% end %>>
                     <i class="bi bi-check-circle"></i> Resolved
                   </span>

data/app/views/rails_error_dashboard/errors/analytics.html.erb

@@ -339,7 +339,11 @@
             <tbody>
               <% @recurring_data[:high_frequency_errors].first(10).each do |error| %>
                 <tr>
-                  <td><code class="small"><%= error[:error_type] %></code></td>
+                  <td>
+                    <%= link_to errors_path(error_type: error[:error_type], unresolved: '0'), class: "text-decoration-none" do %>
+                      <code class="small"><%= error[:error_type] %></code>
+                    <% end %>
+                  </td>
                   <td><span class="badge bg-danger"><%= error[:total_occurrences] %></span></td>
                   <td><%= error[:duration_days] %> days</td>
                   <td><small class="text-muted"><%= local_time(error[:first_seen], format: :date_only) %></small></td>

data/app/views/rails_error_dashboard/errors/correlation.html.erb

@@ -90,7 +90,11 @@
             <tbody>
               <% @problematic_releases.each do |release| %>
                 <tr>
-                  <td><code><%= release[:version] %></code></td>
+                  <td>
+                    <%= link_to errors_path(app_version: release[:version], unresolved: '0'), class: "text-decoration-none" do %>
+                      <code><%= release[:version] %></code>
+                    <% end %>
+                  </td>
                   <td><strong class="text-danger"><%= release[:error_count] %></strong></td>
                   <td>
                     <span class="badge bg-danger">
@@ -105,7 +109,7 @@
                     <% end %>
                   </td>
                   <td>
-                    <%= link_to "View", errors_path(search: release[:version], unresolved: '0'), class: "btn btn-sm btn-outline-primary" %>
+                    <%= link_to "View", errors_path(app_version: release[:version], unresolved: '0'), class: "btn btn-sm btn-outline-primary" %>
                   </td>
                 </tr>
               <% end %>
@@ -141,7 +145,11 @@
                 <tbody>
                   <% @errors_by_version.sort_by { |_, v| -v[:count] }.first(10).each do |version, data| %>
                     <tr>
-                      <td><code><%= version %></code></td>
+                      <td>
+                        <%= link_to errors_path(app_version: version, unresolved: '0'), class: "text-decoration-none" do %>
+                          <code><%= version %></code>
+                        <% end %>
+                      </td>
                       <td><%= data[:count] %></td>
                       <td><%= data[:error_types] %></td>
                       <td>
@@ -185,7 +193,11 @@
                 <tbody>
                   <% @errors_by_git_sha.sort_by { |_, v| -v[:count] }.first(10).each do |sha, data| %>
                     <tr>
-                      <td><code class="small"><%= sha[0..7] %></code></td>
+                      <td>
+                        <%= link_to errors_path(git_sha: sha, unresolved: '0'), class: "text-decoration-none" do %>
+                          <code class="small"><%= sha[0..7] %></code>
+                        <% end %>
+                      </td>
                       <td><%= data[:count] %></td>
                       <td><%= data[:error_types] %></td>
                       <td>

data/app/views/rails_error_dashboard/errors/database_health_summary.html.erb

@@ -150,7 +150,7 @@
                         <%= number_with_delimiter(table[:dead_tuples]) %>
                       <% end %>
                     </td>
-                    <td><%= table[:last_autovacuum] ? local_time_ago(Time.parse(table[:last_autovacuum])) : "Never" %></td>
+                    <td><%= table[:last_autovacuum] ? local_time_ago(parse_pg_timestamp(table[:last_autovacuum])) : "Never" %></td>
                   </tr>
                 <% end %>
               </tbody>
@@ -203,7 +203,7 @@
                           <%= number_with_delimiter(table[:dead_tuples]) %>
                         <% end %>
                       </td>
-                      <td><%= table[:last_autovacuum] ? local_time_ago(Time.parse(table[:last_autovacuum])) : "Never" %></td>
+                      <td><%= table[:last_autovacuum] ? local_time_ago(parse_pg_timestamp(table[:last_autovacuum])) : "Never" %></td>
                     </tr>
                   <% end %>
                 </tbody>
@@ -338,7 +338,11 @@
               <% @entries.each do |entry| %>
                 <tr>
                   <td><%= link_to "##{entry[:error_id]}", error_path(entry[:error_id]), class: "text-decoration-none" %></td>
-                  <td><code><%= truncate(entry[:error_type].to_s, length: 40) %></code></td>
+                  <td>
+                    <%= link_to errors_path(error_type: entry[:error_type], unresolved: '0'), class: "text-decoration-none" do %>
+                      <code><%= truncate(entry[:error_type].to_s, length: 40) %></code>
+                    <% end %>
+                  </td>
                   <td>
                     <% util = entry[:utilization] %>
                     <% util_badge = util >= 80 ? "danger" : (util >= 60 ? "warning" : "success") %>

data/app/views/rails_error_dashboard/errors/diagnostic_dumps.html.erb

@@ -139,7 +139,7 @@
                 <small class="text-muted d-block">GC</small>
                 <small>
                   <% gc_health = health["gc"] || {} %>
-                  Live: <%= gc_health["heap_live_slots"]&.to_s(:delimited) rescue gc_health["heap_live_slots"] || "?" %> /
+                  Live: <%= gc_health["heap_live_slots"] ? number_with_delimiter(gc_health["heap_live_slots"]) : "?" %> /
                   Major GC: <%= gc_health["major_gc_count"] || "?" %>
                 </small>
               </div>

data/app/views/rails_error_dashboard/errors/index.html.erb

@@ -172,7 +172,13 @@
     active_filters << { label: "Timeframe: #{params[:timeframe].humanize}", param: :timeframe } if params[:timeframe].present?
     active_filters << { label: "Frequency: #{params[:frequency].humanize}", param: :frequency } if params[:frequency].present?
     active_filters << { label: "Status: #{params[:status].humanize}", param: :status } if params[:status].present?
-    active_filters << { label: "Priority: P#{params[:priority_level]}", param: :priority_level } if params[:priority_level].present?
+    if params[:priority_level].present?
+      # priority_level is the integer key (3=Critical/P0, 0=Low/P3); look up the short_label
+      # rather than interpolating the raw integer, which inverts the P-number.
+      priority_data = RailsErrorDashboard::ErrorLog::PRIORITY_LEVELS[params[:priority_level].to_i]
+      priority_short = priority_data ? priority_data[:short_label] : "P?"
+      active_filters << { label: "Priority: #{priority_short}", param: :priority_level }
+    end
     if params[:assigned_to] == '__unassigned__'
       active_filters << { label: "Unassigned", param: :assigned_to }
     elsif params[:assigned_to] == '__assigned__'

data/app/views/rails_error_dashboard/errors/overview.html.erb

@@ -92,7 +92,7 @@
   <div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--space-4); margin-bottom: var(--space-6);">
     <!-- Affected Users -->
     <div class="card stat-card" style="padding: var(--space-5) var(--space-6);">
-      <div class="stat-label" style="margin-bottom: 4px;">Affected Users</div>
+      <div class="stat-label" style="margin-bottom: 4px;">Affected Users (Today)</div>
       <div style="display: flex; align-items: baseline; gap: 8px;">
         <span class="stat-value"><%= @stats[:affected_users_today] %></span>
         <% if @stats[:affected_users_change] != 0 %>
@@ -149,7 +149,7 @@
               <div style="font-size: 12px; color: var(--text-tertiary); white-space: nowrap; overflow: hidden; text-overflow: ellipsis;"><%= error[:message]&.truncate(80) %></div>
             </div>
             <div style="text-align: right; flex-shrink: 0;">
-              <div style="font-size: 14px; font-weight: 600; color: var(--text-primary); font-variant-numeric: tabular-nums;"><%= error[:occurrence_count]&.to_s(:delimited) rescue error[:occurrence_count] %></div>
+              <div style="font-size: 14px; font-weight: 600; color: var(--text-primary); font-variant-numeric: tabular-nums;"><%= number_with_delimiter(error[:occurrence_count]) %></div>
               <div style="font-size: 11px; color: var(--text-tertiary);"><%= error[:affected_users] %> users</div>
             </div>
           <% end %>

data/app/views/rails_error_dashboard/errors/platform_comparison.html.erb

@@ -227,7 +227,9 @@
                 <% @cross_platform_errors.first(10).each do |error| %>
                   <tr>
                     <td>
-                      <code class="small"><%= error[:error_type] %></code>
+                      <%= link_to errors_path(error_type: error[:error_type], unresolved: '0'), class: "text-decoration-none" do %>
+                        <code class="small"><%= error[:error_type] %></code>
+                      <% end %>
                     </td>
                     <td>
                       <% error[:platforms].each do |platform| %>

data/app/views/rails_error_dashboard/errors/releases.html.erb

@@ -185,7 +185,9 @@
               <% @releases.each do |release| %>
                 <tr class="<%= 'table-active' if release[:current] %>">
                   <td>
-                    <strong><%= release[:version] %></strong>
+                    <%= link_to errors_path(app_version: release[:version], unresolved: '0'), class: "text-decoration-none" do %>
+                      <strong><%= release[:version] %></strong>
+                    <% end %>
                     <% if release[:current] %>
                       <span class="badge bg-primary ms-1">Current</span>
                     <% end %>

data/app/views/rails_error_dashboard/errors/settings.html.erb

@@ -213,7 +213,6 @@
   <div class="card" style="margin-bottom: var(--space-4);">
     <div style="padding: var(--space-4) var(--space-6); border-bottom: 1px solid var(--border-primary);">
       <span style="font-size: 14px; font-weight: 600; color: var(--text-primary);"><i class="bi bi-puzzle" style="margin-right: 6px;"></i> Active Plugins</span>
-      </h5>
     </div>
     <div class="card-body">
       <% if RailsErrorDashboard::PluginRegistry.any? %>

data/app/views/rails_error_dashboard/errors/show.html.erb

@@ -80,6 +80,11 @@
       <button type="button" class="btn" data-red-action="copy-markdown" data-markdown="<%= j @error_markdown %>">
         <i class="bi bi-clipboard" style="margin-right: 4px;"></i>Copy for LLM
       </button>
+      <% if RailsErrorDashboard.configuration.llm_configured? %>
+        <button type="button" class="btn" data-red-action="open-ai-help">
+          <i class="bi bi-stars" style="margin-right: 4px;"></i>AI Help
+        </button>
+      <% end %>
       <button type="button" class="btn" data-red-action="download-json" title="Export JSON">
         <i class="bi bi-download"></i>
       </button>
@@ -165,6 +170,8 @@
     <div class="error-sidebar" style="display: flex; flex-direction: column; gap: var(--space-4); min-width: 0; overflow-wrap: break-word;">
       <%= render "sidebar_metadata", error: @error, related_errors: @related_errors %>
 
+      <%= render "llm_summary", error: @error %>
+
       <!-- Baseline Statistics -->
       <% if RailsErrorDashboard.configuration.enable_baseline_alerts %>
         <% baselines = @error.baselines %>
@@ -211,8 +218,10 @@
               <i class="bi bi-person"></i> View User's Errors
             <% end %>
           <% end %>
-          <%= link_to errors_path(app_context.merge(platform: @error.platform, unresolved: '0')), class: "btn btn-sm" do %>
-            <i class="bi bi-phone"></i> View <%= @error.platform %> Errors
+          <% if @error.platform.present? %>
+            <%= link_to errors_path(app_context.merge(platform: @error.platform, unresolved: '0')), class: "btn btn-sm" do %>
+              <i class="bi bi-phone"></i> View <%= @error.platform %> Errors
+            <% end %>
           <% end %>
           <%= link_to analytics_errors_path(app_context), class: "btn btn-sm" do %>
             <i class="bi bi-bar-chart-line"></i> Analytics
@@ -224,6 +233,7 @@
 </div>
 
 <%= render "modals", error: @error %>
+<%= render "ai_help_panel", error: @error if RailsErrorDashboard.configuration.llm_configured? %>
 
 <%= red_javascript_tag do %>
 window.switchTab = function(tabId) {

data/app/views/rails_error_dashboard/errors/swallowed_exceptions.html.erb

@@ -93,7 +93,11 @@
             <tbody>
               <% @entries.each do |entry| %>
                 <tr>
-                  <td><code style="font-size: 0.85em;"><%= entry[:exception_class] %></code></td>
+                  <td>
+                    <%= link_to errors_path(error_type: entry[:exception_class], unresolved: '0'), class: "text-decoration-none", title: "View any unrescued #{entry[:exception_class]} errors that leaked into error_log" do %>
+                      <code style="font-size: 0.85em;"><%= entry[:exception_class] %></code>
+                    <% end %>
+                  </td>
                   <td style="color: var(--text-secondary); font-size: 12px; word-break: break-all;"><%= entry[:raise_location] %></td>
                   <td style="color: var(--text-secondary); font-size: 12px; word-break: break-all;"><%= entry[:rescue_location] || "Unknown" %></td>
                   <td><span class="badge bg-info text-dark"><%= number_with_delimiter(entry[:raise_count]) %></span></td>

data/app/views/rails_error_dashboard/errors/user_impact.html.erb

@@ -107,7 +107,9 @@
                 <tr>
                   <td><strong><%= (@pagy.from || 1) + index %></strong></td>
                   <td>
-                    <strong><%= entry[:error_type] %></strong>
+                    <%= link_to errors_path(error_type: entry[:error_type], unresolved: '0'), class: "text-decoration-none" do %>
+                      <strong><%= entry[:error_type] %></strong>
+                    <% end %>
                     <br><small class="text-muted"><%= entry[:message] %></small>
                   </td>
                   <td>

data/config/routes.rb

@@ -23,6 +23,7 @@ RailsErrorDashboard::Engine.routes.draw do
       post :update_status
       post :create_issue
       post :link_issue
+      post :ai_help
     end
     collection do
       get :analytics

data/lib/generators/rails_error_dashboard/install/templates/initializer.rb

@@ -456,6 +456,33 @@ RailsErrorDashboard.configure do |config|
   #   Codeberg: "https://codeberg.org/username/repo"
   # config.git_repository_url = ENV["GIT_REPOSITORY_URL"]
 
+  # ============================================================================
+  # AI HELP (OpenAI / Anthropic)
+  # ============================================================================
+  #
+  # When provider and API key are configured, error detail pages show an
+  # "AI Help" drawer where dashboard users can ask questions about the current
+  # error. Error details, backtrace, and related dashboard context are sent to
+  # the configured provider.
+  #
+  # OpenAI uses the Responses API by default and supports GPT-5 and GPT-4 family
+  # models such as "gpt-5" and "gpt-4.1". Set llm_openai_endpoint to
+  # :chat_completions only if you need the older Chat Completions endpoint.
+  #
+  # config.llm_provider = :openai
+  # config.llm_api_key = -> { Rails.application.credentials.dig(:openai, :api_key) }
+  # config.llm_model = "gpt-5"
+  # config.llm_openai_endpoint = :auto # :auto, :responses, or :chat_completions
+  #
+  # config.llm_provider = :anthropic
+  # config.llm_api_key = -> { Rails.application.credentials.dig(:anthropic, :api_key) }
+  # config.llm_model = "claude-sonnet-4-20250514"
+  #
+  # Shared options:
+  # config.llm_timeout_seconds = 30
+  # config.llm_max_output_tokens = 900
+  # config.llm_system_prompt = "Prefer concise answers with file-level next steps."
+
   # ============================================================================
   # ISSUE TRACKING (GitHub / GitLab / Codeberg)
   # ============================================================================

data/lib/rails_error_dashboard/configuration.rb

@@ -184,9 +184,23 @@ module RailsErrorDashboard
     # ActiveStorage event tracking (requires enable_breadcrumbs = true)
     attr_accessor :enable_activestorage_tracking        # Master switch (default: false)
 
+    # LLM observability (requires enable_breadcrumbs = true)
+    attr_accessor :enable_llm_observability             # Master switch (default: false)
+    attr_accessor :llm_observability_content_capture    # Capture prompt/completion text (default: false — PII risk)
+    attr_accessor :llm_pricing_overrides                # Hash of { "model-name" => { input: usd_per_1m, output: usd_per_1m } }
+
     # Dashboard UI appearance
     attr_accessor :accent_color  # :crimson (default), :ruby, :ember, :violet
 
+    # LLM-powered AI help (disabled unless provider and API key are configured)
+    attr_accessor :llm_provider              # :openai or :anthropic
+    attr_accessor :llm_api_key               # String or lambda/proc
+    attr_accessor :llm_model                 # e.g. "gpt-5", "gpt-4.1", "claude-sonnet-4-20250514"
+    attr_accessor :llm_openai_endpoint       # :responses, :chat_completions, or :auto
+    attr_accessor :llm_timeout_seconds       # HTTP timeout for provider calls
+    attr_accessor :llm_max_output_tokens     # Response length cap
+    attr_accessor :llm_system_prompt         # Optional prompt override/addition
+
     # Notification callbacks (managed via helper methods, not set directly)
     attr_reader :notification_callbacks
 
@@ -304,7 +318,7 @@ module RailsErrorDashboard
       # Breadcrumbs defaults - OFF by default (opt-in)
       @enable_breadcrumbs = false         # Master switch
       @breadcrumb_buffer_size = 40        # Max events per request (Sentry uses 100, we're conservative)
-      @breadcrumb_categories = nil        # nil = all; or [:sql, :controller, :cache, :job, :mailer, :custom, :deprecation]
+      @breadcrumb_categories = nil        # nil = all; or [:sql, :controller, :cache, :job, :mailer, :custom, :deprecation, :llm, :llm_tool]
 
       # N+1 query detection defaults - ON by default (lightweight display-time analysis)
       @enable_n_plus_one_detection = true  # Analyze SQL breadcrumbs for repeated patterns
@@ -352,6 +366,12 @@ module RailsErrorDashboard
       # ActiveStorage event tracking defaults - OFF by default (opt-in, requires breadcrumbs)
       @enable_activestorage_tracking = false
 
+      # LLM observability defaults - OFF by default (opt-in, requires breadcrumbs)
+      # content_capture stays OFF even when master switch is on (privacy: prompts may contain PII/secrets)
+      @enable_llm_observability = false
+      @llm_observability_content_capture = false
+      @llm_pricing_overrides = {}
+
       # Internal logging defaults - SILENT by default
       @enable_internal_logging = false  # Opt-in for debugging
       @log_level = :silent  # Silent by default, use :debug, :info, :warn, :error, or :silent
@@ -359,6 +379,15 @@ module RailsErrorDashboard
       # Dashboard UI
       @accent_color = :crimson  # :crimson, :ruby, :ember, :violet
 
+      # LLM-powered AI help defaults - OFF until provider and API key are configured
+      @llm_provider = ENV["RED_LLM_PROVIDER"]&.to_sym
+      @llm_api_key = ENV["RED_LLM_API_KEY"]
+      @llm_model = ENV["RED_LLM_MODEL"]
+      @llm_openai_endpoint = (ENV["RED_LLM_OPENAI_ENDPOINT"] || "auto").to_sym
+      @llm_timeout_seconds = 30
+      @llm_max_output_tokens = 900
+      @llm_system_prompt = nil
+
       @notification_callbacks = {
         error_logged: [],
         critical_error: [],
@@ -517,6 +546,13 @@ module RailsErrorDashboard
         @enable_activestorage_tracking = false
       end
 
+      # Validate llm observability requires breadcrumbs
+      if enable_llm_observability && !enable_breadcrumbs
+        warnings << "enable_llm_observability requires enable_breadcrumbs = true. " \
+                    "LLM observability has been auto-disabled."
+        @enable_llm_observability = false
+      end
+
       # Skip credential/service-dependent validations during Docker builds.
       # SECRET_KEY_BASE_DUMMY=1 means no credentials or external services available.
       build_env = ENV["SECRET_KEY_BASE_DUMMY"].present?
@@ -582,6 +618,33 @@ module RailsErrorDashboard
         end
       end
 
+      # Validate LLM configuration only when partially or fully configured.
+      if llm_provider.present? || effective_llm_api_key.present? || llm_model.present?
+        valid_llm_providers = %i[openai anthropic]
+        unless effective_llm_provider && valid_llm_providers.include?(effective_llm_provider)
+          errors << "llm_provider must be one of #{valid_llm_providers.inspect} (got: #{llm_provider.inspect})"
+        end
+
+        if effective_llm_api_key.blank? && !build_env
+          warnings << "llm_provider is configured but no LLM API key is set. " \
+                      "Set llm_api_key or RED_LLM_API_KEY to enable AI Help."
+        end
+
+        valid_openai_endpoints = %i[auto responses chat_completions]
+        if llm_openai_endpoint && !valid_openai_endpoints.include?(llm_openai_endpoint.to_sym)
+          errors << "llm_openai_endpoint must be one of #{valid_openai_endpoints.inspect} " \
+                    "(got: #{llm_openai_endpoint.inspect})"
+        end
+
+        if llm_timeout_seconds && llm_timeout_seconds.to_i < 1
+          errors << "llm_timeout_seconds must be at least 1 (got: #{llm_timeout_seconds})"
+        end
+
+        if llm_max_output_tokens && llm_max_output_tokens.to_i < 1
+          errors << "llm_max_output_tokens must be at least 1 (got: #{llm_max_output_tokens})"
+        end
+      end
+
       # Validate total_users_for_impact (must be positive if set)
       if total_users_for_impact && total_users_for_impact < 1
         errors << "total_users_for_impact must be at least 1 (got: #{total_users_for_impact})"
@@ -686,6 +749,43 @@ module RailsErrorDashboard
       end
     end
 
+    # Whether the dashboard can show AI Help controls.
+    #
+    # @return [Boolean]
+    def llm_configured?
+      effective_llm_provider.present? && effective_llm_api_key.present?
+    end
+
+    # Resolve the configured LLM provider.
+    #
+    # @return [Symbol, nil] :openai, :anthropic, or nil
+    def effective_llm_provider
+      provider = llm_provider.presence
+      provider&.to_sym
+    end
+
+    # Resolve the configured LLM API key (supports string or lambda).
+    #
+    # @return [String, nil]
+    def effective_llm_api_key
+      return nil if llm_api_key.nil?
+      llm_api_key.respond_to?(:call) ? llm_api_key.call : llm_api_key
+    rescue => e
+      nil
+    end
+
+    # Resolve the configured model with provider-specific defaults.
+    #
+    # @return [String, nil]
+    def effective_llm_model
+      return llm_model if llm_model.present?
+
+      case effective_llm_provider
+      when :openai then "gpt-5"
+      when :anthropic then "claude-sonnet-4-20250514"
+      end
+    end
+
     # Detect the engine's mount path from the host app routes.
     # Falls back to "/red" if detection fails.
     #

data/lib/rails_error_dashboard/engine.rb

@@ -101,6 +101,20 @@ module RailsErrorDashboard
         RailsErrorDashboard::Subscribers::ActiveStorageSubscriber.subscribe!
       end
 
+      # Register OpenTelemetry SpanProcessor for LLM observability — Tier 1 path
+      # for hosts already running OTel (ruby_llm, thoughtbot/instrumentation).
+      # Internally guards on Integrations::OTel.available? + tracer provider
+      # capability, so this is safe to call unconditionally.
+      RailsErrorDashboard::Integrations::LlmSpanProcessor.register!
+
+      # Subscribe to red.llm_call / red.llm_tool_call AS::Notifications — Tier 3
+      # path for hosts using direct Net::HTTP / gRPC / local inference servers
+      # that aren't covered by OTel or the Faraday middleware.
+      if RailsErrorDashboard.configuration.enable_llm_observability &&
+         RailsErrorDashboard.configuration.enable_breadcrumbs
+        RailsErrorDashboard::Subscribers::LlmCallSubscriber.subscribe!
+      end
+
       # Enable TracePoint(:raise) for local variable and/or instance variable capture
       if RailsErrorDashboard.configuration.enable_local_variables ||
          RailsErrorDashboard.configuration.enable_instance_variables