diff --git a/.verb.md b/.verb.md
index 23c5865..bb22921 100644
--- a/.verb.md
+++ b/.verb.md
@@ -7,12 +7,29 @@
 ## Usage
 
 ```js
-var parseGlob = require('{%= name %}');
+var parse = require('{%= name %}');
+
+// this is a nonsensical pattern, but it shows what this lib does
+parse('a/b/{c,.gitignore,{a,b}}/{a,b}/*.foo.js');
 ```
 
-## API
-{%= apidocs("index.js") %}
+Returns:
 
+```js
+{ pattern: 'a/b/{c,.gitignore,{a,b}}/{a,b}/*.foo.js',
+  dirname: 'a/b/{c,.gitignore,{a,b}}/{a,b}/',
+  filename: '*.foo.js',
+  basename: '*',
+  extname: '.foo.js',
+  ext: 'js',
+
+  // detects when a glob pattern intentionally 
+  // specifies dotfiles
+  dotfiles: false,
+  dotdirs: false }
+```
+
+See the tests for [hundreds of examples](./test.js).
 
 ## Run tests
 
@@ -34,4 +51,4 @@ Pull requests and stars are always welcome. For bugs and feature requests, [plea
 
 ***
 
-{%= include("footer") %}
\ No newline at end of file
+{%= include("footer") %}
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..330a6dc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,62 @@
+# parse-glob [![NPM version](https://badge.fury.io/js/parse-glob.svg)](http://badge.fury.io/js/parse-glob)
+
+> Parse a glob pattern into an object of path parts.
+
+## Install with [npm](npmjs.org)
+
+```bash
+npm i parse-glob --save
+```
+
+## Usage
+
+```js
+var parse = require('parse-glob');
+
+// this is a nonsensical pattern, but it shows what this lib does
+parse('a/b/{c,.gitignore,{a,b}}/{a,b}/*.foo.js');
+```
+
+Returns:
+
+```js
+{ pattern: 'a/b/{c,.gitignore,{a,b}}/{a,b}/*.foo.js',
+  dirname: 'a/b/{c,.gitignore,{a,b}}/{a,b}/',
+  filename: '*.foo.js',
+  basename: '*',
+  extname: '.foo.js',
+  ext: 'js',
+
+  // detects when a glob pattern intentionally 
+  // specifies dotfiles
+  dotfiles: false,
+  dotdirs: false }
+```
+
+See the tests for [hundreds of examples](./test.js).
+
+## Run tests
+
+Install dev dependencies:
+
+```bash
+npm i -d && npm test
+```
+
+## Contributing
+Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/jonschlinkert/parse-glob/issues)
+
+## Author
+
+**Jon Schlinkert**
+ 
++ [github/jonschlinkert](https://github.com/jonschlinkert)
++ [twitter/jonschlinkert](http://twitter.com/jonschlinkert) 
+
+## License
+Copyright (c) 2015 Jon Schlinkert  
+Released under the MIT license
+
+***
+
+_This file was generated by [verb](https://github.com/assemble/verb) on February 07, 2015._