docs(design): add OKF user story catalog

design/us-003-onboarding.md

@@ -0,0 +1,39 @@
+---
+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)