Update top-level documentation

.github/CONTRIBUTING.md

@@ -2,30 +2,48 @@
 
 If you'd like to contribute to Pattern Lab Node, please do so! There is always a lot of ground to cover and something for your wheelhouse.
 
-No pull request is too small. Check out any [up for grabs issues](https://github.com/pattern-lab/patternlab-node/labels/up%20for%20grabs) as a good way to get your feet wet, or add some more unit tests.
+No pull request is too small. Check out any [help wanted 🆘](https://github.com/pattern-lab/patternlab-node/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted+%3Asos%3A%22) or [good first issues 🎓](https://github.com/pattern-lab/patternlab-node/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue+%3Amortar_board%3A%22)as a good way to get your feet wet, or add some more unit tests.
+
+## Prerequisites
+
+To get started, you'll need Node 8 or higher. Managing Node with [nvm](https://github.com/creationix/nvm) is recommended. Once installed, you can target the version of Node we specify within the [`.nvmrc`](https://github.com/pattern-lab/patternlab-node/blob/master/.nvmrc) file.
+
+```sh
+nvm install <<version>>
+nvm use <<version>>
+```
 
 ## Developing Locally
 
-The best way to make changes to the Pattern Lab Node core and test them is through your existing edition.
+The best way to make changes to the Pattern Lab Node core and test them is through an edition.
 
 * Fork this repository on Github.
+* `npm install && npm run bootstrap`
 * Create a new branch in your fork and push your changes in that fork.
-* `npm install`
-* `npm link`
-* `cd /path/to/your/edition`
-* `npm link patternlab-node`
+* `cd packages/edition-node`
+* Test your changes with the edition's api
+
+### Cold start testing
+
+To ensure that developers can bootstrap the repo from a fresh clone, do this in your working copy:
+
+```sh
+git reset --hard && git clean -dfx && npm install && npm run bootstrap
+```
+
+This ensures that any changes you've made will still result in a clean and functional developer experience. **Note**: be sure you've committed any outstanding work before doing this -- it will blow away whatever's still outstanding, including anything staged but not commited.
 
 ## Guidelines
 
 * _ALWAYS_ submit pull requests against the [dev branch](https://github.com/pattern-lab/patternlab-node/tree/dev). If this does not occur, I will first, try to redirect you gently, second, attempt to redirect the target branch myself, thirdly, port over your contribution manually if time allows, and/or lastly, close your pull request. If you have a major feature to stabilize over time, talk to @bmuenzenmeyer via an issue about making a dedicated `feature-branch`
 * Keep your pull requests concise and limited to **ONE** substantive change at a time. This makes reviewing and testing so much easier.
 * Commits should reference the issue you are adressing. For any Pull Request that you send, use the template provided.
 * Commits are best formatted using the [conventional commits pattern](https://conventionalcommits.org/).
-* If you can, add some unit tests using the existing patterns in the `./test` directory
+* If you can, add some unit tests using the existing patterns in the `.packages/core/test` directory
 * Large enhancements should begin with opening an issue. This will result in a more systematic way for us to review your contribution and determine if a [specifcation discussion](https://github.com/pattern-lab/the-spec/issues) needs to occur.
 * Mention the issue number in commits, so anyone can see to which issue your changes belong to. For instance:
-  * `#123 Fix resolving patterns in pattern_hunter`
-  * `Feature #42: improve improbability drive`
+  * `fix(get): Resolve patterns correctly`
+  * `feat(version): Add ability to ask for version statically`
 
 ## Coding style
 

.github/ISSUE_TEMPLATE.md

@@ -2,7 +2,7 @@
 
 <!-- before posting an issue, verify you are running at least Node 6 -->
 
-I am using Pattern Lab Node `vX.X.X` on `Windows | Mac | Linux`, with Node `vX.X.X`, using the `Gulp | Grunt` Edition.
+I am using Pattern Lab Node `vX.X.X` on `Windows | Mac | Linux`, with Node `vX.X.X`, using a `Gulp | Grunt | Vanilla | Custom` Edition.
 
 ##### Expected Behavior
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,5 @@
 <!-- **Please read the contribution guidelines first, and target the `dev` branch!** -->
 
-Addresses #
+Closes #
 
 Summary of changes:

README.md

@@ -8,15 +8,35 @@ This monorepo contains the core of Pattern Lab / Node and all related engines, U
 
 If you'd like to see what a front-end project built with Pattern Lab looks like, check out this [online demo of Pattern Lab output](http://demo.patternlab.io/).
 
-[![Build Status](https://travis-ci.org/pattern-lab/patternlab-node.svg?branch=master)](https://travis-ci.org/pattern-lab/patternlab-node) ![current release](https://img.shields.io/npm/v/@pattern-lab/patternlab-node.svg) ![license](https://img.shields.io/github/license/pattern-lab/patternlab-node.svg) [![Coverage Status](https://coveralls.io/repos/github/pattern-lab/patternlab-node/badge.svg?branch=master)](https://coveralls.io/github/pattern-lab/patternlab-node?branch=master) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
+[![Build Status](https://travis-ci.org/pattern-lab/patternlab-node.svg?branch=master)](https://travis-ci.org/pattern-lab/patternlab-node)
+![current release](https://img.shields.io/npm/v/@pattern-lab/core.svg)
+![license](https://img.shields.io/github/license/pattern-lab/patternlab-node.svg)
+[![Coverage Status](https://coveralls.io/repos/github/pattern-lab/patternlab-node/badge.svg?branch=master)](https://coveralls.io/github/pattern-lab/patternlab-node?branch=master)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
 [![node (scoped)](https://img.shields.io/node/v/@pattern-lab/patternlab-node.svg)]()
 [![Join the chat at Gitter](https://badges.gitter.im/pattern-lab/node.svg)](https://gitter.im/pattern-lab/node)
 
 ## Using Pattern Lab
 
+Refer to the [core usage guidelines](https://github.com/pattern-lab/patternlab-node/blob/master/packages/core/README.md#usage)
+
 ### Installation
 
-Installation is still in flux due to the monorepo transition. Bear with us as we figure this out.
+Installation is still in flux due to the monorepo transition. Bear with us as we figure this out. Our intent is to ship the Pattern Lab Node CLI soon which will help new and existing users.
+
+_In the meantime..._
+
+if you already have an Edition tracking 3.X alphas, you can update using the [standard instructions](https://github.com/pattern-lab/patternlab-node/wiki/Upgrading#3x-instructions).
+
+if you don't mind pulling down everything and playing with it locally, clone this repo and follow the instructions for [developing locally](https://github.com/pattern-lab/patternlab-node/blob/master/.github/CONTRIBUTING.md#developing-locally).
+
+if you don't yet have a 3.X compatible Edition and want to try something a bit messier (and unsupported for now), you could attempt this [workaround](https://github.com/pattern-lab/patternlab-node/issues/813).
+
+## Ecosystem
+
+![Pattern Lab Ecosystem](http://patternlab.io/assets/pattern-lab-2-image_18-large-opt.png)
+
+Core, and Editions, are part of the [Pattern Lab Ecosystem](http://patternlab.io/docs/advanced-ecosystem-overview.html). With this architecture, we encourage people to write and maintain their own Editions, Starterkits, and even PatternEngines.
 
 ## Support for Pattern Lab
 
@@ -31,22 +51,4 @@ Pattern Lab / Node wouldn't be what it is today without the support of the commu
 
 ## Contributing
 
-### Prerequisites
-
-To get started, you'll need Node 8 or higher. Managing Node with `nvm` is recommended.
-
-### Testing
-
-#### Unit tests
-
-Unit tests are currently in `packages/core`. We use Tap
-
-#### Cold start testing
-
-To ensure that developers can bootstrap the repo from a fresh clone, do this in your working copy:
-
-```sh
-git reset --hard && git clean -dfx && npm install && npm run bootstrap
-```
-
-This ensures that any changes you've made will still result in a clean and functional developer experience. **Note**: be sure you've committed any outstanding work before doing this -- it will blow away whatever's still outstanding, including anything staged but not commited.
+Refer to the [contribution guidelines](https://github.com/pattern-lab/patternlab-node/blob/master/.github/CONTRIBUTING.md).