diff --git a/README.md b/README.md
new file mode 100644
index 0000000..da8a27c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,152 @@
+# TrackEngine
+
+A C++17 route-matching engine built on [OSRM](https://github.com/Project-OSRM/osrm-backend), consuming GPS CSV streams via stdin and producing matched results.
+
+---
+
+## Prerequisites
+
+| Requirement | Notes |
+|---|---|
+| **Windows 10/11 (x64)** | MSVC toolchain only |
+| **Visual Studio 2019 or 2022** | With the "Desktop development with C++" workload |
+| **OSRM** | Installed to `C:\OSRM\` (headers + libs) |
+| **OSRM backend clone** | At `C:\Users\TRIZ\clones\osrm-backend\` (vcpkg deps + third-party headers) |
+| **nmake** | Ships with Visual Studio — run everything inside a *Developer Command Prompt* |
+
+---
+
+## Repository layout
+
+```
+trackengine/
+├── src/
+│   └── main.cpp
+├── kdtree/
+│   └── kdtree.c
+├── tomlcpp/
+│   ├── tomlcpp.cpp
+│   └── toml.c
+├── data/               ← OSRM map data, config, etc.
+├── bin/                ← created automatically at build time
+├── Makefile
+└── README.md
+```
+
+---
+
+## Building
+
+### 1 — Open a Developer Command Prompt
+
+Start → **"Developer Command Prompt for VS 20xx"**  
+*(or run `vcvars64.bat` inside any terminal to activate the MSVC environment.)*
+
+### 2 — Navigate to the project root
+
+```cmd
+cd C:\Users\TRIZ\clones\tracluster
+```
+
+### 3 — Compile
+
+```cmd
+nmake /f Makefile
+```
+
+This will:
+
+- Compile `src/main.cpp`, `kdtree/kdtree.c`, `tomlcpp/tomlcpp.cpp`, and `tomlcpp/toml.c` with `/std:c++17 /O3 /MD`.
+- Link against `C:\OSRM\lib\osrm.lib`, all vcpkg `.lib` files, and `AdvAPI32.lib`.
+- Output the executable to **`bin\trackengine.exe`**.
+
+### 4 — Run (quick test)
+
+The `all` target automatically pipes a sample CSV through the engine after building:
+
+```cmd
+type C:\Users\TRIZ\clones\tracluster\gps_260205_070000.csv | bin\trackengine.exe
+```
+
+To run it manually at any time:
+
+```cmd
+type path\to\your_gps_file.csv | bin\trackengine.exe
+```
+
+### Cleaning build artefacts
+
+```cmd
+nmake /f Makefile clean
+```
+
+---
+
+## Packaging for deployment
+
+After a successful build, bundle **`bin\`** and **`data\`** together into split 100 MB ZIP archives using 7-Zip:
+
+```cmd
+"C:\Program Files\7-Zip\7z.exe" a -tzip -v100m TrackEngine.zip bin\ data\
+```
+
+This produces a sequence of files such as:
+
+```
+TrackEngine.zip.001
+TrackEngine.zip.002
+TrackEngine.zip.003
+...
+```
+
+> **Tip — 7-Zip not installed?**  
+> Download it from <https://www.7-zip.org/> and add its folder to your `PATH`, or use the full path shown above.
+
+---
+
+## Uploading to cPanel
+
+1. Log in to your cPanel account and open **File Manager**.
+2. Navigate to:
+   ```
+   public_html → files → TrackEngine
+   ```
+3. Upload each `TrackEngine.zip.001`, `TrackEngine.zip.002`, … part — choose **Overwrite** if prompted for existing files.
+4. Once all parts are uploaded, verify the file list matches what was produced locally.
+
+---
+
+## Restarting Tomcat
+
+After uploading, restart the Tomcat server so the web application picks up the new binaries:
+
+- In cPanel look for **Tomcat Manager** (or use the **Application Manager** if your host uses JVM hosting).
+- Click **Stop** → wait a moment → click **Start**.
+- Alternatively, if you have SSH access:
+  ```bash
+  /path/to/tomcat/bin/shutdown.sh && /path/to/tomcat/bin/startup.sh
+  ```
+
+---
+
+## Enabling the TrackEngine integration
+
+Open your web application's configuration file (e.g. `application.properties` or `config.toml`) and confirm the following property is set to `true`:
+
+```properties
+trizdistribution.trackEngine.enabled=true
+```
+
+After saving the file and restarting Tomcat (see above), the web application will automatically detect, download, and activate the newly uploaded TrackEngine binaries.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `cl` not found | Wrong terminal | Use Developer Command Prompt |
+| Linker error on `osrm.lib` | Wrong OSRM install path | Verify `C:\OSRM\lib\osrm.lib` exists |
+| vcpkg `.lib` wildcard fails | nmake doesn't expand `*.lib` | List each `.lib` explicitly in `LIBS` |
+| Engine exits silently | Missing `data/` files | Ensure OSRM `.osrm` processed map files are in `data/` |
+| Web app doesn't start engine | Property not set | Double-check `trizdistribution.trackEngine.enabled=true` |