chore: document resource hierarchy

README.md

@@ -4,28 +4,28 @@ A TUI application for terraform power users.
 
 * Perform tasks in parallel (plan, apply, init, etc)
 * Manage state resources
-* Task queueing
+* Task scheduling
 * Supports tofu as well as terraform
 * Supports workspaces
 * Backend agnostic
 
 ![Applying runs](./demos/runs/applied_runs.png)
 
-## Modules
+## Demos
+
+### Modules
 
 Invoke `init`, `validate`, and `fmt` across multiple modules.
 
 ![Modules demo](https://vhs.charm.sh/vhs-1OjhjSRfyrCSJ6jzgurJi6.gif)
 
-*Note: what pug calls a module is equivalent to a [root module](https://developer.hashicorp.com/terraform/language/modules#the-root-module), i.e. a directory containing terraform configuration, including a backend definition. It is not to be confused with a [child module](https://developer.hashicorp.com/terraform/language/modules#child-modules).*
-
-## Workspaces
+### Workspaces
 
 Pug supports workspaces. Invoke plan and apply on workspaces. Change the current workspace for a module.
 
 ![Workspaces demo](https://vhs.charm.sh/vhs-mjzb63TfXTuHRwYJplgCO.gif)
 
-## Runs
+### Runs
 
 Create multiple plans and apply them in parallel.
 
@@ -35,13 +35,13 @@ View the output of plans and applies.
 
 ![Run demo](https://vhs.charm.sh/vhs-5DzLqkFlGzvcjiBnlq9wFz.gif)
 
-## State management
+### State management
 
 Manage state resources. Taint, untaint and delete multiple resources. Select resources for targeted plans.
 
 ![State demo](https://vhs.charm.sh/vhs-1k4ANzaRBWzy5xDNdfX0h3.gif)
 
-## Tasks
+### Tasks
 
 All invocations of terraform are represented as a task.
 
@@ -153,8 +153,44 @@ There are several types of resources in pug:
 * tasks
 
 A task can be belong to a run, a workspace, or a module. A run belongs to a workspace. And a workspace belongs to a module.
+
+### Modules
 
-## Scheduling
+*Note: what Pug calls a module is equivalent to a [root module](https://developer.hashicorp.com/terraform/language/modules#the-root-module), i.e. a directory containing terraform configuration, including a state backend. It is not to be confused with a [child module](https://developer.hashicorp.com/terraform/language/modules#child-modules).*
+
+A module is a directory of terraform configuration with a backend configuration. When Pug starts up, it looks recursively within the working directory, walking each directory and parsing any terraform configuration it finds. If the configuration contains a [state backend definition](https://developer.hashicorp.com/terraform/language/settings/backends/configuration) then Pug loads the directory as a module.
+
+Pug also checks if the module contains a `.terraform` directory. If it does not then the module is marked as *uninitialized*, because `terraform init` needs to be run before it can be deemed *initialized*.
+
+Each module has zero or more workspaces. Following successful initialization the module has at least one workspace, named `default`. One workspace is set as the *current workspace* for the module. When you create a run on a module, the run is created on its current workspace. The latest run on its current workspace is set as the *current run* for the module.
+
+If you add/remove modules outside of Pug, you can instruct Pug to reload modules by pressing `Ctrl-r` on the modules listing.
+
+### Workspaces
+
+A workspace is directly equivalent to a [terraform workspace](https://developer.hashicorp.com/terraform/language/state/workspaces).
+
+When a module is loaded for the first time, Pug automatically creates a task to run `terraform workspace list`, to retrieve the list of workspaces for the module.
+
+When a workspace is loaded into Pug for the first time, it'll create a task that invokes `terraform show -json`, to retrieve the workspace's state.
+
+If you add/remove workspaces outside of Pug, you can instruct Pug to reload workspaces by pressing `Ctrl-w` on a module.
+
+### Runs
+
+A run represents a terraform plan and the optional apply of that plan. Under the hood, it invokes `terraform plan -out <plan-file>`. Should you then apply the run, it invokes `terraform apply <plan-file>`.
+
+A run starts in the `pending` state. If its workspace doesn't have a current run, then Pug transitions it into the `scheduled` state and sets it as the workspace's current run. Otherwise the run remains in the `pending` state until the current run has finished.
+
+If there are no blocked tasks running on its workspace and module (see tasks below) then the run transitions into the `plan queued` state. Once there is sufficient task capacity, the run enters the `planning` state, and `terraform plan` is invoked.
+
+Once `terraform plan` completes, it enters one of several states depending upon the outcome of that task. If there were no changes, then it enters the `no changes` termination state, otherwise it enters the `planned` state.
+
+When you apply a run, it enters the `apply queued` state. Once there is sufficient task capacity, the run enters the `applying` state and `terraform apply` is invoked. Upon success it enters the `applied` state. Pug then automatically creates a task to invoke `terraform show -json`, to retrieve the workspace's updated state. 
+
+A run can be canceled at any stage. If it is `planning` or `applying` then the current terraform process is sent a termination signal. Otherwise, in any other non-terminated state, the run is immediately set as `canceled`.
+
+### Tasks
 
 Each invocation of terraform is represented as a task. A task belongs either to a run, a workspace, or a module.
 
@@ -166,14 +202,8 @@ An exception to this rule are tasks which are classified as *immediate*. Immedia
 
 A task can further be classed as *exclusive*. These tasks are globally mutually exclusive and cannot run concurrently. The only task classified as such is the `init` task, and only when you have enabled the [provider plugin cache](https://developer.hashicorp.com/terraform/cli/config/config-file#provider-plugin-cache) (the plugin cache does not permit concurrent writes).
 
-## Automatic tasks
-
-Pug automatically creates particular tasks.
-
-When a module is loaded into pug for the first time, it'll create a task that invokes `terraform workspace list`, to search for workspaces belonging to the module. Any workspaces it finds are loaded into pug.
-
-When a workspace is loaded into pug for the first time, it'll create a task that invokes `terraform show -json`, to retrieve the workspace's state. This task is also created after each successful apply.
+A task can be canceled at any stage. If it is `running` then the current terraform process is sent a termination signal. Otherwise, in any other non-terminated state, the task is immediately set as `canceled`.
 
 ## Tofu support
 
-To use tofu instead of terraform, set `--program=tofu`.
+To use `tofu` instead of `terraform`, set `--program=tofu`.