path-terminal-init 0.2.9 → 0.2.12

package/rules/android/path-integration-android.mdc

@@ -1,410 +1,410 @@
----
-description: >
-  Rules for AI agents integrating the Path Terminal SDK into an Android EPOS
-  application. Apply when the user asks to integrate payments, connect to
-  a payment terminal, wire a sale or refund, or set up the Path emulator.
-globs:
-  - "**/*.kt"
-  - "**/AndroidManifest.xml"
-  - "**/settings.gradle.kts"
-  - "**/build.gradle.kts"
-alwaysApply: false
----
-
-# Path Terminal SDK — Android Integration Rules
-
-You are integrating the Path Terminal SDK into an existing Android EPOS application.
-This app is a **developer EPOS system** that replicates a production environment.
-
-You have access to the Path MCP server at mcp.path2ai.tech:
-- Tools: `get_code_example` (use platform='android'), `validate_integration` (platform='android'),
-  `get_integration_checklist` (platform='android'), `explain_error`, `get_manifest_requirements`
-- Always call MCP tools before writing code. Never guess at SDK patterns.
-
-> **Check whether the SDK is already wired before doing anything else.**
-> Run:
-> ```
-> grep -r "path-terminal-sdk\|PathTerminal\|BLEPathTerminalAdapter" settings.gradle.kts app/build.gradle.kts 2>/dev/null | wc -l
-> ```
-> - **Count > 0** — SDK already present. Proceed directly to Step 1.
-> - **Count = 0** — SDK not yet added. Add the Gradle composite build first (Step 0).
-
-> **Language override.** Never write "Pico W" in any output or code comment.
-> Always use "Path POS Emulator" when referring to the physical device.
-
-> **Confirm the correct project directory first.** Run `pwd` before doing
-> anything. If the path contains `.Trash`, `tmp`, or `worktree`, stop immediately.
-> Ask the developer to relaunch Claude Code from the correct project directory.
-
----
-
-## Step 0 — Gradle setup (if SDK not yet installed)
-
-The Path Android SDK is served from the **Path Maven repo** — one URL gives you every
-module, **including the Verifone backend (`path-psdk-adapter`) and its `.aar`**, resolved
-transitively. **No sibling SDK checkout, no composite build, no JitPack.** (The
-`npx path-terminal-init` step usually adds these for you — verify they are present.)
-
-Call `get_code_example` with operation='install' and platform='android' for the exact lines.
-
-1. **settings.gradle.kts** — add the Path Maven repo inside
-   `dependencyResolutionManagement { repositories { … } }` (keep `google()` + `mavenCentral()`
-   — they resolve the AndroidX / Kotlin transitives):
-```kotlin
-maven { url = uri("https://mcp.path2ai.tech/maven") }
-```
-
-2. **app/build.gradle.kts** — add to `dependencies {}`:
-```kotlin
-implementation("tech.path2ai.sdk:path-core-models:1.5.0")
-implementation("tech.path2ai.sdk:path-terminal-sdk:1.5.0")
-implementation("tech.path2ai.sdk:path-emulator-adapter:1.5.0")
-implementation("tech.path2ai.sdk:path-psdk-adapter:1.5.0")   // Verifone backend (Step 2c)
-```
-The Verifone backend's `.aar` uses data binding, so enable it in the same file:
-```kotlin
-android { buildFeatures { dataBinding = true } }
-```
-
-3. **gradle.properties** — ensure `android.useAndroidX=true` (the SDK pulls AndroidX).
-
-4. **AndroidManifest.xml** — call `get_manifest_requirements` for exact XML.
-
----
-
-## Your job — four steps, in this order
-
----
-
-### Step 1 — Disconnect the existing terminal wiring
-
-Find the app entry point (Application class, MainActivity, or DI root) and **read the actual code**.
-
-Check what adapter is currently injected into the terminal manager. A comment saying
-*"replace with Path adapter"* does not mean it has been done — read the code.
-
-**You are looking for this pattern:**
-```kotlin
-// THIS is wired to Path — correct:
-terminalManager = TerminalManager(PathTerminalAdapter(this))
-
-// THIS is NOT wired to Path — fix it:
-terminalManager = TerminalManager(OCPayTerminalAdapter())
-terminalManager = TerminalManager() // default adapter
-```
-
-If the call does not use `PathTerminalAdapter` (or equivalent Path SDK adapter), change it.
-
-> **The adapter class must implement the existing `PaymentTerminalAdapter` interface.**
-> Do not rename or remove the interface — it is the integration contract.
-
-**Also disable any auto-connect on launch** — find calls to `.connect()` in
-`onCreate`, `init`, or `onResume` that fire automatically. Remove them.
-Path connects manually via Settings, not on launch.
-
----
-
-### Step 2 — Add a backend switcher to Settings
-
-The purpose of this integration is: **prove the payment functions against the Path
-POS Emulator, then let the user switch — themselves, in the app — to a real Verifone
-terminal when ready.** Settings must let the user pick *which* terminal to connect to.
-Do NOT hardcode one transport.
-
-> **Connection details are entered by the user in the app, not by you.** You wire the
-> switcher, the IP field, and the credential storage, ship sensible test defaults, and
-> describe how to use it in your end-of-run summary (Step 4). You do NOT ask the user
-> for an IP or password during this run.
-
-Find the Settings screen (a Composable or Activity named Settings, Preferences, or
-similar). Add a **Path POS Adapter** section with a backend picker offering **three**:
-
-| Backend | Transport | Adapter | Needs |
-|---|---|---|---|
-| **Emulator (Wi-Fi)** — *default selection* | TCP/IP | `TcpPathTerminalAdapter(host = …)` | emulator IP |
-| **Emulator (Bluetooth)** | BLE | `BLEPathTerminalAdapter(context = …)` | scan + pick device |
-| **Verifone** | TCP/IP (PSDK) | `VerifonePSDKAdapter(context, config)` | terminal IP + stored login |
-
-Mirror the demo app's proven pattern — **call `get_code_example` with operation
-='backend-switch' and platform='android' first** and reproduce its `buildAdapter(backend)`
-shape. All sale / refund / void / receipt code is backend-agnostic; only adapter
-construction differs.
-
-**Persist the user's selection and connection details** in `SharedPreferences` behind a
-small settings type, with test defaults so a fresh clone connects without typing anything:
-```kotlin
-enum class TerminalBackend { EMULATOR_WIFI, EMULATOR_BLE, VERIFONE }   // default EMULATOR_WIFI
-// Stored keys: backend, emulator_host, verifone_host,
-//              login_username, login_password, login_shift, refund_password
-// Test defaults: verifone_host "192.168.1.88", username "user",
-//                password "password123", shift "shift123"
-```
-
-#### Step 2a — Emulator over Wi-Fi (the default) and Verifone — IP entry
-
-For the two IP-addressed backends, show a **host/IP text field** (label it "Emulator IP"
-or "Verifone terminal IP" depending on the selection) plus an **Apply & Connect** button.
-On connect, build the matching adapter from the stored host and rebuild `PathTerminal`
-(disconnect the previous adapter first — real terminals and the emulator's Wi-Fi mode
-allow only **one** client at a time). TCP and Verifone need no scan — `discoverDevices()`
-returns one synthetic device for the configured host, so "Apply & Connect" connects directly.
-
-#### Step 2b — Emulator over Bluetooth — scan and connect
-
-> **⚠ Runtime permissions are MANDATORY — this is the #1 reason Bluetooth silently
-> fails.** Declaring `BLUETOOTH_SCAN` / `BLUETOOTH_CONNECT` in the manifest is **not
-> enough** on Android 12+ (API 31). You must **request them at runtime** before the
-> first scan, or `discoverDevices()` finds nothing / throws and the user sees an empty
-> list with no error. Call `get_code_example` with operation='backend-switch' and
-> platform='android' and reproduce its `rememberBlePermission()` pattern:
-> - Use `ActivityResultContracts.RequestMultiplePermissions()` to request
->   `BLUETOOTH_SCAN` **and** `BLUETOOTH_CONNECT` (guarded by `Build.VERSION.SDK_INT >= S`).
-> - Show a **"Grant Bluetooth permission"** button when not yet granted, and **gate the
->   Scan button** on the granted state — don't let the user scan without permission.
-> - Keep `android:usesPermissionFlags="neverForLocation"` on `BLUETOOTH_SCAN` (call
->   `get_manifest_requirements`) so `ACCESS_FINE_LOCATION` is not also required.
-> - Surface **"Bluetooth is turned off"** — `discoverDevices()` throws
->   `PathError(CONNECTIVITY)` when the radio is disabled. The emulator must be in
->   Bluetooth mode and advertise a name containing "Path".
-
-For the BLE backend keep the scan/connect flow:
-1. **Grant Bluetooth permission** (runtime, per the callout above) — required before scanning
-2. **Scan for Path Terminals** — triggers BLE discovery (only enabled once permission is granted)
-3. Discovered devices list — each with a **Connect** button
-4. Live connection state (Scanning / Connected / Disconnected)
-5. **Disconnect** when connected
-
-**Add to `PaymentTerminalAdapter` interface** (with no-op default implementations):
-```kotlin
-suspend fun scanForDevices(): List<TerminalDeviceInfo>
-suspend fun connectToDevice(id: String)
-```
-
-**Implement `PathTerminalAdapter`** — call `get_code_example` with operation='discover'
-and platform='android' first. The SDK exposes `DiscoveredDevice` with `.id` and `.name`
-properties — use them directly.
-
-**Expose on the ViewModel:**
-```kotlin
-private val _discoveredDevices = MutableStateFlow<List<TerminalDeviceInfo>>(emptyList())
-val discoveredDevices: StateFlow<List<TerminalDeviceInfo>> = _discoveredDevices.asStateFlow()
-
-private val _isScanning = MutableStateFlow(false)
-val isScanning: StateFlow<Boolean> = _isScanning.asStateFlow()
-
-fun scanForDevices() {
-    viewModelScope.launch {
-        _isScanning.value = true
-        _discoveredDevices.value = adapter.scanForDevices()
-        _isScanning.value = false
-    }
-}
-```
-
-#### Step 2c — Verifone backend and stored credentials
-
-The Verifone backend connects to a real terminal over the PSDK. Call `get_code_example`
-with operation='verifone-init' and platform='android' first. Construct it from a
-`VerifoneTerminalConfig` built from the **stored** login fields — never hardcode
-credentials inline:
-```kotlin
-import tech.path2ai.sdk.psdk.VerifonePSDKAdapter
-import tech.path2ai.sdk.psdk.VerifoneTerminalConfig
-
-val adapter = VerifonePSDKAdapter(
-    context = context,
-    config = VerifoneTerminalConfig(
-        host = settings.verifoneHost,
-        username = settings.loginUsername,
-        password = settings.loginPassword,
-        shift = settings.loginShift,
-        refundPassword = settings.refundPassword
-    )
-)
-```
-Keep the Verifone login fields **separate from the emulator settings** (their own stored
-keys, their own editable fields) — cleaner than reusing the emulator's. All terminals are
-treated as **generic Verifone** (same AGPA app, same PSDK connect/login), so no
-per-terminal configuration is needed beyond IP + login.
-
----
-
-### Step 3 — Wire sale and refund through the Path SDK
-
-Call `get_code_example` with operation='sale' and platform='android'.
-Call `get_code_example` with operation='refund' and platform='android'.
-
-**Implement `PathTerminalAdapter.submitSale()`:**
-```kotlin
-override suspend fun submitSale(request: TerminalSaleRequest): TerminalSaleResponse {
-    val envelope = RequestEnvelope.create(sdkVersion = "0.1.0", adapterVersion = "0.1.0")
-    val sdkRequest = TransactionRequest.sale(
-        amountMinor = request.amountPence,
-        currency = request.currencyCode,
-        envelope = envelope
-    )
-    val result = terminal.sale(sdkRequest)
-    return when (result.state) {
-        TransactionState.APPROVED -> TerminalSaleResponse(
-            authorised = true,
-            authorisationCode = result.cardLastFour, // map fields as needed
-            terminalReference = result.transactionId
-        )
-        else -> TerminalSaleResponse(
-            authorised = false,
-            failureReason = result.error?.message ?: result.state.name
-        )
-    }
-}
-```
-
-**For refunds**, the success state is `TransactionState.REFUNDED` — **not** `APPROVED`.
-Using `APPROVED` in a refund check will never match.
-
-Call `validate_integration` with platform='android' on your code before finalising.
-
----
-
-### Step 3b — Merchant logo on the customer display (idle branding)
-
-The demo can push a merchant logo to the terminal's **customer-facing display** (idle/
-attract mode). This is a real feature you MUST wire — it works on the **emulator (Wi-Fi
-and Bluetooth)** and on Verifone. Call `get_code_example` with operation='idle-branding'
-and platform='android' first, then reproduce the demo's proven pattern.
-
-**The SDK API** (on `PathTerminal`, a `suspend` function):
-```kotlin
-suspend fun setIdleBranding(content: CustomerDisplayContent?)
-// content: raw PNG/JPEG bytes wrapped in a class — NOT a Bitmap/base64/resource id
-CustomerDisplayContent(imageBytes = logoBytes, caption = caption?.ifBlank { null })
-// pass null to CLEAR the logo (when the "show logo" toggle is off)
-```
-
-**Add a "Customer Display" section to Settings** with:
-- A **"Show merchant logo"** toggle (persisted).
-- A **photo picker** — `ActivityResultContracts.GetContent()` launched with `"image/*"` —
-  storing the chosen image **pre-scaled to ≤ 480px PNG** in private storage (so a fresh
-  launch still has a logo). Ship a default logo asset so it works out of the box.
-- An optional **caption** field.
-- An **"Apply to terminal now"** button, **enabled only when `connectionState` is Connected**.
-
-> **CRITICAL — re-apply after every connect.** A fresh connection starts with a **blank**
-> display. The SDK re-pushes after each sale/refund, but the *first* show is yours: call
-> your `applyBranding()` (which calls `terminal.setIdleBranding(...)`) **right after every
-> successful `terminal.connect()`**, not just from the button. An integration that only
-> sets branding once, or never calls `setIdleBranding` at all, shows nothing.
-
-> **Best-effort + backend-gated.** `setIdleBranding` returns `Unit` and swallows backend
-> errors — **"no exception" does not prove the logo rendered**; confirm on the device.
-> Keep the Verifone payload small (a logo, not a full-res photo) — pre-scaling to ≤ 480px
-> PNG keeps the base64 under the ~32 000-char cap that would otherwise wedge the display.
-
-Call `validate_integration` with platform='android' before finalising.
-
----
-
-### Step 3.5 — Compile the changes (check the environment first)
-
-Confirm your code compiles against the SDK's **real** API — this catches wrong method
-names / signatures the examples can't guarantee. But **probe the build toolchain first**,
-and treat a missing one as an environment limitation to advise on, **never as a failure**:
-
-1. Probe (non-fatal — just checking):
-   - `command -v java && java -version` — a JDK 17+ on PATH?
-   - `echo "$ANDROID_HOME"`, `ls ~/Library/Android/sdk 2>/dev/null`, or an Android Studio
-     install — is the Android SDK available?
-
-2. **Toolchain present** → run `./gradlew assembleDebug` (or `compileDebugKotlin` for speed).
-   Fix any real API mismatches, then continue to Step 4.
-
-3. **Toolchain absent** → the integration code is complete; you simply can't compile *here*.
-   Do **not** report this as an error or a failed install. Instead:
-   - Check `command -v brew`. If Homebrew is available, **offer** (don't assume) to install the
-     toolchain — `brew install openjdk@21` plus the Android command-line tools — explaining
-     what it does and that it's optional.
-   - If Homebrew is absent, or the developer would rather not, tell them plainly:
-     *"The integration code is done — I can't compile in this environment. Open the project in
-     Android Studio and build; paste back any errors and I'll fix them."* Then summarise every
-     file you changed so they can review and build with confidence.
-
-Frame a missing build toolchain as **"here's how to verify"**, never as a failure of the work.
-
-### Step 4 — Verify it works end to end
-
-1. Confirm the Application/MainActivity injects `PathTerminalAdapter` (not the old adapter).
-2. Confirm AndroidManifest.xml has BLUETOOTH_SCAN and BLUETOOTH_CONNECT permissions
-   (with `neverForLocation` on SCAN) **and** that the app requests them at **runtime**
-   before scanning — manifest-only is not enough on Android 12+ (Step 2b).
-3. **Prove on the emulator first (the default path — Wi-Fi/IP):**
-   - Put the Path POS Emulator in Wi-Fi mode (Config → Connection on the device);
-     it shows its `IP:port` on the welcome screen.
-   - Run the app → Settings → Payment Terminal → backend **Emulator (Wi-Fi)** → type
-     that IP → **Apply & Connect**. connectionState should reach Connected.
-   - (Optionally also prove **Emulator (Bluetooth)**: **Grant Bluetooth permission** when
-     prompted, then select it, **Scan**, **Connect**. If Scan finds nothing, the runtime
-     permission was almost certainly not granted/requested — recheck Step 2b.)
-4. Add items to cart → Card payment → present a card / tap NFC tag on emulator when prompted.
-5. Verify:
-   - result.state == TransactionState.APPROVED (or result.isApproved == true)
-   - result.transactionId is non-null
-   - Receipt data populated via terminal.getReceiptData(transactionId)
-5b. **Prove the merchant logo (Step 3b):** in Settings → Customer Display, pick a logo and
-   tap **Apply to terminal now** while connected — confirm it appears on the emulator's
-   customer display. Then disconnect/reconnect and confirm it re-appears (proves you
-   re-apply after connect).
-6. **Then prove the switch to Verifone:** select backend **Verifone**, enter the terminal's
-   IP and confirm the stored login, **Apply & Connect** — the SDK runs the PSDK init + login
-   and the same sale/refund/void flow runs against the real terminal, unchanged. (Only one
-   client may connect to a Verifone terminal at a time — disconnect any other POS first.)
-
----
-
-## SDK rules — always follow these
-
-**ALWAYS:**
-- Call `get_code_example` with platform='android' before writing any SDK code
-- Use `TransactionRequest.sale(...)` and `TransactionRequest.refund(...)` factory methods
-- Use `RequestEnvelope.create(sdkVersion, adapterVersion)` — never build manually
-- Handle TransactionState: APPROVED, DECLINED, TIMED_OUT, FAILED, CANCELLED
-- For **refunds**, success state is `REFUNDED` — not `APPROVED`
-- Catch `PathError` and check `.recoverable`
-- Request BLE runtime permissions (`BLUETOOTH_SCAN` + `BLUETOOTH_CONNECT`) before scanning —
-  the manifest declaration alone does NOT work on Android 12+ (see Step 2b)
-- Re-apply idle branding (`terminal.setIdleBranding(CustomerDisplayContent(imageBytes, caption))`)
-  after every successful `connect()`, not just from the button (see Step 3b)
-- Call `validate_integration` with platform='android' before presenting code
-- Call from coroutines — `terminal.sale()` and `terminal.refund()` are `suspend` functions
-
-**NEVER:**
-- Use the raw `TransactionRequest(...)` constructor — always use factory methods
-- Store or log card data (cardLastFour is acceptable, nothing else)
-- Retry a financial operation without a new `RequestEnvelope` (new idempotencyKey)
-- Leave the existing default adapter in place — Path must be injected
-- Leave auto-connect-on-launch running
-- Skip `PathError` handling
-- Call blocking I/O from the main thread — all SDK calls are suspend functions
-- Wrap `terminal.sale()` in a timeout shorter than 30 seconds
-
-**AMOUNTS:** Minor currency units (pence/cents) only as integers.
-- `100` = £1.00 GBP · `1250` = £12.50 GBP · Never pass decimals.
-
-**COROUTINES:** All SDK methods are `suspend`. Always call from `viewModelScope.launch { }` or equivalent.
-
----
-
-## After making changes
-
-Summarise:
-- Each file modified and the specific change made
-- Confirm Step 1 (adapter injection) was completed
-
-Then give **tailored connect instructions** — the user enters the connection details
-themselves, so tell them exactly where you wired things in:
-- The Settings screen / section name you added the backend switcher to
-- How to connect to the emulator over **Wi-Fi/IP** (the default): which backend to pick,
-  where to type the emulator's IP, which button connects
-- How to also connect over **Bluetooth** if they prefer (Scan → Connect)
-- How to **switch to Verifone** when ready: pick Verifone, enter the terminal IP, confirm
-  the stored login, connect
-
-Keep it brief and concrete — the user should be able to follow it without reading code.
+---
+description: >
+  Rules for AI agents integrating the Path Terminal SDK into an Android EPOS
+  application. Apply when the user asks to integrate payments, connect to
+  a payment terminal, wire a sale or refund, or set up the Path emulator.
+globs:
+  - "**/*.kt"
+  - "**/AndroidManifest.xml"
+  - "**/settings.gradle.kts"
+  - "**/build.gradle.kts"
+alwaysApply: false
+---
+
+# Path Terminal SDK — Android Integration Rules
+
+You are integrating the Path Terminal SDK into an existing Android EPOS application.
+This app is a **developer EPOS system** that replicates a production environment.
+
+You have access to the Path MCP server at mcp.path2ai.tech:
+- Tools: `get_code_example` (use platform='android'), `validate_integration` (platform='android'),
+  `get_integration_checklist` (platform='android'), `explain_error`, `get_manifest_requirements`
+- Always call MCP tools before writing code. Never guess at SDK patterns.
+
+> **Check whether the SDK is already wired before doing anything else.**
+> Run:
+> ```
+> grep -r "path-terminal-sdk\|PathTerminal\|BLEPathTerminalAdapter" settings.gradle.kts app/build.gradle.kts 2>/dev/null | wc -l
+> ```
+> - **Count > 0** — SDK already present. Proceed directly to Step 1.
+> - **Count = 0** — SDK not yet added. Add the Gradle composite build first (Step 0).
+
+> **Language override.** Never write "Pico W" in any output or code comment.
+> Always use "Path POS Emulator" when referring to the physical device.
+
+> **Confirm the correct project directory first.** Run `pwd` before doing
+> anything. If the path contains `.Trash`, `tmp`, or `worktree`, stop immediately.
+> Ask the developer to relaunch Claude Code from the correct project directory.
+
+---
+
+## Step 0 — Gradle setup (if SDK not yet installed)
+
+The Path Android SDK is served from the **Path Maven repo** — one URL gives you every
+module, **including the Verifone backend (`path-psdk-adapter`) and its `.aar`**, resolved
+transitively. **No sibling SDK checkout, no composite build, no JitPack.** (The
+`npx path-terminal-init` step usually adds these for you — verify they are present.)
+
+Call `get_code_example` with operation='install' and platform='android' for the exact lines.
+
+1. **settings.gradle.kts** — add the Path Maven repo inside
+   `dependencyResolutionManagement { repositories { … } }` (keep `google()` + `mavenCentral()`
+   — they resolve the AndroidX / Kotlin transitives):
+```kotlin
+maven { url = uri("https://mcp.path2ai.tech/maven") }
+```
+
+2. **app/build.gradle.kts** — add to `dependencies {}`:
+```kotlin
+implementation("tech.path2ai.sdk:path-core-models:1.6.0")
+implementation("tech.path2ai.sdk:path-terminal-sdk:1.6.0")
+implementation("tech.path2ai.sdk:path-emulator-adapter:1.6.0")
+implementation("tech.path2ai.sdk:path-psdk-adapter:1.6.0")   // Verifone backend (Step 2c)
+```
+The Verifone backend's `.aar` uses data binding, so enable it in the same file:
+```kotlin
+android { buildFeatures { dataBinding = true } }
+```
+
+3. **gradle.properties** — ensure `android.useAndroidX=true` (the SDK pulls AndroidX).
+
+4. **AndroidManifest.xml** — call `get_manifest_requirements` for exact XML.
+
+---
+
+## Your job — four steps, in this order
+
+---
+
+### Step 1 — Disconnect the existing terminal wiring
+
+Find the app entry point (Application class, MainActivity, or DI root) and **read the actual code**.
+
+Check what adapter is currently injected into the terminal manager. A comment saying
+*"replace with Path adapter"* does not mean it has been done — read the code.
+
+**You are looking for this pattern:**
+```kotlin
+// THIS is wired to Path — correct:
+terminalManager = TerminalManager(PathTerminalAdapter(this))
+
+// THIS is NOT wired to Path — fix it:
+terminalManager = TerminalManager(OCPayTerminalAdapter())
+terminalManager = TerminalManager() // default adapter
+```
+
+If the call does not use `PathTerminalAdapter` (or equivalent Path SDK adapter), change it.
+
+> **The adapter class must implement the existing `PaymentTerminalAdapter` interface.**
+> Do not rename or remove the interface — it is the integration contract.
+
+**Also disable any auto-connect on launch** — find calls to `.connect()` in
+`onCreate`, `init`, or `onResume` that fire automatically. Remove them.
+Path connects manually via Settings, not on launch.
+
+---
+
+### Step 2 — Add a backend switcher to Settings
+
+The purpose of this integration is: **prove the payment functions against the Path
+POS Emulator, then let the user switch — themselves, in the app — to a real Verifone
+terminal when ready.** Settings must let the user pick *which* terminal to connect to.
+Do NOT hardcode one transport.
+
+> **Connection details are entered by the user in the app, not by you.** You wire the
+> switcher, the IP field, and the credential storage, ship sensible test defaults, and
+> describe how to use it in your end-of-run summary (Step 4). You do NOT ask the user
+> for an IP or password during this run.
+
+Find the Settings screen (a Composable or Activity named Settings, Preferences, or
+similar). Add a **Path POS Adapter** section with a backend picker offering **three**:
+
+| Backend | Transport | Adapter | Needs |
+|---|---|---|---|
+| **Emulator (Wi-Fi)** — *default selection* | TCP/IP | `TcpPathTerminalAdapter(host = …)` | emulator IP |
+| **Emulator (Bluetooth)** | BLE | `BLEPathTerminalAdapter(context = …)` | scan + pick device |
+| **Verifone** | TCP/IP (PSDK) | `VerifonePSDKAdapter(context, config)` | terminal IP + stored login |
+
+Mirror the demo app's proven pattern — **call `get_code_example` with operation
+='backend-switch' and platform='android' first** and reproduce its `buildAdapter(backend)`
+shape. All sale / refund / void / receipt code is backend-agnostic; only adapter
+construction differs.
+
+**Persist the user's selection and connection details** in `SharedPreferences` behind a
+small settings type, with test defaults so a fresh clone connects without typing anything:
+```kotlin
+enum class TerminalBackend { EMULATOR_WIFI, EMULATOR_BLE, VERIFONE }   // default EMULATOR_WIFI
+// Stored keys: backend, emulator_host, verifone_host,
+//              login_username, login_password, login_shift, refund_password
+// Test defaults: verifone_host "192.168.1.88", username "user",
+//                password "password123", shift "shift123"
+```
+
+#### Step 2a — Emulator over Wi-Fi (the default) and Verifone — IP entry
+
+For the two IP-addressed backends, show a **host/IP text field** (label it "Emulator IP"
+or "Verifone terminal IP" depending on the selection) plus an **Apply & Connect** button.
+On connect, build the matching adapter from the stored host and rebuild `PathTerminal`
+(disconnect the previous adapter first — real terminals and the emulator's Wi-Fi mode
+allow only **one** client at a time). TCP and Verifone need no scan — `discoverDevices()`
+returns one synthetic device for the configured host, so "Apply & Connect" connects directly.
+
+#### Step 2b — Emulator over Bluetooth — scan and connect
+
+> **⚠ Runtime permissions are MANDATORY — this is the #1 reason Bluetooth silently
+> fails.** Declaring `BLUETOOTH_SCAN` / `BLUETOOTH_CONNECT` in the manifest is **not
+> enough** on Android 12+ (API 31). You must **request them at runtime** before the
+> first scan, or `discoverDevices()` finds nothing / throws and the user sees an empty
+> list with no error. Call `get_code_example` with operation='backend-switch' and
+> platform='android' and reproduce its `rememberBlePermission()` pattern:
+> - Use `ActivityResultContracts.RequestMultiplePermissions()` to request
+>   `BLUETOOTH_SCAN` **and** `BLUETOOTH_CONNECT` (guarded by `Build.VERSION.SDK_INT >= S`).
+> - Show a **"Grant Bluetooth permission"** button when not yet granted, and **gate the
+>   Scan button** on the granted state — don't let the user scan without permission.
+> - Keep `android:usesPermissionFlags="neverForLocation"` on `BLUETOOTH_SCAN` (call
+>   `get_manifest_requirements`) so `ACCESS_FINE_LOCATION` is not also required.
+> - Surface **"Bluetooth is turned off"** — `discoverDevices()` throws
+>   `PathError(CONNECTIVITY)` when the radio is disabled. The emulator must be in
+>   Bluetooth mode and advertise a name containing "Path".
+
+For the BLE backend keep the scan/connect flow:
+1. **Grant Bluetooth permission** (runtime, per the callout above) — required before scanning
+2. **Scan for Path Terminals** — triggers BLE discovery (only enabled once permission is granted)
+3. Discovered devices list — each with a **Connect** button
+4. Live connection state (Scanning / Connected / Disconnected)
+5. **Disconnect** when connected
+
+**Add to `PaymentTerminalAdapter` interface** (with no-op default implementations):
+```kotlin
+suspend fun scanForDevices(): List<TerminalDeviceInfo>
+suspend fun connectToDevice(id: String)
+```
+
+**Implement `PathTerminalAdapter`** — call `get_code_example` with operation='discover'
+and platform='android' first. The SDK exposes `DiscoveredDevice` with `.id` and `.name`
+properties — use them directly.
+
+**Expose on the ViewModel:**
+```kotlin
+private val _discoveredDevices = MutableStateFlow<List<TerminalDeviceInfo>>(emptyList())
+val discoveredDevices: StateFlow<List<TerminalDeviceInfo>> = _discoveredDevices.asStateFlow()
+
+private val _isScanning = MutableStateFlow(false)
+val isScanning: StateFlow<Boolean> = _isScanning.asStateFlow()
+
+fun scanForDevices() {
+    viewModelScope.launch {
+        _isScanning.value = true
+        _discoveredDevices.value = adapter.scanForDevices()
+        _isScanning.value = false
+    }
+}
+```
+
+#### Step 2c — Verifone backend and stored credentials
+
+The Verifone backend connects to a real terminal over the PSDK. Call `get_code_example`
+with operation='verifone-init' and platform='android' first. Construct it from a
+`VerifoneTerminalConfig` built from the **stored** login fields — never hardcode
+credentials inline:
+```kotlin
+import tech.path2ai.sdk.psdk.VerifonePSDKAdapter
+import tech.path2ai.sdk.psdk.VerifoneTerminalConfig
+
+val adapter = VerifonePSDKAdapter(
+    context = context,
+    config = VerifoneTerminalConfig(
+        host = settings.verifoneHost,
+        username = settings.loginUsername,
+        password = settings.loginPassword,
+        shift = settings.loginShift,
+        refundPassword = settings.refundPassword
+    )
+)
+```
+Keep the Verifone login fields **separate from the emulator settings** (their own stored
+keys, their own editable fields) — cleaner than reusing the emulator's. All terminals are
+treated as **generic Verifone** (same AGPA app, same PSDK connect/login), so no
+per-terminal configuration is needed beyond IP + login.
+
+---
+
+### Step 3 — Wire sale and refund through the Path SDK
+
+Call `get_code_example` with operation='sale' and platform='android'.
+Call `get_code_example` with operation='refund' and platform='android'.
+
+**Implement `PathTerminalAdapter.submitSale()`:**
+```kotlin
+override suspend fun submitSale(request: TerminalSaleRequest): TerminalSaleResponse {
+    val envelope = RequestEnvelope.create(sdkVersion = "0.1.0", adapterVersion = "0.1.0")
+    val sdkRequest = TransactionRequest.sale(
+        amountMinor = request.amountPence,
+        currency = request.currencyCode,
+        envelope = envelope
+    )
+    val result = terminal.sale(sdkRequest)
+    return when (result.state) {
+        TransactionState.APPROVED -> TerminalSaleResponse(
+            authorised = true,
+            authorisationCode = result.cardLastFour, // map fields as needed
+            terminalReference = result.transactionId
+        )
+        else -> TerminalSaleResponse(
+            authorised = false,
+            failureReason = result.error?.message ?: result.state.name
+        )
+    }
+}
+```
+
+**For refunds**, the success state is `TransactionState.REFUNDED` — **not** `APPROVED`.
+Using `APPROVED` in a refund check will never match.
+
+Call `validate_integration` with platform='android' on your code before finalising.
+
+---
+
+### Step 3b — Merchant logo on the customer display (idle branding)
+
+The demo can push a merchant logo to the terminal's **customer-facing display** (idle/
+attract mode). This is a real feature you MUST wire — it works on the **emulator (Wi-Fi
+and Bluetooth)** and on Verifone. Call `get_code_example` with operation='idle-branding'
+and platform='android' first, then reproduce the demo's proven pattern.
+
+**The SDK API** (on `PathTerminal`, a `suspend` function):
+```kotlin
+suspend fun setIdleBranding(content: CustomerDisplayContent?)
+// content: raw PNG/JPEG bytes wrapped in a class — NOT a Bitmap/base64/resource id
+CustomerDisplayContent(imageBytes = logoBytes, caption = caption?.ifBlank { null })
+// pass null to CLEAR the logo (when the "show logo" toggle is off)
+```
+
+**Add a "Customer Display" section to Settings** with:
+- A **"Show merchant logo"** toggle (persisted).
+- A **photo picker** — `ActivityResultContracts.GetContent()` launched with `"image/*"` —
+  storing the chosen image **pre-scaled to ≤ 480px PNG** in private storage (so a fresh
+  launch still has a logo). Ship a default logo asset so it works out of the box.
+- An optional **caption** field.
+- An **"Apply to terminal now"** button, **enabled only when `connectionState` is Connected**.
+
+> **CRITICAL — re-apply after every connect.** A fresh connection starts with a **blank**
+> display. The SDK re-pushes after each sale/refund, but the *first* show is yours: call
+> your `applyBranding()` (which calls `terminal.setIdleBranding(...)`) **right after every
+> successful `terminal.connect()`**, not just from the button. An integration that only
+> sets branding once, or never calls `setIdleBranding` at all, shows nothing.
+
+> **Best-effort + backend-gated.** `setIdleBranding` returns `Unit` and swallows backend
+> errors — **"no exception" does not prove the logo rendered**; confirm on the device.
+> Keep the Verifone payload small (a logo, not a full-res photo) — pre-scaling to ≤ 480px
+> PNG keeps the base64 under the ~32 000-char cap that would otherwise wedge the display.
+
+Call `validate_integration` with platform='android' before finalising.
+
+---
+
+### Step 3.5 — Compile the changes (check the environment first)
+
+Confirm your code compiles against the SDK's **real** API — this catches wrong method
+names / signatures the examples can't guarantee. But **probe the build toolchain first**,
+and treat a missing one as an environment limitation to advise on, **never as a failure**:
+
+1. Probe (non-fatal — just checking):
+   - `command -v java && java -version` — a JDK 17+ on PATH?
+   - `echo "$ANDROID_HOME"`, `ls ~/Library/Android/sdk 2>/dev/null`, or an Android Studio
+     install — is the Android SDK available?
+
+2. **Toolchain present** → run `./gradlew assembleDebug` (or `compileDebugKotlin` for speed).
+   Fix any real API mismatches, then continue to Step 4.
+
+3. **Toolchain absent** → the integration code is complete; you simply can't compile *here*.
+   Do **not** report this as an error or a failed install. Instead:
+   - Check `command -v brew`. If Homebrew is available, **offer** (don't assume) to install the
+     toolchain — `brew install openjdk@21` plus the Android command-line tools — explaining
+     what it does and that it's optional.
+   - If Homebrew is absent, or the developer would rather not, tell them plainly:
+     *"The integration code is done — I can't compile in this environment. Open the project in
+     Android Studio and build; paste back any errors and I'll fix them."* Then summarise every
+     file you changed so they can review and build with confidence.
+
+Frame a missing build toolchain as **"here's how to verify"**, never as a failure of the work.
+
+### Step 4 — Verify it works end to end
+
+1. Confirm the Application/MainActivity injects `PathTerminalAdapter` (not the old adapter).
+2. Confirm AndroidManifest.xml has BLUETOOTH_SCAN and BLUETOOTH_CONNECT permissions
+   (with `neverForLocation` on SCAN) **and** that the app requests them at **runtime**
+   before scanning — manifest-only is not enough on Android 12+ (Step 2b).
+3. **Prove on the emulator first (the default path — Wi-Fi/IP):**
+   - Put the Path POS Emulator in Wi-Fi mode (Config → Connection on the device);
+     it shows its `IP:port` on the welcome screen.
+   - Run the app → Settings → Payment Terminal → backend **Emulator (Wi-Fi)** → type
+     that IP → **Apply & Connect**. connectionState should reach Connected.
+   - (Optionally also prove **Emulator (Bluetooth)**: **Grant Bluetooth permission** when
+     prompted, then select it, **Scan**, **Connect**. If Scan finds nothing, the runtime
+     permission was almost certainly not granted/requested — recheck Step 2b.)
+4. Add items to cart → Card payment → present a card / tap NFC tag on emulator when prompted.
+5. Verify:
+   - result.state == TransactionState.APPROVED (or result.isApproved == true)
+   - result.transactionId is non-null
+   - Receipt data populated via terminal.getReceiptData(transactionId)
+5b. **Prove the merchant logo (Step 3b):** in Settings → Customer Display, pick a logo and
+   tap **Apply to terminal now** while connected — confirm it appears on the emulator's
+   customer display. Then disconnect/reconnect and confirm it re-appears (proves you
+   re-apply after connect).
+6. **Then prove the switch to Verifone:** select backend **Verifone**, enter the terminal's
+   IP and confirm the stored login, **Apply & Connect** — the SDK runs the PSDK init + login
+   and the same sale/refund/void flow runs against the real terminal, unchanged. (Only one
+   client may connect to a Verifone terminal at a time — disconnect any other POS first.)
+
+---
+
+## SDK rules — always follow these
+
+**ALWAYS:**
+- Call `get_code_example` with platform='android' before writing any SDK code
+- Use `TransactionRequest.sale(...)` and `TransactionRequest.refund(...)` factory methods
+- Use `RequestEnvelope.create(sdkVersion, adapterVersion)` — never build manually
+- Handle TransactionState: APPROVED, DECLINED, TIMED_OUT, FAILED, CANCELLED
+- For **refunds**, success state is `REFUNDED` — not `APPROVED`
+- Catch `PathError` and check `.recoverable`
+- Request BLE runtime permissions (`BLUETOOTH_SCAN` + `BLUETOOTH_CONNECT`) before scanning —
+  the manifest declaration alone does NOT work on Android 12+ (see Step 2b)
+- Re-apply idle branding (`terminal.setIdleBranding(CustomerDisplayContent(imageBytes, caption))`)
+  after every successful `connect()`, not just from the button (see Step 3b)
+- Call `validate_integration` with platform='android' before presenting code
+- Call from coroutines — `terminal.sale()` and `terminal.refund()` are `suspend` functions
+
+**NEVER:**
+- Use the raw `TransactionRequest(...)` constructor — always use factory methods
+- Store or log card data (cardLastFour is acceptable, nothing else)
+- Retry a financial operation without a new `RequestEnvelope` (new idempotencyKey)
+- Leave the existing default adapter in place — Path must be injected
+- Leave auto-connect-on-launch running
+- Skip `PathError` handling
+- Call blocking I/O from the main thread — all SDK calls are suspend functions
+- Wrap `terminal.sale()` in a timeout shorter than 30 seconds
+
+**AMOUNTS:** Minor currency units (pence/cents) only as integers.
+- `100` = £1.00 GBP · `1250` = £12.50 GBP · Never pass decimals.
+
+**COROUTINES:** All SDK methods are `suspend`. Always call from `viewModelScope.launch { }` or equivalent.
+
+---
+
+## After making changes
+
+Summarise:
+- Each file modified and the specific change made
+- Confirm Step 1 (adapter injection) was completed
+
+Then give **tailored connect instructions** — the user enters the connection details
+themselves, so tell them exactly where you wired things in:
+- The Settings screen / section name you added the backend switcher to
+- How to connect to the emulator over **Wi-Fi/IP** (the default): which backend to pick,
+  where to type the emulator's IP, which button connects
+- How to also connect over **Bluetooth** if they prefer (Scan → Connect)
+- How to **switch to Verifone** when ready: pick Verifone, enter the terminal IP, confirm
+  the stored login, connect
+
+Keep it brief and concrete — the user should be able to follow it without reading code.