working on docs...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>

README.md

@@ -10,9 +10,13 @@ The Feature / Action couple is meta-programming library that helps with:
 Actions are an extension to the JavaScript object model tailored for
 a set of specific tasks.
 
-By design this tool-set promotes a _cooperative_ model and makes it
-hard to change/modify existing signatures / _contracts_ in _extending_ 
-code.
+To distinguish this from the native JavaScript elements we introduce new
+terminology, an _action_ is an extended _method_ while an _action set_ is
+a _mixin object_ (stateless, including only functionality) both usable 
+stand-alone as well as _mixed_ into other objects.
+
+Here is a trivial use-case to illustrate the motivation for this tool set:
+
 
 #### The problem:
 
@@ -64,6 +68,7 @@ abstract this...
 
 #### The solution:
 
+
 ```javascript
 var N = Actions({
   times: [function(n){
@@ -104,8 +109,6 @@ n
 - _and more... (see below)_
 
 
-
-
 ### What we get:
 - **Call parent (_extended_) actions automatically**  
   All actions (methods) in a chain are guaranteed to get called if the 
@@ -146,6 +149,11 @@ n
   _(this is not final)_
 
 
+**Notes:**
+- By design this tool-set promotes a _cooperative_ model and makes it
+  hard to change/modify existing signatures / _contracts_ in _extending_ 
+  code, hence the restrictions.
+
 
 ### The main entities: