From c9a45e033b3d469790c771ad2df30cd2fa10ef0f Mon Sep 17 00:00:00 2001
From: "Alex A. Naanou" <alex.nanou@gmail.com>
Date: Tue, 23 Aug 2016 18:04:43 +0300
Subject: [PATCH] working on docs..

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
---
 README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 47 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index b25ae42..d161f0f 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,42 @@
 # Features / Actions
 
+The Feature / Action couple is meta-programming library that helps with:
+- extending and calling methods (Actions) on object inheritance chains
+- managing and applying sets of methods (Features) to objects (a-la _mixin_)
+
+
+
 
 ## Actions
 
 Actions are an extension to the JavaScript object model tailored for
 a set of specific tasks.
 
+
 ### Goals:
-- provide a unified mechanism to define and manage user API's for 
+- 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
+- A means to generate configuration UI's
+- A means to generate documentation
+
+
+### 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 
+  guaranteed to be called, unless a fatal error condition.
+- **No argument shadowing**  
+  The _extending_ has access to all the arguments that the user passed
+  but can not modify or reformat them before the _extended_ action gets
+  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 
+  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`
 
 
 ### The main entities:
@@ -237,8 +263,26 @@ Root Action                             o---|---x
 		an overhead on all the actions if not done carefully.
 
 
+
 ## Features
 
+Features is a module that helps build _features_ out of sets of actions
+and manage sets of features according to external criteria and 
+feature-feature dependencies.
+
+### Goals:
+
+XXX
+
+### The main entities:
+
+**Feature**
+
+XXX
+
+
+**FeatureSet (Features)**
+
 XXX