feat: Add LLM rule explanations, real-time visualizations, and fix analytics permissions

app.py

@@ -510,6 +510,18 @@ def add_admin_rules(tenant_id: str, role: str, rules_text: str) -> str:
                 if data.get("enhanced"):
                     edge_cases = data.get("edge_cases", [])
                     improvements = data.get("improvements", [])
+                    explanation = data.get("explanation", "")
+                    examples = data.get("examples", [])
+                    missing_patterns = data.get("missing_patterns", [])
+                    
+                    if explanation:
+                        enhanced.append(f"**💡 Explanation:** {explanation}")
+                    if examples:
+                        examples_list = "\n".join([f"  • {ex}" for ex in examples[:5]])
+                        enhanced.append(f"**📋 Examples:**\n{examples_list}")
+                    if missing_patterns:
+                        patterns_list = "\n".join([f"  • {p}" for p in missing_patterns[:5]])
+                        enhanced.append(f"**🔍 Suggested Patterns:**\n{patterns_list}")
                     if edge_cases or improvements:
                         enhanced.append(f"**{data.get('added_rule', rules[0])}**:")
                         if improvements:
@@ -546,6 +558,18 @@ def add_admin_rules(tenant_id: str, role: str, rules_text: str) -> str:
                     if data.get("enhanced"):
                         chunk_enhanced = data.get("enhancement_summary", [])
                         enhanced.extend([f"[Chunk {chunk_num}/{total_chunks}] {e}" for e in chunk_enhanced])
+                        
+                        # Add explanations for bulk rules if available
+                        if data.get("explanations"):
+                            for exp in data["explanations"][:3]:  # Show first 3 explanations
+                                if exp.get("explanation"):
+                                    enhanced.append(f"\n💡 **{exp.get('rule', 'Rule')} Explanation:** {exp['explanation']}")
+                                if exp.get("examples"):
+                                    examples_list = "\n".join([f"  • {ex}" for ex in exp['examples'][:3]])
+                                    enhanced.append(f"📋 **Examples:**\n{examples_list}")
+                                if exp.get("missing_patterns"):
+                                    patterns_list = "\n".join([f"  • {p}" for p in exp['missing_patterns'][:3]])
+                                    enhanced.append(f"🔍 **Suggested Patterns:**\n{patterns_list}")
                 else:
                     errors.append(f"Chunk {chunk_num}/{total_chunks} failed: {resp.status_code}: {resp.text}")
             except requests.exceptions.Timeout:
@@ -562,6 +586,7 @@ def add_admin_rules(tenant_id: str, role: str, rules_text: str) -> str:
         summary.append(f"\n🤖 LLM Enhancement Applied:\n" + "\n".join(enhanced[:5]))
         if len(enhanced) > 5:
             summary.append(f"... and {len(enhanced) - 5} more enhancements")
+    
     if errors:
         summary.append("\n⚠️ Errors:\n" + "\n".join(errors))
 

backend/api/routes/admin.py

