Finish merge and recover README

README.rst

@@ -1,44 +1,134 @@
-Welcome to *Kapow!*
+.. image:: https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/f51eb40412bf09c8c800511d7bbe5634/kapow-1601675_480.png
-===================
+    :alt: Kapow!
+
+.. image:: https://circleci.com/gh/BBVA/kapow/tree/master.svg?style=svg
+    :target: https://circleci.com/gh/BBVA/kapow/tree/master
 
 .. image:: https://goreportcard.com/badge/github.com/bbva/kapow
     :target: https://goreportcard.com/report/github.com/bbva/kapow
     
-
+**Kapow!** If you can script it, you can HTTP it.
-With *Kapow!* you can publish simple **shell scripts** as **HTTP services** easily.
-
-*Kapow!* with an example
-------------------------
-
-**Goal**
-
-We want users on the Internet to be able to ``ping`` an *Internal Host*
-which is inside a private network.
-
-.. image:: https://github.com/BBVA/kapow/raw/feature-new-doc/docs/source/_static/network.png
-
-**Limitations**
-
-- We can't allow users to log into any host. 
-
-- We need to have full control over the precise command is run as
-  well as the parameters used.
-
-**Solution**
-
-With a *Kapow!* one-liner you can allow your users to run a command inside
-*External Host* through an HTTP call.
-
-.. image:: https://github.com/BBVA/kapow/raw/feature-new-doc/docs/source/_static/sequence.png
-
-This is the only line you'll need:
-
-.. code-block:: bash
-
-   $ kapow route add /ping -c 'ping -c1 10.10.10.100 | kapow set /response/body'
 
 
-.. todo::
+CAVEAT EMPTOR
+=============
 
-   Mention license and contributing
+**Warning!!! Kapow!** is under **heavy development** and `specification </spec>`_;
+the provided code is a Proof of Concept and the final version will not even
+share programming language.  Ye be warned.
 
+
+What is it?
+===========
+
+Kapow! is an adapter between the world of Pure UNIX® Shell and a HTTP service.
+
+Some tasks are more convenient in the shell, like cloud interactions, or some
+administrative tools.  On the other hand, some tasks are more convenient as a
+service, like DevSecOps tooling.
+
+Kapow! lies between these two worlds, making your life easier.  Maybe you wonder
+about how this kind of magic can happen; if you want to know the nitty-gritty
+details, just read our `specification </spec>`_;.  Or, if you want to know how
+Kapow! can help you first, let's start with a common situation.
+
+Think about that awesome command that you use every day, something very
+familiar, like ``cloudx storage ls /backups``.  Then someone asks you for an
+specific backup, so you ``ssh`` into the host, execute your command, possibly
+``grepping`` through its output, copy the result and send it back to him.
+And that's fine... for the 100 first times.
+
+Then you decide, let's use an API for this and generate an awesome web server
+with it.  So, you create a project, manage its dependencies, code the server,
+parse the request, learn how to use the API, call the API and deploy it
+somewhere.  And that's fine... until you find yourself again in the same
+situation with another awesome command.
+
+The awesomeness of UNIX® commands is infinite, so you'll be in this situation
+an infinite number of times!  Instead, let's put Kapow! into action.
+
+With Kapow! you just need to create a ``.pow`` file named ``backups.pow`` that
+contains:
+
+.. code-block:: sh
+
+    kapow route add /backups \
+        -c 'cloudx storage ls /backups | grep "$(kapow get /request/params/query)" | kapow set /response/body'
+
+and execute it in the remote host with the command:
+
+.. code-block:: sh
+
+    kapow server backups.pow
+
+and that's it.  Done.  You have a web server that people can use to request
+their backups every time they need only by invoking the URL
+`http://remotehost/backups?query=project`
+
+Do you like it? yes?  Then let's start learning a little more, you can access
+the `documentation </doc>`_; section to find installation instructions and some
+examples.
+
+
+
+
+
+
+
+How it was born
+---------------
+
+Some awesome history is coming.
+
+
+Kapow! for the impatient
+========================
+
+When you need to **share** a ``command`` but **not** a complete remote ``ssh
+access``, Kapow!  will help you with the power of HTTP:
+
+.. image:: https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/784a183fba3f24872dd97ee28e765922/Kapow!.png
+    :alt: Where Kapow! lives
+
+Kapow! allows you to write a litte script that will **serve an executable as REST
+service**.  This script will let you define how to connect HTTP and the  Shell
+using Kapow!'s shell abstractions to the HTTP world. See it to believe:
+
+.. image:: resources/kapow.gif?raw=true
+    :alt: Kapow! in action
+
+
+Superpowers
+-----------
+
+Kapow! gives you:
+
+* A very simple way to turn any shell **executable into an API**
+* A **remote administration** API
+* A way to define the integration in you own terms, obligations-free!
+
+
+Curses
+------
+
+Kapow! can't help when:
+-----------------------
+
+* You need high throughput: Kapow! spawns a new executable for every HTTP call
+* You must perform complex logic to attend the request: never use Kapow! if
+  your executables don't perform al least 90% of the hard work
+* You are building a huge application
+
+
+When it is your best friend:
+--------------------------
+
+* Easy command + Hard API = Kapow! to the rescue
+* SSH for one command?  Kapow! allows you to share only that command
+* Remote instrumentation of several machines?  Make it easy with Kapow!
+
+
+The more you know
+=================
+
+If you want to know more, please follow our `documentation </doc>`_.

docs/source/install.rst

@@ -1,17 +0,0 @@
-Installation
-============
-
-Precompiled Binaries
---------------------
-
-1. Get a precompiled static binary for your system from our `releases section <https://github.com/BBVA/kapow/releases/latest>`_.
-
-2. Put it in your ``$PATH`` (Linux example):
-
-   .. code-block:: bash
-
-      sudo install kapow1.0.0-rc1_linux_amd64 /usr/bin/kapow
-
-.. todo::
-
-   Describe all the options available.

docs/source/quickstart.rst

@@ -1,27 +0,0 @@
-Quickstart Guide
-================
-
-
-Hello World! -- *Kapow!* style
-------------------------------
-
-In a shell, the traditional `Hello World!` program would be ``echo "Hello World!"``.
-Let's publish it through HTTP using *Kapow!*
-
-- First you need a *script file* with the route that will publish your command, lets's call the file ``greet.sh`` and should contain the following code:
-
-.. code-block:: bash
-
-    kapow route add /greet -c 'echo "Hello World!" | kapow set /response/body'
-
-- Start the *Kapow!* server with your script as an argument
-
-.. code-block:: bash
-
-    kapow server greet.sh
-
-- Finally check that all is working as intended:
-
-.. image:: _static/browser.png
-
-

docs/source/tutorial.rst

@@ -1,28 +0,0 @@
-
-.. todo::
-
-   Redo 
-
-Hello World! -- *Kapow!* style
-------------------------------
-
-In a shell, the traditional `Hello World!` program would be ``echo "Hello World!"``.
-Let's publish it through HTTP using *Kapow!*
-
-- First you need a *script file* with the route that will publish your command, lets's call the file ``greet.sh`` and should contain the following code:
-
-.. code-block:: bash
-
-    kapow route add /greet -c 'echo "Hello World!" | kapow set /response/body'
-
-- Start the *Kapow!* server with your script as an argument
-
-.. code-block:: bash
-
-    kapow server greet.sh
-
-- Finally check that all is working as intended:
-
-.. image:: _static/browser.png
-
-