diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c13df66
--- /dev/null
+++ b/README.md
@@ -0,0 +1,111 @@
+# ofox-build
+
+Simple bash script to auto-build [OrangeFox Recovery](https://orangefox.download/) for any device.
+No more typing the same sync/lunch/mka commands every time — everything lives in a json config, one file per device.
+
+## Requirements
+
+- Linux (Ubuntu 20.04+ recommended, or any distro that can build AOSP)
+- Standard AOSP build dependencies + `repo` tool
+- `jq` and `git`
+
+```bash
+sudo apt install jq git
+```
+
+For the full AOSP deps, check the [OrangeFox wiki](https://wiki.orangefox.tech/en/dev/building).
+
+## Setup
+
+1. Clone/download this repo
+2. Create a json config for your device (see below), e.g. `vayu.json`
+3. Run it:
+
+```bash
+chmod +x ofox-build.sh
+./ofox-build.sh vayu.json
+```
+
+If you only have one `.json` in the dir, you can just run `./ofox-build.sh` and it will pick it up.
+
+## Usage
+
+```
+./ofox-build.sh [config.json]     full run: sync + clone tree + build
+./ofox-build.sh -s [config.json]  sync fox sources only
+./ofox-build.sh -c [config.json]  clone/update device tree only
+./ofox-build.sh -b [config.json]  build only
+./ofox-build.sh -h                help
+```
+
+First run takes a long time (syncing sources is ~40GB+). After that, `-b` alone is usually enough.
+
+## Config format
+
+One json per device, named whatever you want (`<codename>.json` is a good habit):
+
+```json
+{
+  "fox": {
+    "branch": "12.1",
+    "sync_dir": "~/OrangeFox_sync",
+    "build_dir": "~/fox_12.1"
+  },
+  "device": {
+    "codename": "vayu",
+    "vendor": "xiaomi",
+    "tree_repo": "https://github.com/example/android_device_xiaomi_vayu.git",
+    "tree_branch": "fox_12.1",
+    "recovery_image": "vendor_boot"
+  },
+  "build": {
+    "target": "recoveryimage",
+    "jobs": 0,
+    "ccache": true,
+    "ccache_size": "50G",
+    "clean_before_build": false
+  },
+  "env": {
+    "ALLOW_MISSING_DEPENDENCIES": "true",
+    "FOX_USE_BASH_SHELL": "1",
+    "FOX_ASH_IS_BASH": "1",
+    "FOX_USE_NANO_EDITOR": "1",
+    "OF_MAINTAINER": "your_name"
+  }
+}
+```
+
+### Fields
+
+| key | what it does |
+|-----|--------------|
+| `fox.branch` | OrangeFox source branch (`12.1`, `11.0`, ...) |
+| `fox.sync_dir` | where the fox `sync` scripts get cloned |
+| `fox.build_dir` | where the actual sources + build happen |
+| `device.codename` | your device codename, used for `lunch twrp_<codename>-eng` |
+| `device.vendor` | vendor name, tree goes to `device/<vendor>/<codename>` |
+| `device.tree_repo` | git url of your device tree |
+| `device.tree_branch` | branch of the tree (default: `main`) |
+| `build.target` | `recoveryimage`, `bootimage` or `vendorbootimage` depending on your device |
+| `build.jobs` | build threads, `0` = all cores |
+| `build.ccache` | use ccache (recommended, big speedup on rebuilds) |
+| `build.clean_before_build` | run `make clean` first |
+| `env` | any extra vars exported before building — put your `OF_*` / `FOX_*` flags here |
+
+## Output
+
+After a successful build, images/zips land in:
+
+```
+<build_dir>/out/target/product/<codename>/
+```
+
+## Notes
+
+- The script tries `lunch twrp_<codename>-eng` first, then falls back to `omni_<codename>-eng` for older trees. If both fail, check your tree's makefile name.
+- If your device boots recovery from `vendor_boot` (most newer devices), set `build.target` to `vendorbootimage`.
+- Multiple devices? Just keep multiple configs: `vayu.json`, `alioth.json`, ... and pass the one you want.
+
+## License
+
+MIT
\ No newline at end of file