optimizely · spencerwilson-optimizely · Jul 3, 2018 · Jun 29, 2018 · Jun 29, 2018 · Jun 29, 2018
diff --git a/README.md b/README.md
@@ -3,20 +3,22 @@
 </h3>
 
 <p align="center">
-  This repository houses the official JavaScript SDK for use with Optimizely X Full Stack
+  This repository houses the official JavaScript SDK for use with Optimizely X Full Stack.
 </p>
 
+Optimizely X Full Stack is A/B testing and feature management for product development teams. Experiment in any application. Make every feature on your roadmap an opportunity to learn. Learn more at https://www.optimizely.com/products/full-stack/, or see the [documentation](https://developers.optimizely.com/x/solutions/sdks/reference/index.html?language=node).
+
 ## Packages
 
-This repository is a monorepo that we manage using [Lerna](https://github.com/lerna/lerna). That means that we actually publish [several packages](/packages) to npm from the same codebase, including:
+This repository is a monorepo that we manage using [Lerna](https://github.com/lerna/lerna). Only one package lives here currently, but that may change in the future.
 
 | Package                                                | Version                                                                                                                                   | Docs                                                                                                                                                                                                                                                                          | Description                                                                        |
 | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| [`optimizely-sdk`](/packages/optimizely-sdk)               | [![npm](https://img.shields.io/npm/v/optimizely-sdk.svg?style=flat-square)](https://npmjs.com/package/@optimizely/optimizely-sdk)                     | [![](https://img.shields.io/badge/API%20Docs-site-green.svg?style=flat-square)](https://developers.optimizely.com/x/solutions/sdks/reference/?language=javascript)           | The Optimizely SDK                                                                                                  |
+| [`@optimizely/optimizely-sdk`](/packages/optimizely-sdk) | [![npm](https://img.shields.io/npm/v/%40optimizely%2Foptimizely-sdk.svg)](https://www.npmjs.com/package/@optimizely/optimizely-sdk)     | [![](https://img.shields.io/badge/API%20Docs-site-green.svg?style=flat-square)](https://developers.optimizely.com/x/solutions/sdks/reference/?language=javascript)           | The Optimizely SDK                                                                                                  |
 
 ## About
 
-`optimizely-sdk` is developed and maintained by [Optimizely](https://optimizely.com) and many [contributors](https://github.com/optimizely/javascript-sdk/graphs/contributors). If you're interested in learning more about what Optimizely X FullStack can do for your company, please [get in touch](mailto:eng@optimizely.com)!
+`@optimizely/optimizely-sdk` is developed and maintained by [Optimizely](https://optimizely.com) and many [contributors](https://github.com/optimizely/javascript-sdk/graphs/contributors). If you're interested in learning more about what Optimizely X Full Stack can do for your company, please [get in touch](mailto:eng@optimizely.com)!
 
 
 ### Contributing

diff --git a/packages/optimizely-sdk/README.md b/packages/optimizely-sdk/README.md
@@ -1,68 +1,69 @@
-# Optimizely JavaScript SDK
+# JavaScript SDK for Optimizely X Full Stack
+[![npm](https://img.shields.io/npm/v/%40optimizely%2Foptimizely-sdk.svg)](https://www.npmjs.com/package/@optimizely/optimizely-sdk)
+[![npm](https://img.shields.io/npm/dm/%40optimizely%2Foptimizely-sdk.svg)](https://www.npmjs.com/package/@optimizely/optimizely-sdk)
+[![Travis CI](https://img.shields.io/travis/optimizely/javascript-sdk.svg)](https://travis-ci.org/optimizely/javascript-sdk)
+[![Coveralls](https://img.shields.io/coveralls/optimizely/javascript-sdk.svg)](https://coveralls.io/github/optimizely/javascript-sdk)
+[![license](https://img.shields.io/github/license/optimizely/javascript-sdk.svg)](https://choosealicense.com/licenses/apache-2.0/)
 
-This repository houses the JavaScript SDK for Optimizely X Full Stack.
+
+Optimizely X Full Stack is A/B testing and feature management for product development teams. Experiment in any application. Make every feature on your roadmap an opportunity to learn. Learn more at the [landing page](https://www.optimizely.com/products/full-stack/), or see the [documentation](https://developers.optimizely.com/x/solutions/sdks/reference/index.html?language=node).
+
+This directory contains the source code for the JavaScript SDK, which is usable in Node.js, browsers, and beyond.
 
 ## Getting Started
 
-### Installing the SDK
+### Prerequisites
+
+Ensure the SDK supports all of the platforms you're targeting. In particular, the SDK targets any ES5-compliant JavaScript environment. We officially support:
+  - Node.js >= 4.0.0. By extension, environments like AWS Lambda, Google Cloud Functions, and Auth0 Webtasks are supported as well. Older Node.js releases likely work too (try `npm test` to validate for yourself), but are not formally supported.
+  - [Web browsers](https://caniuse.com/#feat=es5)
+
+Other environments likely are compatible, too, but note that we don't officially support them:
+  - Progressive Web Apps, WebViews, and hybrid mobile apps like those built with React Native and Apache Cordova.
+  - [Cloudflare Workers](https://developers.cloudflare.com/workers/) and [Fly](https://fly.io/), both of which are powered by recent releases of V8.
+  - Anywhere else you can think of that might embed a JavaScript engine. The sky is the limit; experiment everywhere! 🚀
 
-The SDK is available through [npm](https://npmjs.com/package/optimizely-sdk). To install:
+Once you've validated that the SDK supports the platforms you're targeting, fetch the package from [NPM](https://www.npmjs.com/package/@optimizely/optimizely-sdk). Using `npm`:
 
 ```
-npm install @optimizely/optimizely-sdk --save
+npm install --save @optimizely/optimizely-sdk
 ```
 
-Or to use in a non CommonJS fashion in the Browser:
+### Usage
+See the Optimizely X Full Stack [developer documentation](http://developers.optimizely.com/server/reference/index.html) to learn how to set up your first JavaScript project and use the SDK.
 
-1. Run `npm run build`
-2. Pull in `dist/optimizely.browser.umd.min.js` as a `<script>`
-3. Use as global variable `window.optimizelyClient`
+Regarding `EventDispatcher`s: In Node.js and browser environments, the default `EventDispatcher` is powered by the [`http/s`](https://nodejs.org/api/http.html) modules and by [`XMLHttpRequest`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest#Browser_compatibility), respectively. In all other environments, you must supply your own `EventDispatcher`.
 
 ### Migrating from 1.x.x
 
 This version represents a major version change and, as such, introduces some breaking changes:
 
-- The Node SDK is now combined with the JavaScript SDK so that we have one `optimizely-sdk` package that works across both server + browser environments.
+- The Node.js SDK is now combined with the JavaScript SDK. We now have just one package, `@optimizely/optimizely-sdk`, that works in many JavaScript environments.
 
-- We no longer support legacy Node versions (under 4.0).
+- We no longer support Node.js < 4.0.0, which collectively [reached end-of-life](https://github.com/nodejs/Release#end-of-life-releases) on 2016-12-31.
 
 - You will no longer be able to pass in `revenue` value as a stand-alone argument to the `track` call. Instead you will need to pass it as an entry in the [`eventTags`](https://developers.optimizely.com/x/solutions/sdks/reference/index.html?language=javascript#event-tags).
 
-### Feature Management Access
-
-To access the Feature Management configuration in the Optimizely dashboard, please contact your Optimizely account executive.
-
-### Using the SDK
-See the Optimizely X Full Stack testing [developer documentation](http://developers.optimizely.com/server/reference/index.html) to learn how to set up your first JavaScript project and use the SDK.
-
-## Development
+### Feature Management access
 
-### Installing dependencies
+To access Feature Management in the Optimizely web application, please contact your Optimizely account executive.
 
-```npm install```
+## Contributing
+This information is relevant only if you plan on contributing to the SDK itself.
 
-### Unit tests
+```sh
+# Prerequisite: Install dependencies.
+npm install
 
-You can run all unit tests with:
-```
+# Run unit tests with mocha.
 npm test
-```
 
-### Build distribution packages
-
-```
-npm run build
+# Run unit tests in many browsers, currently via BrowserStack.
+# For this to work, the following environment variables must be set:
+#   - BROWSER_STACK_USERNAME
+#   - BROWSER_STACK_PASSWORD
+npm run test-xbrowser
 ```
 
-This command will build several distribution bundles under the `dist` directory:
-1. optimizely.browser.cjs.js - This is the main entry point for browser/client-side bundles
-2. optimizely.browser.umd.js - This is used when not packaging the optimizely-sdk with your own JS bundles. Instead you would load this script as a `<script>` tag and reference it via the global var `optimizelyClient`
-3. optimizely.node.js - This is the main entry point for Node apps
-
-The browser bundles also come with a minified / production-ready version.
-
-### Environment Variables
-
-The .yml of this project contains environment vairables for ```BROWSER_STACK_USERNAME``` and ```BROWSER_STACK_ACCESS_KEY```.
+[.travis.yml](/.travis.yml) contains the definitions for `BROWSER_STACK_USERNAME` and `BROWSER_STACK_ACCESS_KEY` used in CI. These values are Optimizely's BrowserStack credentials, encrypted with our Travis CI public key. These creds can be rotated by following [these docs](https://docs.travis-ci.com/user/environment-variables/#Defining-encrypted-variables-in-.travis.yml).
 
-These variables, created in BrowserStack, are encrypted by the Travis CI public key. This is done directly with the Travis CI command line tools; for additional information see travis encrypt-file.