path-terminal-init 0.2.11 → 0.2.12

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

@@ -1,300 +1,300 @@
----
-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 — Install the SDK (NuGet feed — no checkout)
-
-The SDK is published to the **Path NuGet feed**; you install it like any package — no clone of
-the SDK repo. One package set serves both Windows stacks: on `net48` NuGet automatically picks the
-SDK's `netstandard2.0` core flavour and the `net48` adapter flavours. Call `get_code_example`
-with operation='install' and platform='windows'.
-
-**1) Add the feed** — a `nuget.config` next to your solution:
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<configuration>
-  <packageSources>
-    <add key="path" value="https://mcp.path2ai.tech/nuget/index.json" />
-  </packageSources>
-</configuration>
-```
-
-**2) Reference the packages** in the app's `.csproj`:
-
-```xml
-<PropertyGroup>
-  <!-- The Verifone binding is x64 mixed-mode — the app must run x64. -->
-  <PlatformTarget>x64</PlatformTarget>
-</PropertyGroup>
-<ItemGroup>
-  <PackageReference Include="Path.Terminal.Sdk" Version="1.5.0" />
-  <PackageReference Include="Path.Terminal.EmulatorAdapter" Version="1.5.0" />
-  <PackageReference Include="Path.Terminal.MockAdapter" Version="1.5.0" />
-  <PackageReference Include="Path.Terminal.Diagnostics" Version="1.5.0" />
-  <!-- Verifone backend (Step 2c) — the net48 flavour of the PSDK adapter (PSDK 3.68.27 .NET FW binding). -->
-  <PackageReference Include="Path.Terminal.PsdkAdapter" Version="1.5.0" />
-</ItemGroup>
-```
-
-`Path.Terminal.CoreModels` comes in transitively via `Path.Terminal.Sdk`.
-
-> **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 3b — Merchant logo on the customer display (idle branding)
-
-The app can push a merchant logo to the terminal's **customer-facing display** (idle/attract
-mode). It works on the **emulator (Wi-Fi and Bluetooth)** and on Verifone. Call
-`get_code_example` operation='idle-branding' (platform='windows') first.
-
-**The SDK API** (on `PathTerminal`, async):
-```csharp
-Task SetIdleBrandingAsync(CustomerDisplayContent? content, CancellationToken ct = default);
-// ImageBytes = raw PNG/JPEG bytes (NOT a BitmapImage / not base64); Caption is optional.
-new CustomerDisplayContent(imageBytes, caption);   // pass null content to CLEAR the logo
-```
-
-**Add a "Customer Display" section to Settings** with:
-- A **"Show merchant logo"** toggle (persisted).
-- A **file picker** (`OpenFileDialog`, `.png`/`.jpg`) storing the image **pre-scaled to ≤ 480px
-  PNG** 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 connected**.
-
-> **CRITICAL — re-apply after every connect.** A fresh connection starts with a **blank**
-> display. Call `SetIdleBrandingAsync(...)` **right after every successful connect**, not just
-> from the button — otherwise the logo never appears. Pass `null` content to clear when the
-> toggle is off. Call it with `await` from your handler — never `.Result` / `.Wait()`.
-
-> **Best-effort + backend-gated.** `SetIdleBrandingAsync` swallows backend errors — "no
-> exception" does not prove it rendered; confirm on the device. Keep the Verifone payload small
-> (a logo pre-scaled to ≤ 480px PNG, not a full-res photo, so the base64 stays under the cap).
-
----
-
-### Step 3.5 — Build to catch API mismatches (check the environment first)
-
-Confirm your C# compiles against the SDK's **real** API. **Probe the toolchain first**, and
-treat a missing one as an environment limitation to advise on, **never as a failure:**
-
-1. `dotnet --version` — is the .NET SDK / MSBuild available? (net48 builds need it.)
-2. **Present** → run `dotnet build src\Path.Epos.TestHarness.Wpf\Path.Epos.TestHarness.Wpf.csproj`,
-   fix any real API mismatches, then continue to Step 4.
-3. **Absent** → the code is complete; you just can't build *here*. Do **not** report a failure.
-   If a package manager is present, **offer** to install the .NET SDK (`winget install Microsoft.DotNet.SDK.8`
-   or `choco install dotnet-sdk`); otherwise tell the developer: *"The code is done — build in Visual
-   Studio or with `dotnet build` and paste back any errors,"* and summarise the files you changed.
-
-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 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.
+---
+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 — Install the SDK (NuGet feed — no checkout)
+
+The SDK is published to the **Path NuGet feed**; you install it like any package — no clone of
+the SDK repo. One package set serves both Windows stacks: on `net48` NuGet automatically picks the
+SDK's `netstandard2.0` core flavour and the `net48` adapter flavours. Call `get_code_example`
+with operation='install' and platform='windows'.
+
+**1) Add the feed** — a `nuget.config` next to your solution:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <packageSources>
+    <add key="path" value="https://mcp.path2ai.tech/nuget/index.json" />
+  </packageSources>
+</configuration>
+```
+
+**2) Reference the packages** in the app's `.csproj`:
+
+```xml
+<PropertyGroup>
+  <!-- The Verifone binding is x64 mixed-mode — the app must run x64. -->
+  <PlatformTarget>x64</PlatformTarget>
+</PropertyGroup>
+<ItemGroup>
+  <PackageReference Include="Path.Terminal.Sdk" Version="1.5.0" />
+  <PackageReference Include="Path.Terminal.EmulatorAdapter" Version="1.5.0" />
+  <PackageReference Include="Path.Terminal.MockAdapter" Version="1.5.0" />
+  <PackageReference Include="Path.Terminal.Diagnostics" Version="1.5.0" />
+  <!-- Verifone backend (Step 2c) — the net48 flavour of the PSDK adapter (PSDK 3.68.27 .NET FW binding). -->
+  <PackageReference Include="Path.Terminal.PsdkAdapter" Version="1.5.0" />
+</ItemGroup>
+```
+
+`Path.Terminal.CoreModels` comes in transitively via `Path.Terminal.Sdk`.
+
+> **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 3b — Merchant logo on the customer display (idle branding)
+
+The app can push a merchant logo to the terminal's **customer-facing display** (idle/attract
+mode). It works on the **emulator (Wi-Fi and Bluetooth)** and on Verifone. Call
+`get_code_example` operation='idle-branding' (platform='windows') first.
+
+**The SDK API** (on `PathTerminal`, async):
+```csharp
+Task SetIdleBrandingAsync(CustomerDisplayContent? content, CancellationToken ct = default);
+// ImageBytes = raw PNG/JPEG bytes (NOT a BitmapImage / not base64); Caption is optional.
+new CustomerDisplayContent(imageBytes, caption);   // pass null content to CLEAR the logo
+```
+
+**Add a "Customer Display" section to Settings** with:
+- A **"Show merchant logo"** toggle (persisted).
+- A **file picker** (`OpenFileDialog`, `.png`/`.jpg`) storing the image **pre-scaled to ≤ 480px
+  PNG** 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 connected**.
+
+> **CRITICAL — re-apply after every connect.** A fresh connection starts with a **blank**
+> display. Call `SetIdleBrandingAsync(...)` **right after every successful connect**, not just
+> from the button — otherwise the logo never appears. Pass `null` content to clear when the
+> toggle is off. Call it with `await` from your handler — never `.Result` / `.Wait()`.
+
+> **Best-effort + backend-gated.** `SetIdleBrandingAsync` swallows backend errors — "no
+> exception" does not prove it rendered; confirm on the device. Keep the Verifone payload small
+> (a logo pre-scaled to ≤ 480px PNG, not a full-res photo, so the base64 stays under the cap).
+
+---
+
+### Step 3.5 — Build to catch API mismatches (check the environment first)
+
+Confirm your C# compiles against the SDK's **real** API. **Probe the toolchain first**, and
+treat a missing one as an environment limitation to advise on, **never as a failure:**
+
+1. `dotnet --version` — is the .NET SDK / MSBuild available? (net48 builds need it.)
+2. **Present** → run `dotnet build src\Path.Epos.TestHarness.Wpf\Path.Epos.TestHarness.Wpf.csproj`,
+   fix any real API mismatches, then continue to Step 4.
+3. **Absent** → the code is complete; you just can't build *here*. Do **not** report a failure.
+   If a package manager is present, **offer** to install the .NET SDK (`winget install Microsoft.DotNet.SDK.8`
+   or `choco install dotnet-sdk`); otherwise tell the developer: *"The code is done — build in Visual
+   Studio or with `dotnet build` and paste back any errors,"* and summarise the files you changed.
+
+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 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.