Add docs for user management and invitations

docs/docs/how-to/artifact_signatures.md

@@ -10,14 +10,17 @@ repositories are built from trusted sources and using trusted workflows based
 on their cryptographically signed provenance.
 
 This is done by creating a profile which utilizes the `artifact_signature`
-`rule_type`. 
+`rule_type`.
 
 ## Prerequisites
 
-* The `minder` CLI application
-* A Stacklok account
-* An enrolled Provider (e.g., GitHub)
-* A repository that produces container images. At the moment Minder's artifact signature checks are only available for container images and only the `ghcr.io` registry is supported.
+- The `minder` CLI application
+- A Minder account with
+  [at least `editor` permission](../user_management/user_roles.md)
+- An enrolled Provider (e.g., GitHub)
+- A repository that produces container images. At the moment Minder's artifact
+  signature checks are only available for container images and only the
+  `ghcr.io` registry is supported.
 
 ## Create the artifact provenance rule type
 
@@ -80,6 +83,7 @@ and the policy status will be updated accordingly. If the artifact is not matchi
 violation is presented via the profile status and an alert is raised.
 
 ## Define a more advanced profile that checks artifact provenance
+
 As the next step, let's create a profile that checks the provenance of the artifact.
 Create a new file called `profile-artifact-provenance.yaml`.
 

docs/docs/how-to/create_profile.md

@@ -5,16 +5,19 @@ sidebar_position: 10
 
 ## Prerequisites
 
-* The `minder` CLI application
-* A Stacklok account
+- The `minder` CLI application
+- A Minder account with
+  [at least `editor` permission](../user_management/user_roles.md)
 
 ## Use a reference rule
