Merge remote-tracking branch 'origin/main' into claude-migratedUserWelcomeModalV2

Co-authored-by: Eric Han <eh2077@users.noreply.github.com>

Author: MelvinBot

.claude/commands/review-code-pr.md

@@ -1,6 +1,6 @@
 ---
 allowed-tools: Bash(gh pr diff:*),Bash(gh pr view:*),Bash(check-compiler.sh:*)
-description: Review a code contribution pull request
+description: Run the coding-standards rule linter on a PR diff. Use when user wants to review their changes against our custom rules.
 ---
 
 Perform a comprehensive PR review using a specialized subagent:

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

@@ -1,15 +1,98 @@
 ---
 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 *)
+allowed-tools: Bash(agent-device *) Bash(npm root *) Bash(scripts/is-hybrid-app.sh)
 ---
 
 # agent-device
 
-## Pre-flight
+## Pre-flight (auto)
 
-`agent-device` CLI version: !`agent-device --version 2>&1 || echo "NOT_INSTALLED"`
+These checks evaluate at skill load. If any line shows `FAIL`, stop and surface the fix before running any device command.
 
-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"`
+`agent-device` version: !`R=0.13.0; V=$(agent-device --version 2>/dev/null); [ -n "$V" ] && [ "$(printf '%s\n%s\n' "$R" "$V" | sort -V | head -1)" = "$R" ] && echo "OK ($V)" || echo "FAIL (need v$R+, got: ${V:-not installed}). Fix: npm install -g agent-device@latest"`
 
-> 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.
+Bundled CLI skills dir: !`D="$(npm root -g)/agent-device/skills/agent-device"; test -s "$D/SKILL.md" && echo "OK ($D)" || echo "FAIL (missing $D/SKILL.md). Fix: npm install -g agent-device@latest"`
+
+HybridApp mode: !`M=$(scripts/is-hybrid-app.sh 2>/dev/null | tail -1); [ "$M" = "true" ] && echo "OK (HybridApp)" || echo "FAIL (got: ${M:-unknown}). This skill only supports the HybridApp build - ensure the Mobile-Expensify submodule is present."`
+
+## Bring-up
+
+Run this sequence the first time the user asks for device interaction in a session, before any `open` / `snapshot` / `replay`.
+
+### 1. Platform
+
+If the user prompt names `ios` or `android` explicitly, use it. Otherwise ask. Only iOS and Android are supported; reject other platforms.
+
+### 2. Bundle ID
+
+HybridApp dev builds only (the pre-flight gate enforces this).
+
+| Platform  | Bundle ID                       | Build script      |
+| --------- | ------------------------------- | ----------------- |
+| `ios`     | `com.expensify.expensifylite`   | `npm run ios`     |
+| `android` | `org.me.mobiexpensifyg.dev`     | `npm run android` |
+
+### 3. Confirm dev build is installed
+
+```bash
+agent-device apps --user-installed --platform <p> --json
+```
+
+If the resolved bundle ID is missing from the list, **STOP** and instruct the developer to run the matching build script from the table. HybridApp mobile builds **must** be initiated from `Mobile-Expensify/` (per project CLAUDE.md).
+
+### 4. Metro
+
+```bash
+agent-device metro prepare --public-base-url http://localhost:8081 --port 8081 --kind react-native
+```
+
+If `metro prepare` fails, **STOP** and surface the error verbatim.
+
+### 5. Pick a target device
+
+```bash
+agent-device devices --platform <p> --json
+```
+
+- Prefer the first device with `booted=true`.
+- If none are booted, choose the default target device (usually the first listed), then continue to step 6 to detect and clear any stale session bound to that device before opening.
+- If multiple are booted, ask the user which.
+
+Capture the device name and (for iOS) the simulator UDID, or (for Android) the serial.
+
+### 6. Session reuse vs reset
+
+```bash
+agent-device session list --json
+```
+
+For each entry whose `device_udid` (iOS) or `serial` (Android) matches the chosen device:
+
+- If the session was created earlier in the **current** Claude invocation, reuse it silently.
+- Otherwise prompt: `reuse` (continue with the existing session) or `reset` (force-close it).
+  - To reset: `agent-device close --shutdown --session <name>`. `--shutdown` also frees the simulator.
+
+### 7. Open
+
+```bash
+agent-device open <bundle-id> --platform <p> --device "<name>"
+```
+
+If `open` errors with "app not installed", revisit step 3.
+
+### 8. Sanity
+
+```bash
+agent-device snapshot -i
+```
+
+Confirm the app rendered. From here, follow the [Agent decision loop](flows/README.md) for repeatable flows or drive interactively.
+
+### Canonical skill references
+
+Read these files directly for device automation guidance (bootstrap, exploration, verification, debugging): !`echo "$(npm root -g)/agent-device/skills/agent-device"`
+
+## Flows
+
+Repeatable steps (sign-in, onboarding, etc.) are captured as composable `.ad` snippets under [`flows/`](flows/README.md). For interactive usage, propose and run only `flows/macros/` helpers. `flows/tests/` belongs to a separate QA workflow and must not be proposed by this skill; QA/perf runs execute them via `agent-device test <path>`.

