From 9467c80e867cbb7b9064818b964e662d25953a2f Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Wed, 15 Jul 2026 19:25:48 -0400
Subject: [PATCH 1/2] fix(account): support sign in or account creation

---
 .../components/account/AccountPage.test.tsx   |  44 ++++++
 .../components/account/AccountPage.tsx        |  51 ++-----
 .../renderer/components/app/TabNav.test.tsx   |   2 +-
 .../src/renderer/components/app/TabNav.tsx    |   6 +-
 apps/ios/ADE.xcodeproj/project.pbxproj        |   8 ++
 .../ADE/Services/AccountEmailAuthFlow.swift   |  59 ++++++++
 apps/ios/ADE/Services/AccountService.swift    |  68 +++++++--
 .../Account/AccountConnectionsSection.swift   |  14 +-
 .../ADE/Views/Account/AccountSignInView.swift |  22 +--
 .../ADETests/AccountEmailAuthFlowTests.swift  | 134 ++++++++++++++++++
 docs/ARCHITECTURE.md                          |   2 +-
 .../sync-and-multi-device/ios-companion.md    |  11 ++
 12 files changed, 351 insertions(+), 70 deletions(-)
 create mode 100644 apps/desktop/src/renderer/components/account/AccountPage.test.tsx
 create mode 100644 apps/ios/ADE/Services/AccountEmailAuthFlow.swift
 create mode 100644 apps/ios/ADETests/AccountEmailAuthFlowTests.swift

