feat(onboarding): move phone verification before access key and remove for existing users

When PhoneNumberSend is enabled, new account creation now launches
verification with target=OnboardingFlow(AccessKey) so the user verifies
their phone before seeing the access key. Existing users (PostAccessKey)
skip verification entirely and go straight to permissions. Verification
gating logic moved from composable into LoginViewModel.

Author: bmc08gt

apps/flipcash/features/contact-verification/src/main/kotlin/com/flipcash/app/contact/verification/VerificationFlowScreen.kt

@@ -47,7 +47,7 @@ fun VerificationFlowScreen(
                 value = NavResultOrCanceled.ReturnValue(result),
             )
             if (route.target != null && result is VerificationResult.Success) {
-                outerNavigator.replace(route.target!!)
+                outerNavigator.replaceAll(route.target!!)
             } else {
                 outerNavigator.pop()
             }

apps/flipcash/features/contact-verification/src/main/kotlin/com/flipcash/app/contact/verification/email/EmailMagicLinkScreen.kt

@@ -47,7 +47,7 @@ fun EmailMagicLinkContent(
         horizontalAlignment = Alignment.CenterHorizontally,
     ) {
         AppBarWithTitle(
-            title = stringResource(R.string.title_verifyEmailAddress),
+            title = stringResource(R.string.title_connectEmailAddress),
             isInModal = true,
             titleAlignment = Alignment.CenterHorizontally,
             backButton = true,

apps/flipcash/features/contact-verification/src/main/kotlin/com/flipcash/app/contact/verification/email/EmailVerificationScreen.kt

@@ -43,7 +43,7 @@ fun EmailVerificationContent(
         horizontalAlignment = Alignment.CenterHorizontally,
     ) {
         AppBarWithTitle(
-            title = stringResource(R.string.title_verifyEmailAddress),
+            title = stringResource(R.string.title_connectEmailAddress),
             isInModal = true,
             titleAlignment = Alignment.CenterHorizontally,
             backButton = true,

apps/flipcash/features/contact-verification/src/main/kotlin/com/flipcash/app/contact/verification/internal/phone/PhoneEntryScreen.kt

@@ -11,17 +11,14 @@ import androidx.compose.foundation.layout.imePadding
 import androidx.compose.foundation.layout.navigationBars
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.windowInsetsPadding
-import androidx.compose.material.Text
+import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.LaunchedEffect
-import androidx.compose.runtime.SideEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.remember
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Alignment.Companion.Center
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.focus.FocusRequester
-import androidx.compose.ui.layout.onPlaced
 import androidx.compose.ui.platform.LocalFocusManager
 import androidx.compose.ui.res.stringResource
 import androidx.compose.ui.text.style.TextAlign

apps/flipcash/features/contact-verification/src/main/kotlin/com/flipcash/app/contact/verification/phone/PhoneVerificationScreen.kt

@@ -36,7 +36,7 @@ fun PhoneVerificationContent(isInModal: Boolean = true) {
         horizontalAlignment = Alignment.CenterHorizontally,
     ) {
         AppBarWithTitle(
-            title = stringResource(R.string.title_verifyPhoneNumber),
+            title = stringResource(R.string.title_connectPhoneNumber),
             isInModal = isInModal,
             titleAlignment = Alignment.CenterHorizontally,
             backButton = true,

apps/flipcash/features/login/src/main/kotlin/com/flipcash/app/login/OnboardingFlowScreen.kt

@@ -39,6 +39,7 @@ import com.flipcash.app.login.internal.screens.LoginRouterScreenContent
 import com.flipcash.app.login.internal.screens.SeedInputContent
 import com.flipcash.app.login.router.LoginViewModel
 import com.flipcash.app.login.internal.SeedInputViewModel
+import com.flipcash.app.permissions.asContactAccessHandle
 import com.flipcash.app.permissions.internal.contacts.ContactScreenContent
 import com.flipcash.app.permissions.internal.notifications.NotificationRationalePermissionContent
 import com.flipcash.app.permissions.internal.notifications.NotificationScreenContent
@@ -72,8 +73,8 @@ import kotlinx.coroutines.flow.onEach
  * ```
  * 1. New account (ResumePoint.Login → ProceedToVerification)
  *
- *    Start → AccessKey ──┬────────────→ Verification² → Contacts¹ → Notifications → Scanner
- *                         └→ Purchase ─┘
+ *    Start → Verification³ → AccessKey ──┬──→ Contacts¹ → Notifications → Scanner
+ *                                         └→ Purchase ─┘
  *
  * 2. Seed restore (ResumePoint.Login → LoggedIn via SeedInput)
  *
@@ -82,9 +83,8 @@ import kotlinx.coroutines.flow.onEach
  *
  * 3. App resume (ResumePoint.PostAccessKey)
  *
- *    ┬─ phone linked ──→ Notifications → Scanner
- *    └─ not linked ────→ Verification → Notifications → Scanner
- *    (contacts always skipped — existing users encounter contacts in-app)
+ *    → Notifications → Scanner
+ *    (contacts and verification skipped — existing users encounter these in-app)
  *
  * 4. Mid-flow resume (ResumePoint.AccessKey / AccessKeyThenPurchase)
  *
@@ -96,6 +96,8 @@ import kotlinx.coroutines.flow.onEach
  *   contacts are accessed via the system picker at call site (no READ_CONTACTS needed).
  *   Already-granted permissions are auto-skipped via [PermissionsPhaseFlowHost].
  * ² Verification is skipped if a phone number is already linked.
+ * ³ Phone verification is shown only when [FeatureFlag.PhoneNumberSend] is enabled
+ *   and no phone is linked. Uses `target` to replace nav stack with AccessKey on success.
  */
 @Composable
 fun OnboardingFlowScreen(
@@ -115,17 +117,14 @@ fun OnboardingFlowScreen(
 @Composable
 private fun CompleteExistingUserOnboarding() {
     val navigator = LocalCodeNavigator.current
-    val userManager = LocalUserManager.current!!
-    val userState by userManager.state.collectAsStateWithLifecycle()
-    val hasLinkedPhone = userState.userProfile?.verifiedPhoneNumber != null
 
     LaunchedEffect(Unit) {
-        val route = resolvePostAccountRoute(
-            result = OnboardingResult.ProceedToVerification,
-            hasLinkedPhone = hasLinkedPhone,
-            skipContacts = true,
+        navigator.replace(
+            AppRoute.OnboardingFlow(
+                phase = AppRoute.OnboardingFlow.Phase.Permissions,
+                skipContacts = true,
+            )
         )
-        route?.let { navigator.replace(it) }
     }
 }
 
@@ -306,7 +305,23 @@ private fun LoginStepContent(seed: String?) {
     LaunchedEffect(vm) {
         vm.eventFlow
             .filterIsInstance<LoginViewModel.Event.OnAccountCreated>()
-            .onEach { flowNavigator.navigateTo(OnboardingStep.AccessKey) }
+            .onEach {
+                if (state.needsPhoneVerification) {
+                    flowNavigator.navigate(
+                        AppRoute.Verification(
+                            origin = AppRoute.OnboardingFlow(),
+                            includePhone = true,
+                            includeEmail = false,
+                            target = AppRoute.OnboardingFlow(
+                                resumeAt = AppRoute.OnboardingFlow.ResumePoint.AccessKey,
+                            ),
+                            fullScreen = true,
+                        )
+                    )
+                } else {
+                    flowNavigator.navigateTo(OnboardingStep.AccessKey)
+                }
+            }
             .launchIn(this)
     }
 
@@ -402,8 +417,6 @@ private fun AccessKeyStepContent() {
         AppBarWithTitle(
             title = stringResource(R.string.title_accessKey),
             titleAlignment = Alignment.CenterHorizontally,
-            backButton = true,
-            onBackIconClicked = { flowNavigator.back() },
         )
         AccessKeyScreen(
             viewModel = viewModel,
@@ -415,6 +428,8 @@ private fun AccessKeyStepContent() {
                 flowNavigator.exitWithResult(OnboardingResult.ProceedToVerification)
             }
         }
+
+        BackHandler { /* swallow back during onboarding permissions */ }
     }
 }
 
@@ -432,12 +447,12 @@ private fun PurchaseStepContent() {
     }
 
     Column {
-        AppBarWithTitle(
-            backButton = true,
-            onBackIconClicked = { flowNavigator.back() },
-        )
+        AppBarWithTitle()
         PurchaseAccountScreenContent(state, viewModel::dispatchEvent)
     }
+
+
+    BackHandler { /* swallow back during onboarding permissions */ }
 }
 
 @Composable
@@ -458,7 +473,7 @@ private fun ContactPermissionStepContent() {
     }
 
     ContactScreenContent(
-        permissionState = permissionState,
+        accessHandle = permissionState.asContactAccessHandle(),
         onSkip = {
             analytics.action(Button.SkipContacts)
             flowNavigator.proceed()

apps/flipcash/features/login/src/main/kotlin/com/flipcash/app/login/router/LoginViewModel.kt

@@ -4,15 +4,19 @@ import androidx.lifecycle.viewModelScope
 import com.flipcash.app.analytics.Button
 import com.flipcash.app.analytics.FlipcashAnalyticsService
 import com.flipcash.app.auth.AuthManager
+import com.flipcash.app.featureflags.FeatureFlag
+import com.flipcash.app.featureflags.FeatureFlagController
 import com.flipcash.features.login.R
 import com.flipcash.services.controllers.AccountController
+import com.flipcash.services.user.UserManager
 import com.getcode.manager.BottomBarManager
 import com.getcode.util.resources.ResourceHelper
 import com.getcode.utils.encodeBase64
 import com.flipcash.libs.coroutines.DispatcherProvider
 import com.getcode.view.BaseViewModel
 import com.getcode.view.LoadingSuccessState
 import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.filterIsInstance
 import kotlinx.coroutines.flow.filterNot
@@ -29,6 +33,8 @@ class LoginViewModel @Inject constructor(
     private val accounts: AccountController,
     private val resources: ResourceHelper,
     private val analytics: FlipcashAnalyticsService,
+    userManager: UserManager,
+    featureFlags: FeatureFlagController,
     dispatchers: DispatcherProvider,
 ) : BaseViewModel<LoginViewModel.State, LoginViewModel.Event>(
     initialState = State(),
@@ -40,6 +46,7 @@ class LoginViewModel @Inject constructor(
         val loggingIn: LoadingSuccessState = LoadingSuccessState(),
         val logoTapCount: Int = 0,
         val betaOptionsVisible: Boolean = false,
+        val needsPhoneVerification: Boolean = false,
     )
 
     sealed interface Event {
@@ -53,9 +60,21 @@ class LoginViewModel @Inject constructor(
         data object LogInFailed : Event
         data object OnAccountCreated : Event
         data object CreateFailed : Event
+        data class PhoneVerificationUpdated(val needed: Boolean) : Event
     }
 
     init {
+        combine(
+            userManager.state,
+            featureFlags.observe(FeatureFlag.PhoneNumberSend),
+        ) { userState, phoneNumberSendFlag ->
+            val enabled = phoneNumberSendFlag || userState.flags?.enablePhoneNumberSend == true
+            val hasLinkedPhone = userState.userProfile?.verifiedPhoneNumber != null
+            enabled && !hasLinkedPhone
+        }.onEach { needed ->
+            dispatchEvent(Event.PhoneVerificationUpdated(needed))
+        }.launchIn(viewModelScope)
+
         eventFlow
             .filterIsInstance<Event.OnLogoTapped>()
             .map { stateFlow.value.logoTapCount }
@@ -188,6 +207,10 @@ class LoginViewModel @Inject constructor(
                         )
                     )
                 }
+
+                is Event.PhoneVerificationUpdated -> { state ->
+                    state.copy(needsPhoneVerification = event.needed)
+                }
             }
         }
     }

apps/flipcash/features/login/src/test/kotlin/com/flipcash/app/login/router/LoginViewModelErrorTest.kt

@@ -3,10 +3,12 @@ package com.flipcash.app.login.router
 import androidx.arch.core.executor.testing.InstantTaskExecutorRule
 import com.flipcash.app.analytics.FlipcashAnalyticsService
 import com.flipcash.app.auth.AuthManager
+import com.flipcash.app.featureflags.FeatureFlagController
 import com.flipcash.app.core.MainCoroutineRule
 import com.flipcash.app.core.dispatchers.TestDispatchers
 import com.flipcash.features.login.R
 import com.flipcash.services.controllers.AccountController
+import com.flipcash.services.user.UserManager
 import com.getcode.manager.BottomBarManager
 import com.getcode.util.resources.ResourceHelper
 import io.mockk.every
@@ -41,6 +43,8 @@ class LoginViewModelErrorTest {
     // MockK for everything else
     private val resources: ResourceHelper = mockk(relaxed = true)
     private val analytics: FlipcashAnalyticsService = mockk(relaxed = true)
+    private val userManager: UserManager = mockk(relaxed = true)
+    private val featureFlags: FeatureFlagController = mockk(relaxed = true)
 
     private lateinit var dispatchers: TestDispatchers
 
@@ -68,6 +72,8 @@ class LoginViewModelErrorTest {
             accounts = accounts,
             resources = resources,
             analytics = analytics,
+            userManager = userManager,
+            featureFlags = featureFlags,
             dispatchers = dispatchers,
         )
     }

services/flipcash/src/main/kotlin/com/flipcash/services/controllers/ContactVerificationController.kt

@@ -27,6 +27,13 @@ class ContactVerificationController @Inject constructor(
         val owner = userManager.accountCluster?.authority?.keyPair
             ?: return Result.failure(Throwable("No account cluster in UserManager"))
 
-        return repository.unlink(method, owner)
+        return repository.unlink(method, owner).onSuccess {
+            val profile = userManager.profile ?: return@onSuccess
+            val updated = when (method) {
+                is ContactMethod.Phone -> profile.copy(verifiedPhoneNumber = null)
+                is ContactMethod.Email -> profile.copy(verifiedEmailAddress = null)
+            }
+            userManager.set(updated)
+        }
     }
 }