diff --git a/README.md b/README.md
new file mode 100644
index 0000000..790aeb2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,16 @@
+# Sample Dynamic Menu
+
+This repository is for configuration of the sample dynamic menu web app.
+
+There are two parts to the dynamic menu:
+
+* The menu items with actions, stored in a menu tree.
+* Entitlements (a.k.a. authorisations) to those menu items by fictitous persons and organisations.
+
+## Menu items
+
+If you have edit access you can change the menu items.  See [menu](menu/) README
+
+## Entitlements
+
+If you have edit access you can change the entitlements to menu items.  See [entitlements](entitlements/) README
diff --git a/entitlements/README.md b/entitlements/README.md
new file mode 100644
index 0000000..29a6ab9
--- /dev/null
+++ b/entitlements/README.md
@@ -0,0 +1,16 @@
+# Entitlements
+
+The entitlements are stored in files which
+are processed by the server based controller, which returns
+the list of entitled menus to the web browser which then
+displays them according to its style.
+
+## Self Serve
+
+If you edit the [sample/allow_selfserve_etal.txt](sample/allow_selfserve_etal.txt) file, you 
+can see the changes in the web side after update / refresh immeditaley.
+
+The changes you can do are:
+
+* add a new function id
+* remove a function id
diff --git a/menu/README.md b/menu/README.md
new file mode 100644
index 0000000..e69de29