guild-onboarding-rethink

Onboarding Rethink — Free Signup + Square Identity Linking

Context

Existing WithFriends members are hesitant to sign up because the current flow shows a Stripe checkout. They already pay through WithFriends and think they’re being charged again. They just want to see their dashboard and points.

Additionally, members may want to sign up with Discord or a personal email that differs from their Square POS email. The current system assumes auth email = Square email for auto-linking, which breaks when they differ.

Current state (as of 2026-04-05)

• Better Auth handles member auth (email/password, email verification)
• Signup flow: pick tier → fill form → Stripe checkout → member created
• Square auto-links by email match on Stripe webhook
• Discord OAuth config exists in Better Auth but isn’t wired to signup
• No free tier — all signups require payment

Problem

1. WithFriends migration friction — existing paying members see a paywall to access their own data
2. Email mismatch — auth email (signup/Discord) may differ from Square email (where purchases live)
3. Abuse risk — if members self-serve Square linking, someone could claim another person’s purchases

Proposed architecture

Auth identity vs store identity

Decouple them:

• Auth identity = Better Auth user (email/password or Discord OAuth). How you log in.
• Store identity = Square customer ID. Where your purchases live.
• Link between them = verified, not just a text field

New signup flow

1. Sign up with any email or Discord — no payment required
2. Verify email (or Discord OAuth handles it)
3. Onboarding wizard:
   • “What email do you use at Dungeon Books?” (for Square matching)
   • Or NFC card tap / phone number to link identity
4. Staff approves the Square link (prevents abuse)
5. Tier assignment is separate (staff sets it, or member upgrades via Stripe later)

Square linking verification options

• Staff approval (simplest) — member requests link, staff confirms from POS
• Verification email — send email to the Square email address to confirm ownership
• NFC card tap — if member has a physical card, that proves identity
• Phone number match — match against Square customer phone

Key decisions needed

1. Do WithFriends members get auto-assigned a tier, or do they start tierless?
2. Is Square linking self-serve with verification, or always staff-approved?
3. Does Discord OAuth happen at signup or only as an account link from dashboard?
4. What’s the free tier called and what does it get? (access to dashboard + points, no store discount?)

Free tier store credit restriction

Free members can earn XP and accumulate points but cannot convert points to store credit unless they upgrade to a paid tier. This prevents the free tier from cannibalizing paid tier value while still giving free members a reason to engage. The conversion path exists as a visible carrot — free members see their unredeemable balance and the upgrade cost that would unlock it.

Also: if signup is free and Square auto-backfills on account creation, a new free signup immediately sees their purchase history populated and knows what level they’d be. This is a strong activation moment — backfill makes the character sheet compelling before the player has done anything. Staff don’t need to manually run backfill; it triggers automatically on first Square identity link.

Files likely affected

• src/app/(frontend)/signup/ — new flow without mandatory Stripe
• src/app/api/checkout/route.ts — decouple member creation from checkout
• src/collections/Members.ts — tier may become optional (free members have no tier)
• src/lib/auth-server.ts — enable Discord OAuth in signup
• New: onboarding wizard pages
• New: Square linking request + staff approval flow
• src/app/api/webhooks/stripe/route.ts — handle upgrade-from-free case

Key insight

Auth identity and store identity are different things. Someone’s Discord email or signup email isn’t necessarily the email they use at Square POS. The link between them needs verification — not just a text input.