diff --git a/README.md b/README.md
new file mode 100644
index 00000000..7d978b8a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,25 @@
+# servant
+
+[![Build Status](https://secure.travis-ci.org/haskell-servant/servant.svg)](http://travis-ci.org/haskell-servant/servant)
+
+![servant](https://raw.githubusercontent.com/haskell-servant/servant/master/servant.png)
+
+These libraries provides a family of combinators to define webservices and automatically generate the documentation and client-side querying functions for each endpoint.
+
+In order to minimize the dependencies depending on your needs, we provide these features under different packages.
+
+- `servant`, which contains everything you need to *declare* a webservice and *implement* an HTTP server with handlers for each endpoint.
+- `servant-client`, which lets you derive automatically Haskell functions that let you query each endpoint of a *servant* webservice.
+- `servant-docs`, which lets you generate API docs for your webservice.
+- `servant-jquery`, which lets you derive Javascript functions (based on jquery) to query your API's endpoints, in the same spirit as `servant-client`.
+
+## Getting started
+
+We've written a [Getting Started](http://haskell-servant.github.io/getting-started/) guide that introduces the core types and features of servant. After this article, you should be able to write your first servant webservices, learning the rest from the haddocks' examples.
+
+## Repositories and Haddocks
+
+- The core [servant](http://github.com/haskell-servant) package - [docs](http://haskell-servant.github.io/servant/)
+- (Haskell) client-side function generation with [servant-client](http://github.com/haskell-servant/servant-client) - [docs](http://haskell-servant.github.io/servant-client/)
+- (Javascript) client-side function generation with [servant-jquery](http://github.com/haskell-servant/servant-jquery) - [docs](http://haskell-servant.github.io/servant-jquery/)
+- API docs generation with [servant-docs](http://github.com/haskell-servant/servant-docs) - [docs](http://haskell-servant.github.io/servant-docs/)
diff --git a/servant.cabal b/servant.cabal
index d163c6a8..1bf80bfe 100644
--- a/servant.cabal
+++ b/servant.cabal
@@ -1,7 +1,89 @@
 name:                servant
 version:             0.2
--- synopsis:
--- description:
+synopsis:            A family of combinators for defining webservices APIs and serving them
+description:
+  A family of combinators for defining webservices APIs and serving them
+  .
+  You can learn about the basic in <http://haskell-servant.github.io/getting-started/ the getting started> guide.
+  .
+  Here's a runnable example, with comments that defines a dummy API and
+  implements a webserver that serves this API. You can find it <https://github.com/haskell-servant/servant/blob/master/example/greet.hs here> too.
+  .
+  > {-# LANGUAGE DataKinds #-}
+  > {-# LANGUAGE PolyKinds #-}
+  > {-# LANGUAGE TypeFamilies #-}
+  > {-# LANGUAGE DeriveGeneric #-}
+  > {-# LANGUAGE TypeOperators #-}
+  > {-# LANGUAGE OverloadedStrings #-}
+  >
+  > import Data.Aeson
+  > import Data.Monoid
+  > import Data.Proxy
+  > import Data.Text
+  > import GHC.Generics
+  > import Network.Wai
+  > import Network.Wai.Handler.Warp
+  >
+  > import Servant
+  >
+  > -- * Example
+  >
+  > -- | A greet message data type
+  > newtype Greet = Greet { msg :: Text }
+  >   deriving (Generic, Show)
+  >
+  > instance FromJSON Greet
+  > instance ToJSON Greet
+  >
+  > -- API specification
+  > type TestApi =
+  >        -- GET /hello/:name?capital={true, false}
+           --     returns a Greet as JSON
+  >        "hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get Greet
+  >
+  >        -- POST /greet with a Greet as JSON in the request body,
+  >        --      returns a Greet as JSON
+  >   :<|> "greet" :> ReqBody Greet :> Post Greet
+  >
+  >        -- DELETE /greet/:greetid
+  >   :<|> "greet" :> Capture "greetid" Text :> Delete
+  >
+  > testApi :: Proxy TestApi
+  > testApi = Proxy
+  >
+  > -- Server-side handlers.
+  > --
+  > -- There's one handler per endpoint, which, just like in the type
+  > -- that represents the API, are glued together using :<|>.
+  > --
+  > -- Each handler runs in the 'EitherT (Int, String) IO' monad.
+  > server :: Server TestApi
+  > server = helloH :<|> postGreetH :<|> deleteGreetH
+  >
+  >   where helloH name Nothing = helloH name (Just False)
+  >         helloH name (Just False) = return . Greet $ "Hello, " <> name
+  >         helloH name (Just True) = return . Greet . toUpper $ "Hello, " <> name
+  >
+  >         postGreetH greet = return greet
+  >
+  >         deleteGreetH _ = return ()
+  >
+  > -- Turn the server into a WAI app. 'serve' is provided by servant,
+  > -- more precisely by the Servant.Server module.
+  > test :: Application
+  > test = serve testApi server
+  >
+  > -- Run the server.
+  > --
+  > -- 'run' comes from Network.Wai.Handler.Warp
+  > runTestServer :: Port -> IO ()
+  > runTestServer port = run port test
+  >
+  > -- Put this all to work!
+  > main :: IO ()
+  > main = runTestServer 8001
+homepage:            http://haskell-servant.github.io/
+Bug-reports:         http://github.com/haskell-servant/servant/issues
 license:             BSD3
 license-file:        LICENSE
 author:              Alp Mestanogullari, Sönke Hahn, Julian K. Arni
@@ -11,6 +93,9 @@ category:            Web
 build-type:          Simple
 cabal-version:       >=1.10
 tested-with:         GHC >= 7.8
+source-repository head
+  type: git
+  location: http://github.com/haskell-servant/servant.git
 
 library
   exposed-modules:
@@ -52,12 +137,12 @@ library
     , warp
   hs-source-dirs: src
   default-language: Haskell2010
-  ghc-options: -O0 -Wall
+  ghc-options: -Wall
 
 executable greet
   main-is: greet.hs
   hs-source-dirs: example
-  ghc-options: -O0 -Wall
+  ghc-options: -Wall
   default-language: Haskell2010
   build-depends:
       base
diff --git a/servant.png b/servant.png
new file mode 100644
index 00000000..caec4f60
Binary files /dev/null and b/servant.png differ