Updated the docs, based on GoC feedback

GUARDRAILS.md

@@ -18,6 +18,16 @@ For this document the following definitions will be used:
 ## Applicable Service Models
 This guardrail document relates to Software as a Service (SaaS), specifically DevOps and Source Code management tools.
 
+## Guardrail Activities
+
+The `Activities` listed under each guardrail are intended to provide a high-level overview of the actions organizations should consider to achieve the desired outcome. They are not prescriptive instructions but rather guidelines that can be adapted to fit the specific needs and circumstances of each organization.
+
+While the activities offer general recommendations, the implementation details, such as the choice of specific tools or services, configuration settings, and thresholds for suspicious activity, will vary depending on factors like the organization's size, risk tolerance, and existing security infrastructure.
+
+```
+For more in-depth guidance and technical references, organizations are encouraged to consult your organization's best practices, standards, and specialized resources.
+```
+
 ## SCM Guardrails
 
 | ID. | SCM Guardrails |

README.md

@@ -2,7 +2,7 @@
 
 ## Securing Your GitHub Environment at Scale
 
-### Quick Start: [Get Started Now!](./README.md#getting-started)
+### [Get Started Now!](./README.md#getting-started)
 
 Managing GitHub for multiple groups introduces complex security and consistency challenges. Misaligned permission levels, team structures, incomplete change rollouts across groups, and status reporting are just a few of the obstacles that can manifest with manual processes.  The GitHub Foundations Toolkit offers a secure and efficient way to manage your organization's GitHub environment through automation and centralized control.
 
@@ -50,11 +50,12 @@ Initial setup of your state file backend, and creation of all organizations unde
 Management of organizations, repositories, and teams, Review results of drift detection, and execution of pull request plans for your organizations.
 
 #### Included Tools:
-- **Drift Detection:** Detects when someone makes a change to configuration, outside of the source-controlled configuration. Gives the ability to reapply the correct state.
-- **Deletion Protection:** When a PR change requests resources be deleted, this tool forces the user to confirm the action
-- **GitHub Advanced Security (GHAS) checks:** Checks the state of GHAS for the repos that have it enabled. Reports all of the GHAS scans in one report.
-- **Assessment tool:** Used to assess the readiness of your repo, before importing it with the toolkit. Can be used to check whether toolkit guardrails are already in place in the repo.
-- **Import tool:** Import repos not currently managed by the toolkit.
+- [**Interactive HCL tool:**](./organizations/GEN_INTERACTIVE.md) A CLI tool to help you write HCL interactively for `repositories` and `teams`.
+- [**Drift Detection:**](./organizations/DRIFT_DETECTION.md) Detects when someone makes a change to configuration, outside of the source-controlled configuration. Gives the ability to reapply the correct state.
+- [**Deletion Protection:**](./organizations/DELETION_PROTECTION.md) When a PR change requests resources be deleted, this tool forces the user to confirm the action
+- [**GitHub Advanced Security (GHAS) checks:**](./organizations/GH_ADVANCED_SECURITY.md) Runs GHAS scans for the eligible repos that have it enabled. Reports all of the GHAS scans in one report.
+- [**Assessment tool:**](./organizations/ASSESSMENT_TOOL.md) Used to assess the readiness of your repo, before importing it with the toolkit. Can be used to check whether toolkit guardrails are already in place in the repo.
+- [**Import tool:**](./organizations/IMPORT_TOOL.md) Import repos not currently managed by the toolkit.
 
 
 ## How to Contribute

organizations/ASSESSMENT_TOOL.md

