docs: Update to describe the new asset flow

docs/user/overview.md

@@ -4,7 +4,57 @@ The OpenShift Installer is designed to help users, ranging from novices to exper
 
 In [supported environments](#supported-environments), the installer is also capable of provisioning the underlying infrastructure for the cluster. It is recommended that most users make use of this functionality in order to avoid having to provision their own infrastructure. In unsupported environments or scenarios in which installer-created infrastructure would be incompatible, the installer can stop short of creating the infrastructure, and allow the user to provision their own infrastructure using the cluster assets generated by the installer.
 
-## Cluster Installation Process
+## Lifecycle
+
+### Asset Generation
+
+The first installation phase is completely local, as the installer generates the assets that will be used to create the cluster resources.
+The installer maintains an asset graph tracking dependency relations between assets.
+
+![Asset dependencies](assets.svg)
+
+This graph is generated with:
+
+```sh
+openshift-install graph | dot -Tsvg >docs/user/assets.svg
+```
+
+This is similar to other tools which operate on a dependency graph (e.g. `make` and `systemd`).
+The root target is `cluster`, and once that target is built, there is enough information to move on to [installation](#installation).
+
+Running:
+
+```sh
+openshift-install --dir example create assets
+```
+
+will render the asset graph into the `example` directory.
+The installer will pick reasonable defaults where possible, and prompt the user for assets where we cannot find a reasonable default for all users.
+To avoid being prompted, you can pass your choices into the installer using [environment variables](environment-variables.md).
+
+Each asset is represented by two files, one in the asset directory itself, and another in its `.state` subdirectory.
+The entry in the `.state` subdirectory holds the rendered JSON `Asset` structure, containing the asset's raw data along with associated metadata (parent references, etc.).
+The entry in the asset directory holds the asset's raw data without the associated metadata.
+
+The installer uses the JSON state files to preserve asset information between invocations, but editing the JSON payload is an awkward way to make manual adjustments.
+The raw data files are provided as a more convenient avenue for user adjustments.
+
+To adjust a particular asset, you can edit the raw data file and rerun `openshift-install ... create assets`.
+For example:
+
+```sh
+openshift-install --dir example create assets
+sed -i 's|^\(OPENSHIFT_HYPERSHIFT_IMAGE\)=.*|\1=quay.io/your/hypershift:123|' example/bootkube.sh
+openshift-install --dir example create assets
+```
+
+will rebuild the asset graph using your custom HyperShift image in `bootkube.sh`.
+
+You can continue to edit and run `openshift-install ... create assets` as many times as you like.
+To return to the installer's built-in logic for an asset, remove its `.state/{slugged-asset-name}` file (it doesn't matter if you also remove the associated raw data file or not).
+When you are satisfied with the asset store, move on to installation.
+
+### Installation
 
 OpenShift is unique in that its management extends all the way down to the operating system itself. Every machine boots with a configuration which references resources hosted in the cluster its joining. This allows the cluster to manage itself as updates are applied. A downside to this approach, however, is that new clusters have no way of starting without external help - every machine in the to-be-created cluster is waiting on the to-be-created cluster.
 
@@ -25,31 +75,19 @@ The result of this bootstrapping process is a fully running OpenShift cluster. T
 
 [ignition]: https://github.com/coreos/ignition/blob/master/doc/getting-started.md
 
-## Key Concepts
-
-While striving to remain simple and easy to use, the installer allows many aspects of the clusters it creates to be customized. It is helpful to understand certain key concepts before attempting to customize the installation.
-
-### Targets
-
-The OpenShift Installer operates on the notion of creating and destroying targets. Similar to other tools which operate on a graph of dependencies (e.g. make, systemd), each target represents a subset of the dependencies in the graph. The main target in the installer creates a cluster, but the other targets allow the user to interrupt this process and consume or modify the intermediate artifacts (e.g. the Kubernetes manifests that will be installed into the cluster). Only the immediate dependencies of a target are written to disk by the installer, but the installer can be invoked [multiple times](#multiple-invocations).
-
-The following targets can be created by the installer:
-
-- `install-config` - The install config contains the main parameters for the installation process. This configuration provides the user with more options than the interactive prompts and comes pre-populated with default values.
-- `manifests` - This target outputs all of the Kubernetes manifests that will be installed on the cluster.
-- `ignition-configs` - These are the three Ignition Configs for the bootstrap, master, and worker machines.
-- `cluster` - This target provisions the cluster by invoking a locally-installed Terraform.
-
-The following targets can be destroyed by the installer:
+### Teardown
 
-- `cluster` - This destroys the created cluster and its associated infrastructure.
-- `bootstrap` - This destroys the bootstrap infrastructure.
+You can manually remove the bootstrap infrastructure with:
 
-### Multiple Invocations
+```sh
+openshift-install ... destroy bootstrap
+```
 
-In order to allow users to customize their installation, the installer can be invoked multiple times. The state is stored in a hidden file in the target directory and contains all of the intermediate artifacts. This allows the installer to pause during the installation and wait for the user to modify intermediate artifacts.
+And you can remove the entire cluster with:
 
-For example, if changes to the install config were desired (e.g. the number of worker machines to create), the user would first invoke the installer with the `install-config` target: `openshift-install create install-config`. After prompting the user for the base parameters, the installer writes the install config into the target directory. The user can then make the desired modifications to the install config and invoke the installer with the `cluster` target: `openshift-install create cluster`. The installer will consume the install config from disk, removing it from the target directory, and proceed to create a cluster using the provided configuration.
+```sh
+openshift-install ... destroy cluster
+```
 
 ## Supported Environments