@@ -183,6 +183,9 @@ async def add_redflag_rule(
         final_pattern = enhanced_data["pattern"]
         final_severity = enhanced_data["severity"]
         final_description = enhanced_data["description"]
+        explanation = enhanced_data.get("explanation", "")
+        examples = enhanced_data.get("examples", [])
+        missing_patterns = enhanced_data.get("missing_patterns", [])
         edge_cases = enhanced_data.get("edge_cases", [])
         improvements = enhanced_data.get("improvements", [])
     else:
@@ -191,6 +194,9 @@ async def add_redflag_rule(
         final_pattern = payload.pattern if payload else None
         final_severity = payload.severity if payload else "medium"
         final_description = payload.description if payload else None
+        explanation = ""
+        examples = []
+        missing_patterns = []
         edge_cases = []
         improvements = []
     
@@ -228,6 +234,9 @@ async def add_redflag_rule(
         "severity": final_severity,
         "description": final_description or final_rule,
         "enhanced": enhanced_data is not None,
+        "explanation": explanation,
+        "examples": examples,
+        "missing_patterns": missing_patterns,
         "edge_cases": edge_cases,
         "improvements": improvements,
         "rules": rules
@@ -540,6 +549,17 @@ async def upload_rules_from_file(
         
         rules_list = get_rules_for_tenant(x_tenant_id)
         
+        # Collect explanations, examples, and missing patterns from enhanced rules
+        explanations_data = []
+        for i, enhanced in enumerate(enhanced_rules_data):
+            if i < len(rules):
+                explanations_data.append({
+                    "rule": enhanced.get("rule", rules[i]),
+                    "explanation": enhanced.get("explanation", ""),
+                    "examples": enhanced.get("examples", []),
+                    "missing_patterns": enhanced.get("missing_patterns", [])
+                })
+        
         return {
             "tenant_id": x_tenant_id,
             "filename": file.filename,
@@ -547,6 +567,7 @@ async def upload_rules_from_file(
             "total_extracted": len(rules),
             "enhanced": len(enhanced_rules_data) > 0,
             "enhancement_summary": enhancement_summary,
+            "explanations": explanations_data,
             "rules": rules_list
         }
     

backend/api/routes/analytics.py

@@ -109,7 +109,7 @@ async def analytics_activity(
 ):
     """
     Returns general tenant activity statistics.
-    Includes total queries, active users, and last query timestamp.
+    Includes total queries, active users, last query timestamp, and individual activity records for heatmap visualization.
     """
 
     if not x_tenant_id:
@@ -118,10 +118,14 @@ async def analytics_activity(
 
     since_timestamp = int((datetime.now() - timedelta(days=days)).timestamp()) if days else None
     activity = analytics_store.get_activity_summary(x_tenant_id, since_timestamp)
+    
+    # Also fetch individual activity records for heatmap visualization
+    activities = analytics_store.get_activity_records(x_tenant_id, since_timestamp)
 
     return {
         "tenant_id": x_tenant_id,
         "activity": activity,
+        "activities": activities,  # Individual records with timestamps for heatmap
         "period_days": days
     }
 

backend/api/services/rule_enhancer.py

@@ -51,7 +51,7 @@ class RuleEnhancer:
         
         context_text = f"\nAdditional context: {context}" if context else ""
         
-        prompt = f"""You are an expert in policy rule analysis and pattern matching. Analyze the following rule and enhance it.
+        prompt = f"""You are an expert in policy rule analysis and pattern matching. Analyze the following rule and provide comprehensive enhancements.
 
 Original Rule: "{rule_text}"
 
@@ -60,12 +60,15 @@ Existing Rules (for context):
 {context_text}
 
 Your task:
-1. Analyze the rule for potential edge cases and improvements
-2. Generate an improved regex pattern that catches more variations
-3. Write a clear, comprehensive description
-4. Suggest an appropriate severity level (low/medium/high/critical)
-5. Identify edge cases that might be missed
-6. Suggest improvements
+1. Generate a human-readable explanation of what this rule does (2-3 sentences, plain English)
+2. Provide 5-8 concrete examples of text/phrases that would match this rule's pattern
+3. Suggest 3-5 missing patterns or variations that should also be caught
+4. Analyze the rule for potential edge cases and improvements
+5. Generate an improved regex pattern that catches more variations
+6. Write a clear, comprehensive description
+7. Suggest an appropriate severity level (low/medium/high/critical)
+8. Identify edge cases that might be missed
+9. Suggest improvements
 
 Respond in JSON format with the following structure:
 {{
@@ -73,6 +76,17 @@ Respond in JSON format with the following structure:
     "pattern": "Improved regex pattern (e.g., '.*password.*|.*pwd.*|.*passcode.*')",
     "description": "Clear description of what this rule detects",
     "severity": "low|medium|high|critical",
+    "explanation": "Human-readable explanation in 2-3 sentences explaining what this rule does and why it's important",
+    "examples": [
+        "Example text that would match: 'Please share your password'",
+        "Another example: 'My pwd is 12345'",
+        "More examples..."
+    ],
+    "missing_patterns": [
+        "Pattern variation 1 that should be considered",
+        "Pattern variation 2 that should be considered",
+        "More suggestions..."
+    ],
     "edge_cases": ["Edge case 1", "Edge case 2", ...],
     "improvements": ["Improvement 1", "Improvement 2", ...],
     "keywords": ["keyword1", "keyword2", ...]
@@ -107,6 +121,9 @@ Only return valid JSON, no additional text:"""
                 "pattern": enhanced_data.get("pattern", rule_text),
                 "description": enhanced_data.get("description", rule_text),
                 "severity": enhanced_data.get("severity", "medium"),
+                "explanation": enhanced_data.get("explanation", f"This rule detects: {rule_text}"),
+                "examples": enhanced_data.get("examples", []),
+                "missing_patterns": enhanced_data.get("missing_patterns", []),
                 "edge_cases": enhanced_data.get("edge_cases", []),
                 "improvements": enhanced_data.get("improvements", []),
                 "keywords": enhanced_data.get("keywords", [])
@@ -119,27 +136,35 @@ Only return valid JSON, no additional text:"""
             return result
             
         except asyncio.TimeoutError:
-            # Timeout - return original rule
+            # Timeout - generate basic explanation without LLM
             print(f"LLM enhancement timeout for rule: {rule_text[:50]}...")
+            basic_explanation = self._generate_basic_explanation(rule_text)
             return {
                 "rule": rule_text,
                 "pattern": rule_text,
                 "description": rule_text,
                 "severity": "medium",
+                "explanation": basic_explanation["explanation"],
+                "examples": basic_explanation["examples"],
+                "missing_patterns": basic_explanation["missing_patterns"],
                 "edge_cases": [],
-                "improvements": ["Enhancement timed out - using original rule"],
+                "improvements": ["Enhancement timed out - using basic explanation"],
                 "keywords": []
             }
         except Exception as e:
-            # Fallback to original rule if LLM fails
+            # Fallback to basic explanation if LLM fails
             print(f"LLM enhancement error: {e}")
+            basic_explanation = self._generate_basic_explanation(rule_text)
             return {
                 "rule": rule_text,
                 "pattern": rule_text,
                 "description": rule_text,
                 "severity": "medium",
+                "explanation": basic_explanation["explanation"],
+                "examples": basic_explanation["examples"],
+                "missing_patterns": basic_explanation["missing_patterns"],
                 "edge_cases": [],
-                "improvements": [f"Enhancement failed: {str(e)[:50]}"],
+                "improvements": [f"Enhancement failed - using basic explanation"],
                 "keywords": []
             }
     
@@ -170,15 +195,111 @@ Only return valid JSON, no additional text:"""
                 # If enhancement fails for one rule, use original rule
                 # This ensures other rules can still be processed
                 print(f"Warning: Rule {i+1}/{len(rules)} enhancement failed: {e}")
+                # Generate basic explanation even on error
+                basic_explanation = self._generate_basic_explanation(rule)
                 enhanced_rules.append({
                     "rule": rule,
                     "pattern": rule,
                     "description": rule,
                     "severity": "medium",
+                    "explanation": basic_explanation["explanation"],
+                    "examples": basic_explanation["examples"],
+                    "missing_patterns": basic_explanation["missing_patterns"],
                     "edge_cases": [],
-                    "improvements": [f"Enhancement skipped due to error"],
+                    "improvements": [f"Enhancement skipped - using basic explanation"],
                     "keywords": []
                 })
         
         return enhanced_rules
+    
+    def _generate_basic_explanation(self, rule_text: str) -> Dict[str, Any]:
+        """
+        Generate a basic explanation without LLM when enhancement fails or times out.
+        Uses pattern matching and keyword extraction to provide useful information.
+        """
+        rule_lower = rule_text.lower()
+        
+        # Extract key concepts
+        keywords = []
+        if any(word in rule_lower for word in ["password", "pwd", "passcode", "credential"]):
+            keywords.append("authentication credentials")
+        if any(word in rule_lower for word in ["api", "key", "token", "secret"]):
+            keywords.append("API keys and tokens")
+        if any(word in rule_lower for word in ["credit", "card", "payment", "bank"]):
+            keywords.append("financial information")
+        if any(word in rule_lower for word in ["share", "send", "disclose", "reveal"]):
+            keywords.append("information sharing")
+        if any(word in rule_lower for word in ["prevent", "block", "stop", "deny"]):
+            keywords.append("prevention")
+        if any(word in rule_lower for word in ["sensitive", "private", "confidential"]):
+            keywords.append("sensitive data")
+        
+        # Generate explanation
+        if keywords:
+            explanation = f"This rule is designed to prevent sharing of {', '.join(keywords)}. It monitors conversations to detect attempts to disclose sensitive information that could compromise security or privacy."
+        else:
+            explanation = f"This rule monitors for: {rule_text}. It helps maintain security and compliance by detecting potentially sensitive information sharing."
+        
+        # Generate basic examples based on keywords
+        examples = []
+        if "password" in rule_lower or "credential" in rule_lower:
+            examples.extend([
+                "Can you share your password?",
+                "My password is 12345",
+                "What's your login pwd?",
+                "Here's my passcode: 9876",
+                "The credentials are admin/password123"
+            ])
+        if "api" in rule_lower or "key" in rule_lower:
+            examples.extend([
+                "My API key is sk-1234567890",
+                "Here's the access token: xyz123",
+                "The secret key is abc-def-ghi",
+                "API token: bearer_abc123xyz"
+            ])
+        if "credit" in rule_lower or "card" in rule_lower:
+            examples.extend([
+                "My credit card number is 4532-1234-5678-9010",
+                "CVV is 123",
+                "Card expiry: 12/25"
+            ])
+        if "sensitive" in rule_lower or "authentication" in rule_lower:
+            examples.extend([
+                "Here's my login info",
+                "I'll send you the credentials",
+                "The password is...",
+                "Can I share my account details?"
+            ])
+        if not examples:
+            # Generic examples based on rule text
+            examples = [
+                f"Example: '{rule_text[:40]}...'",
+                "Similar variations of the rule text",
+                "Related phrases containing key terms from the rule"
+            ]
+        
+        # Suggest missing patterns
+        missing_patterns = []
+        if "password" in rule_lower:
+            missing_patterns.extend([
+                "Consider variations: 'pwd', 'passcode', 'login credentials', 'auth info'"
+            ])
+        if "api" in rule_lower or "key" in rule_lower:
+            missing_patterns.extend([
+                "Consider: 'access token', 'secret key', 'auth token', 'bearer token'"
+            ])
+        if "share" in rule_lower:
+            missing_patterns.extend([
+                "Consider action verbs: 'send', 'disclose', 'reveal', 'provide', 'give'"
+            ])
+        if "sensitive" in rule_lower:
+            missing_patterns.extend([
+                "Consider synonyms: 'confidential', 'private', 'secret', 'classified'"
+            ])
+        
+        return {
+            "explanation": explanation,
+            "examples": examples[:8],  # Limit to 8 examples
+            "missing_patterns": missing_patterns[:5]  # Limit to 5 suggestions
+        }
 

backend/api/storage/analytics_store.py

@@ -454,6 +454,46 @@ class AnalyticsStore:
             if last_query_ts
             else None,
         }
+    
+    def get_activity_records(
+        self,
+        tenant_id: str,
+        since_timestamp: Optional[int] = None,
+        limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """Get individual activity records (agent queries) with timestamps for heatmap visualization."""
+        if not self.supabase_client:
+            raise RuntimeError("Supabase client not initialized. Cannot get activity records.")
+        
+        # Fetch agent query events (these represent user queries/activity)
+        queries = self._supabase_simple_select(
+            self.table_names["agent_query"],
+            tenant_id,
+            since_timestamp=since_timestamp,
+            limit=limit,
+            order_desc=False,  # Chronological order for heatmap
+        )
+        
+        # Format records for frontend consumption
+        activities = []
+        for query in queries:
+            timestamp = query.get("timestamp")
+            if timestamp:
+                # Convert timestamp to ISO format if it's a Unix timestamp
+                if isinstance(timestamp, (int, float)):
+                    timestamp_iso = datetime.fromtimestamp(timestamp).isoformat()
+                else:
+                    timestamp_iso = str(timestamp)
+                
+                activities.append({
+                    "timestamp": timestamp_iso,
+                    "created_at": timestamp_iso,  # Alias for compatibility
+                    "type": "query",
+                    "user_id": query.get("user_id"),
+                    "message_preview": query.get("message_preview", "")[:100],
+                })
+        
+        return activities
 
     def get_rag_quality_metrics(
         self,

backend/mcp_server/common/access_control.py

@@ -11,7 +11,7 @@ PERMISSIONS: dict[str, Set[str]] = {
     "manage_rules": {"owner", "admin"},
     "ingest_documents": {"owner", "admin", "editor"},
     "delete_documents": {"owner", "admin"},
-    "view_analytics": {"owner", "admin"},
+    "view_analytics": {"viewer", "editor", "admin", "owner"},  # All roles can view analytics
 }
 
 # Mapping of MCP tool names to enterprise actions

frontend/app/admin-rules/page.tsx

@@ -1,9 +1,10 @@
 "use client";
 
-import { useCallback, useMemo, useState, useRef, useEffect } from "react";
+import React, { useCallback, useMemo, useState, useRef, useEffect } from "react";
 import Link from "next/link";
 
 import { AdminRulesPanel } from "@/components/admin-rules-panel";
+import { RuleExplanation } from "@/components/rule-explanation";
 import { Footer } from "@/components/footer";
 import { useTenant } from "@/contexts/TenantContext";
 import { TenantSelector } from "@/components/tenant-selector";
@@ -50,6 +51,9 @@ export default function AdminRulesPage() {
   const [status, setStatus] = useState<StatusState>(null);
   const [isDragging, setIsDragging] = useState(false);
   const [lastUpdated, setLastUpdated] = useState<string>("");
+  const [ruleExplanations, setRuleExplanations] = useState<Record<string, any>>({});
+  const [expandedRules, setExpandedRules] = useState<Set<string>>(new Set());
+  const [loadingExplanations, setLoadingExplanations] = useState<Set<string>>(new Set());
   const fileInputRef = useRef<HTMLInputElement>(null);
 
   // Set initial time only on client side to avoid hydration mismatch
@@ -123,6 +127,25 @@ export default function AdminRulesPage() {
       const data = await response.json();
       await handleRefresh();
       setRulesInput("");
+      
+      // Store explanations for display and auto-expand
+      if (data.explanations && Array.isArray(data.explanations)) {
+        const explanationsMap: Record<string, any> = {};
+        const newExpanded = new Set(expandedRules);
+        
+        data.explanations.forEach((exp: any) => {
+          if (exp.rule) {
+            explanationsMap[exp.rule] = exp;
+            // Auto-expand rules that have explanations
+            if (exp.explanation || exp.examples || exp.missing_patterns) {
+              newExpanded.add(exp.rule);
+            }
+          }
+        });
+        setRuleExplanations((prev) => ({ ...prev, ...explanationsMap }));
+        setExpandedRules(newExpanded);
+      }
+      
       const enhancedMsg = data.enhanced ? " (enhanced by LLM)" : "";
       setStatus({ tone: "success", message: `Uploaded ${data.added_rules?.length || lines.length} rule(s)${enhancedMsg}.` });
     } catch (error: any) {
@@ -173,6 +196,25 @@ export default function AdminRulesPage() {
 
         const data = await response.json();
         await handleRefresh();
+        
+        // Store explanations for display and auto-expand
+        if (data.explanations && Array.isArray(data.explanations)) {
+          const explanationsMap: Record<string, any> = {};
+          const newExpanded = new Set(expandedRules);
+          
+          data.explanations.forEach((exp: any) => {
+            if (exp.rule) {
+              explanationsMap[exp.rule] = exp;
+              // Auto-expand rules that have explanations
+              if (exp.explanation || exp.examples || exp.missing_patterns) {
+                newExpanded.add(exp.rule);
+              }
+            }
+          });
+          setRuleExplanations((prev) => ({ ...prev, ...explanationsMap }));
+          setExpandedRules(newExpanded);
+        }
+        
         const enhancedMsg = data.enhanced ? " (enhanced by LLM)" : "";
         setStatus({ tone: "success", message: `Uploaded ${data.added_rules?.length || lines.length} rule(s) from ${file.name}${enhancedMsg}.` });
         return;
@@ -198,6 +240,25 @@ export default function AdminRulesPage() {
 
       const data = await response.json();
       await handleRefresh();
+      
+      // Store explanations for display and auto-expand
+      if (data.explanations && Array.isArray(data.explanations)) {
+        const explanationsMap: Record<string, any> = {};
+        const newExpanded = new Set(expandedRules);
+        
+        data.explanations.forEach((exp: any) => {
+          if (exp.rule) {
+            explanationsMap[exp.rule] = exp;
+            // Auto-expand rules that have explanations
+            if (exp.explanation || exp.examples || exp.missing_patterns) {
+              newExpanded.add(exp.rule);
+            }
+          }
+        });
+        setRuleExplanations((prev) => ({ ...prev, ...explanationsMap }));
+        setExpandedRules(newExpanded);
+      }
+      
       const enhancedMsg = data.enhanced ? " (enhanced by LLM)" : "";
       setStatus({ 
         tone: "success", 
@@ -248,6 +309,71 @@ export default function AdminRulesPage() {
     await processFile(file);
   }, [processFile]);
 
+  const fetchRuleExplanation = useCallback(async (rule: string) => {
+    if (!requireTenant()) return;
+    if (ruleExplanations[rule]) return; // Already have explanation
+    
+    try {
+      setLoadingExplanations((prev) => new Set(prev).add(rule));
+      
+      // Fetch explanation by calling the enhance endpoint
+      // We'll use POST with the rule in the body to get explanation
+      const response = await fetch(
+        `${BACKEND_BASE_URL}/admin/rules?enhance=true`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "x-tenant-id": tenantId.trim(),
+            "x-user-role": role,
+          },
+          body: JSON.stringify({ rule }),
+        }
+      );
+      
+      if (response.ok) {
+        const data = await response.json();
+        if (data.explanation || data.examples || data.missing_patterns) {
+          setRuleExplanations((prev) => ({
+            ...prev,
+            [rule]: {
+              explanation: data.explanation,
+              examples: data.examples || [],
+              missing_patterns: data.missing_patterns || [],
+              edge_cases: data.edge_cases || [],
+              improvements: data.improvements || [],
+              severity: data.severity,
+            },
+          }));
+        }
+      }
+    } catch (error) {
+      console.error("Failed to fetch rule explanation:", error);
+    } finally {
+      setLoadingExplanations((prev) => {
+        const next = new Set(prev);
+        next.delete(rule);
+        return next;
+      });
+    }
+  }, [tenantId, role, ruleExplanations, requireTenant]);
+
+  const toggleRuleExplanation = useCallback((rule: string) => {
+    setExpandedRules((prev) => {
+      const next = new Set(prev);
+      if (next.has(rule)) {
+        next.delete(rule);
+      } else {
+        next.add(rule);
+        // Fetch explanation if we don't have it
+        if (!ruleExplanations[rule]) {
+          fetchRuleExplanation(rule);
+        }
+      }
+      return next;
+    });
+  }, [ruleExplanations, fetchRuleExplanation]);
+
   const handleDelete = useCallback(async () => {
     if (!requireTenant()) return;
     if (!deleteInput.trim()) {
@@ -578,15 +704,66 @@ export default function AdminRulesPage() {
                       </td>
                     </tr>
                   )}
-                  {rules.map((rule, idx) => (
-                    <tr 
-                      key={`${rule}-${idx}`} 
-                      className="border-t border-white/5 transition hover:bg-white/5"
-                    >
-                      <td className="px-6 py-4 text-slate-400 font-mono">{idx + 1}</td>
-                      <td className="px-6 py-4 text-slate-200">{rule}</td>
-                    </tr>
-                  ))}
+                  {rules.map((rule, idx) => {
+                    const explanation = ruleExplanations[rule];
+                    const isExpanded = expandedRules.has(rule);
+                    const isLoading = loadingExplanations.has(rule);
+                    return (
+                      <React.Fragment key={`${rule}-${idx}`}>
+                        <tr className="border-t border-white/5 transition hover:bg-white/5">
+                          <td className="px-6 py-4 text-slate-400 font-mono">{idx + 1}</td>
+                          <td className="px-6 py-4">
+                            <div className="flex items-center justify-between gap-3">
+                              <span className="text-slate-200 flex-1">{rule}</span>
+                              <button
+                                onClick={() => toggleRuleExplanation(rule)}
+                                className="flex items-center gap-2 rounded-lg border border-cyan-500/30 bg-cyan-500/10 px-3 py-1.5 text-xs font-semibold text-cyan-300 transition hover:bg-cyan-500/20 hover:border-cyan-400/50"
+                                title={isExpanded ? "Hide explanation" : "Show explanation"}
+                              >
+                                {isLoading ? (
+                                  <>
+                                    <span className="animate-spin">⏳</span>
+                                    <span>Loading...</span>
+                                  </>
+                                ) : isExpanded ? (
+                                  <>
+                                    <span>▼</span>
+                                    <span>Hide</span>
+                                  </>
+                                ) : (
+                                  <>
+                                    <span>▶</span>
+                                    <span>Explain</span>
+                                  </>
+                                )}
+                              </button>
+                            </div>
+                          </td>
+                        </tr>
+                        {isExpanded && explanation && (
+                          <tr>
+                            <td colSpan={2} className="px-6 py-4">
+                              <RuleExplanation
+                                explanation={explanation.explanation}
+                                examples={explanation.examples}
+                                missingPatterns={explanation.missing_patterns}
+                                edgeCases={explanation.edge_cases}
+                                improvements={explanation.improvements}
+                                severity={explanation.severity}
+                              />
+                            </td>
+                          </tr>
+                        )}
+                        {isExpanded && !explanation && !isLoading && (
+                          <tr>
+                            <td colSpan={2} className="px-6 py-4 text-center text-slate-400 text-sm">
+                              No explanation available for this rule.
+                            </td>
+                          </tr>
+                        )}
+                      </React.Fragment>
+                    );
+                  })}
                 </tbody>
               </table>
             </div>

frontend/components/rule-explanation.tsx

@@ -0,0 +1,129 @@
+"use client";
+
+type RuleExplanationProps = {
+  explanation?: string;
+  examples?: string[];
+  missingPatterns?: string[];
+  edgeCases?: string[];
+  improvements?: string[];
+  severity?: string;
+};
+
+export function RuleExplanation({
+  explanation,
+  examples = [],
+  missingPatterns = [],
+  edgeCases = [],
+  improvements = [],
+  severity,
+}: RuleExplanationProps) {
+  if (!explanation && examples.length === 0 && missingPatterns.length === 0) {
+    return null;
+  }
+
+  const severityColors = {
+    low: "bg-blue-500/20 border-blue-500/50 text-blue-200",
+    medium: "bg-yellow-500/20 border-yellow-500/50 text-yellow-200",
+    high: "bg-orange-500/20 border-orange-500/50 text-orange-200",
+    critical: "bg-red-500/20 border-red-500/50 text-red-200",
+  };
+
+  const severityColor = severityColors[severity as keyof typeof severityColors] || severityColors.medium;
+
+  return (
+    <div className="mt-4 space-y-4 rounded-2xl border border-white/10 bg-slate-950/60 p-6">
+      {/* Explanation */}
+      {explanation && (
+        <div>
+          <h4 className="mb-2 flex items-center gap-2 text-sm font-semibold uppercase tracking-wider text-cyan-300">
+            <span>💡</span> Explanation
+          </h4>
+          <p className="text-sm leading-relaxed text-slate-200">{explanation}</p>
+        </div>
+      )}
+
+      {/* Examples */}
+      {examples.length > 0 && (
+        <div>
+          <h4 className="mb-3 flex items-center gap-2 text-sm font-semibold uppercase tracking-wider text-emerald-300">
+            <span>📋</span> Examples This Rule Would Catch
+          </h4>
+          <div className="space-y-2">
+            {examples.map((example, idx) => (
+              <div
+                key={idx}
+                className="rounded-lg border border-emerald-500/30 bg-emerald-500/10 px-4 py-2.5 text-sm text-slate-100"
+              >
+                <span className="font-mono text-emerald-300">"{example}"</span>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {/* Missing Patterns */}
+      {missingPatterns.length > 0 && (
+        <div>
+          <h4 className="mb-3 flex items-center gap-2 text-sm font-semibold uppercase tracking-wider text-amber-300">
+            <span>🔍</span> Suggested Missing Patterns
+          </h4>
+          <div className="space-y-2">
+            {missingPatterns.map((pattern, idx) => (
+              <div
+                key={idx}
+                className="rounded-lg border border-amber-500/30 bg-amber-500/10 px-4 py-2.5 text-sm text-slate-100"
+              >
+                <span className="font-mono text-amber-300">{pattern}</span>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {/* Edge Cases */}
+      {edgeCases.length > 0 && (
+        <div>
+          <h4 className="mb-3 flex items-center gap-2 text-sm font-semibold uppercase tracking-wider text-purple-300">
+            <span>⚠️</span> Edge Cases Identified
+          </h4>
+          <ul className="space-y-1.5">
+            {edgeCases.map((edgeCase, idx) => (
+              <li key={idx} className="text-sm text-slate-300">
+                • {edgeCase}
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {/* Improvements */}
+      {improvements.length > 0 && (
+        <div>
+          <h4 className="mb-3 flex items-center gap-2 text-sm font-semibold uppercase tracking-wider text-cyan-300">
+            <span>✨</span> Improvements Applied
+          </h4>
+          <ul className="space-y-1.5">
+            {improvements.map((improvement, idx) => (
+              <li key={idx} className="text-sm text-slate-300">
+                • {improvement}
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {/* Severity Badge */}
+      {severity && (
+        <div className="pt-2">
+          <span
+            className={`inline-flex items-center gap-1.5 rounded-full border px-3 py-1 text-xs font-semibold uppercase tracking-wider ${severityColor}`}
+          >
+            <span>🛡️</span>
+            Severity: {severity}
+          </span>
+        </div>
+      )}
+    </div>
+  );
+}
+

frontend/components/tenant-heatmap.tsx

@@ -26,7 +26,7 @@ const DAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
 const HOURS = Array.from({ length: 24 }, (_, i) => i);
 
 export function TenantHeatmap({ days = 7 }: TenantHeatmapProps) {
-  const { tenantId, userRole } = useTenant();
+  const { tenantId, role } = useTenant();
   const [loading, setLoading] = useState(false);
   const [heatmapData, setHeatmapData] = useState<HeatmapData[]>([]);
   const [toolTrends, setToolTrends] = useState<ToolUsageTrend[]>([]);
@@ -44,7 +44,7 @@ export function TenantHeatmap({ days = 7 }: TenantHeatmapProps) {
           {
             headers: {
               "x-tenant-id": tenantId,
-              "x-user-role": userRole,
+              "x-user-role": role,
             },
           },
         );
@@ -61,7 +61,7 @@ export function TenantHeatmap({ days = 7 }: TenantHeatmapProps) {
           {
             headers: {
               "x-tenant-id": tenantId,
-              "x-user-role": userRole,
+              "x-user-role": role,
             },
           },
         );
@@ -77,14 +77,22 @@ export function TenantHeatmap({ days = 7 }: TenantHeatmapProps) {
         const activityByHour: Record<string, number> = {};
 
         // Group activities by hour and day
-        if (activityData.activities) {
+        if (activityData.activities && Array.isArray(activityData.activities)) {
           activityData.activities.forEach((activity: any) => {
-            const timestamp = new Date(activity.timestamp || activity.created_at);
-            const hour = timestamp.getHours();
-            const day = timestamp.getDay();
-            const key = `${day}-${hour}`;
-
-            activityByHour[key] = (activityByHour[key] || 0) + 1;
+            try {
+              const timestamp = new Date(activity.timestamp || activity.created_at);
+              // Check if date is valid
+              if (!isNaN(timestamp.getTime())) {
+                const hour = timestamp.getHours();
+                const day = timestamp.getDay();
+                const key = `${day}-${hour}`;
+
+                activityByHour[key] = (activityByHour[key] || 0) + 1;
+              }
+            } catch (e) {
+              // Skip invalid timestamps
+              console.warn("Invalid timestamp in activity:", activity);
+            }
           });
         }
 
@@ -117,13 +125,17 @@ export function TenantHeatmap({ days = 7 }: TenantHeatmapProps) {
         setToolTrends(trends.slice(0, 10)); // Top 10 tools
       } catch (err) {
         console.error("Failed to fetch heatmap data:", err);
+        // Set empty data on error to show empty state
+        setHeatmapData([]);
+        setToolTrends([]);
+        setMaxCount(1);
       } finally {
         setLoading(false);
       }
     }
 
     fetchHeatmapData();
-  }, [tenantId, userRole, days]);
+  }, [tenantId, role, days]);
 
   const getIntensity = (count: number) => {
     if (maxCount === 0) return 0;