diff --git a/README.md b/README.md
index 65e3448a..8c58cc6c 100644
--- a/README.md
+++ b/README.md
@@ -2,33 +2,54 @@
 
 # revive
 
-YUL and EVM bytecode recompiler to LLVM, targetting RISC-V on PolkaVM.
+YUL and EVM assembly recompiler to LLVM, targetting RISC-V on [PolkaVM](https://github.com/koute/polkavm).
 
-Code bases of [frontend](https://github.com/matter-labs/era-compiler-solidity) and [code generator](https://github.com/matter-labs/era-compiler-llvm-context) are forked and adapted from ZKSync `zksolc`.
+[Frontend](https://github.com/matter-labs/era-compiler-solidity) and [code generator](https://github.com/matter-labs/era-compiler-llvm-context) are based of ZKSync `zksolc`.
 
-# Status
+## Status
 
-Currently, primary goal of this codebase is to allow for benchmarks comparing performance against ink! and solang artifacts as well as EVM interpreters.
+This is experimental software in active development and not ready just yet for production usage.
 
-# TODO
+Discussion around the development is hosted on the [Polkadot Forum](https://forum.polkadot.network/t/contracts-update-solidity-on-polkavm/6949#a-new-solidity-compiler-1).
 
-The project is in a very early PoC phase. Don't yet expect the produced code to be working nor to be correct for anything more than a basic flipper contract at the current stage.
+## Installation
+
+TL;DR installing the `resolc` Solidity frontend executable:
+
+```bash
+bash build-llvm.sh
+export PATH=${PWD}/llvm18.0/bin:$PATH
+make install-bin
+resolc --version
+```
+
+### LLVM
+
+`revive` requires a build of LLVM 18.1.4 or later including `compiler-rt`. Use the provided [build-llvm.sh](build-llvm.sh) build script to compile a compatible LLVM build locally in `$PWD/llvm18.0` (don't forget to add that to `$PATH` afterwards). 
+
+### Development
+
+Please consult the [Makefile](Makefile) targets to learn how to run tests and benchmarks.
+
+## Design overview
+`revive` uses [solc](https://github.com/ethereum/solidity/), the Ethereum Solidity compiler, as the [Solidity frontend](crates/solidity/src/lib.rs) to process smart contracts written in Solidity. The YUL IR code (or legacy EVM assembly as a fallback for older `solc` versions) emitted by `solc` is then translated to LLVM IR, targetting a runtime similar to [Polkadots `contracts` pallet](https://docs.rs/pallet-contracts/latest/pallet_contracts/api_doc/trait.Current.html).
+
+## TODO
 
 - [ ] Efficient implementations of byte swaps, memset, memmove, mulmod and the like
-- [ ] Use `drink` for integration tests once we have 64bit support in PolkaVM
+- [ ] Migrate the mock runtime to the on-chain implementation when its avaialbe
 - [x] Use PolkaVM allocator for heap space
 - [ ] Exercice `schlau` and possibly `smart-bench` benchmark cases
 - [x] Tests currently rely on the binary being in $PATH, which is very annoying and requires `cargo install` all the times
 - [x] Define how to do deployments
 - [ ] Calling conventions for calling other contracts
 - [ ] Runtime environment isn't fully figured out; implement all EVM builtins
-- [ ] Iron out many leftovers from the ZKVM target
+- [ ] Iron out leftovers from the ZKVM target
     - [ ] Use of exceptions
     - [ ] Change long calls (contract calls)
     - [ ] Check all alignments, attributes etc. if they still make sense with our target
     - [x] Custom extensions related to zk VM
-    - [ ] `Active Pointer`: Redundant to calldata forwarding in pallet contracts. [Mainly used here](https://github.com/matter-labs/era-contracts/blob/4aa7006153ad571643342dff22c16eaf4a70fdc1/system-contracts/contracts/libraries/EfficientCall.sol) however we could offer a similar optimization.
-    - []
+    - [x] `Active Pointer`: Redundant to calldata forwarding in pallet contracts. [Mainly used here](https://github.com/matter-labs/era-contracts/blob/4aa7006153ad571643342dff22c16eaf4a70fdc1/system-contracts/contracts/libraries/EfficientCall.sol) however we could offer a similar optimization.
 - [ ] Add a lot more test cases
 - [ ] Debug information
 - [ ] Look for and implement further optimizations