Add Apex OTP importer

Import TOTP credentials from the export spreadsheet into a VivoKey Apex
OTP (ykneo-oath) applet over PC/SC. Includes the OATH protocol layer
(SELECT/VALIDATE/LIST/PUT with 61xx reassembly), PBKDF2 password
authentication, pre-flight input validation, ask-per-conflict handling,
optional javacard-memory profiling, and hardware-free unit tests.

README.md

@@ -0,0 +1,61 @@
+# otp-import
+
+Import TOTP credentials from an exported spreadsheet into a VivoKey Apex OTP
+(ykneo-oath) applet over PC/SC.
+
+The importer reads the curated columns of an export spreadsheet
+(`otp-keys-export.xlsx`: Issuer, Account, Secret, Type, Algorithm, Digits,
+Period) and writes each credential to the applet using the standard YKOATH
+`PUT` command. It authenticates first if the applet is password-protected, asks
+before overwriting credentials that already exist, and can optionally profile
+per-credential on-chip memory consumption via the `javacard-memory` applet.
+
+The protocol layer is verified against the applet sources
+(`com.vivokey.otp.YkneoOath` / `OathObj`) and `doc/Protocol.txt`. See
+[docs/design.md](docs/design.md) for the full design and protocol notes.
+
+## Security
+
+This tool handles live TOTP secrets. **Keep your secrets out of this
+repository.** The spreadsheet, any CSV, and QR screenshots are excluded by
+`.gitignore`; keep the actual data in a private location (e.g. a synced
+personal folder) and point the importer at it with `--input`.
+
+## Requirements
+
+- Python 3.9+
+- `pyscard`, `cryptography`, `openpyxl`
+- A PC/SC reader with the Apex (or a JavaCard carrying the applet) presented
+
+## Usage
+
+```
+# 1. Validate the data and preview the APDUs (no card needed)
+python apex_otp_import.py --input /path/to/otp-keys-export.xlsx --dry-run
+
+# 2. Read-only: list what is already on the applet
+python apex_otp_import.py --input /path/to/otp-keys-export.xlsx --list
+
+# 3. Import (asks before overwriting existing credentials)
+python apex_otp_import.py --input /path/to/otp-keys-export.xlsx
+
+# Non-interactive conflict handling
+python apex_otp_import.py --input ... --overwrite-all
+python apex_otp_import.py --input ... --skip-existing
+
+# Target a specific reader, supply a password, and profile memory
+python apex_otp_import.py --input ... --reader VivoKey --password '...' --profile-memory
+```
+
+The input is validated before any reader is touched. Duplicate credential names,
+invalid Base32, over-long names/keys, and unsupported algorithms halt the run
+with a report so they can be fixed in the source data.
+
+## Tests
+
+Hardware-free unit tests cover the protocol encoding, password derivation,
+input validation, and response reassembly:
+
+```
+python test_oath.py
+```