diff --git a/README.md b/README.md
index 25a649f..086a759 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,15 @@ Haskell SDK for the Microsoft APIs:
 | Azure | [![Hackage](https://img.shields.io/hackage/v/ms-azure-api?style=for-the-badge)](https://hackage.haskell.org/package/ms-azure-api) |
 
 
+## Introduction
 
+We provide separate libraries for authentication (`ms-auth`), Graph (`ms-graph-api`) and Azure (`ms-azure-api`) since they cater to different use cases; they are designed to work together at any rate. 
+
+In the majority of cases a user will want to install `ms-auth` as well as the API binding they need (unsure whether Azure or Graph allow anonymous usage of any of their endpoints).
+
+## Examples
+
+* OAuth flow : see `ms-graph-api-test/app/Main.hs` 
 
 ## Status
 
@@ -24,6 +32,7 @@ Some breaking changes might also be introduced as the library matures.
 
 We adhere to a simplified version of the [Package Versioning Policy](https://pvp.haskell.org/): breaking changes are signaled by increasing the major version number (e.g. 0.x -> 1.x ).
 
+Significant changes in the SDK will be documented in the respective CHANGELOG.
 
 ## LICENSE
 
diff --git a/ms-auth/ms-auth.cabal b/ms-auth/ms-auth.cabal
index d9d7089..039dd9b 100644
--- a/ms-auth/ms-auth.cabal
+++ b/ms-auth/ms-auth.cabal
@@ -2,7 +2,7 @@ name:                ms-auth
 version:             0.2.0.0
 synopsis:            Microsoft Authentication API
 description:         Bindings to the Microsoft Identity API / Active Directory (AD) for building applications that use either Delegated or App-only permissions. Helper functions are provided for building OAuth2 authentication flows and keep tokens transactionally secure and up to date.
-homepage:            https://github.com/unfoldml/ms-auth
+homepage:            https://github.com/unfoldml/ms-api
 license:             BSD3
 license-file:        LICENSE
 author:              Marco Zocca
diff --git a/ms-azure-api/ms-azure-api.cabal b/ms-azure-api/ms-azure-api.cabal
index aefc77a..d4ef1d7 100644
--- a/ms-azure-api/ms-azure-api.cabal
+++ b/ms-azure-api/ms-azure-api.cabal
@@ -1,8 +1,8 @@
 name:                ms-azure-api
 version:             0.1.0.0
--- synopsis:
--- description:
-homepage:            https://github.com/unfoldml/ms-azure-api
+synopsis:            Microsoft Azure API
+description:         Bindings to the Microsoft Azure API
+homepage:            https://github.com/unfoldml/ms-api
 license:             BSD3
 license-file:        LICENSE
 author:              Marco Zocca
diff --git a/ms-graph-api/ms-graph-api.cabal b/ms-graph-api/ms-graph-api.cabal
index bb0598a..fd18160 100644
--- a/ms-graph-api/ms-graph-api.cabal
+++ b/ms-graph-api/ms-graph-api.cabal
@@ -2,7 +2,7 @@ name:                ms-graph-api
 version:             1.0.0.0
 synopsis:            Microsoft Graph API
 description:         Bindings to the Microsoft Graph API
-homepage:            https://github.com/unfoldml/ms-graph-api
+homepage:            https://github.com/unfoldml/ms-api
 license:             BSD3
 license-file:        LICENSE
 author:              Marco Zocca