update the readme file

README.md

@@ -91,6 +91,7 @@ Then access:
   - Regex-based red-flag pattern matching with severity levels (low/medium/high/critical)
   - Automatic admin alerts for violations
   - **LLM-Enhanced Rules**: Rules are automatically analyzed and enhanced to identify edge cases, improve regex patterns, and suggest appropriate severity levels
+  - **LLM-Guided Rule Explanations**: Automatic generation of human-readable explanations, concrete examples, and missing pattern suggestions. Includes intelligent fallback when LLM is unavailable - uses keyword extraction to provide useful explanations even during timeouts
   - **File Upload Support**: Upload rules from TXT, PDF, DOC, or DOCX files with drag-and-drop interface
   - **Chunk Processing**: Large rule sets processed in manageable chunks (5 rules at a time) to prevent timeouts
   - **Rule-Based Behavior Control**: Rules checked FIRST - brief response rules return quick answers, blocking rules prevent requests
@@ -114,7 +115,7 @@ Then access:
 ### Enterprise Features
 
 - 🔍 **Regex-Based Red-Flag Detection** – Support for complex regex patterns with keyword fallback and semantic scoring
-- 🤖 **LLM-Enhanced Rule Management** – Rules automatically enhanced by LLM to identify edge cases, improve patterns, and suggest severity levels
+- 🤖 **LLM-Enhanced Rule Management** – Rules automatically enhanced by LLM to identify edge cases, improve patterns, and suggest severity levels. Includes intelligent fallback explanations when LLM is unavailable - uses keyword extraction to generate useful explanations, examples, and pattern suggestions even during timeouts
 - 📄 **File Upload & Drag-and-Drop** – Upload rules from files (TXT, PDF, DOC, DOCX) with intuitive drag-and-drop interface
 - ⚡ **Chunk-Wise Processing** – Large rule sets processed in chunks to prevent timeouts and ensure reliable processing
 - 📈 **Real-Time Analytics Dashboard** – Per-tenant analytics with configurable time windows (7, 30, 90 days)
@@ -869,6 +870,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 ### Admin Rules System (Latest)
 - **File Upload Support**: Upload rules from TXT, PDF, DOC, DOCX files with drag-and-drop interface
 - **LLM Enhancement**: Automatic rule enhancement identifies edge cases, improves regex patterns, and suggests severity levels
+- **Intelligent Fallback Explanations**: When LLM enhancement times out or fails, the system automatically generates basic explanations using keyword extraction, providing useful examples and pattern suggestions without requiring LLM availability
 - **Chunk Processing**: Large rule sets processed in chunks of 5 to prevent timeouts (handles 100+ rules efficiently)
 - **Comment Filtering**: Comment lines (starting with #) automatically ignored when uploading rules
 - **Rule-First Processing**: Admin rules checked before intent classification - enables behavior control (brief responses vs blocking)

backend/README.md

@@ -161,6 +161,21 @@ Use the helper scripts in the repo root when validating backend changes:
   - Improved error handling and status messages
   - Responsive layout with proper component scaling
 
+### LLM-Guided Rule Explanation
+
+The rule enhancement system includes intelligent fallback mechanisms:
+
+- **LLM Enhancement**: When available, rules are enhanced with comprehensive explanations, examples, missing patterns, edge cases, and improvements
+- **Intelligent Fallback**: When LLM times out or fails, the system automatically generates basic explanations using keyword extraction:
+  - Detects keywords (password, API key, credit card, sensitive data, etc.)
+  - Generates contextual explanations based on detected keywords
+  - Provides relevant examples (5-8 examples) based on rule type
+  - Suggests missing patterns (3-5 suggestions) for rule improvement
+- **Timeout Protection**: 30-second timeout per rule with graceful fallback
+- **Chunk Processing**: Bulk rule processing handles failures gracefully - one rule failure doesn't block others
+
+This ensures users always receive useful rule explanations even when the LLM service is unavailable or slow.
+
 ### Real-Time Visualization Components (Next.js Frontend)
 
 The Next.js frontend includes three powerful visualization components:

frontend/README.md

@@ -90,6 +90,20 @@ The frontend includes three powerful visualization components:
 - **Per-tool usage trends** with visual bar charts
 - **Access**: All roles can view analytics (viewer, editor, admin, owner)
 
+### Admin Rules Page (`/admin-rules`)
+- **Rule management** with bulk upload and individual rule deletion
+- **File upload support** for TXT, PDF, DOC, DOCX, MD files with drag-and-drop
+- **LLM-Guided Rule Explanations**:
+  - Automatic generation of human-readable explanations
+  - Concrete examples of what would trigger the rule
+  - Missing pattern suggestions for rule improvement
+  - Edge cases and improvements identified by LLM
+  - **Intelligent fallback**: When LLM times out, uses keyword extraction to generate useful explanations, examples, and suggestions
+- **Expandable explanations** with "Explain" button for each rule
+- **Auto-expand** for newly added rules with explanations
+- **Role-based access**: Requires Admin or Owner role to manage rules
+- **Real-time updates** with refresh functionality
+
 ### Components
 
 - `chat-panel.tsx` - Real-time chat interface with streaming responses and visualization integration
@@ -102,6 +116,8 @@ The frontend includes three powerful visualization components:
 - `reasoning-visualizer.tsx` - Real-time reasoning path visualizer component
 - `tool-timeline.tsx` - Tool invocation timeline component
 - `tenant-heatmap.tsx` - Tenant activity heatmap component
+- `rule-explanation.tsx` - LLM-generated rule explanation component with examples and pattern suggestions
+- `admin-rules-panel.tsx` - Admin rules management panel component
 
 ## Deploy