feat: add MSP workspace operator views

docs/reference/api.md

@@ -174,6 +174,46 @@ the operator checklist, and writing a sanitized workspace audit event.
 Existing domains and mail sources are not duplicated. Existing notification
 settings are preserved unless `overwrite_existing` is set to `true`.
 
+### MSP Operator Views
+
+#### List Workspace Operator Summaries
+
+```text
+GET /operator/workspaces
+```
+
+Returns safe cross-workspace summaries for MSP operators: workspace identity,
+health status, domain/mail-source counts, latest import status, active alert
+count, recent drift event count, aggregate report count, and retention controls.
+The endpoint does not return raw report records.
+
+#### Get One Workspace Summary
+
+```text
+GET /operator/workspaces/{workspace_id}
+```
+
+Returns the same operator summary for a single workspace.
+
+#### Update Workspace Retention
+
+```text
+PUT /operator/workspaces/{workspace_id}/retention
+```
+
+Request:
+
+```json
+{
+  "aggregate_reports_days": 730,
+  "forensic_reports_days": 120,
+  "tls_reports_days": 365
+}
+```
+
+Updates workspace retention controls and writes a sanitized
+`workspace.retention_updated` audit event.
+
 ### Domains
 
 #### List Domains

docs/reference/database.md

@@ -25,6 +25,9 @@ workspace during migration.
 | name | VARCHAR | Display name |
 | description | TEXT | Optional operator-facing description |
 | active | BOOLEAN | Whether the workspace can be used |
+| report_retention_days | INTEGER | Aggregate DMARC report retention target |
+| forensic_retention_days | INTEGER | Forensic report retention target |
+| tls_report_retention_days | INTEGER | SMTP TLS report retention target |
 | created_at | TIMESTAMP | When the workspace was created |
 | updated_at | TIMESTAMP | When the workspace was last updated |
 

docs/reference/workspaces.md

@@ -100,6 +100,36 @@ Notification defaults currently seed the existing notification settings table.
 They intentionally avoid Apprise target URLs, so operators still add and test
 delivery targets explicitly after onboarding.
 
+## MSP Operator Views
+
+MSP operator endpoints provide cross-workspace summaries without returning raw
+DMARC report rows across tenant boundaries. `GET /api/v1/operator/workspaces`
+returns one summary per active workspace:
+
+- workspace identity and active state
+- health status derived from domains, enabled mail sources, active alerts,
+  recent failed imports, and missing import history
+- domain counts and names
+- mail-source counts and the most recent import status
+- aggregate report counts
+- current retention controls
+- recent workspace audit events as drift indicators
+
+`GET /api/v1/operator/workspaces/{workspace_id}` returns the same summary for
+one workspace.
+
+Workspace retention controls are stored on the workspace row:
+
+| Field | Purpose | Default |
+| --- | --- | --- |
+| `report_retention_days` | Aggregate DMARC report retention target | 400 |
+| `forensic_retention_days` | Forensic report retention target | 90 |
+| `tls_report_retention_days` | SMTP TLS report retention target | 400 |
+
+Operators can update these controls with
+`PUT /api/v1/operator/workspaces/{workspace_id}/retention`. Updates are written
+to the workspace audit log as `workspace.retention_updated`.
+
 The current implementation keeps domain names globally unique. That matches the
 existing single-domain ownership model and avoids ambiguous ownership while MSP
 RBAC and onboarding controls are built out.