+
 The first step to creating a profile is to create the rules that your profile will apply.
 
 The Minder team has provided several reference rules for common use cases. To get started quickly, create a rule from
 the set of references.
 
 Fetch all the reference rules by cloning the [minder-rules-and-profiles repository](https://github.com/stacklok/minder-rules-and-profiles).
+
 ```
 git clone https://github.com/stacklok/minder-rules-and-profiles.git
 ```
@@ -30,14 +33,15 @@ minder ruletype create -f rule-types/github/secret_scanning.yaml
 ```
 
 ## Write your own rule
+
 This section describes how to write your own rule, using the existing rule `secret_scanning` as a reference. If you've
 already created the `secret_scanning` rule, you may choose to skip this section.
 
-Start by creating a rule that checks if secret scanning is enabled.  
+Start by creating a rule that checks if secret scanning is enabled.
 
 Create a new file called `secret_scanning.yaml`.
 
-Add some basic information about the rule to the new file, such as the version, type, name, context, description and 
+Add some basic information about the rule to the new file, such as the version, type, name, context, description and
 guidance.
 
 ```yaml
@@ -60,6 +64,7 @@ guidance: |
 
 Next, add the rule definition to the `secret_scanning.yaml` file.
 Set `in_entity` to be `repository`, since secret scanning is enabled on the repository.
+
 ```yaml
 def:
   in_entity: repository
@@ -106,7 +111,7 @@ def:
           def: ".enabled"
 ```
 
-Set up the remediation action that will be taken if this rule is not satisfied 
+Set up the remediation action that will be taken if this rule is not satisfied
 (and the profile has turned on remediation). The remediation action in this case is to make a PATCH request to the
 repository and enable secret scanning.
 ```yaml
@@ -220,6 +225,7 @@ repository:
 ```
 
 Putting it all together, you get the following content if `profile.yaml`:
+
 ```yaml
 version: v1
 type: profile
@@ -260,7 +266,7 @@ In Minder profiles, rules are identified by their type and, optionally, a unique
 
 ### Rule Types vs Rule Names
 
-Rule types are mandatory and refer to the kind of rule being applied. Rule names, on the other hand, are optional 
+Rule types are mandatory and refer to the kind of rule being applied. Rule names, on the other hand, are optional
 identifiers that become crucial when multiple rules of the same type exist under an entity.
 
 ```yaml
@@ -270,11 +276,12 @@ repository:
     def:
       enabled: true
 ```
+
 In this example, `secret_scanning` is the rule type and `secret_scanning_github` is the rule name.
 
 ### When are Rule Names Mandatory?
 
-If you're using multiple rules of the same type under an entity, each rule must have a unique name. This helps 
+If you're using multiple rules of the same type under an entity, each rule must have a unique name. This helps
 distinguish between rules and understand their specific purpose.
 
 ```yaml
@@ -292,7 +299,7 @@ Here, we have two rules of the same type `secret_scanning` under the `repository
 
 ### Uniqueness of Rule Names
 
-No two rules, whether of the same type or different types, can have the same name under an entity. This avoids 
+No two rules, whether of the same type or different types, can have the same name under an entity. This avoids
 confusion and ensures each rule can be individually managed.
 
 ```yaml
@@ -306,8 +313,8 @@ repository: # Would return an error while creating
     def:
       enabled: false
 ```
-In the above used example, even though the rules are of different types (`secret_scanning` and `secret_push_protection`), 
-Minder will return an error while creating this profile as rule names are same under the same entity. 
+In the above used example, even though the rules are of different types (`secret_scanning` and `secret_push_protection`),
+Minder will return an error while creating this profile as rule names are same under the same entity.
 You may use same rule names under different entities (repository, artifacts, etc.)
 
 Rule name should not match any rule type, except its own rule type. If a rule name matches its own rule type, it should
@@ -334,8 +341,8 @@ the explicit name of the `gomod` rule.
 
 ### Example
 
-Consider a profile with two `dependabot_configured` rules under the `repository` entity. The first rule has a unique 
-name, "Dependabot Configured for GoLang". The second rule doesn't have a name, which is acceptable as Minder would 
+Consider a profile with two `dependabot_configured` rules under the `repository` entity. The first rule has a unique
+name, "Dependabot Configured for GoLang". The second rule doesn't have a name, which is acceptable as Minder would
 add rule type as the default name for the rule.
 
 ```yaml
@@ -353,5 +360,5 @@ repository:
       apply_if_file: docs/package.json
 ```
 
-You can find the rule definitions used above and many profile examples at 
+You can find the rule definitions used above and many profile examples at
 [minder-rules-and-profiles](https://github.com/stacklok/minder-rules-and-profiles) repository.

docs/docs/how-to/create_project.md

@@ -0,0 +1,31 @@
+---
+title: Creating a New Project
+sidebar_position: 90
+---
+
+When you log in to Minder without a project, Minder will automatically create a
+new project to manage your entities (repositories, artifacts, etc). It is also
+possible to create additional projects after you have created your Minder
+profile, for example, to create different projects for different organizations
+or teams you are a part of. Note that
+[Minder Projects](../understand/projects.md) can collect resources from several
+upstream resource providers such as different GitHub organizations, so you can
+register several [entity providers](../understand/providers.md) within a
+project.
+
+## Prerequisites
+
+- A Minder account
+- A GitHub organization you are an administrator for which does not have the
+  Minder app installed on.
+
+## Creating a New Project
+
+To create a new project, enable the Minder GitHub application
+([Minder by Stacklok](https://github.com/apps/minder-by-stacklok) for the
+cloud-hosted application) on a new GitHub organization. If the GitHub App is
+installed on a GitHub organization which is not already registered in Minder,
+Minder will create a new project to manage those resources. Using
+[`minder provider enroll`](../ref/cli/minder_provider_enroll.md) within a
+project to add a new GitHub provider will _not_ create a new project and will
+add the selected organization to an existing project.

docs/docs/how-to/pr_reviews.md

@@ -7,9 +7,10 @@ import TabItem from '@theme/TabItem';
 
 ## Prerequisites
 
-* The `minder` CLI application
-* A Minder account
-* An enrolled Provider (e.g., GitHub) and registered repositories
+- The `minder` CLI application
+- A Minder account with
+  [at least `editor` permission](../user_management/user_roles.md)
+- An enrolled Provider (e.g., GitHub) and registered repositories
 
 ## Create the PR vulnerability check rule
 Start by creating a rule that checks if a pull request adds a new dependency with known vulnerabilities. If it does,
@@ -130,10 +131,10 @@ Create the profile in Minder:
 minder profile create -f profile.yaml
 ```
 
-Once the profile is created, Minder will monitor any pull requests to the registered repositories. If a pull 
+Once the profile is created, Minder will monitor any pull requests to the registered repositories. If a pull
 request brings in a dependency with a known vulnerability, then Minder will add a review to the pull request and
 suggest changes.
 
 Alerts are complementary to the remediation feature. If you have both `alert` and `remediation` enabled for a profile,
 Minder will attempt to remediate it first. If the remediation fails, Minder will create an alert. If the remediation
-succeeds, Minder will close any previously opened alerts related to that rule.
+succeeds, Minder will close any previously opened alerts related to that rule.

docs/docs/how-to/remediate-pullrequest.md

@@ -10,13 +10,14 @@ import TabItem from '@theme/TabItem';
 
 ## Prerequisites
 
-* The `minder` CLI application
-* A Minder account
-* An enrolled Provider (e.g., GitHub) and registered repositories
+- The `minder` CLI application
+- A Minder account with
+  [at least `editor` permission](../user_management/user_roles.md)
+- An enrolled Provider (e.g., GitHub) and registered repositories
 
 ## Create a rule type that has support for pull request automatic remediation
 
-The pull request automatic remediation feature provides the functionality to fix a failed rule type by creating a pull request. 
+The pull request automatic remediation feature provides the functionality to fix a failed rule type by creating a pull request.
 
 This feature is only available for rule types that support it. To find out if a rule type supports it, check the
 `remediate` section in their `<alert-type>.yaml` file. It should have the `pull_request` section defined like below:
@@ -31,8 +32,8 @@ type: rule-type
 ```
 
 In this example, we will use a rule type that checks if a repository has Dependabot enabled. If it's not enabled, Minder
-will create a pull request that enables Dependabot. The rule type is called `dependabot_configured.yaml` and is one of 
-the reference rule types provided by the Minder team.
+will create a pull request that enables Dependabot. The rule type is called `dependabot_configured.yaml` and is
+one of the reference rule types provided by the Minder team.
 
 Fetch all the reference rules by cloning the [minder-rules-and-profiles repository](https://github.com/stacklok/minder-rules-and-profiles).
 

docs/docs/how-to/setup-alerts.md

@@ -7,15 +7,17 @@ sidebar_position: 70
 
 ## Prerequisites
 
-* The `minder` CLI application
-* A Minder account
-* An enrolled Provider (e.g., GitHub) and registered repositories
+- The `minder` CLI application
+- A Minder account with
+  [at least `editor` permission](../user_management/user_roles.md)
+- An enrolled Provider (e.g., GitHub) and registered repositories
 
 ## Create a rule type that you want to be alerted on
 
 The `alert` feature is available for all rule types that have the `alert` section defined in their `<alert-type>.yaml`
 file. Alerts are a core feature of Minder providing you with notifications about the status of your registered
-repositories using GitHub Security Advisories. These Security Advisories automatically open and close based on the evaluation of the rules defined in your profiles.
+repositories using GitHub Security Advisories. These Security Advisories automatically open and close based on the evaluation of the rules
+defined in your profiles.
 
 When a rule fails, Minder opens 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.

docs/docs/how-to/setup-autoremediation.md

@@ -7,9 +7,10 @@ sidebar_position: 60
 
 ## Prerequisites
 
-* The `minder` CLI application
-* A Minder account
-* An enrolled Provider (e.g., GitHub) and registered repositories
+- The `minder` CLI application
+- A Minder account with
+  [at least `editor` permission](../user_management/user_roles.md)
+- An enrolled Provider (e.g., GitHub) and registered repositories
 
 ## Create a rule type that you want to use auto-remediation on
 
@@ -20,7 +21,7 @@ creating a pull request with a proposed fix.
 
 In this example, we will use a rule type that checks if a repository allows having force pushes on their main branch,
 which is considered a security risk. If their setting allows for force pushes, Minder will automatically remediate it
-and disable it. 
+and disable it.
 
 The rule type is called `branch_protection_allow_force_pushes.yaml` and is one of the reference rule types provided by
 the Minder team.
@@ -44,6 +45,7 @@ minder ruletype create -f rule-types/github/branch_protection_allow_force_pushes
 ```
 
 ## Create a profile
+
 Next, create a profile that applies the rule to all registered repositories.
 
 Create a new file called `profile.yaml` using the following profile definition and enable automatic remediation by setting

docs/docs/understand/projects.md

@@ -5,8 +5,24 @@ sidebar_position: 20
 
 # Projects in Minder
 
-Projects in Minder are a way to group entities together. They are a way to organize your entities (repositories, artifacts,
-etc.) based on the policy you want to enforce or the team that owns them.
+Projects in Minder are a way to group entities together, and to share access
+with other people in your organization. They are a way to organize your entities
+(repositories, artifacts, 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.
+Each user in an project is [assigned a role](../user_management/user_roles.md),
+such as `editor` or `admin`. Projects must have at least one administrator, who
+has permission to
+[invite other users to the project](../user_management/adding_users.md) and
+change users roles within the project.
+
+When creating an account, Minder will automatically create a default project for
+you, unless you are accepting an invitation to an existing project. You can
+[create additional projects](../how-to/create_project.md) as a way to organize
+and secure your entities, and manage access for your team members.
+
+If you are a member (have a role in) more than one project, you can use
+[the `MINDER_PROJECT` environment variable](../ref/cli_configuration.md) or the
+`--project` flag to select a specific project to operate on with the CLI. If you
+have access to multiple projects and no project is selected, Minder will report
+an error asking you to select a project.