path-terminal-init 0.2.12 → 0.2.16

package/rules/ios/path-integration.mdc

@@ -1,456 +1,456 @@
----
-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:
-> ```
-> find . -name "project.pbxproj" ! -path "*/DerivedData/*" ! -path "*/Pods/*" ! -path "*/.build/*" ! -path "*/SourcePackages/*" -exec grep -l "path-terminal-sdk\|Path-terminal-sdk\|PathTerminalSDK" {} +
-> ```
-> (Searches the project at **any** depth — the app's `.xcodeproj` is often nested
-> a folder or two below the repo root — so the check can't miss it. Prints the
-> project file if the package is present, nothing if it is not.)
-> - **Prints a path** — package is already in the project. Do not mention SPM or
->   package installation anywhere in your output. Proceed directly to Step 1.
-> - **Prints nothing** — 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-IOS-Release`
->      (the compiled-SDK release repo — Xcode downloads prebuilt XCFrameworks)
->   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
-
-> **Add the Bluetooth permission to Info.plist now — this is not optional.** The BLE
-> backend cannot scan without it, and iOS fails **silently**: no prompt, no error, an
-> empty device list (it looks like a dead terminal). Add it **before** writing the scan
-> code — call `get_info_plist_requirements` for the exact XML:
-> ```xml
-> <key>NSBluetoothAlwaysUsageDescription</key>
-> <string>This app uses Bluetooth to connect to the Path POS payment terminal.</string>
-> ```
-> Do this **even when you validate over Wi-Fi/IP first** — the missing key stays
-> invisible until the user tries Bluetooth, then every scan silently finds nothing.
-
-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.
-
-#### Step 2d — Merchant logo on the customer display (idle branding)
-
-Wire the terminal's **customer-display logo** as part of the integration — it is a
-one-call feature that partners expect, and it is easy to miss. Call `get_code_example`
-with operation `"idle-branding"` first, then reproduce it.
-
-- Push the logo with `terminal.setIdleBranding(CustomerDisplayContent(imageData:caption:))`
-  **right after a successful `connect()`** (and whenever the logo changes). It is a
-  **no-op while disconnected**, and a **no-op on the emulator** (only Verifone paints a
-  customer screen), so it is safe to call for any backend.
-- `imageData` is raw **PNG/JPEG bytes**. Use the app's existing logo asset if there is
-  one; otherwise a simple placeholder. Caption = the store name.
-- **Hard size rule:** the payload must fit **~32 KB base64**. A full-size photo is
-  **silently dropped by the PSDK and can wedge the next transaction**. Size the logo to
-  ~**360px** wide (a small PNG). Do not pass a camera-resolution image.
-- On success the SDK logs `idle branding pushed to customer display` — surface that in
-  your `onLog` handler so the developer can confirm it worked.
-
-Do **not** call `setIdleBranding` before connect in the payment path, and never block the
-sale/refund flow on it — it is fire-and-forget branding, not part of a transaction.
-
-#### After creating PathPaymentTerminalAdapter.swift — confirm the SDK is linked
-
-Before triggering the first build, run:
-
-```
-find . -name "project.pbxproj" ! -path "*/DerivedData/*" ! -path "*/Pods/*" ! -path "*/.build/*" ! -path "*/SourcePackages/*" -exec grep -l "PBXFrameworksBuildPhase" {} +
-```
-
-If this prints **nothing**, 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`:
-   ```
-   find . -name "project.pbxproj" ! -path "*/DerivedData/*" ! -path "*/Pods/*" ! -path "*/.build/*" ! -path "*/SourcePackages/*" -exec grep -A 8 "packageProductDependencies" {} +
-   ```
-   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 3.5 — Build to catch API mismatches (check the environment first)
-
-Confirm your Swift 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. `xcodebuild -version` — is Xcode (or its command-line tools) available?
-2. **Present** → you may run a build (e.g. `xcodebuild -scheme <App> -destination 'generic/platform=iOS' build`)
-   to surface Swift errors, then fix real API mismatches. (Full runtime verification is the
-   developer's step below — it needs Xcode + a device/simulator.)
-3. **Absent** → the integration code is complete; you just can't build *here*. Do **not** report a
-   failure. Tell the developer plainly: *"The code is done — open the project in Xcode and build;
-   paste back any errors and I'll fix them,"* and summarise every file you changed. (Xcode installs
-   from the App Store, not a package manager — don't offer to install it.)
-
-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 entry point injects `PathPaymentTerminalAdapter()`.
-   If the old adapter is still the default, go back to Step 1.
-
-2. Confirm Info.plist has the BLE permission `NSBluetoothAlwaysUsageDescription`
-   (you added it in Step 2b). If it is missing, the Bluetooth backend finds **no
-   devices** and shows no error — add it now (`get_info_plist_requirements` has the XML).
-
-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.)
-
-7. **Confirm the customer-display logo (Step 2d):** on the Verifone connect, the
-   terminal screen should show the merchant logo, and the log should read
-   `idle branding pushed to customer display`. If the screen is blank, the image is
-   almost certainly over the ~32 KB base64 limit — shrink it (a ~360px PNG) and retry.
-   (The emulator has no customer display, so nothing shows there — that is expected.)
-
----
-
-## 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`
-- When wiring the BLE backend, add `NSBluetoothAlwaysUsageDescription` to Info.plist —
-  without it iOS blocks Bluetooth scanning **silently** (empty device list, no error)
-
-**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
-- That the **merchant logo** appears on the Verifone customer display on connect
-  (Step 2d), and where to drop in their own logo asset (keep it a small ~360px PNG)
-
-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 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:
+> ```
+> find . -name "project.pbxproj" ! -path "*/DerivedData/*" ! -path "*/Pods/*" ! -path "*/.build/*" ! -path "*/SourcePackages/*" -exec grep -l "path-terminal-sdk\|Path-terminal-sdk\|PathTerminalSDK" {} +
+> ```
+> (Searches the project at **any** depth — the app's `.xcodeproj` is often nested
+> a folder or two below the repo root — so the check can't miss it. Prints the
+> project file if the package is present, nothing if it is not.)
+> - **Prints a path** — package is already in the project. Do not mention SPM or
+>   package installation anywhere in your output. Proceed directly to Step 1.
+> - **Prints nothing** — 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-IOS-Release`
+>      (the compiled-SDK release repo — Xcode downloads prebuilt XCFrameworks)
+>   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
+
+> **Add the Bluetooth permission to Info.plist now — this is not optional.** The BLE
+> backend cannot scan without it, and iOS fails **silently**: no prompt, no error, an
+> empty device list (it looks like a dead terminal). Add it **before** writing the scan
+> code — call `get_info_plist_requirements` for the exact XML:
+> ```xml
+> <key>NSBluetoothAlwaysUsageDescription</key>
+> <string>This app uses Bluetooth to connect to the Path POS payment terminal.</string>
+> ```
+> Do this **even when you validate over Wi-Fi/IP first** — the missing key stays
+> invisible until the user tries Bluetooth, then every scan silently finds nothing.
+
+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.
+
+#### Step 2d — Merchant logo on the customer display (idle branding)
+
+Wire the terminal's **customer-display logo** as part of the integration — it is a
+one-call feature that partners expect, and it is easy to miss. Call `get_code_example`
+with operation `"idle-branding"` first, then reproduce it.
+
+- Push the logo with `terminal.setIdleBranding(CustomerDisplayContent(imageData:caption:))`
+  **right after a successful `connect()`** (and whenever the logo changes). It is a
+  **no-op while disconnected**, and a **no-op on the emulator** (only Verifone paints a
+  customer screen), so it is safe to call for any backend.
+- `imageData` is raw **PNG/JPEG bytes**. Use the app's existing logo asset if there is
+  one; otherwise a simple placeholder. Caption = the store name.
+- **Hard size rule:** the payload must fit **~32 KB base64**. A full-size photo is
+  **silently dropped by the PSDK and can wedge the next transaction**. Size the logo to
+  ~**360px** wide (a small PNG). Do not pass a camera-resolution image.
+- On success the SDK logs `idle branding pushed to customer display` — surface that in
+  your `onLog` handler so the developer can confirm it worked.
+
+Do **not** call `setIdleBranding` before connect in the payment path, and never block the
+sale/refund flow on it — it is fire-and-forget branding, not part of a transaction.
+
+#### After creating PathPaymentTerminalAdapter.swift — confirm the SDK is linked
+
+Before triggering the first build, run:
+
+```
+find . -name "project.pbxproj" ! -path "*/DerivedData/*" ! -path "*/Pods/*" ! -path "*/.build/*" ! -path "*/SourcePackages/*" -exec grep -l "PBXFrameworksBuildPhase" {} +
+```
+
+If this prints **nothing**, 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`:
+   ```
+   find . -name "project.pbxproj" ! -path "*/DerivedData/*" ! -path "*/Pods/*" ! -path "*/.build/*" ! -path "*/SourcePackages/*" -exec grep -A 8 "packageProductDependencies" {} +
+   ```
+   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 3.5 — Build to catch API mismatches (check the environment first)
+
+Confirm your Swift 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. `xcodebuild -version` — is Xcode (or its command-line tools) available?
+2. **Present** → you may run a build (e.g. `xcodebuild -scheme <App> -destination 'generic/platform=iOS' build`)
+   to surface Swift errors, then fix real API mismatches. (Full runtime verification is the
+   developer's step below — it needs Xcode + a device/simulator.)
+3. **Absent** → the integration code is complete; you just can't build *here*. Do **not** report a
+   failure. Tell the developer plainly: *"The code is done — open the project in Xcode and build;
+   paste back any errors and I'll fix them,"* and summarise every file you changed. (Xcode installs
+   from the App Store, not a package manager — don't offer to install it.)
+
+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 entry point injects `PathPaymentTerminalAdapter()`.
+   If the old adapter is still the default, go back to Step 1.
+
+2. Confirm Info.plist has the BLE permission `NSBluetoothAlwaysUsageDescription`
+   (you added it in Step 2b). If it is missing, the Bluetooth backend finds **no
+   devices** and shows no error — add it now (`get_info_plist_requirements` has the XML).
+
+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.)
+
+7. **Confirm the customer-display logo (Step 2d):** on the Verifone connect, the
+   terminal screen should show the merchant logo, and the log should read
+   `idle branding pushed to customer display`. If the screen is blank, the image is
+   almost certainly over the ~32 KB base64 limit — shrink it (a ~360px PNG) and retry.
+   (The emulator has no customer display, so nothing shows there — that is expected.)
+
+---
+
+## 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`
+- When wiring the BLE backend, add `NSBluetoothAlwaysUsageDescription` to Info.plist —
+  without it iOS blocks Bluetooth scanning **silently** (empty device list, no error)
+
+**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
+- That the **merchant logo** appears on the Verifone customer display on connect
+  (Step 2d), and where to drop in their own logo asset (keep it a small ~360px PNG)
+
+Keep it brief and concrete — the user should be able to follow it without reading code.