docs: ✏️ update readme to introduce addon and explain usage

addons/core/README.md

@@ -1,38 +1,89 @@
-core
-==============================================================================
+# Core Features Addon for Boundary
 
-[Short description of the addon.]
+This addon contains core features used by Boundary UIs, such as i18n and
+helpers.
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-Compatibility
-------------------------------------------------------------------------------
+- [Add core to an App](#add-core-to-an-app)
+- [Installation](#installation)
+- [Yarn Commands](#yarn-commands)
+- [Linting](#linting)
+- [Formatting](#formatting)
+- [Running tests](#running-tests)
+- [Running the dummy application](#running-the-dummy-application)
+- [Contributing](#contributing)
+  - [Building ToC](#building-toc)
 
-* Ember.js v3.12 or above
-* Ember CLI v2.13 or above
-* Node.js v10 or above
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
+## Add core to an App
 
-Installation
-------------------------------------------------------------------------------
+Add this addon to an Ember application's `devDependencies` as:
+`"core": "*"`, for applications included in this monorepo.
 
-```
-ember install core
-```
+## Installation
 
+See monorepo README for installation instructions.
 
-Usage
-------------------------------------------------------------------------------
+To use internationalization features, install `ember-intl` into your project:
+`ember install ember-intl`.
 
-[Longer description of how to use the addon in apps.]
+## Usage within a project
 
+To access translations within a template, see `ember-intl` docs.
 
-Contributing
-------------------------------------------------------------------------------
+## Yarn Commands
 
-See the [Contributing](CONTRIBUTING.md) guide for details.
+List of available project commands.  `yarn run <command-name>`
 
+| Command | Description |
+| ------- | ----------- |
+| build:development | Builds the dummy app in development mode. |
+| build | Builds the dummy app for production. |
+| lint | Runs all lint commands. |
+| lint:js | Lints `js` files. |
+| format | Runs all auto-formatters. |
+| format:js | Auto-formats `js` files using Prettier. |
+| start | Runs the dummy app local server. |
+| test | Runs all tests. |
+| test:all | Runs tests across multiple Ember versions with ember-try. |
+| doc:toc | Automatically generates a table of contents for this README file. |
 
-License
-------------------------------------------------------------------------------
+Additional commands in the monorepo package may affect this projects.
 
-This project is licensed under the [MIT License](LICENSE.md).
+## Linting
+
+* `yarn lint:hbs`
+* `yarn lint:js`
+* `yarn lint:js --fix`
+
+## Formatting
+
+Before submitting your work, be sure to run auto-formatters
+(see commands above).  This helps to ensure consistency among authors.
+
+* `yarn format`
+
+## Running tests
+
+* `yarn test` – Runs the test suite on the current Ember version
+* `yarn test --server` – Runs the test suite in "watch mode"
+* `yarn test:all` – Runs the test suite against multiple Ember versions
+
+## Running the dummy application
+
+* `yarn start`
+* Visit the dummy application at [http://localhost:4200](http://localhost:4200).
+
+## Contributing
+
+See monorepo README for more contribution instructions.
+
+### Building ToC
+
+To autogenerate a ToC (table of contents) for this README,
+run `yarn doc:toc`.  Please update the ToC whenever editing the structure
+of README.

addons/core/package.json

@@ -13,15 +13,16 @@
     "test": "tests"
   },
   "scripts": {
+    "build:development": "ember build",
     "build": "ember build --environment=production",
     "lint": "npm-run-all --aggregate-output --continue-on-error --parallel lint:*",
-    "lint:hbs": "ember-template-lint .",
     "lint:js": "eslint .",
     "format": "npm run format:js",
     "format:js": "prettier --write '{addon,app,config,stories,tests}/**/*.js' *.js",
     "start": "ember serve",
     "test": "ember test",
-    "test:ember-compatibility": "ember try:each"
+    "test:ember-compatibility": "ember try:each",
+    "doc:toc": "doctoc README.md"
   },
   "dependencies": {
     "ember-cli-babel": "^7.21.0",
@@ -33,6 +34,7 @@
     "@glimmer/tracking": "^1.0.0",
     "babel-eslint": "^10.1.0",
     "broccoli-asset-rev": "^3.0.0",
+    "doctoc": "^1.4.0",
     "ember-auto-import": "^1.6.0",
     "ember-cli": "~3.20.2",
     "ember-cli-dependency-checker": "^3.2.0",