path-terminal-init 0.2.12 → 0.2.15

package/rules/windows-11/path-integration-windows11.mdc

@@ -1,294 +1,298 @@
----
-description: >
-  Rules for AI agents integrating the Path Terminal SDK into a Windows 11 EPOS
-  application — the modern WinUI 3 / .NET 10 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 WinUI 3 app. For the legacy WPF / .NET Framework
-  4.8 stack use path-integration-windows10.mdc instead.
-globs:
-  - "**/*.cs"
-  - "**/*.csproj"
-  - "**/*.xaml"
-  - "**/Package.appxmanifest"
-alwaysApply: false
----
-
-# Path Terminal SDK — Windows 11 (WinUI 3 / .NET 10) Integration Rules
-
-You are integrating the Path Terminal SDK into an existing **WinUI 3 / .NET 10**
-Windows EPOS application. This app is a **developer EPOS system** that replicates a
-production environment.
-
-> **Which recipe am I in?** This is the **Windows 11** recipe — modern WinUI 3,
-> `net10.0-windows`. If the project is WPF / `net48` (a `<UseWPF>true` csproj
-> targeting .NET Framework 4.8), STOP and use `path-integration-windows10.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 `pwd` (or `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 11 **demo app** (`Path-epos-demo-sdk-Windows11`) already implements this
-exact pattern — its `SdkTerminalManager.BuildTerminal()` 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. 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` (versions in lock-step with Android/iOS):
-
-```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) — bundles the Verifone .NET binding, nothing extra to download. -->
-  <PackageReference Include="Path.Terminal.PsdkAdapter" Version="1.5.0" />
-</ItemGroup>
-```
-
-`Path.Terminal.CoreModels` comes in transitively via `Path.Terminal.Sdk`.
-(The demo tills inside `Path-terminal-sdk-windows11` build against the SDK by `ProjectReference`;
-you, as an integrator, use the feed above.)
-
-> **Bluetooth needs no manifest entry here.** The harness is an *unpackaged* WinUI 3
-> app (`WindowsPackageType=None`), so BLE comes through the WinRT projections the
-> EmulatorAdapter already uses — there is no `Package.appxmanifest` capability to add.
-
----
-
-## Your job — four steps, in this order
-
----
-
-### Step 1 — Disconnect the existing loopback wiring
-
-The harness ships with a **loopback** adapter, `OCPayTerminalAdapter`, composed at the
-app root (look in `App.xaml.cs` / `Services/AppServices.cs` for where the terminal
-manager is built). **Read the actual code** — a comment is not proof.
-
-Create a Path-backed terminal manager that builds `PathTerminal` from the selected
-backend (mirror the demo's `SdkTerminalManager.BuildTerminal()`), and swap the app
-composition to use it instead of the OCPay manager.
-
-> Keep `OCPayTerminalAdapter` in the codebase (it is the shipped loopback default) —
-> just stop composing 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 page (look for `SettingsPage` / `SettingsViewModel`).
-Add a **Path POS Adapter** section with a backend picker offering **three** backends.
-**Call `get_code_example` with operation='backend-switch' and platform='windows' first**
-and reproduce its `BuildTerminal` shape exactly:
-
-| 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 { EmulatorWifi, EmulatorBle, Verifone }   // EmulatorWifi = default
-```
-
-**Persist the selection and connection details** in the harness's settings store (the
-demo uses a small `AppSettings` class writing JSON to
-`%LOCALAPPDATA%\<App>\app.json`). 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 WinUI UI thread (`DispatcherQueue.TryEnqueue`).
-
-#### 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 manager.
-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.
-
----
-
-### 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** (`FileOpenPicker`, `.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.
-
-> **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 10 SDK available?
-2. **Present** → run `dotnet build Path.Epos.TestHarness.sln -c Debug`, 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 10 SDK (`winget install Microsoft.DotNet.SDK.10`);
-   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 root composes the Path-backed manager, 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
-- Marshal UI updates from `Events` onto the WinUI UI thread (`DispatcherQueue.TryEnqueue`)
-
-**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` composed as the live adapter — Path must be the live one
-- Leave auto-connect-on-launch running
-- 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 11 EPOS
+  application — the modern WinUI 3 / .NET 10 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 WinUI 3 app. For the legacy WPF / .NET Framework
+  4.8 stack use path-integration-windows10.mdc instead.
+globs:
+  - "**/*.cs"
+  - "**/*.csproj"
+  - "**/*.xaml"
+  - "**/Package.appxmanifest"
+alwaysApply: false
+---
+
+# Path Terminal SDK — Windows 11 (WinUI 3 / .NET 10) Integration Rules
+
+You are integrating the Path Terminal SDK into an existing **WinUI 3 / .NET 10**
+Windows EPOS application. This app is a **developer EPOS system** that replicates a
+production environment.
+
+> **Which recipe am I in?** This is the **Windows 11** recipe — modern WinUI 3,
+> `net10.0-windows`. If the project is WPF / `net48` (a `<UseWPF>true` csproj
+> targeting .NET Framework 4.8), STOP and use `path-integration-windows10.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 `pwd` (or `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 11 **demo app** (`Path-epos-demo-sdk-Windows11`) already implements this
+exact pattern — its `SdkTerminalManager.BuildTerminal()` 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. 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` (versions in lock-step with Android/iOS):
+
+```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) — bundles the Verifone .NET binding, nothing extra to download. -->
+  <PackageReference Include="Path.Terminal.PsdkAdapter" Version="1.5.0" />
+</ItemGroup>
+```
+
+`Path.Terminal.CoreModels` comes in transitively via `Path.Terminal.Sdk`.
+(The demo tills inside `Path-terminal-sdk-windows11` build against the SDK by `ProjectReference`;
+you, as an integrator, use the feed above.)
+
+> **Bluetooth needs no manifest entry here.** The harness is an *unpackaged* WinUI 3
+> app (`WindowsPackageType=None`), so BLE comes through the WinRT projections the
+> EmulatorAdapter already uses — there is no `Package.appxmanifest` capability to add.
+
+---
+
+## Your job — four steps, in this order
+
+---
+
+### Step 1 — Disconnect the existing loopback wiring
+
+The harness ships with a **loopback** adapter, `OCPayTerminalAdapter`, composed at the
+app root (look in `App.xaml.cs` / `Services/AppServices.cs` for where the terminal
+manager is built). **Read the actual code** — a comment is not proof.
+
+Create a Path-backed terminal manager that builds `PathTerminal` from the selected
+backend (mirror the demo's `SdkTerminalManager.BuildTerminal()`), and swap the app
+composition to use it instead of the OCPay manager.
+
+> Keep `OCPayTerminalAdapter` in the codebase (it is the shipped loopback default) —
+> just stop composing 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 page (look for `SettingsPage` / `SettingsViewModel`).
+Add a **Path POS Adapter** section with a backend picker offering **three** backends.
+**Call `get_code_example` with operation='backend-switch' and platform='windows' first**
+and reproduce its `BuildTerminal` shape exactly:
+
+| 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 { EmulatorWifi, EmulatorBle, Verifone }   // EmulatorWifi = default
+```
+
+**Persist the selection and connection details** in the harness's settings store (the
+demo uses a small `AppSettings` class writing JSON to
+`%LOCALAPPDATA%\<App>\app.json`). Store: `Backend`, `EmulatorHost`, `VerifoneHost`,
+`LoginUsername`, `LoginPassword`, `LoginShift`, `RefundPassword` — with test defaults
+(`VerifoneHost` "192.168.1.88", username "user", password "password123", shift
+"shift123", refund password EMPTY — test estates accept empty, matching the SDK and
+Android defaults) 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 WinUI UI thread (`DispatcherQueue.TryEnqueue`).
+
+#### 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 manager.
+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 `PathError` — the SDK's exception type (there is NO `PathException`) — and check
+  its `.Recoverable` before retrying; `.Code` is the canonical error code.
+
+---
+
+### 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** (`FileOpenPicker`, `.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.
+
+> **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 10 SDK available?
+2. **Present** → run `dotnet build Path.Epos.TestHarness.sln -c Debug`, 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 10 SDK (`winget install Microsoft.DotNet.SDK.10`);
+   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 root composes the Path-backed manager, 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
+- Consume `Events` with `await foreach` on a background task — it is an
+  `IAsyncEnumerable<PathTerminalEvent>` (nested event records), NOT a C# event; there is no `+=`
+- Marshal UI updates from `Events` onto the WinUI UI thread (`DispatcherQueue.TryEnqueue`)
+
+**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` composed as the live adapter — Path must be the live one
+- Leave auto-connect-on-launch running
+- 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.