diff --git a/README.md b/README.md
index 1dc0ba9926f452907a565dd2c1661d56b019a463..cd9db0bde1fce99293d052f83f6fb043b10fa106 100644
--- a/README.md
+++ b/README.md
@@ -1,67 +1,69 @@
-# Hyperledger Burrow v0.16
+# Hyperledger Burrow
|[](https://godoc.org/github.com/hyperledger/burrow) | Linux |
|---|-------|
| Master | [](https://circleci.com/gh/hyperledger/burrow/tree/master) |
| Develop | [](https://circleci.com/gh/hyperledger/burrow/tree/develop) |
-Hyperledger Burrow is a permissioned Ethereum smart-contract blockchain node built with <3 by Monax. It executes Ethereum smart contract code on a permissioned virtual machine. Burrow provides transaction finality and high transaction throughput on a proof-of-stake Tendermint consensus engine. For smart contract development most functionality is provided by `monax chains`, exposed through [monax](https://monax.io/docs), the entry point for the Monax Platform.
+Hyperledger Burrow is a permissioned Ethereum smart-contract blockchain node built with <3 by Monax. It executes Ethereum EVM smart contract code (usually written in [Solidity](https://solidity.readthedocs.io)) on a permissioned virtual machine. Burrow provides transaction finality and high transaction throughput on a proof-of-stake [Tendermint](https://tendermint.com) consensus engine.
-## Table of Contents
+## What is Burrow
-- [What is burrow](#what-is-burrow)
-- [Installation](#installation)
-- [For developers](#for-developers)
-- [Usage](#usage)
-- [Configuration](#configuration)
-- [Contribute](#contribute)
-- [License](#license)
-- [Future work](#future-work)
-
-## What is Burrow ?
-
-Hyperledger Burrow is a permissioned blockchain node that executes smart contract code following the Ethereum specification. Burrow is built for a multi-chain universe with application specific optimization in mind. Burrow as a node is constructed out of three main components; the consensus engine, the permissioned Ethereum virtual machine and the rpc gateway. More specifically Burrow consists of the following:
+Hyperledger Burrow is a permissioned blockchain node that executes smart contract code following the Ethereum specification. Burrow is built for a multi-chain universe with application specific optimization in mind. Burrow as a node is constructed out of three main components; the consensus engine, the permissioned Ethereum virtual machine and the rpc gateway. More specifically Burrow consists of the following:
- **Consensus Engine:** transactions are ordered and finalised with the Byzantine fault-tolerant Tendermint protocol. The Tendermint protocol provides high transaction throughput over a set of known validators and prevents the blockchain from forking.
-- **Application Blockchain Interface (ABCI):** The smart contract application interfaces with the consensus engine over the ABCI. The ABCI allows for the consensus engine to remain agnostic from the smart contract application.
-- **Smart Contract Application:** transactions are validated and applied to the application state in the order that the consensus engine has finalised them. The application state consists of all accounts, the validator set and the name registry. Accounts in Burrow have permissions and either contain smart contract code or correspond to a public-private key pair. A transaction that calls on the smart contract code in a given account will activate the execution of that account’s code in a permissioned virtual machine.
+- **Application Blockchain Interface (ABCI):** The smart contract application interfaces with the consensus engine over the [ABCI](https://github.com/tendermint/abci). The ABCI allows for the consensus engine to remain agnostic from the smart contract application.
+- **Smart Contract Application:** transactions are validated and applied to the application state in the order that the consensus engine has finalised them. The application state consists of all accounts, the validator set and the name registry. Accounts in Burrow have permissions and either contain smart contract code or correspond to a public-private key pair. A transaction that calls on the smart contract code in a given account will activate the execution of that account’s code in a permissioned virtual machine.
- **Permissioned Ethereum Virtual Machine:** This virtual machine is built to observe the Ethereum operation code specification and additionally asserts the correct permissions have been granted. Permissioning is enforced through secure native functions and underlies all smart contract code. An arbitrary but finite amount of gas is handed out for every execution to ensure a finite execution duration - “You don’t need money to play, when you have permission to playâ€.
-- **Application Binary Interface (ABI):** transactions need to be formulated in a binary format that can be processed by the blockchain node. Currently tooling provides functionality to compile, deploy and link solidity smart contracts and formulate transactions to call smart contracts on the chain. For proof-of-concept purposes we provide a monax-contracts.js library that automatically mirrors the smart contracts deployed on the chain and to develop middleware solutions against the blockchain network. Future work on the light client will be aware of the ABI to natively translate calls on the API into signed transactions that can be broadcast on the network.
+- **Application Binary Interface (ABI):** transactions need to be formulated in a binary format that can be processed by the blockchain node. Current tooling provides functionality to compile, deploy and link solidity smart contracts and formulate transactions to call smart contracts on the chain.
- **API Gateway:** Burrow exposes REST and JSON-RPC endpoints to interact with the blockchain network and the application state through broadcasting transactions, or querying the current state of the application. Websockets allow to subscribe to events, which is particularly valuable as the consensus engine and smart contract application can give unambiguously finalised results to transactions within one blocktime of about one second.
## Installation
-`burrow` is intended to be used by the `monax chains` command via [monax](https://monax.io/docs). Available commands such as `make | start | stop | logs | inspect | update` are used for chain lifecycle management.
-
-### For Developers
-Dependency management for Burrow is managed with [glide](github.com/Masterminds/glide), and you can build Burrow from source by following
-- [Install go](https://golang.org/doc/install)
+- [Install go](https://golang.org/doc/install) and have `$GOPATH` set
- Ensure you have `gmp` installed (`sudo apt-get install libgmp3-dev || brew install gmp`)
-- and execute following commands in a terminal:
-- `go get github.com/Masterminds/glide`
-- `go get -d github.com/hyperledger/burrow`
-- `REPO=$($GOPATH/src/github.com/hyperledger/burrow)`
-- `cd $REPO && glide install`
-- `cd $REPO/cmd/burrow && go install`
+```
+go get github.com/hyperledger/burrow
+cd github.com/hyperledger/burrow
+make build
+```
+
+This will build the `burrow` and `burrow-client` binaries and put them in the `bin/` directory. They can be executed from there or put wherever is convenient.
-To run `burrow`, just type `$ burrow serve --work-dir <path to chain directory>`, where the chain directory needs to contain the configuration, genesis file, and private validator file as generated by `monax chains make`.
+## Usage
-This will start the node using the provided folder as working dir. If the path is omitted it defaults to `~/.monax`.
+The end result will be a `burrow.toml` that will be read in from your current working directory when starting `burrow`.
-For a Vagrant file see [monax-vagrant](https://github.com/monax/monax-vagrant) for drafts or soon this repo for [Vagrant](https://github.com/hyperledger/burrow/issues/514) and Packer files.
+### Configuration
-## Usage
+Note: here we'll need `monax-keys` to start the keys server (TODO, where?)
+
+The quick-and-dirty one-liner looks like:
+
+```
+burrow spec -p1 -f1 | burrow configure -s- -v0
+```
+
+which translates into:
+
+```
+burrow spec --participant-accounts=1 --full-accounts=1 > genesis-spec.json
+burrow configure --genesis-spec=genesis-spec.json --validator-index=0 > burrow.toml
+```
-Once the server has started, it will begin syncing up with the network. At that point you may begin using it. The preferred way is through our [javascript api](https://github.com/monax/legacy-contracts.js), but it is possible to connect directly via HTTP or websocket.
+Once the `burrow.toml` has been created, we run:
-## Configuration
+```
+burrow
+```
-A commented template config will be written as part of the `monax chains make` [process](https://monax.io/docs/getting-started) and can be edited prior to the `monax chains start` [process](https://monax.io/docs/getting-started).
+and the logs will start streaming through.
### Logging
-Logging is highly configurable through the `config.toml` `[logging]` section. Each log line is a list of key-value pairs that flows from the root sink through possible child sinks. Each sink can have an output, a transform, and sinks that it outputs to. Below is a more involved example of than the one appearing in the default generated config of what you can configure:
+
+Logging is highly configurable through the `burrow.toml` `[logging]` section. Each log line is a list of key-value pairs that flows from the root sink through possible child sinks. Each sink can have an output, a transform, and sinks that it outputs to. Below is a more involved example of than the one appearing in the default generated config of what you can configure:
```toml
# This is a top level config section within the main Burrow config
@@ -100,19 +102,19 @@ Logging is highly configurable through the `config.toml` `[logging]` section. Ea
output_type = "file"
path = "/var/log/burrow-network.log"
```
+
## Contribute
-We welcome all contributions and have submitted the code base to the Hyperledger project governance during incubation phase. As an integral part of this effort we want to invite new contributors, not just to maintain but also to steer the future direction of the code in an active and open process.
+We welcome any and all contributions. Read the [contributing file](.github/CONTRIBUTING.md) for more informaion on making your first Pull Request to Burrow!
You can find us on:
-- [the Marmot Den (slack)](http://slack.monax.io)
-- [here on Github](http://github.com/hyperledger/burrow/issues)
-- [support.monax.io](http://support.monax.io)
-- read the [Contributor file](.github/CONTRIBUTING.md)
+- [Hyperledger Chat](https://chat.hyperledger.org)
+- [Hyperledger Mailing List](https://lists.hyperledger.org/mailman/listinfo)
+- [here on Github](https://github.com/hyperledger/burrow/issues)
## Future work
-Some burrows marmots have already started digging to build the enterprise ecosystem applications of the future are listed in [docs/proposals](./docs/PROPOSALS.md). Marmots live in groups we welcome your help on these or other improvement proposals. Please help us by joining the conversation on what features matter to you.
+For some (slightly outdated) ideas on future work, see the [proposals document](./docs/PROPOSALS.md).
## License
diff --git a/docs/glide-readme.md b/docs/glide-readme.md
deleted file mode 100644
index 56a897add51a02e6d2ae4aa493b5ae3a8492b32f..0000000000000000000000000000000000000000
--- a/docs/glide-readme.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# Using glide with this repository
-We use the [glide](https://github.com/Masterminds/glide) tool to manage our go
-dependencies.
-
-In this repo we maintain a set of vendored dependencies under vendor/. Make sure
-you have environment variable `GO15VENDOREXPERIMENT` set:
-
-```bash
-export GO15VENDOREXPERIMENT=1
-```
-
-## Installing dependencies
-To (re)install dependencies from scratch based on the values locked in by
-glide.lock run:
-
-```bash
-glide install -s -u
-```
-
-Where `-s` strips VCS files, in the case of git this stops vendored dependencies
-from being treated as submodules that can cause problems, and `-u` updates vendored
-dependencies, that install otherwise skips when dealing with a vendor/ without
-git roots.
-
-To update dependencies - and store the updated versions in glide.lock you can run:
-
-```
-glide up -s -u
-```
-
-This will update the versions according to the specification in glide.yaml, which
-may: update to the latest available, update up to some version bound, or may keep
-exact same version if hooked to a specific commit.
-
-*Beware updating dependencies should be considered destructive* and should only
-be done deliberately and not as part of unrelated updates to the code as a matter
-of course.
-
-## Running tests
-Running `go test ...` from the root of the repository will try to execute the tests
-belonging to all packages under vendor/. Not only is this probably not what you want
-but those tests are likely to break because the the test runner may be unable to find
-their own nested vendored dependencies.
-
-Instead use:
-
-```bash
-glide novendor | xargs go test
-```
-
-Where `glide novendor` returns a newline-delimited list of packages in this project
-excluding vendor of the form `./<package name>/...`.