diff --git a/.DS_Store b/.DS_Store
new file mode 100644
index 0000000..21dc07c
Binary files /dev/null and b/.DS_Store differ
diff --git a/README.md b/README.md
index 0eccc85..a669c96 100644
--- a/README.md
+++ b/README.md
@@ -12,10 +12,10 @@
 
 Speedrun helps you control your compute fleet with minimal effort.
 
-Example (stop nginx across 3k machines):
+Example, stop nginx across 3k machines:
 
 ```bash
-speedrun service stop nginx
+speedrun service stop nginx --target "Labels.role == 'nginx'"
 ```
 
 Features:
@@ -24,9 +24,12 @@ Features:
 * serverless
 * idempotent
 * no complex configuration required
-* server discovery via native cloud integration (currently Google Cloud only, AWS and Azure coming up!)
+* service discovery via native cloud integration (currently Google Cloud only, AWS, Azure and Consul coming up!)
 * extensible (plugin system is in the works)
 
+## Motivation
+This project satisfies a simple need: to be able to perform certain type of operations, such as a service restart, occasionally and on a large number of machines. It should allow you, the SRE/DevOps person, to act on a large scale infrastructure in case of immediate need. The solution attempts to be simple to use, require little maintenance and be easy to configure. It's inspired by Saltstack's execution modules.
+
 ## Installation
 
 #### MacOS, Linux, Windows
@@ -39,7 +42,9 @@ Download the precompiled binaries from here: [Releases](https://github.com/dpogo
 
 On a server:
 
-`sudo ./portal --insecure`
+```bash
+sudo ./portal --insecure
+```
 
 On your machine:
 
@@ -51,17 +56,31 @@ speedrun run whoami --insecure
 
 ## Architecture
 
-* picture first here
+<p align="center">
+  <a rel="nofollow">
+    <img src="assets/architecture-overview.png" width="600" style="max-width:100%;">
+  </a>
+</p>
 
-* speedrun client
+#### Speedrun
+Speedrun is the client. Speedrun is the CLI tool you run on your computer to send commands to your servers.
 
-* portal
+#### Portal
+Portal is the agent running on each server you want to send commands to. It will receive commands sent from Speedrun and respond with the outcome details accordingly.
+#### Service Discovery
+There is no server component in Speedrun's architecture. Service discovery is performed against native facilities of each supported provider such as GCP,AWS or Consul.
+This eliminates the need to deploy,maintain and operate a server and all problems that would come with it as a consequence, such as: scalability, failure tolerance, redundancy, agent lifecycle management etc.
+![Service Discovery](assets/service-discovery-sequence.png)
 
-* protocols
+#### Protocols
 
-* service discovery
+Communication between Speedrun and Portals is performed via [dRPC](https://github.com/storj/drpc), a lightweight, drop-in replacement for gRPC. All dRPC interactions travel on top of TLS1.3 and can be mutually authenticated ([mTLS](https://en.wikipedia.org/wiki/Mutual_authentication)).
 
-* language definition [expr/Language-Definition.md at master · antonmedv/expr · GitHub](https://github.com/antonmedv/expr/blob/master/docs/Language-Definition.md)
+#### Language Definition
+Speedrun supports a flexible yet simple expression language to filter Service Discovery results, it's based on [antonmedv/expr](https://github.com/antonmedv/expr). Full language definition can be found [here](https://github.com/antonmedv/expr/blob/master/docs/Language-Definition.md).
+
+#### Plugins
+TODO
 
 ## Examples
 
@@ -88,9 +107,26 @@ speedrun run whoami -c /path/to/config.toml
 Instead of supplying certain flags repeatedly you can persist their behavior in the config file. Default config file is located at `~/.speedrun/config.toml` and default settings can be fetched via `speedrun init --print`.
 
 #### Run portal as a systemd unit
+TODO
 
 #### Use self signed certificates during testing
+In the [scripts](scripts/) folder you can find scripts that will help you generate:
+* a CA cert/key
+* Speedrun cert/key
+* Portal cert/key
 
+TODO
+
+## List of built-in Actions
+* [x] run: run arbitrary shell commands
+* [X] service: control systemd services
+* [ ] file: perform file operations such as read or tail
+* [ ] disk: perform storage operations such as listing partitions and available disk space
+* [ ] ps: fetch process information
+* [ ] top: fetch or stream high level system stats
+* [ ] pkg: manage packages via default package manager
+* [ ] system: host control operations such as reboot, shutdown etc.
+...
 ## Contributing
 
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
@@ -101,7 +137,7 @@ This project is in a very early stage so expect a lot of breaking changes in the
 
 ## Community & Support
 
-Join the [#Speedrun](https://discord.gg/nkVvPnRvrJ) channel on Discord to chat and ask questions 😃
+Join the [Speedrun Slack](https://join.slack.com/t/slack-w9m7528/shared_invite/zt-11lyemhxe-EdWi0zqh0rIEYc85mKI6_g) and ask questions 😃
 
 ## License
 
diff --git a/assets/architecture-overview.png b/assets/architecture-overview.png
new file mode 100644
index 0000000..16efe1b
Binary files /dev/null and b/assets/architecture-overview.png differ
diff --git a/assets/service-discovery-sequence.png b/assets/service-discovery-sequence.png
new file mode 100644
index 0000000..c5cb4de
Binary files /dev/null and b/assets/service-discovery-sequence.png differ