init - poc

README.md

@@ -1,3 +1,47 @@
 # sw9000-android
 
-Android app that reads NFC EMV cards and dumps everything: PPSE, AIDs, TLV tree, track2, PAN, expiry, AFL records, with raw APDUs.
+A read-only Android app that reads a contactless EMV card over NFC and shows **everything**
+obtainable from it, with full APDU-level transparency. For reading your own cards.
+
+## What it does
+
+On launch it checks NFC:
+
+- **No NFC hardware** → an "NFC not supported" screen.
+- **NFC off** → a prompt with a button to open NFC settings.
+- **NFC on** → the "tap a card" animation (a card swinging onto a phone with NFC ripples,
+  ported from the sibling `android` app). On tap it reads the card and shows:
+  - **Formatted** — PAN, cardholder name, expiry, valid-from, PAN sequence, application label /
+    preferred name / AID, issuer country, currency, ATC, PIN-try counter, AIP, Track 2, plus the
+    tag's UID / technologies / ATQA / SAK / historical bytes.
+  - **Raw dump** — the full BER-TLV tree (every tag labelled and interpreted) for each
+    application, and the complete **APDU log**: every command sent, every response, and the
+    decoded status word.
+
+The read flow is: SELECT PPSE → for each advertised AID: SELECT AID → GET PROCESSING OPTIONS
+(PDOL filled in) → READ RECORD across the AFL → GET DATA for the common counters. It never
+writes to the card and runs no transaction (no GENERATE AC), so tapping is harmless.
+
+## Scheme / country / bank
+
+Derived with no network:
+
+- **Scheme** (Visa / Mastercard / Amex / UnionPay / JCB / Discover …) — from the application AID's
+  RID and, as a fallback, the PAN's leading digits. Reliable.
+- **Issuer country** — from EMV tag `5F28` (ISO-3166 numeric), decoded to a country name. Present
+  on most cards.
+- **Issuer bank / card type / product** — *not* stored on the card. Naming the bank needs a
+  **BIN/IIN database**, which you can optionally bundle at build time: drop a tab-separated dataset
+  at `app/src/main/assets/bins.tsv` (format documented in that file). It compiles into the APK, so
+  the app still makes no network calls. Without it, the app shows the raw BIN for manual lookup,
+  and the application label (`50` / `9F12`) often carries the issuer's branding anyway.
+
+## Privacy
+
+No network. The app declares only `android.permission.NFC` — **no `INTERNET` permission**, so
+nothing read from a card can leave the device.
+
+## Build
+
+Standard Gradle / Android Studio project (AGP 9, Kotlin 2.2, Jetpack Compose). Needs a physical
+NFC-capable device; the emulator can't read cards.