chore(snowflake): add tldr on how rollout tends to work

knowledge base/snowflake/README.md

@@ -12,7 +12,7 @@ Cloud-based [data warehousing][data warehouse] platform.
    1. [Authentication policies](#authentication-policies)
    1. [Network policies](#network-policies)
 1. [Snowflake CLI](#snowflake-cli)
-1. [RoleOut](#roleout)
+1. [Roleout](#roleout)
 1. [Connecting privately](#connecting-privately)
    1. [From AWS accounts](#from-aws-accounts)
 1. [Further readings](#further-readings)
@@ -826,12 +826,12 @@ Meant to replace the SnowSQL tool.
 
 See [Snowflake CLI].
 
-## RoleOut
+## Roleout
 
 Project trying to accelerate the design and deployment of Snowflake environments through Infrastructure as Code.<br/>
 Useful to view and configure the permissions matrix in a graphical way.
 
-Refer [RoleOut].
+Refer [Roleout].
 
 ## Connecting privately
 
@@ -891,7 +891,7 @@ Snowflake recommends **avoiding** this approach.
 
 <!-- Knowledge base -->
 [Data warehouse]: ../data%20warehouse.md
-[RoleOut]: roleout.md
+[Roleout]: roleout.md
 [Snowflake CLI]: cli.md
 
 <!-- Files -->

knowledge base/snowflake/roleout.md

@@ -1,4 +1,4 @@
-# RoleOut
+# Roleout
 
 Project trying to accelerate the design and deployment of Snowflake environments through Infrastructure as Code.
 
@@ -7,13 +7,39 @@ Project trying to accelerate the design and deployment of Snowflake environments
 
 ## TL;DR
 
-Administrators define Snowflake resources in a YAML file. RoleOut then uses it to generate SQL or Terraform code for
+Administrators define Snowflake resources in a YAML file. Roleout then uses it to generate SQL or Terraform code for
 deployment.
 
 > [!important]
 > The tool applies opinionated best practices.<br/>
 > It also comes with its own naming convention, but it can be tweaked.
 
+The way Roleout works is that:
+
+1. One _optionally_ defines one or more environments (e.g. `DEV`, `PROD`).
+1. One defines the databases and their schemas once (e.g., `DWH`).<br/>
+   If any environment is defined, a DB is created for each of them (e.g. `DEV_DWH.whatever`, `PROD_DWH.whatever`).
+1. One defines the virtual warehouses.<br/>
+   If any environment is defined, a virtual warehouse is created for each of them (e.g. `DEV_whatever_WH`,
+   `PROD_whatever_WH`).
+1. One defines the functional roles.
+1. One specifies the permissions matrix for databases and virtual warehouses.<br/>
+   If any environment is defined, a matrix is defined for each of them.<br/>
+   Permissions can be `Read`, `ReadWrite`, or `Full`.
+1. Each matrix forces the creation of
+
+   - One role per environment per permission, e.g.:
+
+     - `DEV_DWH_whatever_R_AR`, `PROD_DWH_whatever_R_AR` for read-only permissions.
+     - `DEV_DWH_whatever_RW_AR`, `PROD_DWH_whatever_RW_AR` for read-write permissions.
+     - `DEV_DWH_whatever_FULL_AR`, `PROD_DWH_whatever_FULL_AR` for full access permissions.
+
+   - One warehouse-specific role per environment per permission, e.g.:
+
+     - `DEV_whatever_WH_U_AR`, `PROD_whatever_WH_U_AR` for read-only permissions.
+     - `DEV_whatever_WH_UM_AR`, `PROD_whatever_WH_UM_AR` for read-write permissions.
+     - `DEV_whatever_WH_FULL_AR`, `PROD_whatever_WH_FULL_AR` for full access permissions.
+
 <details>
   <summary>Setup</summary>
 
@@ -28,7 +54,8 @@ curl -C '-' -LfSO --url 'https://github.com/Snowflake-Labs/roleout/releases/down
 && xattr -d 'com.apple.quarantine' "$HOME/bin/roleout-cli"
 
 # Configure access
-export SNOWFLAKE_ACCOUNT='ab01234.eu-west-1' \
+export \
+  SNOWFLAKE_ACCOUNT='ab01234.eu-west-1' \
   SNOWFLAKE_USER='DIANE' SNOWFLAKE_PRIVATE_KEY_PATH='some-private-key-path' \
   SNOWFLAKE_WAREHOUSE='DEV_DIANE_WH' SNOWFLAKE_ROLE='ACCOUNTADMIN'
 ```