---
type: User Story
title: Complete first-time onboarding
description: New users establish their preferred identity and first Minecraft account.
tags: [player, onboarding, minecraft, discord]
timestamp: 2026-08-01T18:43:58Z
story_id: US-003
status: verified
---

# User Story

As a newly authenticated player, I want a guided setup flow, so that my preferred name, Minecraft identity, and Discord nickname are configured correctly.

# Acceptance Criteria

- [x] Given a new Discord user, when they enter the portal, then they receive a personalized welcome.
- [x] Given the first onboarding step, when the user enters a valid preferred name, then it is stored for their profile.
- [x] Given the Minecraft step, when a valid Java username is submitted from an allowed network, then it is verified and added as primary.
- [x] Given an unverifiable but syntactically valid username, then the user must explicitly confirm before continuing.
- [x] Given a name and primary account, then the expected Discord nickname is previewed before any guild update.
- [x] Given confirmation and a successful Discord update, then onboarding is marked complete and the dashboard opens.

# Implementation

- [`apps/web/src/app/welcome/page.tsx`](../apps/web/src/app/welcome/page.tsx)
- [`apps/web/src/app/welcome/minecraft/page.tsx`](../apps/web/src/app/welcome/minecraft/page.tsx)
- [`apps/web/src/app/welcome/discord/page.tsx`](../apps/web/src/app/welcome/discord/page.tsx)
- [`apps/web/src/app/welcome/actions.ts`](../apps/web/src/app/welcome/actions.ts)

# Validation

Onboarding routes are protected by database-backed sessions and included in production route generation.

# Related Stories

- [Validate Minecraft accounts](us-004-minecraft-validation.md)
- [Synchronize Discord nicknames](us-006-discord-nickname.md)
- [Block anonymized account additions](us-008-vpn-blocking.md)