.claude/skills/agent-device/flows/README.md

@@ -0,0 +1,101 @@
+# Flows
+
+## Directory layout
+
+- `macros/` - reusable helpers for common setup/navigation actions that stop in a navigable state for further interactive work.
+- `tests/` - critical-scenario scripts for QA/perf verification that assert explicit outcomes (for example Sentry spans) and then stop.
+
+Composable `.ad` snippets - bounded units of work. A flow may span one or multiple screens as long as it represents a coherent, reusable action with clear start (`@pre`) and completion (`@post`) checkpoints. Each flow advertises machine-matchable metadata (`@pre`, `@post`, `@tag`, `@param`) via `# @`-prefixed comment headers, while flow type is derived from location (`flows/macros/` or `flows/tests/`).
+
+## Agent decision loop (interactive)
+
+Before manually navigating, use this human-in-the-loop loop:
+
+1. `agent-device snapshot -i` - see current state.
+2. `grep -H '^# @' .claude/skills/agent-device/flows/macros/*.ad` - interactive catalog.
+3. For each candidate flow, run `agent-device is exists "<selector>"` per `@pre`. Keep flows where every `@pre` passes.
+4. Rank survivors by goal closeness and present top macro candidates to the user with a short "why this flow" note:
+   - Prefer flows whose `@post` selectors literally match destination language from the user request (same `text`, `label`, or selector phrase).
+5. Wait for user selection before replaying. **Auto-run is allowed only when there is exactly one survivor and it is an unambiguous match for an explicit user request.**
+   - Only propose flows from `flows/macros/` in interactive usage.
+6. Scan selected flow `# @param` headers. Ask the user for any missing parameter values, then build explicit CLI args (`-e KEY=VALUE`) for replay.
+7. `agent-device replay <path> -e KEY=VALUE ...`.
+8. If the flow declares `@post`, verify each `@post` with `is exists`. On success, re-enter the loop only if the user's stated goal is not complete; otherwise stop and report completion. On failure, propose peer flow/manual fallback options and ask before continuing. If no `@post` is declared (utility flow), rely on explicit user confirmation or the next snapshot before continuing.
+
+## QA workflow (separate)
+
+`flows/tests/` is reserved for dedicated QA automation and should not be offered to users as part of the interactive helper loop above. Run these flows with the dedicated test runner:
+
+```bash
+agent-device test .claude/skills/agent-device/flows/tests/<name>.ad -e KEY=VALUE ...
+```
+
+## Metadata header spec
+
+Each flow starts with `# @key value` comment lines. The `.ad` parser treats `#` lines as no-ops, so headers cost nothing at replay time.
+
+| Field    | Cardinality | Value                                                                                            |
+| -------- | ----------- | ------------------------------------------------------------------------------------------------ |
+| `@desc`  | 1           | One-line human summary.                                                                          |
+| `@pre`   | 1..N        | Selector that must resolve in the current snapshot. Multiple lines are ANDed.                    |
+| `@post`  | 0..N        | Selector expected after replay. Multiple lines are ANDed. Used for chaining + success.           |
+| `@tag`   | 0..N        | Free-form category (`auth`, `onboarding`, ...) or scoped (`sentry-<spanName>`).                  |
+| `@param` | 0..N        | Runtime input contract: `@param KEY description.` Use with `${KEY}` in flow body.                |
+
+Selector syntax matches the body: `id="..."`, `role="..." label="..."`, `text="..."`, `||` for fallbacks.
+
+## Parametrization (`agent-device` v0.13.0+)
+
+Declare runtime inputs via metadata (`@param`) and reference them in the body with `${VAR}` interpolation. Values are supplied by caller arguments (`-e`) or shell imports (`AD_VAR_*`) - never by in-file `env` directives.
+
+| Construct          | Where                    | Purpose                                                                          |
+| ------------------ | ------------------------ | -------------------------------------------------------------------------------- |
+| `# @param KEY ...` | Metadata header comments | Declares expected input and documents meaning for the agent/user handoff.         |
+| `${KEY}`           | Body                     | Interpolation point. Resolves at replay time.                                    |
+| `${KEY:-fallback}` | Body                     | Use `fallback` if `KEY` is unset.                                                |
+| `\${KEY}`          | Body                     | Literal `${KEY}` (escape).                                                       |
+
+Resolution precedence (high to low): CLI `-e KEY=VALUE` (repeatable) > shell `AD_VAR_KEY=...` (auto-imported as `KEY`) > built-ins (`AD_PLATFORM`, `AD_SESSION`, `AD_FILENAME`, `AD_DEVICE`, `AD_ARTIFACTS`). Unresolved `${X}` errors with `file:line`.
+
+Override at runtime without editing the file:
+
+```bash
+agent-device replay <flow>.ad -e EMAIL=other@example.com
+```
+
+## Authoring rules
+
+- **No `open`, no `close`, no `context` header.** Caller owns lifecycle.
+- **No fixed `wait` calls.** `fill`/`press` resolve selectors with retry. Only add `wait <selector>` for real post-action blocks.
+- **Durable selectors.** Prefer `id=...` first, then `role=... label=...`, with `||` fallbacks. Avoid `@eN` refs.
+- **Every flow declares `@desc` and `@pre`.** Add `@post` for outcome-bearing flows; utility flows (for example `go-back`) may omit it. Add `@tag` when applicable.
+- **Choose directory intentionally.** Put reusable setup/navigation steps in `flows/macros/`; put outcome verification scenarios in `flows/tests/`.
+- **Keep scope coherent, not artificially tiny.** Flows can span multiple screens when that sequence is the reusable intent (for example "create and submit manual expense").
+- **Peers share `@pre` and differ on `@post`.** One flow per narrow outcome is better than a mega-flow with conditional branches.
+- **Use `@param` for substituted values.** If a literal is interpolated into the body, declare `# @param KEY description.` and reference it as `${KEY}`.
+- **Do not use `env` directives in repo flows.** Runtime values must come from `-e KEY=VALUE` (preferred) or `AD_VAR_KEY=...`.
+- **Use inline defaults sparingly.** Optional tuning values can use `${KEY:-fallback}` in the body; required values should have no fallback and must be provided by caller input.
+
+## Recording a new flow
+
+1. Drive the target screen manually.
+2. Start a session with `--save-script`:
+   ```bash
+   agent-device open <app> --save-script .claude/skills/agent-device/flows/<kind>/<name>.ad
+   ```
+3. Perform the steps.
+4. `agent-device close` - flushes the `.ad`.
+5. Edit the generated file:
+   - Delete the `context` line, leading `open ... --relaunch`, trailing `close`, and eyeballing `wait`s.
+   - Move file to `flows/macros/` or `flows/tests/`, then add `@desc`, `@pre`, optional `@post`, optional `@tag`, and any needed `@param` headers.
+6. Verify: pre-check from a matching state, replay, post-check.
+
+## Maintenance
+
+Heal selector drift in place:
+
+```bash
+agent-device replay -u .claude/skills/agent-device/flows/<kind>/<name>.ad
+```
+
+Re-verify `@pre`/`@post` still hold, then commit. Note: `replay -u` can rewrite interpolated lines to concrete selectors/values; review diffs and restore `${KEY}` placeholders where needed. Keep runtime inputs in `@param` + `-e`/`AD_VAR_*`; do not reintroduce in-file `env` directives.

