diff --git a/README.md b/README.md
index b421122..d7d4b8d 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,199 @@
+![screenshot1.png](screenshot1.png)
 
-Installation information
-=======
+# Trade
 
-This template repository can be directly cloned to get you started with a new
-mod. Simply create a new repository cloned from this one, by following the
-instructions provided by [GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template).
+`Trade` is a NeoForge mod for Minecraft `1.21.1` that adds a secure player-to-player trading interface inspired by Runescape.
 
-Once you have your clone, simply open the repository in the IDE of your choice. The usual recommendation for an IDE is either IntelliJ IDEA or Eclipse.
+Players can request a trade, review both offers in a shared GUI, accept once to lock the offer, and confirm a second time to complete the exchange.
 
-If at any point you are missing libraries in your IDE, or you've run into problems you can
-run `gradlew --refresh-dependencies` to refresh the local cache. `gradlew clean` to reset everything 
-{this does not affect your code} and then start the process again.
+## Features
 
-Mapping Names:
-============
-By default, the MDK is configured to use the official mapping names from Mojang for methods and fields 
-in the Minecraft codebase. These names are covered by a specific license. All modders should be aware of this
-license. For the latest license text, refer to the mapping file itself, or the reference copy here:
-https://github.com/NeoForged/NeoForm/blob/main/Mojang.md
+- Player-to-player trade requests with an accept / decline handshake
+- Shared trade screen with separate offer areas for both players
+- Two-step confirmation flow
+- Quantity-based item selection with quick amounts and `Trade X`
+- Inventory-safe finalization: nothing changes until safety and security checks pass and the trade succeeds
+- Configurable trade safety checks to prevent dangerous mid-combat or mid-movement trading
+- Per-player trade toggles and ignore list support
+- File-based trade audit log for server operators
 
-Additional Resources: 
-==========
-Community Documentation: https://docs.neoforged.net/  
-NeoForged Discord: https://discord.neoforged.net/
+## Player Usage
+
+### Starting a trade
+
+Primary flow:
+
+- Use the trade keybind (default: `G`) while looking at another player
+
+Command option:
+
+```mcfunction
+/trade <player>
+```
+
+When a request is sent, the target player receives chat text with a clickable accept link.
+
+They can also respond manually:
+
+```mcfunction
+/trade yes
+/trade no
+```
+
+### In the trade screen
+
+- Click an item in your inventory to trade `1`
+- Right-click an item to open the quantity menu
+- Use `Trade X` to enter a custom amount
+- Click `Accept` when your offer is ready
+- Once both players accept, the screen enters the confirmation stage
+- Click `Confirm` to finalize
+
+## Commands
+
+### Player commands
+
+```mcfunction
+/trade <player>
+/trade yes
+/trade no
+/trade toggle
+/trade on
+/trade off
+/trade ignore <player>
+/trade unignore <player>
+/trade ignorelist
+```
+
+### Command behavior
+
+- `/trade <player>` sends a trade request
+- `/trade yes` accepts the current pending trade request
+- `/trade no` declines the current pending trade request
+- `/trade toggle` flips whether you accept incoming trade requests
+- `/trade on` enables incoming trade requests
+- `/trade off` disables incoming trade requests
+- `/trade ignore <player>` blocks trade requests from that online player
+- `/trade unignore <player>` removes that online player from your ignore list
+- `/trade ignorelist` shows your ignored players
+
+## Trade Safety
+
+By default, the mod blocks trade requests or acceptance unless both players are in a safe state.
+
+Default safeguards:
+
+- on solid ground
+- standing still
+- not recently damaged
+- not on fire
+- not in liquid
+- not sleeping
+- not gliding
+- not mounted
+- in the same dimension
+
+There is also a special delayed-accept flow for the most common transient failure:
+
+- if the other player accepts while you are only moving or in the air, the request does not fail immediately
+- instead, you get an on-screen countdown
+- if you get safe in time and remain still long enough, the trade opens automatically
+
+## Final Validation
+
+When both players confirm, the trade is checked one last time before any real inventory is changed.
+
+The trade verifies:
+
+- both players are still in the same dimension, if that config is enabled
+- both players are still within configured trade distance, if enabled
+- both live inventories still match the snapshots taken when the trade started
+- both players can receive the incoming items
+
+If any check fails, the trade is cancelled and both players receive an explicit chat message explaining why.
+
+## Configuration
+
+Server config values live under the `trade` section.
+
+### Request / range
+
+- `tradeCommandProximity`
+  - default: `0`
+  - `0` disables range checks
+  - `1+` requires players to be within that many blocks to request, accept, and finalize a trade
+
+- `requestTimeoutSeconds`
+  - default: `30`
+  - number of seconds before a pending trade request expires
+
+### Debug
+
+- `enableDebugFeatures`
+  - default: `false`
+  - enables debug commands and debug UI/testing tools
+
+### Safety
+
+- `requireOnGround`
+  - default: `true`
+
+- `requireStationary`
+  - default: `true`
+
+- `stationarySpeedThreshold`
+  - default: `0.03`
+
+- `requireNoRecentDamage`
+  - default: `true`
+
+- `noDamageSeconds`
+  - default: `10`
+
+- `requireNotOnFire`
+  - default: `true`
+
+- `requireNotInLiquid`
+  - default: `true`
+
+- `requireNotSleeping`
+  - default: `true`
+
+- `requireNotFallFlying`
+  - default: `true`
+
+- `requireNotRiding`
+  - default: `true`
+
+- `requireSameDimension`
+  - default: `true`
+
+## Audit Log
+
+The mod writes a trade audit log to:
+
+```text
+logs/trade.log
+```
+
+Entries include:
+
+- trade requests
+- request accepts / declines / expirations
+- trade opens
+- trade cancels
+- trade completions
+- player names
+- UUIDs
+- dimensions
+- block coordinates
+- items offered by each side
+- final result text
+
+## Debug Mode
+
+Debug tools are disabled by default and only available when:
+
+- `enableDebugFeatures = true`
+
+When enabled, the mod exposes `/trade debug ...` commands and on-screen debug controls for single-client testing.
\ No newline at end of file
diff --git a/screenshot1.png b/screenshot1.png
new file mode 100644
index 0000000..297663d
Binary files /dev/null and b/screenshot1.png differ