diff --git a/README.md b/README.md
new file mode 100644
--- /dev/null
+++ b/README.md
@@ -0,0 +1,66 @@
+# libnix
+
+Haskell bindings to the [nix package manager][nix]
+
+This project aims to provide an interface to call [nix][nix] functionality from
+the safe haven that is Haskell. As much type safety as possible should be
+guaranteed to the user.
+
+The project consists of two broad steps:
+
+1. bindings to the command line tools
+2. bindings to the nix libraries themselves
+
+At the moment, an beta version of 1. is implemented, together with a small
+number of tests to check for possible changes in the interface,
+which consists mainly of three functions:
+
+```haskell
+parseNixExpr :: Text                 -> NixAction ParseError NixExpr
+instantiate  :: NixExpr              -> NixAction InstantiateError (StorePath Derivation)
+realize      :: StorePath Derivation -> NixAction RealizeError (StorePath Realized)
+```
+
+which do what you’d expect; and two helper functions
+
+```haskell
+eval             :: NixExpr -> NixAction InstantiateError ()
+parseInstRealize :: Text    -> NixAction NixError (StorePath Realized)
+```
+
+where `parseInstRealize` performs all three steps at once.
+
+[nix]: https://github.com/NixOS/nix
+
+
+## Nix Prefetch Wrappers
+
+We implement an additional module that creates nicely typed wrappers
+for `nix-prefetch-X` tools, please see the module documentation what
+is supported exactly.
+
+```haskell
+url :: UrlOptions -> NixAction PrefetchError (Sha256, StorePath Realized)
+git :: GitOptions -> NixAction PrefetchError GitOutput
+```
+
+
+## C++ bindings
+
+The second steps would be to directly bind into the C++ library. That could
+either mean writing a C wrapper and using Haskell’s native FFI, or generating
+bindings with [Hoppy][hoppy], which we’d prefer. Hoppy would need to be able to
+[handle C++ exceptions][exc] first, though.
+
+[hoppy]: http://khumba.net/projects/hoppy/
+[exc]: https://gitlab.com/khumba/hoppy/issues/10
+
+## Other nix libraries on hackage
+
+- [cabal2nix](https://hackage.haskell.org/package/cabal2nix): the executable at the base of nix haskell support
+- [language-nix](https://hackage.haskell.org/package/language-nix): library cabal2nix uses to generate its nix files
+- [hnix](https://hackage.haskell.org/package/hnix): a project to implement the nix expression language in haskell
+- [nix-eval](https://hackage.haskell.org/package/nix-eval): runtime eval of Haskell code using nix
+- [simple-nix](https://hackage.haskell.org/package/simple-nix): looks like a nix parser, but not entirely sure
+
+It doesn’t look like the scope of libnix collides with any of these packages.
diff --git a/libnix.cabal b/libnix.cabal
--- a/libnix.cabal
+++ b/libnix.cabal
@@ -1,19 +1,25 @@
--- Initial libnix.cabal generated by cabal init.  For further 
--- documentation, see http://haskell.org/cabal/users-guide/
-
 name:                libnix
-version:             0.2.0.0
+version:             0.2.0.1
 synopsis:            Bindings to the nix package manager
--- description:       
+description:         Use the nix package manager from Haskell. All modules are designed to be imported qualified.
+category:            Foreign, Nix
+homepage:            https://github.com/Profpatsch/libnix-haskell#readme
+bug-reports:         https://github.com/Profpatsch/libnix-haskell/issues
 license:             GPL-3
 license-file:        LICENSE
 author:              Profpatsch
 maintainer:          mail@profpatsch.de
--- copyright:           
-category:            Foreign, Nix
 build-type:          Simple
--- extra-source-files:  
 cabal-version:       >=1.10
+
+extra-source-files:  
+   LICENSE
+   README.md
+   shell.nix
+   
+source-repository head
+  type: git
+  location: https://github.com/Profpatsch/libnix-haskell
 
 library
   exposed-modules:     Foreign.Nix.Shellout
diff --git a/shell.nix b/shell.nix
new file mode 100644
--- /dev/null
+++ b/shell.nix
@@ -0,0 +1,33 @@
+((import <nixpkgs> {}).haskellPackages.override {
+  overrides = self:
+    super:
+      {
+        my-pkg = let
+          buildDepends = with self;
+          [
+            aeson
+            errors
+            filepath
+            protolude
+            tasty
+            tasty-hunit
+          ];
+        in super.mkDerivation {
+          pname = "pkg-env";
+          src = "/dev/null";
+          version = "none";
+          license = "none";
+          inherit buildDepends;
+          buildTools = with self;
+          [
+            ghcid
+            cabal-install
+            hpack
+            hscolour
+            (hoogleLocal {
+              packages = buildDepends;
+            })
+          ];
+        };
+      };
+}).my-pkg.env