Add PN532 toolkit firmware, web UI, and embedded SPIFFS assets

Includes ESP-IDF NFC stack (deep capture, 4K Classic geometry, UL write API,
open SoftAP), React dashboard with live tag diagnostics, and docs. README
updated for APIs and lab Wi-Fi defaults.

Made-with: Cursor

docs/FLASHING.md

@@ -0,0 +1,34 @@
+# Flashing
+
+## Prerequisites
+
+- [ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/latest/esp-idf-en-latest-esp32s3/esp32s3/get-started-esp32s3.html) **v5.x** installed and exported (`get_idf`)
+- USB cable to the DevKit **USB** port (USB‑JTAG / serial)
+- PN532 module wired per [PINOUT.md](PINOUT.md)
+
+## Steps
+
+1. Build the web assets (embeds into SPIFFS):
+
+   ```bash
+   cd web && npm install && npm run build:fw
+   ```
+
+2. Configure & flash:
+
+   ```bash
+   cd firmware
+   idf.py set-target esp32s3
+   idf.py menuconfig   # set PN532 transport + GPIOs
+   idf.py build flash monitor
+   ```
+
+3. Connect to AP **PN532-Toolkit** / **nfc-toolkit**, browse to **http://192.168.4.1** or **http://pn532tool.local**.
+
+## SPIFFS / UI missing?
+
+If `firmware/data/` is empty, the device serves a placeholder HTML. Always run `npm run build:fw` before `idf.py build` if you changed the UI.
+
+## Flash size
+
+`partitions.csv` assumes **8MB** flash. For **4MB**, shrink `factory` / OTA / `storage` regions and disable dual OTA if needed.

docs/LIMITATIONS.md

@@ -0,0 +1,9 @@
+# Capabilities & limitations
+
+The PN532 is a **hosted NFC controller**, not a low-level RF lab instrument. This project exposes PN532 features honestly:
+
+- **ISO14443-B**: reader support exists with **chip-level caveats** (anticollision / stack-dependent behavior). No promises of full mobile/PICC coverage.
+- **Card emulation / TG modes**: PN532 firmware supports target commands; real-world mimicry depends on timing, UID size, and reader expectations — expose experimentally, not as “propable MIFARE magic.”
+- **Key recovery**: on-device “brute force” at Proxmark scale is **infeasible**. The UI provides **dictionary / manual** key workflows.
+- **Signal / RF metrics**: diagnostics use **PN532 status / timings / retries**, not calibrated dBm.
+- **OTA via UI**: `POST /api/ota` is a **stub** (`501`) — ship OTA with `esp_https_ota` + signed images when you need production updates.

docs/PINOUT.md

@@ -0,0 +1,22 @@
+# Pinout notes (ESP32-S3-DevKitC-1)
+
+Strapping and USB pins differ by revision — **avoid** GPIO `19–20` for PN532 when using USB-Serial/JTAG on many boards. Prefer **SPI2** on free GPIOs from the [DevKitC-1 user guide](https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s3/esp32-s3-devkitc-1/user_guide_v1.1.html).
+
+## Kconfig defaults (examples only)
+
+The firmware Kconfig ships **example** GPIOs:
+
+- **SPI**: MOSI `11`, MISO `13`, SCLK `12`, CS `10`
+- **I2C**: SDA `8`, SCL `9`
+
+**You must verify** these against your PCB/breadboard and PN532 breakout (Adafruit / Elechouse / clones often label SPI and I2C jumpers).
+
+## PN532 wiring checklist
+
+- **SPI**: connect `RSTO`/`RST` to MCU if exposed; some breakouts auto-reset via I2C/SPI activity.
+- **I2C**: set address pins per module (usually **0x24** 7‑bit).
+- **Power**: **3.3V** logic on ESP32; ensure PN532 module is 3.3V compliant (level-shift if using a 5V Arduino-style shield).
+
+## Transport selection
+
+Start with the bus your breakout is jumpered for — **I2C is often simplest** on ESP32 for bring-up; SPI may require **lower clock** initially (e.g. **100 kHz**).

docs/WORKFLOWS.md

@@ -0,0 +1,28 @@
+# Example workflows
+
+## 1. Read a MIFARE Classic sector
+
+1. Dashboard → **Poll once** to verify presence and UID.
+2. **Read** tab → enter default key (e.g. `FFFFFFFFFFFF`), block number, **MIFARE read block**.
+3. Copy hex → save to **Library** (local browser).
+
+## 2. Write a known-good block
+
+1. Authenticate with a key that still allows write on that sector.
+2. **Write** tab → paste **32 hex chars** (16 bytes) → confirm dialog.
+3. Re-read the block to verify.
+
+## 3. Ultralight / NTAG pages
+
+1. Use **Read** → **Ultralight read page** with page index (start at `0` for UID/lock pages per datasheet — exercise caution on OTP/lock bytes).
+
+## 4. Raw PN532 frames
+
+1. **Raw** tab → send e.g. `4A0100` (`InListPassiveTarget`, 1 target, 106 kbps Type A).
+2. Interpret response bytes per NXP **UM0701** / PN532 user manual.
+
+## 5. Continuous scan to WebSocket consumers
+
+1. Dashboard → **Start live scan**.
+2. Connect a WebSocket client to `ws://192.168.4.1/ws` (or `ws://pn532tool.local/ws`).
+3. Messages look like: `{"channel":"scan","payload":{...}}`