From afbe5910a3516efe12fab4c8a3c30fc20981acb3 Mon Sep 17 00:00:00 2001
From: Piotr Stachyra <piotr.stachyra@gmail.com>
Date: Wed, 31 Dec 2025 09:57:16 +0100
Subject: [PATCH 1/3] Adjust ios build script to support regtest

---
 scripts/build-ios-sim.sh | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/scripts/build-ios-sim.sh b/scripts/build-ios-sim.sh
index 5f7550b..3dadbbc 100755
--- a/scripts/build-ios-sim.sh
+++ b/scripts/build-ios-sim.sh
@@ -13,17 +13,31 @@
 #
 # Usage:
 #   ./scripts/build-ios-sim.sh
+#   BACKEND=regtest ./scripts/build-ios-sim.sh
 set -euo pipefail
 E2E_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 IOS_ROOT="$(cd "$E2E_ROOT/../bitkit-ios" && pwd)"
 
-# Default to E2E build unless explicitly disabled.
-E2E_FLAG="${E2E:-true}"
+BACKEND="${BACKEND:-local}"
+E2E_BACKEND="local"
+E2E_NETWORK="regtest"
 XCODE_EXTRA_ARGS=()
-if [[ "$E2E_FLAG" == "true" ]]; then
-  XCODE_EXTRA_ARGS+=(SWIFT_ACTIVE_COMPILATION_CONDITIONS='$(inherited) E2E_BUILD')
+
+if [[ "$BACKEND" == "regtest" ]]; then
+  E2E_BACKEND="network"
+elif [[ "$BACKEND" == "local" ]]; then
+  E2E_BACKEND="local"
+else
+  echo "ERROR: Unsupported BACKEND value: $BACKEND" >&2
+  exit 1
 fi
 
+XCODE_EXTRA_ARGS+=(
+  "E2E_BACKEND=$E2E_BACKEND"
+  "E2E_NETWORK=$E2E_NETWORK"
+  "SWIFT_ACTIVE_COMPILATION_CONDITIONS=\$(inherited) E2E_BUILD"
+)
+
 xcodebuild \
   -project "$IOS_ROOT/Bitkit.xcodeproj" \
   -scheme Bitkit \

From b17508f522694266dd2d1675a695d96bcdd05c20 Mon Sep 17 00:00:00 2001
From: Piotr Stachyra <piotr.stachyra@gmail.com>
Date: Wed, 31 Dec 2025 13:15:29 +0100
Subject: [PATCH 2/3] update readme

---
 README.md | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 40e836e..a12c869 100644
--- a/README.md
+++ b/README.md
@@ -50,7 +50,7 @@ test/
 
 ### 🧱 Build apps locally (Android/iOS)
 
-If you have `bitkit-e2e-tests`, `bitkit-android`, and `bitkit-ios` checked out in the same parent directory, you can use the helper scripts to build local artifacts. The outputs land in `./aut` and are ready to be tested.
+If you have `bitkit-e2e-tests`, `bitkit-android`, and `bitkit-ios` checked out in the same parent directory, you can use the helper scripts to build local artifacts (local Electrum by default). The outputs land in `./aut` and are ready to be tested.
 
 ```bash
 # Android (builds ../bitkit-android and copies APK to ./aut/bitkit_e2e.apk)
@@ -60,14 +60,16 @@ If you have `bitkit-e2e-tests`, `bitkit-android`, and `bitkit-ios` checked out i
 ./scripts/build-ios-sim.sh
 ```
 
-Optional Android backend selection:
+Optional backend selection (`BACKEND=local` is default and can be omitted):
 
 ```bash
-# local Electrum (default)
-./scripts/build-android-apk.sh
-
-# regtest Electrum (network)
+# Android
+BACKEND=local ./scripts/build-android-apk.sh
 BACKEND=regtest ./scripts/build-android-apk.sh
+
+# iOS
+BACKEND=local ./scripts/build-ios-sim.sh
+BACKEND=regtest ./scripts/build-ios-sim.sh
 ```
 
 ---

From 854c5c083543a34e000377dc7cdfb83457e1eb08 Mon Sep 17 00:00:00 2001
From: Piotr Stachyra <piotr.stachyra@gmail.com>
Date: Wed, 31 Dec 2025 13:37:26 +0100
Subject: [PATCH 3/3] init agents

---
 AGENTS.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9906251
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,80 @@
+# AGENTS.md
+
+This file provides guidance to AI agents (Codex/Claude/Cursor/WARP) working in this repository.
+
+## Purpose
+
+Bitkit E2E tests for:
+- **bitkit-android** (native Android app)
+- **bitkit-ios** (native iOS app)
+
+For local work, keep `bitkit-e2e-tests`, `bitkit-android`, and `bitkit-ios` checked out in the same parent directory.
+
+## Key Paths
+
+- `aut/` — built app artifacts used by tests (`bitkit_e2e.apk`, `Bitkit.app`)
+- `artifacts/` — screenshots/videos/logs from test runs
+- `test/specs/` — E2E specs
+- `test/helpers/` — helper utilities (selectors, actions)
+- `wdio.conf.ts` — WebdriverIO/Appium config
+
+## Local Build Helpers
+
+Android (builds from `../bitkit-android`, copies APK to `./aut/bitkit_e2e.apk`):
+
+```bash
+./scripts/build-android-apk.sh
+
+# backend selection (local is default)
+BACKEND=regtest ./scripts/build-android-apk.sh
+```
+
+iOS (builds from `../bitkit-ios`, copies app to `./aut/Bitkit.app`):
+
+```bash
+./scripts/build-ios-sim.sh
+
+# backend selection (local is default)
+BACKEND=regtest ./scripts/build-ios-sim.sh
+```
+
+Notes:
+- `BACKEND=local` uses local Electrum (default).
+- `BACKEND=regtest` sets network Electrum against regtest.
+
+## Running Tests
+
+```bash
+# Android
+npm run e2e:android
+
+# iOS
+npm run e2e:ios
+```
+
+Run a single spec:
+
+```bash
+npm run e2e:android -- --spec ./test/specs/onboarding.e2e.ts
+```
+
+Run by tag:
+
+```bash
+npm run e2e:android -- --mochaOpts.grep "@backup"
+```
+
+## CI Helper Scripts
+
+These wrap the `npm run e2e:*` commands and capture logs/artifacts:
+
+```bash
+./ci_run_android.sh
+./ci_run_ios.sh
+```
+
+## Practical Tips
+
+- The tests expect built artifacts in `./aut`.
+- Use `ciIt()` in specs (not `it()`) to enable CI retry-skipping behavior.
+- Keep Android/iOS platform differences behind helpers in `test/helpers/`.