diff --git a/composer.json b/composer.json
index 2dcd69fd71..78f99cda27 100644
--- a/composer.json
+++ b/composer.json
@@ -31,7 +31,7 @@
     "consolidation/annotated-command": "^2.8.1",
     "consolidation/config": "^1.0.9",
     "consolidation/output-formatters": "^3.1.12",
-    "consolidation/site-alias": "^0.1",
+    "consolidation/site-alias": "^1",
     "consolidation/robo": "^1.1.5",
     "grasmash/yaml-expander": "^1.1.1",
     "league/container": "~2",
diff --git a/examples/example.site.yml b/examples/example.site.yml
index 815b5974f4..69bafdc034 100644
--- a/examples/example.site.yml
+++ b/examples/example.site.yml
@@ -71,8 +71,30 @@
 #       - /etc/drush/sites
 # @endcode
 #
-# If you run the command `drush core:init`, this configuration will
-# be done for you automatically.
+# It is also possible to create a named location that contains a group
+# of related site aliases. For example, if you had a number of sites
+# for local schools, you could define a location named "schools":
+#
+# @code
+# drush:
+#   paths:
+#     alias-path:
+#       - '${env.home}/.drush/sites/schools'
+# @endcode
+#
+# Site aliases stored in this directory may then be referenced by its
+# full alias name, including its location, e.g.:
+#
+#   $ drush @schools.example.dev
+#
+# Such alias files may still be referenced by their shorter name, e.g.
+# `@example.dev`. Note that it is necessary to individually list every
+# location where site alias files may be stored; Drush never does recursive
+# (deep) directory searches for alias files.
+#
+# The command `drush core:init` will automatically configure your
+# ~/.drush/drush.yml configuration file to add `~/.drush/sites` and
+# `/etc/drush/sites` as locations where alias files may be placed.
 #
 # Files stored in one of the search path locations can be used to create
 # aliases to local and remote Drupal installations.  These aliases can be
@@ -85,6 +107,18 @@
 #
 #   $ drush site:alias @self
 #
+# The `site:alias` command may also be used to list all of the sites and
+# environments in a given location, e.g.:
+#
+#   $ drush site:alias @schools
+#
+# Or it may be used to list all of the environments in a given site:
+#
+#   $ drush site:alias @example
+#
+# If called without any parameters, it will list all of the sites and
+# environments in all locations.
+#
 # Drush also supports *remote* site aliases.  When a site alias is
 # defined for a remote site, Drush will use the ssh command to run
 # the requested command on the remote machine.  The simplest remote
diff --git a/isolation/tests/SiteAliasFileLoaderTest.php b/isolation/tests/SiteAliasFileLoaderTest.php
index a5f3df1a2c..bd0ff9d9db 100644
--- a/isolation/tests/SiteAliasFileLoaderTest.php
+++ b/isolation/tests/SiteAliasFileLoaderTest.php
@@ -100,6 +100,6 @@ public function testLoadAll()
         $this->sut->addSearchLocation($this->fixturesDir() . '/sitealiases/single');
 
         $all = $this->sut->loadAll();
-        $this->assertEquals('@single.alternate,@single.common,@single.dev', implode(',', array_keys($all)));
+        $this->assertEquals('@single.single.alternate,@single.single.common,@single.single.dev', implode(',', array_keys($all)));
     }
 }
diff --git a/tests/SiteAliasConvertTest.php b/tests/SiteAliasConvertTest.php
index d060416e24..1b925766d0 100644
--- a/tests/SiteAliasConvertTest.php
+++ b/tests/SiteAliasConvertTest.php
@@ -25,10 +25,11 @@ public function testSiteAliasConvert()
         file_put_contents(Path::join(self::getSandbox(), 'etc/drush/drush.yml'), Yaml::dump($config, 3));
 
         $this->drush('site:alias', [], ['format' => 'json']);
+        // $this->assertEquals('', $this->getOutput());
         $json = $this->getOutputFromJSON();
-        $this->assertObjectHasAttribute('@drupalvm.dev', $json);
-        $this->assertObjectHasAttribute('@www-drupalvm.dev', $json);
-        $dev = $json->{'@drupalvm.dev'};
+        $this->assertObjectHasAttribute('@testSiteAliasConvert.drupalvm.dev', $json);
+        $this->assertObjectHasAttribute('@testSiteAliasConvert.www-drupalvm.dev', $json);
+        $dev = $json->{'@testSiteAliasConvert.drupalvm.dev'};
         $this->assertSame('drupalvm.dev', $dev->host);
         $this->assertSame('-o PasswordAuthentication=no -i /.vagrant.d/insecure_private_key', $dev->ssh->{'options'});
         $this->assertSame('/var/www/drupalvm/drupal/vendor/drush/drush/drush', $dev->paths->{'drush-script'});