diff --git a/README.md b/README.md
index dafad9b..d4adc5c 100644
--- a/README.md
+++ b/README.md
@@ -1,85 +1,83 @@
 # ssb-client v2
+Create an [rpc connection](https://ssbc.github.io/scuttlebutt-protocol-guide/#rpc-protocol) to an 
+*[sbot](https://github.com/ssbc/scuttlebot)* instance. Here are some resources that can help you 
+understand how it works in a practical way:
 
-[Scuttlebot](https://github.com/ssbc/scuttlebot) client.
+* Tutorials using this library to create basic clients: 
+[ssb-client-basic](https://github.com/mixmix/ssb-client-basic)
+* A simple command line wrapper around this library: 
+[ssb-client-cli](https://github.com/qypea/ssb-client-cli)
 
-Create an [rpc connection](https://ssbc.github.io/scuttlebutt-protocol-guide/#rpc-protocol) to an sbot running locally.
+## Table of contents
+[Example](#example) | [Api](#api) | [License](#license)
 
-## example
+___
+
+# Example
 
 ```js
 var ssbClient = require('ssb-client')
 var ssbKeys = require('ssb-keys')
 
-// simplest usage, connect to localhost sbot
-// this will cb with an error if an sbot server is not running
-ssbClient(function (err, sbot) {
+  var keys = ssbKeys.loadOrCreateSync('./my-ssb-folder')
+  var config = { caps: { shs: '1KHLiKZvAvjbY1ziZEHMXawbCEIM6qwjCDm3VYRan/s=' }}
+
+// This is the clearest and 
+// recommended way to use ssb-client
+ssbClient(keys, config, function (err, sbot, config) {
   // ...
 })
-
-// configuration:
-var keys = ssbKeys.loadOrCreateSync('./app-private.key')
-ssbClient(
-  keys,                // optional, defaults to ~/.ssb/secret
-  {
-    host: 'localhost', // optional, defaults to localhost
-    port: 8008,        // optional, defaults to 8008
-    key: keys.id,      // optional, defaults to keys.id
-
-    caps: {
-        // random string for `appKey` in secret-handshake
-        shs: ''
-    },
-
-    // Optional muxrpc manifest. Defaults to manifest provided by server.
-    manifest: {}
-
-  },
-  function (err, sbot, config) {
-    // ...
-  }
-)
 ```
 
-* Tutorials using this library to create basic clients: [ssb-client-basic](https://github.com/mixmix/ssb-client-basic)
-* A simple command line wrapper around this library: [ssb-client-cli](https://github.com/qypea/ssb-client-cli)
-
-## api
+# Api
 
-### require('ssb-client') => createEasyClient
+## ssbClient(cb): async
+Makes things as "easy" as possible, by loading configuration and defaults. This is useful for scripts 
+but applications should specify the configuration.
 
-#### createEasyClient(cb(err, sbot))
-
-Create a connection to the local `ssb-server` instance, using the default keys.
-Configuration and keys will be loaded from directory specified by `ssb_appname`.
-(by default `~/.ssb`)
+```js
+var ssbClient = require('ssb-client')
+ssbClient(function(err, sbot, config) {})
+```
+Create a connection to the local `ssb-server` instance, using the default keys and configuration. This 
+will be loaded from directory specified by `ssb_appname` (by default `~/.ssb`).
 
 The manifest will be the manifest provided by that server.
 
-Calling this without arguments is handy for scripts, but applications
-should use the clearer apis.
+Calling this without arguments is handy for scripts, but applications should use the clearer apis.
 
-there is a legacy api, that makes things as "easy" as possible,
-by loading configuration and defaults. This is useful for scripts
-but applications should probably use
+## ssbClient({ keys, config, manifest, remote } | keys | config | cb): async
+There are several ways to call ssb-client. Many of them are shortcuts for advanced users and can 
+generate some confusion.
 
-##### createCustomClient({keys, config, manifest, remote}, cb(err, sbot))
+```js
+var ssbClient = require('ssb-client')
+var ssbKeys = require('ssb-keys')
 
-Connect to a specific server with fixed settings. All fields are mandatory.
+var keys = ssbKeys.loadOrCreateSync()
+var config = { port: 4321 }
 
-#### createLegacyClient(keys, opts, cb(err, sbot))
+// With keys and config, 
+// config.caps are required
+ssbClient(keys, config, function(err, sbot, config) {})
 
-Connect to a client with some custom settings.
+//Only with config
+ssbClient(config, function(err, sbot, config) {})
 
-opts supports the keys:
+//Only with keys
+ssbClient(keys, function(err, sbot, config) {})
 
-* `remote` multiserver address to connect to
-* `host, port, key` (legacy) if remote is not set, assemble address from host, port, key.
-* `manifest` use a custom manifest.
+// With keys and custom ssb_appname
+ssbClient(keys, 'testnet', function(err, sbot, config) {})
 
-If you need custom options, it's recommended to use the `createCustomClient` API
-instead, but this is still provided for legacy support.
+// Only with custom ssb_appname
+ssbClient('testnet', function(err, sbot, config) {})
 
+// This is the option that offers more customization
+ssbClient({ keys, config, manifest, remote }, function(err, sbot, config) {})
+```
 
+## Parameters
 ### keys
 
 See [ssb-keys](https://github.com/ssbc/ssb-keys). The keys look like this:
@@ -91,14 +89,23 @@ See [ssb-keys](https://github.com/ssbc/ssb-keys). The keys look like this:
     curve: 'ed25519'
 }
 ```
+### config
+You can use [`ssb-config`](https://github.com/ssbc/ssb-config) to generate a valid configuration.
 
-### caps
-`caps.shs` is a random string passed to [secret-handshake](https://github.com/auditdrivencrypto/secret-handshake#example). It determines which sbot you are able to connect to. It defaults to a magic string in this repo and also in [scuttlebot](https://github.com/ssbc/scuttlebot/blob/master/lib/ssb-cap.js)
+No parameters are required except `config.caps.shs` if the call is `ssbClient(keys, config, cb)`.
 
-```js
-var appKey = Buffer.from(opts.caps.shs, 'base64')
-```
+`config.caps.shs` is a random string passed to 
+[secret-handshake](https://github.com/auditdrivencrypto/secret-handshake#example). It determines which 
+sbot you are able to connect to.
+
+In all other cases the configuration used will be the result of merging the configuration declared and 
+the one founded in the application directory (~/.ssb in most cases).
+
+If `config.manifest` is not defined, the manifest will be provided by the server.
 
+### ssb_appname
+Declares where to look for further config, where to read and write databases. Stores data in 
+~/.${appName}, defaults to ssb (so data in ~/.ssb).
 
 ## License