README.md in rzo-0.3.0 vs README.md in rzo-0.4.0

@@ -2,10 +2,16 @@
 
 Rizzo is a heavily customized Vagrant configuration and work flow with a
 role based focus. It is meant to make working with Vagrant easier and
 purpose built for layered Puppet control repositories.
 
+Rizzo loads a personal configuration file, `~/.rizzo.json` by default, which
+lists one or more control repositories.  Rizzo then looks for a loads a
+`.rizzo.json` configuration file located at the root of the top level control
+repository.  The top level control repository is the first listed in
+the array of control repositories in the personal configuration file.
+
 There should be at least one node for every role that is managed by a
 control repo. This information is stored in `.rizzo.json` under the
 control repo. This makes it apparent what roles are available and aids
 in functional testing.
 
@@ -88,18 +94,23 @@
 
 # Setup
 
 ## `~/.rizzo.json`
 
-Change the paths to your git repos
+The personal configuration file is loaded first from `~/.rizzo.json` by default.
+The global `--config` option allows the end user to specific a different path to
+the personal configuration file.
 
+Using this example, change the paths to your git repos:
+
 ```json
 {
   "defaults": {
     "bootstrap_repo_path": "/Users/gh/git/bootstrap"
   },
   "control_repos": [
+    "/Users/gh/git/puppet-control-myteam",
     "/Users/gh/git/puppetdata",
     "/Users/gh/git/puppet-modules"
   ],
   "puppetmaster": {
     "name": "infra-puppetca",
@@ -122,15 +133,20 @@
     }
   }
 }
 ```
 
-Once you have `~/.rizzo.json`, change to your top level control repository and generate your `Vagrantfile`.
+Once you have a personal config file, `~/.rizzo.json`, change directories to
+your top level control repository and generate your `Vagrantfile`:
 
 ```shell
+cd ~/git/puppet-control-myteam
 bundle exec rizzo generate
 ```
+
+Expected output:
+
 ```
 Wrote vagrant config to Vagrantfile
 ```
 
 Once the `Vagrantfile` has been generated, interact with the roles using `vagrant status`.
@@ -153,11 +169,11 @@
 ## Configuration Specification
 
 ### defaults
 
 The defaults hash is merged with each node entries hash. Put user
-specific entries in `~/.rizzo.json` and project specific entries in
-`${PATH_TO_CONTROL_REPO}/.rizzo.json`.
+specific entries in the personal configuration file at `~/.rizzo.json` and
+control repo specific entries in `${PATH_TO_CONTROL_REPO}/.rizzo.json`.
 
 ### control_repos
 
 The control_repos array is a list of control repos. Rizzo takes the
 approach that control repos are layered. The ordering should match your