README.textile in cantango-0.8.5.1 vs README.textile in cantango-0.8.6

@@ -1,13 +1,13 @@
 h1. CanTango
 
 CanTango is an advanced Access Control (permissions) system for Rails 3. It:
 
-* extends "CanCan":http://github.com/ryanb/cancan and offers a role oriented design
+* extends "CanCan":http://github.com/ryanb/cancan and offers a more role oriented design
 * integrates with _role_ and _authentication_ systems in a non-intrusive manner
-* can _cache_ rules between requests for increased performance
-* can _store_ rules in a permission store, including a YAML file, for easy administration
+* can _cache_ ability rules between requests for increased performance
+* can _store_ abilites in a permission store, including a YAML file, for easy administration
 * works well with multiple user accounts and sub applications
 * supports multiple "Devise":https://github.com/plataformatec/devise users
 
 h3. Will CanTango meet my Access Control (permission) requirements?
 
@@ -35,19 +35,19 @@
 
 @$ bundle@
 
 h2. Update Sept 1, 2011
 
-Version *0.8.5* has been released.
+Version *0.8.5.1* has been released.
 
-CanTango now supports "sugar-high 0.6":https://github.com/kristianmandrup/sugar-high.git' where "sweetloader":https://github.com/kristianmandrup/sweet_loader.git' has been extracted into its own gem.
+CanTango now:
 
-* The Cache has been refactored
-* Engines are now run in correct order (and only if active)
-* The Cache Kompiler (for dynamic rules caching) and Moneta cache are now optional (via adapters)
-* Permits are found and loaded via pre-registratio via the @#inherited@ method for the base permits. You can also use the _tango_permit_ macro.
-* Better visibility of the @Ability@ flow, to allow one to see which rules are triggered by which permits (likely via a special :debug config mode, since it would affect performance).
+* supports "sugar-high 0.6":https://github.com/kristianmandrup/sugar-high.
+* The ability cache has been refactored
+* Activated engines are now run in specified order
+* The ability cache rules compiler (for dynamic rules caching) and Moneta cache/store are now optional (enabled via adapters)
+* Permits are found and loaded using pre-registration via inheritance. You can also use the _tango_permit_ macro for more control.
 
 The wiki will soon be updated to reflect these improvements and changes.
 
 h2. Quickstart
 
@@ -71,34 +71,65 @@
 
 h3. Rails 3 configuration
 
 The CanTango "Configuration":https://github.com/kristianmandrup/cantango/wiki/Configuration consists of a nice DSL that let's you configure most of the things we imagine you would want to customize. Feel free to suggest more configuration options!
 
-h3. Access Control via Permits and Permissions
+h3. Abilities via Permits and Permissions
 
-AC rules can be defined in both:
+Abilities are Access Control rules. With CanTango, these can be defined in both:
 
 * "Permissions":https://github.com/kristianmandrup/cantango/wiki/Permissions (fx a yaml file)
 * "Permits":https://github.com/kristianmandrup/cantango/wiki/Permits (special classes)
 
-AC rules can be defined for the following conceptual entities:
+Note: For the simplest cases, you can define a @#permit_rules@ instance method directly in _CanTango::Ability_
 
+Abilities can be defined for the following conceptual entities:
+
 * User models
 * User Account models
 * Roles
 * Role groups
 * Users
 
+h3. Debugging Abilities and Permits
+
+Each Permit is in effect an Ability on its own. This lets you easily investigate which Permits allowed or denied a certain action for a specific ability candidate (typically a user or user account). 
+
+Debugging Example:
+
+<pre>
+# First you must enable debug mode
+CanTango.debug!
+
+# And have the permit engine execute at least once
+user_can? :read, Article
+
+# Then you can debug the permits execution
+CanTango.permits_allowed current_user, :read, Article
+
+admin_can? :read, Article
+CanTango.permits_denied admin_user, :publish, [Article, Post]
+CanTango.permits_allowed admin_user, :write, Article
+
+CanTango.clear_executed_permits! # reset as if no permits have been executed
+
+user_can? :publish, Article
+CanTango.permits_denied current_user, [:write, publish], [Article, Post]
+
+guest_account_can? :publish, Article
+CanTango.permits_denied guest_account, :publish, [Article, Post], options
+</pre>
+
 h3. Design overview
 
-The default CanTango ability pattern is simple.
+The default CanTango Ability pattern is simple.
 
-1. Return cached rules for ability candidate if available
+1. Return cached ability rules for candidate if available
 2. Generate rules for candidate
 3. Cache rules for candidate
 
-An ability candidate is typically either a user or an account instance.
+A candidate is typically either a user or an account instance.
 
 Caching can be enabled or disabled. To generate the rules, one or more engines are executed.
 
 CanTango comes with the following engines:
 
@@ -139,21 +170,11 @@
   (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
 h2. Contributors
 
-*Kristian Mandrup*
-- Main architect
-- Designer of structure
-- Feature ideas
-- Initiator of project
-- Devise app integration specs
-
-"Stanislaw Pankevich":https://github.com/stanislaw
-- Main contributor of permissions engine
-- Caching of Procs for caching engine
-- Lots of bug fixes and specs
-- Tireless "worker" ;)
+* Kristian Mandrup
+* "Stanislaw Pankevich":https://github.com/stanislaw
 
 h3. Copyright
 
 Copyright (c) 2010 Kristian Mandrup. See LICENSE for details.