Merge remote-tracking branch 'origin/main' into perf/report-welcome-text

Author: TMisiukiewicz

.claude/settings.json

@@ -52,7 +52,9 @@
             "mcp__sentry__search_events",
             "mcp__sentry__search_issue_events",
             "mcp__sentry__search_issues",
-            "mcp__sentry__whoami"
+            "mcp__sentry__whoami",
+            "Bash(agent-device *)",
+            "Bash(echo \"$(npm root -g)/agent-device/skills/agent-device\")"
         ]
     },
     "enabledPlugins": {

.claude/skills/agent-device/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: agent-device
+description: Drive iOS and Android devices for the Expensify App - testing, debugging, performance profiling, bug reproduction, and feature verification. Use when the developer needs to interact with the mobile app on a device.
+allowed-tools: Bash(agent-device *) Bash(npm root *)
+---
+
+# agent-device
+
+## Pre-flight
+
+`agent-device` CLI version: !`agent-device --version 2>&1 || echo "NOT_INSTALLED"`
+
+Canonical skill reference path (read these files directly for device automation guidance - bootstrap, exploration, verification, debugging): !`echo "$(npm root -g)/agent-device/skills/agent-device"`
+
+> If the version line above shows `NOT_INSTALLED` or a command-not-found error, **STOP** and instruct the developer to install it: `npm install -g agent-device`. All device interaction depends on it.

.gitignore

@@ -162,5 +162,8 @@ modules/*/lib/
 .playwright-output/
 .playwright-mcp/
 
+# agent-device
+agent-device-output/
+
 # cspell cache
 .cspellcache

CLAUDE.md

@@ -278,6 +278,9 @@ npm run web
 ### Browser Testing
 Use the `/playwright-app-testing` skill to test and debug the App in a browser. Use this skill after making frontend changes to verify your work, or when the user requests testing.
 
+### Mobile Device Testing
+Use the `/agent-device` skill to drive the App on iOS and Android (simulators or real devices) for interactive testing, performance profiling, bug reproduction, and device-specific debugging. Requires `npm install -g agent-device` - the skill's pre-flight check will surface the install instruction if missing.
+
 ## Architecture Decisions
 
 ### React Native New Architecture

Mobile-Expensify

@@ -48,6 +48,8 @@ For detailed setup instructions for each platform, see the following guides:
 * **📱 iOS Development**: [iOS Setup Instructions](contributingGuides/SETUP_IOS.md)  
 * **🤖 Android Development**: [Android Setup Instructions](contributingGuides/SETUP_ANDROID.md)
 
+**Optional AI-assisted mobile testing:** If you use Claude Code, the [`/agent-device` skill](.claude/skills/agent-device/SKILL.md) drives iOS and Android simulators or devices for interactive testing, debugging, and performance profiling. Requires `npm install -g agent-device`.
+
 ## General Troubleshooting
 1. If you are having issues with **_Getting Started_**, please reference [React Native's Documentation](https://reactnative.dev/docs/environment-setup)
 2. If you are running into CORS errors like (in the browser dev console)

README.md

@@ -111,8 +111,8 @@ android {
         minSdkVersion rootProject.ext.minSdkVersion
         targetSdkVersion rootProject.ext.targetSdkVersion
         multiDexEnabled rootProject.ext.multiDexEnabled
-        versionCode 1009036102
-        versionName "9.3.61-2"
+        versionCode 1009036103
+        versionName "9.3.61-3"
         // Supported language variants must be declared here to avoid from being removed during the compilation.
         // This also helps us to not include unnecessary language variants in the APK.
         resConfigs "en", "es"

android/app/build.gradle

@@ -1141,7 +1141,7 @@ In Expensify, we use an extended implementation of this function because:
 -   In case of opening the RHP, appropriate screens should be pushed to the navigation to be displayed below the overlay. A guide on how to set up a good screen for RHP can be found [here](#how-to-set-a-correct-screen-below-the-rhp).
 -   When opening the settings of a specific workspace, the workspace list needs to be pushed to the state.
 -   When the `backTo` parameter is in the URL, we need to build a state also for the screen we want to return to. (`backTo` parameter is deprecated, more information can be found [here](#how-to-remove-backto-from-url))
--   For dynamic routes, state is built from the current path and [entryScreens](#entry-screens-access-control) access control.
+-   For dynamic routes, when the page is refreshed the navigation state only contains the deepest screen. To make back navigation work, all intermediate dynamic screens must be inserted into the state in the correct order so the app knows which screen to return to.
 
 Here are examples how the state is generated based on route:
 
@@ -1255,6 +1255,77 @@ As you can see after opening the workspace settings of the specific workspace, w
 
 In the above example, we can see that when building a state from a link leading to a screen in RHP, screens that appear below the overlay are also built.
 
+-   `settings/profile/address/country?country=US`
+
+```json
+{
+    "stale": false,
+    "type": "stack",
+    "key": "stack-key-7",
+    "index": 1,
+    "routes": [
+        {
+            "name": "SettingsSplitNavigator",
+            "state": {
+                "stale": false,
+                "type": "stack",
+                "key": "stack-key-8",
+                "index": 1,
+                "routes": [
+                    {
+                        "name": "Settings_Root",
+                        "key": "Settings_Root-key"
+                    },
+                    {
+                        "name": "Settings_Profile",
+                        "key": "Settings_Profile-key"
+                    }
+                ]
+            },
+            "key": "SettingsSplitNavigator-key"
+        },
+        {
+            "name": "RightModalNavigator",
+            "state": {
+                "stale": false,
+                "type": "stack",
+                "key": "stack-key-9",
+                "index": 0,
+                "routes": [
+                    {
+                        "name": "Settings",
+                        "state": {
+                            "stale": false,
+                            "type": "stack",
+                            "key": "stack-key-10",
+                            "index": 1,
+                            "routes": [
+                                {
+                                    "name": "Settings_Address",
+                                    "path": "/settings/profile/address",
+                                    "key": "Settings_Address-key"
+                                },
+                                {
+                                    "name": "Dynamic_Address_Country",
+                                    "path": "/settings/profile/address/country?country=US",
+                                    "params": {
+                                        "country": "US"
+                                    },
+                                    "key": "Dynamic_Address_Country-key"
+                                }
+                            ]
+                        },
+                        "key": "Settings-key"
+                    }
+                ]
+            },
+            "key": "RightModalNavigator-key"
+        }
+    ]
+}
+```
+Since `country` is a dynamic suffix, the `Dynamic_Address_Country` screen is layered on top of the static `Settings_Address` screen in the initial state, ensuring correct back navigation after a refresh.
+
 ## Setting the correct screen underneath RHP
 
 RHP screens can usually be opened from a specific central screen. Of course there are cases where one RHP screen can be used in different tabs. However, most often one RHP screen has a specific central screen assigned underneath.

assets/images/simple-illustrations/simple-illustration__chalkboard.svg

@@ -73,7 +73,8 @@ If you haven't done any intentional edits outside of `src/` (like adding new dep
 - Changes applied to Javascript will be applied automatically, any changes to native code will require a recompile
 
 ### Expensify Employees
-If you are an Expensify employee and want to point the emulator to your local VM, follow [this](https://stackoverflow.com/c/expensify/questions/7699)
+- To point the **Development Emulator** at your local VM, follow [these steps](https://stackoverflow.com/c/expensify/questions/7699).
+- You must configure the local dev email account; follow [these instructions](https://stackoverflowteams.com/c/expensify/questions/23537/23538#23538).
 
 ## Enabling Prebuilt React Native Artifacts