README.md in config_curator-0.2.1 vs README.md in config_curator-0.2.2

@@ -11,12 +11,198 @@
 
 _Simple and intelligent configuration file management._
 
 ## Description
 
+Config Curator is a flexible configuration and dotfile manager.
+Simply define what to manage in `manifest.yml`,
+then run `curate` to install and update your **configuration units**.
+
+Currently, Config Curator supports installing
+directories, files, and symbolic links.
+It also handles setting other properties such as
+permissions and ownership.
+Additionally, configuration units can be installed per-host
+or only if certain packages are installed.
+
+Config Curator is written to be extensible:
+each type of configuration unit,
+e.g., file, directory, symbolic link, etc.,
+is actually a subclass of the more generic `Unit` type.
+Other types can be added simply by adding more subclasses.
+
+## Usage
+
+### The `manifest.yml` file
+
+The `manifest.yml` file is a YAML file that defines
+the configuration units to install.
+
+Each key is either a global setting, `default`,
+or a unit type: `components`, `config_files`, or `symlinks`.
+
+#### Settings
+
+Optional global Config Curator settings.
+Defaults listed below.
+
+````yaml
+# All units installed relative to the root.
+root: "~/"
+
+# Package tool to use.
+# Will automatically detect if not explicitly set.
+# Available tools: pacman, dpkg, pkgng.
+package_tool:
+````
+
+#### `defaults`
+
+Optional key that sets the default attribute values for each unit.
+
+Any per-unit attribute will override the value here.
+
+Any attribute not set here will use
+the Config Curator defined defaults below.
+
+````yaml
+defaults:
+  # File and directory permissions.
+  # Empty values will not change permissions.
+  fmode:
+  dmode:
+
+  # File and directory owner and group.
+  # Empty values will not change ownership.
+  owner:
+  group:
+
+  # Hosts to install this unit on.
+  # Empty array will install on all hosts.
+  hosts: []
+
+  # Only install this unit if packages are present.
+  # Empty array will not check for any packages.
+  packages: []
+````
+
+#### Units
+
+Each unit must have a `src` which defines the source file or directory.
+
+You may give a `dst` to override the install location.
+Otherwise the destination will mimic the source path relative to the `root` path.
+This is required for symlinks.
+
+You can define an array of `hosts` to control what hostnames the unit will install on.
+Similarly you can give a list of packages that must be present to install the unit.
+You can also use any other attribute in the `defaults` key listed in the previous section.
+
+Best to see some examples.
+Note in the examples below how some units are installed from the `bower_components` directory:
+external configuration is thus managed as a Bower dependency and installed using `curate`.
+You can always visit [my dotfiles for a real-world example](https://github.com/razor-x/dotfiles).
+
+##### Components are entire directories
+
+Components are installed before other units.
+
+The source will be mirrored to the destination.
+**Any existing files in the destination will be lost.**
+
+````yaml
+components:
+  - src: .config/terminator
+
+  - src: bower_components/tmuxinator-profiles
+    dst: .tmuxinator
+    fmode: 640
+    dmode: 0750
+    packages: [ tmux ]
+````
+
+##### Config files are copied individually
+
+Files are installed after components.
+
+Subdirectories are created as needed.
+
+In this example, the files `.tmux.conf` and `.tmux.baz.conf` both exist:
+the first will be installed on hosts `foo` and `bar`,
+while the second will be installed on host `baz`.
+
+````yaml
+config_files:
+  - src: .gitconfig
+  - src: .bundle/config
+
+  - src: bower_components/ssh-config/config
+    dst: .ssh/config
+    fmode: 600
+    dmode: 0700
+
+  - src: .tmux.conf
+    hosts: [ foo, bar, baz ]
+````
+
+##### Symlinks
+
+Symlinks create a symbolic link to the `src` at the `dst`.
+
+They are installed last.
+
+````yaml
+symlinks:
+  - src: ~/Wallpaper/tux.png
+    dst: .config/awesome/wall.png
+    packages: [ awesome ]
+````
+
+### The `curate` command
+
+Once you have prepared your manifest, simply run
+
+````bash
+$ curate
+````
+
+Or if you prefer more verbose feedback
+
+````bash
+$ curate -v
+````
+
+You can always get help with
+
+```
+$ curate help
+
+Commands:
+  curate help [COMMAND]  # Describe available commands or one specific command
+  curate install         # Installs all units in collection.
+
+Options:
+  v, [--verbose], [--no-verbose]
+  q, [--quiet], [--no-quiet]
+      [--debug], [--no-debug]
+```
+
+### Scripting
+
+Config Curator is fully scriptable for easy inclusion into other Ruby programs.
+The API is well documented for this purpose
+(see [Documentation](#documentation) above).
+
 ## Installation
 
+You can install the gem either with Bundler or directly.
+Bundler is preferred, however the direct method may be convenient
+when initially bootstrapping a system with an initial configuration.
+
+The recommend setup is to check your configuration
+along with `manifest.yml` into version control.
+
 Add this line to your application's Gemfile:
 
 ````ruby
 gem 'config_curator'
 ````
@@ -39,17 +225,9 @@
 
 YARD documentation for all gem versions is hosted on the
 [Config Curator gem page](https://rubygems.org/gems/config_curator).
 Documentation for the latest commits is hosted on
 [the RubyDoc.info project page](http://rubydoc.info/github/razor-x/config_curator/frames).
-
-## Usage
-
-### Scripting
-
-Config Curator is fully scriptable for easy inclusion into other Ruby programs.
-The API is well documented for this purpose
-(see [Documentation](#documentation) above).
 
 ## Development and Testing
 
 ### Source Code