Merge branch 'main' into feat/domain-members-move-single-user-between-groups

Author: jmusial

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

@@ -8,8 +8,23 @@ allowed-tools: Bash(agent-device *) Bash(npm root *)
 
 ## Pre-flight
 
-`agent-device` CLI version: !`agent-device --version 2>&1 || echo "NOT_INSTALLED"`
+<!-- The line below compares the installed `agent-device --version` to the required minimum 0.13.0 -->
+
+`agent-device` version check: !`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})"`
+
+> If the version check above shows `FAIL`, **STOP** and instruct the developer: `npm install -g agent-device@latest`.
 
 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.
+## Dev prerequisites
+
+Default assumption: dev build from this repo. Before `open <app>`, both must be true:
+
+1. **Metro dev server** running: `npm run start` (background).
+2. **Dev build installed** on target: `npm run ios` or `npm run android` from the repo root.
+
+Skip these only when the developer explicitly targets a non-dev build (e.g., standalone/prod artifact, or a pre-installed release build).
+
+## Flows
+
+Repeatable steps (sign-in, onboarding, etc.) are captured as composable `.ad` snippets under [`flows/`](flows/README.md). Before manually tapping through a screen, follow the **Agent decision loop** in [`flows/README.md`](flows/README.md) - it covers discovery, `@pre` filtering, replay, and `@post` verification.

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

@@ -0,0 +1,81 @@
+# Flows
+
+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`) via `# @`-prefixed comment headers, so an agent can pick the right one from a snapshot.
+
+## Agent decision loop
+
+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/*.ad` - full catalog in one read.
+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 (`@post` overlap with the requested destination when present) and present top candidates to the user with a short "why this flow" note.
+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.**
+6. `agent-device replay <path>`.
+7. 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.
+
+## 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>`).                  |
+
+Selector syntax matches the body: `id="..."`, `role="..." label="..."`, `text="..."`, `||` for fallbacks.
+
+## Parametrization (`agent-device` v0.13.0+)
+
+Lift body literals to named variables via `env` + `${VAR}` interpolation so values can be overridden at runtime without editing the file.
+
+| Construct          | Where                | Purpose                                                                          |
+| ------------------ | -------------------- | -------------------------------------------------------------------------------- |
+| `env KEY=VALUE`    | Header (after `# @`) | File-level default. Quote values with spaces or `||` chains: `env KEY="a || b"`. |
+| `${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_KEY=...` (auto-imported, prefix stripped) > file `env` > 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.
+- **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 `env` for substituted values.** If a literal is interpolated into the body, declare a matching `env` default and reference it as `${VAR}`.
+
+## 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/<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.
+   - Add `@desc`, `@pre`, optional `@post`, and `@tag` 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/<name>.ad
+```
+
+Re-verify `@pre`/`@post` still hold, then commit. Note: `replay -u` is rejected when the script declares `env` directives (rewrite would drop them); strip the `env` block manually before healing, then re-add it.

.claude/skills/agent-device/flows/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
+env FIRST_NAME=Agent
+env LAST_NAME=Device
+
+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/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
+env AMOUNT=22
+env CURRENCY=PLN
+env MERCHANT="Test Coffee"
+
+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/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/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/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    text="Navigates to a chat"
+# @post   role="textview" label="Write something..."
+# @tag    chat
+# @tag    navigation
+# @tag    perf
+# @tag    sentry-ManualOpenReport
+env TARGET_CHAT="Navigates to a chat"
+
+find "Inbox" "click"
+find "${TARGET_CHAT}" "click"

.claude/skills/agent-device/flows/open-search-router.ad

@@ -0,0 +1,10 @@
+# @desc   Open the SearchRouter from the Inbox tab. Triggers the ManualOpenSearchRouter Sentry span (Search button tap -> SearchRouterPage visible). Assumes the user is signed in.
+# @pre    text="Inbox"
+# @pre    role="button" label="Search"
+# @post   label="Search for something..." editable=true
+# @tag    navigation
+# @tag    perf
+# @tag    search
+# @tag    sentry-ManualOpenSearchRouter
+press "label=\"Inbox\" || label=\"Inbox. Your review is required\""
+press "role=\"button\" label=\"Search\""

.claude/skills/agent-device/flows/scan-receipt-init.ad

@@ -0,0 +1,12 @@
+# @desc   From the Inbox tab, open the FAB -> Create expense -> switch to Scan tab. Triggers the ManualCameraInit Sentry span (Scan tab mount -> camera session ready). Assumes the user is signed in and camera permission is granted.
+# @pre    text="Inbox"
+# @pre    role="button" label="Open actions menu"
+# @post   text="Take a photo"
+# @tag    iou
+# @tag    scan
+# @tag    perf
+# @tag    sentry-ManualCameraInit
+find "Inbox" "click"
+press "role=\"button\" label=\"Open actions menu\""
+press "role=\"button\" label=\"Create expense\" || label=\"Create expense\""
+press "label=\"Scan\""

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

@@ -0,0 +1,16 @@
+# @desc   From the Inbox tab, open a chat matching TARGET_CHAT in the LHN, type a message and send it. Triggers the ManualSendMessage Sentry span (Send press -> optimistic message fragment rendered). Assumes the user is signed in with at least one chat in the Inbox.
+# @pre    text="Inbox"
+# @pre    text="Navigates to a chat"
+# @post   label="Write something..." editable=true
+# @tag    chat
+# @tag    navigation
+# @tag    perf
+# @tag    sentry-ManualSendMessage
+env MESSAGE="Hello from agent-device ManualSendMessage flow"
+env TARGET_CHAT="Navigates to a chat"
+
+find "Inbox" "click"
+find "${TARGET_CHAT}" "click"
+is exists "label=\"Write something...\" editable=true"
+fill "label=\"Write something...\" editable=true" "${MESSAGE}"
+press "role=\"button\" label=\"Send\""