update the readme file

README.md

@@ -222,6 +222,15 @@ PERMISSIONS = {
 - `/rag/delete*` - Requires `admin` or `owner` role
 - `/analytics/*` - All roles can view (viewer, editor, admin, owner)
 
+**Role Propagation:**
+The user role is automatically propagated through the entire request pipeline:
+1. Frontend sends `x-user-role` header
+2. Backend API route receives and validates role
+3. Role is passed to service layer (`process_ingestion()`, etc.)
+4. Service layer passes role to MCP clients
+5. MCP clients include role in payload to MCP server
+6. MCP server extracts role and enforces permissions
+
 **Example Request:**
 ```bash
 curl -X POST "http://localhost:8000/admin/rules" \
@@ -231,7 +240,10 @@ curl -X POST "http://localhost:8000/admin/rules" \
   -d '{"rule": "Do not share passwords"}'
 ```
 
-If the role lacks permission, the API returns `403 Forbidden` with a descriptive error message.
+If the role lacks permission, the API returns `403 Forbidden` with a descriptive error message that includes:
+- Which role was used
+- Which roles are allowed for the action
+- Instructions to change role in the UI
 
 ### Frontend RBAC
 
@@ -575,6 +587,9 @@ IntegraChat includes three powerful visualization components that provide real-t
 Most endpoints require:
 - `x-tenant-id`: Tenant identifier for multi-tenant isolation
 - `x-user-role`: Caller role for RBAC enforcement (`viewer`, `editor`, `admin`, or `owner`)
+  - **Important**: Role must be passed through the entire pipeline (UI → API → RAG Client → MCP Server)
+  - Role is automatically propagated from the frontend to backend API, then to RAG client, and finally to MCP server for permission checks
+  - If ingestion fails with permission errors, verify the role is set correctly in the UI and check backend logs for role propagation debug messages
 - `Content-Type: application/json`: For POST requests with JSON payloads
 
 ### Example Request
@@ -754,6 +769,8 @@ See `SUPABASE_SETUP.md` and `SUPABASE_MIGRATION_COMPLETE.md` for detailed instru
   - Check file size limits (default may be 10MB)
   - Verify file format is supported (PDF, DOCX, TXT, MD)
   - Ensure tenant_id is provided in request
+  - **Check user role**: Ingestion requires `editor`, `admin`, or `owner` role. If you see "Permission Denied (403)", change your role in the UI dropdown (top right) from "viewer" to "editor", "admin", or "owner"
+  - Verify `x-user-role` header is being sent correctly (check backend logs for debug messages)
   - Check backend logs for specific error messages
   - Verify PostgreSQL connection for RAG storage
 
@@ -871,6 +888,20 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Recent Enhancements
 
+### Role Propagation & Permission Handling (Latest)
+- **Fixed Role Propagation**: User role (`viewer`, `editor`, `admin`, `owner`) is now properly passed through the entire ingestion pipeline:
+  - UI sends role in `x-user-role` header
+  - Backend API route receives and validates role
+  - Role is passed to `process_ingestion()` service
+  - RAG client includes role in payload to MCP server
+  - MCP server uses role for permission checks
+- **Improved Error Handling**: Permission errors (403 Forbidden) now return clear, actionable error messages:
+  - Clear indication when role lacks required permissions
+  - Guidance on which roles can perform specific actions
+  - Instructions to change role in UI dropdown
+- **Debug Logging**: Added comprehensive debug logging to trace role values through the pipeline for troubleshooting
+- **Admin Question Handling**: Fixed "who is the admin" type questions to use RAG from knowledge base instead of generic LLM responses
+
 ### 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

backend/README.md

@@ -185,6 +185,22 @@ Every tool now returns strict JSON schemas for consistency:
 
 **Schema Definitions**: `backend/api/services/tool_metadata.py` contains `TOOL_OUTPUT_SCHEMAS` with validation functions.
 
+### Role Propagation & Permission Handling
+- **Fixed Role Propagation**: User role is now properly passed from API route → `process_ingestion()` → RAG client → MCP server
+  - `rag_client.ingest_with_metadata()` now accepts `user_role` parameter
+  - Role is included in payload sent to MCP server: `{"user_role": "owner", ...}`
+  - MCP server extracts role from payload via `build_tenant_context()` and uses it for permission checks
+- **Improved Error Handling**: 
+  - Permission errors (403) return clear messages with actionable guidance
+  - Error messages specify which roles are allowed for each action
+  - Frontend displays user-friendly error messages with instructions
+- **Debug Logging**: Added debug logging in route handlers and services to trace role values:
+  - Logs role received in route handler
+  - Logs role passed to process_ingestion
+  - Logs role sent to RAG client
+  - Logs role received by MCP server
+- **Admin Question Handling**: Fixed admin identity questions to prioritize RAG results from knowledge base
+
 ### UI Enhancements (app.py)
 - **Knowledge Base Library Tab**: 
   - Statistics cards showing document counts by type
@@ -347,6 +363,20 @@ Agents that speak the Model Context Protocol should connect to the `integrachat`
 - **Ensure knowledge base content exists**: Questions like "who is the admin" require relevant content in the knowledge base
 - **Pattern matching**: The tool selector automatically triggers RAG for patterns like "admin", "who is", "what is", but semantic similarity also plays a role
 
+### Document Ingestion Permission Errors
+- **403 Forbidden**: If you see "Role 'viewer' is not permitted to perform 'ingest_documents'":
+  - Change your role in the UI dropdown (top right) from "viewer" to "editor", "admin", or "owner"
+  - Verify `x-user-role` header is being sent correctly (check backend logs for `🔍 DEBUG:` messages)
+  - Check that role is being propagated through the pipeline: route handler → process_ingestion → RAG client → MCP server
+  - Review debug logs to see where role might be getting lost or defaulting to "viewer"
+- **Role Propagation**: The role must flow through:
+  1. UI sends `x-user-role` header
+  2. Route handler receives it as `x_user_role` parameter
+  3. Route handler passes it to `process_ingestion(user_role=...)`
+  4. `process_ingestion` passes it to `rag_client.ingest_with_metadata(user_role=...)`
+  5. RAG client includes it in payload: `{"user_role": "...", ...}`
+  6. MCP server extracts it via `build_tenant_context()` and uses for permission checks
+
 ### Document Deletion Issues
 - **404 Not Found**: Verify the document_id exists and belongs to the correct tenant
 - **Tenant ID mismatch**: The system normalizes tenant IDs, but ensure you're using the same tenant_id format as when documents were ingested