feat: add workspace onboarding templates

docs/reference/api.md

@@ -121,6 +121,59 @@ filters:
 
 Audit details redact secret-like fields before they are stored.
 
+### Workspace Onboarding
+
+Workspace onboarding endpoints require administrator access and render/apply
+versioned onboarding templates for new client workspaces.
+
+#### List Onboarding Templates
+
+```text
+GET /onboarding/templates
+```
+
+Returns template metadata, variables, domain and mail-source templates,
+notification defaults, and operator checklist items.
+
+#### Preview Onboarding Plan
+
+```text
+POST /onboarding/preview
+```
+
+Request:
+
+```json
+{
+  "template_id": "standard_monitoring",
+  "workspace": {
+    "slug": "client-one",
+    "name": "Client One"
+  },
+  "variables": {
+    "domain": "example.com",
+    "report_mailbox": "dmarc@example.com",
+    "imap_server": "imap.example.com"
+  }
+}
+```
+
+Returns the rendered plan without writing to the database. Secret-like fields
+are redacted in the response.
+
+#### Apply Onboarding Plan
+
+```text
+POST /onboarding/apply
+```
+
+Applies the rendered plan by creating or reusing the workspace, adding missing
+domains and mail-source shells, seeding safe notification defaults, returning
+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`.
+
 ### Domains
 
 #### List Domains

docs/reference/workspaces.md

@@ -74,6 +74,32 @@ 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.
 
+## Onboarding Templates
+
+Workspace onboarding templates give MSP operators a repeatable way to create a
+new client workspace with minimal manual configuration. The template API can:
+
+- preview a rendered onboarding plan before anything is saved
+- create or reuse a workspace
+- seed monitored domains and manual DKIM selectors
+- seed disabled mail-source shells for IMAP, Gmail, or Microsoft 365
+- seed safe notification defaults without storing notification target secrets
+- return an operator checklist for DNS validation, mailbox connection, initial
+  import, and notification testing
+
+Available templates are exposed from `GET /api/v1/onboarding/templates`.
+Operators render a plan with `POST /api/v1/onboarding/preview` and apply it
+with `POST /api/v1/onboarding/apply`.
+
+The onboarding response and audit records redact secret-like fields, including
+passwords, OAuth secrets, tokens, and API keys. Existing domains and mail
+sources are treated idempotently; duplicate domains owned by another workspace
+are rejected to keep ownership unambiguous.
+
+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.
+
 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.