diff --git a/.github/ISSUE_TEMPLATE/pre-work-template-devops-security.md b/.github/ISSUE_TEMPLATE/pre-work-template-devops-security.md
index 05bfa63..47bca1c 100644
--- a/.github/ISSUE_TEMPLATE/pre-work-template-devops-security.md
+++ b/.github/ISSUE_TEMPLATE/pre-work-template-devops-security.md
@@ -38,7 +38,6 @@ As a new member on the HfLA devops-security team, fill in the following fields a
 - [ ] Follow the instructions in [Creating a backend state](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#creating-backend-state) to create the S3 bucket.
 - [ ] Create the S3 bucket
 - [ ] Install Terraform locally by following the instructions of the installation guide mentioned in [Installing Terraform](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#installing-terraform)
-- [ ] Install Terraform Docs locally by following the instructions of the installation guide mentioned in [Installing Terraform docs](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#installing-terraform-docs)
 - [ ] Complete the instructions in [Clone the repository](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#clone-the-repository)
 - [ ] Submit a [new request](https://github.com/hackforla/devops-security/issues/new?assignees=&projects=&template=request-aws-iam-resources.yml) to create new AWS user account and then self-assign this issue.
 - [ ] Create a new branch from main by executing the command
@@ -79,10 +78,9 @@ If you are unable to authenticate from your local machine using the CLI, post in
 - [ ] Execute the command `terraform plan` this will output a plan replicating the same IAM resources as the devops security account. Address any failures that arise (if any).
 - [ ] Then execute the command `terraform apply` this will create all of the resources that are currently managed by Devops Security.  All of the resources created here incur zero cost.
   - [ ] **If you have cost concerns, Run a Terraform Destroy to take down all of the resources you created (don't worry, you can recreate them just as quickly). If you create resources outside of what's described in this issue, you may incur charges.**
-- [ ] Update the README using Terraform Docs to document changes
-  - [ ] ```terraform-docs -c .terraform.docs.yml .```
 - [ ] Once you have tested your changes, stage them in git with 
     - [ ] `git status` command.
     - [ ] then `git add path/to/file` (you can copy from above output for the file path).
 - [ ] Commit the changes by executing `git commit -m "brief description of changes"`.
 - [ ] Push the changes with `git push --set-upstream origin name-of-branch`
+- [ ] Once you open a pull request, CI regenerates the Terraform READMEs and pushes a `terraform-docs: automated updates…` commit to your branch. Run `git pull` before pushing again. See [Generate Terraform Docs](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#generate-terraform-docs).
diff --git a/.github/workflows/terraform-plan.yaml b/.github/workflows/terraform-plan.yaml
index 1555ced..2cbbdf4 100644
--- a/.github/workflows/terraform-plan.yaml
+++ b/.github/workflows/terraform-plan.yaml
@@ -35,3 +35,29 @@ jobs:
         path: terraform
         backend_config_file: terraform/prod.backend.tfvars
         variables: iam_only = false
+
+  terraform-docs:
+    name: Generate Terraform Docs
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.pull_request.head.ref }}
+
+    - name: Render terraform docs inside the README.md and push changes back to PR branch
+      uses: terraform-docs/gh-actions@v1.4.1
+      with:
+        find-dir: "terraform"
+        output-file: README.md
+        output-method: inject
+        git-push: "true"
+        # [skip ci] stops this README-only commit re-firing the pull_request event.
+        # That second run is attributed to github-actions[bot], which the repo's
+        # first_time_contributors approval policy gates, so every PR touching .tf
+        # needed a manual approval for a plan that was already green one commit earlier.
+        git-commit-message: "terraform-docs: automated updates to Terraform modules README.md [skip ci]"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 235fa17..19a23c9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -164,13 +164,6 @@ Use the [Official HashiCorp install instructions](https://developer.hashicorp.co
 <sub>[Back to Top](#)</sub>
 ***
 
-### **Installing Terraform docs**
-
-Follow the Terraform docs [installation guide](https://terraform-docs.io/user-guide/installation/)
-
-<sub>[Back to Top](#)</sub>
-***
-
 ## **Clone the repository**
 
 Create a new folder in your computer that will contain `hackforla` projects.
@@ -285,15 +278,11 @@ terraform destroy
 ***
 
 ### Generate Terraform Docs
-Terraform docs allow the easy updating of README files inside of Terraform directories
+The README files inside the `terraform` directories are generated by [terraform-docs](https://terraform-docs.io/). You don't need to install or run it: when you open a pull request that changes a `.tf` file, CI regenerates the READMEs and pushes a `terraform-docs: automated updates…` commit to your branch.
 
-Navigate to the directory where the changes were made
-```bash
-cd terraform # or other directory
-```
-```bash
-terraform-docs -c .terraform.docs.yml .
-```
+Run `git pull` before pushing again, or your push will be rejected.
+
+To add hand-written text to one of these READMEs, put it above the `<!-- BEGIN_TF_DOCS -->` marker. Anything between the markers is overwritten on every run.
 
 <sub>[Back to Top](#)</sub>
 ***
diff --git a/terraform/.terraform.docs.yml b/terraform/.terraform.docs.yml
deleted file mode 100755
index 0fb7630..0000000
--- a/terraform/.terraform.docs.yml
+++ /dev/null
@@ -1,71 +0,0 @@
-formatter: "markdown table" # this is required
-version: ""
-
-header-from: main.tf
-footer-from: ""
-
-recursive:
-  enabled: false
-  path: modules
-
-sections:
-  hide: []
-  show: []
-
-content: |-
-  # Overview
-  Resources created by this code repository.
-
-  {{ .Header }}
-  {{ .Modules }}
-  {{ .Resources }}
-  {{ .Inputs }}
-  {{ .Outputs }}
-  {{ .Providers }}
-  {{ .Requirements }}
-  {{ .Footer }} 
-  
-  # Directory Structure
-  Terraform directory structure
-
-  - 📁 [terraform](https://github.com/hackforla/devops-security/tree/main/terraform)
-    - 📁  [aws-custom-policies](https://github.com/hackforla/devops-security/tree/main/terraform/aws-custom-policies) - JSON configurations for customer-managed policies (AWS-managed policies are referenced by ARN and not needed here)
-        - 📁 [existing-policies](https://github.com/hackforla/devops-security/tree/main/terraform/aws-custom-policies/existing-policies) - a few of our current policy configurations for reference
-    - 📁 [modules](https://github.com/hackforla/devops-security/tree/main/terraform/modules) - reusable Terraform configurations
-    - 📄 [aws-custom-policies.tf](https://github.com/hackforla/devops-security/tree/main/terraform/modules/aws-groups) - maintain custom policies here
-    - 📄 [aws-groups.tf](https://github.com/hackforla/devops-security/tree/main/terraform/modules/aws-groups) - maintain groups here
-    - 📄 [aws-users.tf](https://github.com/hackforla/devops-security/tree/main/terraform/modules/aws-users) - maintain users here
-      
-  To automatically update this documentation, install terraform-docs on your local machine run the following: 
-  `cd <directory of README location to update>`
-  `terraform-docs -c .terraform.docs.yml .`
-output:
-  file: README.md
-  mode: replace
-  template: |-
-    <!-- BEGIN_TF_DOCS -->
-    {{ .Content }}
-    <!-- END_TF_DOCS -->    
-
-output-values:
-  enabled: false
-  from: ""
-
-sort:
-  enabled: true
-  by: name
-
-settings:
-  anchor: true
-  color: true
-  default: true
-  description: false
-  escape: true
-  hide-empty: true
-  html: true
-  indent: 2
-  lockfile: true
-  read-comments: true
-  required: true
-  sensitive: true
-  type: true
\ No newline at end of file
diff --git a/terraform/README.md b/terraform/README.md
index ba4f0fa..a7a5207 100644
--- a/terraform/README.md
+++ b/terraform/README.md
@@ -1,27 +1,66 @@
-<!-- BEGIN_TF_DOCS -->
 # Overview
 Resources created by this code repository.
 
+# Directory Structure
+Terraform directory structure
+
+- 📁 [terraform](./)
+  - 📁 [aws-custom-policies](aws-custom-policies/) - JSON documents for customer-managed policies (AWS-managed policies are referenced by ARN and not needed here)
+    - 📁 [existing-policies](aws-custom-policies/existing-policies/) - policy documents captured from the live account; `manage-access-keys-policy.json` is used by `aws-custom-policies-legacy.tf`, the rest are kept for reference
+  - 📁 [modules](modules/) - reusable Terraform configurations, each documented in its own README
+    - 📁 [aws-gha-oidc-providers](modules/aws-gha-oidc-providers/) - GitHub Actions OIDC identity provider and role
+    - 📁 [aws-groups](modules/aws-groups/) - IAM groups
+    - 📁 [aws-policies](modules/aws-policies/) - IAM customer-managed policies
+    - 📁 [aws-roles](modules/aws-roles/) - IAM roles
+    - 📁 [aws-users](modules/aws-users/) - IAM users
+  - 📄 [aws-custom-policies.tf](aws-custom-policies.tf) - maintain custom policies here
+  - 📄 [aws-custom-policies-legacy.tf](aws-custom-policies-legacy.tf) - policies that predate the module, declared as bare resources
+  - 📄 [aws-gha-oidc-providers.tf](aws-gha-oidc-providers.tf) - OIDC roles for hackforla/incubator CI and the user-bot deploy workflow
+  - 📄 [aws-groups.tf](aws-groups.tf) - maintain groups here
+  - 📄 [aws-groups-legacy.tf](aws-groups-legacy.tf) - groups that predate the module, declared as bare resources
+  - 📄 [aws-users.tf](aws-users.tf) - maintain users here
+  - 📄 [aws-users-legacy.tf](aws-users-legacy.tf) - users that predate the module, declared as bare resources
+  - 📄 [backend.tf](backend.tf) - Terraform and provider version pins, S3 backend and AWS provider
+  - 📄 [cloudtrail.tf](cloudtrail.tf) - the account's two CloudTrail trails and their log buckets
+  - 📄 [prod.backend.tfvars](prod.backend.tfvars) - backend configuration used by CI
+  - 📄 [user-bot.tf](user-bot.tf) - the user-bot Lambda that sends new IAM users their temporary console password on Slack
+  - 📄 [variables.tf](variables.tf) - input variables
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | ~> 1.16.0 |
+| <a name="requirement_archive"></a> [archive](#requirement\_archive) | ~> 2.8.0 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 6.64.0 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_archive"></a> [archive](#provider\_archive) | 2.8.1 |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | 6.64.0 |
 
 ## Modules
 
 | Name | Source | Version |
-| ---- | ------ | ------- |
+|------|--------|---------|
 | <a name="module_aws_custom_policies"></a> [aws\_custom\_policies](#module\_aws\_custom\_policies) | ./modules/aws-policies | n/a |
 | <a name="module_iam_oidc_gha_incubator"></a> [iam\_oidc\_gha\_incubator](#module\_iam\_oidc\_gha\_incubator) | ./modules/aws-gha-oidc-providers | n/a |
 | <a name="module_iam_read_only_group"></a> [iam\_read\_only\_group](#module\_iam\_read\_only\_group) | ./modules/aws-groups | n/a |
 | <a name="module_iam_user_Ganeshswaminathan1912"></a> [iam\_user\_Ganeshswaminathan1912](#module\_iam\_user\_Ganeshswaminathan1912) | ./modules/aws-users | n/a |
 | <a name="module_iam_user_Sbairamian"></a> [iam\_user\_Sbairamian](#module\_iam\_user\_Sbairamian) | ./modules/aws-users | n/a |
-| <a name="module_iam_user_alexe"></a> [iam\_user\_alexe](#module\_iam\_user\_alexe) | ./modules/aws-users | n/a |
-| <a name="module_iam_user_benettonkkb"></a> [iam\_user\_benettonkkb](#module\_iam\_user\_benettonkkb) | ./modules/aws-users | n/a |
-| <a name="module_iam_user_herehfla"></a> [iam\_user\_herehfla](#module\_iam\_user\_herehfla) | ./modules/aws-users | n/a |
+| <a name="module_iam_user_ale210"></a> [iam\_user\_ale210](#module\_iam\_user\_ale210) | ./modules/aws-users | n/a |
+| <a name="module_iam_user_here"></a> [iam\_user\_here](#module\_iam\_user\_here) | ./modules/aws-users | n/a |
 | <a name="module_iam_user_rsakuma"></a> [iam\_user\_rsakuma](#module\_iam\_user\_rsakuma) | ./modules/aws-users | n/a |
 | <a name="module_iam_user_testiamuser"></a> [iam\_user\_testiamuser](#module\_iam\_user\_testiamuser) | ./modules/aws-users | n/a |
 | <a name="module_iam_user_tylerthome"></a> [iam\_user\_tylerthome](#module\_iam\_user\_tylerthome) | ./modules/aws-users | n/a |
+
 ## Resources
 
 | Name | Type |
-| ---- | ---- |
+|------|------|
 | [aws_cloudtrail.management_events](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudtrail) | resource |
 | [aws_cloudtrail.tf_backend_logs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudtrail) | resource |
 | [aws_cloudwatch_event_rule.user_bot](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_event_rule) | resource |
@@ -47,6 +86,8 @@ Resources created by this code repository.
 | [aws_lambda_permission.user_bot_eventbridge](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_permission) | resource |
 | [aws_s3_bucket.management_events](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket) | resource |
 | [aws_s3_bucket.tf_backend_logs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket) | resource |
+| [aws_s3_bucket_lifecycle_configuration.management_events](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_lifecycle_configuration) | resource |
+| [aws_s3_bucket_lifecycle_configuration.tf_backend_logs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_lifecycle_configuration) | resource |
 | [aws_s3_bucket_ownership_controls.tf_backend_logs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_ownership_controls) | resource |
 | [aws_s3_bucket_policy.management_events](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_policy) | resource |
 | [aws_s3_bucket_policy.tf_backend_logs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_policy) | resource |
@@ -57,39 +98,14 @@ Resources created by this code repository.
 | [aws_ssm_parameter.user_bot_slack_token](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ssm_parameter) | resource |
 | [archive_file.user_bot_placeholder](https://registry.terraform.io/providers/hashicorp/archive/latest/docs/data-sources/file) | data source |
 | [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
+
 ## Inputs
 
 | Name | Description | Type | Default | Required |
-| ---- | ----------- | ---- | ------- | :------: |
+|------|-------------|------|---------|:--------:|
 | <a name="input_iam_only"></a> [iam\_only](#input\_iam\_only) | Manage IAM resources only, skipping the Hack for LA account's CloudTrail trails and log buckets. Set to false for the Hack for LA account. | `bool` | `true` | no |
 
-## Providers
-
-| Name | Version |
-| ---- | ------- |
-| <a name="provider_archive"></a> [archive](#provider\_archive) | 2.8.1 |
-| <a name="provider_aws"></a> [aws](#provider\_aws) | 6.64.0 |
-## Requirements
-
-| Name | Version |
-| ---- | ------- |
-| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | ~> 1.16.0 |
-| <a name="requirement_archive"></a> [archive](#requirement\_archive) | ~> 2.8.0 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 6.64.0 |
- 
-
-# Directory Structure
-Terraform directory structure
+## Outputs
 
-- 📁 [terraform](https://github.com/hackforla/devops-security/tree/main/terraform)
-  - 📁  [aws-custom-policies](https://github.com/hackforla/devops-security/tree/main/terraform/aws-custom-policies) - JSON configurations for customer-managed policies (AWS-managed policies are referenced by ARN and not needed here)
-      - 📁 [existing-policies](https://github.com/hackforla/devops-security/tree/main/terraform/aws-custom-policies/existing-policies) - a few of our current policy configurations for reference
-  - 📁 [modules](https://github.com/hackforla/devops-security/tree/main/terraform/modules) - reusable Terraform configurations
-  - 📄 [aws-custom-policies.tf](https://github.com/hackforla/devops-security/tree/main/terraform/modules/aws-groups) - maintain custom policies here
-  - 📄 [aws-groups.tf](https://github.com/hackforla/devops-security/tree/main/terraform/modules/aws-groups) - maintain groups here
-  - 📄 [aws-users.tf](https://github.com/hackforla/devops-security/tree/main/terraform/modules/aws-users) - maintain users here
-    
-To automatically update this documentation, install terraform-docs on your local machine run the following: 
-`cd <directory of README location to update>`
-`terraform-docs -c .terraform.docs.yml .`
-<!-- END_TF_DOCS -->    
\ No newline at end of file
+No outputs.
+<!-- END_TF_DOCS -->
diff --git a/terraform/modules/aws-gha-oidc-providers/README.md b/terraform/modules/aws-gha-oidc-providers/README.md
new file mode 100644
index 0000000..8ab1b36
--- /dev/null
+++ b/terraform/modules/aws-gha-oidc-providers/README.md
@@ -0,0 +1,48 @@
+# GitHub Actions OIDC providers
+
+This module declares all of the resources necessary to let a GitHub Actions workflow authenticate to AWS through OIDC: the GitHub OIDC identity provider and an IAM role that workflows in a given repository and branch can assume.
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+No requirements.
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
+| <a name="provider_tls"></a> [tls](#provider\_tls) | n/a |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [aws_iam_openid_connect_provider.github_actions](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_openid_connect_provider) | resource |
+| [aws_iam_role.github_actions_oidc](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
+| [aws_iam_role_policy_attachment.github_actions_oidc](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
+| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
+| [tls_certificate.github_actions](https://registry.terraform.io/providers/hashicorp/tls/latest/docs/data-sources/certificate) | data source |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_github_branch"></a> [github\_branch](#input\_github\_branch) | The branch name (or name wildcard pattern if use\_wildcard=true) | `string` | n/a | yes |
+| <a name="input_github_environment"></a> [github\_environment](#input\_github\_environment) | The environment name (optional) | `string` | `""` | no |
+| <a name="input_github_repo"></a> [github\_repo](#input\_github\_repo) | The repository name (or name wildcard pattern if use\_wildcard=true) | `string` | n/a | yes |
+| <a name="input_policy_arns"></a> [policy\_arns](#input\_policy\_arns) | The ARN of the policy to attach to the role | `list(string)` | n/a | yes |
+| <a name="input_role_name"></a> [role\_name](#input\_role\_name) | The name of the IAM role | `string` | n/a | yes |
+| <a name="input_use_wildcard"></a> [use\_wildcard](#input\_use\_wildcard) | Specifies whether OIDC claim subject should use wildcard pattern | `bool` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_provider_arn"></a> [provider\_arn](#output\_provider\_arn) | The ARN of the OIDC provider |
+| <a name="output_role_arn"></a> [role\_arn](#output\_role\_arn) | The ARN of the IAM role for the federated identity |
+<!-- END_TF_DOCS -->
diff --git a/terraform/modules/aws-groups/.terraform.docs.yml b/terraform/modules/aws-groups/.terraform.docs.yml
deleted file mode 100755
index 76cf8e3..0000000
--- a/terraform/modules/aws-groups/.terraform.docs.yml
+++ /dev/null
@@ -1,60 +0,0 @@
-formatter: "markdown table" # this is required
-version: ""
-
-header-from: main.tf
-footer-from: ""
-
-recursive:
-  enabled: false
-  path: modules
-
-sections:
-  hide: []
-  show: []
-
-content: |-
-  # Groups
-
-  This module declares all of the resources necessary to create AWS IAM groups.
-
-  {{ .Header }}
-  {{ .Modules }}
-  {{ .Resources }}
-  {{ .Inputs }}
-  {{ .Outputs }}
-  {{ .Providers }}
-  {{ .Requirements }}
-  {{ .Footer }}
-  To automatically update this documentation, install terraform-docs on your local machine run the following: 
-      cd <directory of README location to update>
-      terraform-docs -c .terraform.docs.yml . 
-output:
-  file: README.md
-  mode: replace
-  template: |-
-    <!-- BEGIN_TF_DOCS -->
-    {{ .Content }}
-    <!-- END_TF_DOCS -->    
-
-output-values:
-  enabled: false
-  from: ""
-
-sort:
-  enabled: true
-  by: name
-
-settings:
-  anchor: true
-  color: true
-  default: true
-  description: false
-  escape: true
-  hide-empty: true
-  html: true
-  indent: 2
-  lockfile: true
-  read-comments: true
-  required: true
-  sensitive: true
-  type: true
\ No newline at end of file
diff --git a/terraform/modules/aws-groups/README.md b/terraform/modules/aws-groups/README.md
index 953b2e9..890702a 100644
--- a/terraform/modules/aws-groups/README.md
+++ b/terraform/modules/aws-groups/README.md
@@ -1,9 +1,21 @@
-<!-- BEGIN_TF_DOCS -->
 # Groups
 
 This module declares all of the resources necessary to create AWS IAM groups.
 
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+No requirements.
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
+
+## Modules
 
+No modules.
 
 ## Resources
 
@@ -11,27 +23,19 @@ This module declares all of the resources necessary to create AWS IAM groups.
 |------|------|
 | [aws_iam_group.group](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_group) | resource |
 | [aws_iam_group_policy_attachment.group_policy_attachment](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_group_policy_attachment) | resource |
+
 ## Inputs
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
 | <a name="input_group_name"></a> [group\_name](#input\_group\_name) | The name of the IAM group | `string` | n/a | yes |
 | <a name="input_group_path"></a> [group\_path](#input\_group\_path) | Path in which to create the group | `string` | `"/"` | no |
-| <a name="input_policy_arn"></a> [policy\_arn](#input\_policy\_arn) | List of policy ARNs to attach to the group | `list(string)` | n/a | yes |
+| <a name="input_policy_arn"></a> [policy\_arn](#input\_policy\_arn) | Map of policy names to ARNs to attach to the group | `map(string)` | n/a | yes |
+
 ## Outputs
 
 | Name | Description |
 |------|-------------|
 | <a name="output_group_arn"></a> [group\_arn](#output\_group\_arn) | The ARN of the IAM group |
 | <a name="output_group_name"></a> [group\_name](#output\_group\_name) | The name of the IAM group |
-## Providers
-
-| Name | Version |
-|------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
-
-
-To automatically update this documentation, install terraform-docs on your local machine run the following: 
-    cd <directory of README location to update>
-    terraform-docs -c .terraform.docs.yml . 
-<!-- END_TF_DOCS -->    
\ No newline at end of file
+<!-- END_TF_DOCS -->
diff --git a/terraform/modules/aws-policies/.terraform.docs.yml b/terraform/modules/aws-policies/.terraform.docs.yml
deleted file mode 100755
index acb528c..0000000
--- a/terraform/modules/aws-policies/.terraform.docs.yml
+++ /dev/null
@@ -1,58 +0,0 @@
-formatter: "markdown table" # this is required
-version: ""
-
-header-from: main.tf
-footer-from: ""
-
-recursive:
-  enabled: false
-  path: modules
-
-sections:
-  hide: []
-  show: []
-
-content: |-
-  # Policies
-
-  This module declares all of the resources necessary to create AWS IAM policies.
-
-  {{ .Header }}
-  {{ .Modules }}
-  {{ .Resources }}
-  {{ .Inputs }}
-  {{ .Outputs }}
-  {{ .Providers }}
-  {{ .Requirements }}
-  {{ .Footer }}
-
-output:
-  file: README.md
-  mode: replace
-  template: |-
-    <!-- BEGIN_TF_DOCS -->
-    {{ .Content }}
-    <!-- END_TF_DOCS -->    
-
-output-values:
-  enabled: false
-  from: ""
-
-sort:
-  enabled: true
-  by: name
-
-settings:
-  anchor: true
-  color: true
-  default: true
-  description: false
-  escape: true
-  hide-empty: true
-  html: true
-  indent: 2
-  lockfile: true
-  read-comments: true
-  required: true
-  sensitive: true
-  type: true
\ No newline at end of file
diff --git a/terraform/modules/aws-policies/README.md b/terraform/modules/aws-policies/README.md
index 4fe26d4..ea19e1d 100644
--- a/terraform/modules/aws-policies/README.md
+++ b/terraform/modules/aws-policies/README.md
@@ -1,29 +1,37 @@
-<!-- BEGIN_TF_DOCS -->
 # Policies
 
 This module declares all of the resources necessary to create AWS IAM policies.
 
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+No requirements.
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
+
+## Modules
 
+No modules.
 
 ## Resources
 
 | Name | Type |
 |------|------|
 | [aws_iam_policy.custom_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_policy) | resource |
+
 ## Inputs
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_policies"></a> [policies](#input\_policies) | Map of policy definitions | <pre>map(object({<br>    description = string<br>    filename    = string<br>  }))</pre> | n/a | yes |
+| <a name="input_policies"></a> [policies](#input\_policies) | Map of policy definitions | <pre>map(object({<br/>    description = string<br/>    filename    = string<br/>  }))</pre> | n/a | yes |
+
 ## Outputs
 
 | Name | Description |
 |------|-------------|
 | <a name="output_policy_arns"></a> [policy\_arns](#output\_policy\_arns) | Map of policy names to their ARNs |
-## Providers
-
-| Name | Version |
-|------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
-
-<!-- END_TF_DOCS -->    
\ No newline at end of file
+<!-- END_TF_DOCS -->
diff --git a/terraform/modules/aws-roles/.terraform.docs.yml b/terraform/modules/aws-roles/.terraform.docs.yml
deleted file mode 100755
index e1a0cac..0000000
--- a/terraform/modules/aws-roles/.terraform.docs.yml
+++ /dev/null
@@ -1,58 +0,0 @@
-formatter: "markdown table" # this is required
-version: ""
-
-header-from: main.tf
-footer-from: ""
-
-recursive:
-  enabled: false
-  path: modules
-
-sections:
-  hide: []
-  show: []
-
-content: |-
-  # Roles
-
-  This module declares all of the resources necessary to create AWS IAM roles.
-
-  {{ .Header }}
-  {{ .Modules }}
-  {{ .Resources }}
-  {{ .Inputs }}
-  {{ .Outputs }}
-  {{ .Providers }}
-  {{ .Requirements }}
-  {{ .Footer }}
-
-output:
-  file: README.md
-  mode: replace
-  template: |-
-    <!-- BEGIN_TF_DOCS -->
-    {{ .Content }}
-    <!-- END_TF_DOCS -->    
-
-output-values:
-  enabled: false
-  from: ""
-
-sort:
-  enabled: true
-  by: name
-
-settings:
-  anchor: true
-  color: true
-  default: true
-  description: false
-  escape: true
-  hide-empty: true
-  html: true
-  indent: 2
-  lockfile: true
-  read-comments: true
-  required: true
-  sensitive: true
-  type: true
\ No newline at end of file
diff --git a/terraform/modules/aws-roles/README.md b/terraform/modules/aws-roles/README.md
index 9a35fdf..5943920 100644
--- a/terraform/modules/aws-roles/README.md
+++ b/terraform/modules/aws-roles/README.md
@@ -1,9 +1,21 @@
-<!-- BEGIN_TF_DOCS -->
 # Roles
 
 This module declares all of the resources necessary to create AWS IAM roles.
 
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+No requirements.
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
+
+## Modules
 
+No modules.
 
 ## Resources
 
@@ -11,6 +23,7 @@ This module declares all of the resources necessary to create AWS IAM roles.
 |------|------|
 | [aws_iam_role.iam_role](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
 | [aws_iam_role_policy_attachment.role_policy_attachment](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |
+
 ## Inputs
 
 | Name | Description | Type | Default | Required |
@@ -18,15 +31,10 @@ This module declares all of the resources necessary to create AWS IAM roles.
 | <a name="input_assume_role_principal"></a> [assume\_role\_principal](#input\_assume\_role\_principal) | The AWS service or entity that can assume this role | `string` | n/a | yes |
 | <a name="input_policy_arn"></a> [policy\_arn](#input\_policy\_arn) | The ARN of the policy to attach to the role | `string` | n/a | yes |
 | <a name="input_role_name"></a> [role\_name](#input\_role\_name) | The name of the IAM role | `string` | n/a | yes |
+
 ## Outputs
 
 | Name | Description |
 |------|-------------|
 | <a name="output_role_arn"></a> [role\_arn](#output\_role\_arn) | The ARN of the IAM role |
-## Providers
-
-| Name | Version |
-|------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
-
-<!-- END_TF_DOCS -->    
\ No newline at end of file
+<!-- END_TF_DOCS -->
diff --git a/terraform/modules/aws-users/.terraform.docs.yml b/terraform/modules/aws-users/.terraform.docs.yml
deleted file mode 100755
index 19f0f5b..0000000
--- a/terraform/modules/aws-users/.terraform.docs.yml
+++ /dev/null
@@ -1,58 +0,0 @@
-formatter: "markdown table" # this is required
-version: ""
-
-header-from: main.tf
-footer-from: ""
-
-recursive:
-  enabled: false
-  path: modules
-
-sections:
-  hide: []
-  show: []
-
-content: |-
-  # Users
-
-  This module declares all of the resources necessary to create AWS IAM users.
-
-  {{ .Header }}
-  {{ .Modules }}
-  {{ .Resources }}
-  {{ .Inputs }}
-  {{ .Outputs }}
-  {{ .Providers }}
-  {{ .Requirements }}
-  {{ .Footer }}
-
-output:
-  file: README.md
-  mode: replace
-  template: |-
-    <!-- BEGIN_TF_DOCS -->
-    {{ .Content }}
-    <!-- END_TF_DOCS -->    
-
-output-values:
-  enabled: false
-  from: ""
-
-sort:
-  enabled: true
-  by: name
-
-settings:
-  anchor: true
-  color: true
-  default: true
-  description: false
-  escape: true
-  hide-empty: true
-  html: true
-  indent: 2
-  lockfile: true
-  read-comments: true
-  required: true
-  sensitive: true
-  type: true
\ No newline at end of file
diff --git a/terraform/modules/aws-users/README.md b/terraform/modules/aws-users/README.md
index 6c903ee..4123c1f 100644
--- a/terraform/modules/aws-users/README.md
+++ b/terraform/modules/aws-users/README.md
@@ -1,9 +1,21 @@
-<!-- BEGIN_TF_DOCS -->
 # Users
 
 This module declares all of the resources necessary to create AWS IAM users.
 
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+No requirements.
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
+
+## Modules
 
+No modules.
 
 ## Resources
 
@@ -12,6 +24,7 @@ This module declares all of the resources necessary to create AWS IAM users.
 | [aws_iam_user.user](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_user) | resource |
 | [aws_iam_user_group_membership.user_group_membership](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_user_group_membership) | resource |
 | [aws_iam_user_login_profile.user_login](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_user_login_profile) | resource |
+
 ## Inputs
 
 | Name | Description | Type | Default | Required |
@@ -21,16 +34,11 @@ This module declares all of the resources necessary to create AWS IAM users.
 | <a name="input_user_name"></a> [user\_name](#input\_user\_name) | The name of the IAM user | `string` | n/a | yes |
 | <a name="input_user_path"></a> [user\_path](#input\_user\_path) | Path in which to create the user | `string` | `"/"` | no |
 | <a name="input_user_tags"></a> [user\_tags](#input\_user\_tags) | Tags to assign to the user | `map(string)` | `{}` | no |
+
 ## Outputs
 
 | Name | Description |
 |------|-------------|
 | <a name="output_user_arn"></a> [user\_arn](#output\_user\_arn) | The ARN of the IAM user |
 | <a name="output_user_name"></a> [user\_name](#output\_user\_name) | The name of the IAM user |
-## Providers
-
-| Name | Version |
-|------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | n/a |
-
-<!-- END_TF_DOCS -->    
\ No newline at end of file
+<!-- END_TF_DOCS -->