diff --git a/.imdone/config.json b/.imdone/config.json
index f1dd8478..1a29f78d 100644
--- a/.imdone/config.json
+++ b/.imdone/config.json
@@ -37,6 +37,10 @@
     {
       "name": "DOING",
       "hidden": false
+    },
+    {
+      "name": "NOTE",
+      "hidden": false
     }
   ],
   "marked": {
diff --git a/.imdoneignore b/.imdoneignore
index ea6a56a3..b09d96aa 100644
--- a/.imdoneignore
+++ b/.imdoneignore
@@ -4,5 +4,6 @@
 !test
 !test/**/*
 !DoD.md
+!README.md
 test/repos
 test/files
diff --git a/README.md b/README.md
index 165aa831..b3a367cf 100644
--- a/README.md
+++ b/README.md
@@ -1,49 +1,44 @@
-imdone-core
-===========
-
-[![NPM](https://nodei.co/npm/imdone-core.png)](https://nodei.co/npm/imdone-core/)
-
+[![npm version](https://badge.fury.io/js/imdone-core.svg)](https://badge.fury.io/js/imdone-core)
 [![Build Status](https://travis-ci.org/imdone/imdone-core.png?branch=master)](https://travis-ci.org/imdone/imdone-core)
 [![Downloads](https://img.shields.io/npm/dm/imdone-core.svg)](https://npmjs.org/package/imdone-core)
-[![Stories in Ready](https://badge.waffle.io/imdone/imdone-core.png?label=ready&title=Ready)](https://waffle.io/imdone/imdone-core)
 
-**Organize TODO, FIXME, HACK, etc. comments in code or any text file.**
+Imdone is text based kanban processor with a simple syntax and model that allows the user to create and modify tasks using the keyboard to improve productivity.
 
-Initializing a Repository
-----
-```
-var Repo        = require('imdone-core/lib/repository'),
-    FsStore     = require('imdone-core/lib/mixins/repo-watched-fs-store');
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-var repo = FsStore(new Repo('path/to/my/project'));
 
-repo.on('initialized', function() {
-  // do something with the repo...
-  var lists = repo.getLists();
-  lists.forEach(function(list) {
-    var listTasks = repo.getTasksInList(list.name);
-  });
+- [Imdone format](#imdone-format)
+  - [Code Style](#code-style)
+  - [Hash Style](#hash-style)
+  - [Markdown Style](#markdown-style)
+- [Task syntax](#task-syntax)
+- [todo.txt syntax](#todotxt-syntax)
+  - [Create date](#create-date)
+  - [Completed date](#completed-date)
+  - [Due Date](#due-date)
+  - [Tags (todo.txt projects)](#tags-todotxt-projects)
+  - [Context](#context)
+  - [Metadata](#metadata)
+- [Metadata links](#metadata-links)
+- [Resources](#resources)
+- [License](#license)
 
-  var tasks = repo.getTasks();
-});
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-repo.on('file.update', function(file) {
-  // Do something usefull
-});
-
-repo.on('config.update', function() {
-  // Do something usefull
-});
-```
-
-Task formats
-----
+## Imdone format
+Imdone aims to keep you in the flow of your work while capturing tasks to be accomplished later.  Most kanban tools require the user to use a UI.  Imdone lets you capture tasks in a simple text format that has roots in programming [comment tags like TODO and FIXME](https://en.wikipedia.org/wiki/Comment_%28computer_programming%29#Tags) and [todo.txt format](https://github.com/todotxt/todo.txt#todotxt-format).
 
 ### Code Style
 <pre>
 // TODO This is a task
 // TODO: This is a task
 // TODO:5 This is a task
+// TODO: A task with a descrption looks like this.
+// Every line after the task is part of the description until we find another
+// task, a blank comment line, or a line of code
+// - A list item
+// - Another list item
 </pre>
 
 ### Hash Style
@@ -51,7 +46,16 @@ Task formats
 &#35;TODO: This is a task
 &#35;TODO:0 This is a task
 &#35;to-do:0 This is a task
+
+&lt;!--
+&#35;TODO: If you don't want your task to get converted to html in markdown files, put it in a comment.
+You can still add descriptive text, but don't forget to leave a blank line
+between the description and the comment end tag, or the comment end will become
+a part of your description.
+
+ --&gt;
 </pre>
+- Take a look at the source of this README.md.  You'll probably find a few tasks in comments.
 
 ### Markdown Style
 <pre>
@@ -121,19 +125,29 @@ Metadata links
     }
   }
 ```
+<!--
+#TODO: Add Node.js API SECTION
+## Node.js API
+### Generated Docs
+- use [jsdoc3/jsdoc: An API documentation generator for JavaScript.](https://github.com/jsdoc3/jsdoc)
+### Examples
+- use links to github [examples](https://github.com/imdone-core/tree/master/examples)
 
-Things yet to be done...
-----
-1. [Use [visionmedia/dox](https://github.com/visionmedia/dox), [smartcomments/smartcomments](https://github.com/smartcomments/smartcomments) and [JSDoc](http://usejsdoc.org) for documenting the following... +doc](#TODO:)
-  - Project
-  - Repository
-  - File
-  - Task
-  - List
-  - Config
+-->
+
+<!--
+#TODO: Add Contributing Section
+## Contributing
+### Build and Test
+### FAQs and BUGs
 
-- [Use [gajus/gitdown](https://github.com/gajus/gitdown) for docs +doc](#BACKLOG:)
+-->
 
+Resources
+----
+- [Is the keyboard faster than the mouse? | Hacker News](https://news.ycombinator.com/item?id=14544571)
+- [Blog | Personal Kanban](http://personalkanban.com/pk/blog/)
+- [Do TODO comments make sense? - Software Engineering Stack Exchange](https://softwareengineering.stackexchange.com/questions/125320/do-todo-comments-make-sense)
 
 License
 ----
diff --git a/package.json b/package.json
index da7f965d..814a73a9 100644
--- a/package.json
+++ b/package.json
@@ -4,6 +4,7 @@
   "description": "imdone-core",
   "main": "index.js",
   "scripts": {
+    "build": "doctoc --github --notitle README.md && npm test",
     "test": "export NODE_ENV=test && npm run coverage",
     "coverage": "nyc --reporter=lcov --reporter=text --reporter=html mocha",
     "lint": "jshint ./lib"
@@ -42,6 +43,7 @@
     "cheerio": "^1.0.0-rc.2",
     "chokidar": "1.7.0",
     "debug": "^2.2.0",
+    "doctoc": "^1.3.0",
     "ignore": "^3.2.0",
     "isbinaryfile": "^3.0.2",
     "lodash": "2.4.2",
diff --git a/test/file-spec.js b/test/file-spec.js
index c53b4206..4cb70481 100644
--- a/test/file-spec.js
+++ b/test/file-spec.js
@@ -56,8 +56,8 @@ describe('File', function() {
 
       var expectation = sinon.mock();
       file.on("task.found", expectation);
-      expectation.exactly(5);
-      (file.extractTasks().getTasks().length).should.be.exactly(5);
+      expectation.exactly(6);
+      (file.extractTasks().getTasks().length).should.be.exactly(6);
       expectation.verify();
     });
 
diff --git a/test/files/sample.md b/test/files/sample.md
index c671c52f..4d12f580 100644
--- a/test/files/sample.md
+++ b/test/files/sample.md
@@ -3,5 +3,6 @@
 - [task 3](#todo:0)
 - [task 4](#doing:0)
 - Looking for #doing:0 A new task
-
-
+<!--
+- #DOING: Find tasks in markdown coments
+ -->