diff --git a/apps/desktop/src/renderer/components/account/AccountPage.test.tsx b/apps/desktop/src/renderer/components/account/AccountPage.test.tsx
new file mode 100644
index 000000000..63417f03d
--- /dev/null
+++ b/apps/desktop/src/renderer/components/account/AccountPage.test.tsx
@@ -0,0 +1,44 @@
+/* @vitest-environment jsdom */
+
+import React from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { SignInCard } from "./AccountPage";
+
+const beginLogin = vi.fn(async () => undefined);
+
+vi.mock("../../lib/accountLogin", () => ({
+  useAccountLogin: () => ({
+    phase: "idle",
+    error: null,
+    beginLogin,
+    cancel: vi.fn(),
+  }),
+}));
+
+describe("AccountPage signed-out card", () => {
+  afterEach(() => {
+    cleanup();
+    beginLogin.mockClear();
+  });
+
+  it("presents one truthful browser action with combined account language", () => {
+    render(<SignInCard configured onSignedIn={vi.fn()} />);
+
+    expect(screen.getByText("Continue to ADE")).toBeTruthy();
+    expect(screen.getByText(/account is created automatically/i)).toBeTruthy();
+    expect(screen.getByText(/browser page offers the sign-in methods enabled for ADE/i)).toBeTruthy();
+    expect(screen.queryByRole("button", { name: /Continue with/i })).toBeNull();
+
+    fireEvent.click(screen.getByRole("button", { name: "Continue in browser" }));
+    expect(beginLogin).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps local pairing explicitly available without an account", () => {
+    render(<SignInCard configured={false} onSignedIn={vi.fn()} />);
+
+    expect(screen.getByText(/Account access isn't set up on this machine yet/i)).toBeTruthy();
+    expect(screen.getByText("Local pairing works without an account.")).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Continue in browser" }).hasAttribute("disabled")).toBe(true);
+  });
+});
diff --git a/apps/desktop/src/renderer/components/account/AccountPage.tsx b/apps/desktop/src/renderer/components/account/AccountPage.tsx
index 1cb177546..b9882dd64 100644
--- a/apps/desktop/src/renderer/components/account/AccountPage.tsx
+++ b/apps/desktop/src/renderer/components/account/AccountPage.tsx
@@ -1,14 +1,11 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { useNavigate } from "react-router-dom";
 import {
-  AppleLogo,
   ArrowRight,
   CircleNotch,
   DesktopTower,
   DeviceMobile,
-  EnvelopeSimple,
   GithubLogo,
-  GoogleLogo,
   Laptop,
   ShieldCheck,
   SignOut,
@@ -98,7 +95,7 @@ const sectionLabelStyle: CSSProperties = {
 // Signed-out: the rich sign-in card.
 // ---------------------------------------------------------------------------
 
-function SignInCard({
+export function SignInCard({
   configured,
   onSignedIn,
 }: {
@@ -110,21 +107,15 @@ function SignInCard({
   });
   const busy = phase === "starting" || phase === "awaiting";
 
-  const secondary: Array<{ label: string; icon: JSX.Element }> = [
-    { label: "Email", icon: <EnvelopeSimple size={15} weight="regular" /> },
-    { label: "Apple", icon: <AppleLogo size={15} weight="fill" /> },
-    { label: "Google", icon: <GoogleLogo size={15} weight="bold" /> },
-  ];
-
   return (
     <div style={cardStyle({ padding: 28, maxWidth: 440, width: "100%" })}>
       <div style={{ display: "flex", flexDirection: "column", gap: 6, textAlign: "center", alignItems: "center" }}>
         <img src="./logo.png" alt="ADE" style={{ height: 26, opacity: 0.95 }} draggable={false} />
         <div style={{ fontFamily: SANS_FONT, fontSize: 19, fontWeight: 700, color: COLORS.textPrimary, marginTop: 6 }}>
-          Sign in to ADE
+          Continue to ADE
         </div>
         <div style={{ fontFamily: SANS_FONT, fontSize: 13, lineHeight: 1.5, color: COLORS.textSecondary, maxWidth: 320 }}>
-          One identity for your machines, mobile, and web sessions — so they find each other wherever you are.
+          Choose a sign-in method in your browser. If you're new, your ADE account is created automatically.
         </div>
       </div>
 
@@ -147,7 +138,7 @@ function SignInCard({
         >
           <WarningCircle size={16} weight="fill" color={COLORS.warning} style={{ flexShrink: 0, marginTop: 1 }} />
           <span>
-            Account sign-in isn't set up on this machine yet. You can still pair machines, phones, and web
+            Account access isn't set up on this machine yet. You can still pair machines, phones, and web
             clients from <strong style={{ color: COLORS.textPrimary }}>Connections</strong>.
           </span>
         </div>
@@ -170,35 +161,11 @@ function SignInCard({
             }),
           }}
         >
-          {busy ? <CircleNotch size={16} weight="bold" className="animate-spin" /> : <GithubLogo size={17} weight="fill" />}
-          Continue with GitHub
+          {busy ? <CircleNotch size={16} weight="bold" className="animate-spin" /> : <ArrowRight size={17} weight="bold" />}
+          Continue in browser
         </button>
-
-        <div style={{ display: "flex", alignItems: "center", gap: 10, color: COLORS.textDim }}>
-          <div style={{ flex: 1, height: 1, background: COLORS.borderMuted }} />
-          <span style={{ fontFamily: SANS_FONT, fontSize: 11 }}>or continue with</span>
-          <div style={{ flex: 1, height: 1, background: COLORS.borderMuted }} />
-        </div>
-
-        <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr 1fr", gap: 8 }}>
-          {secondary.map((option) => (
-            <button
-              key={option.label}
-              type="button"
-              disabled={busy || !configured}
-              onClick={() => void beginLogin()}
-              style={outlineButton({
-                height: 38,
-                gap: 6,
-                fontSize: 12,
-                opacity: busy || !configured ? 0.55 : 1,
-                cursor: busy || !configured ? "not-allowed" : "pointer",
-              })}
-            >
-              {option.icon}
-              {option.label}
-            </button>
-          ))}
+        <div style={{ fontFamily: SANS_FONT, fontSize: 12, lineHeight: 1.5, textAlign: "center", color: COLORS.textMuted }}>
+          The browser page offers the sign-in methods enabled for ADE.
         </div>
       </div>
 
@@ -218,7 +185,7 @@ function SignInCard({
         >
           <span style={{ display: "flex", alignItems: "center", gap: 8, fontFamily: SANS_FONT, fontSize: 12, color: COLORS.textSecondary }}>
             <CircleNotch size={14} weight="bold" className="animate-spin" />
-            Finish signing in in your browser…
+            Finish in your browser…
           </span>
           <button
             type="button"
diff --git a/apps/desktop/src/renderer/components/app/TabNav.test.tsx b/apps/desktop/src/renderer/components/app/TabNav.test.tsx
index 4dac45ea0..3aa75aaea 100644
--- a/apps/desktop/src/renderer/components/app/TabNav.test.tsx
+++ b/apps/desktop/src/renderer/components/app/TabNav.test.tsx
@@ -75,7 +75,7 @@ describe("TabNav", () => {
       </MemoryRouter>,
     );
 
-    expect(screen.getByRole("link", { name: "Sign in to ADE" }).getAttribute("href")).toBe(
+    expect(screen.getByRole("link", { name: "Continue to ADE" }).getAttribute("href")).toBe(
       "/account",
     );
   });
diff --git a/apps/desktop/src/renderer/components/app/TabNav.tsx b/apps/desktop/src/renderer/components/app/TabNav.tsx
index d756457a1..c25a7cf04 100644
--- a/apps/desktop/src/renderer/components/app/TabNav.tsx
+++ b/apps/desktop/src/renderer/components/app/TabNav.tsx
@@ -123,7 +123,7 @@ export function TabNav({ githubStatus }: { githubStatus?: GitHubStatus | null })
     accountStatus.name?.trim() ||
     accountStatus.email?.trim() ||
     githubLogin ||
-    (accountStatus.signedIn ? "Account" : "Sign in");
+    (accountStatus.signedIn ? "Account" : "Continue");
   const accountRouteActive =
     location.pathname === "/account" || location.pathname.startsWith("/account/");
 
@@ -333,7 +333,7 @@ export function TabNav({ githubStatus }: { githubStatus?: GitHubStatus | null })
         </SmartTooltip>
 
         {/* Account avatar — provider-aware image → monogram, routes to /account.
-            Always present so sign-in stays discoverable from the sidebar. */}
+            Always present so account access stays discoverable from the sidebar. */}
         <NavLink
           to="/account"
           data-active={accountRouteActive ? "true" : undefined}
@@ -341,7 +341,7 @@ export function TabNav({ githubStatus }: { githubStatus?: GitHubStatus | null })
           aria-label={
             accountStatus.signedIn
               ? `ADE account — ${accountLabel}`
-              : "Sign in to ADE"
+              : "Continue to ADE"
           }
           title={accountLabel}
         >
diff --git a/apps/ios/ADE.xcodeproj/project.pbxproj b/apps/ios/ADE.xcodeproj/project.pbxproj
index f6b94473e..4db30c182 100644
--- a/apps/ios/ADE.xcodeproj/project.pbxproj
+++ b/apps/ios/ADE.xcodeproj/project.pbxproj
@@ -178,6 +178,8 @@
 		AD0000000000000000000B02 /* AccountDirectory.swift in Sources */ = {isa = PBXBuildFile; fileRef = AD0000000000000000000A02 /* AccountDirectory.swift */; };
 		AD0000000000000000000B03 /* AccountSignInView.swift in Sources */ = {isa = PBXBuildFile; fileRef = AD0000000000000000000A03 /* AccountSignInView.swift */; };
 		AD0000000000000000000B04 /* AccountConnectionsSection.swift in Sources */ = {isa = PBXBuildFile; fileRef = AD0000000000000000000A04 /* AccountConnectionsSection.swift */; };
+		AD0000000000000000000B05 /* AccountEmailAuthFlow.swift in Sources */ = {isa = PBXBuildFile; fileRef = AD0000000000000000000A05 /* AccountEmailAuthFlow.swift */; };
+		AD0000000000000000000B06 /* AccountEmailAuthFlowTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = AD0000000000000000000A06 /* AccountEmailAuthFlowTests.swift */; };
 		F10000000000000000000004 /* SettingsPinSheet.swift in Sources */ = {isa = PBXBuildFile; fileRef = F20000000000000000000004 /* SettingsPinSheet.swift */; };
 		F10000000000000000000005 /* SettingsAppearanceSection.swift in Sources */ = {isa = PBXBuildFile; fileRef = F20000000000000000000005 /* SettingsAppearanceSection.swift */; };
 		F10000000000000000000006 /* SettingsDiagnosticsSection.swift in Sources */ = {isa = PBXBuildFile; fileRef = F20000000000000000000006 /* SettingsDiagnosticsSection.swift */; };
@@ -452,6 +454,8 @@
 		AD0000000000000000000A02 /* AccountDirectory.swift */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.swift; name = AccountDirectory.swift; path = ADE/Services/AccountDirectory.swift; sourceTree = "<group>"; };
 		AD0000000000000000000A03 /* AccountSignInView.swift */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.swift; name = AccountSignInView.swift; path = ADE/Views/Account/AccountSignInView.swift; sourceTree = "<group>"; };
 		AD0000000000000000000A04 /* AccountConnectionsSection.swift */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.swift; name = AccountConnectionsSection.swift; path = ADE/Views/Account/AccountConnectionsSection.swift; sourceTree = "<group>"; };
+		AD0000000000000000000A05 /* AccountEmailAuthFlow.swift */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.swift; name = AccountEmailAuthFlow.swift; path = ADE/Services/AccountEmailAuthFlow.swift; sourceTree = "<group>"; };
+		AD0000000000000000000A06 /* AccountEmailAuthFlowTests.swift */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.swift; name = AccountEmailAuthFlowTests.swift; path = ADETests/AccountEmailAuthFlowTests.swift; sourceTree = "<group>"; };
 		F20000000000000000000004 /* SettingsPinSheet.swift */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.swift; name = SettingsPinSheet.swift; path = ADE/Views/Settings/SettingsPinSheet.swift; sourceTree = "<group>"; };
 		F20000000000000000000005 /* SettingsAppearanceSection.swift */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.swift; name = SettingsAppearanceSection.swift; path = ADE/Views/Settings/SettingsAppearanceSection.swift; sourceTree = "<group>"; };
 		F20000000000000000000006 /* SettingsDiagnosticsSection.swift */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.swift; name = SettingsDiagnosticsSection.swift; path = ADE/Views/Settings/SettingsDiagnosticsSection.swift; sourceTree = "<group>"; };
@@ -833,6 +837,7 @@
 				AF00000000000000000000A2 /* PairingQrPayload.swift */,
 				AC1000000000000000000006 /* ClipPairingHandoff.swift */,
 				AD0000000000000000000A01 /* AccountService.swift */,
+				AD0000000000000000000A05 /* AccountEmailAuthFlow.swift */,
 				AD0000000000000000000A02 /* AccountDirectory.swift */,
 				B34C6C526E3BBB1E720C8D7C /* Dictation */,
 			);
