diff --git a/README.md b/README.md
index be4dec7..4a75dfb 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,78 @@
 # JStom
 
-Minestom server with JS scripting support
\ No newline at end of file
+**JStom** is a lightweight Minecraft server implementation built on top of [Minestom](https://minestom.net/), featuring a powerful JavaScript scripting engine powered by GraalVM. It allows you to write server logic, handle events, and interact with the Minestom API directly using JavaScript, with support for runtime hot-reloading.
+
+## Features
+
+- **JavaScript Scripting:** Write your server logic in standard JavaScript (ES6+ support via GraalJS).
+- **Hot Reloading:** modifying scripts does not require a server restart. Use the `reload` command to apply changes instantly.
+- **Isolated Contexts:** Each script file runs in its own isolated context, preventing global variable collisions while still sharing the server API.
+- **Full API Access:** Scripts have access to the full Java classpath, allowing usage of any Minestom class.
+
+## Prerequisites
+
+- **Java 25** (Required by the latest Minestom version).
+
+## Getting Started
+
+### Windows
+1.  Double-click `run.bat` to build and start the server.
+2.  The server will start on port **25565**.
+
+### Linux / Mac
+1.  Grant execution permissions: `chmod +x gradlew`
+2.  Build and run:
+    ```bash
+    ./gradlew installDist
+    ./build/install/jstom/bin/jstom
+    ```
+
+## Usage
+
+### Managing Scripts
+Scripts are located in the `scripts/` directory. You can add as many `.js` files as you like. They are loaded automatically on startup.
+
+**Commands:**
+- `reload`: Unloads and reloads **all** scripts.
+- `reload <filename.js>`: Reloads a specific script file (e.g., `reload index.js`).
+- `stop`: Stops the server.
+
+### Scripting API
+
+The global `server` object is your gateway to the Minestom API.
+
+**Logging:**
+```javascript
+server.log("Hello from JavaScript!");
+```
+
+**Event Handling:**
+You can listen to any Minestom event by its fully qualified class name.
+```javascript
+// Listen for a player joining
+server.on('net.minestom.server.event.player.PlayerSpawnEvent', (event) => {
+    const player = event.getPlayer();
+    player.sendMessage("Welcome to JStom!");
+    server.log(`${player.getUsername()} joined the game.`);
+});
+```
+
+**Accessing Java Classes:**
+Since `allowHostClassLookup` is enabled, you can import and use Java classes directly.
+```javascript
+const Pos = Java.type('net.minestom.server.coordinate.Pos');
+const ItemStack = Java.type('net.minestom.server.item.ItemStack');
+const Material = Java.type('net.minestom.server.item.Material');
+
+// Example: Give an item
+server.on('net.minestom.server.event.player.PlayerSpawnEvent', (event) => {
+    const player = event.getPlayer();
+    player.getInventory().addItemStack(ItemStack.of(Material.DIAMOND));
+});
+```
+
+## Project Structure
+
+- `src/main/java/net/jstom/`: Java source code (Server initialization, ScriptManager).
+- `scripts/`: Directory for user JavaScript files.
+- `build.gradle.kts`: Project dependencies and build configuration.