fix(docs): describe state changes, values, and remote options

README.md

@@ -89,7 +89,7 @@ Options:
   --remote, -r                                               [string] [required]
 ```
 
-Docker provides a single output stream, regardless of logger configuration. When running `graph-labes`, turning
+Docker provides a single output stream, regardless of logger configuration. When running `graph-labels`, turning
 the `logger.level` to `warn` or `error` will suppress log messages that could confuse `dot`.
 
 ### Running with Yarn

docs/arch.md

@@ -6,40 +6,54 @@ This guide describes the program architecture.
 
 - [Architecture Guide](#architecture-guide)
   - [Contents](#contents)
-  - [Purpose](#purpose)
-  - [Label](#label)
-    - [Flag Label](#flag-label)
-    - [State Label](#state-label)
-      - [State Value](#state-value)
+  - [Summary](#summary)
+  - [Labels](#labels)
+    - [Flag Labels](#flag-labels)
+      - [Change Sets](#change-sets)
+    - [State Labels](#state-labels)
+      - [State Values](#state-values)
       - [State Changes](#state-changes)
   - [Remote](#remote)
     - [Github Remote](#github-remote)
     - [Gitlab Remote](#gitlab-remote)
   - [Sync](#sync)
     - [Sync Issues](#sync-issues)
-    - [Sync Labels](#sync-labels)
+    - [Sync Projects](#sync-projects)
 
-## Purpose
+## Summary
 
-`cautious-journey` exists to manage labels and their workflow.
+`cautious-journey` is a label manager and state machine for remote APIs. It creates and updates labels to match
+the configuration, can replace labels to create complex workflows, and supports multiple projects with shared or
+unique labels.
 
-## Label
+## Labels
 
-While `cautious-journey` reads issue data, labels are what it cares about.
+Labels come in two varieties: individual flags and mutually-exclusive states. These are equivalent to
+checkboxes and radio groups in web forms, with the state changes between values forming a state machine within
+each group of state labels.
 
-### Flag Label
+### Flag Labels
 
-Flag labels are set individually. While they may depend on or even remove each other,
-they are not connected directly.
+Flag labels are set individually. They support basic change sets, like `adds` and `removes`. While flags are
+independent by default, they can depend on other labels in `requires`.
 
-### State Label
+#### Change Sets
 
-State labels are set from a group. Only one value from each state may be set at a time,
-and the highest priority value automatically replaces any others.
+If the flag in question is present on an issue, then:
 
-#### State Value
+- the labels listed in `adds` will be added
+- the labels listed in `removes` will be removed
 
-Individual values within the state.
+### State Labels
+
+State labels are set from a group of values. Only one value from each state may be present at a time; if more than
+one value exists, the highest priority will be kept. Each value can define a set of potential state changes, which
+will replace the current value with another label (flag or state value).
+
+#### State Values
+
+State values are mutually exclusive, but are normal labels in other ways. They support basic change sets, like
+`adds` and `removes`, along with a set of potential changes in `becomes`.
 
 #### State Changes
 
@@ -75,19 +89,30 @@ labels will be promoted to `status/in-progress`, and both the `status/new` and `
 
 ## Remote
 
-`cautious-journey` manipulates issues and labels that exist on some remote service.
+`cautious-journey` typically connects to some remote service to manage labels there. You can choose which remote
+should be used for each project.
 
 ### Github Remote
 
 Connects to a Github repository.
 
-- `path`
+- `type: github-remote`
+- `data:`
+  - `type: app`
+    - `appId`
+    - `installationId`
+    - `privateKey`
+  - `type: token`
+    - `token`: personal token with `repo` scope
 
 ### Gitlab Remote
 
 Connects to a Gitlab repository.
 
-- `path`
+- `type: gitlab-remote`
+- `data:`
+  - `type: token`
+    - `token`: personal access token with `api` scope
 
 ## Sync
 
@@ -95,8 +120,11 @@ Update issue labels or the labels themselves.
 
 ### Sync Issues
 
-Update issue labels.
+Update issue labels by resolving state changes and other change sets.
 
-### Sync Labels
+### Sync Projects
 
-Update project labels.
+Update project labels to match the `flags` and `states` provided in the config.
+
+The project config is considered the source of truth when syncing projects, and the remote labels will be
+updated to match the config.