Close all 25 codex audit findings across KMP, iOS, and Android

Remediate all P0-S priority findings from cross-platform architecture audit:
- Harden token storage with EncryptedSharedPreferences (Android) and Keychain (iOS)
- Add SSL pinning and certificate validation to API clients
- Fix subscription cache race conditions and add thread-safe access
- Add input validation for document uploads and file type restrictions
- Refactor DocumentApi to use proper multipart upload flow
- Add rate limiting awareness and retry logic to API layer
- Harden subscription tier enforcement in SubscriptionHelper
- Add biometric prompt for sensitive actions (Login, Onboarding)
- Fix notification permission handling and device registration
- Add UI test infrastructure (page objects, fixtures, smoke tests)
- Add CI workflow for mobile builds

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

iosApp/CaseraUITests/CriticalPath/SmokeTests.swift

@@ -0,0 +1,120 @@
+import XCTest
+
+/// Smoke tests - run on every PR. Must complete in <2 minutes.
+///
+/// Tests that the app launches successfully, the auth screen renders correctly,
+/// and core navigation is functional. These are the minimum-viability tests
+/// that must pass before any PR can merge.
+final class SmokeTests: XCTestCase {
+    var app: XCUIApplication!
+
+    override func setUp() {
+        super.setUp()
+        continueAfterFailure = false
+        app = TestLaunchConfig.launchApp()
+    }
+
+    override func tearDown() {
+        app = nil
+        super.tearDown()
+    }
+
+    // MARK: - App Launch
+
+    func testAppLaunches() {
+        // App should show either login screen or main tab view
+        let loginScreen = LoginScreen(app: app)
+        let mainScreen = MainTabScreen(app: app)
+
+        let loginAppeared = loginScreen.emailField.waitForExistence(timeout: 15)
+        let mainAppeared = mainScreen.residencesTab.waitForExistence(timeout: 5)
+
+        XCTAssertTrue(loginAppeared || mainAppeared, "App should show login or main screen on launch")
+    }
+
+    // MARK: - Login Screen Elements
+
+    func testLoginScreenElements() {
+        let login = LoginScreen(app: app)
+        guard login.emailField.waitForExistence(timeout: 15) else {
+            // Already logged in, skip this test
+            return
+        }
+
+        XCTAssertTrue(login.emailField.exists, "Email field should exist")
+        XCTAssertTrue(login.passwordField.exists, "Password field should exist")
+        XCTAssertTrue(login.loginButton.exists, "Login button should exist")
+    }
+
+    // MARK: - Login Flow
+
+    func testLoginWithExistingCredentials() {
+        let login = LoginScreen(app: app)
+        guard login.emailField.waitForExistence(timeout: 15) else {
+            // Already on main screen - verify tabs
+            let main = MainTabScreen(app: app)
+            XCTAssertTrue(main.isDisplayed, "Main tabs should be visible")
+            return
+        }
+
+        // Login with the known test user
+        let user = TestFixtures.TestUser.existing
+        login.login(email: user.email, password: user.password)
+
+        let main = MainTabScreen(app: app)
+        XCTAssertTrue(main.residencesTab.waitForExistence(timeout: 15), "Should navigate to main screen after login")
+    }
+
+    // MARK: - Tab Navigation
+
+    func testMainTabsExistAfterLogin() {
+        let login = LoginScreen(app: app)
+        if login.emailField.waitForExistence(timeout: 15) {
+            // Need to login first
+            let user = TestFixtures.TestUser.existing
+            login.login(email: user.email, password: user.password)
+        }
+
+        let main = MainTabScreen(app: app)
+        guard main.residencesTab.waitForExistence(timeout: 15) else {
+            XCTFail("Main screen did not appear")
+            return
+        }
+
+        XCTAssertTrue(main.residencesTab.exists, "Residences tab should exist")
+        XCTAssertTrue(main.tasksTab.exists, "Tasks tab should exist")
+        XCTAssertTrue(main.contractorsTab.exists, "Contractors tab should exist")
+        XCTAssertTrue(main.documentsTab.exists, "Documents tab should exist")
+        XCTAssertTrue(main.profileTab.exists, "Profile tab should exist")
+    }
+
+    func testTabNavigation() {
+        let login = LoginScreen(app: app)
+        if login.emailField.waitForExistence(timeout: 15) {
+            let user = TestFixtures.TestUser.existing
+            login.login(email: user.email, password: user.password)
+        }
+
+        let main = MainTabScreen(app: app)
+        guard main.residencesTab.waitForExistence(timeout: 15) else {
+            XCTFail("Main screen did not appear")
+            return
+        }
+
+        // Navigate through each tab and verify selection
+        main.goToTasks()
+        XCTAssertTrue(main.tasksTab.isSelected, "Tasks tab should be selected")
+
+        main.goToContractors()
+        XCTAssertTrue(main.contractorsTab.isSelected, "Contractors tab should be selected")
+
+        main.goToDocuments()
+        XCTAssertTrue(main.documentsTab.isSelected, "Documents tab should be selected")
+
+        main.goToProfile()
+        XCTAssertTrue(main.profileTab.isSelected, "Profile tab should be selected")
+
+        main.goToResidences()
+        XCTAssertTrue(main.residencesTab.isSelected, "Residences tab should be selected")
+    }
+}

iosApp/CaseraUITests/Fixtures/TestFixtures.swift

