(MAINT) Update readme and reviewdog docs

README.md

@@ -1 +1,47 @@
-# cat-github-actions
+# cat-github-actions
+
+This repository contains GitHub Actions workflows and configurations for automating various tasks related to the `Content and Tooling (CAT)` project. These workflows help ensure code quality, automate testing, and streamline the release process.
+
+## Workflows
+
+The following are the workflows we currently maintain in this repository:
+* gem_acceptance: runs automated acceptance CI on tooling PRs
+* gem_ci: runs automated unit testing CI on tooling PRs
+* gem_release_prep: prepares the gem for release by running necessary pre-release checks and tasks
+* gem_release: handles the release process of the gem, including versioning and publishing
+* lint: runs linting checks on the codebase to ensure code quality and consistency
+* mend_ruby: automates the usage of mend for vulnerability scanning on modules
+* module_acceptance: runs automated acceptance CI for modules on PRs
+* module_ci: runs automated unit testing CI for modules on PRs
+* module_release_prep: prepares the module for release by running necessary pre-release checks and tasks
+* module_release: handles the release process of the module, including versioning and publishing
+* tooling_mend_ruby: automates the usage of mend for vulnerability scanning on tools
+* workflow-restarter-test: tests the workflow restarter functionality
+* workflow-restarter: restarts workflows that have failed or need to be re-run
+
+Note: For more information about workflows like workflow-restarter, check out our [docs](./docs/)
+
+```mermaid
+flowchart TD
+    A[Content and Tooling] --> B & C
+    B(Modules) --> D & F
+    B@{ shape: div-rect }
+    C(Tools) --> G & I
+    C@{ shape: div-rect }
+    D@{ shape: procs, label: "Release"} --> N & O
+    F@{ shape: procs, label: "Testing"} --> J & K & L & M & Z
+    G@{ shape: procs, label: "Testing"} --> P & Q & R & M & Z
+    I@{ shape: procs, label: "Release"} --> S & T
+    J@{ shape: lin-rect, label: "mend_ruby.yml"}
+    K@{ shape: lin-rect, label: "module_acceptance.yml"}
+    L@{ shape: lin-rect, label: "module_ci.yml"}
+    M@{ shape: lin-rect, label: "lint.yml"}
+    N@{ shape: lin-rect, label: "module_release_prep.yml"}
+    O@{ shape: lin-rect, label: "module_release.yml"}
+    P@{ shape: lin-rect, label: "gem_ci.yml"}
+    Q@{ shape: lin-rect, label: "gem_acceptance.yml"}
+    R@{ shape: lin-rect, label: "tooling_mend_ruby.yml"}
+    S@{ shape: lin-rect, label: "gem_release_prep.yml"}
+    T@{ shape: lin-rect, label: "gem_release.yml"}
+    Z@{ shape: lin-rect, label: "workflow_restarter.yml"}
+```

docs/reviewdog-shellcheck.md

@@ -0,0 +1,7 @@
+## Attention
+
+Reviewdog/shellcheck is a third-party action that we have implemented in our testing workflows. As such,
+if your repository has strict permission control, you might need to add it as a trusted action. Otherwise,
+you might run into the following or similar errors:
+
+`reviewdog/action-shellcheck@v1 is not allowed to be used in <your_repo>. Actions in this workflow must be: within a repository that belongs to your Enterprise account, created by GitHub, verified in the GitHub Marketplace, or matching the following: ruby/*, puppetlabs/*, docker://puppet/*, luchihoratiu/*, peter-evans/*.`