diff --git a/README.md b/README.md
new file mode 100644
index 0000000..58e80dd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,97 @@
+# ESPsNAKE
+
+ESPsNAKE is a small handheld Snake console built around an ESP32-C3. It uses a 1.3" I2C OLED, four directional buttons, and a buzzer for sound effects. The firmware also stores settings and per-difficulty leaderboards in non-volatile memory.
+
+## Overview
+
+The project combines three parts:
+
+- `code/`: the Arduino/PlatformIO firmware that runs the game.
+- `pcb/`: the KiCad schematic and PCB for the handheld.
+- `3d/`: the enclosure and mechanical design reference.
+
+The game starts on a title screen, supports multiple difficulty presets, a custom difficulty mode, leaderboard tracking, and name entry for new high scores.
+
+## Features
+
+- Classic Snake gameplay with wall and self-collision.
+- Sound feedback for food pickups and game over events.
+- Sprint mode that activates by holding a direction button long enough.
+- Three preset difficulties: Easy, Medium, and Hard.
+- Custom difficulty with configurable step speed, speedup per food, and min/max limits.
+- Persistent settings and leaderboards stored on the device.
+- Separate leaderboards for Easy, Medium, and Hard.
+
+## Controls
+
+The four buttons are active-low inputs with pull-ups enabled in firmware.
+
+| Button | GPIO | Main use |
+| --- | --- | --- |
+| Up | `GPIO0` | Start game, move up, move through menus |
+| Right | `GPIO1` | Open settings, move right |
+| Down | `GPIO3` | Move down |
+| Left | `GPIO10` | Open leaderboard, move left |
+
+Other controls and behaviors:
+
+- `L+R` together confirm selections during name entry.
+- The leaderboard shortcut is disabled while Custom difficulty is selected.
+- Name entry uses an on-screen 4x7 keyboard with `DEL` and `OK` keys.
+
+## Hardware
+
+Main parts shown in the schematic and PCB:
+
+- `ESP32-C3 SuperMini` module: main controller.
+- `OLED 128x64 I2C` display: game screen.
+- `SW1` to `SW4`: four tactile buttons.
+- `BZ1`: polarized buzzer.
+- `TP4056` charger IC: single-cell Li-ion/LiPo charging from USB-C.
+- `DW01A` + `FS8205A`: battery protection circuit.
+- `D1` and `D2`: charger status LEDs.
+- `J1` and `J3`: headers for serial/control access.
+- `Battery` connector: 2-pin LiPo battery input.
+
+### Pin mapping used by the firmware
+
+- Display I2C clock: `GPIO9`
+- Display I2C data: `GPIO8`
+- Buzzer: `GPIO7`
+- Up: `GPIO0`
+- Right: `GPIO1`
+- Down: `GPIO3`
+- Left: `GPIO10`
+
+## Power and Charging
+
+The board is designed for a single-cell lithium battery.
+
+- USB-C provides power for charging.
+- The charger section uses a `TP4056`-class linear charger.
+- The protection section uses `DW01A` and `FS8205A` for overcharge, overcurrent, and overdischarge protection.
+- The schematic includes charge-status LEDs driven from the charger status pins.
+
+## Software Notes
+
+The firmware is a PlatformIO Arduino project targeting `esp32-c3-devkitm-1`.
+
+- Display library: `U8g2`.
+- Runtime states: start screen, playing, game over, settings, leaderboard, and name entry.
+- Settings saved in `Preferences` include buzzer frequency, difficulty, sprint enable, and custom difficulty values.
+- Leaderboards are stored separately for each preset difficulty and use 8-character names.
+- Sprint scoring awards 2 points per food while sprinting, otherwise 1 point.
+
+## 3D Design
+
+The enclosure/mechanical reference is stored in `3d/readme` and points to the Onshape model:
+
+`https://cad.onshape.com/documents/bb9db5aa964d643ccd7e46c3/w/9284d4a7438acf7663ad1fe7/e/a1c5cd401b084cdfb7fd39db?renderMode=0&uiState=6a0da37ffa326fa20df8f248`
+
+If you extend the enclosure, keep the OLED, buttons, buzzer, USB-C access, and battery connector aligned with the PCB placement.
+
+## Notes
+
+- Custom difficulty does not use the standard leaderboard flow.
+- The game stores board-specific leaderboard data, so changing difficulty changes which board is active.
+- The README is based on the current firmware and PCB files; verify mechanical details directly in Onshape before manufacturing changes.
\ No newline at end of file