diff --git a/Roles-and-Permissions.-.md b/Roles-and-Permissions.-.md
index e69de29..0dfc01f 100644
--- a/Roles-and-Permissions.-.md
+++ b/Roles-and-Permissions.-.md
@@ -0,0 +1,222 @@
+# Roles and Permissions
+
+Aegis uses Role-Based Access Control (RBAC) with six roles organized in a hierarchy.
+Every authenticated request carries the user's role, which is checked against the
+required role for each endpoint.
+
+---
+
+## Role Hierarchy
+
+```
+admin
+  └─ red_lead / blue_lead
+        └─ red_tech / blue_tech
+              └─ viewer
+```
+
+Higher roles generally include the capabilities of lower roles, with some
+team-specific restrictions (e.g. a `red_lead` cannot perform `blue_lead` actions).
+
+> **Admin bypass**: `admin` ALWAYS passes any role check, regardless of which role
+> is required. There is no endpoint an admin cannot call.
+
+---
+
+## Role Descriptions
+
+### admin
+
+**Primary use case**: Platform administrator. Full system access.
+
+**Can do:**
+- Everything any other role can do
+- Create, update, deactivate, and delete users
+- View audit logs (`GET /api/v1/audit-logs`)
+- Delete snapshots (`DELETE /api/v1/snapshots/{id}`)
+- Delete alert rules
+- Trigger MITRE ATT&CK sync (`POST /api/v1/system/sync-mitre`)
+- Manage webhooks (`GET/POST/PATCH/DELETE /api/v1/webhooks`) — **admin only**
+- Set data classification on tests (`PATCH /api/v1/tests/{id}/classification`)
+- View scheduler status (`GET /api/v1/system/scheduler-status`)
+- Configure SSO (`PUT /api/v1/sso/config`)
+- Manage data sources (`POST/PATCH/DELETE /api/v1/data-sources`)
+- Complete campaigns (along with red_lead)
+
+**Cannot do:**
+- Be locked out — bypasses all role checks by design
+
+---
+
+### red_lead
+
+**Primary use case**: Red Team Lead. Manages the offensive side of operations.
+
+**Can do:**
+- Create, update, and delete tests (in `draft` or `rejected` state)
+- Create campaigns and complete them (`POST /campaigns/{id}/complete`)
+- Create test templates
+- Create and manage playbooks and lessons
+- Validate the red side of a test (`POST /tests/{id}/validate-red`)
+- Manage attack paths (including delete)
+- Create alert rules
+- Generate professional reports (PDF, DOCX, HTML)
+- Start test execution
+- Upload red evidence
+- Submit red assessment
+- All viewer capabilities
+
+**Cannot do:**
+- Access audit logs
+- Perform blue-side actions (validate-blue, submit-blue, update blue fields)
+- Delete snapshots
+- Sync MITRE data
+- Access or manage webhooks
+- Set data classification
+
+---
+
+### blue_lead
+
+**Primary use case**: Blue Team Lead. Manages the defensive side of operations.
+
+**Can do:**
+- Evaluate and validate the blue side of a test (`POST /tests/{id}/validate-blue`)
+- Validate blue side (`POST /tests/{id}/validate-blue`)
+- Manage detection assets and detection rules
+- Create playbooks and lessons
+- Generate a revalidation queue
+- Manage ownership of assets
+- Create alert rules
+- Generate professional reports (PDF, DOCX, HTML)
+- Upload blue evidence (in `blue_evaluating` state)
+- Submit blue assessment
+- All viewer capabilities
+
+**Cannot do:**
+- Complete campaigns (red_lead + admin only)
+- Start test execution (`POST /tests/{id}/start-execution`)
+- Validate the red side
+- Access audit logs
+- Delete snapshots
+- Sync MITRE data
+- Access or manage webhooks
+
+---
+
+### red_tech
+
+**Primary use case**: Red Team Technician. Executes attacks.
+
+**Can do:**
+- Start test execution (`POST /tests/{id}/start-execution`) — moves `draft` → `red_executing`
+- Update red-side fields (`PATCH /tests/{id}/red`): `tool_used`, `command_executed`, `output_observed`, `red_notes`, etc.
+- Upload red evidence files
+- Submit red assessment (`POST /tests/{id}/submit-red`) — moves `red_executing` → `blue_evaluating`
+- Pause and resume test timers
+- Create worklogs for tests
+- View all read-only data (same as viewer)
+
+**Cannot do:**
+- Create new tests
+- Create campaigns
+- Manage playbooks or lessons
+- Access webhooks, audit logs, or admin endpoints
+- Perform blue-side actions
+- Validate either side
+- Generate professional reports
+
+---
+
+### blue_tech
+
+**Primary use case**: Blue Team Technician. Evaluates detection.
+
+**Can do:**
+- Update blue-side fields (`PATCH /tests/{id}/blue`): `detection_result` (detected/not_detected/partial), `detection_notes`, `alert_fired`, `response_action`, etc.
+- Upload blue evidence files (only while test is in `blue_evaluating` state)
+- Submit blue assessment (`POST /tests/{id}/submit-blue`) — moves `blue_evaluating` → `in_review`
+- Evaluate detection rules (`POST /api/v1/detection-rules/evaluate`)
+- Create detection validations
+- Pause and resume test timers
+- Create worklogs for tests
+- View all read-only data (same as viewer)
+
+**Cannot do:**
+- Start test execution
+- Submit red assessment
+- Validate either side
+- Create tests, campaigns, playbooks, or lessons
+- Access webhooks, audit logs, or admin endpoints
+- Generate professional reports
+
+---
+
+### viewer
+
+**Primary use case**: Stakeholder, auditor, or report consumer. Read-only access plus report generation.
+
+**Can do:**
+- Read all entities: tests, techniques, campaigns, playbooks, lessons, coverage, snapshots, alerts, dashboards, detection lifecycle, scores, heatmap, threat actors, compliance, analytics
+- Generate professional reports: PDF, DOCX, HTML (all report types)
+- Mark own notifications as read
+
+**Cannot do:**
+- Create or modify any entity (no POST/PATCH/DELETE on data entities)
+- Upload evidence
+- Change test state
+- Manage users, webhooks, alert rules, playbooks, campaigns, or any configuration
+
+---
+
+## Access Matrix
+
+The table below shows key endpoints and which roles can call them.
+✅ = allowed, ❌ = forbidden, * = with restrictions (see notes)
+
+| Endpoint | admin | red_lead | blue_lead | red_tech | blue_tech | viewer |
+|----------|-------|----------|-----------|----------|-----------|--------|
+| POST /tests | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
+| PATCH /tests/{id} (general) | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
+| POST /tests/{id}/start-execution | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
+| PATCH /tests/{id}/red | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
+| POST /tests/{id}/submit-red | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
+| PATCH /tests/{id}/blue | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ |
+| POST /tests/{id}/submit-blue | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ |
+| POST /tests/{id}/validate-red | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
+| POST /tests/{id}/validate-blue | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
+| POST /tests/{id}/reopen | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
+| POST /tests/{id}/pause-timer | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
+| PATCH /tests/{id}/classification | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| POST /campaigns | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
+| POST /campaigns/{id}/complete | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
+| POST /campaigns/from-threat-actor/{id} | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
+| POST /knowledge/playbooks | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
+| GET /reports/generate/* | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
+| GET /audit-logs | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| ALL /webhooks | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| DELETE /snapshots/{id} | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| POST /system/sync-mitre | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| PUT /sso/config | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| PATCH /data-sources | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| GET /users (list) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| POST /users | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| PATCH /alerts/rules | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
+| POST /alerts/evaluate | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
+| GET /scores/organization | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| PATCH /scores/config | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+
+---
+
+## Notes on Role Enforcement
+
+1. **JWT carries the role**: The user's role is embedded in the JWT payload and
+   re-verified against the database on every request.
+2. **Admin bypass is unconditional**: The `require_role()` dependency immediately
+   returns if `current_user.role == "admin"`.
+3. **Resource ownership**: Some endpoints additionally check that the requesting
+   user owns the resource (e.g. API keys, worklogs, notifications). Admins bypass
+   ownership checks too.
+4. **must_change_password**: If this flag is set on the user record, all endpoints
+   return `403 PASSWORD_CHANGE_REQUIRED` until the password is changed via
+   `POST /api/v1/auth/change-password`.