update the readme file

README.md

@@ -71,8 +71,10 @@ Then access:
 - **Gradio UI**: `http://localhost:7860`
 - **FastAPI Docs**: `http://localhost:8000/docs`
 - **Next.js Frontend** (optional): `cd frontend && npm install && npm run dev` → `http://localhost:3000`
+  - Use the role selector in the header to switch between viewer, editor, admin, or owner roles
+  - UI automatically shows/hides features based on selected role
 
-> **Security Note:** REST requests that hit protected endpoints must include both `x-tenant-id` and `x-user-role` headers. Roles (`viewer`, `editor`, `admin`, `owner`) determine which actions—such as document ingestion, rule uploads, or analytics access—the caller may perform.
+> **Security Note:** REST requests that hit protected endpoints must include both `x-tenant-id` and `x-user-role` headers. Roles (`viewer`, `editor`, `admin`, `owner`) determine which actions—such as document ingestion, rule uploads, or analytics access—the caller may perform. The Next.js frontend automatically sends the selected role in all API requests.
 
 ---
 
@@ -102,6 +104,7 @@ Then access:
   - LLM token logs and latency metrics
 - 🌐 **Live Web Search** – Google Programmable Search (Custom Search API) with tenant-aware MCP tooling
 - 🏢 **Multi-Tenant Isolation** – Complete tenant isolation with centralized tenant ID management; backend enforces strict isolation for chat, ingestion, and admin ops
+- 🔐 **Fine-Grained Role-Based Access Control (RBAC)** – Four-tier role system (viewer, editor, admin, owner) with dynamic UI visibility and backend permission enforcement; frontend automatically shows/hides features based on role
 - 🔄 **Intelligent Multi-Tool Orchestration** – MCP agent orchestrator autonomously selects optimal tool chains (RAG + Web + LLM, etc.) based on query intent and context
 - ⚡ **Robust Error Handling** – Structured error responses, retry mechanisms, and graceful fallbacks (e.g., if RAG fails → fallback to LLM-only)
 - 📡 **Streaming Responses** – Chat responses stream word-by-word using Server-Sent Events (SSE) for real-time user experience
@@ -147,6 +150,116 @@ Subsequent tool calls with the same `session_id` will receive a `memory` field c
 
 ---
 
+## Role-Based Access Control (RBAC)
+
+IntegraChat implements fine-grained role-based access control (RBAC) for both backend API endpoints and frontend UI. This ensures that users only see and can access features appropriate for their role level.
+
+### Roles
+
+The system supports four roles with increasing privileges:
+
+1. **viewer** (default) - Basic read-only access
+   - Can use chat functionality
+   - Cannot ingest documents
+   - Cannot delete documents
+   - Cannot view analytics
+   - Cannot manage admin rules
+
+2. **editor** - Content management access
+   - Can use chat functionality
+   - ✅ Can ingest documents (upload, paste, URLs, files)
+   - ❌ Cannot delete documents
+   - ❌ Cannot view analytics
+   - ❌ Cannot manage admin rules
+
+3. **admin** - Administrative access
+   - Can use chat functionality
+   - ✅ Can ingest documents
+   - ✅ Can delete documents
+   - ✅ Can view analytics
+   - ✅ Can manage admin rules
+
+4. **owner** - Full system access
+   - Same permissions as admin (highest privilege level)
+
+### Permission Matrix
+
+| Action | viewer | editor | admin | owner |
+|--------|--------|--------|-------|-------|
+| Chat Bot | ✅ | ✅ | ✅ | ✅ |
+| Ingest Documents | ❌ | ✅ | ✅ | ✅ |
+| Delete Documents | ❌ | ❌ | ✅ | ✅ |
+| View Analytics | ❌ | ❌ | ✅ | ✅ |
+| Manage Rules | ❌ | ❌ | ✅ | ✅ |
+
+### Backend RBAC
+
+Backend API endpoints enforce RBAC through the `x-user-role` header:
+
+```python
+# Permission matrix in backend/mcp_server/common/access_control.py
+PERMISSIONS = {
+    "manage_rules": {"owner", "admin"},
+    "ingest_documents": {"owner", "admin", "editor"},
+    "delete_documents": {"owner", "admin"},
+    "view_analytics": {"owner", "admin"},
+}
+```
+
+**Protected Endpoints:**
+- `/admin/rules` - Requires `admin` or `owner` role
+- `/rag/ingest*` - Requires `editor`, `admin`, or `owner` role
+- `/rag/delete*` - Requires `admin` or `owner` role
+- `/analytics/*` - Requires `admin` or `owner` role
+
+**Example Request:**
+```bash
+curl -X POST "http://localhost:8000/admin/rules" \
+  -H "Content-Type: application/json" \
+  -H "x-tenant-id: tenant123" \
+  -H "x-user-role: admin" \
+  -d '{"rule": "Do not share passwords"}'
+```
+
+If the role lacks permission, the API returns `403 Forbidden` with a descriptive error message.
+
+### Frontend RBAC
+
+The frontend UI dynamically shows/hides features based on the selected role:
+
+**Role Selector:**
+- Located in the header navigation
+- Dropdown to switch between roles (viewer, editor, admin, owner)
+- Role is persisted in localStorage
+- Changes take effect immediately across all pages
+
+**Conditional UI Visibility:**
+- **Navigation Links**: Only relevant links shown (e.g., editor doesn't see "Analytics" or "Admin Rules")
+- **Page Sections**: Entire sections hidden if user lacks permission
+- **Action Buttons**: Delete buttons hidden for editor role
+- **Access Denied Pages**: Friendly error messages when accessing restricted routes
+
+**Protected Routes:**
+- `/ingestion` - Editor, Admin, Owner only
+- `/analytics` - Admin, Owner only
+- `/admin-rules` - Admin, Owner only
+
+**Implementation:**
+- Permission utilities in `frontend/lib/permissions.ts`
+- Conditional rendering in components based on role
+- Access denied pages with clear messaging
+
+### Using RBAC
+
+1. **Change Role**: Use the role dropdown in the header to switch roles
+2. **Verify Permissions**: UI automatically updates to show only permitted features
+3. **API Requests**: Role is automatically sent as `x-user-role` header
+4. **Error Handling**: Access denied pages guide users on required roles
+
+**Note**: Role changes are immediate and affect both UI visibility and API permissions. The role persists across page refreshes via localStorage.
+
+---
+
 ## Installation & Setup
 
 ### Prerequisites