path-terminal-init 0.2.0

package/rules/ios/path-integration.mdc

@@ -0,0 +1,393 @@
+---
+description: >
+  Rules for AI agents integrating the Path Terminal SDK into an iOS 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:
+  - "**/*.swift"
+  - "**/Info.plist"
+  - "**/Package.swift"
+  - "**/*.xcodeproj/**"
+alwaysApply: false
+---
+
+# Path Terminal SDK — Integration Rules
+
+You are integrating the Path Terminal SDK into an existing iOS 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`, `validate_integration`, `get_integration_checklist`,
+  `explain_error`, `get_info_plist_requirements`
+- Always call MCP tools before writing code. Never guess at SDK patterns.
+
+> **Check whether the Swift Package is installed before doing anything else.**
+> Run:
+> ```
+> grep -c "path-terminal-sdk\|PathTerminalSDK" $(find . -maxdepth 2 -name "project.pbxproj" ! -path "*/DerivedData/*" | head -1)
+> ```
+> - **Count > 0** — package is already in the project. Do not mention SPM or
+>   package installation anywhere in your output. Proceed directly to Step 1.
+> - **Count = 0** — package is not yet added. Tell the developer to add it:
+>   1. Open Xcode → **File → Add Package Dependencies…**
+>   2. Enter URL: `https://github.com/keyman12/path-terminal-sdk`
+>   3. In the **Add to Target** sheet, tick **all four** products:
+>      `PathTerminalSDK`, `PathEmulatorAdapter`, `PathCoreModels`,
+>      `PathVerifonePSDKAdapter`
+>      (PathDiagnostics can be left as None)
+>      `PathVerifonePSDKAdapter` is required for the Verifone backend (Step 2c).
+>   4. Click **Add Package**
+>   Then stop and ask the developer to confirm the packages have been added
+>   before you continue.
+
+> **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
+> — you are not in the real project. Ask the developer to relaunch Claude Code
+> from the correct project directory. Never make changes from a Trash or temp path.
+
+---
+
+## Your job — four steps, in this order
+
+---
+
+### Step 1 — Disconnect the existing terminal wiring
+
+Find the app entry point (`@main` App struct or AppDelegate) and **read the actual
+code** — do not rely on comments or file names alone.
+
+Check the exact argument in the terminal manager initialisation call. A comment
+saying *"pass a different adapter"* does not mean it has been done — read the code.
+
+**You are looking for this pattern:**
+```swift
+// THIS is wired to Path — correct:
+TerminalManager(adapter: PathPaymentTerminalAdapter())
+
+// THIS is NOT wired to Path — fix it:
+TerminalManager()
+TerminalManager(adapter: SomeOtherAdapter())
+```
+
+If the call does not pass `PathPaymentTerminalAdapter()`, change it now.
+
+> **The class must be named exactly `PathPaymentTerminalAdapter`.** This name is
+> referenced across CLAUDE.md and the existing codebase. Do not use
+> `PathPaymentAdapter`, `PathAdapter`, or any other variation.
+
+**Also disable any auto-connect on launch** — find calls to `.connect()` in
+`.onAppear`, `init`, or app lifecycle methods that fire automatically on start.
+Remove them. Path connects manually via Settings, not on launch.
+
+> Do this before anything else. Until this is changed, all payments go through
+> the existing adapter no matter what else you do.
+
+---
+
+### 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 they are ready.** So 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. You do NOT ask the user for an IP
+> or password during this run — you build the screen, ship sensible test defaults, and
+> describe how to use it in your end-of-run summary (see Step 4).
+
+Find the Settings screen (a view named Settings, Preferences, or similar). Add a
+**Path POS Adapter** section with a backend picker offering **three** backends:
+
+| Backend | Transport | Adapter | Needs |
+|---|---|---|---|
+| **Emulator (Wi-Fi)** — *default selection* | TCP/IP | `TcpPathTerminalAdapter(host:)` | emulator IP |
+| **Emulator (Bluetooth)** | BLE | `BLEPathTerminalAdapter()` | scan + pick device |
+| **Verifone** | TCP/IP (PSDK) | `VerifonePSDKAdapter(config:)` | terminal IP + stored login |
+
+Mirror the demo app's proven pattern exactly — **call `get_code_example` with operation
+`"backend-switch"` first** and reproduce its `makeAdapter(for:)` shape. All sale / refund /
+void / receipt code is backend-agnostic; only adapter construction differs.
+
+**Persist the user's selection and connection details** (so the choice survives a relaunch).
+Store these in `UserDefaults` behind a small settings type, with test defaults so a fresh
+clone connects without typing anything:
+```swift
+enum TerminalBackend: String, CaseIterable, Identifiable {
+    case emulatorWifi = "emulator_wifi"   // default
+    case emulatorBLE  = "emulator_ble"
+    case verifone     = "verifone"
+    var id: String { rawValue }
+}
+// Stored keys: backend, emulatorHost, verifoneHost,
+//              loginUsername, loginPassword, loginShift, refundPassword
+// Test defaults: verifoneHost "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).
+
+#### Step 2b — Emulator over Bluetooth — scan and connect
+
+For the BLE backend, keep the scan/connect flow:
+1. **Scan for Path Terminals** — triggers BLE discovery
+2. Discovered devices list — each with a **Connect** button
+3. Live connection state (Scanning… / Connected / Disconnected)
+4. **Disconnect** when connected
+
+To support this, add scan/connect to the manager and adapter.
+
+**Add to `PaymentTerminalAdapter` protocol** (with no-op default implementations
+so any other existing adapter requires no changes):
+```swift
+func scanForDevices() async throws -> [TerminalDeviceInfo]
+func connectToDevice(id: String) async throws
+```
+
+**Add `TerminalDeviceInfo`** to the terminal models file **before** writing any
+code that references it — other files will fail to compile if this is added last:
+```swift
+struct TerminalDeviceInfo: Identifiable, Equatable {
+    let id: String
+    let name: String
+}
+```
+
+**Implement in `PathPaymentTerminalAdapter`** — call `get_code_example` with
+operation `"discover"` first. The SDK exposes a concrete `DiscoveredDevice` type
+with a `.name` property — use it directly. Do not use `[some Any]` or `[any Any]`
+to store devices, and do not parse names from string descriptions. Then implement:
+- `scanForDevices()` — calls `pathTerminal.discoverDevices()`, maps results to
+  `[TerminalDeviceInfo]`, stores a closure per device (so the SDK's opaque
+  device type never leaks into the rest of the app)
+- `connectToDevice(id:)` — looks up the stored closure by id and calls it
+
+> **TCP and Verifone need no scan** — `discoverDevices()` returns one synthetic
+> device for the configured host, so "Apply & Connect" can connect directly.
+
+**Expose on the terminal manager:**
+```swift
+@Published private(set) var discoveredDevices: [TerminalDeviceInfo] = []
+@Published private(set) var isScanning: Bool = false
+
+func scanForDevices() async { ... }
+func connectToDevice(_ device: TerminalDeviceInfo) async { ... }
+```
+
+#### 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"` first. Construct it from a
+`VerifoneTerminalConfig` built from the **stored** login fields — never hardcode
+credentials inline:
+```swift
+import PathVerifonePSDKAdapter   // separate SPM product — ticked at install
+
+let adapter = VerifonePSDKAdapter(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 in Settings) — 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.
+
+#### After creating PathPaymentTerminalAdapter.swift — confirm the SDK is linked
+
+Before triggering the first build, run:
+
+```
+grep -c "PBXFrameworksBuildPhase" $(find . -maxdepth 2 -name "project.pbxproj" ! -path "*/DerivedData/*" | head -1)
+```
+
+If the count is **0**, the Frameworks build phase is missing and the build will
+fail with `Undefined symbol` linker errors for PathTerminalSDK / PathEmulatorAdapter
+/ PathCoreModels. Fix it now — do not wait for the build to fail.
+
+**How to add the missing Frameworks build phase:**
+
+1. Find the four package product UUIDs from the target's `packageProductDependencies`:
+   ```
+   grep -A 8 "packageProductDependencies" $(find . -maxdepth 2 -name "project.pbxproj" ! -path "*/DerivedData/*" | head -1)
+   ```
+   You will see something like:
+   ```
+   packageProductDependencies = (
+       AAAA1111BBBB2222 /* PathCoreModels */,
+       CCCC3333DDDD4444 /* PathEmulatorAdapter */,
+       EEEE5555FFFF6666 /* PathTerminalSDK */,
+       7777888899990000 /* PathVerifonePSDKAdapter */,
+   );
+   ```
+
+2. In the `/* Begin PBXBuildFile section */`, add one entry per product. Use
+   **fresh UUIDs** for the build file entries (not the productRef UUIDs):
+   ```
+   A1A1A1A1B2B2B2B2 /* PathCoreModels in Frameworks */ = {isa = PBXBuildFile; productRef = AAAA1111BBBB2222 /* PathCoreModels */; };
+   C3C3C3C3D4D4D4D4 /* PathEmulatorAdapter in Frameworks */ = {isa = PBXBuildFile; productRef = CCCC3333DDDD4444 /* PathEmulatorAdapter */; };
+   E5E5E5E5F6F6F6F6 /* PathTerminalSDK in Frameworks */ = {isa = PBXBuildFile; productRef = EEEE5555FFFF6666 /* PathTerminalSDK */; };
+   1212343456567878 /* PathVerifonePSDKAdapter in Frameworks */ = {isa = PBXBuildFile; productRef = 7777888899990000 /* PathVerifonePSDKAdapter */; };
+   ```
+
+3. Add a `PBXFrameworksBuildPhase` section (before `PBXResourcesBuildPhase`):
+   ```
+   /* Begin PBXFrameworksBuildPhase section */
+       F7F7F7F7A8A8A8A8 /* Frameworks */ = {
+         isa = PBXFrameworksBuildPhase;
+         buildActionMask = 2147483647;
+         files = (
+           A1A1A1A1B2B2B2B2 /* PathCoreModels in Frameworks */,
+           C3C3C3C3D4D4D4D4 /* PathEmulatorAdapter in Frameworks */,
+           E5E5E5E5F6F6F6F6 /* PathTerminalSDK in Frameworks */,
+           1212343456567878 /* PathVerifonePSDKAdapter in Frameworks */,
+         );
+         runOnlyForDeploymentPostprocessing = 0;
+       };
+   /* End PBXFrameworksBuildPhase section */
+   ```
+
+4. Add the Frameworks phase UUID to the target's `buildPhases` array:
+   ```
+   buildPhases = (
+       <Sources UUID>,
+       F7F7F7F7A8A8A8A8 /* Frameworks */,    ← add this line
+       <Resources UUID>,
+   );
+   ```
+
+Replace every UUID shown above with freshly generated unique hex strings.
+**Never reuse an existing UUID from the file.** The productRef values (step 1)
+are the only values copied from the existing file.
+
+---
+
+### Step 3 — Wire sale and refund through the Path SDK
+
+If `PathPaymentTerminalAdapter.swift` already exists and implements `submitSale()`
+and `submitRefund()`, **no changes are needed to the payment flow** — once Step 1
+is done, all sales and refunds automatically go through Path.
+
+Call `validate_integration` with the existing `PathPaymentTerminalAdapter.swift`
+to confirm it is correct. Fix any warnings before proceeding.
+
+If `PathPaymentTerminalAdapter.swift` does not exist, create it:
+- Call `get_code_example` with operation `"sale"` before writing sale code
+- Call `get_code_example` with operation `"refund"` before writing refund code
+- Call `validate_integration` on your code before finalising
+
+---
+
+### Step 4 — Verify it works end to end
+
+1. Confirm the app entry point injects `PathPaymentTerminalAdapter()`.
+   If the old adapter is still the default, go back to Step 1.
+
+2. Confirm Info.plist has BLE permissions (needed for the Bluetooth backend).
+   Call `get_info_plist_requirements` if unsure.
+
+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 → Path POS Adapter → backend **Emulator (Wi-Fi)** →
+     type that IP → **Apply & Connect**. Connection state should reach `.connected`.
+   - (Optionally also prove **Emulator (Bluetooth)**: select it, **Scan**, **Connect**.)
+
+4. Return to the EPOS. Add items to the cart. Trigger a card payment.
+   When prompted, present a card / tap the NFC tag on the Path POS Emulator.
+
+5. Verify:
+   - `result.state == .approved`
+   - `result.transactionId` is non-nil
+   - Receipt data is populated (call `get_code_example` with operation `"receipt"`)
+
+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. The same sale/refund/void flow now 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` before writing any SDK code
+- Use `TransactionRequest.sale(...)` and `TransactionRequest.refund(...)` factory methods
+- Use `RequestEnvelope.create(sdkVersion:adapterVersion:)` — never build envelopes manually
+- Handle all `TransactionState` cases: `.approved`, `.declined`, `.timedOut`, `.failed`
+- For **refunds**, the success state is `.refunded` — **not** `.approved`. Using
+  `.approved` in a refund switch will never match and every refund will appear to fail.
+- Catch `PathError` and check `.recoverable` — if true, retry is safe; if false, do not retry
+- Call `validate_integration` on your code before presenting it to the developer
+- Import both `PathTerminalSDK` and `PathCoreModels`
+
+**NEVER:**
+- Use the raw `TransactionRequest` initialiser — always use the factory methods
+- Store or log card data (maskedPan is acceptable, nothing else)
+- Retry a financial operation without a new `idempotencyKey`
+- Leave the existing default adapter in place — Path must be the injected adapter
+- Leave auto-connect-on-launch running — it will connect the old adapter and bypass Path
+- Remove the existing adapter from the codebase — it must remain available alongside Path
+- Skip `PathError` handling
+- Use `[some Any]` or `[any Any]` to store discovered devices. This is always wrong:
+  ```swift
+  // WRONG — will not compile when assigned from discoverDevices():
+  let devices: [some Any]
+  let devices: [any Any]
+
+  // CORRECT — use the concrete SDK type directly:
+  let devices: [DiscoveredDevice]
+  ```
+  `DiscoveredDevice` is a concrete type from `PathCoreModels` with a `.name` property.
+- Reference a type (e.g. `TerminalDeviceInfo`) in one file before adding it to the
+  models file — add shared types to the models file first, then reference them
+- Parse device names from string descriptions — use `device.name` directly
+- Write "Pico W" anywhere in code, comments, or UI strings — always "Path POS Emulator"
+- Guess at UUIDs when editing `project.pbxproj` — always read existing UUIDs
+  from the file itself. All productRef UUIDs for the SDK packages already exist
+  in the target's `packageProductDependencies` array — use those exact values.
+
+**AMOUNTS:** Minor currency units only.
+- `100` = £1.00 GBP · `1250` = £12.50 GBP · Never pass decimals.
+
+**TIMEOUTS:**
+- Never wrap `terminal.submitSale()` or `terminal.submitRefund()` in any app-level
+  timeout shorter than 30 seconds — the Path POS Emulator needs time to wait for
+  card/NFC presentation. The SDK handles its own 30-second response ceiling.
+- Never call `terminal.connect()` automatically inside the payment or refund flow.
+  If the terminal is not connected when a payment is triggered, show an error
+  directing the user to Settings → Payment Terminal to reconnect. Do not attempt
+  to auto-reconnect mid-flow — a silent reconnect attempt masquerading as a
+  payment timeout is confusing and hard to recover from.
+
+---
+
+## After making changes
+
+Summarise what you changed:
+- 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 they're 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.

