diff --git a/README.md b/README.md
index fe895c18e..679bcf1fd 100644
--- a/README.md
+++ b/README.md
@@ -1,69 +1,89 @@
-# Quay - container image registry
+# quay
 
-`master` branch build status: ![Docker Repository on Quay](https://quay.io/repository/quay/quay/status?token=7bffbc13-8bb0-4fb4-8a70-684a0cf485d3 "Docker Repository on Quay")
+![Docker Repository on Quay](https://quay.io/repository/quay/quay/status?token=7bffbc13-8bb0-4fb4-8a70-684a0cf485d3 "Docker Repository on Quay")
 
-Quay is a container image registry with managements APIs, a Docker registry API, a container build system.
-The application is implemented as a set of API endpoints written in python and an Angular.js frontend.
+**Note**: The `master` branch may be in an *unstable or even broken state* during development.
+Please use [releases] instead of the `master` branch in order to get stable binaries.
 
-## Setup Development Environment
+![Quay Logo](static/img/Quay_horizontal_color.svg)
 
-If you are doing local development on your workstation against the code base follow these instructions.
+Quay is project to build, store, and distribute container images.
 
-### Docker
+High-level features include:
 
-Quay and its parts can run inside of docker containers.
-This method requires no installation of any python packages on your host machine.
-The `local-docker.sh` script is provided to prepare and run parts of quay.
-First, start redis:
+- Docker Registry Protocol [v1], [v2.1]
+- [AppC Image Discovery]
+- Authentication provided by [LDAP], [Keystone], [Dex], [Google], [GitHub]
+- ACLs, team management, and auditability logs
+- Geo-replicated storage provided by local filesystems, [S3], [GCS], [Swift], [Ceph]
+- Continuous Integration integrated with [GitHub], [Bitbucket], [GitLab], and [git]
+- Security Vulnerability Analysis via [Clair]
+- [Swagger]-compliant HTTP API
 
+[releases]: https://github.com/coreos-inc/quay/releases
+[v1]: https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-1.md
+[v2.1]: https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-2.md
+[AppC Image Discovery]: https://github.com/appc/spec/blob/master/spec/discovery.md
+[LDAP]: https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol
+[Keystone]: http://docs.openstack.org/developer/keystone
+[Dex]: https://github.com/coreos/dex
+[Google]: https://developers.google.com/identity/sign-in/web/sign-in
+[GitHub]: https://developer.github.com/v3/oauth
+[S3]: https://aws.amazon.com/s3
+[GCS]: https://cloud.google.com/storage
+[Swift]: http://swift.openstack.org
+[Ceph]: http://docs.ceph.com/docs/master/radosgw/config
+[GitHub]: https://github.com
+[Bitbucket]: https://bitbucket.com
+[GitLab]: https://gitlab.com
+[git]: https://git-scm.com
+[Clair]: https://github.com/coreos/clair
+[Swagger]: http://swagger.io
+
+## Getting Started
+
+### macOS
+
+macOS developers will need:
+
+* [command line tools] or [xcode]
+* [brew]
+* [Docker For Mac] or [Docker Machine]
+* [pyenv] with [pyenv-virtualenv]
+
+[command line tools]: https://developer.apple.com/downloads
+[xcode]: https://developer.apple.com/downloads
+[brew]: https://github.com/Homebrew/brew
+[Docker For Mac]: https://beta.docker.com/docs/mac/getting-started://beta.docker.com/docs/mac/getting-started
+[Docker Machine]: https://docs.docker.com/machine/install-machine://docs.docker.com/machine/install-machine
+[pyenv]: https://github.com/yyuu/pyenv
+[pyenv-virtualenv]: https://github.com/yyuu/pyenv-virtualenv
 
 ```
-docker run -d -p 6379:6379 redis
-```
+# Download the code
+git clone git@github.com:coreos-inc/quay.git && cd quay
 
-And clone the configuration repo:
+# Install the system dependencies
+brew install libevent libmagic postgresql gpgme
 
-```
+# Some installs don't have /usr/include, required for finding SASL header files
+if [ ! -e /usr/include ]; then sudo ln -s `xcrun --show-sdk-path`/usr/include /usr/include; fi
+
+# Install the Python dependencies
+pyenv virtualenv 2.7.11 quay
+pyenv activate quay
+pip install -r requirements.txt
+pip install -r requirements-dev.txt
+
+# Setup a local config
 git clone git@github.com:coreos-inc/quay-config.git ../quay-config
 ln -s ../../quay-config/local conf/stack
 ```
 
-To build and run a docker container, pass one argument to local-docker.sh:
-
-- `dev`: run quay on port 5000
-- `buildman`: run the buildmanager
-- `notifications`: run the notification worker
-- `test`: run the unit tests
-- `initdb`: clear and initialize the test database
-
-For example:
-
-```
-./local-docker.sh dev
-````
-
-will start quay in a docker container.
-Now quay will be running on: http://127.0.0.1:5000
-The username is `devtable` and the password is `password`.
-
-### OS X
-
-```
-git clone git@github.com:coreos-inc/quay.git
-cd quay
-./contrib/osx/local-setup.sh
-```
-
-Now run the server; it will use sqlite as the SQL server.
-
-```
-./local-run.sh
-```
-
-Now quay will be running on: http://127.0.0.1:5000
-The username is `devtable` and the password is `password`.
+#### clang errors
 
 Some packages may fail to build with clang (which now defaults to C11).
+
 They can be installed with C99 with:
 
 ```
@@ -72,24 +92,68 @@ CFLAGS='-std=c99' pip install --no-cache --no-binary :all: cffi
 CFLAGS='-std=c99' pip install --no-cache --no-binary :all: cryptography
 ```
 
-## Update Requirements
+### Linux
 
-1. Create a new virtualenv 
-2. Activate new virtualenv
-3. Install unversioned dependencies 
-4. Run tests 
-5. Freeze requirements 
-6. Deactivate virtualenv 
-7. Remove virtualenv 
+TODO
 
-Example (commands may differ dependending on virtualenv tools):
+## Running and Testing
+
+### Test Data
+
+A SQLite database full of test data is committed to this git repository.
+This database is generated by executing `python initdb.py`.
+The username and password of the admin account is `devtable` and `password`, respectively.
+
+### Local Scripts
+
+* `local-run` runs the web server for testing
+* `local-test` runs the unit test suite
+
+### Development inside Docker
+
+To build and run a development container, pass one argument to local-docker.sh:
+
+- `buildman`: run the buildmanager
+- `dev`: run web server on port 5000
+- `initdb`: clear and initialize the test database
+- `notifications`: run the notification worker
+- `test`: run the unit test suite
+
+### Adding a Python Dependency
 
 ```
+# Create a new virtualenv and activate it
 pyenv virtualenv 2.7.11 quay-deps
 pyenv activate quay-deps
+
+# Install unversioned dependencies with your changes
 pip install -r requirements-nover.txt
+
+# Run the unit test suite
 ./local-test.sh
+
+# Freeze the versions of all of the dependencies
 pip freeze > requirements.txt
-pyenv deactivate quay-deps
-pyenv uninstall quay-deps
 ```
+
+### Running the Build System
+
+TODO
+
+```
+# Run an instance of redis
+docker run -d -p 6379:6379 quay.io/quay/redis
+```
+
+## Documentation
+
+* [Quay Enterprise Documentation](https://tectonic.com/quay-enterprise/docs/latest)
+* [Quay.io Documentation](https://docs.quay.io)
+
+### Architecture at a Glance
+
+TODO
+
+### Terminology
+
+TODO
diff --git a/contrib/osx/local-setup.sh b/contrib/osx/local-setup.sh
deleted file mode 100755
index 3ce6735c0..000000000
--- a/contrib/osx/local-setup.sh
+++ /dev/null
@@ -1,23 +0,0 @@
-#!/bin/bash
-
-# Put us at the root of the quay repo no matter what
-pushd $(dirname "${0}") > /dev/null
-basedir=$(pwd -L)
-cd "${basedir}"/../../
-
-# Install Docker and C libraries on which Python libraries are dependent
-brew update
-brew upgrade
-brew install boot2docker docker libevent libmagic postgresql gpgme
-
-# Some OSX installs don't have /usr/include, which is required for finding SASL headers for our LDAP library
-if [ ! -e /usr/include ]; then
-    sudo ln -s `xcrun --show-sdk-path`/usr/include /usr/include
-fi
-
-# Install Python dependencies
-sudo pip install -r requirements.txt
-
-# Put the local testing config in place
-git clone git@github.com:coreos-inc/quay-config.git ../quay-config
-ln -s ../../quay-config/local conf/stack