docs: improve examples/complete + overall docs (#41)

* chore: updates examples w/ more full use-case

* chore: updates complete example to use policies module

* chore: adds video intro for spacelift-automation

* fix: add `some j` for looping tracked extensions

README.md

@@ -6,7 +6,9 @@ This Terraform child module provides infrastructure automation for projects in [
 
 ## Overview
 
-The `spacelift-automation` root module is designed to streamline the deployment and management of all Spacelift infrastructure, including creating a Spacelift Stack to manage itself.
+This `spacelift-automation` child module is designed to streamline the deployment and management of all Spacelift infrastructure, including creating a Spacelift Stack to manage itself.
+
+Check out our quick introduction to this child module here: [![[External] terraform-spacelift-automation quick intro - Watch Video](https://cdn.loom.com/sessions/thumbnails/8de21afb732048a58fdee90042b4840f-11908d1d42de3247-full-play.gif)](https://www.loom.com/share/8de21afb732048a58fdee90042b4840f)
 
 It automates the creation of "child" stacks and all the required accompanying Spacelift resources. For each enabled root module it creates:
 
@@ -37,7 +39,7 @@ Structure requirements:
 - Stack config files and tfvars files must be equal to OpenTofu/Terraform workspace, e.g. `stacks/dev.yaml` and `tfvars/dev.tfvars` for a workspace named `dev`.
 - Common configs are placed in `<root_modules_path>/<root_module>/stacks/common.yaml` file (or `var.common_config_file` value). This is useful when you know that some values should be shared across all the stacks created for a root module. For example, all stacks that manage Spacelift Policies must use the `administrative: true` setting or all stacks must share the same labels.
 
-We have an example of this structure in the [examples/complete](./examples/complete/components/), which looks like the following:
+We have an example of this structure in the [examples/complete](./examples/complete/root-modules/), which looks like the following:
 
 ```sh
 ├── root-modules
@@ -179,7 +181,7 @@ Spacelift Automation can manage itself as a Stack as well, and we recommend this
 4. Move the Automation configs to the `<root-modules>/spacelift-automation/stacks` directory and push the changes to the tracked repo and branch.
 5. After pushed to your repo's tracked branch, Spacelift Automation will track the addition of new root modules and create Stacks for them.
 
-Check out an example configuration in the [examples/complete](./examples/complete/components/spacelift-automation/tfvars/example.tfvars).
+Check out an example configuration in the [examples/complete](./examples/complete/root-modules/spacelift-automation/tfvars/example.tfvars).
 
 <!-- NOTE to Masterpoint team: We might want to create a small wrapper to automatize this using Taskit. On hold for now. -->
 

examples/complete/README.md

@@ -1,8 +1,8 @@
 # Complete Example
 
-This example demonstrates how to use the spacelift-automation component to manage Spacelift stacks, including the ability for Spacelift to manage its own configuration.
+This example demonstrates how to use the spacelift-automation child-module as a root-module to manage Spacelift stacks, including the ability for Spacelift to manage its own configuration.
 
-Normally, this directory would contain a simple root module to spin up a basic example. To showcase a more practical use case where Spacelift manages its own infrastructure, we’ve moved the configuration to the expected path: [examples/complete/components/spacelift-automation/](./components/spacelift-automation/).
+Normally, this directory would contain a simple root module to spin up a basic example. To showcase a more practical use case where Spacelift manages its own infrastructure, we’ve moved the configuration to the expected path: [examples/complete/root-modules/spacelift-automation/](./root-modules/spacelift-automation/).
 
 By doing this, we provide an example of how to set up Spacelift to automate the management of your infrastructure stacks, including itself.
 
@@ -11,28 +11,35 @@ By doing this, we provide an example of how to set up Spacelift to automate the
 1. Prerequisites:
    - Replace the following configuration files with your own values:
      - `backend.tf.json`: Configure your Terraform backend settings
-     - `example.tfvars`: Set your Spacelift configuration variables
-     - `example.yaml`: Define your stack configuration
+     - `main.tf`: Because this root module only has one instance, we manage the variables passed to it via the `main.tf` file. You'll want to change those values to match your own.
+     - `stacks/common.yaml`: Define your stack configuration
        > **Important:** These files may contain sensitive information. Ensure you:
        >
        > - Remove any hardcoded credentials or sensitive values
        > - Have appropriate Spacelift ([`SPACELIFT_API_KEY_*`](https://docs.spacelift.io/concepts/spacectl#spacelift-api-keys) environment variables) and AWS permissions
        > - Follow your organization's security practices
-2. Navigate to the spacelift-automation component directory:
+2. Navigate to the spacelift-automation root-modules directory:
+
    ```sh
-   cd ./components/spacelift-automation/
+   cd ./root-modules/spacelift-automation/
    ```
+
 3. Initialize Terraform:
+
    ```sh
    tofu init
    ```
-4. Select the worspace:
+
+4. Review the Terraform plan:
+
    ```sh
-   tofu workspace select example
+   tofu plan
    ```
-5. Review the Terraform plan:
+
+5. Apply the Terraform plan:
+
    ```sh
-   tofu plan -var-file tfvars/example.tfvars
+   tofu apply
    ```
 
-This will set up the Spacelift stack that manages itself.
+This will set up the Spacelift Stack that manages itself and the rest of the Stacks in the root-modules directory as well.