@@ -0,0 +1,120 @@
+import Foundation
+
+/// Reusable test data builders for UI tests.
+///
+/// Each fixture generates unique names using random numbers or UUIDs
+/// to ensure test isolation and prevent cross-test interference.
+enum TestFixtures {
+
+    // MARK: - Users
+
+    struct TestUser {
+        let firstName: String
+        let lastName: String
+        let email: String
+        let password: String
+
+        /// Standard test user with unique email.
+        static let standard = TestUser(
+            firstName: "Test",
+            lastName: "User",
+            email: "uitest_\(UUID().uuidString.prefix(8))@test.com",
+            password: "TestPassword123!"
+        )
+
+        /// Secondary test user for multi-user scenarios.
+        static let secondary = TestUser(
+            firstName: "Second",
+            lastName: "Tester",
+            email: "uitest2_\(UUID().uuidString.prefix(8))@test.com",
+            password: "TestPassword456!"
+        )
+
+        /// Pre-existing test user with known credentials (must exist on backend).
+        static let existing = TestUser(
+            firstName: "Test",
+            lastName: "User",
+            email: "testuser",
+            password: "TestPass123!"
+        )
+    }
+
+    // MARK: - Residences
+
+    struct TestResidence {
+        let name: String
+        let address: String
+        let type: String
+
+        static let house = TestResidence(
+            name: "Test House \(Int.random(in: 1000...9999))",
+            address: "123 Test St",
+            type: "House"
+        )
+
+        static let apartment = TestResidence(
+            name: "Test Apt \(Int.random(in: 1000...9999))",
+            address: "456 Mock Ave",
+            type: "Apartment"
+        )
+    }
+
+    // MARK: - Tasks
+
+    struct TestTask {
+        let title: String
+        let description: String
+        let priority: String
+        let category: String
+
+        static let basic = TestTask(
+            title: "Test Task \(Int.random(in: 1000...9999))",
+            description: "A test task",
+            priority: "Medium",
+            category: "Cleaning"
+        )
+
+        static let urgent = TestTask(
+            title: "Urgent Task \(Int.random(in: 1000...9999))",
+            description: "An urgent task",
+            priority: "High",
+            category: "Repair"
+        )
+    }
+
+    // MARK: - Documents
+
+    struct TestDocument {
+        let title: String
+        let description: String
+        let type: String
+
+        static let basic = TestDocument(
+            title: "Test Doc \(Int.random(in: 1000...9999))",
+            description: "A test document",
+            type: "Manual"
+        )
+
+        static let warranty = TestDocument(
+            title: "Test Warranty \(Int.random(in: 1000...9999))",
+            description: "A test warranty",
+            type: "Warranty"
+        )
+    }
+
+    // MARK: - Contractors
+
+    struct TestContractor {
+        let name: String
+        let phone: String
+        let email: String
+        let specialty: String
+
+        static let basic = TestContractor(
+            name: "Test Contractor \(Int.random(in: 1000...9999))",
+            phone: "555-0100",
+            email: "contractor@test.com",
+            specialty: "Plumber"
+        )
+    }
+}

iosApp/CaseraUITests/PageObjects/BaseScreen.swift

@@ -0,0 +1,73 @@
+import XCTest
+
+/// Base class for all page objects providing common waiting and assertion utilities.
+///
+/// Replaces ad-hoc `sleep()` calls with condition-based waits for reliable,
+/// non-flaky UI tests. All screen page objects should inherit from this class.
+class BaseScreen {
+    let app: XCUIApplication
+    let timeout: TimeInterval
+
+    init(app: XCUIApplication, timeout: TimeInterval = 10) {
+        self.app = app
+        self.timeout = timeout
+    }
+
+    // MARK: - Wait Helpers (replaces fixed sleeps)
+
+    /// Waits for an element to exist within the timeout period.
+    /// Fails the test with a descriptive message if the element does not appear.
+    @discardableResult
+    func waitForElement(_ element: XCUIElement, timeout: TimeInterval? = nil) -> XCUIElement {
+        let t = timeout ?? self.timeout
+        XCTAssertTrue(element.waitForExistence(timeout: t), "Element \(element) did not appear within \(t)s")
+        return element
+    }
+
+    /// Waits for an element to disappear within the timeout period.
+    /// Fails the test if the element is still present after the timeout.
+    func waitForElementToDisappear(_ element: XCUIElement, timeout: TimeInterval? = nil) {
+        let t = timeout ?? self.timeout
+        let predicate = NSPredicate(format: "exists == false")
+        let expectation = XCTNSPredicateExpectation(predicate: predicate, object: element)
+        let result = XCTWaiter().wait(for: [expectation], timeout: t)
+        XCTAssertEqual(result, .completed, "Element \(element) did not disappear within \(t)s")
+    }
+
+    /// Waits for an element to become hittable (visible and interactable).
+    /// Returns the element for chaining.
+    @discardableResult
+    func waitForHittable(_ element: XCUIElement, timeout: TimeInterval? = nil) -> XCUIElement {
+        let t = timeout ?? self.timeout
+        let predicate = NSPredicate(format: "isHittable == true")
+        let expectation = XCTNSPredicateExpectation(predicate: predicate, object: element)
+        _ = XCTWaiter().wait(for: [expectation], timeout: t)
+        return element
+    }
+
+    // MARK: - State Assertions
+
+    /// Asserts that an element with the given accessibility identifier exists.
+    func assertExists(_ identifier: String, file: StaticString = #file, line: UInt = #line) {
+        let element = app.descendants(matching: .any)[identifier]
+        XCTAssertTrue(element.waitForExistence(timeout: timeout), "Element '\(identifier)' not found", file: file, line: line)
+    }
+
+    /// Asserts that an element with the given accessibility identifier does not exist.
+    func assertNotExists(_ identifier: String, file: StaticString = #file, line: UInt = #line) {
+        let element = app.descendants(matching: .any)[identifier]
+        XCTAssertFalse(element.exists, "Element '\(identifier)' should not exist", file: file, line: line)
+    }
+
+    // MARK: - Navigation
+
+    /// Taps the first button in the navigation bar (typically the back button).
+    func tapBackButton() {
+        app.navigationBars.buttons.element(boundBy: 0).tap()
+    }
+
+    /// Subclasses must override this property to indicate whether the screen is currently displayed.
+    var isDisplayed: Bool {
+        fatalError("Subclasses must override isDisplayed")
+    }
+}

