---
id: USER-WP-0013
type: workplan
title: "Onboarding Journeys And Welcome Protocols"
domain: netkingdom
repo: user-engine
status: finished
owner: codex
topic_slug: netkingdom
planning_priority: medium
planning_order: 13
created: "2026-06-15"
updated: "2026-06-15"
depends_on:
  - USER-WP-0011
  - USER-WP-0012
state_hub_workstream_id: "1dc82dfd-be68-4585-b6c9-6d24aebd3e27"
---

# USER-WP-0013 - Onboarding Journeys And Welcome Protocols

## Goal

Create a journey layer that helps newly registered or newly entitled users
enter the right NetKingdom subsystems. Welcome protocols should be driven by
registration, prepared-account, invitation, role, profile, and access events.

## Scope Direction

user-engine owns journey state, task references, event correlation, and user
context. Delivery systems, protected services, help content, notification
channels, and external task systems remain adapters or downstream systems.

## Non-Goals

- Do not build a notification platform.
- Do not embed service-specific tours or support content in core domain code.
- Do not replace external workflow/task systems.
- Do not build the UI in this workplan.

## Tasks

```task
id: USER-WP-0013-T1
status: done
priority: high
state_hub_task_id: "30ef8507-eebc-4b96-8aa6-c530bef05739"
```

Define onboarding journey, welcome protocol, journey step, task, and subsystem
handoff models.

```task
id: USER-WP-0013-T2
status: done
priority: high
state_hub_task_id: "7c6e53d4-ff96-4036-a413-f04b4b73d266"
```

Add journey templates keyed by registration outcome, prepared entitlement,
tenant, realm, service, application, role, hat, and factor requirements.

```task
id: USER-WP-0013-T3
status: done
priority: high
state_hub_task_id: "d9c2983a-45d1-4b1b-a416-63e180ca74b3"
```

Implement journey start, progress, complete, skip, fail, and resume operations
with authorization, audit, and outbox behavior.

```task
id: USER-WP-0013-T4
status: done
priority: medium
state_hub_task_id: "7155c2eb-4e32-46f0-ad33-961784cb9a03"
```

Add adapter ports for notifications, task systems, support content, subsystem
welcome callbacks, and lifecycle task linking.

```task
id: USER-WP-0013-T5
status: done
priority: medium
state_hub_task_id: "c5e42dd6-207a-4b1e-a0d8-35701e9f71bc"
```

Expose onboarding status through identity context, diagnostics, and optional UI
contracts.

## Acceptance Criteria

- Registration or prepared-account claim can start an onboarding journey.
- Journey state is resumable, auditable, and correlated with outbox events.
- Subsystem welcome steps are adapter-driven, not hard-coded into core
  registration logic.
- Users and admins can inspect pending onboarding work and blocked steps.
- Missing subsystem callbacks produce explicit lifecycle gaps.

## Expected Outputs

- Onboarding journey domain model.
- Welcome protocol service facade.
- Adapter ports for notifications and subsystem handoff.
- Scenario tests for successful, blocked, and resumed onboarding.

## Implementation Notes

Implemented on 2026-06-15:

- Added `OnboardingTriggerType`, `OnboardingJourneyStatus`,
  `OnboardingStepStatus`, `WelcomeProtocol`, `WelcomeProtocolStep`,
  `OnboardingJourney`, `OnboardingStep`, `OnboardingTask`, and
  `SubsystemHandoff` domain models.
- Added welcome-protocol and onboarding-journey persistence to
  `UserEngineStore` and `InMemoryUserEngineStore`, including transaction
  snapshots and record counts.
- Added adapter ports for onboarding notifications, task links, support
  content, subsystem welcome callbacks, and lifecycle task linking.
- Added `UserEngineService` onboarding facade methods:
  `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`, and
  `onboarding_diagnostics`.
- Added auto-start hooks for matching registration-completion protocols and
  prepared-account claim protocols.
- Extended `identity_context` with onboarding journeys for the resolved
  user/tenant.
- Added lifecycle-gap handling for missing subsystem callbacks and resumable
  blocked/failed journey state.
- Added `docs/onboarding-journeys-and-welcome-protocols.md`, public contract
  updates, and tests for registration-triggered, prepared-claim-triggered,
  blocked, resumed, progressed, skipped, and failed onboarding.

Verification:

```text
make test
Ran 66 tests in 0.620s
OK
```