Merge branch 'main' into ethomson/docs_underlines

docs/docs/developer_guide/architecture.md

@@ -1,5 +1,5 @@
 ---
-title: Architecture
+title: Architecture overview
 sidebar_position: 60
 ---
 

docs/docs/developer_guide/feature_flags.md

@@ -1,5 +1,5 @@
 ---
-title: Feature Flags
+title: Feature flags
 sidebar_position: 20
 ---
 
@@ -45,4 +45,4 @@ Using `flags.Bool` from our own repo will enable a couple bits of default behavi
 
 You can create a `flags-config.yaml` in the root Minder directory when running with `make run-docker`, and the file (and future changes) will be mapped into the Minder container, so you can make changes live.  The `flags-config.yaml` uses the [GoFeatureFlag format](https://gofeatureflag.org/docs/configure_flag/flag_format), and is in the repo's `.gitignore`, so you don't need to worry about accidentally checking it in.  Note that the Minder server currently rechecks the flag configuration once a minute, so it may take a minute or two for flags changes to be visible.
 
-When deploying as a Helm chart, you can create a ConfigMap named `minder-flags` containing a key `flags-config.yaml`, and it will be mounted into the container.  Again, changes to the `minder-flags` ConfigMap will be updated in the Minder server within about 2 minutes of update.
+When deploying as a Helm chart, you can create a ConfigMap named `minder-flags` containing a key `flags-config.yaml`, and it will be mounted into the container.  Again, changes to the `minder-flags` ConfigMap will be updated in the Minder server within about 2 minutes of update.

docs/docs/developer_guide/get-hacking.md

@@ -1,5 +1,5 @@
 ---
-title: Get Hacking
+title: Get hacking
 sidebar_position: 1
 ---
 

docs/docs/getting_started/_category_.yml

@@ -1,2 +1,2 @@
-label: Getting Started
-position: 20
+label: Getting started
+position: 10

docs/docs/getting_started/enroll_provider.md

@@ -1,30 +1,38 @@
 ---
-title: Enrolling a Provider
+title: Enrolling the GitHub Provider
 sidebar_position: 40
 ---
 
-# Enrolling a Provider
+# Enrolling the GitHub Provider
 
-Once you have authenticated to Minder, you'll want to enroll your GitHub credentials to allow Minder to manage your GitHub repositories.  In the future, Minder will support other source control and artifact repositories, and you will be able to enroll credentials for those providers in the same manner.
+Once you have authenticated to Minder, you'll need to enroll your GitHub credentials to allow Minder to manage your GitHub repositories. This allows Minder to inspect and manage your repository configuration. You will be prompted to grant Minder access.
+
+In the future, Minder will support other source control and artifact repositories, and you will be able to enroll credentials for those providers in the same manner.
+
+:::note
+If you used the [minder `quickstart` command](quickstart), the GitHub Provider was enrolled as part of the quickstart, and you do not need to enroll a second time.
+:::
 
 ## Prerequisites
 
-* A running Minder server, including a running KeyCloak installation
-* A GitHub account
-* [The `minder` CLI application](./install_cli.md)
-* [Logged in to Minder server](./login.md)
+Before you can enroll the GitHub Provider, you must [log in to Minder using the CLI](login).
 
-## Enrolling the GitHub Provider
+## Enrolling and granting access
 
 To enroll your GitHub credentials in your Minder account, run:
 
 ```bash
 minder provider enroll
 ```
 
-A browser session will open, and you will be prompted to login to your authorize the Minder application to access your GitHub account and select the organizations you want to install the application for.
+A browser session will open. If you are a member of multiple GitHub organizations, then you will be prompted which organization you want to enroll. You can select your personal account, or a GitHub organization that contains the repositories that you want to manage with Minder.
+
+![Selecting a GitHub organization](images/select-github-organization.png)
+
+Then you will need to select which repositories you want to allow Minder to manage. You can select all repositories within your GitHub organization, or you can choose individual repositories. If you select individual repositories, they will not be visible within Minder, and you will not be able to [register them](register_repos).
+
+![Selecting GitHub repositories](images/select-repositories.png)
 
-![Enrollment screenshot](./minder-authorize.png)
-![Enrollment screenshot](./minder-enroll.png)
+You can change your repository selection within GitHub at any time.
 
-Once you have granted Minder access, you will be redirected back, and the user will be enrolled. The `minder` CLI application will report the session is complete.
+Once you authorize Minder within GitHub, the browser window will close, and you will have enrolled the GitHub Provider. The `minder` CLI application will report the session is complete.

docs/docs/getting_started/first_profile.md

@@ -5,51 +5,51 @@ sidebar_position: 60
 
 # Creating your first profile
 
-Minder uses [profiles](../how-to/create_profile.md) to specify common,
-consistent configuration which should be enforced on all registered
-repositories.  In this tutorial, you will register a GitHub repository and
-create a profile that indicates whether secret scanning is enabled on the
-registered repositories.
+Once you have registered repositories, you can create a profile that specifies the common, consistent configuration that you expect your your repositories to comply with. 
 
 ## Prerequisites
 
-* [The `minder` CLI application](./install_cli.md)
-* [A Minder account](./login.md)
-* [An enrolled GitHub token](./login.md#enrolling-the-github-provider) that is either an Owner in the organization or an Admin on the repositories
-* [One or more repositories registered with Minder](./register_repos.md)
+Before you can create a profile, you should [register repositories](register_repos).
 
-## Creating and applying profiles
+## Creating a profile
 
-A profile is a set of rules that you apply to your registered repositories.
-Before creating a profile, you need to ensure that all desired rule_types have been created in Minder.
+A profile is composed of a set of one or more rule types, each of which scan for an individual piece of configuration within a repository.
 
-Start by creating a rule that checks if secret scanning is enabled and creates
-a security advisory alert if secret scanning is not enabled.  
-This is a reference rule provided by the Minder team in the [minder-rules-and-profiles repository](https://github.com/stacklok/minder-rules-and-profiles).
+For example, you may have a profile that describes your organization's security best practices, and this profile may have two rule types: GitHub secret scanning should be enabled, and secret push protection should be enabled.
 
-For this exercise, we're going to download just the `secret_scanning.yaml`
-rule, and then use `minder ruletype create` to define the secret scanning rule.
+In this example, Minder will scan the repositories that you've registered and identify any repositories that do not have secret scanning enabled, and those that do not have secret push protection enabled.
+
+### Adding rule types
+
+In Minder, the rule type configuration is completely flexible, and you can author them yourself. Because of this, your Minder organization does not have any rule types configured when you create it. You need to configure some, and you can upload some of Minder's already created rules from the [minder-rules-and-profiles repository](https://github.com/stacklok/minder-rules-and-profiles).
+
+For example, to add a rule type that ensures that secret scanning is enabled, and one that ensures that secret push protection is enabled, you can download the [secret_scanning.yaml](https://github.com/stacklok/minder-rules-and-profiles/blob/main/rule-types/github/secret_scanning.yaml) and [secret_push_protection.yaml](https://github.com/stacklok/minder-rules-and-profiles/blob/main/rule-types/github/secret_push_protection.yaml) rule types.
 
 ```bash
 curl -LO https://raw.githubusercontent.com/stacklok/minder-rules-and-profiles/main/rule-types/github/secret_scanning.yaml
+curl -LO https://raw.githubusercontent.com/stacklok/minder-rules-and-profiles/main/rule-types/github/secret_push_protection.yaml
 ```
 
-Once you've downloaded the rule definition, you can create it in your Minder account:
+Once you've downloaded the rule type configuration from GitHub, you can upload them to your Minder organization.
 
 ```bash
 minder ruletype create -f secret_scanning.yaml
+minder ruletype create -f secret_push_protection.yaml
 ```
 
-Next, create a profile that applies the secret scanning rule.
+### Creating a profile
+
+Once you have added the rule type definitions to Minder, you can create a profile that uses them to scan your repositories.
+
+Like rules, profiles are defined in YAML. They specify the rules that apply to your organization, whether you want to be alerted with GitHub Security Advisories, and whether you want Minder to try to automatically remediate problems when they're found.
 
-Create a new file called `profile.yaml`.
-Paste the following profile definition into the newly created file.
+To create a profile that checks for secret scanning and secret push protection in your repositories, create a file called `my_profile.yaml`:
 
 ```yaml
 ---
 version: v1
 type: profile
-name: github-profile
+name: my_profile
 context:
   provider: github
 alert: "on"
@@ -58,56 +58,38 @@ repository:
   - type: secret_scanning
     def:
       enabled: true
+  - type: secret_push_protection
+    def:
+      enabled: true
 ```
 
-Create the profile in Minder:
+Then upload the profile configuration to Minder:
+
 ```
-minder profile create -f profile.yaml
+minder profile create -f my_profile.yaml
 ```
 
+
+
 Check the status of the profile:
 ```
-minder profile status list --name github-profile
+minder profile status list --name my_profile
 ```
 If all registered repositories have secret scanning enabled, you will see the `OVERALL STATUS` is `Success`, otherwise the 
 overall status is `Failure`.
 
 ```
-+--------------------------------------+----------------+----------------+----------------------+
-|                  ID                  |      NAME      | OVERALL STATUS |     LAST UPDATED     |
-+--------------------------------------+----------------+----------------+----------------------+
-| 1abcae55-5eb8-4d9e-847c-18e605fbc1cc | github-profile |    Success     | 2023-11-06T17:42:04Z |
-+--------------------------------------+----------------+----------------+----------------------+
++--------------------------------------+------------+----------------+----------------------+
+|                  ID                  |    NAME    | OVERALL STATUS |     LAST UPDATED     |
++--------------------------------------+------------+----------------+----------------------+
+| 1abcae55-5eb8-4d9e-847c-18e605fbc1cc | my_profile |    Success     | 2023-11-06T17:42:04Z |
++--------------------------------------+------------+----------------+----------------------+
 ```
 
 If secret scanning is not enabled, you will see `Failure` instead of `Success`.
 
 
 See a detailed view of which repositories satisfy the secret scanning rule:
 ```
-minder profile status list --name github-profile --detailed
+minder profile status list --name my_profile --detailed
 ```
-
-## Viewing alerts
-
-Disable secret scanning in one of the registered repositories, by following 
-[these instructions provided by GitHub](https://docs.github.com/en/code-security/secret-scanning/configuring-secret-scanning-for-your-repositories).
-
-Navigate to the repository on GitHub, click on the Security tab and view the Security Advisories.  
-Notice that there is a new advisory titled `minder: profile github-profile failed with rule secret_scanning`.
-
-Enable secret scanning in the same registered repository, by following
-[these instructions provided by GitHub](https://docs.github.com/en/code-security/secret-scanning/configuring-secret-scanning-for-your-repositories).
-
-Navigate to the repository on GitHub, click on the Security tab and view the Security Advisories.
-Notice that the advisory titled `minder: profile github-profile failed with rule secret_scanning` is now closed.
-
-## Delete registered repositories
-
-If you want to stop monitoring a repository, you can delete it from Minder by using the `repo delete` command:
-```bash
-minder repo delete --name ${REPO_NAME}
-```
-where `$REPO_NAME` is the fully-qualified name (`owner/name`) of the repository you wish to delete, for example `testorg/testrepo`.
-
-This will delete the repository from Minder and remove the webhook from the repository. 

docs/docs/getting_started/install_cli.md

@@ -5,15 +5,15 @@ sidebar_position: 10
 
 # Installing the Minder CLI
 
-Minder consists of two components: a server-side application, and the `minder`
-CLI application for interacting with the server.  Minder is built for `amd64`
-and `arm64` architectures on Windows, MacOS, and Linux.
+The open source Minder CLI can communicate with either [Minder Cloud](https://cloud.stacklok.com/), Stacklok's free-to-use, cloud-hosted version of Minder, or with an on-premises version of Minder that has been [set up independently](../run_minder_server/run_the_server).
+
+The `minder` CLI is built for `amd64` and `arm64` architectures on Windows, MacOS, and Linux.
 
 You can install `minder` using one of the following methods:
 
-## MacOS (Homebrew)
+## macOS
 
-The easiest way to install `minder` is through [Homebrew](https://brew.sh/):
+The easiest way to install `minder` for macOS systems is through [Homebrew](https://brew.sh/):
 
 ```bash
 brew install stacklok/tap/minder
@@ -26,9 +26,9 @@ tar -xzf minder_${RELEASE}_darwin_${ARCH}.tar.gz minder
 xattr -d com.apple.quarantine minder
 ```
 
-## Windows (Winget)
+## Windows
 
-For Windows, the built-in `winget` tool is the simplest way to install `minder`:
+For Windows, the built-in `winget` tool is the easiest way to install `minder`:
 
 ```bash
 winget install stacklok.minder

docs/docs/getting_started/login.md

@@ -1,18 +1,17 @@
 ---
 title: Logging in to Minder
-sidebar_position: 30
+sidebar_position: 20
 ---
 
 # Logging in to Minder
 
-Minder consists of a client-side CLI tool and a server-side component.  The server-side component runs as a multi-user service.  In order to use Minder to manage repositories and artifacts, you need to log in, which will automatically create an account.
+To start using Minder, you must first log in. Logging in to a Minder server for the first time will create your account.
 
-## Prerequisites
+By default, the Minder CLI will log in to [Minder Cloud](https://cloud.minder.com/), Stacklok's hosted instance of Minder. If you have a separate instance of Minder, you can log in to that server instead.
 
-* [The `minder` CLI application](./install_cli.md)
-* A running Minder server, including a running KeyCloak installation
+## Prerequisites
 
-If you don't want to run your own Minder server, Stacklok hosts a public instance.  See [Logging in to the Stacklok-hosted Instance](#logging-in-to-the-stacklok-hosted-instance) below.
+Before you can log in, you must have [installed the `minder` CLI application](install_cli).
 
 ## Logging in to the Stacklok-hosted instance