diff --git a/docs/configuring-storage.rst b/docs/configuring-storage.rst
index 592f22958..0a6267752 100644
--- a/docs/configuring-storage.rst
+++ b/docs/configuring-storage.rst
@@ -14,7 +14,10 @@ e.g :
         "provider": "ipfs",
         "available_providers": ["ipfs"],
         "host": "localhost",
-        "port": 5001
+        "port": 5001,
+        "versions": {
+          "ipfs-api": "17.2.4"
+        }
       },
       "development": {
         "enabled": true,
@@ -30,4 +33,5 @@ options available:
   * ``provider`` (string: "ipfs") desired provider to automatically connect to on the dapp. e.g in the example above, seting this to ``"ipfs"`` will automaticaly add ``EmbarkJS.setProvider('ipfs', {server: 'localhost', 5001})`` to the generated code
   * ``available_providers`` (array: ["ipfs"]) list of storages to be supported on the dapp. This will affect what's available with the EmbarkJS library on the dapp.
   * ``host`` and ``port`` of the ipfs node to connect to.
+  * ``versions`` (object) key-value hash of library and its desired version
 
diff --git a/docs/creating-a-new-dapp.rst b/docs/creating-a-new-dapp.rst
index bd52c0299..66d9435b7 100644
--- a/docs/creating-a-new-dapp.rst
+++ b/docs/creating-a-new-dapp.rst
@@ -25,11 +25,8 @@ DApp Structure
 
 .. code:: bash
 
-      app/
-        |___ contracts/ #solidity smart contracts
-        |___ html/
-        |___ css/
-        |___ js/
+      app/ # dapp code
+      contracts/ #smart contracts
       config/
         |___ blockchain.json #rpc and blockchain configuration
         |___ contracts.json  #ethereum contracts configuration
@@ -38,5 +35,9 @@ DApp Structure
         |___ webserver.json  #dev webserver configuration
       test/
         |___ #contracts tests
+      dist/
+        |___ # build folder
+      chains.json #keeps track of deployments in each chain
 
 Solidity files in the contracts directory will automatically be deployed with ``embark run``. Changes in any files will automatically be reflected in app, changes to contracts will result in a redeployment and update of their JS Bindings
+
diff --git a/docs/dashboard.rst b/docs/dashboard.rst
index 4d5d05fc8..6f77d98ff 100644
--- a/docs/dashboard.rst
+++ b/docs/dashboard.rst
@@ -28,3 +28,19 @@ Embark.
 if you prefer to only see the logs, you can disable the dashboard with the
 nodashboard option ``embark run --nodashboard``
 
+Console
+=========
+
+There is a console at the bottom which can be used to interact with
+contracts or with embark itself. type ``help`` to see a list of
+available commands, more commands will be added with each version of
+Embark.
+
+After contract deployment, you should be able to interact with the web3 object and the deployed contracts.
+Some commands available include:
+
+* ``version`` - see list of software & libraries and their respective versions
+* ``quit`` or ``exit`` - to immediatly exit (you can also use ctrl + c)
+* ``webserver start`` - start the dev webserver
+* ``webserver stop`` - stop the dev webserver
+
diff --git a/docs/deploying-to-ipfs.rst b/docs/deploying-to-ipfs.rst
index cb5a20a9d..a0c4d7bcf 100644
--- a/docs/deploying-to-ipfs.rst
+++ b/docs/deploying-to-ipfs.rst
@@ -6,3 +6,4 @@ and then run ``embark upload ipfs``. If you want to deploy to the livenet then
 after configuring you account on ``config/blockchain.json`` on the
 ``livenet`` environment then you can deploy to that chain by
 specifying the environment ``embark ipfs livenet``.
+
diff --git a/docs/embarkjs-storage.rst b/docs/embarkjs-storage.rst
index c8b9f2a4c..360b65e0a 100644
--- a/docs/embarkjs-storage.rst
+++ b/docs/embarkjs-storage.rst
@@ -55,3 +55,8 @@ The current available storage is IPFS. it can be initialized as
 .. code:: javascript
 
       EmbarkJS.Storage.getUrl(hash);
+
+**configuring IPFS**
+
+note: if not using localhost, the cors needs to be set as ```ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin '["your-host-name-port"]```
+
diff --git a/docs/index.rst b/docs/index.rst
index c3550d494..24b444c8a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -29,6 +29,7 @@ This is a work in progress, feel free to contribute!
    deploying-to-swarm.rst
    plugins.rst
    using-embark-with-grunt.rst
+   other.rst
    donations.rst
 
 Indices and tables
diff --git a/docs/other.rst b/docs/other.rst
new file mode 100644
index 000000000..243c820dd
--- /dev/null
+++ b/docs/other.rst
@@ -0,0 +1,8 @@
+Other
+========
+
+In case you run into issues it can useful to reset embark's state, to do this
+you can run the cmd ```embark reset```
+
+
+
diff --git a/docs/plugins.rst b/docs/plugins.rst
index 49518ef01..60706a69c 100644
--- a/docs/plugins.rst
+++ b/docs/plugins.rst
@@ -28,13 +28,16 @@ The ``embark`` object then provides an api to extend different functionality of
 * plugin to add support for es6, jsx, coffescript, etc (``embark.registerPipeline``)
 * plugin to add standard contracts or a contract framework (``embark.registerContractConfiguration`` and ``embark.addContractFile``)
 * plugin to make some contracts available in all environments for use by other contracts or the dapp itself e.g a Token, a DAO, ENS, etc.. (``embark.registerContractConfiguration`` and ``embark.addContractFile``)
-* plugin to add a libraries such as react or boostrap (``embark.addFileToPipeline``)
+* plugin to add a libraries such as react or boostrap (``embark.addFileToPipeline``, ``embark.registerImportFile``)
 * plugin to process contract's binary code before deployment (``embark.beforeDeploy``)
 * plugin to specify a particular web3 initialization for special provider uses (``embark.registerClientWeb3Provider``)
 * plugin to create a different contract wrapper (``embark.registerContractsGeneration``)
 * plugin to add new console commands (``embark.registerConsoleCommand``)
 * plugin to add support for another contract language such as viper, LLL, etc (``embark.registerCompiler``)
 * plugin that executes certain actions when contracts are deployed (``embark.events.on``)
+* plugin that registers a service in embark (``embark.registerServiceCheck``)
+* plugin that adds support to upload the dapp somewhere (``embark.registerUploadCommand``)
+* plugin that extends EmbarkJS (``embark.addCodeToEmbarkJS``, ``embark.addProviderInit``)
 
 **embark.pluginConfig**
 
@@ -298,9 +301,11 @@ This call is used to listen and react to events that happen in Embark such as co
    * available events:
       * "contractsDeployed" - triggered when contracts have been deployed
       * "file-add", "file-change", "file-remove", "file-event" - triggered on a file change, args is (filetype, path)
-      * "abi", "abi-vanila", "abi-contracts-vanila" - triggered when contracts have been deployed and returns the generated JS code
+      * "code", "code-vanila", "code-contracts-vanila" - triggered when contracts have been deployed and returns the generated JS code
       *  "outputDone" - triggered when dapp is (re)generated
       * "firstDeploymentDone" - triggered when the dapp is deployed and generated for the first time
+      * "check:backOnline:serviceName" - triggered when the service with ``serviceName`` comes back online
+      * "check:backOffline:serviceName" - triggered when the service with ``serviceName`` comes back offline
 
 .. code:: javascript
 
@@ -314,3 +319,85 @@ This call is used to listen and react to events that happen in Embark such as co
           }
         });
     }
