README.md in kindergarten-0.1.1 vs README.md in kindergarten-0.2.0

@@ -4,10 +4,32 @@
 
 [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/coffeeaddict/kindergarten)
 
 A way to achieve modularity and modular security with a sandbox on steroids.
 
+## Introduction
+
+### Modules
+A Kindergarten could be seen as collection of service objects, each
+representing a 'play area' (think: doll area, lego table, etc. etc.).
+
+Within the realm of kindergarten, the service objects are refered to as
+modules.
+
+### Sandboxing
+The modules are plugged into the kindergarten and can be governed, both per
+module and kindergarten wide. There are governesses looking for, and preventing
+trouble.
+
+Each module is not just exposed as-is; it is sandboxed. Which means that they
+must specify which methods are to be played with.
+
+### Child
+What good would a kindergarten with a sandbox full of toys be without a child?
+In a Rails context; the most logical choise for a child would be
+the ```current_user```.
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
     gem 'kindergarten'
@@ -21,58 +43,70 @@
     $ gem install kindergarten
 
 ## Usage
 
 ```ruby
-# define a child
-child = User.find(2)
+  # define a child
+  child = User.find(2)
 
-# define a module (perimeter) for the child to play in
-class MyPlayModule < Kindergarten::Perimeter
-  # use can-can rules to govern the perimeter
-  govern do
-    can :watch, Television
-    cannot :watch, CableTV
+  # define a module (perimeter) for the child to play in
+  class MyPlayModule < Kindergarten::Perimeter
+    # every module must have a purpose.
+    # The purpose also serves as a namespace
+    #
+    purpose :playing
 
-    can :eat, Candy do |candy|
-      child.quotum.allows(candy)
+    # use can-can rules to govern the perimeter
+    govern do
+      can :watch, Television
+      cannot :watch, CableTV
+
+      can :eat, Candy do |candy|
+        child.quotum.allows(candy)
+      end
     end
-  end
 
-  # define methods for the sandbox
-  sandbox :watch_tv, :eat
+    # define exposed methods
+    expose :watch_tv, :eat
 
-  def watch_tv(tv)
-    guard(:watch, tv)
-    child.watch(tv)
+    def watch_tv(tv)
+      guard(:watch, tv)
+      child.watch(tv)
 
-    sleep(:four)
-  end
+      sleep(:four)
+    end
 
-  def eat(candy)
-    guard(:eat, candy)
-    child.eat(candy)
-  end
+    def eat(candy)
+      guard(:eat, candy)
+      child.eat(candy)
+    end
 
-  def sleep(len) # not_accessible_from_outside
-    child.sleep(len)
+    def sleep(len) # not_accessible_from_outside
+      child.sleep(len)
+    end
+
+    # or expose methods in an 'annotation like way'
+
+    expose :method
+    # method that does nothing at all
+    def method
+    end
   end
-end
 
-# load the child and the module into a sandbox
-sandbox = Kindergarten.sandbox(child)
-sandbox.load_module(MyPlayPerimeter)
+  # load the child (any object) and the module into a sandbox
+  sandbox = Kindergarten.sandbox(child)
+  sandbox.load_module(MyPlayPerimeter)
 
-# you can now call the sandboxed methods on the sandbox
-sandbox.watch_tv(CableTV.new)  # fails with Kindergarten::AccessDenied
-30.times do
-  sandbox.eat(Liquorice.new)   # fails after a while
-end
+  # you can now call the sandboxed methods on the sandbox
+  sandbox.playing.watch_tv(CableTV.new)   # fails with Kindergarten::AccessDenied
+  30.times do
+    sandbox.playing.eat(Liquorice.new)    # fails after a while
+  end
 
-sandbox.sleep(:long)           # fails with NoMethodError
+  sandbox.playing.sleep(:long)            # fails with NoMethodError
 
-sandbox.allowed?(:watch, Television)
-# => true
+  sandbox.allows?(:watch, Television)
+  # => true
 ```
 
 You are not restricted to only one perimeter/module - that would be most
 boring...