README.md in cogy-0.1.1 vs README.md in cogy-0.2.0

@@ -99,25 +99,36 @@
 ## Usage
 
 Defining a new command:
 
 ```ruby
-# in cogy/commands.rb
+# in cogy/my_commands.rb
 
 on "foo", desc: "Echo a bar" do
   "bar"
 end
 ```
 
-This will print "bar" back to the user who calls `!foo` in Slack, for example.
+This will print "bar" back to the user who calls `!foo` in Slack.
 
+Let's define a command that simply adds the numbers passed as arguments:
+
+```ruby
+# in cogy/calculations.rb
+
+on "add", args: [:a, :b], desc: "Add two numbers" do
+  a.to_i + b.to_i
+end
+```
+
 Inside the block there are the following pre-defined helpers available:
 
-* `#args`: an array containing the arguments passed to the command
-* `#opts`: a hash containing the options passed to the command
-* `#handle`: the chat handle of the user who called the command
-* `#env`: a hash containing the Cogy environment, that is, every environment variable
+* `args`: an array containing the arguments passed to the command
+  * arguments can also be accessed by their names as local variables
+* `opts`: a hash containing the options passed to the command
+* `handle`: the chat handle of the user who called the command
+* `env`: a hash containing the Cogy environment, that is, every environment variable
   starting with 'COGY_' and set in the Relay
 
 For instructions on defining your own helpers, see [Helpers](#helpers).
 
 A more complete example:
@@ -135,47 +146,125 @@
 end
 ```
 
 For more examples see the [test commands](https://github.com/skroutz/cogy/tree/master/test/dummy/cogy).
 
+### Returning JSON to Cog
 
+You can return JSON to Cog by just returning a `Hash`:
+
+```ruby
+on "foo", desc: "Just a JSON" do
+  { a: 3 }
+end
+```
+
+The hash automatically gets converted to JSON by Cogy. The above command would return the following response to Cog:
+
+```
+COG_TEMPLATE: foo
+JSON
+{"a":3}
+```
+
+To customize the Cog [template](#Templates) to be used, pass the `template` option:
+
+```ruby
+on "foo", desc: "Just a JSON", template: "bar" do
+  { a: 3 }
+end
+```
+
+Info on how Cog handles JSON can be found in the [official documentation](https://cog-book.operable.io/#_returning_data_from_cog).
+
+### Templates
+
+Templates are defined in their own files under `templates/` inside any of
+the [command load paths](#Configuration). For example:
+
+```
+$ tree
+.
+├── README.rdoc
+├── <..>
+├── cogy
+│   ├── some_commands.rb
+│   └── templates
+│       └── foo # <--- a template named 'foo'
+|── <...>
+```
+
+Given the following template:
+
+```
+# in cogy/templates/foo
+~ hello world ~
+```
+
+the resulting bundle config would look like this:
+
+```yaml
+---
+cog_bundle_version: 4
+name: foo
+description: The bundle you really need
+version: 0.0.1
+commands:
+  <...>
+templates:
+  foo:
+    body: |-
+      ~ hello world ~
+```
+
+Refer to the [Cog book](https://cog-book.operable.io/#_templates) for more on
+templates.
+
 ## Configuration
 
 The configuration options provided are the following:
 
 ```ruby
 # in config/initializers/cogy.rb
 
 Cogy.configure do |config|
-  # Used in the generated bundle config YAML.
-  #
-  # Default: "cogy"
-  config.bundle_name = "myapp"
+  # Configuration related to the generated Cog bundle. Will be used when
+  # generating the bundle config YAML to be installed.
+  config.bundle = {
+    # The bundle name.
+    #
+    # Default: "cogy"
+    name: "myapp",
 
-  # Used in the generated bundle config YAML.
-  #
-  # Default: "Cogy-generated commands"
-  config.bundle_description = "myapp-generated commands from Cogy"
+    # The bundle description
+    #
+    # Default: "Cog commands generated from Cogy"
+    description: "myapp-generated commands from Cogy",
 
-  # Can be either a string or an object that responds to `#call` and returns
-  # a string.
-  config.bundle_version = "0.0.1"
+    # The bundle version.
+    #
+    # Can be either a string or an object that responds to `#call` and returns
+    # a string.
+    #
+    # Default: "0.0.1"
+    version: "0.0.1",
 
-  # if you used a callable object, it will be evaluated each time the inventory
-  # is called. This can be useful if you want the version to change dynamically
-  # when it's needed.
-  #
-  # For example, this will change the version only when a command is
-  # added or is modified (uses the 'grit' gem).
-  config.bundle_version = -> {
-    repo = Grit::Repo.new(Rails.root.to_s)
-    repo.log("HEAD", "cogy/", max_count: 1).first.date.strftime("%y%m%d.%H%M%S")
+    # if you used a callable object, it will be evaluated each time the inventory
+    # is called. This can be useful if you want the version to change
+    # automatically.
+    #
+    # For example, this will change the version only when a command is
+    # added or is modified (uses the 'grit' gem).
+    version: -> {
+      repo = Grit::Repo.new(Rails.root.to_s)
+      repo.log("HEAD", "cogy/", max_count: 1).first.date.strftime("%y%m%d.%H%M%S")
+    },
+
+    # The path in the Relay where the cogy command executable is located.
+    cogy_executable: "/cogcmd/cogy"
   }
 
-  # The path in the Relay where the cogy command executable is located at.
-  config.executable_path = "/cogcmd/cogy"
-
   # Paths in your application where the files that define the commands live in.
   # For example the default value will search for all `*.rb` files in the `cogy/`
   # directory relative to the root of your application.
   #
   # Default: ["cogy"]
@@ -245,9 +334,54 @@
     <%= @exception.class %>:<%= @exception.message %>
     ```
 
 It can be overriden in the application by creating a view in
 `app/views/cogy/error.text.erb`.
+
+## Deployment
+
+Cogy provides the `cogy:notify_cog` task for Capistrano. The following options
+need to be set:
+
+* `cogy_release_trigger_url`: This is the URL of the Cog Trigger that will
+  install the newly deployed bundle (ie. `!cogy:install`).
+* `cogy_endpoint`: Where the Cogy Engine is mounted at.
+  For example `http://myapp.com/cogy`.
+
+You can also configure the timeout value for the request to the Trigger by
+setting the `cogy_trigger_timeout` option (default: 7).
+
+The task can be found [here](https://github.com/skroutz/cogy/blob/master/lib/cogy/capistrano/cogy.rake).
+
+### Capistrano 2
+
+Add the following in `config/deploy.rb`:
+
+```ruby
+# in config/deploy.rb
+require "cogy/capistrano"
+
+set :cogy_release_trigger_url, "<TRIGGER-INVOCATION-URL>"
+set :cogy_endpoint, "<COGY-MOUNT-POINT>"
+```
+
+The `cogy:notify_cog` task is automatically hooked after `deploy:restart`.
+
+### Capistrano 3
+
+Add the following in your Capfile:
+
+```ruby
+require "cogy/capistrano"
+```
+
+The `cogy:notify_cog` task should be manually hooked after the task that
+restarts the application. For example:
+
+```ruby
+# in config/deploy.rb
+after "deploy:restart_app", "cogy:notify_cog"
+```
 
 ## Development
 
 Running the tests and RuboCop: