diff --git a/README.md b/README.md
index e4af09a7a1a..cd4cf3e4ecf 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,67 @@
freesewing
a library for made-to-measure sewing patterns
-
+
+ 
+ 
+ 
+
# freesewing
-A port of [freesewing core](https://github.com/freesewing/core) to node.js.
-> This is alpha code.
+[Freesewing](https://freesewing.org/) is an open source platform for made-to-measure sewing pattern.
+This is our core library.
+A freesewing plugin to display debug information in your browser console.
+## Usage
+
+To load this plugin, add it to your instantiated pattern.
+
+On node.js:
+
+```js
+import pattern from '@freesewing/pattern-brian'
+import debug from '@freesewing/plugin-debug'
+
+pattern.with(debug);
+```
+
+In the browser, this plugin will register as `freesewing.plugins.debug`:
+
+```html
+
+
+
+
+
+```
+
+## Example
+
+This plugin will gather debug info and log it to your browser console:
+
+
+
+
+## Install
+
+To install, run:
+
+```sh
+npm install @freesewing/plugin-debug
+```
+
+## Build
+
+To build this plugin, run:
+
+```sh
+npm run build
+```
+
+## License: MIT
+
+See [the license file](https://github.com/freesewing/plugin-theme/blob/master/LICENSE)
+for details.