Add details to the README

README.md

@@ -92,6 +92,48 @@ var node = new Awk('docs', 'ES6', 'ECMAScript 2015');
 module.exports = node;
 ```
 
+## Persistent Cache
+
+__Note: This feature is experimental and is only available on Unix based systems.__
+
+Adding persist flag allows a subclass to persist state across restarts. This exists to mitigate the upfront cost of some more expensive transforms on warm boot. __It does not aim to improve incremental build performance, if it does, it should indicate something is wrong with the filter or input filter in question.__
+
+### How does it work?
+
+It does so but establishing a 2 layer file cache. The first layer, is the entire bucket.
+The second, `cacheKeyProcessString` is a per file cache key.
+
+Together, these two layers should provide the right balance of speed and sensibility.
+
+The bucket level cacheKey must be stable but also never become stale. If the key is not
+stable, state between restarts will be lost and performance will suffer. On the flip-side,
+if the cacheKey becomes stale changes may not be correctly reflected.
+
+It is configured by subclassing and refining `cacheKey` method. A good key here, is
+likely the name of the plugin, its version and the actual versions of its dependencies.
+
+```js
+Subclass.prototype.cacheKey = function() {
+ return md5(Filter.prototype.call(this) + inputOptionsChecksum + dependencyVersionChecksum);
+}
+```
+
+The second key, represents the contents of the file. Typically the base-class's functionality
+is sufficient, as it merely generates a checksum of the file contents. If for some reason this
+is not sufficient, it can be re-configured via subclassing.
+
+```js
+Subclass.prototype.cacheKeyProcessString = function(string, relativePath) {
+  return superAwesomeDigest(string);
+}
+```
+
+It is recommended that persistent re-builds is opt-in by the consumer as it does not currently work on all systems.
+
+```js
+var myTree = new SomePlugin('lib', { persist: true });
+```
+
 ## FAQ
 
 ### Upgrading from 0.1.x to 1.x