diff --git a/README.md b/README.md
index 07c74b8..4bb54fc 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,191 @@
-
- 
+
+
Lootinator
- 
- 
+ 
+
+ 
+ 
-GPU accelerated Minecraft loot finding
+ GPU accelerated Minecraft loot finding
## About
-Lootinator on its own is not a program for finding loot, Lootinator's job is to generate an optimized self-contained CUDA kernel(s) which can either be executed directly or elsewhere. Currently all interactions are done through the API, but the end goal is to support a wide range of frontends, native applications, discord bots, even web interfaces.
+Lootinator finds _loot seeds_ - the internal seeds Minecraft uses to determine chest loot.
+
+Lootinator does not find loot seeds directly, instead it generates optimized CUDA kernels that can be compiled and run on any NVIDIA graphics card from 2012 onwards.
+
+## Prerequisites
+
+- **NVIDIA GPU** - required to run the generated kernel.
+- **NVIDIA CUDA Toolkit** - provides `nvcc` for compiling the kernel. Download from .
+- **To build from source:** CMake 3.11+, a C++11 compiler (MSVC/Visual Studio on Windows, GCC/Clang on Linux), and Git.
+
+> Pre-built binaries for Windows and Linux are on the [releases page](https://github.com/MinecraftAtHome/Lootinator/releases) - no compiler needed.
+
+## Getting Started
+
+### 1. Download or build the binary
+
+#### Option A
+
+Download a pre-built Windows or Linux `lootinator-cli` binary from the [releases page](https://github.com/MinecraftAtHome/Lootinator/releases).
+
+#### Option B
+
+Clone the repository to build the `lootinator-cli` binary from source.
+
+```bash
+git clone --recurse-submodules https://github.com/MinecraftAtHome/Lootinator.git
+cd Lootinator
+```
+
+### 2. Prepare your inputs
+
+You need two JSON files:
+
+- **Loot table** for the chest type you are targeting - all versions available at .
+- **Constraint file** describing the items you want in the chest - schema described [below](#constraint-file-schema).
+
+### 3. Generate the CUDA kernel
+
+```bash
+./lootinator-cli --loot-table --constraint-file -o [-sc] [-sk] [-v ]
+```
+
+This produces a `.cu` source file.
+
+### 4. Compile the kernel
+
+```bash
+nvcc output.cu -o loot_finder
+```
+
+### 5. Run
+
+```bash
+./loot_finder
+```
+
+A full example of the CLI can be found [below](#usage-example).
+
+## CLI Reference
+
+### Flags
+
+| Flag | Description |
+| ------------------------ | ------------------------------------------------------------------------------------------- |
+| `-sc`, `--seedcracking` | Only accept the **exact** chest contents specified in the constraint file (no extra items). |
+| `-sk`, `--single-kernel` | Generate the predicted best kernel instead of benchmarking all possible kernels. |
+| `-v`, `--version` | Target Minecraft version, e.g. `1.16` or `latest`. |
+| `--list-versions` | List all supported Minecraft versions. |
+
+### Constraint file schema
+
+```json
+[
+ {
+ "item": "",
+ "range": {
+ "min": "",
+ "max": ""
+ },
+ "slot": "",
+ "attributes": [
+ {
+ "type": "",
+ "level": ""
+ }
+ ]
+ }
+]
+[
+ {
+ // the name of the item you are targetting, must be prefixed with minecraft:
+ "item": "minecraft:",
+
+ // the minimum and maximum item count for this constraint
+ "range": {
+ "min": ,
+ "max": ,
+ },
+
+ // the slot of the item between 0-27 (currently ignored)
+ "slot": ,
+
+ // optional attribute data for enchantments
+ "attributes": [
+ {
+ "type": "", // e.g. efficiency
+ "level": // number between 1-5 (optional)
+ }
+ ]
+ }
+]
+```
+
+## Features
+
+### CLI
+
+- Support for Minecraft 1.13 and above (experimental).
+- Support for any loot table defined as a JSON file (experimental).
+- Two operation modes:
+ - **Seedfinding** (default) - find chests containing at least the specified items.
+ - **Seedcracking** (`-sc`) - find chests with the exact items specified.
+- Built-in automated kernel benchmarking (disable with `-sk`).
+
+### API
+
+- Supports all operations provided by the CLI.
+- See `lootinator/include/lootinator.h` for available functions.
+
+### Coming Soon
+
+- **Web interface** - run Lootinator directly in the browser using WebGPU.
+- **Native GUI** - a native desktop application for Windows and Linux.
+
+## Issues
+
+If you have any issues, please report them at .
+
+You can also join the `#lootinator` channel in the [Minecraft@Home Discord server](https://discord.gg/QmE5zeWVBA).
+
+## Usage Example
+
+Find ruined portal chests containing at least 4 enchanted golden apples in version 26.1.
+
+**Loot table:**
+
+**Constraint file** (`constraints_4_notches.json`):
+
+```json
+[
+ {
+ "item": "minecraft:enchanted_golden_apple",
+ "range": { "min": 4, "max": 10000 },
+ "slot": 0
+ }
+]
+```
+
+**Generate:**
+
+```bash
+./lootinator-cli --loot-table ruined_portal.json --constraint-file constraints_4_notches.json -o four_notches.cu -v 26.1
+```
+
+**Compile:**
+
+```bash
+nvcc four_notches.cu -o four_notches
+```
+
+**Run:**
+
+```bash
+./four_notches
+```
diff --git a/cli/README.md b/cli/README.md
deleted file mode 100644
index 2a86c5a..0000000
--- a/cli/README.md
+++ /dev/null
@@ -1,104 +0,0 @@
-# Lootinator CLI Usage Guide
-
-## About the project
-
-Lootinator lets you find *loot seeds* - a type of internal seed that Minecraft uses to determine chest loot.
-
-Lootinator does not find loot seeds directly, it instead generates cuda kernels which can in turn be compiled and run on any
-NVIDIA graphics card.
-
-## Quick Start
-
-- In order to run the CLI, you will need the json of the loot table you are targetting. These can be found for all versions here: https://mcasset.cloud/latest
-
-- In addition, you will need a constraint file describing all the constraints you are targetting. The json schematic is as follows:
-```
-[
- {
- // the name of the item you are targetting, must be prefixed with minecraft:
- "item": ,
-
- // the minimum and maximum item count for this constraint
- "range": {
- "min": ",
- "max":
- },
-
- // the slot of the item between 0-27 (currently ignored)
- "slot": ,
-
- // optional attribute data for enchantments
- "attributes": [
- {
- "type": , // e.g. efficiency
- "level": // optional
- }
- ]
- }
-]
-```
-
-- With both of these json files, we can call the lootinator-cli
-
-```bash
-./lootinator-cli --loot-table --constraint-file -o [-sc] [-sk] [-v ]
-```
-
-- The options are as follows
-```
--sc, --seedcracking
- if enabled, the kernel will only accept the **exact** chest contents specified in the constraint file
-
--sk, --single-kernel
- generates the predicted best kernel rather than benchmarking all possible kernels
-
--v, --version
- the target minecraft version e.g. 1.16 or latest for the latest supported release
-```
-
-- Once you have run the cli, you will be left with an output cuda (.cu) file
-
-## Usage example
-
-- Target loot table: https://mcasset.cloud/26.1.2/data/minecraft/loot_table/chests/ruined_portal.json
-
-- Constraints file - `constraints_4_notches.json` (looking for at least 4 enchanted golden apples in a ruined portal chest):
-
-```json
-[
- {
- "item": "minecraft:enchanted_golden_apple",
- "range": {
- "min": 4,
- "max": 10000
- },
- "slot": 0
- }
-]
-```
-
-- Use lootinator CLI like this (assuming the constraints and loot table files are in the same directory as the executable):
-```bash
-./lootinator-cli --loot-table ruined_portal.json --constraint-file constraints_4_notches.json -o four_notches.cu -v 26.1
-```
-
-- Compile the CUDA source code file (four_notches.cu). This requires `nvcc` to be available on the host machine.
-```bash
-nvcc four_notches.cu -o four_notches
-```
-
-- Run the compiled code, saving results to the output file `out.txt`. Requires a CUDA-capable GPU.
-```bash
-./four_notches 1> out.txt
-```
-
-## Features
-
-### CLI
-- Support for Minecraft 1.13 and above (experimental).
-- Support for any loot table defined as a json file (experimental).
-- Two modes of operation - *seedcracking* (finding the exact specified chest contents, enable with the `-sc` flag) and *seedfinding* (default, finding a chest with at least the specified items, and potentially others)
-- Built-in automated benchmarking (turn off with the `-sk` flag)
-
-### API
-- supports all the operations provided by the CLI, see `lootinator/include/lootinator.h` for available functions
\ No newline at end of file