docs: add READMEs for each package and at the repo root

README.md

@@ -0,0 +1,12 @@
+# Milestones [![Build Status](https://travis-ci.org/salsify/milestones.svg?branch=master)](https://travis-ci.org/salsify/milestones)
+
+The `@milestones` packages provide a set of tools for navigating concurrent code in testing and development. Milestones act as named synchronization points, and they give you the ability to change the behavior of annotated code during testing, skipping pauses or mocking out results.
+
+Full interactive documentation can be found at https://salsify.github.io/milestones.
+
+## Packages
+
+This library is broken out into several packages:
+ - [@milestones/core](packages/core): the core library, containing tools for defining and interacting with milestones
+ - [@milestones/babel-plugin-strip-milestones](packages/babel-plugin-strip-milestones): a Babel plugin that removes milestone definitions from your code, ensuring no overhead in production
+ - [@milestones/ember](packages/ember): an Ember addon that integrates with the framework runtime and build system to provide zero-config setup for working with milestones

packages/babel-plugin-strip-milestones/README.md

@@ -0,0 +1,9 @@
+# @milestones/babel-plugin-strip-milestones
+
+This package allows you to strip the `milestone()` calls completely out of your code to eliminate any overhead in production.
+
+Full documentation can be found at https://salsify.github.io/milestones/docs/babel-plugin.
+
+## Usage
+
+Include `@milestones/babel-plugin-strip-milestones` in your package dependencies and then add `'@milestones/strip-milestones'` to the `plugins` array in your `babel.config.json` or the corresponding configuration location for your particular Babel integration.

packages/core/README.md

@@ -0,0 +1,55 @@
+# @milestones/core
+
+Milestones are a tool for annotating points in time in your code.
+
+A milestone can act as a named synchronization point, allowing you to ensure the state of your application code at the moment in time in your testing when you wish to make assertions. They also give you the ability to change the behavior of annotated code during testing, skipping pauses or mocking out results.
+
+Full interactive documentation can be found at https://salsify.github.io/milestones.
+
+## Example
+
+#### Application Code
+```ts
+import { milestone } from '@milestones/core';
+
+export const Save = Symbol('save');
+export const ShowCompletion = Symbol('show-completion-message');
+
+// ...
+
+async function save() {
+  renderMessage('Saving...');
+  await milestone(Save, () => saveData());
+
+  renderMessage('Saved!');
+  await milestone(ShowCompletion, () => sleep(4000));
+
+  renderMessage('');
+}
+```
+
+#### Test Code
+```ts
+import { advanceTo } from '@milestones/core';
+import { Save, ShowCompletion } from '../app/code/under/test';
+
+// ...
+
+it('renders the current saving status', async () => {
+  click('.save-button');
+
+  // Wait until we start saving, then check that
+  // the expected message is being shown.
+  let saveHandle = await advanceTo(Save);
+  expect(currentMessage()).to.equal('Saving...');
+
+  // Now go ahead and perform the save
+  await saveHandle.continue();
+  expect(currentMessage()).to.equal('Saved!');
+
+  // Now advance to where we pause to show the
+  // the status message, but skip the sleep
+  await advanceTo(ShowCompletion).andReturn();
+  expect(currentMessage()).to.equal('');
+});
+```

packages/ember/README.md

@@ -0,0 +1,25 @@
+# @milestones/ember
+
+The `@milestones/ember` addon integrates with the Ember runtime and ember-cli to provide zero-config setup for working with milestones.
+
+Full documentation can be found at https://salsify.github.io/milestones/docs/ember.
+
+## Runtime
+
+All milestones are configured by `@milestones/ember` to use RSVP for their promise implementation, ensuring that any code that executes as a result of a milestone occurs within a runloop.
+
+## Build
+
+By default, milestones will be stripped from your code in production builds using `@milestones/babel-plugin-strip-milestones`. This behavior is always controlled by the host application, and it can be overridden in the host's `ember-cli-build.js`.
+
+```ts
+let app = new EmberApp(defaults, {
+  milestones: {
+    stripMilestones: false, // or whatever your preference
+  },
+});
+```
+
+## Ember Concurrency
+
+If `ember-concurrency` is present in your project, any milestones you create will be task-like promises that will bubble cancelation appropriately. They will also be cancelable from your test code.