TRIAL_AND_ONBOARDING.md — Trial, Onboarding & Conversion Guide¶
Last updated: April 13, 2026 (Omega v2.7)
Status: AUTHORITATIVE — the ONLY canonical reference for trial structure, onboarding, progressive interview, Laiv Rules of Engagement, and conversion mechanics.
Supersedes:
- trial_model_locked.md
- trial_strategy_2026.md + ADDENDUM_TRIAL_STRATEGY_2026.md
- trial_enchantment_blueprint.md
- trial_experience_design.md
- trial_touchpoint_strategy.md
- trial_touchpoints_detailed.md
- sprint10_BETA_addendum_onboarding.md (B10-6b)
- sprint_G2_trial_feature_gates.md
- sprint_G3_trial_questionnaire.md (old 7-screen questionnaire — DEAD CODE, superseded by progressive interview)
- sprint_G4_conversion_upgrade_workouts.md
- sprint_B3_savings_invite_tones.md
- sprint_B4_savings_card_referrals.md
- sprint_B8_onboarding_rebuild.md
- builder_prompt_phaseA6_onboarding_tutorials.md
- beta_onboarding_persona_legal.md
- MANDATORY_INTERVIEW_PATCH.md (absorbed)
- ADDENDUM_PROGRESSIVE_INTERVIEW_DESIGN_SPEC.md (absorbed — full spec still in PROGRESSIVE_INTERVIEW_DESIGN_SPEC.md)
- All trial sections from historical handover docs (OMEGA v2.1–v2.7)
Cross-references (do not duplicate): PROGRESSIVE_INTERVIEW_DESIGN_SPEC.md (full 45-question bank), ANTI_ABUSE_SPEC.md (7 defense layers), PRICING_AND_TIERS.md (tier matrix, competitor price DB), GHOST_PROTOCOL.md (Ghost trial moment mechanics), VOICE_AND_AI.md (Laiv voice tiers).
1. TRIAL STRUCTURE (LOCKED)¶
1.1 The 21-Day Model (guaranteed) → up to 28 with referrals¶
| Phase | Days | Tier | How Unlocked |
|---|---|---|---|
| Pro Trial | 0–14 | proTrial |
Auto on first install + device-fingerprint pass (silent) |
| Elite Trial | 14–21 | eliteTrial |
Mandatory progressive interview complete (6/11 traits) + mandatory phone verification. Skip phone = drop to starter immediately. |
| Referral Bonus | 21–28 | eliteTrial |
1 friend = +2 days, 2 = +4 days, 3 = +7 days |
| Expired | 28+ | starter |
Investment-score conversion screen |
21 days guaranteed. Up to 28 with referrals. No credit card required. No Ghost access during trial (on-device only, except the surgical Ghost trial moment — §5). The progressive interview is mandatory — every user completes it, every verified user gets Elite.
1.2 Trial Cost to Citerius¶
~$0.03/user (traffic + Supabase) + ~$0.08/user weighted Ghost trial moment = ~$0.11/user. Budget supports full 21–28 day trial for ALL users.
1.3 What Trial Users Get¶
| Feature | Pro Trial (0–14) | Elite Trial (14–28) |
|---|---|---|
| On-device AI (AMI-selected: Qwen 3.5 0.8B / 2B / 4B) | ✅ | ✅ |
| All Pro features | ✅ | ✅ |
| Adaptive scheduling, AI health insights, deep cross-module correlations | ❌ | ✅ |
| Ghost Protocol (Gemma 4 E4B) | ❌ (single-insight Ghost trial moment only) | ❌ base access; gift insights ok |
| Laiv Voice Standard (Piper ONNX) | ✅ | ✅ |
| Laiv Checkup | Day 0 baseline (Planning) + hints | Day 14 mid-trial + Day 28 FULL (FREE) |
| Paid add-ons | ❌ | ❌ |
No data export on Trial or Starter (anti-abuse). See ANTI_ABUSE_SPEC.md §4.
2. ONBOARDING FLOW (V21 — NewOnboardingScreen)¶
2.1 The 10-Step Flow (built)¶
Active file: lib/ui/onboarding/new_onboarding_screen.dart. Total time: <90 seconds.
1. Welcome ("Your life, organized." — StaggeredFadeIn)
2. Health Disclaimer (blocking; layer 1 of 7-layer legal framework)
3. Name (free text; Supabase user_profiles.display_name)
3.5 Username (FTS-safe; TAW10 BUG 1 fix: catch block returns TRUE on RLS/unknown errors — real collision caught at INSERT)
4. Birthday (date picker)
5. Biological Sex (feeds Wellbeing baselines)
6. Goals (multi-select, max 3; steers progressive-interview depth)
7. Roadblock ("What's the biggest thing standing in your way?")
8. Management Style (proactive ↔ hands-off; feeds LaivAgent tone)
9. Currency (locale-detected, one-tap confirm)
10. Finish → Dashboard
Dead code (orphaned): onboarding_screen.dart (old B10-6b 4-question flow) and old interview_screen.dart (27-question wall). Do not reference.
2.2 Six Onboarding Fields Persisted to Supabase (Omega v2.7 / Alpha sprint 8)¶
Reinstall recovery requires all onboarding data to survive device wipe. user_profiles now carries 8 columns (TAW10 + sprint 8):
| Field | SharedPrefs key | Supabase column |
|---|---|---|
| Display name | user_name |
display_name |
| Username | user_username |
username |
| Birthday | user_birthday |
birthday |
| Biological sex | user_biological_sex |
biological_sex |
| Goals (JSON array) | user_goals_list + interests |
goals_list |
| Roadblock | user_roadblock |
roadblock |
| Management style | user_management_style |
management_style |
| Currency | user_currency + currency |
preferred_currency |
Migration: 6 ALTER TABLE public.user_profiles ADD COLUMN IF NOT EXISTS … statements added to db_service.dart (RLS unchanged — owner-row policy covers new columns). auth_service.dart restore path also writes to both currency keys and both goals keys.
2.3 Reinstall / Re-login Recovery¶
- App launches → auth state checked.
- If authenticated →
auth_service.dartqueriesuser_profilesvia RLS-fallback query. - If profile exists with
display_name→ skip onboarding, rehydrate all 8 SharedPreferences keys from Supabase, markonboarding_completed=true. - Else → show 10-step onboarding.
Device fingerprint is checked silently at signup (see ANTI_ABUSE_SPEC.md). A known device that re-signs gets "Welcome back!" + subscription plans, no new trial.
2.4 Guided Setup (Tier-2 profiling, per-module)¶
Triggered on first module open. Max 2 questions, conversational, smart-default fallback. Tracked in LaivFirstInteractionService.
| Module | First-visit questions |
|---|---|
| Money | Pay cadence (weekly/biweekly/monthly) / monthly budget goal? |
| Wellbeing | Focus areas (sleep/nutrition/movement/mental/hydration) / health considerations |
| Focus | Short bursts (25 min) vs deep sessions (50+ min) |
| Projects | Board vs list / solo vs team |
| Events | Week starts Sunday or Monday |
| People | Import contacts or start fresh |
| Streams | Daily prompts vs freeform journaling |
| Sessions | Skills being built (multi-select) |
2.5 Contact Import → VIP → Family Group Chain¶
Contact import → VIP selection → relationship labels (family/partner/close friend/work/VIP) → priority notification tones → if 2+ labelled "family", Laiv offers Family Group auto-provision.
3. PROGRESSIVE PROFILING (Three Tiers)¶
- Tier 1 — Onboarding (§2.1): 8 fields, explicit.
- Tier 2 — First Module Interaction (§2.4): guided setup, max 2 per module, conversational, smart default on skip.
- Tier 3 — Behavioral Inference (Silent): Laiv infers preferences from usage. Minimum 3 data points before inference; soft confidence-scored preferences; visible in Settings → "What Laiv knows about me."
4. PROGRESSIVE INTERVIEW (Days 1–14) — MANDATORY¶
4.1 How It Works¶
Laiv weaves profiling questions into natural conversation across Days 1–14. 1–2 questions/day, asked during natural moments (Morning Pulse / Prism, Evening Wind Down, after task completion, during module exploration). There is no formal Day-14 questionnaire wall — it has been retired.
Full spec: PROGRESSIVE_INTERVIEW_DESIGN_SPEC.md (do not duplicate here).
4.2 Summary (built March 26, Gamma)¶
- 45 questions across 4 sources:
- Source A: 3 universal + 21 goal-specific (8 goals) = 24
- Source B: 14 per-module
- Source C: dynamic feature-feedback templates
- Source D: 7 fixed-day anchors (Days 3–14)
- 11 composite trait categories; Elite unlock = 6/11 traits populated OR Day 14 deterministic fallback.
- Files:
interview_question.dart(88 lines) ·interview_question_bank.dart(277) ·progressive_interview_service.dart(282) ·interview_card.dart(342). - Delivery points: Prism insight card (Morning Pulse), Evening Wind Down card.
- 31 tests, all passing. Zero hardcoded English (ARB across 21 locales).
Unverified claim (Omega v2.7): Layer 4 (Source D fixed-day questions appearing on schedule Days 1–14) needs device verification.
4.3 11 Trait Map (composite scoring)¶
Identity/Context · Financial Dimensions · Health & Wellness · Productivity & Focus · Relationships & Social · Life Management · Lifestyle & Values · Technology Comfort · Privacy Orientation · Commute/Mobility · Reflection/NPS.
4.4 Delivery Rules (GT #11 — Mandatory)¶
- No skip button, no cancel, no gesture dismiss. Only Source C feature-feedback nudges carry a "Not now" option.
- If ignored, Laiv re-asks at the next natural moment (next app open, next Morning Pulse, next Evening Wind Down).
- Max 2/day. Never stack 3+.
- Context-sensitive: Financial qs during Money module, Health qs during Wellbeing.
- Deflection caps: 3 attempts/question → marked declined. Global nudge cooldown 48 h. Lifetime nudges per module: 2.
- Laiv voice — never form-like. "Hey — quick one. How'd you sleep?"
- Progress invisible (no "12 of 45" counter).
- Stored in SharedPreferences
trait_{key}+ dimensional profile.
4.5 SaaS Tax Calculator (Question 17)¶
User taps competitor app icons from visual grid; each tap adds monthly price to running total. Laiv surfaces the comparison against alaivOS Core ($7.99/mo). Feeds the Day-21/28 conversion screen and the shareable savings card (§8.1). Competitor DB: PRICING_AND_TIERS.md §16 (2026 prices: Notion $12–24, Strava $11.99, Copilot Money $13, Duolingo $12.99–29.99, Readwise $12.99, 1Password $3.99–5.99). Typical 5-app stack = $63.98/mo; alaivOS Core replaces for $7.99 = savings $56/mo, $672/yr.
5. GHOST TRIAL MOMENT (Days 5–7)¶
Ghost is NOT available during trial. A single Ghost-powered insight is delivered surgically between Days 5–7 to show what Ghost can do. Card in Morning Pulse / Evening Wind Down with Ghost icon visible.
Laiv framing: "I did some extra research overnight through Ghost Protocol — here's what I found. [insight]. Ghost Protocol gives me access to a bigger brain and deeper research, all through your own private server."
Follow-up days later (casual): "I could tell you more, but I'd need Ghost Protocol to research it properly. Something to think about."
Cost: ~$0.08/trial-user weighted average. Gift, not entitlement.
6. LAIV CHECKUP — TRIAL CADENCE¶
Laiv Checkup is a 3-domain overnight analysis (Wellbeing, Planning, Financial). Pipeline: on-device anonymization strip → Ghost relay (CX43:8100) → Gemma 4 E4B secondary anonymization → Anthropic Batch API. Cost: ~$0.012/checkup.
Trial cadence (baked in, not credit-gated during trial)¶
| Moment | Day | Scope |
|---|---|---|
| Baseline | Day 0 (immediately after onboarding) | Planning domain only |
| Hints | Days 1–13 | Teaser hints between checkups (Beta-2 sprint) |
| Mid-trial | Day 14 | All 3 domains |
| Full | Day 28 | All 3 domains — FREE regardless of subscription |
Post-trial cadence by tier: Elite 1 mo · Pro 2 mo · Core 3 mo · Spark 6 mo · Starter none.
7. DAY-BY-DAY EXPERIENCE DESIGN¶
7.1 Day 0 — Install¶
- Morning install → onboarding → guided setup → Morning Pulse (if <11 AM) or dashboard.
- Afternoon/evening install → onboarding → guided setup → Evening Reflection (not next-day Morning Pulse; value TODAY).
- Day 0 Laiv Checkup baseline fires (Planning only).
7.2 Days 1–3 — On-Device Wow (100%)¶
Profile-dependent wow-moment selection from a library (meal planning + grocery + budget check for cooking mom, Smart Departure for commuter, first overspend alert, adaptive workout suggestion, Morning Pulse prioritization, etc.).
7.3 Days 3–5 — Cross-Module Intelligence¶
Laiv connects modules: "You have a dentist appointment Thursday and $45 left in your Health budget for the copay." Spine-level synthesis (4B model strength when device RAM allows).
7.4 Days 5–7 — Ghost Introduction¶
Single Ghost-powered insight (§5). Ghost icon visible but no ongoing access.
7.5 Days 7–14 — Deepening + Interview¶
Progressive interview accumulates dimensional data; Elite feature previews start surfacing as traits populate.
7.6 Day 14 — Elite Unlock Checkpoint (MANDATORY PHONE VERIFY)¶
See ANTI_ABUSE_SPEC.md v1.1.
Day 14:
Interview complete (6/11 traits) → Elite Unlock screen
VERIFY PHONE (Twilio) → Elite active for 7 more days
SKIP → Starter immediately (Pro trial ends Day 14)
Phone verification is mandatory to continue past Day 14. Purposes: 1. Anti-abuse — one phone = one trial (prevents eternal re-trialers). 2. Account security — enables family location sharing, account recovery.
Phone number is hashed (SHA-256, server-side salt). Raw number NEVER stored. Device ID fingerprinted silently at signup (separate from phone hash).
7.7 Days 14–21 — Elite Phase¶
Full Elite: adaptive scheduling, AI health insights, deep cross-module correlations, Ghost Protocol (Gemma 4 E4B, 50D/20I credit allotment), family location sharing, live-traffic coloring, multi-stop navigation. Laiv Checkup mid-trial (Day 14).
7.8 Day 21 — Trial Expiry (Investment Score)¶
Full-screen personalized conversion prompt showing concrete trial investment:
Your trial has ended.
In 21 days you've built:
📅 47 events 💰 $1,234 tracked
📝 23 notes 🗺️ 12 saved places
🤖 Laiv knows your 8 routines
Keep everything + unlock more — starting at $3.99/month
Investment score computed across 14 data sources, stored in trial_devices table for analytics.
7.9 Days 21–28 — Referral Bonus (verified phone only)¶
Non-blocking dashboard card. 1 friend = +2 · 2 = +4 · 3 = +7 Elite days.
7.10 Day 28 — Final Conversion¶
Tier cards with personalized recommendation (usage-based). Laiv Checkup Day 28 full run — FREE, regardless of subscription decision.
8. CONVERSION & RETENTION MECHANICS¶
8.1 Shareable Savings Card (sprint B-3)¶
Triggered by SaaS Tax Q17.
- Left: chaotic competitor icons + hefty price. Right: serene alaivOS + single price.
- Headline: "[Name] just reclaimed 30 hours of her life."
- Metrics: monthly savings · hours saved · apps replaced.
- Rendered via RepaintBoundary → toImage → share_plus.
- Aspect ratios: 9:16 (IG Stories), 16:9 (X), 1.91:1 (LinkedIn).
8.2 Referral System (sprint B-4)¶
Share via share_plus + url_launcher (WhatsApp/SMS/Signal/Email). Tracked in RevenueCat + Supabase referrals. Progressive rewards banked against Elite (not Pro): 1/2/3 friends = 2/4/7 Elite days.
8.3 Retention Milestones (Firebase events — already wired)¶
trial_started · trial_day_3 · trial_day_7 · trial_day_14 · interview_started · interview_completed · elite_unlocked · phone_verified · phone_skipped · referral_sent · referral_converted · trial_expired · conversion_shown · subscription_started.
8.4 Upgrade Hook — Voice Silence¶
Days 0–28: Laiv speaks in Piper Standard. Trial expires → Starter → voice goes silent (Starter = text only). Spark ($3.99/mo) brings voice back. Strongest single upgrade motivator in the app.
8.5 Anti-Abuse Integration Points¶
(Details in ANTI_ABUSE_SPEC.md — 7 layers.)
| Touchpoint | Enforcement |
|---|---|
| Signup | Device fingerprint check (silent) |
| Day 14 | Mandatory phone verify (SHA-256 hash) |
| Trial / Starter | No data export |
| Day 21 expiry | Investment score computed |
| Any tier | Behavioral detection (analytics-only) |
| Reinstall | Supabase user_profiles + trial_devices prevents new trial |
| Subpoena surface | Phone-hash + device-hash are confirm-match only, never reverse |
9. LAIV RULES OF ENGAGEMENT¶
The 14 Rules¶
- Laiv speaks, doesn't announce. "Your dentist is in 47 minutes — leave by 1:05." Not "I have calculated…"
- One input ripples across all modules. A grocery item touches Money, Events, Wellbeing.
- High visibility when required, zero when in the zone. Focus sessions = Laiv invisible; only emergencies break through.
- Defer by default. "I'll have this ready in your Morning Pulse." Never waste Instant credits on deferrables.
- Never explain what you're doing when you can just do it. "Done — $82.47 at HEB, 21 of 23 items."
- Errors are conversational. "Lost connection. I'll sync this when we're back."
- Suggestions never forced. Always offer "Proceed as planned." Null-safe on all dimensional inputs.
- Privacy is a gentleman's promise. "Stays on your device." Not legalese.
- Health data is sacred. Never synced. Never in Ghost prompts. Never shared with family unless per-field enabled.
- Emergency fallback is absolute. DDG + on-device always works. Never strand the user.
- Voice matches the moment. Morning energetic · Evening calm · Sick kid gentle · Budget crisis pragmatic.
- Contractions always. I'm / Let's / We'll / I've.
- Laiv never mentions infrastructure. No "DuckDuckGo", "Ghost server", "credits", "API."
- Invisible when possible. Best UX is when the user forgets Laiv is there.
Vocabulary¶
- Avoid: calibrate, parameters, system, metrics, user, input, optimize, leverage, utilize, facilitate.
- Use: fine-tune, set up, standards, your life, you, focus areas, adjust, build, handle, sort out.
Tone Matrix¶
| Situation | Tone |
|---|---|
| User oversleeps | Supportive: "Sleep was light — want me to shift deep work to tomorrow?" |
| Budget overspend | Pragmatic: "We're over on dining. Pull from vacation fund or trim next week's groceries?" |
| New project | Efficient: "Blocked the time, set aside the funds, added your collaborator." |
| Vacation detected | Relaxed: "Trip mode on. Habits paused. Enjoy." |
| User is busy | Invisible — silent notifications only. |
| Error | Conversational: "Lost connection. I'll sync when we're back online." |
10. STARTER-TIER NUDGE FLOW (post-expiry)¶
- Voice silent (Rule #8.4).
- Raw numbers only in notifications (Smart Flutter Responses tier-gated: Starter=raw, Spark+=category, Core+=follow-up).
- No data export.
- No Ghost credits.
- Gentle conversion surfaces in: Morning Pulse, Evening Wind Down, Settings → Plans, Day-28 card, SaaS Tax savings moment.
- No dark patterns, no timer pressure, no locked data — all local data remains the user's.
11. IMPLEMENTATION STATUS (April 13, 2026)¶
| Component | Status | Owner / Sprint |
|---|---|---|
| V21 10-step onboarding (NewOnboardingScreen) | ✅ Built | Sprint 10 / V21 |
| StaggeredFadeIn welcome | ✅ Built | Sprint 10 |
| Username catch-block fix (TAW10 BUG 1) | ✅ Built | Alpha-B TAW10 |
| 6 onboarding fields persisted to Supabase | ✅ Built | Alpha sprint 8 (Omega v2.7) |
| Reinstall recovery (skip onboarding on restored profile) | ✅ Built | TAW10-B + sprint 8 |
| TrialService (phase management, 7 AppTier values) | ✅ Built | Sprint G-2 |
| Feature gate enforcement (119 gates × 7 tiers) | ✅ Built | Sprints 8 + G-2 |
| Health disclaimer (7-layer framework) | ✅ Built | Beta legal |
| Piper TTS Standard (sherpa_onnx + hfc_female) | ✅ Built | Alpha Mar 26 |
| Progressive interview (45 Qs, 11 traits, GT #11-compliant) | ✅ Built | Gamma Mar 26 (31 tests) — Layer 4 needs device verify |
| Laiv Checkup (3 domains, Day 0/14/28 trial cadence) | ✅ Built | Alpha+Gamma+Beta-2 Omega v2.7 |
| Checkup hints (Days 1–13) | ✅ Built | Beta-2 Omega v2.7 |
| Smart Flutter Responses (10 handlers, tier-gated) | ✅ Built | Beta TAW10 |
| Device fingerprint at signup | ✅ Built | Anti-abuse sprint |
| Day-14 phone verify (SHA-256 hash, Twilio) | ⚠️ Code ready, blocked on Twilio signup | Alpha + J |
| Investment score at expiry | ✅ Built | Anti-abuse sprint |
| Shareable savings card | 🔲 Sprint pending | B-3 |
| Referral tracking + progressive rewards | 🔲 Sprint pending | B-4 |
| Day-28 conversion screen (tier recommendation) | 🔲 Sprint pending | G-4 |
| Contact import → VIP → Family Group chain | 🔲 Sprint pending | Spec ready |
| Ghost trial moment Days 5–7 orchestrator | 🔲 Sprint pending | Spec ready |
12. DECISION LOG (locked — do not override)¶
- Trial = 14 Pro + 7 Elite = 21 days guaranteed. Up to 28 with referrals.
- Progressive interview is mandatory — no skip/cancel/dismiss. 45 questions, 11 traits, Days 1–14.
- Day 14 phone verify is mandatory to unlock Elite. Skip = Starter immediately. Phone hash only, never raw.
- Device ID fingerprinted silently at signup.
- Day 0 Laiv Checkup baseline fires immediately after onboarding (Planning domain only).
- Day 28 Laiv Checkup is FREE regardless of subscription.
- Six onboarding fields persisted to Supabase
user_profilesfor reinstall recovery (plus existing name + username = 8 total). - Username check catch block returns true on RLS/unknown errors (TAW10 BUG 1 fix).
- No data export on Trial or Starter.
- Investment score computed at Day 21 expiry.
- Ghost trial moment = one insight, Days 5–7, Ghost icon visible. No ongoing Ghost access in trial.
- Voice silence on Starter post-expiry is the primary upgrade hook.
This document is the ONLY authoritative reference for trial structure, onboarding flow, progressive interview, Laiv Rules of Engagement, and conversion mechanics. If any other document contradicts this one, this document wins.