README.md in chef-helpers-0.0.6 vs README.md in chef-helpers-0.0.7

@@ -2,29 +2,81 @@
 
 This gem includes miscellaneous add-on helper methods for Opscode Chef.
 
 ## Installation
 
-To use helper methods in your Chef recipes, add `chef_gem
-'chef-helpers'` and `require 'chef-helpers'` in your recipes.
+To use helper methods in your Chef recipes, use following code in your
+recipe:
 
-To use methods locally in `knife exec` scripts or Knife plugins, add
-this line to your application's Gemfile:
+```ruby
+chef_gem 'chef-helpers'
+require 'chef-helpers'
+```
 
-    gem 'chef-helpers'
+To use the helpers locally in `knife exec` scripts or Knife plugins,
+just add the `chef-helpers` gem to your dependencies and `require 'chef-helpers'`.
 
-And then execute:
+## Usage
 
-    $ bundle
+Detailed documentation of the helper methods can be seen at
+http://rdoc.info/github/3ofcoins/chef-helpers/
 
-Or install it yourself as:
+### Finding existing templates and cookbook files
 
-    $ gem install chef-helpers
+The recipe DSL is extended with `ChefHelpers::HasSource` module that
+provides methods for checking which templates and cookbook files exist
+on the Chef server. Detailed docs are available at
+http://rdoc.info/github/3ofcoins/chef-helpers/ChefHelpers/HasSource
 
-## Usage
+### Chef::Node#allies
 
-Detailed documentation of the helper methods can be seen at
-http://rdoc.info/github/3ofcoins/chef-helpers/
+The `node.allies` method returns an array of node's *allies*.  These
+are: all nodes in the same environment (if the environment is not
+`_default`), plus nodes specified by `allies` attribute. The `allies`
+attribute - if set - should be an array of node names or node search
+queries; the named nodes and search results will be added to node's
+allies.
+
+This is mostly useful when defining firewall or other access rules, to
+easily limit access to insides of a cluster plus a handful of friendly
+machines.
+
+### Chef::Node#ip_for
+
+The `node.ip_for(other_node)` method decides, which IP address should
+the node use to contact the other node, and returns this IP as a
+string. It is particularly useful when your setup spans across cloud
+availability zones or different providers. At the moment only EC2 and
+nodes with public `ipaddress` are supported; suggestions are welcome.
+
+If both nodes are on EC2 and in the same region, then other node's
+`ec2.local_ipv4` attribute is used. Otherwise, if other node is a
+cloud instance, its `cloud_public.ipv4` attribute is used. Otherwise,
+other node's `ipaddress` is used.
+
+### JSONPath access to attributes
+
+The `Chef::Node` class is monkey-patched to allow easy deep access to
+the attributes using the
+[JSONPath](http://goessner.net/articles/JsonPath/) syntax:
+
+```
+chef > require 'chef-helpers'
+ => true 
+chef > node['$..name']
+ => ["portinari-2.local", "Java(TM) SE Runtime Environment", "Java HotSpot(TM) 64-Bit Server VM", "Darwin"] 
+chef > node['$.kernel.name']
+ => ["Darwin"] 
+```
+
+Regular access to attributes is preserved; JSONPath is used only when
+the attribute name starts with `$` character, or if a `JSONPath`
+instance is used for indexing.
+
+The [jsonpath gem](https://github.com/joshbuddy/jsonpath) is used for
+the implementation. While the original gem allows modification, it's
+not straightforward to achieve with Chef's attributes, so only reading
+attributes with JSONPath is supported.
 
 ## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)