@@ -981,6 +986,7 @@
 			isa = PBXGroup;
 			children = (
 				14C0DF7FEB4C2EB854BAC888 /* ADETests.swift */,
+				AD0000000000000000000A06 /* AccountEmailAuthFlowTests.swift */,
 				B70000000000000000000003 /* SyncRecoveryPolicyTests.swift */,
 				AF00000000000000000000A4 /* PairingAndDpopTests.swift */,
 				AC1000000000000000000008 /* ClipPairingHandoffTests.swift */,
@@ -1340,6 +1346,7 @@
 				F10000000000000000000002 /* SettingsConnectionHeader.swift in Sources */,
 				F10000000000000000000003 /* SettingsPairingSection.swift in Sources */,
 				AD0000000000000000000B01 /* AccountService.swift in Sources */,
+				AD0000000000000000000B05 /* AccountEmailAuthFlow.swift in Sources */,
 				AD0000000000000000000B02 /* AccountDirectory.swift in Sources */,
 				AD0000000000000000000B03 /* AccountSignInView.swift in Sources */,
 				AD0000000000000000000B04 /* AccountConnectionsSection.swift in Sources */,
@@ -1454,6 +1461,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				7B70BE6839672E5D2D006B28 /* ADETests.swift in Sources */,
+				AD0000000000000000000B06 /* AccountEmailAuthFlowTests.swift in Sources */,
 				B70000000000000000000004 /* SyncRecoveryPolicyTests.swift in Sources */,
 				AF00000000000000000000C4 /* PairingAndDpopTests.swift in Sources */,
 				AC1100000000000000000008 /* ClipPairingHandoffTests.swift in Sources */,
diff --git a/apps/ios/ADE/Services/AccountEmailAuthFlow.swift b/apps/ios/ADE/Services/AccountEmailAuthFlow.swift
new file mode 100644
index 000000000..a71071913
--- /dev/null
+++ b/apps/ios/ADE/Services/AccountEmailAuthFlow.swift
@@ -0,0 +1,59 @@
+import ClerkKit
+import Foundation
+
+enum AccountEmailVerificationKind: Equatable {
+  case signIn
+  case signUp
+}
+
+struct AccountEmailAuthActions {
+  var startSignIn: @MainActor (String) async throws -> Void
+  var startSignUp: @MainActor (String) async throws -> Void
+  var verifySignIn: @MainActor (String) async throws -> Void
+  var verifySignUp: @MainActor (String) async throws -> Void
+}
+
+@MainActor
+enum AccountEmailAuthFlow {
+  private static let accountNotFoundCodes: Set<String> = [
+    "form_identifier_not_found",
+    "invitation_account_not_exists",
+  ]
+
+  static func shouldBeginSignUp(after error: Error) -> Bool {
+    guard let clerkError = error as? ClerkAPIError else { return false }
+    return isAccountNotFoundCode(clerkError.code)
+  }
+
+  static func isAccountNotFoundCode(_ code: String) -> Bool {
+    accountNotFoundCodes.contains(code)
+  }
+
+  static func sendCode(
+    to email: String,
+    actions: AccountEmailAuthActions,
+    shouldBeginSignUp: @MainActor (Error) -> Bool = AccountEmailAuthFlow.shouldBeginSignUp(after:)
+  ) async throws -> AccountEmailVerificationKind {
+    do {
+      try await actions.startSignIn(email)
+      return .signIn
+    } catch {
+      guard shouldBeginSignUp(error) else { throw error }
+      try await actions.startSignUp(email)
+      return .signUp
+    }
+  }
+
+  static func verifyCode(
+    _ code: String,
+    kind: AccountEmailVerificationKind,
+    actions: AccountEmailAuthActions
+  ) async throws {
+    switch kind {
+    case .signIn:
+      try await actions.verifySignIn(code)
+    case .signUp:
+      try await actions.verifySignUp(code)
+    }
+  }
+}
diff --git a/apps/ios/ADE/Services/AccountService.swift b/apps/ios/ADE/Services/AccountService.swift
index 6c70351b1..81dd8394d 100644
--- a/apps/ios/ADE/Services/AccountService.swift
+++ b/apps/ios/ADE/Services/AccountService.swift
@@ -44,6 +44,12 @@ struct AccountIdentity: Equatable {
   }
 }
 
