diff --git a/README.md b/README.md
index 263ea9c..0253d22 100644
--- a/README.md
+++ b/README.md
@@ -5,11 +5,7 @@ Load environment variables at runtime from a `.env` file.
 
 [![Pub Version][pub-badge]][pub]
 [![Build Status][ci-badge]][ci]
-[![][dartdocs-badge]][dartdocs]
-
-_NB: Travis uses [`test_runner`][], which has not yet moved off `unittest`._
-
-[`test_runner`]: https://github.com/google/test_runner.dart/blob/master/pubspec.yaml
+[![Documentation][dartdocs-badge]][dartdocs]
 
 [ci-badge]: https://travis-ci.org/mockturtl/dotenv.svg?branch=master
 [ci]: https://travis-ci.org/mockturtl/dotenv
@@ -18,7 +14,13 @@ _NB: Travis uses [`test_runner`][], which has not yet moved off `unittest`._
 [dartdocs-badge]: https://img.shields.io/badge/dartdocs-reference-blue.svg
 [dartdocs]: http://www.dartdocs.org/documentation/dotenv/latest
 
-###### install
+### usage
+
+See [documentation][dotenv-usage].
+
+[dotenv-usage]: http://www.dartdocs.org/documentation/dotenv/latest/index.html#dotenv/dotenv
+
+### cli
 
 Get the latest:
 
@@ -26,10 +28,10 @@ Get the latest:
 $ pub global activate dotenv
 ```
 
-### run
+Run:
 
-```
-$ pub run dotenv      # load the environment and print it to stdout
+```sh
+$ pub run dotenv      # load a file and print the environment to stdout
 $ pub run dotenv:new  # create the `.env` file and add it to `.gitignore`
 ```
 
diff --git a/tool/README.md b/tool/README.md
index 44ac006..2216b72 100644
--- a/tool/README.md
+++ b/tool/README.md
@@ -5,12 +5,11 @@ _Consider calling these in a git pre-commit hook._
 
 Ensure `~/.pub_cache/bin` is in your `$PATH`.
 
-### [fmt.sh][]
+### [fmt.sh](fmt.sh)
 
 Runs the official [code formatter][].
 
 [code formatter]: https://github.com/dart-lang/dart_style
-[fmt.sh]: fmt.sh
 
 ###### setup
 
@@ -18,17 +17,14 @@ Runs the official [code formatter][].
 $ pub global activate dart_style
 ```
 
-### [test.sh][]
+### [test.sh](test.sh)
 
 Runs the unit test suite.
 
-[test.sh]: test.sh
-
-### [docs.sh][]
+### [docs.sh](docs.sh)
 
 Preview [dartdoc][] documentation.
 
-[docs.sh]: docs.sh
 [dartdoc]: https://github.com/dart-lang/dartdoc
 
 ###### setup
@@ -36,3 +32,7 @@ Preview [dartdoc][] documentation.
 ```sh
 $ pub global activate dartdoc
 ```
+
+### [travis.sh](travis.sh)
+
+Run the analyzer and unit tests on Travis CI.