+
+**embark.registerServiceCheck(serviceName, callback({name, status}), time)**
+
+This call is used to register a service in embark so it's periodically checked.
+It will be displayed in the Embark Dashboard, and will also trigger events such as ``check:backOnline:yourServiceName`` and ``check:backOffline:yourServiceName``
+
+* serviceName - name of service (string)
+* callback:
+  * "name" - name/text to display (string)
+  * "status" - status of the service (string, "on" or "off" or "warn")
+* time (optional) - ms interval to call the callback (default: 5000 ms)
+
+.. code:: javascript
+
+    module.exports = function(embark) {
+        embark.registerServiceCheck("MyServer", function(cb) {
+          if (myServiceOnline()) {
+            return cb({name: "MyServer Online", status: "on"});
+          } else {
+            return cb({name: "MyServer Offline", status: "off"});
+          }
+        });
+    }
+
+**embark.registerUploadCommand(cmdName, callback)**
+
+This call is used to add a new cmd to ``embark upload`` to upload the dapp to
+a new storage service
+
+.. code:: javascript
+
+    module.exports = function(embark) {
+        embark.registerUploadCommand("ipfs", function() {
+          run("ipfs add -r dist/");
+        });
+    }
+
+**embark.addCodeToEmbarkJS(code)**
+
+This call is used to add code to the embark.js library. It's typically used to
+extend it with new functionality, new storage providers, new communication
+providers, etc..
+
+.. code:: javascript
+
+    module.exports = function(embark) {
+        embark.addCodeToEmbarkJS("alert('hello world!')");
+    }
+
+**embark.addProviderInit(providerType, code, initCondition(config))**
+
+This call is used to add code to be executed in the initialization under the
+condition that ```initCondition``` returns true. For example this can be used to
+set the storage provider of EmbarkJS to ipfs if ipfs is enabled as a provider in
+the config
+
+* providerType - type of provider (string, "storage" or "communication")
+* code - code to add (string)
+* callback:
+  * "config" - config of the ``providerType``
+
+.. code:: javascript
+
+    module.exports = function(embark) {
+        let code = "\nEmbarkJS.Storage.setProvider('ipfs')";
+        embark.addProviderInit('storage', code, (storageConfig) => {
+          return (storageConfig.provider === 'ipfs' && storageConfig.enabled === true);
+        });
+    }
+
+**embark.registerImportFile(importName, importLocation)**
+
+This call is used so the plugin can make a certain file available as a library
+to a user
+
+.. code:: javascript
+    var path = require('path')
+
+    module.exports = function(embark) {
+        embark.registerImportFile("my-lib", path.join(__dirname, "my-lib.js"));
+    }
+
diff --git a/docs/structuring-application.rst b/docs/structuring-application.rst
index 0d70c5c01..c384a9fb8 100644
--- a/docs/structuring-application.rst
+++ b/docs/structuring-application.rst
@@ -8,12 +8,12 @@ structure using ``embark.json``
 
     # embark.json
     {
-      "contracts": ["app/contracts/**"],
+      "contracts": ["contracts/**"],
       "app": {
+        "js/app.js": ["app/dapp.js"],
+        "index.html": "app/index.html",
         "css/app.css": ["app/css/**"],
-        "images/": ["app/images/**"],
-        "js/app.js": ["embark.js", "app/js/**"],
-        "index.html": "app/index.html"
+        "images/": ["app/images/**"]
       },
       "buildDir": "dist/",
       "config": "config/",
diff --git a/docs/tests.rst b/docs/tests.rst
index 2b6d0801f..0172d99be 100644
--- a/docs/tests.rst
+++ b/docs/tests.rst
@@ -10,20 +10,17 @@ EVM.
 .. code:: javascript
 
     # test/simple_storage_spec.js
-
-    var assert = require('assert');
-    var Embark = require('embark');
-    var EmbarkSpec = Embark.initTests();
-    var web3 = EmbarkSpec.web3;
-
     describe("SimpleStorage", function() {
+      this.timeout(0);
       before(function(done) {
         var contractsConfig = {
           "SimpleStorage": {
             args: [100]
           }
         };
-        EmbarkSpec.deployAll(contractsConfig, done);
+        EmbarkSpec.deployAll(contractsConfig, (accounts) => {
+          done();
+        });
       });
 
       it("should set constructor value", function(done) {
@@ -44,5 +41,82 @@ EVM.
 
     });
 
+**configuring accounts**
+
+You can use a mnemonic to always use a specific account for testing purposes
+
+.. code:: javascript
+
+    # test/simple_storage_spec.js
+
+    config({
+      mnemonic: "labor ability deny divide mountain buddy home client type shallow outer pen"
+    })
+
+    describe("SimpleStorage", function() {
+      ....
+
+**configuring node**
+
+By default Embark will use an internal VM to run the tests, however you can also
+specify a node to connect to and run the tests there.
+
+.. code:: javascript
+
+    # test/simple_storage_spec.js
+
+    config({
+      node: "http://localhost:8545"
+    })
+
+    describe("SimpleStorage", function() {
+      ....
+
+**testing with any testing framework**
+
 Embark uses `Mocha <http://mochajs.org/>`__ by default, but you can use
-any testing framework you want.
+any testing framework you want. To do this you can require Embark as a library
+and initialize the testing functionality. Below is an example using mocha:
+
+.. code:: javascript
+
+    # test/simple_storage_spec.js
+
+    var assert = require('assert');
+    var Embark = require('embark');
+    var EmbarkSpec = Embark.initTests();
+    var web3 = EmbarkSpec.web3;
+
+    describe("SimpleStorage", function() {
+      this.timeout(0);
+      before(function(done) {
+        var contractsConfig = {
+          "SimpleStorage": {
+            args: [100]
+          }
+        };
+        EmbarkSpec.deployAll(contractsConfig, (accounts) => {
+          done();
+        });
+      });
+
+      it("should set constructor value", function(done) {
+        SimpleStorage.storedData(function(err, result) {
+          assert.equal(result.toNumber(), 100);
+          done();
+        });
+      });
+
+      it("set storage value", function(done) {
+        SimpleStorage.set(150, function() {
+          SimpleStorage.get(function(err, result) {
+            assert.equal(result.toNumber(), 150);
+            done();
+          });
+        });
+      });
+
+    });
+
+``mocha test/simple_storage_spec.js --no-timeouts``
+
diff --git a/docs/usage.rst b/docs/usage.rst
index 63afbdfd0..bbef4c947 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -42,3 +42,36 @@ and deploy your DApp to a local server at http://localhost:8000
 Note that if you update your code it will automatically be re-deployed,
 contracts included. There is no need to restart embark, refreshing the
 page on the browser will do.
+
+embark run options
+============
+
+**Dashboard**
+
+* ``--nodashboard`` - simple mode, disables the dashboard
+* ``--no-color`` - no colors in case it's needed for compatbility purposes
+
+**Web Server**
+
+* ``-p [port]`` or ``--port [port]`` - port to run the dev webserver (default: 8000)
+* ``-b [host]`` or ``--host [host]`` - host to run the dev webserver (default: localhost)
+* ``--noserver`` - disable the development webserver
+
+**Log File**
+
+* ``--logfile [logfile]`` - filename to output logs (default: none)
+
+embark simulator options
+============
+
+**RPC Server**
+
+* ``-p [port]`` or ``--port [port]`` - port to run the rpc simulator (default: 8545)
+* ``-b [host]`` or ``--host [host]`` - host to run the rpc simulator (default: localhost)
+
+**Other Options**
+
+* ``--accounts [numAccounts]`` - number of accounts (default: 10)
+* ``--defaultBalanceEther [balance]`` - Amount of ether to assign each test account (default: 100)
+* ``--gasLimit [gasLimit]`` - custom gas limit (default: 8000000)
+
diff --git a/docs/using-contracts.rst b/docs/using-contracts.rst
index 630afa9ea..2a2ea7690 100644
--- a/docs/using-contracts.rst
+++ b/docs/using-contracts.rst
@@ -27,9 +27,11 @@ Will automatically be available in Javascript as:
 .. code:: javascript
 
     # app/js/index.js
-    SimpleStorage.set(100);
-    SimpleStorage.get().then(function(value) { console.log(value.toNumber()) });
-    SimpleStorage.storedData().then(function(value) { console.log(value.toNumber()) });
+    import SimpleStorage from 'Embark/contracts/SimpleStorage';
+
+    SimpleStorage.methods.set(100).send();
+    SimpleStorage.methods.get().call().then(function(value) { console.log(value) });
+    SimpleStorage.methods.storedData().call().then(function(value) { console.log(value) });
 
 You can specify for each contract and environment its gas costs and
 arguments:
@@ -44,7 +46,8 @@ arguments:
           "SimpleStorage": {
             "args": [
               100
-            ]
+            ],
+            "gas": 800000
           }
         }
       }
@@ -53,6 +56,7 @@ arguments:
 If you are using multiple contracts, you can pass a reference to another
 contract as ``$ContractName``, Embark will automatically replace this
 with the correct address for the contract.
+You can also specify interfaces and choose to not deploy contracts (for e.g in case they are interfaces)
 
 .. code:: json
 
@@ -76,6 +80,9 @@ with the correct address for the contract.
             "args": [
               "$SimpleStorage"
             ]
+          },
+          "MyContractInteface": {
+            "deploy": false
           }
         }
       }
@@ -169,3 +176,4 @@ instead.
       }
       ...
     }
