diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # goggles
 
-<img src="goggles1.png" style="width: 300px;"/>
+<img src="https://raw.githubusercontent.com/ocramz/goggles/master/goggles1.png" width="300" >
 
 [![Build Status](https://travis-ci.org/ocramz/goggles.png)](https://travis-ci.org/ocramz/goggles)
 
diff --git a/goggles.cabal b/goggles.cabal
--- a/goggles.cabal
+++ b/goggles.cabal
@@ -1,5 +1,5 @@
 name:                goggles
-version:             0.1.0.1
+version:             0.1.0.2
 synopsis:            Interface to Google Cloud APIs
 description:         High-level, extensible interface to Google Cloud APIs. 
 homepage:            https://github.com/ocramz/goggles
diff --git a/src/Network/Goggles.hs b/src/Network/Goggles.hs
--- a/src/Network/Goggles.hs
+++ b/src/Network/Goggles.hs
@@ -1,17 +1,55 @@
+{-| This module is the entry point to the @goggles@ library, which is a Haskell interface to the cloud services hosted by Google (e.g. storage, compute, mail, etc.: <https://cloud.google.com/>) .
+
+Most Google Cloud Platform (GCP) functionality requires authentication, which must be obtained beforehand from the website either with a free trial or a paid plan.
+
+From now on, we'll assume the user has such credentials and is able to load them alongside this library.
+
+The examples require the following declarations (which in turn mean that the @req@ and @bytestring@ libraries are imported by the user's project):
+
+> {-# language OverloadedStrings #-}
+>
+> import qualified Data.ByteString.Lazy as LB
+> import Network.HTTP.Req (responseBody)
+> import Network.Goggles
+
+== /Examples/
+
+This first example, @listBucket@, reads content from a cloud storage bucket:
+
+1. it loads the GCP credentials (username and RSA key),
+2. retrieves a token via OAuth2,
+3. performs a single call to the Cloud Storage API endpoint that lists the metadata related to the contents of a storage bucket, and
+4. returns the raw API data to the user as a lazy ByteString.
+
+> listBucket :: IO LB.ByteString
+> listBucket = do
+>   let usr = "...iam.gserviceaccount.com"
+>       bucket = "<my-gcs-bucket>"
+>       key = "<rsa_key>"
+>   pvtkey <- parseRSAPrivateKey key
+>   let creds = GCPServiceAccount pvtkey usr Nothing ""
+>   hdl <- createHandle creds scopesDefault
+>   responseBody <$> evalCloudIO hdl (listObjects bucket)
+
+
+-}
 module Network.Goggles (
-  -- * Google Cloud Storage
+  -- * API endpoints
+  -- ** Google Cloud Storage
     getObject
   , listObjects
   , putObject
   -- ** GCP Authentication scopes
   , scopesDefault
   -- ** Running Cloud programs
+  , createHandle    
   , evalCloudIO
+  -- *** Executing IO actions within 'Cloud'
   , liftCloudIO
-  , createHandle  
   -- * Types
   , GCP
   , GCPServiceAccount(..)
+  , GCPTokenOptions(..)
   , Cloud(..)
   -- ** Authentication
   , HasCredentials(..)
diff --git a/src/Network/Goggles/Cloud.hs b/src/Network/Goggles/Cloud.hs
--- a/src/Network/Goggles/Cloud.hs
+++ b/src/Network/Goggles/Cloud.hs
@@ -27,18 +27,24 @@
 import Network.Goggles.Control.Exceptions
 
 
+-- | This class 
 class HasCredentials c where
   type Credentials c
   type Options c
   type TokenContent c 
   tokenFetch :: Cloud c (Token c)
 
--- | A 'Token' with an expiry date
+-- | An authentication 'Token' with an expiry date
 data Token c = Token {
     tToken :: TokenContent c
   , tTime :: UTCTime
   }
 
+-- | A 'Handle' contains all information necessary to communicating with a cloud API provider:
+--
+-- * Authentication credentials (e.g. username/password)
+-- * Authentication token (used to authenticate every API call)
+-- * Options (e.g. GCP authentication scopes)
 data Handle c = Handle {
       credentials :: Credentials c
     , token :: TVar (Maybe (Token c))