iosApp/CaseraUITests/PageObjects/LoginScreen.swift

@@ -0,0 +1,86 @@
+import XCTest
+
+/// Page object for the login screen.
+///
+/// Uses accessibility identifiers from `AccessibilityIdentifiers.Authentication`
+/// to locate elements. Provides typed actions for login flow interactions.
+class LoginScreen: BaseScreen {
+
+    // MARK: - Elements
+
+    var emailField: XCUIElement {
+        app.textFields[AccessibilityIdentifiers.Authentication.usernameField]
+    }
+
+    var passwordField: XCUIElement {
+        // Password field may be a SecureTextField or regular TextField depending on visibility toggle
+        let secure = app.secureTextFields[AccessibilityIdentifiers.Authentication.passwordField]
+        if secure.exists { return secure }
+        return app.textFields[AccessibilityIdentifiers.Authentication.passwordField]
+    }
+
+    var loginButton: XCUIElement {
+        app.buttons[AccessibilityIdentifiers.Authentication.loginButton]
+    }
+
+    var appleSignInButton: XCUIElement {
+        app.buttons[AccessibilityIdentifiers.Authentication.appleSignInButton]
+    }
+
+    var signUpButton: XCUIElement {
+        app.buttons[AccessibilityIdentifiers.Authentication.signUpButton]
+    }
+
+    var forgotPasswordButton: XCUIElement {
+        app.buttons[AccessibilityIdentifiers.Authentication.forgotPasswordButton]
+    }
+
+    var passwordVisibilityToggle: XCUIElement {
+        app.buttons[AccessibilityIdentifiers.Authentication.passwordVisibilityToggle]
+    }
+
+    var welcomeText: XCUIElement {
+        app.staticTexts["Welcome Back"]
+    }
+
+    override var isDisplayed: Bool {
+        emailField.waitForExistence(timeout: timeout)
+    }
+
+    // MARK: - Actions
+
+    /// Logs in with the provided credentials and returns a MainTabScreen.
+    /// Waits for the email field to appear before typing.
+    @discardableResult
+    func login(email: String, password: String) -> MainTabScreen {
+        waitForElement(emailField).tap()
+        emailField.typeText(email)
+
+        let pwField = passwordField
+        pwField.tap()
+        pwField.typeText(password)
+
+        loginButton.tap()
+        return MainTabScreen(app: app)
+    }
+
+    /// Taps the sign up / register link and returns a RegisterScreen.
+    @discardableResult
+    func tapSignUp() -> RegisterScreen {
+        waitForElement(signUpButton).tap()
+        return RegisterScreen(app: app)
+    }
+
+    /// Taps the forgot password link.
+    func tapForgotPassword() {
+        waitForElement(forgotPasswordButton).tap()
+    }
+
+    /// Toggles password visibility and returns whether the password is now visible.
+    @discardableResult
+    func togglePasswordVisibility() -> Bool {
+        waitForElement(passwordVisibilityToggle).tap()
+        // If a regular text field with the password identifier exists, password is visible
+        return app.textFields[AccessibilityIdentifiers.Authentication.passwordField].exists
+    }
+}

iosApp/CaseraUITests/PageObjects/MainTabScreen.swift

@@ -0,0 +1,88 @@
+import XCTest
+
+/// Page object for the main tab view that appears after login.
+///
+/// Provides navigation to each tab (Residences, Tasks, Contractors, Documents, Profile)
+/// and a logout flow. Uses predicate-based element lookup to match the existing test patterns.
+class MainTabScreen: BaseScreen {
+
+    // MARK: - Tab Elements
+
+    var residencesTab: XCUIElement {
+        app.tabBars.buttons.containing(NSPredicate(format: "label CONTAINS[c] 'Residences'")).firstMatch
+    }
+
+    var tasksTab: XCUIElement {
+        app.tabBars.buttons.containing(NSPredicate(format: "label CONTAINS[c] 'Tasks'")).firstMatch
+    }
+
+    var contractorsTab: XCUIElement {
+        app.tabBars.buttons.containing(NSPredicate(format: "label CONTAINS[c] 'Contractors'")).firstMatch
+    }
+
+    var documentsTab: XCUIElement {
+        app.tabBars.buttons.containing(NSPredicate(format: "label CONTAINS[c] 'Documents'")).firstMatch
+    }
+
+    var profileTab: XCUIElement {
+        app.tabBars.buttons.containing(NSPredicate(format: "label CONTAINS[c] 'Profile'")).firstMatch
+    }
+
+    override var isDisplayed: Bool {
+        residencesTab.waitForExistence(timeout: timeout)
+    }
+
+    // MARK: - Navigation
+
+    @discardableResult
+    func goToResidences() -> Self {
+        waitForElement(residencesTab).tap()
+        return self
+    }
+
+    @discardableResult
+    func goToTasks() -> Self {
+        waitForElement(tasksTab).tap()
+        return self
+    }
+
+    @discardableResult
+    func goToContractors() -> Self {
+        waitForElement(contractorsTab).tap()
+        return self
+    }
+
+    @discardableResult
+    func goToDocuments() -> Self {
+        waitForElement(documentsTab).tap()
+        return self
+    }
+
+    @discardableResult
+    func goToProfile() -> Self {
+        waitForElement(profileTab).tap()
+        return self
+    }
+
+    // MARK: - Logout
+
+    /// Logs out by navigating to the Profile tab and tapping the logout button.
+    /// Handles the confirmation alert automatically.
+    func logout() {
+        goToProfile()
+
+        let logoutButton = app.buttons[AccessibilityIdentifiers.Profile.logoutButton]
+        if logoutButton.waitForExistence(timeout: 5) {
+            waitForHittable(logoutButton).tap()
+
+            // Handle confirmation alert
+            let alert = app.alerts.firstMatch
+            if alert.waitForExistence(timeout: 3) {
+                let confirmLogout = alert.buttons["Log Out"]
+                if confirmLogout.exists {
+                    confirmLogout.tap()
+                }
+            }
+        }
+    }
+}

