---
id: USER-WP-0013
type: workplan
title: "Onboarding Journeys And Welcome Protocols"
domain: netkingdom
repo: user-engine
status: proposed
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: todo
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: todo
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: todo
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: todo
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: todo
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.