feat: implement onboarding journeys

docs/contracts.md

@@ -14,6 +14,12 @@ HTTP or RPC adapters should preserve these operation names:
   `claim_prepared_account`
 - `register_access_profile`, `list_access_profiles`, `select_active_hat`,
   `export_access_control_facts`, `access_profile_diagnostics`
+- `register_welcome_protocol`, `list_welcome_protocols`,
+  `start_onboarding_journey`, `start_onboarding_for_registration`,
+  `start_onboarding_for_prepared_account`, `progress_onboarding_step`,
+  `complete_onboarding_step`, `skip_onboarding_step`,
+  `fail_onboarding_step`, `resume_onboarding_journey`,
+  `onboarding_diagnostics`
 - `me`, `create_user`, `set_account_status`, `link_identity`
 - `resolve_tenant_context`, `set_tenant_account_status`, `add_membership`,
   `tenant_diagnostics`
@@ -86,14 +92,33 @@ Access-profile diagnostics report counts, factor requirement types, and
 approval-required issues without exposing profile default values, projection
 claim values, or raw factor values.
 
+## Onboarding Journey Contract
+
+Welcome protocols are tenant-scoped onboarding templates. They can match
+registration completion, prepared-account claims, invitations, access-profile
+events, or manual starts by trigger type and optional context keys.
+
+Onboarding journeys are persisted user state. They track protocol, source
+event, trigger type, ordered steps, task references, subsystem handoff
+references, lifecycle gaps, active step, status, and correlation ids.
+
+Registration completion and prepared-account claim automatically start matching
+welcome protocols. Manual start/progress/complete/skip/fail/resume operations
+are also exposed through `UserEngineService` and authorization-gated.
+
+Missing required subsystem callbacks produce explicit lifecycle gaps and block
+the journey. The service records audit/outbox events with ids, statuses, step
+keys, source ids, and lifecycle gap identifiers, but not factor values, support
+content, notification payloads, or subsystem-specific tour data.
+
 ## Identity Context Contract
 
 `identity_context` is the first canon-facing read model for NetKingdom
 identity-domain consumers. It resolves a verified actor into the local user,
 account, external identity links, tenant scope, memberships, optional
 application scope, optional effective profile, optional active access context,
-exportable access-control facts, canon entity references, relationship
-references, grant-like membership facts, and evidence references.
+exportable access-control facts, onboarding journeys, canon entity references,
+relationship references, grant-like membership facts, and evidence references.
 
 The method keeps these concepts distinct: