Citizen Onboarding Flow
🌱 Citizen Onboarding Flow¶
Version: 1.0
Date: December 3, 2025
Purpose: Guide new citizens through their first experience in the HIVE
Overview¶
This document defines the complete onboarding experience for new citizens joining a City-State.
Goals: - ✅ Make citizens feel welcome and empowered - ✅ Explain key concepts clearly - ✅ Get them participating quickly - ✅ Build excitement and connection - ✅ Establish foundational understanding
Duration: 15-30 minutes
Flow Diagram¶
┌─────────────┐
│ WELCOME │
│ SCREEN │
└──────┬──────┘
│
▼
┌─────────────┐
│ CITY-STATE │
│ SELECTION │
└──────┬──────┘
│
▼
┌─────────────┐
│ COMPANION │
│ AGENT │
│ MATCHING │
└──────┬──────┘
│
▼
┌─────────────┐
│ THREE NORTH │
│ STARS │
│ (Tutorial) │
└──────┬──────┘
│
▼
┌─────────────┐
│ FIRST QUEST │
│ "Hello, │
│ HIVE" │
└──────┬──────┘
│
▼
┌─────────────┐
│ DASHBOARD │
│ TOUR │
└──────┬──────┘
│
▼
┌─────────────┐
│ FIRST EVENT │
│ INVITATION │
└──────┬──────┘
│
▼
┌─────────────┐
│ ONBOARDING │
│ COMPLETE │
└─────────────┘
Screen 1: Welcome Screen¶
Visual:¶
Large, clean welcome message with soft background imagery
╔══════════════════════════════════════════════════╗
║ ║
║ 🌟 Welcome to the HIVE 🌟 ║
║ ║
║ A place built on integrity, participation, ║
║ and shared meaning. ║
║ ║
║ [BEGIN JOURNEY] ║
║ ║
╚══════════════════════════════════════════════════╝
Text:¶
Welcome to the HIVE
You're about to join a digital civilization unlike anything you've experienced.
Here: - There are no politicians - There is no manipulation - Your contribution matters - You're never alone
Ready to begin?
Button: [BEGIN JOURNEY]
Audio (Optional):¶
Soft, welcoming ambient music
Screen 2: City-State Selection¶
Visual:¶
Grid of City-State cards with key metrics displayed
╔═══════════════════════════════════════════════╗
║ Choose Your City-State ║
║ ║
║ ┌─────────────┐ ┌─────────────┐ ║
║ │ AURORA │ │ HELIX │ ║
║ │ 🟢 0.972 │ │ 🟢 0.961 │ ║
║ │ v: 0.82 │ │ v: 0.74 │ ║
║ │ 130M GDP │ │ 96M GDP │ ║
║ │ │ │ │ ║
║ │ Knowledge │ │ Research │ ║
║ │ [LEARN] │ │ [LEARN] │ ║
║ └─────────────┘ └─────────────┘ ║
║ ║
║ ┌─────────────┐ ┌─────────────┐ ║
║ │ SOLACE │ │ MERIDIAN │ ║
║ │ 🟢 0.958 │ │ 🟡 0.949 │ ║
║ │ v: 0.69 │ │ v: 0.63 │ ║
║ │ 81M GDP │ │ 72M GDP │ ║
║ │ │ │ │ ║
║ │ Community │ │ Arts │ ║
║ │ [LEARN] │ │ [LEARN] │ ║
║ └─────────────┘ └─────────────┘ ║
║ ║
║ [EXPLORE MORE] ║
╚═══════════════════════════════════════════════╝
Explanation for Each City-State:¶
When clicking [LEARN MORE] on a city:
Aurora Card Expanded:
Aurora City-State 🌟
Focus: Knowledge, learning, and skill development
Culture: Curious, supportive, growth-oriented
Integrity (GI_state): 0.972 🟢 (Excellent)
Participation (v): 0.82 (High activity)
GDP: $130M (Thriving economy)
What makes it special: - Strong education programs - Active tutoring community - Weekly learning festivals - Research collaborations
Good fit if you enjoy: Learning, teaching, research, knowledge sharing
[JOIN AURORA] [EXPLORE OTHERS]
Guidance Text:¶
"Each City-State has its own personality, but all share the same foundation: integrity.
Don't worry — you can move between City-States later!"
Screen 3: Companion Agent Matching¶
Visual:¶
Interactive personality/preference questions with friendly UI
╔══════════════════════════════════════════════════╗
║ Meet Your Companion Agent ║
║ ║
║ Every citizen receives a free AI Companion ║
║ to help you learn, grow, and thrive. ║
║ ║
║ Answer a few questions to find your match: ║
║ ║
║ 1. I prefer learning through: ║
║ ○ Reading and writing ║
║ ○ Visual guides and videos ║
║ ○ Hands-on practice ║
║ ○ Conversations ║
║ ║
║ 2. I work best with: ║
║ ○ Structured guidance ║
║ ○ Flexible exploration ║
║ ○ Both, depending on the task ║
║ ║
║ 3. My main goals here are: ║
║ ☑ Learn new skills ║
║ ☑ Contribute knowledge ║
║ ☐ Build community ║
║ ☐ Create things ║
║ ║
║ [FIND MY COMPANION] ║
╚══════════════════════════════════════════════════╝
Result Screen:¶
╔══════════════════════════════════════════════════╗
║ Your Companion: SAGE ║
║ ║
║ 🤖 ║
║ ║
║ SAGE is a learning-focused Companion who ║
║ specializes in: ║
║ ║
║ • Personalized education paths ║
║ • Research assistance ║
║ • Knowledge organization ║
║ • Skill development tracking ║
║ ║
║ ───────────────────────────────────── ║
║ ║
║ 💬 "Hello! I'm SAGE, and I'm here to help ║
║ you thrive in Aurora. Ready to begin?" ║
║ ║
║ [YES, LET'S GO!] ║
╚══════════════════════════════════════════════════╝
Screen 4: Three North Stars Tutorial¶
Visual:¶
Interactive, animated explanation of the three key metrics
╔══════════════════════════════════════════════════╗
║ The Three North Stars ║
║ ║
║ Life in the HIVE is guided by three numbers: ║
║ ║
║ ┌────────────────────────────────────┐ ║
║ │ 1. INTEGRITY (GI_state) │ ║
║ │ │ ║
║ │ 🛡️ 0.972 │ ║
║ │ │ ║
║ │ "Are we honest, fair, aligned?" │ ║
║ │ │ ║
║ │ High integrity = healthy state │ ║
║ │ │ ║
║ │ [LEARN MORE] │ ║
║ └────────────────────────────────────┘ ║
║ ║
║ [CONTINUE] ║
╚══════════════════════════════════════════════════╝
Progression:¶
- GI_state Explanation (with animation showing healthy vs unhealthy states)
- Velocity Explanation (with animation showing participation levels)
- GDP_state Explanation (with animation showing value creation)
Final Summary:¶
╔══════════════════════════════════════════════════╗
║ Your Three North Stars ║
║ ║
║ 🛡️ Integrity → Are we doing good? ║
║ 💫 Velocity → Are we participating? ║
║ 💰 GDP → Are we creating value? ║
║ ║
║ You'll see these metrics everywhere. ║
║ They guide everything we do together. ║
║ ║
║ 💬 SAGE: "When all three are healthy, ║
║ amazing things happen!" ║
║ ║
║ [I UNDERSTAND] ║
╚══════════════════════════════════════════════════╝
Screen 5: First Quest — "Hello, HIVE"¶
Visual:¶
Quest card with clear objectives and rewards
╔══════════════════════════════════════════════════╗
║ 🎯 Your First Quest: "Hello, HIVE" ║
║ ║
║ Welcome to Aurora! Complete these steps to ║
║ earn your first KS and start contributing: ║
║ ║
║ ☑ Meet your Companion Agent ║
║ ☐ Set up your profile ║
║ ☐ Explore the dashboard ║
║ ☐ Earn 10 KS (this quest gives 20!) ║
║ ☐ Introduce yourself in the plaza ║
║ ║
║ ─────────────────────────────────── ║
║ ║
║ Rewards: ║
║ • 20 KS ║
║ • "First Steps" badge ║
║ • +10 Reputation ║
║ • Unlock: Dashboard tour ║
║ ║
║ 💬 SAGE: "Let's start with your profile!" ║
║ ║
║ [BEGIN PROFILE SETUP] ║
╚══════════════════════════════════════════════════╝
Profile Setup:¶
Simple, optional fields:
- Display name
- Avatar (choose from library or upload)
- Short bio (optional)
- Interests (tags)
- Preferred pronouns
Note: Emphasize privacy — only public info is shared.
Screen 6: Dashboard Tour¶
Visual:¶
Interactive tour with highlights and explanations
╔══════════════════════════════════════════════════╗
║ ║
║ ┌─────────────────────────────────────────┐ ║
║ │ AURORA DASHBOARD 🟢 0.972 │ ║
║ ├─────────────────────────────────────────┤ ║
║ │ │ ║
║ │ Your Stats: │ ← This shows your
║ │ • KS Balance: 20 │ personal stats
║ │ • Reputation: 10 │
║ │ • Quests: 1/1 complete │ ║
║ │ │ ║
║ │ City-State Health: │ ← This shows Aurora's
║ │ • GI: 0.972 🟢 │ overall health
║ │ • v: 0.82 (High) │
║ │ • GDP: $130M │ ║
║ │ │ ║
║ │ Active Quests: │ ║
║ │ [3 available quests listed] │ ║
║ │ │ ║
║ │ Upcoming Events: │ ║
║ │ 🎉 Learning Festival - Tomorrow │ ║
║ │ │ ║
║ └─────────────────────────────────────────┘ ║
║ ║
║ [GOT IT] ║
╚══════════════════════════════════════════════════╝
Tour Steps:
- Your Stats — Balance, reputation, quests
- City-State Health — GI, velocity, GDP
- Quest Board — Available tasks and challenges
- Event Calendar — Festivals, gatherings, meetings
- Community — Citizen directory, chat, forums
- Settings — Privacy, notifications, preferences
Screen 7: First Event Invitation¶
Visual:¶
Warm invitation to the next City-State event
╔══════════════════════════════════════════════════╗
║ 🎉 You're Invited! ║
║ ║
║ AURORA LEARNING FESTIVAL ║
║ Tomorrow at 2:00 PM ║
║ ║
║ Join fellow citizens for: ║
║ • Skill-sharing sessions ║
║ • Q&A with experienced members ║
║ • Collaborative projects ║
║ • Welcome ceremony for new citizens ║
║ ║
║ This is a great way to meet people and ║
║ start participating! ║
║ ║
║ 💬 SAGE: "I'll remind you before it starts!" ║
║ ║
║ [ADD TO CALENDAR] [MAYBE LATER] ║
╚══════════════════════════════════════════════════╝
Screen 8: Onboarding Complete¶
Visual:¶
Celebration screen with clear next steps
╔══════════════════════════════════════════════════╗
║ ║
║ 🎊 Welcome Home! 🎊 ║
║ ║
║ You're now a full citizen of Aurora! ║
║ ║
║ What you've unlocked: ║
║ ✅ Full dashboard access ║
║ ✅ Quest board (3 new quests available) ║
║ ✅ Community features ║
║ ✅ Event participation ║
║ ✅ SAGE (your Companion Agent) ║
║ ║
║ Your stats: ║
║ • 20 KS earned ║
║ • "First Steps" badge ║
║ • Reputation: 10 ║
║ ║
║ ─────────────────────────────────── ║
║ ║
║ What to do next: ║
║ • Complete more quests ║
║ • Attend the Learning Festival ║
║ • Introduce yourself in the plaza ║
║ • Ask SAGE any questions ║
║ ║
║ 💬 SAGE: "I'm always here if you need help!" ║
║ ║
║ [EXPLORE AURORA] ║
╚══════════════════════════════════════════════════╝
Technical Implementation Notes¶
Required Data Collection:¶
- City-State selection
- Companion Agent preferences
- Profile information (name, avatar, bio)
- Privacy settings
API Calls:¶
POST /api/citizen/register— Create citizen accountPOST /api/companion/match— Assign Companion AgentPOST /api/quest/complete— Mark "Hello, HIVE" quest completePOST /api/event/rsvp— RSVP to first event (optional)
Tracking:¶
Track onboarding metrics: - Completion rate per screen - Drop-off points - Time spent per screen - Feature engagement
A/B Testing Opportunities:¶
- Different City-State presentation styles
- Quest order variations
- Companion matching questions
- Welcome message variations
Success Metrics¶
Onboarding is successful if:¶
- ✅ Completion Rate ≥ 80% (citizens finish entire flow)
- ✅ Time to Complete ≤ 30 minutes
- ✅ Day 1 Return Rate ≥ 60% (citizens come back next day)
- ✅ Week 1 Activity ≥ 3 actions (quests, events, interactions)
- ✅ Citizen Satisfaction ≥ 4.0/5.0 (post-onboarding survey)
Accessibility Requirements¶
The onboarding flow must:¶
- ✅ Work on mobile, tablet, desktop
- ✅ Support screen readers (WCAG 2.1 AA)
- ✅ Provide text alternatives for all visuals
- ✅ Allow keyboard-only navigation
- ✅ Offer high-contrast mode
- ✅ Support multiple languages (English, Spanish, French, Mandarin, Japanese initially)
Follow-Up: Days 2-7¶
Day 2:¶
- Reminder: Learning Festival today (if RSVP'd)
- New Quest Unlock: "Explore Three Features"
- SAGE Check-In: "How are you settling in?"
Day 3:¶
- Quest Recommendation: Based on interests
- Citizen Spotlight: Introduction to active member
- Tip of the Day: Dashboard feature highlight
Day 4:¶
- Community Invitation: Join a topic-based group
- SAGE Tutorial: Advanced feature walkthrough
- Progress Review: Stats since joining
Day 7:¶
- Week 1 Review: Achievements, KS earned, reputation gained
- Feedback Request: "How can we improve?"
- Next Steps: Suggested path forward
END OF CITIZEN ONBOARDING FLOW
"I walk with integrity. I build with others. I rise as my City-State rises."
Version: 1.0
Date: December 3, 2025
Maintained by: HIVE Onboarding Team
"We heal as we walk." — Mobius Systems