Docs updates

docs/docs/index.md

@@ -20,7 +20,7 @@ Minder can be deployed as a Helm chart and provides a CLI tool ‘minder’. Min
 * **Artifact attestation:** Continuously verify that packages are signed to ensure they’re tamper-proof, using the open source project Sigstore.
 * **Dependency management:** Manage dependency security posture by helping developers make better choices and enforcing controls. Minder is integrated with [Trusty by Stacklok](http://trustypkg.dev) to enable policy-driven dependency management based on the risk level of dependencies.
 
-## SaaS
+## Minder Cloud
 
 Stacklok, the company behind Minder, also provides a free-to-use hosted version of Minder, allowing you to utilize Minder 
 without the need for managing your own infrastructure.

docs/docs/understand/alerts.md

@@ -1,10 +1,12 @@
 ---
 title: Alerting
-sidebar_position: 60
+sidebar_position: 40
 ---
 
 # Alerts from Minder
 
+Minder issues _alerts_ to notify you when the state of your software supply chain does not meet the criteria that you've defined in your [profile](profile).
+
 Alerts are a core feature of Minder providing you with notifications about the status of your registered
 repositories. These alerts automatically open and close based on the evaluation of the rules defined in your profiles.
 
@@ -18,6 +20,46 @@ In the alert, you'll be able to see details such as:
 * Guidance on how to remediate and also fix the issue
 * Severity of the issue. The severity of the alert is based on what is set in the rule type definition.
 
+### Enabling alerts in a profile
+To activate the alert feature within a profile, you need to adjust the YAML definition. 
+Specifically, you should set the alert parameter to "on":
+```yaml
+alert: "on"
+```
+
+Enabling alerts at the profile level means that for any rules included in the profile, alerts will be generated for 
+any rule failures. For better clarity, consider this rule snippet:
+```yaml
+---
+version: v1
+type: rule-type
+name: sample_rule
+def:
+  alert:
+      type: security_advisory
+      security_advisory:
+        severity: "medium"
+```
+In this example, the `sample_rule` defines an alert action that creates a medium severity security advisory in the 
+repository for any non-compliant repositories.
+
+Now, let's see how this works in practice within a profile. Consider the following profile configuration with alerts 
+turned on:
+```yaml
+version: v1
+type: profile
+name: sample-profile
+context:
+  provider: github
+alert: "on"
+repository:
+  - type: sample_rule
+    def:
+      enabled: true
+```
+In this profile, all repositories that do not meet the conditions specified in the `sample_rule` will automatically
+generate security advisories.
+
 ## Alert types
 
 Minder supports alerts of type GitHub Security Advisory.

docs/docs/understand/profiles.md

@@ -1,11 +1,11 @@
 ---
 title: Profiles and Rules
-sidebar_position: 30
+sidebar_position: 10
 ---
 
 # Profiles in Minder
 
-Minder allows you to define profiles for your software supply chain.
+A _profile_ defines your security policies that you want to apply to your software supply chain. Profiles contain rules that query data in a [provider](provider), and specifies whether Minder will issue [alerts](alerts) or perform automatic [remediations](remediations) when an entity is not in compliance with the policy.
 
 Profiles in Minder allow you to group and manage
 rules for various entity types, such as repositories, pull requests, and artifacts, across your registered GitHub

docs/docs/understand/projects.md

@@ -9,4 +9,4 @@ Projects in Minder are a way to group entities together. They are a way to organ
 etc.) based on the policy you want to enforce or the team that owns them.
 
 When creating an account, Minder will automatically create a default project for you. You can create additional projects as
-a way to organize and secure your entities, and manage access for your team members.
+a way to organize and secure your entities, and manage access for your team members.

docs/docs/understand/providers.md

@@ -1,14 +1,27 @@
 ---
 title: Providers
-sidebar_position: 10
+sidebar_position: 20
 ---
 
 # Providers in Minder
 
