diff --git a/README.md b/README.md
index 2d93340..94c4f94 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Glide: The Lightweight Vendor Package Manager
+# Glide: Vendor Package Management for Golang
 
 *Manage your vendor and vendored packages with ease.* Glide is a tool for
 managing the `vendor` directory within a Go package. This feature, first
@@ -13,9 +13,8 @@
 
 * Ease dependency management
 * Support **versioning packages** including [Semantic Versioning
-  2.0.0](http://semver.org/) support. Any constraint the [`github.com/
-  Masterminds/semver`](https://github.com/Masterminds/semver) package can parse
-  can be used.
+  2.0.0](http://semver.org/) support. Any constraint the [`github.com/Masterminds/semver`](https://github.com/Masterminds/semver)
+  package can parse can be used.
 * Support **aliasing packages** (e.g. for working with github forks)
 * Remove the need for munging import statements
 * Work with all of the `go` tools
@@ -26,6 +25,8 @@
     - svn
 * Support custom local and global plugins (see docs/plugins.md)
 * Repository caching including reuse of packages in the `$GOPATH`
+* Flatten dependencies resolving version differences and avoiding the inclusion
+  of a package multiple times.
 
 ## How It Works
 
@@ -33,11 +34,11 @@
 include a version, VCS, repository location (that can be different from the
 package name), etc. When `glide up` is run it downloads the packages (or updates)
 to the `vendor` directory. It then recursively walks through the downloaded
-packages looking for those with a `glide.yaml` file that don't already have
-a `vendor` directory and installing their dependencies to their `vendor`
-directories.
+packages looking for those with a `glide.yaml` file (or Godep, gb, or GPM config
+file) that don't already have a `vendor` directory and installing their
+dependencies to their `vendor` directories.
 
- A projects is structured like this:
+A projects is structured like this:
 
 ```
 - $GOPATH/src/myProject (Your project)
@@ -141,17 +142,15 @@
 $ glide up
 ```
 
-If the dependent vendor packages listed in your `glide.yaml` file use GPM or
-Godep you can use the `--import` flag to import them. If an import occurs a
-`vendor` directory will be created in each project with with dependencies being
-imported. A `glide.yaml` file will also be created for each project.
+This will recurse over the packages looking for other projects managed by Glide,
+Godep, gb, and GPM. When one is found those packages will be installed as needed.
 
 ## glide novendor (aliased to nv)
 
 When you run commands like `go test ./...` it will iterate over all the
 subdirectories including the `vendor` directory. When you are testing your
 application you may want to test your application files without running all the
-tests of your dependencies and their dependencies. This is where the novendor
+tests of your dependencies and their dependencies. This is where the `novendor`
 command comes in. It lists all of the directories except `vendor`.
 
     $ go test $(glide novendor)
@@ -192,15 +191,36 @@
 ```
 $ glide tree
 github.com/Masterminds/glide
-	github.com/Masterminds/cookoo   (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo)
-		github.com/Masterminds/cookoo/io   (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo/io)
-	github.com/Masterminds/glide/cmd   (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/cmd)
-		github.com/Masterminds/cookoo   (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo)
-			github.com/Masterminds/cookoo/io   (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo/io)
-		github.com/Masterminds/vcs   (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
-		github.com/codegangsta/cli   (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/codegangsta/cli)
-		github.com/kylelemons/go-gypsy/yaml   (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/kylelemons/go-gypsy/yaml)
-	github.com/codegangsta/cli   (/Users/mbutcher/Code/Go/src/github.com/Masterminds/glide/vendor/github.com/codegangsta/cli)
+	github.com/Masterminds/cookoo   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo)
+		github.com/Masterminds/cookoo/io   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo/io)
+	github.com/Masterminds/glide/cmd   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/cmd)
+		github.com/Masterminds/cookoo   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo)
+			github.com/Masterminds/cookoo/io   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo/io)
+		github.com/Masterminds/glide/gb   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/gb)
+		github.com/Masterminds/glide/util   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/util)
+			github.com/Masterminds/vcs   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+		github.com/Masterminds/glide/yaml   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/yaml)
+			github.com/Masterminds/glide/util   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/util)
+				github.com/Masterminds/vcs   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+			github.com/Masterminds/vcs   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+			gopkg.in/yaml.v2   (/Users/mfarina/Code/go/src/gopkg.in/yaml.v2)
+		github.com/Masterminds/semver   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/semver)
+		github.com/Masterminds/vcs   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+		github.com/codegangsta/cli   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/codegangsta/cli)
+	github.com/codegangsta/cli   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/codegangsta/cli)
+	github.com/Masterminds/cookoo   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo)
+		github.com/Masterminds/cookoo/io   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/cookoo/io)
+	github.com/Masterminds/glide/gb   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/gb)
+	github.com/Masterminds/glide/util   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/util)
+		github.com/Masterminds/vcs   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+	github.com/Masterminds/glide/yaml   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/yaml)
+		github.com/Masterminds/glide/util   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/util)
+			github.com/Masterminds/vcs   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+		github.com/Masterminds/vcs   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+		gopkg.in/yaml.v2   (/Users/mfarina/Code/go/src/gopkg.in/yaml.v2)
+	github.com/Masterminds/semver   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/semver)
+	github.com/Masterminds/vcs   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/Masterminds/vcs)
+	github.com/codegangsta/cli   (/Users/mfarina/Code/go/src/github.com/Masterminds/glide/vendor/github.com/codegangsta/cli)
 ```
 
 This shows a tree of imports, excluding core libraries. Because
@@ -215,16 +235,20 @@
 
 ```
 $ glide list