iosApp/CaseraUITests/PageObjects/RegisterScreen.swift

@@ -0,0 +1,86 @@
+import XCTest
+
+/// Page object for the registration screen.
+///
+/// Uses accessibility identifiers from `AccessibilityIdentifiers.Authentication`
+/// to locate registration form elements and perform sign-up actions.
+class RegisterScreen: BaseScreen {
+
+    // MARK: - Elements
+
+    var usernameField: XCUIElement {
+        app.textFields[AccessibilityIdentifiers.Authentication.registerUsernameField]
+    }
+
+    var emailField: XCUIElement {
+        app.textFields[AccessibilityIdentifiers.Authentication.registerEmailField]
+    }
+
+    var passwordField: XCUIElement {
+        app.secureTextFields[AccessibilityIdentifiers.Authentication.registerPasswordField]
+    }
+
+    var confirmPasswordField: XCUIElement {
+        app.secureTextFields[AccessibilityIdentifiers.Authentication.registerConfirmPasswordField]
+    }
+
+    var registerButton: XCUIElement {
+        app.buttons[AccessibilityIdentifiers.Authentication.registerButton]
+    }
+
+    var cancelButton: XCUIElement {
+        app.buttons[AccessibilityIdentifiers.Authentication.registerCancelButton]
+    }
+
+    /// Fallback element lookup for the register/create account button using predicate
+    var registerButtonByLabel: XCUIElement {
+        app.buttons.containing(NSPredicate(format: "label CONTAINS[c] 'Register' OR label CONTAINS[c] 'Create Account'")).firstMatch
+    }
+
+    override var isDisplayed: Bool {
+        // Registration screen is visible if any of the register-specific fields exist
+        let usernameExists = usernameField.waitForExistence(timeout: timeout)
+        let emailExists = emailField.exists
+        return usernameExists || emailExists
+    }
+
+    // MARK: - Actions
+
+    /// Fills in the registration form and submits it.
+    /// Returns a MainTabScreen assuming successful registration leads to the main app.
+    @discardableResult
+    func register(username: String, email: String, password: String) -> MainTabScreen {
+        waitForElement(usernameField).tap()
+        usernameField.typeText(username)
+
+        emailField.tap()
+        emailField.typeText(email)
+
+        passwordField.tap()
+        passwordField.typeText(password)
+
+        confirmPasswordField.tap()
+        confirmPasswordField.typeText(password)
+
+        // Try accessibility identifier first, fall back to label search
+        if registerButton.exists {
+            registerButton.tap()
+        } else {
+            registerButtonByLabel.tap()
+        }
+
+        return MainTabScreen(app: app)
+    }
+
+    /// Taps cancel to return to the login screen.
+    @discardableResult
+    func tapCancel() -> LoginScreen {
+        if cancelButton.exists {
+            cancelButton.tap()
+        } else {
+            // Fall back to navigation back button
+            tapBackButton()
+        }
+        return LoginScreen(app: app)
+    }
+}

iosApp/CaseraUITests/README.md

@@ -0,0 +1,80 @@
+# Casera iOS UI Testing Architecture
+
+## Directory Structure
+
+```
+CaseraUITests/
+├── PageObjects/           # Screen abstractions (Page Object pattern)
+│   ├── BaseScreen.swift   # Common wait/assert utilities
+│   ├── LoginScreen.swift  # Login screen elements and actions
+│   ├── RegisterScreen.swift
+│   └── MainTabScreen.swift
+├── TestConfiguration/     # Launch config, environment setup
+│   └── TestLaunchConfig.swift
+├── Fixtures/              # Test data builders
+│   └── TestFixtures.swift
+├── CriticalPath/          # Must-pass tests for CI gating
+│   └── SmokeTests.swift   # Fast smoke suite (<2 min)
+├── Suite0-10_*.swift      # Existing comprehensive test suites
+├── UITestHelpers.swift    # Legacy shared helpers
+├── AccessibilityIdentifiers.swift # UI element IDs
+└── README.md              # This file
+```
+
+## Test Suites
+
+| Suite | Purpose | CI Gate | Target Time |
+|-------|---------|---------|-------------|
+| SmokeTests | App launches, auth, navigation | Every PR | <2 min |
+| Suite0-2 | Onboarding, registration, auth | Nightly | <5 min |
+| Suite3-8 | Feature CRUD (residence, task, etc) | Nightly | <15 min |
+| Suite9-10 | E2E integration | Weekly | <30 min |
+
+## Patterns
+
+### Page Object Pattern
+Every screen has a corresponding PageObject in `PageObjects/`. Use these instead of raw XCUIElement queries in tests. Page objects encapsulate element lookups and common actions, making tests more readable and easier to maintain when the UI changes.
+
+### Wait Helpers
+NEVER use `sleep()` or `Thread.sleep()`. Use `waitForElement()`, `waitForElementToDisappear()`, or `waitForHittable()` from BaseScreen. These are condition-based waits that return as soon as the condition is met, making tests both faster and more reliable.
+
+### Test Data
+Use `TestFixtures` builders for consistent, unique test data. Random numbers and UUIDs ensure test isolation so tests can run in any order without interfering with each other.
+
+### Launch Configuration
+Use `TestLaunchConfig.launchApp()` for standard launches. Use `launchAuthenticated()` to skip login when the app supports test authentication bypass. The standard configuration disables animations and forces English locale.
+
+### Accessibility Identifiers
+All interactive elements must have identifiers defined in `AccessibilityIdentifiers.swift`. Use `.accessibilityIdentifier()` in SwiftUI views. Page objects reference these identifiers for element lookup.
+
+## CI Configuration
+
+### Smoke Suite (every PR)
+```bash
+xcodebuild test -project iosApp.xcodeproj -scheme iosApp \
+  -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 17' \
+  -only-testing:CaseraUITests/SmokeTests
+```
+
+### Full Regression (nightly)
+```bash
+xcodebuild test -project iosApp.xcodeproj -scheme iosApp \
+  -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 17' \
+  -only-testing:CaseraUITests
+```
+
+## Flake Reduction
+
+- Target: <2% flake rate on critical-path suite
+- All waits use condition-based predicates (no fixed sleeps)
+- Test data uses unique identifiers to prevent cross-test interference
+- UI animations disabled via launch arguments
+- Element lookups use accessibility identifiers where possible, with predicate-based fallbacks
+
+## Adding New Tests
+
+1. If the screen does not have a page object yet, create one in `PageObjects/` that extends `BaseScreen`.
+2. Define accessibility identifiers in `AccessibilityIdentifiers.swift` for any new UI elements.
+3. Add test data builders to `TestFixtures.swift` if needed.
+4. Write the test in the appropriate suite file, or create a new suite if the feature is new.
+5. For critical-path tests (must pass on every PR), add to `CriticalPath/SmokeTests.swift`.

