diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9710171
--- /dev/null
+++ b/README.md
@@ -0,0 +1,146 @@
+# Kode Dot FTP Explorer
+
+A wireless FTP file server running on the [Kode Dot](https://docs.kode.diy) (ESP32-S3). Serves the microSD card over Wi-Fi with a real-time AMOLED status display, battery monitoring, and persistent timekeeping.
+
+## Features
+
+- **FTP Server** — Access the SD card from any FTP client (FileZilla, WinSCP, etc.)
+- **Wi-Fi from SD** — Reads network credentials from `/Wi-Fi.json` on the SD card
+- **AMOLED UI** — 410×502 LVGL 9.5 interface with live status, storage bar, clock
+- **Battery** — Real-time charge percentage + charging indicator (BQ27220 + BQ25896)
+- **Persistent Clock** — NTP sync → external RTC (MAX31329), survives power cycles
+- **Status LED** — NeoPixel: green (idle), blue (connected), purple (transferring), red (error)
+
+## Hardware
+
+| Component | Details |
+|-----------|---------|
+| MCU | ESP32-S3, 240 MHz, 32 MB flash |
+| Display | 410×502 AMOLED (QSPI, CO5300) |
+| Storage | microSD via SD_MMC 1-bit |
+| Battery | BQ27220 fuel gauge, BQ25896 PMIC |
+| RTC | MAX31329 external clock |
+| IO Expander | TCA9555 (buttons, SD detect) |
+| LED | WS2812B NeoPixel on GPIO 4 |
+
+## Quick Start
+
+### 1. Prepare the SD card
+
+Create a `Wi-Fi.json` file in the root of your microSD card:
+
+```json
+[
+  { "ssid": "YourNetwork", "pass": "YourPassword" },
+  { "ssid": "Fallback Network", "pass": "BackupPass" }
+]
+```
+
+The device tries each network in order (20s timeout per attempt).
+
+### 2. Build & Flash
+
+```bash
+# Build
+pio run
+
+# Flash (preserves KodeOS bootloader)
+pio run -t upload
+
+# Serial monitor
+pio device monitor
+```
+
+### 3. Connect via FTP
+
+| Setting | Value |
+|---------|-------|
+| Host | IP shown on display |
+| Port | 21 |
+| User | `kode` |
+| Pass | `kode` |
+
+> **FileZilla tip**: Go to Site Manager → Transfer Settings → check "Limit number of simultaneous connections" and set to **1**. SimpleFTPServer handles one client at a time.
+
+## UI Layout
+
+```
+┌─────────────────────────────────────┐
+│         FTP Explorer          96% █ │ Header + battery
+│─────────────────────────────────────│
+│ 📶 Lago Sommer IoT                  │ Wi-Fi SSID
+│ 192.168.178.102                     │ IP address
+│                                     │
+│ ┌─────────────────────────────────┐ │
+│ │  FTP Server                     │ │
+│ │  ● Idle                         │ │ FTP panel
+│ │  ftp://192.168.178.102          │ │
+│ │  User: kode   Pass: kode       │ │
+│ └─────────────────────────────────┘ │
+│                                     │
+│ Storage                             │
+│ [██████░░░░]  61 MB / 7.3 GB   1%  │ Storage bar
+│                                     │
+│          14:32:45                   │ Clock
+│       Fri, 03 Apr 2026             │
+└─────────────────────────────────────┘
+```
+
+## LED Status
+
+| Color | Meaning |
+|-------|---------|
+| 🟢 Green | Wi-Fi connected, FTP idle |
+| 🔵 Blue | FTP client connected |
+| 🟣 Purple | File transfer in progress |
+| 🔴 Red | Error (no SD, no Wi-Fi) |
+
+## I2C Peripherals
+
+| Device | Address | Function |
+|--------|---------|----------|
+| TCA9555 | 0x20 | IO expander (buttons, SD detect) |
+| BQ27220 | 0x55 | Battery fuel gauge |
+| BQ25896 | 0x6B | PMIC / charger |
+| MAX31329 | 0xD0 | External RTC |
+
+## Key Pin Assignments
+
+| GPIO | Function |
+|------|----------|
+| 4 | NeoPixel LED |
+| 5, 6, 7 | SD_MMC (CMD, CLK, D0) |
+| 47, 48 | I2C (SCL, SDA) |
+| 8–10, 14–17 | QSPI display |
+
+## Dependencies
+
+- [LVGL 9](https://github.com/lvgl/lvgl) — UI framework
+- [SimpleFTPServer](https://github.com/xreef/SimpleFTPServer) — FTP daemon
+- [ArduinoJson 7](https://github.com/bblanchon/ArduinoJson) — Wi-Fi.json parsing
+- [GFX Library for Arduino](https://github.com/moononournation/Arduino_GFX) — Display driver
+- [Adafruit NeoPixel](https://github.com/adafruit/Adafruit_NeoPixel) — Status LED
+- [TCA9555](https://github.com/RobTillaart/TCA9555) — IO expander
+- [PMIC_BQ25896](https://github.com/sqmsmu/PMIC_BQ25896) — Charger
+- [kode_BQ27220](https://github.com/kodediy/kode_BQ27220) — Fuel gauge
+- [kode_MAX31329](https://github.com/kodediy/kode_MAX31329) — External RTC
+
+## Project Structure
+
+```
+├── platformio.ini          Build config, libraries, upload command
+├── partitions_app.csv      Flash partition layout
+├── Wi-Fi.json              Example Wi-Fi credentials
+├── boards/
+│   └── kode_dot.json       Custom board definition
+├── src/
+│   ├── main.cpp            Firmware (Wi-Fi, FTP, NTP, battery, SD)
+│   ├── ui.h / ui.cpp       LVGL 9 display interface
+│   └── lv_conf.h           LVGL configuration
+├── lib/kodedot_bsp/        Board support (display driver, pin config)
+└── extra_scripts/          Build helpers (auto port, rename, framework libs)
+```
+
+## License
+
+MIT