@@ -0,0 +1,19 @@
+([Back](../README.md#included-tools))
+
+# Assessment Tool
+
+The `Assessment Tool` allows you to assess the readiness of your pre-existing GitHub `repository`, before importing it with the toolkit.
+It is used to check whether toolkit guardrails are already in place in the `repository`, as well as any settings required at the `organization` level.
+
+## Running the Assessment Tool
+
+The `Assessment Tool` is available as part of the `GitHub Foundations CLI` tool, found [here](https://github.com/FociSolutions/github-foundations-cli/releases)
+
+To run an assessment check on a repository, run the following command:
+
+```bash
+    Usage:
+    gh_foundations check <org-slug>
+```
+
+`<org-slug>` is the organization slug to check. See the [documentation](https://github.com/FociSolutions/github-foundations-cli/blob/main/README.md#check) for more information.

organizations/DELETION_PROTECTION.md

@@ -0,0 +1,30 @@
+([Back](../README.md#included-tools))
+
+# Deletion Protection
+
+The `Deletion Protection` tool is automatically installed on all GitHub Foundations organizations.
+
+`Deletion Protection` is a feature that helps to prevent accidental deletion of resources. When a resource is removed from the Terraform configuration, a mechanism kicks-in to ask for confirmation before the resource is deleted. It is implemented as a GitHub Action that is invoked when a Pull Request (PR) into the default branch is opened, and works by checking for any resources that are about to be deleted and asking for confirmation before proceeding with the deletion.
+
+## Confirmation
+
+When a PR is opened that deletes resources, the `Deletion Protection` tool will comment on the PR with a message telling the user:
+
+```bash
+#### ⚠️ The Terraform Plan contains ${process.env.DELETIONS} Deletion(s) ⚠️
+            Please review the plan and ensure that the deletions are expected.
+
+            If the deletions are expected, you must:
+
+              1. Create a new comment on this PR.
+              2. Set the contents to 'delete' (no quotes)
+              3. Press the comment button.
+
+            before you can merge.
+```
+
+The status of the PR Review is then set to `Changes Requested` until the user follows the instructions and confirms the deletions.
+
+The user should review the plan, which is also a comment on the PR, and if the deletions are expected, they should create a new comment on the PR with the contents: `delete`.
+
+Once the user has confirmed the deletions, the status of the PR Review is set to `Approved`.

organizations/DRIFT_DETECTION.md

@@ -1,3 +1,5 @@
+([Back](../README.md#included-tools))
+
 # Drift Detection
 
 The `Drift Detection` tool is automatically installed on all GitHub Foundations organizations.

organizations/GEN_INTERACTIVE.md

@@ -0,0 +1,21 @@
+([Back](../README.md#included-tools))
+
+# Interactive `Generate` Tool
+
+The `Generate` tool is a CLI tool to help you write HCL interactively for `repositories` and `teams`.
+
+## Running the Generate Tool
+
+The Generate Tool is available as part of the `GitHub Foundations CLI` tool, found [here](https://github.com/FociSolutions/github-foundations-cli/releases). To run the Generate Tool, run the following command:
+
+```bash
+Usage:
+    github-foundations-cli gen <resource>
+````
+
+Where `<resource>` is one of the following:
+
+* `repository_set`
+* `team_set`
+
+See the [documentation](https://github.com/FociSolutions/github-foundations-cli?tab=readme-ov-file#generate) for more information.

organizations/GH_ADVANCED_SECURITY.md

@@ -0,0 +1,27 @@
+([Back](../README.md#included-tools))
+
+# GitHub Advanced Security (GHAS) checks
+
+The `GHAS Checks` tool is automatically installed on all GitHub Foundations organizations.
+
+It runs [GitHub Advanced Security (GHAS)](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) scans for eligible repositories that have it enabled and reports all of the GHAS scans in one report. It is implemented as a GitHub Action that runs on a cron schedule (02:00 daily), and works by checking for any repositories that have GHAS enabled and running a scan on them.
+
+## Changing the Schedule
+
+The schedule for the `GHAS Checks` tool can be changed by modifying the `schedule` field in the `.github/workflows/ghas-policy-check.yml` file.
+
+```yaml
+on:
+  schedule:
+    - cron: '0 2 * * *'
+```
+
+The schedule is set to run at 02:00 daily by default.
+To learn how cron schedules work, see the [GitHub Actions documentation](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule).
+
+## Repository Eligibility
+
+To be eligible for a GHAS scan, the repository must have GHAS enabled. A repository can have GHAS enabled if:
+
+1. The repository is public.
+2. The repository is private and GHAS has been purchased.

organizations/IMPORT_TOOL.md

@@ -0,0 +1,17 @@
+([Back](../README.md#included-tools))
+
+# Import Tool
+
+An Import tool is provided with the [GitHub Foundations CLI](https://github.com/FociSolutions/github-foundations-cli). This tool will start an interactive process to import resources into Terraform state. It uses the results of a terraform plan to determine which resources are available for import.
+
+
+To run an import check for a repository, run the following command:
+
+```bash
+Usage:
+    github-foundations-cli import [module_path]
+```
+
+Where `<module_path>` is the path to the Terragrunt module to import.
+
+For more information, see the [documentation](https://github.com/FociSolutions/github-foundations-cli?tab=readme-ov-file#import).

organizations/README.md

@@ -12,6 +12,7 @@
       * [Secret Management](#secret-management)
    * [Running the Organizations Layer locally](#running-the-organizations-layer-locally)
       * [Prerequisites](#prerequisites)
+   * [Pre-installed tools](#pre-installed-tools)
 
 
 ## Introduction
@@ -171,6 +172,12 @@ Before running the organizations layer, please ensure you have the following pre
 * GCP CLI: [https://cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install)
 * GCP IAM Roles: [https://cloud.google.com/iam/docs/understanding-roles](https://cloud.google.com/iam/docs/understanding-roles)
 
-## Drift Detection
+## Pre-installed tools
 
-The GitHub Foundations toolkit comes with a [drift-detection](./DRIFT_DETECTION.md) tool pre-installed. For more information, see the [documentation here](./DRIFT_DETECTION.md)
+The GitHub Foundations toolkit comes with:
+* A [Drift Detection](./DRIFT_DETECTION.md) tool
+* An [Interactive HCL generation](./GEN_INTERACTIVE.md) tool
+* A [Deletion Protection](./DELETION_PROTECTION.md) tool
+* [GitHub Advanced Security (GHAS) checks](./GH_ADVANCED_SECURITY.md)
+* An [Assessment](./ASSESSMENT_TOOL.md) tool
+* An [Import](./IMPORT_TOOL.md) tool