package/rules/windows-10/path-integration-windows10.mdc

@@ -0,0 +1,238 @@
+---
+description: >
+  Rules for AI agents integrating the Path Terminal SDK into a Windows 10 EPOS
+  application — the legacy WPF / .NET Framework 4.8 stack. Apply when the user asks
+  to integrate payments, connect to a payment terminal, wire a sale or refund, or
+  set up the Path emulator on a WPF app. For the modern WinUI 3 / .NET 10 stack use
+  path-integration-windows11.mdc instead.
+globs:
+  - "**/*.cs"
+  - "**/*.csproj"
+  - "**/*.xaml"
+  - "**/app.manifest"
+alwaysApply: false
+---
+
+# Path Terminal SDK — Windows 10 (WPF / .NET Framework 4.8) Integration Rules
+
+You are integrating the Path Terminal SDK into an existing **WPF / .NET Framework 4.8**
+Windows EPOS application. This app is a **developer EPOS system** that replicates a
+production environment.
+
+> **Which recipe am I in?** This is the **Windows 10** recipe — legacy WPF,
+> `net48`, `<UseWPF>true`. If the project is WinUI 3 / `net10.0-windows`, STOP and
+> use `path-integration-windows11.mdc` instead. The two stacks differ in app shell,
+> UI threading, and settings storage.
+
+You have access to the Path MCP server at mcp.path2ai.tech:
+- Tools: `get_code_example` (use platform='windows'), `explain_error`. Always call
+  `get_code_example` before writing SDK code — never guess at SDK patterns.
+
+> **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 `Get-Location` before anything.
+> If the path contains `.Trash`, `tmp`, or `worktree`, stop — ask the developer to
+> relaunch from the real project directory.
+
+---
+
+## The purpose of this integration
+
+Wire the SDK so the user can **prove the payment functions against the Path POS
+Emulator, then switch — themselves, in the app — to a real Verifone terminal when
+ready.** So Settings gets a **backend switcher**, not one hardcoded transport.
+
+> **You wire the capability; the user enters the connection details.** You build the
+> switcher, the IP field, and the credential storage, and ship sensible test
+> defaults. You do NOT ask the user for an IP or password during this run — you
+> describe how to use the screen in your end-of-run summary (Step 4).
+
+The Windows 10 **demo app** (`Path-epos-demo-sdk-Windows10`) already implements this
+exact pattern — its `TerminalService.Build()` is the reference. Mirror it.
+
+---
+
+## Step 0 — Reference the SDK (sibling-folder ProjectReference)
+
+The SDK is consumed by relative `ProjectReference`, and the SDK repo (named
+`Path-terminal-sdk-windows11` — one repo serves both Windows stacks) must be cloned as
+a **sibling** of this app. On `net48` the build automatically picks the SDK's
+`netstandard2.0` core flavour and the `net48` adapter flavours. Call `get_code_example`
+with operation='install' and platform='windows', then add these six references to the
+app's `.csproj` (adjust the `..\` depth to your project's location):
+
+```xml
+<ItemGroup>
+  <ProjectReference Include="..\..\..\Path-terminal-sdk-windows11\Path.Terminal.CoreModels\Path.Terminal.CoreModels.csproj" />
+  <ProjectReference Include="..\..\..\Path-terminal-sdk-windows11\Path.Terminal.Sdk\Path.Terminal.Sdk.csproj" />
+  <ProjectReference Include="..\..\..\Path-terminal-sdk-windows11\Path.Terminal.EmulatorAdapter\Path.Terminal.EmulatorAdapter.csproj" />
+  <ProjectReference Include="..\..\..\Path-terminal-sdk-windows11\Path.Terminal.MockAdapter\Path.Terminal.MockAdapter.csproj" />
+  <ProjectReference Include="..\..\..\Path-terminal-sdk-windows11\Path.Terminal.Diagnostics\Path.Terminal.Diagnostics.csproj" />
+  <!-- Verifone backend (Step 2c) — the net48 flavour of the PSDK adapter (PSDK 3.68.27 .NET FW binding). -->
+  <ProjectReference Include="..\..\..\Path-terminal-sdk-windows11\Path.Terminal.PsdkAdapter\Path.Terminal.PsdkAdapter.csproj" />
+</ItemGroup>
+```
+
+> **Bluetooth:** WPF/.NET FW reaches BLE through WinRT interop, which the EmulatorAdapter
+> already brings in (`Microsoft.Windows.SDK.Contracts`). The generic `app.manifest`
+> needs **no** Bluetooth declaration. The emulator Wi-Fi (TCP) and Verifone backends use
+> no Bluetooth at all.
+
+---
+
+## Your job — four steps, in this order
+
+---
+
+### Step 1 — Disconnect the existing loopback wiring
+
+The harness ships with a **loopback** adapter, `OCPayTerminalAdapter`, wired up where the
+terminal service is constructed (look in `MainWindow` / `App.xaml.cs` / the terminal
+service). **Read the actual code** — a comment is not proof.
+
+Create a Path-backed terminal service that builds `PathTerminal` from the selected
+backend (mirror the demo's `TerminalService.Build()`), and swap the app to use it
+instead of the OCPay wiring.
+
+> Keep `OCPayTerminalAdapter` in the codebase (it is the shipped loopback default) —
+> just stop wiring it as the live adapter. Do not delete it.
+
+**Also disable any auto-connect on launch** — the Path backends connect manually from
+Settings, never automatically on start.
+
+---
+
+### Step 2 — Add a backend switcher to Settings
+
+The harness already has a Settings view. Add a **Path POS Adapter** section with a
+backend picker. **Call `get_code_example` with operation='backend-switch' and
+platform='windows' first** and reproduce its `BuildTerminal` shape (the demo's
+`Build()` uses the same construction):
+
+| Backend | Transport | Adapter | Needs |
+|---|---|---|---|
+| **Emulator (Wi-Fi)** — *default* | TCP/IP | `new TcpPathTerminalAdapter(host, …)` | emulator IP |
+| **Emulator (Bluetooth)** | BLE | `new BlePathTerminalAdapter(…)` | scan + connect |
+| **Verifone** | TCP/IP (PSDK) | `new VerifonePsdkAdapter(config, …)` | terminal IP + stored login |
+
+```csharp
+public enum TerminalBackend { EmulatorBle, EmulatorWifi, Verifone }   // EmulatorWifi = the default selection
+```
+(The demo also includes a `Mock` case — optional; not required for this integration.)
+
+**Persist the selection and connection details** in the harness's settings store (the
+demo uses an `AppSettings` class writing JSON to
+`%LOCALAPPDATA%\<App>\settings.json` via a DTO). Store: `Backend`, `EmulatorHost`,
+`VerifoneHost`, `LoginUsername`, `LoginPassword`, `LoginShift`, `RefundPassword` — with
+test defaults (`VerifoneHost` "192.168.1.88", username "user", password "password123",
+shift "shift123") so a fresh clone connects without typing.
+
+#### Step 2a — Emulator (Wi-Fi, the default) and Verifone — IP entry
+
+For the two IP-addressed backends show a **host/IP text box** (label "Emulator IP" or
+"Verifone terminal IP" by selection) and an **Apply & Connect** button. On connect,
+build the matching adapter from the stored host, dispose the previous `PathTerminal`,
+and build a new one (only **one** client per terminal / per emulator Wi-Fi session).
+TCP and Verifone need no scan — `DiscoverDevicesAsync()` returns one synthetic device
+for the host, so Apply & Connect connects directly.
+
+#### Step 2b — Emulator (Bluetooth) — scan and connect
+
+For the BLE backend keep a scan/connect flow: a **Scan** button → `DiscoverDevicesAsync()`
+→ list devices → **Connect** → live connection state from the `Events` stream. Marshal
+UI updates onto the WPF UI thread (`Application.Current.Dispatcher`).
+
+#### Step 2c — Verifone backend and stored credentials
+
+Call `get_code_example` with operation='verifone-init' and platform='windows'.
+Construct it from a `VerifoneTerminalConfig` built from the **stored** login — never
+hardcode credentials inline:
+```csharp
+using Path.Terminal.PsdkAdapter;
+var adapter = new VerifonePsdkAdapter(
+    new VerifoneTerminalConfig {
+        Host = settings.VerifoneHost,
+        Username = settings.LoginUsername,
+        Password = settings.LoginPassword,
+        Shift = settings.LoginShift,
+        RefundPassword = settings.RefundPassword,
+    },
+    log: Log);
+```
+Keep the Verifone login fields **separate** (their own stored keys + editable fields).
+All terminals are treated as **generic Verifone** (same AGPA app, same PSDK
+connect/login) — no per-terminal config beyond IP + login.
+
+---
+
+### Step 3 — Wire sale, refund and void through the Path SDK
+
+Once Step 1 is done, the harness's existing payment flow calls the Path-backed service.
+Confirm the transaction methods map correctly:
+- Call `get_code_example` operation='sale' (platform='windows') — handle `TransactionState.Approved`, `Declined`, `TimedOut`, `Failed`, default.
+- Call `get_code_example` operation='refund' — pass `originalTransactionId` from the sale result.
+- Call `get_code_example` operation='void' — full reversal; success state is `Reversed`.
+- Amounts are **minor units** (`420` = £4.20). Never pass decimals.
+- Catch `PathException` and check whether it is recoverable before retrying.
+- SDK calls are async (`Task`). From WPF event handlers use `async`/`await`; never block
+  the UI thread with `.Result` / `.Wait()`.
+
+---
+
+### Step 4 — Verify it works end to end
+
+1. Confirm the app composes the Path-backed service, not `OCPayTerminalAdapter`.
+2. **Prove on the emulator first (the default — Wi-Fi/IP):**
+   - Put the Path POS Emulator in Wi-Fi mode (Config → Connection); note the `IP:port`
+     on its welcome screen.
+   - Run the app → Settings → Path POS Adapter → **Emulator (Wi-Fi)** → type that IP →
+     **Apply & Connect**. Connection state should reach Connected.
+   - (Optionally prove **Emulator (Bluetooth)**: select it, **Scan**, **Connect**.)
+3. Run a sale (amountMinor `100` = £1.00), present a card / tap the emulator's NFC tag,
+   verify `result.State == Approved`, `TransactionId` is non-null, and receipt data is
+   populated (`get_code_example` operation='receipt'). Run a refund and a void.
+4. **Then prove the switch to Verifone:** select **Verifone**, enter the terminal IP and
+   confirm the stored login, **Apply & Connect** — the SDK runs the PSDK init + login and
+   the same flow runs against the real terminal, unchanged. One client per terminal —
+   disconnect any other POS first.
+
+---
+
+## SDK rules — always follow these
+
+**ALWAYS:**
+- Call `get_code_example` (platform='windows') before writing SDK code
+- Use `TransactionRequest.Sale(...)` / `.Refund(...)` / `.Void(...)` factory methods
+- Use `RequestEnvelope.Create(...)` — never build envelopes by hand
+- For **refunds** the success state is the refunded/approved state, and for **voids** it is `Reversed` — not the sale's `Approved`
+- Dispose the old `PathTerminal` before building a new one on a backend change (the demo's
+  `TerminalService` disposes synchronously — do the same; do not rely on `await using` on net48)
+- Marshal UI updates from `Events` onto the WPF UI thread (`Application.Current.Dispatcher`)
+
+**NEVER:**
+- Use a raw `TransactionRequest` constructor — use the factory methods
+- Store or log card data (masked PAN only)
+- Retry a financial operation without a fresh `RequestEnvelope` (new idempotency key)
+- Leave `OCPayTerminalAdapter` wired as the live adapter — Path must be the live one
+- Leave auto-connect-on-launch running
+- Block the UI thread on async SDK calls with `.Result` / `.Wait()`
+- Set `OnCardRead` / `OnAck` on an adapter — `PathTerminal` owns those
+- Write "Pico W" anywhere
+
+---
+
+## After making changes
+
+Summarise each file changed and confirm Step 1 (the live adapter is now Path-backed).
+
+Then give **tailored connect instructions** — the user enters the connection details, so
+tell them exactly where you wired things in:
+- The Settings section you added the backend switcher to
+- How to connect to the emulator over **Wi-Fi/IP** (the default): which backend, where to
+  type the emulator's IP, which button connects
+- How to connect over **Bluetooth** instead (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 follow it without reading code.