-Providers are integration points from Minder towards external services. They are Minder's way
-of fetching information about the different aspects of your supply chain. Taking an operating
-system analogy, providers are like device drivers.
+A _provider_ connects Minder to your software supply chain — giving Minder information about your source code repositories, and their pull requests, dependencies, and artifacts. Minder will apply your [profiles](profiles) to providers to analyze the security posture of your software supply chain, and then will create [alerts](alerts) and can automatically [remediate](remediation) problems that it finds.
 
-Providers are the backbone of Minder. They are the ones that fetch the data that Minder uses to
-provide you with insights and analytics. When you enroll a provider, Minder will fetch the data
-from the provider and store it in its database.
+The currently supported providers are:
+* GitHub
+
+Stay tuned as we add more providers in the future!
+
+## Enrolling a provider
+
+To enroll GitHub as a provider, use the following command:
+```
+minder provider enroll
+```
+
+Note: If you are enrolling an organization, the account you use to enroll must be an Owner in the organization
+or an Admin on the repositories you will be registering.
+
+Once a provider is enrolled, public repositories from that provider can be registered with Minder. Security profiles
+can then be applied to the registered repositories, giving you an overview of your security posture and providing
+remediations to improve your security posture.

docs/docs/understand/remediation.md

@@ -1,62 +1,15 @@
 ---
-title: Auto-remediation
-sidebar_position: 40
+title: Automatic Remediations
+sidebar_position: 60
 ---
 
 # Automatic Remediation in Minder
 
-A profile in Minder offers a comprehensive view of your security posture, encompassing more than just the status report. 
-It actively responds to any rules that are not in compliance, taking specific actions. These actions can include the 
-creation of alerts for rules that have failed, as well as the execution of remediations to fix the non-compliant 
-aspects.
+Minder can perform _automatic remediation_ for many rules in an attempt to resolve problems in your software supply chain, and bring your resources into compliance with your [profile](profiles).
 
-When alerting is turned on in a profile, Minder will open an alert to bring your attention to the non-compliance issue. 
-Conversely, when the rule evaluation passes, Minder will automatically close any previously opened alerts related to 
-that rule.
+The steps to take during automatic remediation are defined within the rule itself and can perform actions like sending a REST call to an endpoint to change configuration, or creating a pull request with a proposed fix.
 
-When remediation is turned on, Minder also supports the ability to automatically remediate failed rules based on their 
-type, i.e., by processing a REST call to enable/disable a non-compliant repository setting or creating a pull request 
-with a proposed fix. Note that not all rule types support automatic remediation yet.
-
-### Enabling alerts in a profile
-To activate the alert feature within a profile, you need to adjust the YAML definition. 
-Specifically, you should set the alert parameter to "on":
-```yaml
-alert: "on"
-```
-
-Enabling alerts at the profile level means that for any rules included in the profile, alerts will be generated for 
-any rule failures. For better clarity, consider this rule snippet:
-```yaml
----
-version: v1
-type: rule-type
-name: sample_rule
-def:
-  alert:
-      type: security_advisory
-      security_advisory:
-        severity: "medium"
-```
-In this example, the `sample_rule` defines an alert action that creates a medium severity security advisory in the 
-repository for any non-compliant repositories.
-
-Now, let's see how this works in practice within a profile. Consider the following profile configuration with alerts 
-turned on:
-```yaml
-version: v1
-type: profile
-name: sample-profile
-context:
-  provider: github
-alert: "on"
-repository:
-  - type: sample_rule
-    def:
-      enabled: true
-```
-In this profile, all repositories that do not meet the conditions specified in the `sample_rule` will automatically
-generate security advisories.
+For example, if you have a rule in your profile that specifies that [Secret Scanning should be enabled](../ref/rules/secret_scanning), and you have enabled automatic remediation in your profile, then Minder will attempt to turn Secret Scanning on in any repositories where it is not enabled.
 
 ### Enabling remediations in a profile
 To activate the remediation feature within a profile, you need to adjust the YAML definition.