docs(terraform): update terraform docs per feedback

content/en/docs/components/orchestration/infrastructure/terraform.md

@@ -15,7 +15,7 @@ description: >
 * **Last Updated**: 2025-11-26
 * **TODO**:
   * [x] Add detailed component description
-  * [ ] Include usage examples and code samples
+  * [x] Include usage examples and code samples
   * [ ] Add architecture diagrams
   * [ ] Review and finalize content
 * **Review**:
@@ -67,33 +67,42 @@ Alternatively, manually trigger automated [deployment pipeline](https://edp.buil
 - You will be asked for essential information like the deployment name and tenant.
 - Any fields marked `INITIAL` only need to be set when first creating an environment
 - Thereafter, the cached values are used and the `INITIAL` values provided to the pipeline are ignored.
+    - Specifically, they are cached in a `terragrunt.values.hcl` file within `infra-deploy/<tenant>/<cluster-name>`, where both variables are set in the pipeline
+    - e.g. [prod/edp](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp/terragrunt.values.hcl) or [nonprod/garm-provider-test](https://edp.buildth.ing/DevFW/infra-deploy/src/commit/189632811944d3d3bc41e26c09262de8f215f82b/non-prod/garm-provider-test/terragrunt.values.hcl)
 
 ### Verification
 
-> Stephan: 1. Typo: prod and non prod are the same domain name
-> Stephan: 2. Pls provide a link into the config where <cluster-name> is specified
+After the deploymenet completes, and a short startup time, you should be able to access your Forgejo instance at `<cluster-name>.buildth.ing` (production tenant) or `<cluster-name>.t09.de` (non-prod tenant). `<cluster-name>` is the name you provided in the deployment pipeline, or the $CLUSTER_ENVIRONMENT variable when running manually.
 
-After the deploymenet completes, and a short startup time, you should be able to access your Forgejo instance at `<cluster-name>.buildth.ing` (production tenant) or `<cluster-name>.buildth.ing` (non-prod tenant). For example, the primary production cluster is called [edp](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp) and can be accessed at [edp.buildth.ing](https://edp.buildth.ing).
+For example, the primary production cluster is called [edp](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp) and can be accessed at [edp.buildth.ing](https://edp.buildth.ing).
 
 #### Screens
 
-> Stephan: Perhaps some significant screenshots here from the CLI, OTC (during deployment), pipeline logs ... otherweise we will forget what it looked like on our machines in 2025 ;-)
- 
+Deployment using production pipeline:
+
+![Running the deployment pipeline](../deploy-pipeline.png)
+...
+![Successful deploy pipeline logs](../deploy-pipeline-success.png)
+
 ## Configuration
 
-> Stephan: perhaps another link to the READMEs how config is done?
+Configuration of clusters is done in two ways. The first, mentioned above, is to provide `INITIAL` configuration when creating a new cluster. Thereafter, configuration is done within the relevant `infra-deploy/<tenant>` directory (e.g. [prod/edp](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp)). Variables may be changed within the [terragrunt.values.hcl](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp/terragrunt.values.hcl) file, but equally the [terragrunt.stack.hcl](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp/terragrunt.stack.hcl) file contains references to the lower-level code set up in `infra-catalogue`.
 
-[Key configuration options and how to set them]
+These are organised in layers, according to Terragrunt's natural structure. First is a [stack](https://edp.buildth.ing/DevFW/infra-catalogue/src/branch/main/stacks), a high-level abstraction for a whole cluster. This in turn [references](https://edp.buildth.ing/DevFW/infra-catalogue/src/branch/main/stacks/forgejo/terragrunt.stack.hcl) terragrunt [units](https://edp.buildth.ing/DevFW/infra-catalogue/src/branch/main/units), which in turn are wrappers around standard _Terraform_ [modules](https://edp.buildth.ing/DevFW/infra-catalogue/src/branch/main/modules).
+When deployed, the Terraform modules require a `provider.tf` file which is automatically generated by Terragrunt using [tenant-level](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/tenant.hcl) and [global](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/root.hcl) configuration stored in `infra-deploy`.
+
+When deploying manually (e.g. with [install.sh](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/install.sh)), you can observe these layers as Terragrunt will cache them on your machine, within the `.terragrunt-stack/` directory generated within [/\<tenant\>/\<cluster-name\>/](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp).
 
 ## Troubleshooting
 
-### [Common Issue 1]
+### Version updates
 
-> Stephan: are there problems left with versioning?
+**Problem**: Updates to `infra-catalogue` are not immediately reflected in deployed clusters, even after running [deploy](https://edp.buildth.ing/DevFW/infra-deploy/actions?workflow=deploy.yaml).
 
-**Problem**: [Description]
+**Solution**: Versions must be updated.
+Each cluster deployment specifies a [catalogue version](https://edp.buildth.ing/DevFW/infra-deploy/src/commit/189632811944d3d3bc41e26c09262de8f215f82b/prod/edp/terragrunt.values.hcl#L7) in its `terragrunt.values.hcl`; this refers to a tag in [infra-catalogue](https://edp.buildth.ing/DevFW/infra-catalogue/releases/tag/v2.0.6). Within `infra-catalogue`, stacks reference units and modules from the same tag.
 
-**Solution**: [How to fix]
+Thus, to test a new change to `infra-catalogue`, first make a new [tag](https://edp.buildth.ing/DevFW/infra-catalogue/tags), then update the relevant [values file](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp/terragrunt.values.hcl) to point to it.
 
 
 ## Status
@@ -102,13 +111,6 @@ After the deploymenet completes, and a short startup time, you should be able to
 
 ## Additional Resources
 
-> Stephan: perhaps terraform/terragrunt links?
-
-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-Unsure if remaining sections are useful.
-> Stephan: I removed sections which I also don't see useful, and added hints/ideas for content to the rest
+- [Terraform](https://developer.hashicorp.com/terraform)
+- [OpenTofu](https://opentofu.org/), the community-driven replacement for Terraform
+- [Terragrunt](https://terragrunt.gruntwork.io/)