diff --git a/API-Reference.-.md b/API-Reference.-.md
index e69de29..1a1b605 100644
--- a/API-Reference.-.md
+++ b/API-Reference.-.md
@@ -0,0 +1,336 @@
+# API Reference
+
+All endpoints are prefixed with `/api/v1/`. Authentication via cookie `aegis_token` or
+`Authorization: Bearer <token>`. Role abbreviations: A=admin, RL=red_lead, BL=blue_lead,
+RT=red_tech, BT=blue_tech, V=viewer, Any=all authenticated.
+
+---
+
+## Auth — /api/v1/auth
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | /auth/login | Public | Login with username+password (form-encoded). Sets `aegis_token` cookie. |
+| POST | /auth/logout | Any | Revokes token (adds jti to Redis blacklist). Clears cookie. |
+| GET | /auth/me | Any | Returns current user profile + role. |
+| POST | /auth/change-password | Any | Change own password. Required if `must_change_password=true`. |
+
+---
+
+## Users — /api/v1/users
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /users | A | List all users (paginated). |
+| POST | /users | A | Create a new user. Sets `must_change_password=true`. |
+| GET | /users/{id} | A | Get user by ID. |
+| PATCH | /users/{id} | A | Update user (role, is_active, display_name, etc.). |
+| DELETE | /users/{id} | A | Deactivate (soft-delete) a user. |
+| GET | /users/me | Any | Get own profile. |
+| PATCH | /users/me/preferences | Any | Update own UI preferences (theme, notifications, etc.). |
+
+---
+
+## Techniques — /api/v1/techniques
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /techniques | Any | List techniques. Query: tactic_id, platform, coverage_status, search. |
+| GET | /techniques/{mitre_id} | Any | Get technique by MITRE ID (e.g. T1059.001). |
+| POST | /techniques | A | Create a custom technique (non-MITRE). |
+| PATCH | /techniques/{mitre_id} | A | Update technique metadata. |
+| PATCH | /techniques/{mitre_id}/review | RL,BL,A | Mark technique as needing review. |
+| GET | /techniques/{mitre_id}/d3fend | Any | D3FEND countermeasure mappings for this technique. |
+
+---
+
+## Tests — /api/v1/tests
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /tests | Any | List tests. Filters: state, technique_id, campaign_id, assigned_to. |
+| POST | /tests | RL,BL,A | Create a new test in draft state. |
+| POST | /tests/from-template | RL,BL,A | Create test(s) from a saved template. |
+| GET | /tests/{id} | Any | Get full test detail including all fields. |
+| PATCH | /tests/{id} | RL,BL,A | Update general fields (title, objective, technique, etc.). Draft/rejected only. |
+| PATCH | /tests/{id}/classification | A | Set data_classification (confidential, restricted, etc.). |
+| PATCH | /tests/{id}/red | RL,RT,A | Update red-side fields. State: red_executing. |
+| PATCH | /tests/{id}/blue | BL,BT,A | Update blue-side fields. State: blue_evaluating. |
+| POST | /tests/{id}/start-execution | RL,RT,A | Transition draft → red_executing. |
+| POST | /tests/{id}/submit-red | RL,RT,A | Transition red_executing → blue_evaluating. |
+| POST | /tests/{id}/submit-blue | BL,BT,A | Transition blue_evaluating → in_review. |
+| POST | /tests/{id}/validate-red | RL,A | Approve/reject red side. State: in_review. |
+| POST | /tests/{id}/validate-blue | BL,A | Approve/reject blue side. State: in_review. |
+| POST | /tests/{id}/reopen | RL,BL,A | Transition rejected → draft. |
+| POST | /tests/{id}/pause-timer | All except V | Pause elapsed time counter. |
+| POST | /tests/{id}/resume-timer | All except V | Resume elapsed time counter. |
+| PATCH | /tests/{id}/remediation | RL,BL,A | Update remediation status/notes (any state post-review). |
+| GET | /tests/{id}/timeline | Any | Full audit trail of state changes and actions. |
+| GET | /tests/{id}/retest-chain | Any | All tests in this retest lineage. |
+
+---
+
+## Evidence — /api/v1/tests/{id}/evidence & /api/v1/evidence
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | /tests/{id}/evidence | Role-dependent* | Upload evidence file. team=red or team=blue. |
+| GET | /tests/{id}/evidence | Any | List all evidence files for a test. |
+| GET | /evidence/{id} | Any | Get evidence metadata. |
+| GET | /evidence/{id}/download | Any | Download evidence file from MinIO (signed URL or stream). |
+| DELETE | /evidence/{id} | Own or RL,BL,A | Delete evidence file. |
+
+*red evidence: RL, RT, A | blue evidence: BL, BT, A. State restrictions apply (see [Test-Lifecycle](Test-Lifecycle)).
+
+---
+
+## Campaigns — /api/v1/campaigns
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /campaigns | Any | List campaigns. Filters: status, type, date range. |
+| POST | /campaigns | RL,BL,A | Create a new campaign. |
+| GET | /campaigns/{id} | Any | Get campaign detail. |
+| PATCH | /campaigns/{id} | RL,BL,A | Update campaign metadata. |
+| POST | /campaigns/{id}/tests | RL,BL,A | Add a test to a campaign. |
+| DELETE | /campaigns/{id}/tests/{ctid} | RL,BL,A | Remove a test from a campaign. |
+| POST | /campaigns/{id}/activate | RL,BL,A | Transition draft → active. |
+| POST | /campaigns/{id}/complete | RL,A | Transition active → completed. |
+| GET | /campaigns/{id}/progress | Any | Count validated/total tests in campaign. |
+| POST | /campaigns/from-threat-actor/{actor_id} | RL,BL,A | Auto-create campaign + tests from threat actor profile. |
+| PATCH | /campaigns/{id}/schedule | RL,BL,A | Set start_date / end_date. |
+| GET | /campaigns/{id}/history | Any | Campaign state change history. |
+
+---
+
+## Attack Paths — /api/v1/attack-paths
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /attack-paths | Any | List attack paths. |
+| POST | /attack-paths | All except V | Create an attack path (sequence of techniques). |
+| GET | /attack-paths/{id} | Any | Get attack path detail. |
+| PATCH | /attack-paths/{id} | All except V | Update attack path metadata. |
+| DELETE | /attack-paths/{id} | RL,BL,A | Delete attack path. |
+| POST | /attack-paths/{id}/steps | All except V | Add a step (technique) to attack path. |
+| DELETE | /attack-paths/{id}/steps/{sid} | All except V | Remove a step. |
+| POST | /attack-paths/{id}/executions | All except V | Start an execution of the attack path. |
+| POST | /executions/{id}/start | All except V | Begin execution. |
+| POST | /executions/{id}/steps/{sid} | All except V | Record step outcome. |
+| POST | /executions/{id}/complete | All except V | Mark execution complete. |
+| POST | /executions/{id}/abort | RL,BL,A | Abort execution. |
+
+---
+
+## Knowledge — /api/v1/knowledge
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /knowledge/playbooks | Any | List playbooks. Filter by technique, type. |
+| POST | /knowledge/playbooks | RL,BL,A | Create a playbook. |
+| GET | /knowledge/playbooks/{id} | Any | Get playbook + versions list. |
+| PATCH | /knowledge/playbooks/{id} | RL,BL,A | Update playbook (creates version snapshot). |
+| DELETE | /knowledge/playbooks/{id} | RL,BL,A | Delete playbook. |
+| GET | /knowledge/playbooks/{id}/versions | Any | List all versions of a playbook. |
+| POST | /knowledge/playbooks/{id}/restore/{version} | RL,BL,A | Restore a previous version. |
+| GET | /knowledge/lessons | Any | List lessons learned. Filter by severity, technique. |
+| POST | /knowledge/lessons | RL,BL,A | Create a lesson learned. |
+| GET | /knowledge/lessons/{id} | Any | Get lesson detail. |
+| PATCH | /knowledge/lessons/{id} | RL,BL,A | Update lesson. |
+| DELETE | /knowledge/lessons/{id} | RL,BL,A | Delete lesson. |
+| GET | /knowledge/stats | Any | Summary: playbooks by type, lessons by severity. |
+
+---
+
+## Ownership — /api/v1/ownership
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /ownership/assignments | Any | Technique-to-owner assignments. |
+| POST | /ownership/assignments | RL,BL,A | Assign technique ownership. |
+| PATCH | /ownership/assignments/{id} | RL,BL,A | Update assignment. |
+| DELETE | /ownership/assignments/{id} | RL,BL,A | Remove assignment. |
+| GET | /ownership/assets | Any | Asset ownership list. |
+| POST | /ownership/assets | BL,A | Create asset ownership record. |
+| GET | /ownership/revalidation-queue | BL,A | Techniques requiring revalidation. |
+| POST | /ownership/revalidation-queue/generate | BL,A | Generate revalidation queue from infrastructure changes. |
+
+---
+
+## Risk — /api/v1/risk
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | /risk/compute | RL,BL,A | Trigger risk recomputation. |
+| GET | /risk/profiles | Any | Risk profile per technique. |
+| GET | /risk/matrix | Any | Risk matrix (impact × coverage). |
+| GET | /risk/summary | Any | Aggregate risk numbers. |
+| GET | /risk/recommendations | Any | Prioritized list of techniques to test next. |
+| GET | /risk/top | Any | Top N highest-risk uncovered techniques. ?limit=N |
+
+---
+
+## Alerts — /api/v1/alerts
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | /alerts/evaluate | RL,BL,A | Manually trigger evaluation of all enabled rules. |
+| GET | /alerts/summary | Any | Alert counts by status, severity, rule type. |
+| GET | /alerts | Any | List alert instances. Filters: status, severity, rule_type. |
+| GET | /alerts/{id} | Any | Get alert instance detail. |
+| POST | /alerts/{id}/acknowledge | RL,BL,A | Acknowledge an alert. |
+| POST | /alerts/{id}/resolve | RL,BL,A | Resolve an alert. |
+| POST | /alerts/{id}/dismiss | RL,BL,A | Dismiss an alert. |
+| GET | /alerts/rules | Any | List alert rules. |
+| POST | /alerts/rules | RL,BL,A | Create an alert rule. |
+| GET | /alerts/rules/{id} | Any | Get rule detail. |
+| PATCH | /alerts/rules/{id} | RL,BL,A | Update rule. |
+| DELETE | /alerts/rules/{id} | A | Delete rule. |
+
+---
+
+## Dashboard — /api/v1/dashboard
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /dashboard/kpis | Any | Key metrics: total techniques, covered %, tests, campaigns. |
+| GET | /dashboard/executive | Any | Narrative executive summary. |
+| GET | /dashboard/coverage-by-tactic | Any | Coverage breakdown per tactic. |
+| GET | /dashboard/posture-history | Any | Historical coverage trend data. |
+| GET | /dashboard/activity | Any | Recent activity feed (tests, campaigns, validations). |
+| POST | /dashboard/posture-snapshot | RL,BL,A | Create an immediate posture snapshot. |
+
+---
+
+## Snapshots — /api/v1/snapshots
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /snapshots | Any | List snapshots (paginated). |
+| POST | /snapshots | RL,BL,A | Create a manual snapshot. |
+| GET | /snapshots/{id} | Any | Get snapshot detail. |
+| DELETE | /snapshots/{id} | A | Delete a snapshot. |
+| GET | /snapshots/evolution | Any | Trend data: coverage over time. |
+| GET | /snapshots/compare | Any | Diff two snapshots. Query: ?a=<id>&b=<id> |
+
+---
+
+## Reports — /api/v1/reports
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /reports/coverage-summary | Any | Coverage data as JSON. |
+| GET | /reports/coverage-csv | Any | Coverage data as CSV download. |
+| GET | /reports/test-results | Any | Test results data as JSON. |
+| GET | /reports/remediation-status | Any | Remediation tracking data. |
+| GET | /reports/generate/purple-campaign/{id} | RL,BL,A,V | Full campaign report. ?format=pdf|docx|html |
+| GET | /reports/generate/coverage-summary | RL,BL,A,V | Coverage status report. |
+| GET | /reports/generate/executive-summary | RL,BL,A,V | Executive briefing document. |
+| GET | /reports/generate/quarterly-summary | RL,BL,A,V | Quarterly review report. |
+| GET | /reports/generate/technique/{id} | RL,BL,A,V | Per-technique detail report. |
+
+---
+
+## Detection Lifecycle — /api/v1/detection-lifecycle
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /detection-lifecycle/assets | Any | List detection assets. |
+| POST | /detection-lifecycle/assets | BL,A | Create a detection asset. |
+| GET | /detection-lifecycle/assets/{id} | Any | Get asset detail. |
+| PATCH | /detection-lifecycle/assets/{id} | BL,A | Update asset. |
+| DELETE | /detection-lifecycle/assets/{id} | BL,A | Delete asset. |
+| POST | /detection-lifecycle/assets/{id}/techniques/{tid} | BL,A | Link asset to technique. |
+| DELETE | /detection-lifecycle/assets/{id}/techniques/{tid} | BL,A | Unlink asset from technique. |
+| GET | /detection-lifecycle/validations | Any | List detection validations. |
+| POST | /detection-lifecycle/validations | BL,A | Create a validation record. |
+| POST | /detection-lifecycle/validations/{id}/invalidate | BL,A | Invalidate (revoke) a validation. |
+| GET | /detection-lifecycle/infrastructure-changes | Any | List infrastructure change records. |
+| POST | /detection-lifecycle/infrastructure-changes | BL,A | Record an infrastructure change. |
+| GET | /detection-lifecycle/dashboard | Any | Detection confidence per technique. |
+
+---
+
+## Detection Rules — /api/v1/detection-rules
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /detection-rules | Any | List detection rules. |
+| POST | /detection-rules | BL,A | Create detection rule. |
+| GET | /detection-rules/{id} | Any | Get rule detail. |
+| PATCH | /detection-rules/{id} | BL,A | Update rule. |
+| DELETE | /detection-rules/{id} | BL,A | Delete rule. |
+| POST | /detection-rules/evaluate | BL,BT,A | Record rule triggered/not-triggered for a test. |
+
+---
+
+## Test Templates — /api/v1/test-templates
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /test-templates | Any | List templates. |
+| POST | /test-templates | RL,BL,A | Create template from existing test or from scratch. |
+| GET | /test-templates/{id} | Any | Get template detail. |
+| PATCH | /test-templates/{id} | RL,BL,A | Update template. |
+| DELETE | /test-templates/{id} | RL,BL,A | Delete template. |
+
+---
+
+## Webhooks — /api/v1/webhooks (admin only)
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /webhooks | A | List configured webhooks. |
+| POST | /webhooks | A | Create a webhook (URL, events, secret). |
+| GET | /webhooks/{id} | A | Get webhook detail. |
+| PATCH | /webhooks/{id} | A | Update webhook. |
+| DELETE | /webhooks/{id} | A | Delete webhook. |
+| POST | /webhooks/{id}/test | A | Send a test event to the webhook URL. |
+
+Webhook events: `test.validated`, `test.state_changed`, `campaign.completed`,
+`alert.fired`, `coverage.changed`.
+
+SSRF protection: webhook URLs are validated against private IP ranges before saving.
+
+---
+
+## API Keys — /api/v1/api-keys
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /api-keys | Any | List own API keys. |
+| POST | /api-keys | Any | Create a new API key. Scope: read/write/admin. |
+| DELETE | /api-keys/{id} | Own or A | Revoke an API key. |
+
+Keys are prefixed `aegis_` and passed as `Authorization: Bearer aegis_<hex>`.
+
+---
+
+## SSO — /api/v1/sso
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /sso/status | Any | Whether SSO is configured and enabled. |
+| PUT | /sso/config | A | Configure SAML 2.0 SSO settings. |
+| GET | /sso/login | Public | Initiate SAML login redirect. |
+| POST | /sso/callback | Public | SAML assertion callback. |
+| GET | /sso/metadata | Public | Service provider metadata XML. |
+
+---
+
+## Other Modules
+
+| Module | Path prefix | Auth | Notes |
+|--------|-------------|------|-------|
+| Notifications | /notifications | Any (own) | GET list, PATCH mark-read |
+| Audit Logs | /audit-logs | A | GET with filters |
+| Jira | /jira | RL,BL,A | sync, issues |
+| Threat Actors | /threat-actors | Any GET, RL,BL,A manage | |
+| Compliance | /compliance | Any | frameworks, controls, gaps |
+| Analytics | /analytics | Any | trend analytics |
+| Heatmap | /heatmap | Any | Coverage matrix |
+| Scores | /scores | Any GET; A for config PATCH | |
+| Worklogs | /worklogs | Any create; own or A to read | |
+| OSINT | /osint | RL,BL,A | |
+| Data Sources | /data-sources | Any GET; A manage | |
+| System | /system | A (scheduler, sync); Public (health) | |