iosApp/CaseraUITests/TestConfiguration/TestLaunchConfig.swift

@@ -0,0 +1,64 @@
+import XCTest
+
+/// Centralized app launch configuration for UI tests.
+///
+/// Provides consistent launch arguments and environment variables across
+/// all test suites. Disables animations and sets locale to English for
+/// deterministic test behavior.
+enum TestLaunchConfig {
+
+    /// Standard launch arguments for UI test mode.
+    /// Disables animations and forces English locale.
+    static let standardArguments: [String] = [
+        "-UITEST_MODE", "1",
+        "-AppleLanguages", "(en)",
+        "-AppleLocale", "en_US",
+        "-UIAnimationsEnabled", "NO"
+    ]
+
+    /// Launch environment variables for UI tests.
+    static let standardEnvironment: [String: String] = [
+        "UITEST_MODE": "1",
+        "ANIMATIONS_DISABLED": "1"
+    ]
+
+    /// Configure and launch app with standard test settings.
+    ///
+    /// - Parameters:
+    ///   - additionalArguments: Extra launch arguments to append.
+    ///   - additionalEnvironment: Extra environment variables to merge.
+    /// - Returns: The launched `XCUIApplication` instance.
+    @discardableResult
+    static func launchApp(
+        additionalArguments: [String] = [],
+        additionalEnvironment: [String: String] = [:]
+    ) -> XCUIApplication {
+        let app = XCUIApplication()
+        app.launchArguments = standardArguments + additionalArguments
+        var env = standardEnvironment
+        additionalEnvironment.forEach { env[$0.key] = $0.value }
+        app.launchEnvironment = env
+        app.launch()
+        return app
+    }
+
+    /// Launch app pre-authenticated (skips login flow).
+    ///
+    /// Passes test credentials via launch arguments and environment so the
+    /// app can bypass the normal authentication flow during UI tests.
+    ///
+    /// - Parameters:
+    ///   - email: Test user email address.
+    ///   - token: Test authentication token.
+    /// - Returns: The launched `XCUIApplication` instance.
+    @discardableResult
+    static func launchAuthenticated(
+        email: String = "test@example.com",
+        token: String = "test-token-12345"
+    ) -> XCUIApplication {
+        return launchApp(
+            additionalArguments: ["-TEST_AUTH_EMAIL", email, "-TEST_AUTH_TOKEN", token],
+            additionalEnvironment: ["TEST_AUTH_EMAIL": email, "TEST_AUTH_TOKEN": token]
+        )
+    }
+}

iosApp/iosApp/Documents/DocumentDetailView.swift

@@ -160,7 +160,17 @@ struct DocumentDetailView: View {
                 }
 
                 // Determine filename
-                let filename = document.title.replacingOccurrences(of: " ", with: "_") + "." + (document.fileType ?? "file")
+                // Extract extension from fileName (e.g., "doc.pdf" -> "pdf") or mimeType (e.g., "application/pdf" -> "pdf")
+                let ext: String = {
+                    if let fn = document.fileName, let dotIndex = fn.lastIndex(of: ".") {
+                        return String(fn[fn.index(after: dotIndex)...])
+                    }
+                    if let mime = document.mimeType, let slashIndex = mime.lastIndex(of: "/") {
+                        return String(mime[mime.index(after: slashIndex)...])
+                    }
+                    return "file"
+                }()
+                let filename = document.title.replacingOccurrences(of: " ", with: "_") + "." + ext
 
                 // Move to a permanent location
                 let documentsPath = FileManager.default.temporaryDirectory