+enum AccountAuthenticationOutcome: Equatable {
+  case newAccount
+  case returningUser
+  case unknown
+}
+
 /// Wraps ClerkKit behind the app's `ObservableObject` convention so SwiftUI
 /// surfaces observe published state instead of the `@Observable` `Clerk` type
 /// directly. Owns configuration, session restore, the sign-in/out operations,
@@ -75,11 +81,13 @@ final class AccountService: ObservableObject {
   @Published private(set) var identity: AccountIdentity?
   @Published private(set) var machines: [AccountMachine] = []
   @Published private(set) var machinesState: MachinesState = .idle
+  @Published private(set) var authenticationOutcome: AccountAuthenticationOutcome = .unknown
   /// Transient, user-facing error from the last sign-in attempt.
   @Published var lastError: String?
 
   private var didConfigure = false
   private var eventTask: Task<Void, Never>?
+  private var emailVerificationKind: AccountEmailVerificationKind?
   private let directory = AccountDirectoryClient()
 
   var isConfigured: Bool { phase != .unconfigured }
@@ -143,24 +151,33 @@ final class AccountService: ObservableObject {
 
   // MARK: - Sign in
 
-  /// Start an email sign-in: creates the attempt and sends a one-time code.
+  /// Start an email sign-in-or-sign-up attempt and send a one-time code.
   func sendEmailCode(to email: String) async throws {
     let trimmed = email.trimmingCharacters(in: .whitespacesAndNewlines)
     guard trimmed.contains("@") else {
       throw AccountError.message("Enter a valid email address.")
     }
     lastError = nil
-    _ = try await Clerk.shared.auth.signInWithEmailCode(emailAddress: trimmed)
+    emailVerificationKind = nil
+    emailVerificationKind = try await AccountEmailAuthFlow.sendCode(
+      to: trimmed,
+      actions: emailAuthActions()
+    )
   }
 
-  /// Verify the emailed code, completing the sign-in when it matches.
+  /// Verify the emailed code against the attempt that sent it.
   func verifyEmailCode(_ code: String) async throws {
     let trimmed = code.trimmingCharacters(in: .whitespacesAndNewlines)
-    guard let signIn = Clerk.shared.auth.currentSignIn else {
-      throw AccountError.message("Start the email sign-in again.")
+    guard let emailVerificationKind else {
+      throw AccountError.message("Start the email verification again.")
     }
     lastError = nil
-    _ = try await signIn.verifyCode(trimmed)
+    try await AccountEmailAuthFlow.verifyCode(
+      trimmed,
+      kind: emailVerificationKind,
+      actions: emailAuthActions()
+    )
+    authenticationOutcome = emailVerificationKind == .signUp ? .newAccount : .returningUser
     syncFromClerk()
   }
 
@@ -168,7 +185,8 @@ final class AccountService: ObservableObject {
   /// supplies the presentation anchor and handles the redirect callback.
   func signInWithOAuth(_ provider: OAuthProvider) async throws {
     lastError = nil
-    _ = try await Clerk.shared.auth.signInWithOAuth(provider: provider)
+    let result = try await Clerk.shared.auth.signInWithOAuth(provider: provider)
+    authenticationOutcome = Self.outcome(from: result)
     syncFromClerk()
   }
 
@@ -177,7 +195,8 @@ final class AccountService: ObservableObject {
   /// and in a simulator signed into an Apple ID.
   func signInWithApple() async throws {
     lastError = nil
-    _ = try await Clerk.shared.auth.signInWithApple()
+    let result = try await Clerk.shared.auth.signInWithApple()
+    authenticationOutcome = Self.outcome(from: result)
     syncFromClerk()
   }
 
@@ -187,6 +206,8 @@ final class AccountService: ObservableObject {
     } catch {
       // Even if the network revoke fails, drop local state below.
     }
+    authenticationOutcome = .unknown
+    emailVerificationKind = nil
     syncFromClerk()
   }
 
@@ -231,6 +252,37 @@ final class AccountService: ObservableObject {
 
   // MARK: - Identity mapping
 
+  private func emailAuthActions() -> AccountEmailAuthActions {
+    AccountEmailAuthActions(
+      startSignIn: { email in
+        _ = try await Clerk.shared.auth.signInWithEmailCode(emailAddress: email)
+      },
+      startSignUp: { email in
+        let signUp = try await Clerk.shared.auth.signUp(emailAddress: email)
+        _ = try await signUp.sendEmailCode()
+      },
+      verifySignIn: { code in
+        guard let signIn = Clerk.shared.auth.currentSignIn else {
+          throw AccountError.message("Start the email verification again.")
+        }
+        _ = try await signIn.verifyCode(code)
+      },
+      verifySignUp: { code in
+        guard let signUp = Clerk.shared.auth.currentSignUp else {
+          throw AccountError.message("Start the email verification again.")
+        }
+        _ = try await signUp.verifyEmailCode(code)
+      }
+    )
+  }
+
+  private static func outcome(from result: TransferFlowResult) -> AccountAuthenticationOutcome {
+    switch result {
+    case .signIn: return .returningUser
+    case .signUp: return .newAccount
+    }
+  }
+
   private static func identity(from user: User) -> AccountIdentity {
     let first = user.firstName?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
     let last = user.lastName?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
diff --git a/apps/ios/ADE/Views/Account/AccountConnectionsSection.swift b/apps/ios/ADE/Views/Account/AccountConnectionsSection.swift
index db7be2c2d..ec83dd260 100644
--- a/apps/ios/ADE/Views/Account/AccountConnectionsSection.swift
+++ b/apps/ios/ADE/Views/Account/AccountConnectionsSection.swift
@@ -1,7 +1,7 @@
 import SwiftUI
 
 /// ACCOUNT subsection for the connection settings screen. Signed out, it shows a
-/// quiet sign-in prompt; signed in, it shows the identity card plus "Your
+/// quiet account prompt; signed in, it shows the identity card plus "Your
 /// machines" from the directory Worker. It sits above the local MACHINE pairing
 /// rows so the two ways to reach a machine — your account, or direct pairing —
 /// read as one connections surface. Hidden entirely when no Clerk key is wired.
@@ -18,7 +18,7 @@ struct AccountConnectionsSection: View {
         VStack(alignment: .leading, spacing: 12) {
           SettingsSectionHeader(
             label: "ACCOUNT",
-            hint: account.isSignedIn ? "Your machines, from anywhere" : "Sign in to find your machines"
+            hint: account.isSignedIn ? "Your machines, from anywhere" : "Continue to find your machines"
           )
 
           switch account.phase {
@@ -45,7 +45,7 @@ struct AccountConnectionsSection: View {
   }
 }
 
-// MARK: - Sign-in prompt (signed out)
+// MARK: - Account prompt (signed out)
 
 struct AccountSignInPromptCard: View {
   let onSignIn: () -> Void
@@ -61,7 +61,7 @@ struct AccountSignInPromptCard: View {
           .glassEffect(in: .rect(cornerRadius: 11))
 
         VStack(alignment: .leading, spacing: 3) {
-          Text("Sign in to ADE")
+          Text("Continue to ADE")
             .font(.headline)
             .foregroundStyle(ADEColor.textPrimary)
           Text("See every machine on your account and connect with one tap.")
@@ -73,17 +73,17 @@ struct AccountSignInPromptCard: View {
       }
 
       Button(action: onSignIn) {
-        Text("Sign in")
+        Text("Continue")
           .font(.subheadline.weight(.semibold))
           .frame(maxWidth: .infinity)
-          .padding(.vertical, 11)
+          .frame(minHeight: 44)
       }
       .buttonStyle(.glassProminent)
       .tint(ADEColor.accent)
     }
     .adeGlassCard()
     .accessibilityElement(children: .combine)
-    .accessibilityLabel("Sign in to ADE to see your machines")
+    .accessibilityLabel("Continue to ADE to see your machines")
   }
 }
 
diff --git a/apps/ios/ADE/Views/Account/AccountSignInView.swift b/apps/ios/ADE/Views/Account/AccountSignInView.swift
index 645bcf1b8..04dd935d7 100644
--- a/apps/ios/ADE/Views/Account/AccountSignInView.swift
+++ b/apps/ios/ADE/Views/Account/AccountSignInView.swift
@@ -1,8 +1,8 @@
 import ClerkKit
 import SwiftUI
 
-/// Native sign-in flow matching `ADEDesignSystem`. Covers email one-time-code,
-/// Sign in with Apple, Google, and GitHub. On success it presents the first-run
+/// Native account flow matching `ADEDesignSystem`. Covers email one-time-code,
+/// Apple, Google, and GitHub. On success it presents the first-run
 /// "here are your machines" step so a fresh login lands directly on connect.
 ///
 /// Structurally close to ClerkKit's `AuthView` (identifier-first, then a
@@ -60,11 +60,11 @@ struct AccountSignInView: View {
             Image(systemName: "xmark")
               .font(.system(size: 13, weight: .semibold))
           }
-          .accessibilityLabel(step == .machines ? "Done" : "Close sign in")
+          .accessibilityLabel(step == .machines ? "Done" : "Close")
         }
       }
       .onChange(of: account.phase) { _, newValue in
-        // A completed sign-in (from any provider) advances to the first-run
+        // A completed authentication (from any provider) advances to the
         // machines step.
         if newValue == .signedIn, step != .machines {
           step = .machines
@@ -107,16 +107,21 @@ struct AccountSignInView: View {
 
   private var headerTitle: String {
     switch step {
-    case .identifier: return "Sign in to ADE"
+    case .identifier: return "Continue to ADE"
     case .emailCode: return "Check your email"
-    case .machines: return "You're in"
+    case .machines:
+      switch account.authenticationOutcome {
+      case .newAccount: return "Your ADE account is ready"
+      case .returningUser: return "Welcome back"
+      case .unknown: return "You're in"
+      }
     }
   }
 
   private var headerSubtitle: String {
     switch step {
     case .identifier:
-      return "Reach your machines from anywhere and keep them in one account."
+      return "Choose a method below. If you're new, we'll create your account automatically."
     case .emailCode:
       return "Enter the 6-digit code we sent to \(email)."
     case .machines:
@@ -209,7 +214,7 @@ struct AccountSignInView: View {
       .adeInsetField()
 
       primaryButton(
-        title: "Verify & sign in",
+        title: "Verify code",
         isBusy: busy == .verify,
         disabled: code.trimmingCharacters(in: .whitespaces).count < 4
       ) {
@@ -225,6 +230,7 @@ struct AccountSignInView: View {
       }
       .font(.caption.weight(.medium))
       .foregroundStyle(ADEColor.textSecondary)
+      .frame(minHeight: 44)
 
       errorView
     }
diff --git a/apps/ios/ADETests/AccountEmailAuthFlowTests.swift b/apps/ios/ADETests/AccountEmailAuthFlowTests.swift
new file mode 100644
index 000000000..95d26d23a
--- /dev/null
+++ b/apps/ios/ADETests/AccountEmailAuthFlowTests.swift
@@ -0,0 +1,134 @@
+import ClerkKit
+import Foundation
+import XCTest
+@testable import ADE
+
+@MainActor
+final class AccountEmailAuthFlowTests: XCTestCase {
+  private enum TestError: Error {
+    case unavailable
+  }
+
+  private func clerkError(code: String) throws -> ClerkAPIError {
+    let data = Data(#"{"code":"\#(code)","message":"Test error"}"#.utf8)
+    return try JSONDecoder().decode(ClerkAPIError.self, from: data)
+  }
+
+  private final class ActionsSpy {
+    var signInError: Error?
+    private(set) var calls: [String] = []
+
+    func actions() -> AccountEmailAuthActions {
+      AccountEmailAuthActions(
+        startSignIn: { [self] email in
+          calls.append("startSignIn:\(email)")
+          if let signInError { throw signInError }
+        },
+        startSignUp: { [self] email in
+          calls.append("startSignUp:\(email)")
+        },
+        verifySignIn: { [self] code in
+          calls.append("verifySignIn:\(code)")
+        },
+        verifySignUp: { [self] code in
+          calls.append("verifySignUp:\(code)")
+        }
+      )
+    }
+  }
+
+  func testReturningEmailStartsSignInAndVerifiesExistingAccount() async throws {
+    let spy = ActionsSpy()
+
+    let kind = try await AccountEmailAuthFlow.sendCode(
+      to: "returning@example.com",
+      actions: spy.actions()
+    )
+
+    XCTAssertEqual(kind, .signIn)
+    XCTAssertEqual(spy.calls, ["startSignIn:returning@example.com"])
+    try await AccountEmailAuthFlow.verifyCode("654321", kind: kind, actions: spy.actions())
+    XCTAssertEqual(spy.calls, [
+      "startSignIn:returning@example.com",
+      "verifySignIn:654321",
+    ])
+  }
+
+  func testNewEmailFallsBackToSignUpAndVerifiesSignUpCode() async throws {
+    let spy = ActionsSpy()
+    spy.signInError = try clerkError(code: "form_identifier_not_found")
+
+    let kind = try await AccountEmailAuthFlow.sendCode(
+      to: "new@example.com",
+      actions: spy.actions()
+    )
+
+    XCTAssertEqual(kind, .signUp)
+    XCTAssertEqual(spy.calls, [
+      "startSignIn:new@example.com",
+      "startSignUp:new@example.com",
+    ])
+    try await AccountEmailAuthFlow.verifyCode("123456", kind: kind, actions: spy.actions())
+    XCTAssertEqual(spy.calls, [
+      "startSignIn:new@example.com",
+      "startSignUp:new@example.com",
+      "verifySignUp:123456",
+    ])
+  }
+
+  func testBothClerkAccountNotFoundCodesAllowSignUpFallback() async throws {
+    for code in ["form_identifier_not_found", "invitation_account_not_exists"] {
+      let spy = ActionsSpy()
+      spy.signInError = try clerkError(code: code)
+
+      let kind = try await AccountEmailAuthFlow.sendCode(
+        to: "new@example.com",
+        actions: spy.actions()
+      )
+
+      XCTAssertEqual(kind, .signUp)
+      XCTAssertEqual(spy.calls, [
+        "startSignIn:new@example.com",
+        "startSignUp:new@example.com",
+      ])
+    }
+  }
+
+  func testUnrelatedClerkErrorDoesNotStartSignUp() async throws {
+    let spy = ActionsSpy()
+    spy.signInError = try clerkError(code: "too_many_requests")
+
+    do {
+      _ = try await AccountEmailAuthFlow.sendCode(
+        to: "existing@example.com",
+        actions: spy.actions()
+      )
+      XCTFail("Expected the unrelated Clerk error to be preserved")
+    } catch let error as ClerkAPIError {
+      XCTAssertEqual(error.code, "too_many_requests")
+      XCTAssertEqual(spy.calls, ["startSignIn:existing@example.com"])
+      XCTAssertFalse(spy.calls.contains { $0.hasPrefix("startSignUp:") })
+    } catch {
+      XCTFail("Expected ClerkAPIError, got \(error)")
+    }
+  }
+
+  func testNonClerkErrorDoesNotStartSignUp() async {
+    let spy = ActionsSpy()
+    spy.signInError = TestError.unavailable
+
+    do {
+      _ = try await AccountEmailAuthFlow.sendCode(
+        to: "existing@example.com",
+        actions: spy.actions()
+      )
+      XCTFail("Expected the original non-Clerk error to be preserved")
+    } catch TestError.unavailable {
+      XCTAssertEqual(spy.calls, ["startSignIn:existing@example.com"])
+      XCTAssertEqual(spy.calls.count, 1)
+      XCTAssertFalse(spy.calls.contains { $0.hasPrefix("startSignUp:") })
+    } catch {
+      XCTFail("Expected TestError.unavailable, got \(error)")
+    }
+  }
+}
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index fa15c5aae..f7e8dd886 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -137,7 +137,7 @@ Product positioning and workflows live in [`docs/PRD.md`](../docs/PRD.md). This
 
 **Session identity.** The runtime resolves caller role from ADE context env vars and command flags. Role vocabulary: `cto`, `orchestrator`, `agent`, `external`, `evaluator`. Browser automation adds a separate bearer capability: ADE-launched chat and owned-terminal environments receive an opaque `ADE_BROWSER_ACTOR_TOKEN` bound in Electron memory to that chat's trusted lane/project or personal tab collection. The runtime requires the token, strips caller-supplied routing, and carries it only over the authenticated desktop bridge. Electron validates it in the same process that issued it before restoring the bound scope; role alone never grants access to a human-authenticated browser profile.
 
-**Optional ADE account auth.** `ade login` preserves the local-browser loopback OAuth path, but selects the account-directory device authorization bridge for explicit `--headless`, SSH, display-less hosts, or a failed browser launch. The brain generates and retains the device redemption secret, polls the bridge, and persists the resulting refresh-capable session under `account.session.v1`. `ADE_ACCOUNT_TOKEN` takes precedence without starting a login flow: JWT access credentials are used through their declared expiry, while refresh credentials are exchanged and rotated only in memory. `ade account token create` wraps the current interactive refresh credential with its public issuer/client context in a versioned secret envelope, so a newly provisioned agent or CI host needs no local Clerk configuration. Legacy raw opaque refresh tokens retain local-config compatibility and return migration guidance when that config is absent. Account status exposes `loopback`, `device`, or `env-token`; signed-out state never gates local projects, `ade code`, or PIN workflows.
+**Optional ADE account auth.** `ade login` preserves the local-browser loopback OAuth path, but selects the account-directory device authorization bridge for explicit `--headless`, SSH, display-less hosts, or a failed browser launch. The brain generates and retains the device redemption secret, polls the bridge, and persists the resulting refresh-capable session under `account.session.v1`. `ADE_ACCOUNT_TOKEN` takes precedence without starting a login flow: JWT access credentials are used through their declared expiry, while refresh credentials are exchanged and rotated only in memory. `ade account token create` wraps the current interactive refresh credential with its public issuer/client context in a versioned secret envelope, so a newly provisioned agent or CI host needs no local Clerk configuration. Legacy raw opaque refresh tokens retain local-config compatibility and return migration guidance when that config is absent. The desktop Account page exposes one honest browser continuation because the bridge opens the generic hosted account flow rather than selecting a provider; the browser presents whichever methods are enabled. Native iOS uses ClerkKit's transferable OAuth result to distinguish new accounts from returning users. Its identifier-first email path starts sign-in, falls back to sign-up only for Clerk's precise account-not-found codes, sends the sign-up email verification code, and verifies against the matching sign-in or sign-up attempt. Account status exposes `loopback`, `device`, or `env-token`; signed-out state never gates local projects, `ade code`, local pairing, or PIN workflows.
 
 **Action surface.** First-class command families cover lanes (including `ade lanes link-linear-issue` / `detach-linear-issue` for post-creation Linear issue linking, and `ade lanes create-from-linear` / `batch-create-from-linear` to spin up one or many issue lanes — optionally launching an agent chat with `--start-chat`), git, diffs, files, PRs, runs, shells, chats (including `ade chat create --prompt` for a persistent Work chat followed by an initial chat message, `ade chat send` / `message` / `steer` / `wait` for peer chat delivery and status polling, `ade chat read <session>` for recent transcript messages, `ade chat create --from-linear-issue <id>`, `ade chat attach-linear-issue` / `detach-linear-issue` / `linear-issues` for session-scoped issue attachment, and `--parent <sessionId>` / `--no-parent` to control child-chat lineage — a chat created via `ade chat create` / `ade new --mode chat` defaults its parent to `$ADE_CHAT_SESSION_ID` (the spawning agent's own chat, injected into every tracked agent shell) so it lists in the parent's subagents panel instead of becoming an orphan, and `--no-parent` opts out), agents, CTO, Linear (the write bridge an attached CLI agent uses: `ade linear attach` / `detach` / `issues` / `issue` / `comment` / `set-state` / `assign` / `label`, with `--this-session` resolving the issue id from `$ADE_LINEAR_ISSUE_IDS` so a launched agent needs no Linear token — see [features/linear-integration/README.md](./features/linear-integration/README.md#session-scoped-issue-attachment-and-cli-context-injection)), tests, proof, settings, the iOS Simulator (`ade ios-sim` / `ade ios` / `ade simulator` — see [features/ios-simulator/README.md](./features/ios-simulator/README.md)), the Cursor Cloud bridge (`ade cursor cloud agents | runs | artifacts | repos | models | me` — talks directly to `@cursor/sdk` without going through the ADE runtime endpoint), the App Control bridge for Electron apps (`ade app-control` / `ade app` / `ade electron` — `launch`, `connect`, `stop`, `status`, `screenshot`, `snapshot`, `inspect`, `select`, `click`, `type`, `scroll`, `key`, `targets`, `attach`, `logs`, `terminal write`, `terminal signal` — see [features/computer-use/app-control.md](./features/computer-use/app-control.md)), the chat-scoped terminal (`ade terminal list` / `read` / `write` / `signal` / `active`), universal search (`ade search "<query>"` over chats, terminals, PRs, commits, branches, lanes, files, and Linear — see [features/search/README.md](./features/search/README.md)), and a generic `ade actions run <domain.action>` escape hatch for every registered ADE service action. The chat action surface includes `chat.createSession`, `chat.sendMessage` (low-level normal-turn send), `chat.messageSession` (normalized peer delivery: auto, queue, wake, interrupt-replace), `chat.readTranscript`, and model-catalog actions; session-bound non-CTO callers are restricted to their own chat for `chat.sendMessage` and `chat.readTranscript`, while `chat.messageSession` is the reviewed primitive for deliberately messaging another ADE chat through routing semantics. The action allow-list adds three domains for these surfaces: `app_control` (every public method on `AppControlService`), `terminal` (`list`, `read`, `write`, `signal`, `activeForChat` against `ptyService`), named iOS Simulator actions for launch, live view, inspection, input, and Preview Lab workflows, and `search` (`query`, `indexStatus`, and the CTO-only `rebuildIndex` against `searchService`; session-bound non-CTO callers get chat/terminal hits scoped to their own session).
 
diff --git a/docs/features/sync-and-multi-device/ios-companion.md b/docs/features/sync-and-multi-device/ios-companion.md
index bf2cd71ab..03993757b 100644
--- a/docs/features/sync-and-multi-device/ios-companion.md
+++ b/docs/features/sync-and-multi-device/ios-companion.md
@@ -117,6 +117,12 @@ apps/ios/
 │   │   ├── DatabaseBootstrap.sql    # generated from desktop kvDb.ts
 │   │   └── VoiceGlossary.json       # shared dictation cleanup glossary
 │   ├── Services/
+│   │   ├── AccountService.swift     # Clerk-backed optional account identity,
+│   │   │                            # transferable social auth outcomes, and
+│   │   │                            # account-directory machine lookup
+│   │   ├── AccountEmailAuthFlow.swift # identifier-first email sign-in-or-up:
+│   │   │                              # precise account-not-found fallback and
+│   │   │                              # matching attempt verification
 │   │   ├── Database.swift           # SQLite + pure-SQL CRR + offline caches
 │   │   ├── KeychainService.swift    # paired device secret storage
 │   │   ├── DpopKeyService.swift     # Secure Enclave P-256 key + signed
@@ -265,6 +271,9 @@ apps/ios/
 │   │   │                            # SettingsPinSheet, SettingsPushDeliverySection
 │   │   │                            #   (push + Live Activity diagnostics/toggles),
 │   │   │                            # SettingsVoiceInputSection
+│   │   ├── Account/                 # AccountSignInView and account connection
+│   │   │                            # cards; account access is optional and
+│   │   │                            # does not gate direct machine pairing
 │   │   └── LanesTabView.swift
 │   └── Assets.xcassets/             # App icon, brand mark, provider logos
 │                                    # (Anthropic, Claude, Codex, Cursor,
@@ -277,6 +286,8 @@ apps/ios/
 │                                    # presentation for active agent runs
 └── ADETests/
     ├── ADETests.swift
+    ├── AccountEmailAuthFlowTests.swift # returning email sign-in, new-email
+    │                                   # sign-up fallback, exact error codes
     └── PairingAndDpopTests.swift    # smart-URL QR parse + DPoP proof tests
 ```
 

From 5432052cb8a13f45c26ea375d130b2cca5489226 Mon Sep 17 00:00:00 2001
From: Arul Sharma <31745423+arul28@users.noreply.github.com>
Date: Wed, 15 Jul 2026 19:57:48 -0400
Subject: [PATCH 2/2] docs(account): clarify email auth flow contracts

---
 apps/ios/ADE/Services/AccountEmailAuthFlow.swift | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/apps/ios/ADE/Services/AccountEmailAuthFlow.swift b/apps/ios/ADE/Services/AccountEmailAuthFlow.swift
index a71071913..33df35822 100644
--- a/apps/ios/ADE/Services/AccountEmailAuthFlow.swift
+++ b/apps/ios/ADE/Services/AccountEmailAuthFlow.swift
@@ -1,11 +1,13 @@
 import ClerkKit
 import Foundation
 
+/// Identifies which Clerk flow owns the pending email verification code.
 enum AccountEmailVerificationKind: Equatable {
   case signIn
   case signUp
 }
 
+/// Clerk operations used to start and finish either email authentication path.
 struct AccountEmailAuthActions {
   var startSignIn: @MainActor (String) async throws -> Void
   var startSignUp: @MainActor (String) async throws -> Void
@@ -13,6 +15,7 @@ struct AccountEmailAuthActions {
   var verifySignUp: @MainActor (String) async throws -> Void
 }
 
+/// Routes email authentication between returning-user sign-in and precise new-user fallback.
 @MainActor
 enum AccountEmailAuthFlow {
   private static let accountNotFoundCodes: Set<String> = [
@@ -20,15 +23,18 @@ enum AccountEmailAuthFlow {
     "invitation_account_not_exists",
   ]
 
+  /// Returns true only for Clerk errors that explicitly mean the identifier has no account.
   static func shouldBeginSignUp(after error: Error) -> Bool {
     guard let clerkError = error as? ClerkAPIError else { return false }
     return isAccountNotFoundCode(clerkError.code)
   }
 
+  /// Classifies Clerk's exact account-not-found error codes without broadening the fallback.
   static func isAccountNotFoundCode(_ code: String) -> Bool {
     accountNotFoundCodes.contains(code)
   }
 
+  /// Starts sign-in first, falling back to sign-up only when the supplied classifier allows it.
   static func sendCode(
     to email: String,
     actions: AccountEmailAuthActions,
@@ -44,6 +50,7 @@ enum AccountEmailAuthFlow {
     }
   }
 
+  /// Verifies the code against the same Clerk flow that issued it.
   static func verifyCode(
     _ code: String,
     kind: AccountEmailVerificationKind,