oneie
Version:
Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.
745 lines (567 loc) • 24.6 kB
Markdown
---
title: Wave1 Onboarding Vision
dimension: things
category: plans
tags: agent, ai, backend, frontend, groups, cycle, ontology
related_dimensions: connections, events, groups, people
scope: global
created: 2025-11-03
updated: 2025-11-03
version: 1.0.0
ai_context: |
This document is part of the things dimension in the plans category.
Location: one/things/plans/wave1-onboarding-vision.md
Purpose: Documents wave 1: creator onboarding - vision document
Related dimensions: connections, events, groups, people
For AI agents: Read this to understand wave1 onboarding vision.
---
# Wave 1: Creator Onboarding - Vision Document
**Version:** 1.0.0
**Status:** Ready for Implementation
**Last Updated:** 2025-11-01
---
## Executive Summary
Wave 1 Creator Onboarding is the **critical path foundation** for the ONE platform. This feature enables creators to register, verify their email, complete their profile, create a workspace, invite team members, connect wallets, and begin monetizing.
This is **NOT** a standalone feature - it's the prerequisite that unblocks all downstream work (monetization, agents, API, e-commerce). Without creator onboarding, no one can use the platform.
**Timeline:** Cycle 1-100 (approximately 8-12 cycles per specialist per day)
**Team:** 4 specialists (backend, frontend, quality, designer) + documentation
**Scope:** 8-stage signup flow + workspace management + team collaboration
---
## 6-Dimension Ontology Validation
### GROUPS (Isolation & Hierarchy)
**Onboarding maps perfectly to the Groups dimension:**
- **Creator's workspace** = New `group` (type: "organization")
- **Team members** = Additional people added to the group via `member_of` connections
- **Hierarchical structure:** Personal workspace (level 1) → optional sub-groups for departments (level 2+)
- **Group ownership:** Creator becomes the `group_owner` of their workspace
- **Data scoping:** All creator's content, team, and settings are scoped to this group
**Example:**
```
Creator "Jane" registers
↓ Creates workspace "Jane's Studio" (group)
├─ Jane is group_owner (role: "group_owner")
├─ Invites Editor "Bob" (role: "group_user")
└─ All content/analytics scoped to this group
```
### PEOPLE (Authorization & Governance)
**Onboarding maps perfectly to the People dimension:**
- **Creator thing** = Person with properties (email, username, bio, avatar, skills, interests)
- **Roles:** Creator starts as `group_owner` in their workspace
- **Permissions:** Workspace owner can manage team, billing, settings
- **Additional roles:** Editor, Viewer (for team members)
- **Authentication:** Email + password verified via verification code
- **Governance:** Creator controls who can access their workspace
**Role Hierarchy:**
```
Platform Owner (global)
└─ Creator (group_owner)
├─ Team Member (group_user) - Editor/Viewer roles
├─ Team Member (group_user) - Editor/Viewer roles
└─ ...
```
### THINGS (Entities)
**Onboarding creates and manages these thing types:**
1. **creator** (person) - The registered user
- Email, username, displayName, bio, avatar
- Niche, expertise, interests
- Workspace IDs, roles
- Wallet address (optional)
- Onboarding status/completion tracking
2. **organization** (workspace group) - Created during workspace setup
- Name, slug, description, logo
- Plan (starter/pro/enterprise)
- Member count, visibility settings
3. **invitation_token** - For team member invitations
- Token, invitedEmail, workspaceId, role
- Status (pending/accepted/expired), expiresAt
4. **verification_token** - For email verification
- Token, userId, type (email/2fa)
- ExpiresAt, attempts, maxAttempts
5. **ui_preferences** - User settings & preferences
- Theme, language, timezone, notification settings
**All scoped to group:** Every thing is associated with `groupId` (creator's workspace)
### CONNECTIONS (Relationships)
**Onboarding creates these relationship types:**
1. **member_of** (creator → workspace group)
- Metadata: role (group_owner), permissions, joinedAt
2. **member_of** (team member → workspace group)
- Metadata: role (group_user), permissions, invitedBy, invitedAt, status
3. **owns** (creator → created content/resources)
- Will be used for content ownership post-onboarding
**Connection Pattern:**
```
creator_jane → workspace_jane_studio (member_of, role: "group_owner")
editor_bob → workspace_jane_studio (member_of, role: "group_user", status: "pending/active")
```
### EVENTS (Actions & Audit Trail)
**Onboarding logs these event types:**
- `user_registered` - Signup form submitted
- `email_verification_sent` - Verification code sent
- `email_verified` - Email confirmed
- `profile_updated` - Profile completed
- `thing_created` (thingType: "organization") - Workspace created
- `user_invited_to_group` - Team member invited
- `user_joined_group` - Team member accepted
- `wallet_connected` - Crypto wallet linked
- `thing_updated` (thingType: "creator") - Skills added
- `onboarding_completed` - Full journey done
**Complete Audit Trail:** Every step logged for analytics, funnel tracking, and debugging
### KNOWLEDGE (Taxonomy & RAG)
**Onboarding connects creators to knowledge labels:**
- **Skills/Expertise:** skill:video-editing, skill:copywriting, skill:fitness-coaching
- **Industries:** industry:fitness, industry:education, industry:finance
- **Interests:** topic:personal-branding, topic:monetization, topic:community
- **Platform Goals:** goal:income, goal:audience, goal:collaboration, goal:learning
**Knowledge Pattern:**
```
creator_jane links to knowledge items:
├─ skill:fitness-coaching
├─ skill:social-media
├─ industry:wellness
├─ goal:income
└─ goal:community
```
These labels enable:
- Smart recommendations (show relevant products/courses/agents)
- Cohort discovery (find similar creators)
- Personalized dashboard (show relevant features)
- Semantic search (find by expertise/interest)
---
## User Personas & Motivations
### Persona 1: Solo Creator (YouTuber/Podcaster)
**Why they join:**
- Want to monetize existing audience
- Need passive income stream
- Interested in AI collaboration (avatars, agents)
- Tired of platform dependence (YouTube, Spotify)
**First 5 minutes:**
1. Sign up with Google
2. Verify email (auto-verify from Google)
3. Enter name + bio (copy from YouTube description)
4. Select niche (comedy, education, business)
5. See "Ready to monetize" CTA
**First day goal:**
- Profile 100% complete
- Wallet connected (to receive X402 payments)
- First 3 skills tagged
- See dashboard tour
**First week goal:**
- Create first content piece
- Earn first tokens
- Understand monetization model
- Subscribe to starter plan
### Persona 2: Agency Owner (Team Leader)
**Why they join:**
- Manage multiple creators in one place
- Coordinate team content production
- Track earnings across team
- Automate workflows
**First 5 minutes:**
1. Sign up with email
2. Create workspace (e.g., "Creative Collective")
3. Invite 3 team members via email
4. Set member permissions (editor/viewer)
5. See team dashboard
**First day goal:**
- Workspace created and branded
- Team invited (pending their acceptance)
- Roles defined (who can publish, who can view)
- Settings configured (brand colors, domain)
**First week goal:**
- All team members joined
- First collaborative content created
- Team earnings visible
- Upgrade to pro plan
### Persona 3: AI Agent Developer
**Why they join:**
- Deploy custom AI agents that monetize
- Earn from agent conversations
- Integrate with their own systems
- Use X402 for micropayments
**First 5 minutes:**
1. Sign up with GitHub OAuth
2. Verify email
3. Enter name + bio (copy from GitHub profile)
4. Select interests (AI, automation, integration)
5. See "API Documentation" link
**First day goal:**
- Profile complete
- Wallet connected (for X402 transactions)
- API keys generated
- Read API docs
**First week goal:**
- Deploy first agent
- Make first API call
- Receive first X402 payment
- Subscribe to developer plan
### Persona 4: Product Merchant
**Why they join:**
- Sell digital products (templates, tools, courses)
- Manage inventory + pricing
- Receive payments automatically
- Build customer relationships
**First 5 minutes:**
1. Sign up with email
2. Create workspace (e.g., "Design Templates Store")
3. Complete profile (store name, description)
4. Add first product (template/tool)
5. Set pricing
**First day goal:**
- Store profile created
- First 3 products listed
- Wallet connected (for payouts)
- Store visible to public
**First week goal:**
- Make first sale
- Receive first payout
- Get 10 customers
- Set up email automation
---
## Onboarding Flow (8 Stages)
```
┌─────────────────────────────────────────────────────┐
│ STAGE 1: LANDING (Pre-Auth) │
│ "Welcome to ONE" │
│ - Hero section + features │
│ - CTA: Sign Up | Sign In │
│ - 30 seconds │
└──────────────┬──────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ STAGE 2: SIGNUP (Auth) │
│ Email, Password, Agree to Terms │
│ - Email/password form │
│ - OAuth options (Google, GitHub, Discord) │
│ - "I agree to terms" checkbox │
│ - 2 minutes │
└──────────────┬──────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ STAGE 3: EMAIL VERIFICATION │
│ Confirm email with 6-digit code │
│ - "Check your inbox" │
│ - 6-digit code input (auto-submit) │
│ - Resend option (with cooldown) │
│ - 1 minute │
└──────────────┬──────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ STAGE 4: PROFILE │
│ Complete creator profile │
│ - Avatar upload │
│ - Display name │
│ - Username (unique, URL-safe) │
│ - Bio (up to 500 chars) │
│ - Niche selection (multi-select) │
│ - 3 minutes │
└──────────────┬──────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ STAGE 5: WORKSPACE │
│ Create workspace (group) │
│ Option A: "I'm solo" │
│ → Create personal workspace │
│ → 1 minute │
│ Option B: "I manage a team" │
│ → Name workspace │
│ → Add team members (email list) │
│ → 3 minutes │
└──────────────┬──────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ STAGE 6: WALLET (Optional but Encouraged) │
│ Connect crypto wallet for X402 payments │
│ - Benefits explanation │
│ - "Connect Wallet" button │
│ - Wallet selection (MetaMask, Rainbow, etc) │
│ - "Skip for now" link │
│ - 2 minutes or skip │
└──────────────┬──────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ STAGE 7: SKILLS │
│ Tag expertise + interests │
│ - Pre-populated from niche (if selected) │
│ - Skill groups (education, fitness, tech, etc) │
│ - Multi-select + custom skill text │
│ - 2 minutes │
└──────────────┬──────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ STAGE 8: WELCOME & TOUR │
│ Interactive tour + dashboard intro │
│ - "Welcome to ONE!" celebration │
│ - Quick tour (6 steps, can skip) │
│ - Show: create content, manage team, monetize │
│ - First-day checklist │
│ - CTA: "Go to Dashboard" │
│ - 2 minutes or skip │
└──────────────┬──────────────────────────────────────┘
↓
READY!
Access Dashboard
Begin Creating/Selling
```
**Total time:** <15 minutes for complete onboarding (8-10 min focused, 2-5 min skippable)
---
## Success Metrics
### Funnel Metrics (Target: 80%+ completion)
```
Signups: 100%
↓
Email Verified: 90%
↓
Profile Completed: 85%
↓
Workspace Created: 83%
↓
Team Member Invited (or Solo): 81%
↓
Skills Added: 80%
↓
Dashboard Tour Started: 78%
↓
FULLY COMPLETE: 75%+
```
### Timing Metrics
| Stage | Target Time | Upper Limit |
| ---------------------- | ----------- | ----------- |
| Signup → Email Verify | 2 min | 5 min |
| Email Verify → Profile | 1 min | 3 min |
| Profile → Workspace | 1 min | 2 min |
| Workspace → Skills | 2 min | 5 min |
| Skills → Complete | 1 min | 2 min |
| **Total** | **7 min** | **15 min** |
### Quality Metrics
- **Email delivery:** >98% (track hard bounces)
- **Form validation:** Real-time feedback (no surprises at submit)
- **Error resolution:** <30 seconds to recover from any error
- **Mobile conversion:** 70%+ of desktop rate
- **Accessibility:** WCAG 2.1 AA compliance
- **Load time:** <2s initial page load
### Business Metrics (Post-Onboarding)
- **7-day retention:** 70%+ return to dashboard
- **30-day activation:** 50%+ create content or make sale
- **Profile strength:** 85%+ add 3+ skills
- **Wallet adoption:** 40%+ connect wallet
- **Team adoption:** 30%+ invite team member
- **Plan upgrade:** 20%+ upgrade from free to paid within 30 days
---
## First-Day Quick Win Checklist
Goal: Creator feels **successful and confident** after onboarding.
```
Quick Wins Checklist (6 items to complete):
☐ Profile 80% Complete
├─ Name + avatar (required)
├─ Bio (required)
└─ Niche selected (required)
Reward: Profile badge unlocked
☐ Email Verified
└─ Check! (happens during signup)
Reward: Email verification badge
☐ Workspace Created
└─ Personal or team workspace active
Reward: Workspace badge unlocked
☐ Team Member Invited (or Solo Confirmed)
└─ Invited 1+ team member OR confirmed solo
Reward: Collaboration badge (or Solo badge)
☐ Wallet Connected (Encouraged but Optional)
└─ Crypto wallet linked and verified
Reward: Ready to Earn badge
☐ First Skill Added
└─ At least 1 expertise tagged
Reward: Expert badge unlocked
Final Reward: "Welcome to ONE" achievement + 100 bonus tokens (for testing)
└─ Unlock advanced dashboard features
└─ Access to AI agents (if available)
└─ Community welcome message from platform
```
Completion of all 6 items triggers:
- Email: "You're all set! Here's what's next..."
- Dashboard notification: "You're ready to create & earn"
- Unlock beginner-friendly content (first course, first template, etc)
---
## Integration Points
### 1. Better Auth (Authentication)
**Current state:** Email/password + OAuth working in production
**Onboarding adds:**
- Email verification flow (6-digit code via Resend)
- User creation in Better Auth
- Session creation for authenticated requests
- Login redirect after onboarding complete
**API Integration:**
```
signup → Create user in Better Auth
↓
send verification email → Resend
↓
verify code → Mark user as verified
↓
login → Get session token
```
### 2. Convex (Database)
**Creates:**
- `creator` thing (in entities table)
- `organization` thing (workspace, in entities table)
- `member_of` connection (creator → workspace)
- Verification tokens for email flow
- Events for every transition
**Tables touched:**
- `entities` (creator, workspace things)
- `connections` (team membership)
- `events` (audit trail)
- `groups` (workspace group)
### 3. Email (Resend)
**Sends:**
- Welcome email (after signup)
- Verification code (6-digit, 10-min expiry)
- Team invitation (if inviting others)
- Password reset (if requested)
- Onboarding reminder (if abandoned)
### 4. Wallet (viem/wagmi) - Optional
**For X402 protocol:**
- Detect MetaMask, Rainbow Kit, WalletConnect
- Request wallet connection
- Sign message to verify ownership
- Store wallet address in creator properties
- Display wallet balance (future: X402 earnings)
### 5. Analytics
**Track every transition:**
- Conversion funnel (which stage drops off?)
- Time in each stage
- Device/browser (mobile vs desktop)
- Signup source (direct, OAuth provider, referral)
- Completion rate by cohort
---
## Dependencies
### Block Everything Until Ready
**Wave 1 blocks:**
- Wave 2 (Monetization) - Needs creators first
- Wave 3 (Agents) - Needs authenticated creators
- Wave 4 (API) - Needs API keys (requires creator)
- Wave 5 (E-commerce) - Needs workspace for product management
- All team features - Needs workspace + team members
### Requirements Met
✅ Better Auth working (email/password + OAuth)
✅ Convex schema defined (groups, entities, connections, events)
✅ Resend integrated (email sending)
✅ Production Convex Cloud deployed
✅ Frontend React 19 ready
✅ Backend TypeScript fixed
**Everything needed is ready. This is a pure build.**
---
## Out of Scope (Wave 2+)
These features are intentionally **NOT** in Wave 1:
- **Monetization:** No stripe, no pricing, no products yet
- **AI Agents:** No agent deployment, no AI clone
- **Analytics:** No detailed dashboard stats
- **Advanced team:** No fine-grained permissions, no audit logs per action
- **Advanced wallet:** No balance display, no transaction history
- **Advanced profile:** No portfolio, no testimonials, no verification badges
- **Content creation:** No editor, no publishing system
- **Community:** No forums, no messaging
These are all Wave 2+. Wave 1 is **purely onboarding**.
---
## Success Criteria for Wave 1 Complete
Wave 1 is done when:
- ✅ User can register with email + password
- ✅ Email verification works (code sent + verified)
- ✅ Profile form complete + avatar upload working
- ✅ Workspace creation working
- ✅ Team member invitations working (send + accept)
- ✅ Wallet connection optional but functional
- ✅ Skills/expertise tagging working
- ✅ Onboarding status tracked (events logged)
- ✅ 80%+ of test users complete full flow
- ✅ Average time < 15 minutes
- ✅ Mobile-responsive (70%+ desktop conversion on mobile)
- ✅ Accessibility compliant (WCAG 2.1 AA)
- ✅ New creator can access dashboard
- ✅ Team features tested (invite, accept, roles visible)
- ✅ Complete audit trail (all events logged)
- ✅ API documented + ready for Wave 2
---
## What Happens After Onboarding
**Day 1:**
- Creator sees dashboard
- Dashboard shows quick wins checklist (if not completed)
- Suggestions for next steps (create content, connect wallet, invite team)
- "Recommended for you" section (based on skills/interests)
**Day 2-7:**
- First content created (or first sale)
- First X402 payment received (if wallet connected)
- First team member joins (if invited)
- First earnings visible
- Email: "You earned X tokens!"
**Week 2-4:**
- Decide to upgrade to pro plan
- Buy first AI agent or course
- Publish second piece of content
- Invite more team members
- Build audience
**Month 2+:**
- Platform becomes primary revenue stream
- Team grows
- AI agents deployed
- Community engaged
- Becomes advocate (invites friends)
---
## Architecture Notes
### Frontend Stack
- **Pages:** Astro (SSR) - Fast, server-rendered, minimal JS
- **Components:** React 19 (islands) - Interactive elements only
- **Forms:** Shadcn/ui + Tailwind v4 - Accessible, beautiful
- **Routing:** File-based (Astro routing)
- **State:** Convex hooks (useQuery, useMutation)
- **Auth:** Better Auth client library
### Backend Stack
- **Database:** Convex (Real-time, schema-enforced)
- **Services:** Effect.ts (pure business logic)
- **Mutations:** Thin wrappers (validation + event logging)
- **Email:** Resend (@convex-dev/resend component)
- **Auth:** Better Auth (6 methods: email, Google, GitHub, Discord, magic link, 2FA)
- **Rate Limiting:** @convex-dev/rate-limiter (prevent abuse)
### Security
- Email verification (prevents fake email signup)
- Rate limiting (prevent brute force)
- Password hashing (SHA-256 minimum, bcrypt recommended)
- JWT tokens (refresh + access token pattern)
- CORS validation (frontend/backend same origin)
- Email validation (basic format + delivery check)
### Performance Targets
- Signup page: <2s initial load
- Form submit: <1s response
- Email delivery: <30 seconds
- Dashboard render: <3s after login
- Mobile: 70%+ of desktop speed
---
## Next Steps After Approval
1. **Backend specialist** starts at Cycle 11
- Extend creator entity type
- Create onboarding mutations
- Create verification system
- Create email templates
2. **Frontend specialist** starts at Cycle 21
- Build signup → verification → profile flow
- Build workspace creation UI
- Build team management UI
- Build onboarding pages
3. **Quality specialist** starts at Cycle 31
- Define test cases
- Build test infrastructure
- Run integration tests
- Create test user accounts
4. **Designer specialist** starts at Cycle 41
- Create wireframes (already have specs)
- Design system review
- Component specs
- Accessibility audit
5. **Orchestration** throughout
- Monitor progress across all specialists
- Resolve blockers
- Ensure 6-dimension alignment
- Log completion events
---
**Status:** Ready for implementation
**Approved:** Engineering Director (AI Agent)
**Implementation Start:** Immediate (Cycle 1)