diff --git a/Readme.md b/Readme.md
index 0111a55..f761e1e 100644
--- a/Readme.md
+++ b/Readme.md
@@ -1,25 +1,43 @@
-Python Build Pack
-====================
-The Python Build Pack (PBP) is a build pack for running Python and Django
-apps on Heroku.
+Heroku buildpack: Python
+========================
 
-## Usage
+This is a [Heroku buildpack](http://devcenter.heroku.com/articles/buildpack) for Python apps.
+It uses [virtualenv](http://www.virtualenv.org/) and [pip](http://www.pip-installer.org/).
 
-If `requirements.txt` is present, the PBP considers the directory a Python app
-with packages to install via pip.
+Usage
+-----
 
-Furthermore, if `${PROJECT}/settings.py` is present, the PBP considers the
-directory a Python/Django app, and patches `settings.py` to parse the Heroku
-DATABASE_URL config vars. It then sets default process types to use the Django
-web server.
+Example usage:
 
+    $ ls
+    Procfile  requirements.txt  web.py
 
-## Hacking
+    $ heroku create --stack cedar --buildpack git@github.com:nzoschke/heroku-buildpack-python.git
 
-To change this buildpack, fork it on GitHub. Push up changes to your
-fork, then create a test app with `--buildpack YOUR_GITHUB_URL` and
-push to it. If you already have an existing app you may use
-`heroku config add BUILDPACK_URL=YOUR_GITHUB_URL` instead.
+    $ git push heroku master
+    ...
+    -----> Heroku receiving push
+    -----> Fetching custom build pack... done
+    -----> Python app detected
+    -----> Preparing virtualenv version 1.6.4
+           New python executable in ./bin/python
+           Installing setuptools............done.
+           Installing pip...............done.
+    -----> Installing dependencies using pip version 1.0.2
+           Downloading/unpacking Flask==0.7.2 (from -r requirements.txt (line 1))
+           Downloading/unpacking Werkzeug>=0.6.1 (from Flask==0.7.2->-r requirements.txt (line 1))
+           Downloading/unpacking Jinja2>=2.4 (from Flask==0.7.2->-r requirements.txt (line 1))
+           Installing collected packages: Flask, Werkzeug, Jinja2
+           Successfully installed Flask Werkzeug Jinja2
+           Cleaning up...
 
-For example, you could adapt it to use pypy at build time.... to be continued
+The buildpack will detect your app as Python if it has the file `requirements.txt` in the root. It will detect your app as Python/Django if there is an additional `settings.py` in a project subdirectory.
 
+It will use virtualenv and pip to install your dependencies, vendoring a copy of the Python runtime into your slug.  The `bin/`, `include/` and `lib/` directories will be cached between builds to allow for faster pip install time.
+
+Hacking
+-------
+
+To use this buildpack, fork it on Github.  Push up changes to your fork, then create a test app with `--buildpack <your-github-url>` and push to it.
+
+To change the vendored virtualenv, unpack the desired version to the `src/` folder, and update the virtualenv() function in `bin/compile` to prepend the virtualenv module directory to the path. The virtualenv release vendors its own versions of pip and setuptools.
diff --git a/bin/compile b/bin/compile
index 2e1cc31..f4a2072 100755
--- a/bin/compile
+++ b/bin/compile
@@ -48,7 +48,7 @@ if [ "$NAME" = "Python/Django" ]; then
 
   SETTINGS_FILE=$(ls **/settings.py | head -1)
   PROJECT=$(dirname $SETTINGS_FILE)
-  echo "       Injecting code into $SETTINGS_FILE to read from DATABASE_URL"
+  echo "Injecting code into $SETTINGS_FILE to read from DATABASE_URL" | indent
   
   cat >>$SETTINGS_FILE <<EOF
 
diff --git a/bin/detect b/bin/detect
index 37252b5..034e4c8 100755
--- a/bin/detect
+++ b/bin/detect
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# bin/name <build-dir>
+# bin/detect <build-dir>
 
 BUILD_DIR=$1
 [ -f $BUILD_DIR/requirements.txt ] || exit 1 # fail fast if no requirements.txt
diff --git a/bin/release b/bin/release
index 7c036e2..33950ac 100755
--- a/bin/release
+++ b/bin/release
@@ -1,12 +1,10 @@
 #!/usr/bin/env bash
 # bin/release <build-dir>
 
-BIN_DIR=$(dirname $0)
+BIN_DIR=$(cd $(dirname $0); pwd) # absolute path
 BUILD_DIR=$1
 NAME=$($BIN_DIR/detect $BUILD_DIR) || exit 1
 
-cd $BUILD_DIR
-
 cat <<EOF
 ---
 config_vars:
@@ -16,7 +14,7 @@ EOF
 
 [ "$NAME" = "Python/Django" ] || exit 0
 
-SETTINGS_FILE=$(ls **/settings.py | head -1)
+SETTINGS_FILE=$(ls $BUILD_DIR/**/settings.py | head -1)
 PROJECT=$(dirname $SETTINGS_FILE)
 
 cat <<EOF