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:
 

docs/netkingdom-registration-onboarding-vision.md

@@ -235,9 +235,9 @@ once.
 
 ## Recommended Workplans
 
-As of 2026-06-15, `USER-WP-0010`, `USER-WP-0011`, and `USER-WP-0012` are
-implemented as headless user-engine slices. The later workplans remain
-recommended follow-on work.
+As of 2026-06-15, `USER-WP-0010`, `USER-WP-0011`, `USER-WP-0012`, and
+`USER-WP-0013` are implemented as headless user-engine slices. The later
+workplans remain recommended follow-on work.
 
 | Workplan | Title | Purpose |
 | --- | --- | --- |

docs/onboarding-journeys-and-welcome-protocols.md

@@ -0,0 +1,91 @@
+# Onboarding Journeys And Welcome Protocols
+
+Status: implemented headless slice
+Date: 2026-06-15
+Related workplan: USER-WP-0013
+
+## Purpose
+
+This slice adds resumable onboarding journeys for newly registered or newly
+entitled users. Welcome protocols are templates that can be triggered by
+registration completion, prepared-account claims, invitations, access-profile
+events, or explicit manual starts.
+
+user-engine owns journey state, audit/event correlation, lifecycle gaps, and
+adapter references. Notification delivery, support content, protected service
+tours, and external workflow/task systems remain outside the core domain.
+
+## Domain Model
+
+`WelcomeProtocol` is the tenant-scoped template. It stores trigger type,
+optional matching keys such as prepared journey, application, realm, service,
+role, hat, factor requirements, and ordered `WelcomeProtocolStep` definitions.
+
+`WelcomeProtocolStep` names the subsystem, task kind, optional external task
+reference, optional callback reference, support reference, and whether a
+subsystem callback is required.
+
+`OnboardingJourney` is the persisted user state. It records tenant, user,
+protocol, trigger type, source id/event, journey key, status, active step,
+correlation id, and timestamps.
+
+`OnboardingStep` carries step status plus optional `OnboardingTask` and
+`SubsystemHandoff` references. Missing required subsystem callbacks produce
+explicit lifecycle gaps such as
+`subsystem-callback-missing:<subsystem>:<step>`.
+
+## Public Facade
+
+`UserEngineService` exposes:
+
+- `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(...)`
+
+Registration completion auto-starts matching registration protocols. Prepared
+account claim auto-starts matching prepared-account protocols when the claimed
+package includes a matching onboarding journey key.
+
+## Lifecycle Rules
+
+Journey status is derived from step state:
+
+- a missing required callback starts the journey as `blocked`;
+- an active non-blocked first step starts as `in_progress`;
+- failed steps fail the journey;
+- all completed/skipped steps complete the journey;
+- all skipped steps skip the journey.
+
+Resuming a pending, blocked, or failed journey can attach callback references
+and returns blocked/failed steps to `in_progress`.
+
+## Adapter Boundary
+
+The service defines ports for notification delivery, task systems, support
+content, subsystem welcome callbacks, and lifecycle task linking. The current
+headless slice stores adapter references but does not call external systems.
+
+## Identity Context And Diagnostics
+
+`identity_context` includes onboarding journeys for the resolved user/tenant.
+`onboarding_diagnostics` reports protocol count, journey count, status counts,
+blocked step ids, and lifecycle gaps.
+
+Diagnostics and outbox events avoid factor values and service content. Payloads
+carry ids, statuses, trigger types, source ids, active step keys, and lifecycle
+gap identifiers.
+
+## Current Limits
+
+- No notification platform or support-content renderer is implemented.
+- No protected subsystem tour is hard-coded into user-engine.
+- External task and callback execution is left to adapters.
+- UI surfaces are left to USER-WP-0014.

docs/prepared-accounts-and-entitlement-claims.md

@@ -114,4 +114,5 @@ addresses, and eID payloads.
   adds explicit approval decisions.
 - Final authorization policy and ACL evaluation remains outside user-engine;
   user-engine only activates owned facts for policy systems to consume.
-- Journey orchestration beyond outbox requests is left to USER-WP-0013.
+- Journey orchestration from prepared-account onboarding requests is
+  implemented by USER-WP-0013.

docs/registration-identity-and-factor-model.md

@@ -113,6 +113,7 @@ return factor values.
 - Hats, realms, services, assets, and access profiles are implemented by
   USER-WP-0012 and documented in
   `docs/hats-realms-services-assets-access-profiles.md`.
-- Welcome protocols and onboarding journeys are left to USER-WP-0013.
+- Welcome protocols and onboarding journeys are implemented by USER-WP-0013
+  and documented in `docs/onboarding-journeys-and-welcome-protocols.md`.
 - Registration UI is left to USER-WP-0014.
 - Provider-backed proofing and credential flows remain external adapters.