1 files changed, 96 insertions, 0 deletions

diff --git a/interop/AGENTS.md b/interop/AGENTS.md
new file mode 100644
index 0000000..33a2d6d
--- /dev/null
+++ b/interop/AGENTS.md
@@ -0,0 +1,96 @@
+# AGENTS.md — Interop Test Standing Instructions
+
+## Overview
+
+Cross-platform interoperability tests for ESP32 TollGate firmware vs OpenWRT TollGate (tollgate-module-basic-go). Makefile-driven tests that verify Cashu e-cash token compatibility and upstream payment flows between the two implementations.
+
+## Standing Instructions
+
+1. **Always maintain these files:**
+   - `INTEROP_PLAN.md` — up-to-date interop test plan
+   - `PROGRESS.md` — checklist of done/pending items
+
+2. **Testing requirements:**
+   - All interop targets must be idempotent — safe to re-run
+   - Cleanup targets must restore original state
+   - Never leave a device in a broken state
+
+3. **Commit discipline:**
+   - Commit every time a test scenario passes end-to-end
+   - Push after each commit
+
+4. **No comments in code** unless explicitly requested
+
+5. **No secrets in git** — all secrets in `routers.env` (gitignored) or `.env`
+
+6. **Device safety:**
+   - Always save upstream state before changing it
+   - Always restore upstream state after tests
+   - Use router mutex (if shared with other sessions)
+
+## Repository Context
+
+This directory lives inside `esp32-tollgate/interop/`. The parent repo has its own `AGENTS.md` with firmware testing rules. This file covers interop testing only.
+
+## Device Access
+
+| Device | Transport | Address | Notes |
+|--------|-----------|---------|-------|
+| OpenWRT (alpha) | SSH | `root@10.47.41.1` | Ethernet at `enx00e04c683d2d` |
+| ESP32 Board A | WiFi API | `10.192.45.1` | WiFi at `wlp59s0`, SSID `TollGate-C0E9CA` |
+| ESP32 Board A | Serial | `/dev/ttyACM0` | USB serial, 115200 baud |
+| ESP32 Board B | Serial | `/dev/ttyACM1` | USB serial, 115200 baud |
+
+## Token Generation
+
+| Target | Tool | Format | Command |
+|--------|------|--------|---------|
+| ESP32 | `cashu` CLI | V3 (cashuA) | `cashu --env-mint testnut.cashu.space send --legacy 21` |
+| OpenWRT | `mint-token` | V4 | `/tmp/mint-token nofee.testnut.cashu.space 1` |
+
+**ESP32 only accepts V3 tokens.** OpenWRT accepts both V3 and V4.
+
+## Mint URLs
+
+| Mint | URL | Auto-pay |
+|------|-----|----------|
+| testnut | `https://testnut.cashu.space` | Yes |
+| nofee-testnut | `https://nofee.testnut.cashu.space` | Yes |
+
+Both must be in both devices' accepted_mints for cross-platform payment.
+
+## Key Commands
+
+```bash
+# Show all device status
+make interop-status
+
+# Full setup (mints + wallets)
+make interop-setup
+
+# Run individual scenarios
+make interop-laptop-esp32
+make interop-laptop-openwrt
+make interop-openwrt-esp32
+make interop-esp32-esp32
+
+# Cleanup after tests
+make interop-cleanup
+```
+
+## Network Interfaces
+
+| Interface | Device | Purpose |
+|-----------|--------|---------|
+| `enx00e04c683d2d` | Laptop | Ethernet to OpenWRT LAN (`10.47.41.x`) |
+| `wlp59s0` | Laptop | WiFi to ESP32 AP (`10.192.45.x`) |
+
+The laptop has simultaneous connectivity to both devices via different interfaces.
+
+## Troubleshooting
+
+- **OpenWRT unreachable**: Check ethernet cable, `ip addr show enx00e04c683d2d`
+- **ESP32 unreachable**: Check WiFi connection, `nmcli dev wifi connect TollGate-C0E9CA`
+- **Token rejected**: Check mint URL matches accepted_mints on target device
+- **OpenWRT won't auto-pay**: Check wallet balance > 0, check daemon logs `logread -e tollgate-wrt -f`
+- **ESP32 serial**: `python3 -m serial.tools.miniterm /dev/ttyACM0 115200`