app/src/androidTest/kotlin/org/libremail/ui/onboarding/OnboardingFlowTest.kt

@@ -286,4 +286,21 @@ class OnboardingFlowTest {
         composeTestRule.onNodeWithText(string(R.string.app_password_open_page, "iCloud Mail"))
             .assertIsDisplayed()
     }
+
+    @Test
+    fun appPasswordSetup_showsAccountPasswordDisclaimerNearField() {
+        setOnboardingContent(FakeAccountRepository(), FakeMailRepository())
+
+        composeTestRule.onNodeWithText(string(R.string.onboarding_add_account)).performClick()
+        waitForText("Gmail")
+        composeTestRule.onNodeWithText("Gmail").performClick()
+
+        // Issue #160: new users unfamiliar with app passwords commonly try their regular account
+        // password first. The disclaimer must render as supporting text directly under the "App
+        // password" field itself (not only in the intro InfoCards above), on every preset provider
+        // screen since they all share this composable.
+        waitForText(string(R.string.app_password_field))
+        composeTestRule.onNodeWithText(string(R.string.app_password_field_disclaimer))
+            .performScrollTo().assertIsDisplayed()
+    }
 }

app/src/main/kotlin/org/libremail/ui/accountsetup/AppPasswordSetupScreen.kt

@@ -188,6 +188,7 @@ fun AppPasswordSetupScreen(
                 singleLine = true,
                 visualTransformation = PasswordVisualTransformation(),
                 keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
+                supportingText = { Text(stringResource(R.string.app_password_field_disclaimer)) },
                 modifier = Modifier.fillMaxWidth(),
             )
 

app/src/main/res/values/strings.xml

@@ -213,6 +213,7 @@
     <string name="app_password_open_failed">Couldn\'t open your browser</string>
     <string name="app_password_email">Email address</string>
     <string name="app_password_field">App password</string>
+    <string name="app_password_field_disclaimer">Do not try to use your account password. It will not work. You must use an app password.</string>
     <string name="app_password_show_servers">Server settings</string>
     <string name="app_password_server_imap">Incoming (IMAP): %1$s:%2$d (%3$s)</string>
     <string name="app_password_server_smtp">Outgoing (SMTP): %1$s:%2$d (%3$s)</string>