.claude/skills/agent-device/flows/macros/complete-onboarding.ad

@@ -0,0 +1,13 @@
+# @desc   Complete onboarding with minimal choices (skip work email, pick "Something else" purpose, enter generic name). Lands on Home.
+# @pre    text="What’s your work email?"
+# @post   text="Home"
+# @post   role="button" label="Search"
+# @tag    onboarding
+# @param  FIRST_NAME First name to enter on onboarding profile step.
+# @param  LAST_NAME Last name to enter on onboarding profile step.
+
+press "id=\"onboardingPrivateEmailSkipButton\" || role=\"button\" label=\"Skip\" || label=\"Skip\""
+press "role=\"button\" label=\"Something else\" || label=\"Something else\""
+fill "role=\"textfield\" label=\"First name\" editable=true || label=\"First name\" editable=true" "${FIRST_NAME}"
+fill "role=\"textfield\" label=\"Last name\" editable=true || label=\"Last name\" editable=true" "${LAST_NAME}"
+press "role=\"button\" label=\"Continue\" || label=\"Continue\""

.claude/skills/agent-device/flows/macros/go-back.ad

@@ -0,0 +1,4 @@
+# @desc   Generic back navigation via the HeaderWithBackButton chevron. Works on any screen that mounts HeaderWithBackButton (Create Expense, Search, Report details, settings pages, etc.).
+# @pre    role="button" label="Back"
+# @tag    navigation
+press "role=\"button\" label=\"Back\""

