feat: add workspace RBAC audit foundations

docs/reference/workspaces.md

@@ -29,6 +29,40 @@ Domain, mail-source, and user query helpers scope reads to a workspace by
 default. This prevents cross-tenant reads in new M15 surfaces and gives later
 RBAC work a single ownership field to enforce.
 
+## Roles And Permissions
+
+DMARQ defines these workspace roles as the RBAC vocabulary for MSP mode:
+
+| Role | Intended operator |
+|------|-------------------|
+| `workspace_owner` | Full workspace administrator |
+| `domain_admin` | Domain and mail-source administrator |
+| `operator` | Day-to-day operations and notification management |
+| `analyst` | Reporting and posture reader |
+| `auditor` | Audit and report reader |
+
+The role catalog is available from `GET /api/v1/audit/roles`. Current admin
+sessions and admin API keys map to `workspace_owner` until membership management
+screens are added.
+
+## Audit Logs
+
+The `workspace_audit_logs` table stores sanitized records for sensitive
+workspace actions. `GET /api/v1/audit/logs` returns recent audit events for the
+default workspace and can filter by `action` or `entity_type`.
+
+Current audit coverage includes:
+
+- API token creation and revocation
+- mail-source creation, update, deletion, enable/disable toggles, and OAuth
+  connect/disconnect actions
+- notification and forensic setting changes
+- webhook creation, update, disable, and test actions
+- manual DKIM selector add/remove actions
+
+Audit details redact secret-like fields such as passwords, OAuth tokens, API
+keys, and webhook signing secrets.
+
 ## Migration Story
 
 The migration creates the `workspaces` table, inserts the default workspace, and
@@ -37,6 +71,9 @@ mail-source tables. Nullable columns keep upgrades safe for older databases and
 for import paths that may be backfilled in stages; runtime helpers attach
 legacy rows to the default workspace when needed.
 
+The RBAC/audit migration adds `workspace_memberships` for role assignments and
+`workspace_audit_logs` for workspace-scoped change history.
+
 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.