Big overhaul of the main README

README.md

@@ -1,12 +1,66 @@
 # CosmJS
 
-This is a JavaScript/TypeScript client-side binding to [wasmd](https://github.com/cosmwasm/wasmd), a sample blockchain for the [cosmwasm](https://github.com/confio/cosmwasm) smart contracting platform.
+CosmJS is the swiss army knife to power JavaScript based client solutions
+ranging from Web apps/explorers over browser extensions to server-side clients
+like faucets/scrapers in the Cosmos ecosystem.
+
+"Cosm" stands for Cosmos and "JS" stands for _runs everywhere_ – we actually
+develop in TypeScript.
+
+## Packages
+
+CosmJS is a library that consists of many smaller npm packages within the
+[@cosmjs namespace](https://www.npmjs.com/org/cosmjs), a so called monorepo.
+Here are some of them to get an idea:
+
+| Package                               | Description                                            | Latest version                                                                                                      |
+| ------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| [@cosmjs/sdk38](packages/sdk38)       | A client library for the Cosmos SDK 0.38               | [![npm version](https://img.shields.io/npm/v/@cosmjs/sdk38.svg)](https://www.npmjs.com/package/@cosmjs/sdk38)       |
+| [@cosmjs/faucet](packages/faucet)     | A faucet application for node.js                       | [![npm version](https://img.shields.io/npm/v/@cosmjs/faucet.svg)](https://www.npmjs.com/package/@cosmjs/faucet)     |
+| [@cosmjs/cosmwasm](packages/cosmwasm) | Client for chains with the CosmWasm module enabled     | [![npm version](https://img.shields.io/npm/v/@cosmjs/cosmwasm.svg)](https://www.npmjs.com/package/@cosmjs/cosmwasm) |
+| [@cosmjs/crypto](packages/crypto)     | Cryptography resources for blockchain projects         | [![npm version](https://img.shields.io/npm/v/@cosmjs/crypto.svg)](https://www.npmjs.com/package/@cosmjs/crypto)     |
+| [@cosmjs/encoding](packages/encoding) | Encoding helpers for blockchain projects               | [![npm version](https://img.shields.io/npm/v/@cosmjs/encoding.svg)](https://www.npmjs.com/package/@cosmjs/encoding) |
+| [@cosmjs/math](packages/math)         | Safe integers; decimals for handling financial amounts | [![npm version](https://img.shields.io/npm/v/@cosmjs/math.svg)](https://www.npmjs.com/package/@cosmjs/math)         |
+
+### Modularity
+
+We're pretty proud of the modularity and a clean dependency tree in this
+monorepo. This ensures software quality on our side and lets users pick exactly
+what they need. Here you see how everything fits together (every item is an npm
+package; right depends on left):
+
+![CosmJS dependency tree](docs/cosmjs-tree.png)
+
+<!--
+Build with depsight (https://github.com/webmaster128/depsight), using:
+
+from_npm ~/cosmjs | depsight --exclude cosmjs-monorepo-root --format svg --output - | inkscape --pipe --export-width 3000 --export-filename cosmjs-tree.png
+
+optipng cosmjs-tree.png
+-->
+
+### Supported JS environments
+
+Currently the codebase supports the following environments:
+
+1. Node.js 10+
+2. Modern browsers (Chromium/Firefox/Safari, no IE or Edge)
+3. Browser extensions (Chromium/Firefox)
+
+Our current JavaScript target standard is ES2017, giving us native async/wait
+support. We use WebAssembly to implement certain crypto.
+
+We're happy to adjust this list according to users' needs as long as you don't
+ask for IE support. If your environment does not support Wasm, we can work on a
+solution with swapable implementations.
 
 ## Development
 
 Requires Node 10+. For best results, use yarn. The basic commands are:
 
 ```sh
+yarn install
+
 # compile the code
 yarn build
 # run unit tests
@@ -18,7 +72,10 @@ yarn format && yarn lint
 
 ### Integration tests
 
-To run the entire test suite, you need to run a local blockchain to test against. This should work on any Linux/OSX system with docker installed.
+To run the entire test suite, you need to run a local blockchain to test
+against. We use [wasmd](https://github.com/CosmWasm/wasmd) for both CosmWasm
+tests and as a generic Cosmos SDK 0.38 blockchain. This should work on any
+Linux/OSX system with docker installed:
 
 ```sh
 ./scripts/wasmd/start.sh