feat(app): onboarding that ends in a first conversation (A/B), paywall re-ask on app open (A/B), Home live pill

[YinkaAdepoju]

Draft. Behind a PostHog A/B flag (onboarding-activation-flow, not created yet), so nothing changes for users until it's turned on. Every paywall goes through Nik's paywall experiment (#21450); the Superwall pilot is opt-in, iOS debug only.

Why

Device buyers who use Omi in their first days subscribe; most who don't subscribe barely use it and never see a paywall. The voice intro is the biggest drop inside onboarding. So: one clear use moment with a visible result, then a paywall for everyone, then a Home that isn't empty.

What changed

Onboarding (both arms)

• Opens straight on sign-in (no Get Started). Name opens with the keyboard; simpler permission toggles; language after permissions; attribution question removed.
• New Connect Omi step: pair in-page, or "I've ordered mine" / "Not ordered yet" (opens the store). The answer is tracked (Onboarding Device Choice), so we can finally see buyers we can't match by email.
• An Omi connected here gets the button tutorial right away.

New ending (activation arm)

• "Let's try Omi" → read three short sentences → live words → real summary and to-dos → "You're all set" → rating → paywall → Home.
• Phone dictation also saves the voice profile. Never stuck: silence or a failed start shows a clear Continue.

Home and Settings

• Bottom bar: Ask Omi + a live recording pill (Listening, newest words; tap for the transcript).
• First conversation and its to-dos (or starter tasks) waiting on Home; Omi's first chat message.
• Settings shows minutes and an Upgrade button directly (before: Settings → Plan → Upgrade).

Device-test fixes (Oct 14)

From a run on a real iPhone with live transcription:

• Dictation: read-along — the script lights up word by word with the voice (soft tick per word, waits on silence); Omi's sentences confirm it, or the person's own words ink in when they said something else. A live waveform shows Omi is listening.
• Summarizing: the words condense in the same card (filler folds away, key words draw together); the sparkle became three lines condensing into one. The card no longer jumps between the two steps.
• Summary: rises out of a blur; "Omi remembers so you don't have to" above the title; no "still writing your notes" line.
• Rating: moves on to the paywall under the App Store pop-up (iOS gives no close callback, so the screen used to stay up).
• Home: fades in after onboarding (a slide showed Home over Home).
• Buttons: every new-flow step's primary button sits 24pt above the home bar.
• Pull-to-refresh (Home, Tasks, iOS): a ring draws as you pull, ticks when armed, then spins.

A/B setup

• PostHog: draft experiment 482367 on flag onboarding-activation-flow (inactive until launched, so everyone gets control). 50/50 control (today's voice intro) / test (new ending), user-based.
• Exposure: the app turns off $feature_flag_called, so the experiment counts the custom event Onboarding Ending Shown, which now carries $feature/onboarding-activation-flow. People who fell back to control (no identity, slow read, error) carry no variant and stay out of the analysis.
• The arm is read at Connect Omi and saved per account, so a resumed onboarding keeps its arm.
• Primary metric: subscribed within 30 days. Subscriptions live in Stripe data, not app events, so the metric still has to be added (data owner's call). Guardrail: onboarding completion can't drop more than 2 points. Pre-registration: app/lib/services/experiments/onboarding_activation_flow.md.
• Launch only after a store build with this code ships.

Paywalls: built on #21450

Every upgrade entry point (end of the activation, Settings Upgrade, Plan & Usage, locked conversations and memories, chat quota, Plus meter) calls one helper, openUpgradePaywall: Superwall pilot when it's on → otherwise Nik's PaywallRouter (flag paywall-variant: control / outline / web) → otherwise the existing plans sheet. Paywall Opened is logged once per open; the web variant's fallback (forceNative) skips the router so it can't loop.

• End of onboarding: the activation ending's paywall asks the router first (so its arms and exposure count), then falls back to the onboarding plans sheet. The experiment's own end-of-onboarding placement is skipped when the ending already offered a plan, so nobody sees two paywalls in a row.
• Nik's web onboarding entry and debug onboarding rerun (OMI_ONBOARDING_RERUN=1) are kept.

Paywall re-ask on app open (A/B, flag paywall-reask)

Free users keep opening the app but rarely meet a paywall, because every paywall today waits for a limit. On launch or return to the app, a free user whose re-ask is due gets the usual paywall (same helper, so paywall-variant still picks the design), queued in PromptQueue so it never covers a recording, a call or another prompt.

• Schedule: 2, 3, 5, then every 7 calendar days after the last paywall seen from any source (a limit or Settings Upgrade restarts the clock). The first Home visit only starts the clock, so never on onboarding day; at most once a day; dropped if they subscribed meanwhile.
• A/B: control / test. Both arms are exposed ($feature_flag_called) at the same due moments; control shows nothing. New Paywall Opened source app_open_reask. Pre-registration: app/lib/services/experiments/paywall_reask.md (primary: Upgrade Succeeded within 14 days; guardrail: active days can't drop >5%).
• Not yet created in PostHog; until it is, nobody is in the experiment and nothing shows.

Superwall pilot (iOS debug, opt-in)

Named placements: device_setup_complete (end of onboarding), settings_upgrade, plus_meter, locked_content, usage_upgrade, chat_apps, chat_quota, transcription_settings_usage. Off unless a debug build passes --dart-define=SUPERWALL_TEST_MODE=true; anywhere it's off, the paywall experiment decides.

For production: Omi's own Superwall project (replaces the test key) with campaigns for these placements; the plans as in-app purchases in App Store Connect; backend reconciliation of purchases. See app/docs/superwall-pilot.md.

How to try it

flutter run --flavor dev (debug), as a new user: new ending + the paywall experiment's arm (control = plans sheet) by default.

• --dart-define=OMI_ONBOARDING_ENDING=control: old ending
• --dart-define=OMI_ACTIVATION_DEMO=1: scripted words on a simulator
• --dart-define=OMI_PAYWALL_VARIANT=outline (or web): force a paywall arm
• --dart-define=SUPERWALL_TEST_MODE=true: Superwall pilot paywall instead
• --dart-define=OMI_PAYWALL_REASK=test --dart-define=OMI_PAYWALL_REASK_NOW=true: re-ask on every app open

Risks / open

• fix(onboarding): Watch instructions layout, specific pairing errors, find-us fits on screen #21426 left out on purpose: its screens are replaced or removed here. Its pairing errors could come to Connect Omi later.
• Paywall ownership: main's paywall work (feat(mobile): define storefront presentation contract and paywall design #21354, feat(billing): plans sheet schema_version 2 #21397, feat(app): PostHog paywall A/B test (control / outline / web) + flag-gated web onboarding #21450) is merged in; every entry point now goes through feat(app): PostHog paywall A/B test (control / outline / web) + flag-gated web onboarding #21450's router. Superwall stays a debug-only pilot until Omi decides on its billing path.
• Rating ask inside onboarding (Guideline 5.6.3); attribution data lost; voice profile only from phone dictation.
• Still to test on device (Yinka): transcription in onboarding and the button tutorial after Connect Omi. The dictation, summary and to-dos have only run with scripted words (OMI_ACTIVATION_DEMO), because the local server has no speech-to-text. Next: a real phone run against a backend with live transcription.
• Not yet verified: real Omi pairing (and the button-tutorial handoff), real StoreKit prices.

Verified

• On the merge with main (incl. feat(app): PostHog paywall A/B test (control / outline / web) + flag-gated web onboarding #21450) + re-ask: flutter test test/widgets test/providers test/unit test/spine: 4,418 passed (1 skipped, as on main) before the re-ask; full suite on the re-ask commit: 4,425 passed (1 skipped); re-ask tests re-run after the schedule change: pass.
• scripts/pr-preflight --lane local: 31/31 checks pass.
• iOS simulator (iPhone 17 Pro, local server): activation → Outline paywall via the router; control → onboarding plans sheet → Home with no second paywall; Settings → Upgrade → Outline; re-ask on returning to the app; a plain build doesn't re-ask.

Screenshots (iOS simulator, debug build with scripted dictation)

Repo checks

Product invariants affected

• INV-DATA-1: main.dart only adds SuperwallPilot.configure() / syncUser(uid); routing unchanged, pilot inert outside iOS debug.
• INV-MEM-1: memory_item.dart routes the locked-memory upgrade through openUpgradePaywall (same source); storage unchanged.
• INV-CAP-1: capture_controller.dart adds an optional phoneMicAudioTap that gets a copy of phone-mic PCM; never consumes, delays or drops audio.

Line-count exceptions

Line-Count-Exception: app/lib/backend/preferences.dart | 1514 -> 1519 | one preference for the closable Home voice-profile card
Line-Count-Exception: app/lib/providers/device_provider.dart | 1488 -> 1504 | hold the firmware prompt during first-run onboarding and show it on Home
Line-Count-Exception: app/lib/utils/analytics/analytics_manager.dart | 3131 -> 3138 | one onboarding device-choice event for matching buyers to orders
Line-Count-Exception: app/lib/pages/settings/transcription_settings_page.dart | 1554 -> 1559 | Superwall placement name on the existing usage-page route

Failure class (fixes)

Failure-Class: none

🤖 Generated with Claude Code

[Git-on-my-level]

Thanks @YinkaAdepoju — this is a substantial, well-structured draft. The fail-closed experiment handling in app/lib/services/experiments/onboarding_activation_flow.dart (control on no-identity/timeout/error, per-account arm memory, debug override that can't reach store builds), the flag registration in config/feature-flags.yaml + backend/docs/feature-flag-registry.md with prereg and review date, the plans-sheet fallback in app/lib/pages/settings/widgets/upgrade_paywall.dart, and the guarded pilot in app/lib/services/superwall_pilot.dart (debug-only, serialized identity sync, 5-minute paywall timeout so onboarding can't hang) all look carefully built. The new app/docs/ux-contract.md permissions section matches permissions_widget.dart (answered-vs-granted semantics, orange/red states, onboarding/bluetoothAskedAtLaunch), and app/e2e/SKILL.md's new step map tracks the file changes.

Dependency note: superwallkit_flutter 2.6.0 is hosted on pub.dev with a pinned sha; Podfile.lock adds SuperwallKit 4.17.0 transitively. The embedded key is a public SDK key and the docs correctly forbid secrets — no integrity concern found there.

Leaving for human maintainer review — these are product decisions rather than code defects:

1. Monetization direction: the activation arm shows a paywall before Home for every new user. That's a strategy call the maintainers should make explicitly, not something review can settle.
2. Entry-point ownership vs main: feat(mobile): define storefront presentation contract and paywall design #21354 (contextual upsells) and feat(billing): plans sheet schema_version 2 #21397 (plans sheet v2) overlap the eight Superwall placements here. The PR's own "Risks / open" flags this — a ruling on which stack owns each upgrade entry point would unblock it.
3. New payments SDK: Superwall sign-off is needed even though it's debug-gated today (configure() requires kDebugMode && iOS && SUPERWALL_TEST_MODE).
4. UID sharing: SuperwallPilot.syncUser sends the Firebase UID to a third-party service — fine for a debug pilot, but worth an explicit OK for whenever the pilot widens.
5. Two acknowledged trade-offs: the in-onboarding rating ask (App Store 5.6.3) and the removal of the attribution survey.

Nothing verified as broken, so no change requests from me — the open-questions section is honest and the work is cohesive as one unit.

---

by AI on behalf of David — if you need David’s attention urgently, please @Git-on-my-level and escalate with need human response.

[Git-on-my-level]

Reviewed statically (draft, suspicious tier — no code executed). This is a big but coherent change — one product outcome (first-run ending in a first conversation, paywall experiment, Home live pill) — so I'm not asking for a split; feedback below is on substance.

What looks good, with specifics:

• app/lib/services/experiments/paywall_reask.dart: clean fail-closed design — no identity, unread flag, or any error returns false and exposes nobody; the first Home visit only starts the clock (never asks on onboarding day); control advances the same schedule so both arms are counted at the same moments. Schedule math (gapAfter/daysBetween/isDue) is straightforward and unit-tested in app/test/unit/paywall_reask_test.dart.
• app/lib/pages/settings/widgets/upgrade_paywall.dart: one entry point for every upgrade surface with ordered fallbacks (Superwall pilot → PaywallRouter variant → existing plans sheet) and a forceNative escape so the web variant's dead page can't loop back into itself.
• app/lib/pages/paywall/paywall_router.dart: PaywallReask.noteShown() on any router-shown paywall restarts the re-ask clock from any source; exposeControl() gives control-arm readers their exposure event at the same moment variants see a paywall — good experiment hygiene.
• app/lib/services/superwall_pilot.dart: configure() is inert unless kDebugMode + SUPERWALL_TEST_MODE + iOS; identity updates are serialized through a queue so an earlier identify can't finish last; showPlacementAndWait has a 5-minute timeout so an unreported close can't hang onboarding.
• app/lib/pages/onboarding/activation/activation_capture.dart: real capture pipeline reuse (device stream or phone mic), cancel-checked after each await so a Skip can't leave the mic recording behind the next screen, and voice-profile enrollment gated on minimum words/seconds so silence doesn't enroll a bad voiceprint.
• app/integration_test/app_performance_test.dart: find.text('Ask Omi') finders replaced with ValueKey('home_ask_omi_button') — more robust against localization.
• The l10n sweep across all .arb locales is consistent with the new onboarding strings, and a changelog fragment is present (app/changelog/unreleased/20261013-onboarding-redesign-first-conversation.json).

Things that need a maintainer decision before this leaves draft:

1. New third-party payment SDK. app/pubspec.yaml adds superwallkit_flutter ^2.6.0 direct (pub.dev, lockfile sha 22c9be1…), pulling native SuperwallKit 4.17.0 + Superscript into app/ios/Podfile.lock. Even though the pilot is iOS-debug-only, the native binary enters every iOS build. That plus item 2 is why dependency-review should stay on.
2. Default key and uid sharing. superwall_pilot.dart ships a source default public SDK key (pk_EA03…) pointing at a personal Superwall test project, and syncUser() identifies Firebase uids to it. Public SDK keys are designed to ship, but making a personal test project the in-repo default — and sending user identifiers to it, even debug-only — is a privacy/ownership call for a maintainer. If this lands, consider making the key dart-define-only with no default.
3. Product direction. The PR honestly flags these and they're real decisions: an App Store rating ask inside onboarding (Guideline 5.6.3 exposure), dropping the attribution survey, and a scheduled paywall re-ask for free users (2/3/5/7-day cadence). All are behind not-yet-created PostHog flags and fail closed, so nothing ships by accident — but whether Omi wants this monetization posture is a human call.
4. CI. No check runs are reported on this head, so the body's local "4,425 passed" claim is unverified here. Please make sure the PR is ready for CI (or rebase so checks trigger) before marking ready for review.
5. Overlap with fix(onboarding): Watch instructions layout, specific pairing errors, find-us fits on screen #21426: its screens are removed here; the pairing-error improvements it carries would be lost. Worth an explicit ruling on that PR (supersede/extract) so it doesn't linger.

Agent-guidance docs note: this PR rewrites app/e2e/SKILL.md's onboarding tree, adds app/docs/superwall-pilot.md, and extends app/docs/ux-contract.md — all docs that AI coding/review agents in this repo follow. I checked them against the diff and they match the new code (step order, flag names, key-handling rules); the Superwall doc's "never commit a private key" guidance is accurate and safe. Just be aware these now describe a flow that differs from main until this merges, and superwall-pilot.md documents a billing pilot whose adoption is still open.

Thanks @YinkaAdepoju — the engineering discipline here is genuinely good (fail-closed flags, both-arm exposure, fallback chains, tests per new service). Leaving for human maintainer review: the new payment SDK dependency + uid-sharing default need maintainer sign-off, and the onboarding/paywall product direction (rating placement, re-ask cadence, #21426 supersession) is a product decision, not a code-correctness one.

--
Automated maintainer feedback on behalf of the Omi maintainers. AI-generated review; human maintainers make the final call.

---

by AI on behalf of David — if you need David’s attention urgently, please @Git-on-my-level and escalate with need human response.

[YinkaAdepoju]

Closing in favour of two smaller pieces: the onboarding itself landed as the yinka arm of the onboarding experiment in #21650 (thanks @kodjima33), and the rest (Home redesign, Tasks, sign-in, upgrade entry points) is rebased on main in draft #21711. The Superwall pilot is dropped in favour of #21450's paywall router.

[github-actions]

Hey @YinkaAdepoju 👋

Thank you so much for taking the time to contribute to Omi! We truly appreciate you putting in the effort to submit this pull request.

After careful review, we've decided not to merge this particular PR. Please don't take this personally — we genuinely try to merge as many contributions as possible, but sometimes we have to make tough calls based on:

• Project standards — Ensuring consistency across the codebase
• User needs — Making sure changes align with what our users need
• Code best practices — Maintaining code quality and maintainability
• Project direction — Keeping aligned with our product principles and locked invariants

Before your next PR, please skim:

• PRODUCT.md — product north star
• Product invariants — locked rules (shared chat, memory tiers, agent control plane, integrations, brand)

If this was declined for direction or taste, maintainers should cite an invariant ID or open a proposed one — ask if that citation is missing.

Your contribution is still valuable to us, and we'd love to see you contribute again in the future! If you'd like feedback on how to improve this PR or want to discuss alternative approaches, please don't hesitate to reach out.

Thank you for being part of the Omi community!