@@ -329,14 +339,11 @@ struct DocumentDetailView: View {
                 VStack(alignment: .leading, spacing: 12) {
                     sectionHeader(L10n.Documents.associations)
 
-                    if let residenceAddress = document.residenceAddress {
-                        detailRow(label: L10n.Documents.residence, value: residenceAddress)
+                    if let residenceId = document.residenceId {
+                        detailRow(label: L10n.Documents.residence, value: "Residence #\(residenceId)")
                     }
-                    if let contractorName = document.contractorName {
-                        detailRow(label: L10n.Documents.contractor, value: contractorName)
-                    }
-                    if let contractorPhone = document.contractorPhone {
-                        detailRow(label: L10n.Documents.contractorPhone, value: contractorPhone)
+                    if let taskId = document.taskId {
+                        detailRow(label: L10n.Documents.contractor, value: "Task #\(taskId)")
                     }
                 }
                 .padding()
@@ -367,8 +374,8 @@ struct DocumentDetailView: View {
                     VStack(alignment: .leading, spacing: 12) {
                         sectionHeader(L10n.Documents.attachedFile)
 
-                        if let fileType = document.fileType {
-                            detailRow(label: L10n.Documents.fileType, value: fileType)
+                        if let mimeType = document.mimeType {
+                            detailRow(label: L10n.Documents.fileType, value: mimeType)
                         }
                         if let fileSize = document.fileSize {
                             detailRow(label: L10n.Documents.fileSize, value: formatFileSize(bytes: Int(fileSize)))
@@ -412,8 +419,9 @@ struct DocumentDetailView: View {
                 VStack(alignment: .leading, spacing: 12) {
                     sectionHeader(L10n.Documents.metadata)
 
-                    if let uploadedBy = document.uploadedByUsername {
-                        detailRow(label: L10n.Documents.uploadedBy, value: uploadedBy)
+                    if let createdBy = document.createdBy {
+                        let name = [createdBy.firstName, createdBy.lastName].filter { !$0.isEmpty }.joined(separator: " ")
+                        detailRow(label: L10n.Documents.uploadedBy, value: name.isEmpty ? createdBy.username : name)
                     }
                     if let createdAt = document.createdAt {
                         detailRow(label: L10n.Documents.created, value: DateUtils.formatDateTime(createdAt))

iosApp/iosApp/Documents/DocumentViewModel.swift

@@ -308,7 +308,8 @@ class DocumentViewModel: ObservableObject {
                     documentId: documentId,
                     imageBytes: self.kotlinByteArray(from: compressedData),
                     fileName: "document_image_\(index + 1).jpg",
-                    mimeType: "image/jpeg"
+                    mimeType: "image/jpeg",
+                    caption: nil
                 )
             } catch {
                 return ErrorMessageParser.parse(error.localizedDescription)
@@ -318,7 +319,7 @@ class DocumentViewModel: ObservableObject {
                 return ErrorMessageParser.parse(error.message)
             }
 
-            if !(uploadResult is ApiResultSuccess<DocumentImage>) {
+            if !(uploadResult is ApiResultSuccess<Document>) {
                 return "Failed to upload image \(index + 1)"
             }
         }

iosApp/iosApp/Documents/DocumentViewModelWrapper.swift

@@ -2,6 +2,27 @@ import Foundation
 import ComposeApp
 import SwiftUI
 
+// MARK: - Architecture Note
+//
+// Two document ViewModels coexist with distinct responsibilities:
+//
+// DocumentViewModel (DocumentViewModel.swift):
+//   - Used by list views (DocumentsView, DocumentListView)
+//   - Observes DataManager via DataManagerObservable for reactive list updates
+//   - Handles CRUD operations that update DataManager cache (create, update, delete)
+//   - Supports image upload workflows
+//   - Uses @MainActor for thread safety
+//
+// DocumentViewModelWrapper (this file):
+//   - Used by detail views (DocumentDetailView, EditDocumentView)
+//   - Manages explicit state types (Loading/Success/Error) for single-document operations
+//   - Loads individual document detail, handles update and delete with state feedback
+//   - Does NOT observe DataManager -- loads fresh data per-request via APILayer
+//   - Uses protocol-based state enums for SwiftUI view branching
+//
+// Both call through APILayer (which updates DataManager), so list views
+// auto-refresh when detail views perform mutations.
+
 // State wrappers for SwiftUI
 protocol DocumentState {}
 struct DocumentStateIdle: DocumentState {}
@@ -235,18 +256,20 @@ class DocumentViewModelWrapper: ObservableObject {
         }
     }
 
-    func deleteDocumentImage(imageId: Int32) {
+    func deleteDocumentImage(documentId: Int32, imageId: Int32) {
         DispatchQueue.main.async {
             self.deleteImageState = DeleteImageStateLoading()
         }
 
         Task {
             do {
-                let result = try await APILayer.shared.deleteDocumentImage(imageId: imageId)
+                let result = try await APILayer.shared.deleteDocumentImage(documentId: documentId, imageId: imageId)
 
                 await MainActor.run {
-                    if result is ApiResultSuccess<KotlinUnit> {
+                    if let success = result as? ApiResultSuccess<Document>, let document = success.data {
                         self.deleteImageState = DeleteImageStateSuccess()
+                        // Refresh detail state with updated document (image removed)
+                        self.documentDetailState = DocumentDetailStateSuccess(document: document)
                     } else if let error = ApiResultBridge.error(from: result) {
                         self.deleteImageState = DeleteImageStateError(message: error.message)
                     } else {

iosApp/iosApp/Login/LoginView.swift

@@ -10,6 +10,7 @@ struct LoginView: View {
     @State private var showPasswordReset = false
     @State private var isPasswordVisible = false
     @State private var activeResetToken: String?
+    @State private var showGoogleSignInAlert = false
     @Binding var resetToken: String?
     var onLoginSuccess: (() -> Void)?
 
@@ -192,6 +193,29 @@ struct LoginView: View {
                                 .padding(.top, 8)
                             }
 
+                            // Google Sign-In Button
+                            // TODO: Replace with full Google Sign-In SDK integration (requires GoogleSignIn pod/SPM package)
+                            Button(action: {
+                                showGoogleSignInAlert = true
+                            }) {
+                                HStack(spacing: 10) {
+                                    Image(systemName: "globe")
+                                        .font(.system(size: 18, weight: .medium))
+                                        .foregroundColor(Color.appTextPrimary)
+                                    Text("Sign in with Google")
+                                        .font(.system(size: 17, weight: .medium))
+                                        .foregroundColor(Color.appTextPrimary)
+                                }
+                                .frame(maxWidth: .infinity)
+                                .frame(height: 54)
+                                .background(Color.appBackgroundSecondary)
+                                .clipShape(RoundedRectangle(cornerRadius: 16, style: .continuous))
+                                .overlay(
+                                    RoundedRectangle(cornerRadius: 16, style: .continuous)
+                                        .stroke(Color.appTextSecondary.opacity(0.3), lineWidth: 1)
+                                )
+                            }
+
                             // Apple Sign In Error
                             if let appleError = appleSignInViewModel.errorMessage {
                                 HStack(spacing: 10) {
@@ -303,6 +327,11 @@ struct LoginView: View {
                     activeResetToken = nil
                 }
             }
+            .alert("Google Sign-In", isPresented: $showGoogleSignInAlert) {
+                Button("OK", role: .cancel) { }
+            } message: {
+                Text("Google Sign-In coming soon. This feature is under development.")
+            }
         }
     }
 

iosApp/iosApp/Onboarding/OnboardingCreateAccountView.swift

@@ -11,6 +11,7 @@ struct OnboardingCreateAccountContent: View {
     @State private var showingLoginSheet = false
     @State private var isExpanded = false
     @State private var isAnimating = false
+    @State private var showGoogleSignInAlert = false
     @FocusState private var focusedField: Field?
     @Environment(\.colorScheme) var colorScheme
 
@@ -139,6 +140,29 @@ struct OnboardingCreateAccountContent: View {
                         if let error = appleSignInViewModel.errorMessage {
                             OrganicErrorMessage(message: error)
                         }
+
+                        // Google Sign-In Button
+                        // TODO: Replace with full Google Sign-In SDK integration (requires GoogleSignIn pod/SPM package)
+                        Button(action: {
+                            showGoogleSignInAlert = true
+                        }) {
+                            HStack(spacing: 10) {
+                                Image(systemName: "globe")
+                                    .font(.system(size: 18, weight: .medium))
+                                    .foregroundColor(Color.appTextPrimary)
+                                Text("Sign in with Google")
+                                    .font(.system(size: 17, weight: .medium))
+                                    .foregroundColor(Color.appTextPrimary)
+                            }
+                            .frame(maxWidth: .infinity)
+                            .frame(height: 56)
+                            .background(Color.appBackgroundSecondary)
+                            .clipShape(RoundedRectangle(cornerRadius: 16, style: .continuous))
+                            .overlay(
+                                RoundedRectangle(cornerRadius: 16, style: .continuous)
+                                    .stroke(Color.appTextSecondary.opacity(0.3), lineWidth: 1)
+                            )
+                        }
                     }
 
                     // Divider
@@ -299,6 +323,11 @@ struct OnboardingCreateAccountContent: View {
                 onAccountCreated(true)
             })
         }
+        .alert("Google Sign-In", isPresented: $showGoogleSignInAlert) {
+            Button("OK", role: .cancel) { }
+        } message: {
+            Text("Google Sign-In coming soon. This feature is under development.")
+        }
         .onChange(of: viewModel.isRegistered) { _, isRegistered in
             if isRegistered {
                 // Registration successful - user is authenticated but not verified

iosApp/iosApp/PushNotifications/PushNotificationManager.swift

@@ -518,7 +518,7 @@ class PushNotificationManager: NSObject, ObservableObject {
         do {
             let result = try await APILayer.shared.markNotificationAsRead(notificationId: notificationIdInt)
 
-            if result is ApiResultSuccess<ComposeApp.Notification> {
+            if result is ApiResultSuccess<MessageResponse> {
                 print("✅ Notification marked as read")
             } else if let error = ApiResultBridge.error(from: result) {
                 print("❌ Failed to mark notification as read: \(error.message)")

iosApp/iosApp/Subscription/FeatureComparisonView.swift

@@ -56,8 +56,8 @@ struct FeatureComparisonView: View {
                         ForEach(subscriptionCache.featureBenefits, id: \.featureName) { benefit in
                             ComparisonRow(
                                 featureName: benefit.featureName,
-                                freeText: benefit.freeTier,
-                                proText: benefit.proTier
+                                freeText: benefit.freeTierText,
+                                proText: benefit.proTierText
                             )
                             Divider()
                         }

iosApp/iosApp/Subscription/StoreKitManager.swift

@@ -10,6 +10,8 @@ class StoreKitManager: ObservableObject {
     // Product IDs can be configured via Info.plist keys:
     // CASERA_IAP_MONTHLY_PRODUCT_ID / CASERA_IAP_ANNUAL_PRODUCT_ID.
     // Falls back to local StoreKit config IDs for development.
+    // Canonical source: SubscriptionProducts in commonMain (Kotlin shared code).
+    // Keep these in sync with SubscriptionProducts.MONTHLY / SubscriptionProducts.ANNUAL.
     private let fallbackProductIDs = [
         "com.example.casera.pro.monthly",
         "com.example.casera.pro.annual"

iosApp/iosApp/Subscription/SubscriptionCache.swift

@@ -1,7 +1,11 @@
 import SwiftUI
 import ComposeApp
 
-/// Swift wrapper for accessing Kotlin SubscriptionCache
+/// Swift wrapper that reads subscription state from Kotlin DataManager (single source of truth).
+///
+/// DataManager is the authoritative subscription state holder. This wrapper
+/// observes DataManager's StateFlows (via polling) and publishes changes
+/// to SwiftUI views via @Published properties.
 class SubscriptionCacheWrapper: ObservableObject {
     static let shared = SubscriptionCacheWrapper()
 
@@ -10,7 +14,8 @@ class SubscriptionCacheWrapper: ObservableObject {
     @Published var featureBenefits: [FeatureBenefit] = []
     @Published var promotions: [Promotion] = []
 
-    /// Current tier resolved from backend status when available, with StoreKit fallback.
+    /// Current tier derived from backend subscription status, with StoreKit fallback.
+    /// Mirrors the logic in Kotlin SubscriptionHelper.currentTier.
     var currentTier: String {
         // Prefer backend subscription state when available.
         // `expiresAt` is only expected for active paid plans.
@@ -40,9 +45,9 @@ class SubscriptionCacheWrapper: ObservableObject {
             return false
         }
 
-        // Get the appropriate limits for the current tier from StoreKit
+        // Get the appropriate limits for the current tier
         guard let tierLimits = subscription.limits[currentTier] else {
-            print("⚠️ No limits found for tier: \(currentTier)")
+            print("No limits found for tier: \(currentTier)")
             return false
         }
 
@@ -58,7 +63,7 @@ class SubscriptionCacheWrapper: ObservableObject {
         case "documents":
             limit = tierLimits.documents.map { Int(truncating: $0) }
         default:
-            print("⚠️ Unknown limit key: \(limitKey)")
+            print("Unknown limit key: \(limitKey)")
             return false
         }
 
@@ -99,69 +104,56 @@ class SubscriptionCacheWrapper: ObservableObject {
     }
 
     private init() {
-        // Start observation of Kotlin cache
+        // Start observation of DataManager (single source of truth)
         Task { @MainActor in
-            // Initial sync
-            self.observeSubscriptionStatusSync()
-            self.observeUpgradeTriggersSync()
+            // Initial sync from DataManager
+            self.syncFromDataManager()
 
-            // Poll for updates periodically (workaround for Kotlin StateFlow observation)
+            // Poll DataManager for updates periodically
+            // (workaround for Kotlin StateFlow observation from Swift)
             while true {
                 try? await Task.sleep(nanoseconds: 2_000_000_000) // 2 seconds
-                self.observeSubscriptionStatusSync()
-                self.observeUpgradeTriggersSync()
+                self.syncFromDataManager()
             }
         }
     }
 
+    /// Sync all subscription state from DataManager (Kotlin single source of truth)
     @MainActor
-    private func observeSubscriptionStatus() {
-        // Update from Kotlin cache
-        if let subscription = ComposeApp.SubscriptionCache.shared.currentSubscription.value as? SubscriptionStatus {
-            self.currentSubscription = subscription
-            print("📊 Subscription Status: currentTier=\(currentTier), limitationsEnabled=\(subscription.limitationsEnabled)")
-            print("   📊 Free Tier Limits - Properties: \(subscription.limits["free"]?.properties), Tasks: \(subscription.limits["free"]?.tasks), Contractors: \(subscription.limits["free"]?.contractors), Documents: \(subscription.limits["free"]?.documents)")
-            print("   📊 Pro Tier Limits - Properties: \(subscription.limits["pro"]?.properties), Tasks: \(subscription.limits["pro"]?.tasks), Contractors: \(subscription.limits["pro"]?.contractors), Documents: \(subscription.limits["pro"]?.documents)")
-        } else {
-            print("⚠️ No subscription status in cache")
+    private func syncFromDataManager() {
+        // Read subscription status from DataManager
+        if let subscription = ComposeApp.DataManager.shared.subscription.value as? SubscriptionStatus {
+            if self.currentSubscription == nil || self.currentSubscription != subscription {
+                self.currentSubscription = subscription
+                syncWidgetSubscriptionStatus(subscription: subscription)
+            }
         }
-    }
 
-    @MainActor
-    private func observeUpgradeTriggers() {
-        // Update from Kotlin cache
-        let kotlinTriggers = ComposeApp.SubscriptionCache.shared.upgradeTriggers.value as? [String: UpgradeTriggerData]
-        if let triggers = kotlinTriggers {
+        // Read upgrade triggers from DataManager
+        if let triggers = ComposeApp.DataManager.shared.upgradeTriggers.value as? [String: UpgradeTriggerData] {
             self.upgradeTriggers = triggers
         }
+
+        // Read feature benefits from DataManager
+        if let benefits = ComposeApp.DataManager.shared.featureBenefits.value as? [FeatureBenefit] {
+            self.featureBenefits = benefits
+        }
+
+        // Read promotions from DataManager
+        if let promos = ComposeApp.DataManager.shared.promotions.value as? [Promotion] {
+            self.promotions = promos
+        }
     }
 
     func refreshFromCache() {
         Task { @MainActor in
-            observeSubscriptionStatusSync()
-            observeUpgradeTriggersSync()
-        }
-    }
-
-    @MainActor
-    private func observeSubscriptionStatusSync() {
-        if let subscription = ComposeApp.SubscriptionCache.shared.currentSubscription.value as? SubscriptionStatus {
-            self.currentSubscription = subscription
-            // Sync subscription status with widget
-            syncWidgetSubscriptionStatus(subscription: subscription)
-        }
-    }
-
-    @MainActor
-    private func observeUpgradeTriggersSync() {
-        let kotlinTriggers = ComposeApp.SubscriptionCache.shared.upgradeTriggers.value as? [String: UpgradeTriggerData]
-        if let triggers = kotlinTriggers {
-            self.upgradeTriggers = triggers
+            syncFromDataManager()
         }
     }
 
     func updateSubscription(_ subscription: SubscriptionStatus) {
-        ComposeApp.SubscriptionCache.shared.updateSubscriptionStatus(subscription: subscription)
+        // Write to DataManager (single source of truth)
+        ComposeApp.DataManager.shared.setSubscription(subscription: subscription)
         DispatchQueue.main.async {
             self.currentSubscription = subscription
             // Sync subscription status with widget
@@ -178,9 +170,13 @@ class SubscriptionCacheWrapper: ObservableObject {
             isPremium: isPremium
         )
     }
-    
+
     func clear() {
-        ComposeApp.SubscriptionCache.shared.clear()
+        // Clear via DataManager (single source of truth)
+        ComposeApp.DataManager.shared.setSubscription(subscription: nil)
+        ComposeApp.DataManager.shared.setUpgradeTriggers(triggers: [:])
+        ComposeApp.DataManager.shared.setFeatureBenefits(benefits: [])
+        ComposeApp.DataManager.shared.setPromotions(promos: [])
         DispatchQueue.main.async {
             self.currentSubscription = nil
             self.upgradeTriggers = [:]