fix: Adjusting run-all docs (#3589)

* fix: Adjusting `run-all` docs

* fix: Markdown linting

docs/_docs/01_getting-started/add-to-opentofu-project.md

@@ -343,7 +343,7 @@ Group 2
 08:57:09.936 ERROR  Unable to determine underlying exit code, so Terragrunt will exit with error code 1
 ```
 
-Oh no! We got an error. This is because the way in which dependencies are resolved by default in Terragrunt is to run `terragrunt output` within the dependent unit in order to fetch them for the dependent unit. In this case, the `foo` unit has not been applied yet, so there are no outputs to fetch.
+Oh no! We got an error. This is because the way in which dependencies are resolved by default in Terragrunt is to run `terragrunt output` within the dependency for use in the dependent unit. In this case, the `foo` unit has not been applied yet, so there are no outputs to fetch.
 
 You should notice, however, that Terragrunt has already figured out the order in which to run the `plan` command across the units in your stack. This is what we mean when we say that Terragrunt uses a DAG to determine the order in which to run commands across your stack. Terragrunt analyzes the dependencies across your units, and determines the order in which to run updates so that outputs are ready to be used as inputs in dependent units.
 

docs/_docs/04_reference/cli-options.md

@@ -139,14 +139,13 @@ Run `terraform --help` to get the full list.
 
 ### run-all
 
-Runs the provided OpenTofu/Terraform command against a `stack`, where a `stack` is a
-tree of terragrunt modules. The command will recursively find terragrunt
-modules in the current directory tree and run the OpenTofu/Terraform command in
-dependency order (unless the command is destroy, in which case the command is
-run in reverse dependency order).
+Runs the provided OpenTofu/Terraform command against a [stack](/docs/getting-started/terminology/#stack).
+The command will recursively find terragrunt [units](/docs/getting-started/terminology/#unit) in the current directory
+tree and run the OpenTofu/Terraform command in dependency order (unless the command is destroy,
+in which case the command is run in reverse dependency order).
 
 Make sure to read [Execute OpenTofu/Terraform
-commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-modules-at-once/) for
+commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-units-at-once/) for
 context.
 
 Example:
@@ -155,27 +154,46 @@ Example:
 terragrunt run-all apply
 ```
 
-This will recursively search the current working directory for any folders that contain Terragrunt modules and run
+This will recursively search the current working directory for any folders that contain Terragrunt units and run
 `apply` in each one, concurrently, while respecting ordering defined via
 [`dependency`](/docs/reference/config-blocks-and-attributes/#dependency) and
 [`dependencies`](/docs/reference/config-blocks-and-attributes/#dependencies) blocks.
 
-**[WARNING] Using `run-all` with `plan` is currently broken for certain use cases**. If you have a stack of Terragrunt
-modules with dependencies between them—either via `dependency` blocks or `terraform_remote_state` data sources—and
-you've never deployed them, then `run-all plan` will fail as it will not be possible to resolve the `dependency` blocks
-or `terraform_remote_state` data sources! Please [see here for more
-information](https://github.com/gruntwork-io/terragrunt/issues/720#issuecomment-497888756).
+**[WARNING] Use `run-all` with care if you have unapplied dependencies**.
+
+If you have a stack of Terragrunt units with dependencies between them—either via `dependency` blocks
+or `terraform_remote_state` data sources—and
+you've never deployed them, then commands like `run-all plan` will fail,
+as it will not be possible to resolve the `dependency` blocks
+or `terraform_remote_state` data sources!
+
+The solution for this is to take advantage of [mock outputs in dependency blocks](/docs/reference/config-blocks-and-attributes/#dependency).
+
+**[WARNING] Do not set [TF_PLUGIN_CACHE_DIR](https://opentofu.org/docs/cli/config/config-file/#provider-plugin-cache) when using `run-all`**
+
+Instead take advantage of the built-in [Provider Cache Server](https://terragrunt.gruntwork.io/docs/features/provider-cache/) that
+mitigates some of the limitations of using the OpenTofu/Terraform Provider Plugin Cache directly.
+
+Note that we are [working with the OpenTofu team to improve this behavior](https://github.com/opentofu/opentofu/issues/1483) so that you don't have to worry about this.
 
 **[NOTE]** Using `run-all` with `apply` or `destroy` silently adds the `-auto-approve` flag to the command line
-arguments passed to OpenTofu/Terraform due to issues with shared `stdin` making individual approvals impossible. Please
-[see here for more information](https://github.com/gruntwork-io/terragrunt/issues/386#issuecomment-358306268)
+arguments passed to OpenTofu/Terraform due to issues with shared `stdin` making individual approvals impossible.
+
+**[NOTE]** Using the OpenTofu/Terraform [-detailed-exitcode](https://opentofu.org/docs/cli/commands/plan/#other-options)
+flag with the `run-all` command results in an aggregate exit code being returned, rather than the exit code of any particular unit.
+
+The algorithm for determining the aggregate exit code is as follows:
+
+- If any unit throws a 1, Terragrunt will throw a 1.
+- If any unit throws a 2, but nothing throws a 1, Terragrunt will throw a 2.
+- If nothing throws a non-zero, Terragrunt will throw a 0.
 
 ### plan-all (DEPRECATED: use run-all)
 
 **DEPRECATED: Use `run-all plan` instead.**
 
 Display the plans of a `stack` by running `terragrunt plan` in each subfolder. Make sure to read [Execute OpenTofu/Terraform
-commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-modules-at-once/) for
+commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-units-at-once/) for
 context.
 
 Example:
@@ -200,7 +218,7 @@ information](https://github.com/gruntwork-io/terragrunt/issues/720#issuecomment-
 **DEPRECATED: Use `run-all apply` instead.**
 
 Apply a `stack` by running `terragrunt apply` in each subfolder. Make sure to read [Execute OpenTofu/Terraform
-commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-modules-at-once/) for
+commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-units-at-once/) for
 context.
 
 Example:
@@ -223,7 +241,7 @@ information](https://github.com/gruntwork-io/terragrunt/issues/386#issuecomment-
 **DEPRECATED: Use `run-all output` instead.**
 
 Display the outputs of a `stack` by running `terragrunt output` in each subfolder. Make sure to read [Execute OpenTofu/Terraform
-commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-modules-at-once/) for
+commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-units-at-once/) for
 context.
 
 Example:
@@ -248,7 +266,7 @@ information](https://github.com/gruntwork-io/terragrunt/issues/720#issuecomment-
 **DEPRECATED: Use `run-all destroy` instead.**
 
 Destroy a `stack` by running `terragrunt destroy` in each subfolder. Make sure to read [Execute OpenTofu/Terraform
-commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-modules-at-once/) for
+commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-units-at-once/) for
 context.
 
 Example:
@@ -271,7 +289,7 @@ information](https://github.com/gruntwork-io/terragrunt/issues/386#issuecomment-
 **DEPRECATED: Use `run-all validate` instead.**
 
 Validate `stack` by running `terragrunt validate` in each subfolder. Make sure to read [Execute OpenTofu/Terraform
-commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-modules-at-once/) for
+commands on multiple modules at once](/docs/features/execute-terraform-commands-on-multiple-units-at-once/) for
 context.
 
 Example:

docs/_docs/04_reference/config-blocks-and-attributes.md

@@ -977,7 +977,7 @@ inputs = {
 The `dependency` block is used to configure module dependencies. Each dependency block exports the outputs of the target
 module as block attributes you can reference throughout the configuration. You can learn more about `dependency` blocks
 in the [Dependencies between modules
-section](/docs/features/execute-terraform-commands-on-multiple-modules-at-once/#dependencies-between-modules) of the
+section](/docs/features/execute-terraform-commands-on-multiple-units-at-once/#dependencies-between-modules) of the
 "Execute Opentofu/Terraform commands on multiple modules at once" use case overview.
 
 You can define more than one `dependency` block. Each label you provide to the block identifies another `dependency`

docs/_includes/use-cases-box.html

@@ -12,7 +12,7 @@ <h2>Use cases</h2>
         <a href="{{site.baseurl}}/docs/features/keep-your-cli-flags-dry/">Keep your CLI flags DRY</a>
       </div>
       <div class="card-link">
-        <a href="{{site.baseurl}}/docs/features/execute-terraform-commands-on-multiple-modules-at-once/">Execute OpenTofu/Terraform commands on multiple modules at once</a>
+        <a href="{{site.baseurl}}/docs/features/execute-terraform-commands-on-multiple-units-at-once/">Execute OpenTofu/Terraform commands on multiple modules at once</a>
       </div>
       <div class="card-link">
         <a href="{{site.baseurl}}/docs/features/work-with-multiple-aws-accounts/">Work with multiple AWS accounts</a>

docs/_pages/index/_key-features.html

@@ -68,7 +68,7 @@ <h3>Keep your <strong>OpenTofu/Terraform CLI</strong> arguments DRY</h3>
       <div class="col-xs-12 col-md-6">
         <h3>Execute OpenTofu/Terraform commands on <strong>multiple modules</strong> at once</h3>
         <p class="subtitle">Run one command for all modules instead of executing it in each module independently.</p>
-        <a class="btn btn-primary" href="{{site.baseurl}}/docs/features/execute-terraform-commands-on-multiple-modules-at-once/">Learn more</a>
+        <a class="btn btn-primary" href="{{site.baseurl}}/docs/features/execute-terraform-commands-on-multiple-units-at-once/">Learn more</a>
       </div>
     </div>
   </div>