working on docs..

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

README.md

@@ -13,17 +13,17 @@ Actions are an extension to the JavaScript object model tailored for
 a set of specific tasks.
 
 
-### Goals:
+#### Goals:
 - Provide a unified mechanism to define and manage user API's for 
   use in UI-hooks, keyboard mappings, scripting, ... etc.
 - A means to generate configuration UI's
 - A means to generate documentation
 
 
-### Restrictions:
+#### Restrictions:
 - **No method shadowing**  
   The _extending_ action can not "shadow" the _extended_ action in a 
-  non destructive manner (e.g. via a throw), all actions in a chain are 
+  non destructive manner (e.g. via a `throw`), all actions in a chain are 
   guaranteed to be called, unless a fatal error condition.
 - **No argument shadowing**  
   The _extending_ has access to all the arguments that the user passed
@@ -31,13 +31,18 @@ a set of specific tasks.
   them.
 - **No return shadowing**  
   The _extending_ action can not replace the object returned by the 
-  _extended_ action, though it can _coopiratively_ update/modify it if 
+  _extended_ action, though it can _cooperatively_ update/modify it if 
   needed
 - **Single return point**
   Only the _root_ action can return a value, any other returns by 
   _extending_ actions are ignored
 - The default return value is `this`
 
+By design this tool-set promotes a _cooperative_ design and makes it
+hard to change/modify existing signatures / _contracts_ in _extending_ 
+code.
+
+
 
 ### The main entities: