diff --git a/README.md b/README.md
index 6ec8c6c..e66c936 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,130 @@
-![](https://img.shields.io/github/downloads/EZ-Robotics/EZ-Template/total.svg)
-![](https://github.com/EZ-Robotics/EZ-Template/workflows/Build/badge.svg)
-[![License: MPL 2.0](https://img.shields.io/badge/License-MPL%202.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)
+# 11254Y Robot Code
+
+This repository contains the software for my VEX V5 competition robot. The project is written in C++ using **PROS** and is built on the **uncompiled/source version of EZ-Template**.
+
+The goal of this project is to provide a modular structure for controlling the robot's drivetrain and mechanisms while keeping individual mechanisms easy to reuse and modify.
+
+## Technologies
+
+* **C++**
+* **PROS**
+* **EZ-Template** — source/uncompiled version
+* **VEX V5**
+
+## Project Structure
+
+The project is organized similarly to the structure used by EZ-Template. Mechanism systems are separated into their own header and source files so they can be developed and reused independently.
+
+### EZ-Template
+
+EZ-Template provides the foundation for the robot code, including systems such as:
+
+* Drivetrain control
+* Autonomous routines
+* Autonomous selector
+* PID control
+* General robot utilities
+
+The source version of EZ-Template is included directly in the project rather than using it only as a precompiled library. This allows the template's code to be modified and extended as needed.
+
+## Custom Systems
+
+I have added several custom mechanism-control systems following the same general structure and organization used by EZ-Template.
+
+### Color Sorter
+
+The color sorter controls the robot's ring-sorting mechanism.
+
+It is designed to handle the logic required to detect and sort rings based on their color while integrating with the rest of the robot's control system.
+
+### Pneumatic Control
+
+The pneumatic control system provides an organized way to control the robot's pneumatic mechanisms.
+
+Instead of handling individual pneumatic outputs throughout the main robot code, pneumatic mechanisms can be controlled through their own class and functions.
+
+### Rotation Mechanisms
+
+The rotation-control system is designed for mechanisms that use a VEX V5 Rotation Sensor to determine their position.
+
+Mechanisms can define multiple preset positions and cycle between those positions. The system also provides control functions for moving and maintaining the mechanism at its desired position.
+
+For example, a mechanism can have states such as:
+
+```text
+State 0 → 0°
+State 1 → 26.5°
+State 2 → 45°
+```
+
+The mechanism can then cycle between these states without requiring the state-management code to be rewritten for every mechanism.
+
+## Design Philosophy
+
+One of the main goals of this project is **modularity**.
+
+Rather than putting all robot functionality into `main.cpp`, individual systems are implemented as classes with their own `.hpp` and `.cpp` files.
+
+A typical mechanism is structured like this:
+
+```text
+include/
+└── EZ-Template/
+    └── ...
+    
+src/
+└── EZ-Template/
+    ├── ...
+    └── rotation_mechanisms/
+        ├── arm_mech.cpp
+        └── ...
+```
+
+The header files contain the class declarations, while the `.cpp` files contain the implementation.
+
+This allows mechanisms to be instantiated and controlled from the main robot program without putting their implementation directly into `main.cpp`.
+
+## Using a Mechanism
+
+A mechanism can be created as an object and then controlled through its member functions.
+
+For example:
+
+```cpp
+ArmMech arm_control;
+```
+
+Once the object exists, its functions can be called from the robot code:
+
+```cpp
+arm_control.cycle_states();
+arm_control.reset_state();
+arm_control.arm_control();
+```
+
+This keeps the main robot code focused on **what the robot should do** instead of how each individual mechanism works internally.
+
+## Development
+
+This project is actively developed for VEX Robotics competition use. The code may change as the robot's mechanical design, autonomous routines, and control systems are improved.
+
+Because the project uses the source version of EZ-Template, changes can be made directly to the template and custom systems can be integrated alongside it.
+
+## Credits
+
+### PROS
+
+This project uses PROS as the development environment and operating system for the VEX V5 brain.
+
+### EZ-Template
+
+EZ-Template is used as the foundation for the drivetrain and competition-code structure. Custom systems in this project are implemented using a similar organization and design approach.
+
+## License
+
+This project is intended for personal and educational use. If you reuse portions of this code, please give appropriate credit to the original authors of EZ-Template and PROS where applicable.
+
+
 
 ⚡️ **coding made ez** ⚡️