Add more information to readme

README.md

@@ -9,7 +9,7 @@ Managing aliases can be tedius and difficult to set up. `nostromo` makes this pr
 
 `nostromo` can potentially help you build complex tools in a declarative way. Tools commonly allow you to run multi-level commands like `git rebase master branch` or `docker rmi b750fe78269d` which seem clear to use. Imagine if you could wrap your aliases / commands / workflow into custom commands that describe things you do often.
 
-With `nostromo` you can take some aliases like these:
+With `nostromo` you can take aliases like these:
 ```sh
 alias ios-build='pushd $IOS_REPO_PATH;xcodebuild -workspace Foo.xcworkspace -scheme foo_scheme'
 alias ios-test='pushd $IOS_REPO_PATH;xcodebuild -workspace Foo.xcworkspace -scheme foo_test_scheme'
@@ -52,12 +52,75 @@ nostromo manifest init
 ## Usage
 
 ### Managing Aliases
+Aliases is one of the core functionalities provided by `nostromo`. Instead of constantly updating shell profiles manually, `nostromo` will automatically keep it updated with the latest additions. **Note** that commands won't take affect until you open a new shell or `source` your `.bash_profile` again.
+
+To add an alias (or command in `nostromo` parlance), simply run:
+```sh
+nostromo add cmd foo "echo doo"
+```
+Re-source your `.bash_profile` and just like that you can run `foo` like any other alias.
+
+#### Keypaths
+`nostromo` uses the concept of keypaths to simplify building commands and accessing the command tree. A keypath is simply a `.` delimited string that represents the path to the command.
+
+For example:
+```sh
+nostromo add cmd foo.bar.baz "echo hello"
+```
+will build the command tree for `foo` -> `bar` -> `baz` such that any of these commands are now valid:
+```sh
+foo
+foo bar
+foo bar baz
+```
+where the last one will actually execute the `echo` command.
+
+This is also how you can compose further commands by adding a **real** command to `foo.bar` for example that will get prepended for commands below that scope.
 
 ### Scoped Commands & Substitutions
+Scope affects a tree of commands such that a parent scope is executed first and then each command in the keypath. If a command is run as follows:
+```sh
+foo bar baz
+```
+and the command associated with `foo` runs first, then `bar`, and finally `baz`. So if these commands were configured like this:
+```sh
+nostromo add cmd foo "echo oof"
+nostromo add cmd foo.bar "rab"
+nostromo add cmd foo.bar.baz "zab"
+```
+then the actual execution would yield:
+```sh
+oof rab zab
+```
+
+`nostromo` also provides the ability to add substitutions at each one of these scopes in the command tree. So if want to shorten common strings that are otherwise long into substitutions you can attach them to a parent scope and `nostromo` will replace them at execution time for all instances.
+
+A substitution can be added with:
+```sh
+nostromo add foo.bar sub //some/long/string sls
+```
+Subsequent calls to `foo bar` would replace the subs before running. This command:
+```sh
+foo bar baz sls
+```
+would finally run the following since the substitution is in scope:
+```sh
+oof rab zab //some/long/string
+```
 
 ### Complex Command Tree
+Given features like **keypaths** and **scope** you can build a complex set of commands and effectively your own tool that performs additive functionality with each command node.
+
+You can get a quick snapshot of the command tree using:
+```sh
+nostromo manifest show
+```
 
 ### Bash Completion
+`nostromo` provides bash completion scripts to allow tab completion. You can get this by adding this to your shell init file:
+```sh
+eval "$(nostromo completion)"
+```
 
 ## Credits