diff --git a/README.md b/README.md
index 431de9b..32c2e49 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,270 @@
-<p align="center">
-    <img src="./images/CM-Deck_Logo.svg" width="400" >
-</p>
+<div align="center">
 
-Watch the build video ↓
+<img src="images/CM-Deck_Logo.svg" alt="CM-Deck Logo" width="400"/>
 
-[<img src="./images/CM-Deck_Thumbnail.jpg">](https://youtu.be/U5GZeMm5nhI)
+<br/>
 
-CM Deck is a clamshell style cyberdeck built around the Raspberry Pi Compute Module 5. It has a custom carrier board and a low profile mechanical keyboard.
+[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-gold.svg?style=for-the-badge)](http://creativecommons.org/licenses/by-nc-sa/4.0/)
+[![GitHub Stars](https://img.shields.io/github/stars/sb-ocr/cmdeck?style=for-the-badge&color=blue&logo=github)](https://github.com/sb-ocr/cmdeck/stargazers)
+[![GitHub Forks](https://img.shields.io/github/forks/sb-ocr/cmdeck?style=for-the-badge&color=blue&logo=github)](https://github.com/sb-ocr/cmdeck/forks)
+[![GitHub Issues](https://img.shields.io/github/issues/sb-ocr/cmdeck?style=for-the-badge&color=green&logo=github)](https://github.com/sb-ocr/cmdeck/issues)
+[![YouTube](https://img.shields.io/badge/Watch-Build%20Video-red?style=for-the-badge&logo=youtube)](https://youtu.be/U5GZeMm5nhI)
 
-<sub>⚠️ The PCBs will be updated to fix three issues: 1. The flash chip CS pin isn’t connected (see video at [11:09](https://youtu.be/U5GZeMm5nhI?si=vS6aNDHk9gTeop53&t=669)) | 2. Add jumper pads for the power button so I can solder wires and connect it to the power board (see video at [16:32](https://youtu.be/U5GZeMm5nhI?si=_Pz7x-TjfpxkA6fn&t=992)) | 3. Add an open jumper pad on the 3V3 line of the DSI connector on the main board (see video at [15:09](https://youtu.be/U5GZeMm5nhI?si=e3sX7tEprCDsY_S7&t=909))</sub>
+**A clamshell-style cyberdeck built around the Raspberry Pi Compute Module 5.**  
+Custom carrier board · Low-profile mechanical keyboard · Trackpad · OLED display
 
+</div>
 
-[![CC BY-NC-SA 4.0][cc-by-nc-sa-shield]][cc-by-nc-sa]
+---
 
-[![CC BY-NC-SA 4.0][cc-by-nc-sa-image]][cc-by-nc-sa]
+## 📺 Build Video
 
-[cc-by-nc-sa]: http://creativecommons.org/licenses/by-nc-sa/4.0/
-[cc-by-nc-sa-image]: https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png
-[cc-by-nc-sa-shield]: https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg
\ No newline at end of file
+[![CM-Deck Build Video](images/CM-Deck_Thumbnail.jpg)](https://www.youtube.com/watch?v=U5GZeMm5nhI)
+
+> Watch the full build — from PCB design and 3D-printed prototypes to soldering, debugging, and final assembly.
+
+---
+
+## ✨ Overview
+
+CM Deck is a fully custom, handheld cyberdeck built from scratch. It features:
+
+- 🧠 **Raspberry Pi Compute Module 5** as the brain
+- 🔌 **Custom carrier board** with USB, display, and power circuitry
+- ⌨️ **Low-profile mechanical keyboard** with integrated trackpad
+- 🖥️ **Small OLED status display**
+- 🖨️ **3D-printed clamshell enclosure**
+- 🔋 Battery-powered and portable
+
+---
+
+## ⚠️ Known PCB Issues (Fix in Progress)
+
+The current PCB revision has three known issues that will be corrected in the next update:
+
+| # | Issue | Timestamp |
+|---|-------|-----------|
+| 1 | Flash chip CS pin not connected | [11:09](https://youtu.be/U5GZeMm5nhI?t=669) |
+| 2 | Power button needs jumper pads for wire connection | [16:32](https://youtu.be/U5GZeMm5nhI?t=992) |
+| 3 | Missing open jumper pad on 3V3 line of DSI connector | [15:09](https://youtu.be/U5GZeMm5nhI?t=909) |
+
+<!-- > Updated PCB files will be pushed to this repo once revised. -->
+
+---
+
+## 📁 Repository Structure
+
+```
+cmdeck/
+├── boms/                        # Bills of materials (CSV/spreadsheet)
+│   ├── bom_mainboard.csv        # Components for the CM5 carrier board
+│   └── bom_keyboard.csv         # Components for the keyboard PCB
+│
+├── enclosure/
+│   └── exports/
+│       └── STL/                 # 3D-printable enclosure parts
+│           ├── top_shell.stl    # Upper clamshell half (display side)
+│           ├── bottom_shell.stl # Lower clamshell half (keyboard side)
+│           ├── hinge_*.stl      # Hinge mechanism parts
+│           └── misc/            # Brackets, standoffs, and other hardware mounts
+│
+├── firmware/
+│   └── qmk/                     # QMK keyboard firmware source
+│       ├── config.h             # Pin assignments and hardware config
+│       ├── keymap/
+│       │   └── keymap.c         # Key layout definition
+│       └── rules.mk             # Build rules and MCU target
+│
+├── images/                      # Project photos and assets
+│   ├── CM-Deck_Logo.svg         # Project logo (vector)
+│   └── CM-Deck_Thumbnail.jpg    # YouTube build video thumbnail
+│
+├── pcbs/                        # KiCad PCB design files
+│   ├── mainboard/               # CM5 carrier board
+│   │   ├── mainboard.kicad_pcb  # PCB layout
+│   │   ├── mainboard.kicad_sch  # Schematic
+│   │   └── gerbers/             # Fabrication-ready Gerber files
+│   └── keyboard/                # Keyboard controller PCB
+│       ├── keyboard.kicad_pcb
+│       ├── keyboard.kicad_sch
+│       └── gerbers/
+│
+├── .gitignore
+├── LICENSE
+└── README.md
+```
+
+> **Note:** File names above are illustrative — actual names may vary slightly. Browse the folders directly for the exact contents.
+
+---
+
+## 🖨️ Enclosure — `enclosure/exports/STL/`
+
+The enclosure is a clamshell design modelled in Autodesk Fusion 360 and exported as STL files for 3D printing. The design went through multiple prototype iterations before the final version — see the [build video at 07:40](https://youtu.be/U5GZeMm5nhI?t=460) for the full journey.
+
+**Recommended print settings:**
+
+| Setting | Value |
+|---------|-------|
+| Material | PLA or PETG |
+| Layer height | 0.2 mm |
+| Infill | 20–30% |
+| Supports | Required for hinge areas and display cutouts |
+| Perimeters | 3+ walls for structural parts |
+
+**Parts overview:**
+
+| File | Description |
+|------|-------------|
+| `top_shell.stl` | Upper half of the clamshell — holds the display |
+| `bottom_shell.stl` | Lower half — houses the keyboard and mainboard |
+| `hinge_*.stl` | Hinge mechanism components |
+| `misc/` | Standoffs, brackets, and any auxiliary mounting hardware |
+
+---
+
+## ⌨️ Keyboard Firmware — `firmware/qmk/`
+
+The keyboard runs [QMK firmware](https://qmk.fm/), an open-source keyboard firmware framework. The source in this folder defines the key matrix, pin assignments, and keymap for the CM Deck's built-in keyboard controller.
+
+**Key files:**
+
+| File | Purpose |
+|------|---------|
+| `config.h` | Matrix pin assignments, USB descriptor, debounce settings |
+| `keymap/keymap.c` | Layer definitions and key bindings |
+| `rules.mk` | Target MCU and enabled QMK features |
+
+### Prerequisites
+
+```bash
+# Install QMK CLI
+pip install qmk
+
+# Set up QMK environment (first time only)
+qmk setup
+```
+
+### Building
+
+```bash
+# Copy the firmware folder into your QMK keyboards directory
+cp -r firmware/qmk ~/qmk_firmware/keyboards/cmdeck
+
+# Compile
+qmk compile -kb cmdeck -km default
+```
+
+### Flashing
+
+```bash
+# Flash via QMK CLI (put the keyboard into bootloader mode first)
+qmk flash -kb cmdeck -km default
+```
+
+To enter bootloader mode, short the `BOOT` and `GND` pins on the keyboard PCB while plugging in USB — or press the physical reset button if one is populated on your board.
+
+Alternatively, use [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (Windows/macOS) for a GUI-based flashing experience with no terminal required.
+
+---
+
+## 🔌 PCBs — `pcbs/`
+
+The project uses two custom PCBs, both designed in [KiCad](https://www.kicad.org/). Each board folder contains the schematic, PCB layout, and fabrication-ready Gerber files.
+
+### Mainboard (CM5 Carrier Board)
+
+The carrier board plugs into the Raspberry Pi Compute Module 5 via its high-density board-to-board connectors and breaks out:
+
+- USB-A host ports
+- DSI display connector
+- Power management and battery charging circuitry
+- I²C bus for the OLED status display
+- USB connection to the keyboard controller MCU
+
+See the [build video at 01:55](https://youtu.be/U5GZeMm5nhI?t=115) for a walkthrough of the schematic and layout decisions, and [09:40](https://youtu.be/U5GZeMm5nhI?t=580) for the bring-up and debugging process.
+
+### Keyboard PCB
+
+A compact PCB for the low-profile mechanical key switch matrix, including:
+
+- Low-profile key switch footprints (Choc-style)
+- Trackpad flex connector
+- Microcontroller running QMK firmware
+- USB connector for host communication
+
+**Ordering PCBs:**
+
+Gerber files in each board's `gerbers/` subfolder can be uploaded directly to any PCB manufacturer. This project was fabricated through [PCBWay](https://pcbway.com/g/TC4KGU).
+
+> ⚠️ Review the [known issues](#️-known-pcb-issues-fix-in-progress) before placing an order on the current revision.
+
+---
+
+## 📋 Bill of Materials — `boms/`
+
+The `boms/` folder contains CSV files listing every component needed to build the boards. Open them in any spreadsheet app (Excel, LibreOffice Calc, Google Sheets) or import into a sourcing tool like [Octopart](https://octopart.com/) or [Mouser BOM Manager](https://www.mouser.com/).
+
+**Columns included:**
+
+| Column | Description |
+|--------|-------------|
+| Reference | PCB reference designator (e.g. `R1`, `C4`, `U2`) |
+| Value | Component value or part name |
+| Footprint | PCB footprint identifier |
+| Quantity | Number of units needed |
+| Supplier / MPN | Suggested source or manufacturer part number |
+
+---
+
+## 🗂️ Build Timeline
+
+| Phase | Timestamp | Description |
+|-------|-----------|-------------|
+| Project Goals | [00:20](https://youtu.be/U5GZeMm5nhI?t=20) | Design goals and feature set |
+| PCB Design | [01:55](https://youtu.be/U5GZeMm5nhI?t=115) | Schematic and layout in KiCad |
+| Prototyping | [07:40](https://youtu.be/U5GZeMm5nhI?t=460) | 3D-printed enclosure iterations |
+| Electronics | [09:40](https://youtu.be/U5GZeMm5nhI?t=580) | Soldering and PCB bring-up |
+| Integration | [13:45](https://youtu.be/U5GZeMm5nhI?t=825) | Fitting everything together |
+| Assembly | [18:55](https://youtu.be/U5GZeMm5nhI?t=1135) | Final mechanical assembly |
+| Usage & Features | [23:10](https://youtu.be/U5GZeMm5nhI?t=1390) | Demo and full walkthrough |
+
+---
+
+## 🛠️ Tools Used
+
+| Tool | Purpose |
+|------|---------|
+| [KiCad](https://www.kicad.org/) | PCB schematic and layout |
+| [Autodesk Fusion 360](https://bit.ly/49dQyQN) | Enclosure CAD design |
+| [QMK Firmware](https://qmk.fm/) | Keyboard firmware |
+| [Bambu Lab 3D Printers](https://bit.ly/4gwNFhK) | Enclosure prototyping and final prints |
+| [PCBWay](https://pcbway.com/g/TC4KGU) | PCB fabrication |
+
+---
+
+## 📜 License
+
+This project is licensed under **[CC BY-NC-SA 4.0](http://creativecommons.org/licenses/by-nc-sa/4.0/)**.
+
+[![CC BY-NC-SA 4.0](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png)](http://creativecommons.org/licenses/by-nc-sa/4.0/)
+
+You are free to share and adapt this work for **non-commercial purposes**, as long as you give appropriate credit and distribute under the same license.
+
+---
+
+## 🙏 Credits & Acknowledgements
+
+- PCB design guidance — [@PhilsLab](https://www.youtube.com/@PhilsLab)
+- PCB manufacturing — [PCBWay](https://pcbway.com/g/TC4KGU)
+- Keyboard firmware — [QMK](https://qmk.fm/)
+
+---
+
+<div align="center">
+
+Soldered by hand. Powered by coffee. Built by [Salim Benbouziyane](https://linktr.ee/salimbenbouz).
+
+⭐ Star this repo if you found it useful!
+
+</div>
\ No newline at end of file