+
diff --git a/docs/working-with-different-chains.rst b/docs/working-with-different-chains.rst
index 7a90ea13f..4fef2dd52 100644
--- a/docs/working-with-different-chains.rst
+++ b/docs/working-with-different-chains.rst
@@ -15,12 +15,56 @@ managed at config/blockchain.json
     # config/blockchain.json
       ...
        "livenet": {
-        "networkType": "livenet",
-        "rpcHost": "localhost",
-        "rpcPort": 8545,
-        "rpcCorsDomain": "http://localhost:8000",
-        "account": {
-          "password": "config/livenet/password"
-        }
+         "networkType": "livenet",
+         "rpcHost": "localhost",
+         "rpcPort": 8545,
+         "rpcCorsDomain": "http://localhost:8000",
+         "account": {
+           "password": "config/livenet/password"
+         },
+         "targetGasLimit": 8000000,
+         "wsOrigins": "http://localhost:8000",
+         "wsRPC": true,
+         "wsHost": "localhost",
+         "wsPort": 8546,
+         "simulatorMnemonic": "example exile argue silk regular smile grass bomb merge arm assist farm",
+         "simulatorBlocktime": 0
       },
       ...
+
+**Specify a genesis block**
+
+You can specify a genesis block for each environment if you so wish. This can be
+useful to establish some initial balances and specific conditions such as the
+gasLimit
+
+.. code:: json
+
+    # config/blockchain.json
+      ...
+       "development": {
+         "genesisBlock": "config/development/genesis.json",
+         "account": {
+           "password": "config/livenet/password"
+         }
+      },
+      ...
+
+    # config/development/genesis.json
+     {
+        "config": {
+          "homesteadBlock": 1
+        },
+        "nonce": "0x0000000000000042",
+        "difficulty": "0x0",
+        "alloc": {
+            "0x3333333333333333333333333333333333333333": {"balance": "15000000000000000000"}
+        },
+        "mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000",
+        "coinbase": "0x3333333333333333333333333333333333333333",
+        "timestamp": "0x00",
+        "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
+        "extraData": "0x",
+        "gasLimit": "0x7a1200"
+      }
+