.claude/skills/agent-device/flows/macros/send-message.ad

@@ -0,0 +1,9 @@
+# @desc   Send a chat message from inside an already-open chat. Reusable helper for setting up state in other flows. Does not navigate or open a chat - assumes the composer is visible. For the QA scenario that exercises the ManualSendMessage Sentry span, see flows/tests/send-message.ad.
+# @pre    label="Write something..." editable=true
+# @post   label="Write something..." editable=true
+# @tag    chat
+# @param  MESSAGE Message text to send in the currently open chat.
+
+is exists "label=\"Write something...\" editable=true"
+fill "label=\"Write something...\" editable=true" "${MESSAGE}"
+press "role=\"button\" label=\"Send\" || label=\"Send\""

.claude/skills/agent-device/flows/macros/sign-in.ad

@@ -0,0 +1,10 @@
+# @desc   Sign in with the shared agent-device test account. Supports both new-account and returning-account outcomes. Caller MUST randomize EMAIL via `-e EMAIL=agent-device-testing+<9digits>@gmail.com` to avoid account flagging.
+# @pre    role="textfield" label="Phone or email"
+# @pre    role="button" label="Continue"
+# @post   text="Welcome" || text="Home"
+# @post   role="button" label="Join" || role="button" label="Search"
+# @tag    auth
+# @param  EMAIL Login email. Use randomized alias format `agent-device-testing+<9digits>@gmail.com` to avoid account flagging.
+
+fill "id=\"username\" || role=\"textfield\" label=\"Phone or email\" editable=true || label=\"Phone or email\" editable=true" "${EMAIL}"
+press "role=\"button\" label=\"Continue\" || label=\"Continue\""

