fix(docs): begin fleshing out getting-started guide

docs/dev.md

@@ -8,9 +8,10 @@
     - [Linux](#linux)
     - [Mac OS](#mac-os)
   - [Checking Out the Project](#checking-out-the-project)
-  - [Building](#building)
+  - [Build](#build)
     - [Compiling Typescript](#compiling-typescript)
     - [Running Mocha Tests](#running-mocha-tests)
+    - [Running Bundled Code](#running-bundled-code)
 
 ## Setup
 
@@ -66,7 +67,7 @@ Clone the repository:
 
 You can also clone the repository through Github Desktop:
 
-* [x-github-client://openRepo/https://github.com/ssube/cautious-journey](x-github-client://openRepo/https://github.com/ssube/cautious-journey)
+- [x-github-client://openRepo/https://github.com/ssube/cautious-journey](x-github-client://openRepo/https://github.com/ssube/cautious-journey)
 
 Change the directory:
 
@@ -74,7 +75,7 @@ Change the directory:
 > cd ~/Documents/GitHub/cautious-journey/
 ```
 
-## Building
+## Build
 
 Building the app is done through `make` and its targets. To see a list of available targets:
 
@@ -104,3 +105,13 @@ This will compile the code and run tests.
 ### Running Mocha Tests
 
 Tests use Mocha: https://mochajs.org/#getting-started
+
+```shell
+> make test
+```
+
+### Running Bundled Code
+
+```shell
+> node ./out/index.js --help
+```

docs/getting-started.md

@@ -17,47 +17,106 @@ This guide explains how to start using `cautious-journey` to manage project and
     - [Configuring Multiple Projects](#configuring-multiple-projects)
     - [Running Select Projects](#running-select-projects)
   - [Remotes](#remotes)
+    - [Available Remotes](#available-remotes)
     - [Copying Project Remotes](#copying-project-remotes)
   - [Commands](#commands)
-    - [Sync Labels](#sync-labels)
+    - [Sync Issue Labels](#sync-issue-labels)
-    - [Sync Issues](#sync-issues)
+    - [Sync Project Labels](#sync-project-labels)
   - [Changes](#changes)
     - [Flag Changes](#flag-changes)
     - [State Changes](#state-changes)
+    - [State Value Changes](#state-value-changes)
+  - [Examples](#examples)
+    - [Example: Conflicting Labels](#example-conflicting-labels)
+    - [Example: Release Workflow](#example-release-workflow)
 
 ## Setup
 
 ### Installing
 
-TODO: how would you install the app?
+To use the latest version of `master` from Docker Hub:
+
+```shell
+> docker pull ssube/cautious-journey:master
+```
+
+To use the latest release from npm:
+
+```shell
+> yarn add -g cautious-journey
+```
+
+To use the latest code from Github, following the [developer guide's `setup` and `build` steps](./dev.md).
 
 ### Running
 
-TODO: how would you run the app?
+To run the Docker image:
+
+```shell
+> docker run --rm -it ssube/cautious-journey:master --help
+```
+
+TODO: mounting config file into container
+
+To run the npm package:
+
+```shell
+> $(yarn global bin)/cautious-journey --help
+```
+
+To run the latest code, once it has been built:
+
+```shell
+> node --require esm ./out/index.js --help
+```
+
+To pretty-print logs for any of the above methods, pipe the output through `bunyan`:
+
+```shell
+> docker run --rm -it ssube/cautious-journey:master --help | $(yarn global bin)/bunyan
+> $(yarn global bin)/cautious-journey --help | $(yarn global bin)/bunyan
+> node --require esm ./out/index.js --help | ./node_modules/.bin/bunyan
+```
 
 ### Configuring
 
-TODO: how would you configure the app?
+Configuration is provided as a YAML file, typically named `~/.cautious-journey.yml`.
+
+Mac OS users may want to omit the leading dot from the filename and use `~/cautious-journey.yml` instead, to make
+the file visible in Finder. The hidden filename will be used in examples.
 
 ## Labels
 
-TODO: what are labels? what kinds of labels do we support?
+Labels are the unit of data being manipulated by cautious-journey. Labels may exist independently (flags) or as part
+of a group (state values), with rules to add, remove, and replace labels.
 
 ### Flag Labels
 
-TODO: what are flag labels?
+Flags exist independently, but have the same rules as other labels:
+
+- `adds`
+- `removes`
+- `requires`
 
 ### State Labels
 
-TODO: what are state labels?
+State labels exist in groups, of which only one value can be set at a time. If multiple values are set, the highest
+priority value will be kept, unless some rule removes it.
 
 ## Projects
 
-TODO: what are projects? how are they managed? how do you pick which projects to run?
+Projects usually map to a repository on some remote service, like Github or Gitlab. Each project can have its own
+set of labels and random colors.
 
 ### Configuring Multiple Projects
 
-TODO: how would you configure the app to run for multiple projects?
+The config file has a `projects` key at its root, containing a list of projects to be processed.
+
+- `colors`
+- `flags`
+- `name`
+- `remote`
+- `states`
 
 ### Running Select Projects
 
@@ -65,7 +124,18 @@ TODO: how would you run a single project, or a subset?
 
 ## Remotes
 
-TODO: what are remotes? how are they configured?
+Remotes abstract the API calls, requests, and writes needed to persist data in some service or file.
+
+### Available Remotes
+
+The following remote services are supported:
+
+- Github
+
+Support for more is planned:
+
+- File
+- Gitlab
 
 ### Copying Project Remotes
 
@@ -73,22 +143,62 @@ TODO: how would you share a remote config block between two projects?
 
 ## Commands
 
-TODO: what commands are present?
+The program can run in a few different modes:
 
-### Sync Labels
+- sync issue labels
+- sync project labels
 
-TODO: what happens when you sync the project labels?
+### Sync Issue Labels
 
-### Sync Issues
+This mode will look through each issue on the project, open or closed, and check for label updates. Labels will
+be resolved using the project's rules, and a comment left recording any changes.
 
-TODO: what happens when you sync the issue labels?
+### Sync Project Labels
+
+This mode will look through the project labels, ensuring they are up to date with the project labels in the
+config. Missing labels will be created, extra labels will be deleted, and existing labels will be updated to
+match the config.
 
 ## Changes
 
+Every change can add or remove flags, but certain labels may have their own rules.
+
 ### Flag Changes
 
-TODO: how are flag labels added and removed?
+- `adds`: labels to be added, `{ name: string }`
+- `removes`: labels to be removed, `{ name: string }`
+- `requires`:
+  - all required labels must be present
+  - if any required labels are missing, _this flag_ will be removed
+  - `adds`/`removes` rules will not be run if this flag is removed
 
 ### State Changes
 
-TODO: how are state labels added and removed?
+States have the base rules:
+
+- `adds`: labels to be added
+- `removes`: labels to be removed
+
+### State Value Changes
+
+State values have the base rules, which will be combined with their parent state's `adds`/`removes`, as well as
+a list of potential state changes that may replace the value, if matching labels exist.
+
+- `becomes`
+  - `adds`: labels to be added
+  - `matches`:
+    - all matched labels must be present
+    - if any matched labels are missing, this change will be skipped
+    - `adds`/`removes` rules will not be run if this change is skipped
+    - if this change is run, _this value_ will be removed
+  - `removes`: labels to be removed
+
+## Examples
+
+### Example: Conflicting Labels
+
+TODO: describe a workflow with `blocked` as a flag that removes any `status`
+
+### Example: Release Workflow
+
+TODO: describe a workflow with `status` state and `next`/`release` flags