diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2cf1a58
--- /dev/null
+++ b/README.md
@@ -0,0 +1,76 @@
+onf-make library makefiles
+==========================
+
+This repository contains common makefile logic and targets that can be
+used to build arbitrary repositories.  Makefile logic is currently being
+consumed by the VOLTHA project 
+
+makefiles/ subdirectories
+-------------------------
+
+Two distinct sets of makefiles are needed to support builds:
+
+- The first is a subdir of makefiles/ named 'onf-make'
+    - This directory exists and is maintained as a git-submodule
+      of [repo:onf-make](https://github.com/opencord/onf-make).
+    - Makefile directory contains independent logic to install common
+      tools such as (virtualenv), perform linting tasks, define constants
+      and perform path/string manipulation, etc.
+- The second makefile directory contains repository specific logic
+
+    - Exists as a repository subdirectory named makefiles/local/.
+    - Contains custom targets, variant parameters and custom logic
+      specific to the repository it exists within.
+
+- Most makefile logic can be parameterized and implemented to support
+  reuse.  Consider adding enhancements or refactoring local/ makefile
+  logic into [repo:onf-make](https://github.com/opencord/onf-make) so
+  all makefiles can leverage the logic.
+
+Hierarchy
+---------
+    
+    % tree --charset=ascii -n
+    
+    Makefile
+    config.mk
+    makefiles/
+    |-- include.mk
+    |-- local
+    |   |-- include.mk
+    |   |   |   |-- doc8
+    |   |   |   |    |-- doc8.ini   (alas only one --config switch allowed)
+    |-- [onf-make: git-submodule](https://github.com/opencord/onf-make)
+    |   |-- makefiles
+    |   |   |-- consts.mk
+    |   |   |-- include.mk
+    |   |   |-- lint
+    |   |   |   |-- doc8            Syntax check ReStructuredText (rst) files
+    |   |   |   |-- groovy
+    |   |   |   |-- python
+    |   |   |   |-- robot.mk        Syntax check robot testing framework
+    |   |   |   |-- shell.mk        Invoke shellcheck command on scripts
+    |   |   |   |-- yaml            Syntax check yaml configs
+  
+TODO
+====
+
+- Refactor and merge logic from available repository makefiles/ directories.
+- Update to make use of library makefiles
+
+    - [setup.sh](http://github.com/opencord/onf-make/blob/master/bin/setup.sh)
+    - {repository}/makefiles/{local, onf-make}/
+    - Create [config.mk](https://github.com/opencord/onf-make/blob/master/config.mk) to enable targets and features.
+
+- Exercise make lint targets, bulk cleanup is needed across all repositories.
+
+NOTES
+=====
+
+- Ascii art was rendered using
+
+    - tree --charset=ascii -n
+
+- README.md can be rendered locally using
+
+    - pandoc README.md | lynx -stdin
diff --git a/bin/setup.sh b/bin/setup.sh
index fbb8b99..0359907 100755
--- a/bin/setup.sh
+++ b/bin/setup.sh
@@ -1,21 +1,36 @@
 #!/bin/bash
+## -----------------------------------------------------------------------
+## Intent: This script ca
+## -----------------------------------------------------------------------
 
 set -euo pipefail
 
+[[ -d makefiles ]] || { echo "ERROR: makefiles/ not found"; exit 1; }
+
+# git rm -fr makefiles
+
 mkdir -p makefiles
 pushd makefiles || { echo "ERROR: pushd makefiles failed"; exit 1; }
 
+echo '** Adding repo:onf-make (library makefiles) as a submodule'
 git submodule add 'https://github.com/opencord/onf-make.git' onf-lib
 
+echo '** Ignore local onf-make edits'
 echo 'onf-lib' >> .gitignore
-git add .gitignore
 
 cp ../makefiles_include_mk.ex include.mk
 
+echo '** Create project specific directory makefiles/local'
 mkdir -p local
 touch local/include.mk
-git add include.mk
 
 popd || { echo "ERROR: popd makefiles failed"; exit 1; }
 
+if false; then
+    git add makefiles/.gitignore
+    git add makefiles/include.mk
+    git add makefiles/local/include.mk
+
+# git add makefiles
+
 # [EOF]
diff --git a/makefiles/README b/makefiles/README
new file mode 100644
index 0000000..694eb37
--- /dev/null
+++ b/makefiles/README
@@ -0,0 +1,32 @@
+Two distinct makefile directories are in use:
+  - Common library makefiles (onf-make/)
+  - Project specific makefile logic (local/)
+
+Makefile logic is loaded/accessed through make macros:
+    ONF_MAKEDIR=   Common makefile targets and logic
+    MAKEDIR=       Repository/project specific targets
+
+Common library targets are defined/augmented as double colon rules:
+    build clean help sterile test :: # dup targets OK
+
+    % make sterile test
+
+All other targets are defined and accessed as single colon rules:
+    repo-rule : # fail on duplicate targets
+
+
+All makefiles/ logic can be access from the top level Makefile
+==============================================================
+
+TOP ?= $(strip $(dir $(abspath $(lastword $(MAKEFILE_LIST))) ) )    
+include $(TOP)/config.mk
+include $(TOP)/makefiles/include.mk
+
+Which in turn will load onf-make/ and local/
+============================================
+include $(ONF_MAKE)/makefiles/include.mk
+include $(MAKEDIR)/makefiles/include.mk
+
+% make sterile build
+
+# [EOF]