.claude/skills/agent-device/flows/tests/create-expense-manual.ad

@@ -0,0 +1,28 @@
+# @desc   Open Create Expense from the FAB, enter an amount on the Manual tab, fill the Merchant field, and submit. Supports configurable currency-aware submit button matching. Exercises the full submit-chain Sentry spans end-to-end. Assumes a workspace where Category is not required.
+# @pre    role="button" label="Open actions menu"
+# @post   text="Reports"
+# @post   role="button" label="Expenses"
+# @tag    iou
+# @tag    navigation
+# @tag    perf
+# @tag    sentry-ManualCreateExpenseSubmit
+# @tag    sentry-ManualSubmitToDestinationVisible
+# @tag    sentry-ManualCreateExpenseServerResponse
+# @tag    sentry-ManualConfirmationMount
+# @tag    sentry-ManualConfirmationListReady
+# @tag    sentry-ManualConfirmationReceiptLoad
+# @tag    sentry-ManualGeolocationWait
+# @param  AMOUNT Whole-number amount to type into the Manual amount input (for example `22`).
+# @param  CURRENCY Currency symbol used by the submit CTA selector (for example `PLN` or `USD`).
+# @param  MERCHANT Merchant name to populate before submit.
+
+press "role=\"button\" label=\"Open actions menu\""
+press "role=\"button\" label=\"Create expense\" || label=\"Create expense\""
+press "label=\"Manual\""
+is exists "role=\"button\" label=\"Flip\""
+fill "editable=true" "${AMOUNT}"
+press "role=\"button\" label=\"Next\" || label=\"Next\""
+press "role=\"button\" label=\"Merchant\" || label=\"Merchant\""
+fill "role=\"text-field\" label=\"Merchant,\" editable=true || label=\"Merchant,\" editable=true" "${MERCHANT}"
+press "role=\"button\" label=\"Save\" || label=\"Save\""
+press "label=\"Create ${CURRENCY} ${AMOUNT}.00 expense\" || label=\"Create expense\""

.claude/skills/agent-device/flows/tests/open-create-expense.ad

@@ -0,0 +1,11 @@
+# @desc   From the Inbox tab, open the FAB actions menu and tap "Create expense". Triggers the ManualOpenCreateExpense Sentry span (startMoneyRequest -> IOURequestStart/Participants/Confirmation page). Assumes the user is signed in and the Inbox bottom nav with the floating action button is visible.
+# @pre    text="Inbox"
+# @pre    role="button" label="Open actions menu"
+# @post   text="Manual"
+# @tag    iou
+# @tag    navigation
+# @tag    perf
+# @tag    sentry-ManualOpenCreateExpense
+find "Inbox" "click"
+press "role=\"button\" label=\"Open actions menu\""
+press "role=\"button\" label=\"Create expense\" || label=\"Create expense\""

.claude/skills/agent-device/flows/tests/open-report.ad

@@ -0,0 +1,12 @@
+# @desc   From the Inbox tab, open a chat/report matching TARGET_CHAT in the LHN, with fallback to the first available chat row. Triggers the ManualOpenReport Sentry span (LHN row press -> report screen mounted with composer visible). Assumes the user is signed in with at least one chat in the Inbox.
+# @pre    text="Inbox"
+# @pre    role="button" label="Search"
+# @post   role="textview" label="Write something..."
+# @tag    chat
+# @tag    navigation
+# @tag    perf
+# @tag    sentry-ManualOpenReport
+# @param  TARGET_CHAT Visible report/chat title to open from Inbox LHN.
+
+find "Inbox" "click"
+find "${TARGET_CHAT}" "click"