-github.com/Masterminds/cookoo (Present: yes)
-github.com/Masterminds/cookoo/io (Present: yes)
-github.com/Masterminds/glide/cmd (Present: yes)
-github.com/Masterminds/vcs (Present: yes)
-github.com/codegangsta/cli (Present: yes)
-github.com/kylelemons/go-gypsy/yaml (Present: yes)
+github.com/Masterminds/cookoo (Location: vendored)
+github.com/Masterminds/cookoo/io (Location: vendored)
+github.com/Masterminds/glide/cmd (Location: gopath)
+github.com/Masterminds/glide/gb (Location: gopath)
+github.com/Masterminds/glide/util (Location: gopath)
+github.com/Masterminds/glide/yaml (Location: gopath)
+github.com/Masterminds/semver (Location: vendored)
+github.com/Masterminds/vcs (Location: vendored)
+github.com/codegangsta/cli (Location: vendored)
+gopkg.in/yaml.v2 (Location: vendored)
 ```
 
-If it finds a reference to a package that has not been installed,
-`Present` is set to `no`.
+The possible locations for `list` are `vendored`, `gopath`, and `missing` (if
+the package is not installed anywhere accessible).
 
 ### glide help
 
@@ -240,7 +264,7 @@
 
 ```
 $ glide --version
-glide version 0.5.0
+glide version 0.7.0
 ```
 
 ### glide.yaml
@@ -255,10 +279,10 @@
 ```yaml
 package: github.com/Masterminds/glide
 import:
-  - package: github.com/kylelemons/go-gypsy
+  - package: github.com/Masterminds/semver
   - package: github.com/Masterminds/cookoo
     vcs: git
-    version: master
+    version: ^1.2.0
     repo: git@github.com:Masterminds/cookoo.git
 ```
 
@@ -272,9 +296,9 @@
 the fully qualified import path.
 
 When Glide reads the definition for the second library, it will get the repo
-from the source in `repo`, checkout the master branch, and put it in
-`github.com/Masterminds/cookoo` in the `vendor` directory. (Note that `package`
-and `repo` can be completely different)
+from the source in `repo`, checkout the latest version between 1.2.0 and 2.0.0,
+and put it in `github.com/Masterminds/cookoo` in the `vendor` directory. (Note
+that `package` and `repo` can be completely different)
 
 **TIP:** The version is either VCS dependent and can be anything that can be checked
 out or a semantic version constraint that can be parsed by the [`github.com/
@@ -322,30 +346,28 @@
 
 ## Troubleshooting
 
-**Q: bzr (or hg) is not working the way I expected. Why?**
+#### Q: bzr (or hg) is not working the way I expected. Why?
 
 These are works in progress, and may need some additional tuning. Please
 take a look at the [vcs package](https://github.com/masterminds/vcs). If you
 see a better way to handle it please let us know.
 
-**Q: Should I check `vendor/` into version control?**
+#### Q: Should I check `vendor/` into version control?
 
 That's up to you. It's not necessary, but it may also cause you extra
-work and lots of extra space in your VCS.
+work and lots of extra space in your VCS. There may also be unforeseen errors
+([see an example](https://github.com/mattfarina/golang-broken-vendor)).
 
-**Q: How do I import settings from GPM or Godep?**
+#### Q: How do I import settings from GPM, Godep, or gb?
 
-There are two ways to approach importing. The first is when you use `glide up`
-or `glide get` there is an `--import` flag. It will attempt to import from GPM
-and Godep automatically. If fetching is happening recursively this will be
-applied to recursive packages as well.
+There are two parts to importing.
 
-Alternatively, Glide can import from GPM's `Godeps` file format or from Godep's
-`Godeps/Godeps.json` file format with the `import` command.
-
-For GPM, use `glide import gpm`.
-
-For Godep, use `glide import godep`.
+1. If a package you import has configuration for GPM, Godep, or gb Glide will
+   recursively install the dependencies automatically.
+2. If you would like to import configuration from GPM, Godep, or gb to Glide see
+   the `glide import` command. For example, you can run `glide import godep` for
+   Glide to detect the projects Godep configuration and generate a `glide.yaml`
+   file for you.
 
 Each of these will merge your existing `glide.yaml` file with the
 dependencies it finds for those managers, and then emit the file as
@@ -357,7 +379,7 @@
 $ glide import godep > new-glide.yaml
 ```
 
-**Q: Can Glide fetch a package based on OS or Arch?**
+#### Q: Can Glide fetch a package based on OS or Arch?
 
 A: Yes. Using the `os` and `arch` fields on a `package`, you can specify
 which OSes and architectures the package should be fetched for. For
@@ -374,10 +396,6 @@
 
 The package will not be fetched for other architectures or OSes.
 
-**Q: How do I prevent vendored packages from importing the same package**
-
-You can use the `flatten: true` config option on the entire project or just one specific dependency.
-
 ## LICENSE
 
 This package is made available under an MIT-style license. See