Clarification folders and git sync (#745)

docs/advanced/12_deploy_to_prod/index.mdx

@@ -4,12 +4,12 @@ import DocCard from '@site/src/components/DocCard';
 
 To deploy to prod, 3 options are possible:
 
-## Option 1. Draft and deploy - Single Workspace
+## Option 1. Draft and deploy - Single workspace
 
 A simple setup in which deploying to prod means deploying items that have been iterated on in the UI as Drafts.
 Deployments in Windmill are commonly done from the same workspace using the [Draft and deploy](../../core_concepts/0_draft_and_deploy/index.mdx) buttons.
 
-## Option 2. Deploy to prod using a git workflow - Multi Workspace
+## Option 2. Deploy to prod using a git workflow - Multi workspace
 
 The integration can be used to push from git, and receive changes done from the UI in a bi-directional way.
 You can also use a separate dev and staging branch and repo and have Windmill create automatically branches and Pull Request upon any changes deployed to staging/dev.
@@ -22,7 +22,7 @@ You can also use a separate dev and staging branch and repo and have Windmill cr
 	/>
 </div>
 
-This process can be used in particular for local development with a solid setup:
+This process can be used in particular for [local development](../4_local_development/index.mdx) with a solid setup:
 
 ![Local development Setup](../4_local_development/local_development.png 'Local development Setup')
 
@@ -34,7 +34,7 @@ This process can be used in particular for local development with a solid setup:
 	/>
 </div>
 
-## Option 3. Deploy to prod using the UI only - Multi Workspace
+## Option 3. Deploy to prod using the UI only - Multi workspace
 
 From a workspace in Windmill, you can deploy a script/flow/resource/variable and all its dependencies to another workspace.
 

docs/advanced/4_local_development/index.mdx

@@ -12,7 +12,7 @@ To simply create and edit scripts and flows locally, you can directly go to the
 
 For a more complex setup involving Git, you can go to the [Local development Recommended Setup](#local-development-recommended-setup).
 
-## Local development Recommended Setup
+## Local development recommended setup
 
 Local development involves two components:
 
@@ -48,11 +48,12 @@ The second part is well covered in:
 
 ## Develop locally
 
-Local development quickstart:
+You can develop locally by using [Windmill CLI](../3_cli/index.mdx) to clone a workspace and edit scripts and flows in your favorite IDE.
+
+Here is a quickstart video:
 
 <video
 	className="border-2 rounded-lg object-cover w-full h-full dark:border-gray-800"
-	autoPlay
 	controls
 	id="Local development quickstart"
 	src="/videos/local_dev_quickstart.mp4"
@@ -66,9 +67,13 @@ All details and commands are available [below](#editing-and-creating-scripts-loc
 
 Developing Windmill scripts and flows from your favorite IDE is made easy by using Windmill CLI. Here we will go through the full process of cloning a Windmill workspace locally, creating and editing new scripts and flows, and pushing them back the Windmill workspace.
 
-:::tip
-Not familiar with Windmill CLI? Get started with it [here](../3_cli/installation.md).
-:::
+<div className="grid grid-cols-2 gap-6 mb-4">
+	<DocCard
+		title="Command-line interface (CLI)"
+		description="The Windmill CLI, `wmill` allows you to interact with Windmill instances right from your terminal."
+		href="/docs/advanced/cli"
+	/>
+</div>
 
 The first step is to clone an existing Windmill workspace into a local folder.
 
@@ -90,7 +95,7 @@ This will download the content of the workspace into your local folder. You will
 
 :::caution
 
-`wmill sync pull` will pull everything from the Windmill workspace, including resources and variables, even secrets. If you're planning to use Git as explained below, we recommend only pulling scripts, flows and apps, skipping the rest. It can be done with:
+[`wmill sync pull`](../3_cli/sync.mdx) will pull everything from the Windmill workspace, including resources and variables, even secrets. If you're planning to use Git as explained below, we recommend only pulling scripts, flows and apps, skipping the rest. It can be done with:
 
 ```bash
 wmill sync pull --skip-variables --skip-secrets --skip-resources
@@ -139,7 +144,7 @@ wmill flow bootstrap f/my_space/groundbreaking_flow
 wmill sync push
 ```
 
-Once the workspace folder is pulled, edits can be made using any IDE.
+Once the workspace folder is pulled, edits can be made using any IDE (including the [VS Code extension](../../cli_local_dev/1_vscode-extension/index.mdx)).
 
 When created and edited through the UI (Windmill App), the lockfile is automatically generated. On local development, each script gets:
 - a content file (`script_path.py`, `script_path.ts`, `script_path.go`, etc.) that contains the code of the script,
@@ -154,7 +159,7 @@ Editing a script is as simple as editing its content. The code can be edited fre
 
 Some fields of the metadata file can also be edited by hand, like the summary of the description fields. If you update the dependencies of your script, or the signature of the `main` method, the lockfile and/or the script schema will need to be updated. We do not recommend doing it by hand.
 
-[Windmill CLI](../3_cli/index.mdx) comes with a `wmill script generate-metadata` command that will read all the files that have been edited and gracefully update the metadata file and lockfile accordingly.
+[Windmill CLI](../3_cli/index.mdx) comes with a [`wmill script generate-metadata`](../3_cli/script.md#re-generating-a-script-metadata-file) command that will read all the files that have been edited and gracefully update the metadata file and lockfile accordingly.
 This command is mainly used update the lockfile and schema inplace. Be re-assured, any manual update to other files like summary and description will be kept:
 
 _Generate metadata command:_

docs/advanced/9_deploy_gh_gl/index.md → docs/advanced/9_deploy_gh_gl/index.mdx

@@ -4,35 +4,36 @@ import DocCard from '@site/src/components/DocCard';
 
 Windmill integration with Git repositories makes it possible to adopt a robust development process for your Windmill scripts, flows and apps.
 
+![Local development Setup](../4_local_development/local_development.png 'Local development Setup')
+
 The integration with git works in three-folds:
 
-1. GitHub Action + [CLI](../3_cli/index.mdx): upon any commit to a particular branch, the GitHub action will run the `wmill` CLI and push to a Windmill workspace this works using the CLI doing `wmill sync push` ([free & open source](/pricing))
+1. [GitHub Action](https://docs.github.com/en/actions) + [CLI](../3_cli/index.mdx): upon any commit to a particular branch, the GitHub action will run the `wmill` CLI and push to a Windmill workspace this works using the CLI doing `wmill sync push` ([free & open source](/pricing))
 2. [Git sync](../11_git_sync/index.mdx) (Workspace mode): Windmill automatically committing to a git repository upon any deployment to a workspace, this works using the CLI doing `wmill sync pull` ([Cloud and Enterprise Self-Hosted](/pricing)). Having it commit back to Windmill has 2 benefits:
 
-- It ensures that any automatically created metadata files are wrote-back (in case you pushed a script without its metadata for instance).
-- It ensures that any modification done in the UI is kept in sync with the git repository and guarantees a bi-sync between the repo and the UI.
+    - It ensures that any automatically created metadata files are wrote-back (in case you pushed a script without its metadata for instance).
+    - It ensures that any modification done in the UI is kept in sync with the git repository and guarantees a bi-sync between the repo and the UI.
 
 3. [Git sync](../11_git_sync/index.mdx) (Item mode): Windmill automatically creates a branch specific to that item (and whose name is derived from that item) that targets the branch set in the git sync settings, upon any change to any items, be it from the UI or from git ([Cloud and Enterprise Self-Hosted](/pricing)). This should be coupled with a GitHub action that automatically create a PR when a branch is created. This PR can then be reviewed and merged. Upon being merged to the prod branch, a GitHub action as described in 1. would then deploy it to the prod branch.
 
 Once everything is set up, the process is as follows:
 
 - Users iterate and make their changes in the "staging" Windmill workspace UI or in the git staging branch directly.
 - Every time a Windmill App, Flow or Script is deployed to that workspace (via Windmill's UI or through the GitHub action that deploys to staging upon any change), Windmill automatically sync it back to the repo on the "staging" branch (Git sync - Workspace mode) and also create a branch that targets prod and keep it in sync with any new changes (Git sync - Item mode)
-- On every new branch created, PRs are automatically created via a [GitHub Action](https://docs.github.com/en/actions). Approved GitHub users can review and merge those PRs.
+- On every new branch created, PRs are automatically created via a GitHub Action. Approved GitHub users can review and merge those PRs.
 - Every time a PR is merged, another GitHub Action automatically deploys the change to a "production" Windmill workspace.
 
 Note that although the CLI is used by both the GitHub Action and the Git sync, the CLI does not need to be used directly by any users and everything happen behind the scene in an automated way.
 
 This gives the flexibility to fully test new Windmill scripts, flows and apps, while having them [version-controlled](../13_version_control/index.mdx) and deployed in an automated way to the production environment.
 
+This process can be used in particular for [local development](../4_local_development/index.mdx).
+
 :::tip
 
 Check out the [windmill-sync-example repository](https://github.com/windmill-labs/windmill-sync-example) as an illustration of this process.
-:::
 
-This process can be used in particular for [local development](../4_local_development/index.mdx) with a solid setup:
-
-![Local development Setup](../4_local_development/local_development.png 'Local development Setup')
+:::
 
 More details at:
 
@@ -50,6 +51,14 @@ Deploying to a prod workspace using git requires the [Git sync](../11_git_sync/i
 
 From the workspace settings, you can set a [git_repository](../../integrations/git_repository.mdx) resource on which the workspace will automatically commit and push scripts, flows and apps to the repository on each [deploy](../../core_concepts/0_draft_and_deploy/index.mdx).
 
+<div className="grid grid-cols-2 gap-6 mb-4">
+	<DocCard
+		title="Git sync"
+		description="Connect a Windmill workspace to a Git repository to automatically commit and push scripts, flows and apps to the repository on each deploy."
+		href="/docs/advanced/git_sync"
+	/>
+</div>
+
 ## Setup the full Git workflow
 
 Note: this is the detailed setup steps for a [GitHub](https://github.com/) repository. It will need to be adapted for [GitLab](https://about.gitlab.com/).
@@ -73,15 +82,14 @@ If you are not using the [Enterprise Edition](/pricing) (EE) version of Windmill
 :::
 
 :::tip
-The guide covers a staging and prod setup. To add an additional dev environment, simply consider staging to be the target of the dev workspace and prod to be the target of the staging workspace..
+The guide covers a staging and prod setup. To add an additional dev environment, simply consider staging to be the target of the dev workspace and prod to be the target of the staging workspace.
 :::
 
-:::tip
-What about variables, resources and secrets?
+### Variables, resources and secrets
 
-The CLI is able to sync variables, resources and secrets as well. However, everywhere the CLI is used here, it it set with the flags `--skip-variables --skip-secrets --skip-resources` to avoid syncing them. This is because variables, resources and secrets should have values that are specific to each environment. For instance, a resource named `f/myproject/myimportantdb` should have a different value in staging and prod. This is why they are not synced and should be set manually in each environment. You can however if you prefer, manually sync those. Do note that secrets have an additional layer of encryption and are by default exported in their encrypted form whose decryption key is workspace specific. To sync them between workspace, use `--plain-secrets` to export them in plain text.
+The [CLI](../3_cli/index.mdx) is able to sync [variables](../../core_concepts/2_variables_and_secrets/index.mdx), [resources](../../core_concepts/3_resources_and_types/index.mdx) and [secrets](../../core_concepts/2_variables_and_secrets/index.mdx#secrets) as well. However, everywhere the CLI is used here, it it set with the flags `--skip-variables --skip-secrets --skip-resources` to avoid syncing them. This is because variables, resources and secrets should have values that are specific to each environment.
 
-:::
+For instance, a resource named `f/myproject/myimportantdb` should have a different value in staging and prod. This is why they are not synced and should be set manually in each environment. You can however if you prefer, manually sync those. Do note that secrets have an additional layer of encryption and are by default exported in their encrypted form whose decryption key is workspace specific. To sync them between workspace, use `--plain-secrets` to export them in plain text.
 
 ### GitHub repository setup
 

docs/cli_local_dev/1_vscode-extension/index.mdx

@@ -122,7 +122,7 @@ Editing the flow from the UI immediately modifies the YAML definition
 
 ### Infer lockfile or Use current lockfile
 
-With this toggle, you can choose to use the metadata lockfile ([derived from](../../advanced/3_cli/script.md#packagejson--requirementstxt) package.json or requirements.txt after `wmill script generate-metadata`) instead of inferring them directly from the script.
+With this toggle, you can choose to use the metadata lockfile ([derived from](../../advanced/3_cli/script.md#packagejson--requirementstxt) package.json or requirements.txt after [`wmill script generate-metadata`](../../advanced/3_cli/script.md#re-generating-a-script-metadata-file)) instead of inferring them directly from the script.
 
 ![Toggle Lockfile](./toggle_lockfile.png 'Toggle Lockfile')
 

docs/core_concepts/8_groups_and_folders/index.mdx

@@ -16,6 +16,20 @@ Recap of how permissions are given to an item (script, flow, resource, variable,
 	/>
 </div>
 
+## Folders
+
+Folders group various items, such as scripts, flows, resources, and schedules, together and assign [role](../16_roles_and_permissions/index.mdx#roles-in-windmill)-based access control permissions to groups and individual users.
+
+![Folders](./3-folders.png 'Folders')
+
+Folders should represent projects, and we recommend assigning permissions to groups. You should have as many top-level folders that you have different projects/permission scopes.
+
+### Subfolders
+
+You can have as many subfolders as you want but only the top-level folder will have permissions one can inherit from.
+
+To use subfolders, you just need to have '/' in the last part of the [path](../16_roles_and_permissions/index.mdx#path) of an item, like you would do on a filesystem.
+
 ## Groups
 
 Groups of users are a way to classify users together, allowing for shared permissions within the workspace. Users within the same group (also referred to as a role) will have homogenous permissions. Users can belong to multiple groups simultaneously.
@@ -28,12 +42,6 @@ Similar to users, groups can be assigned one of three permission levels for a sp
 - Writer: read and write access.
 - Admin: read and write access, and can manage permissions and new admins.
 
-## Folders
-
-Folders group various **items**, such as scripts, flows, resources, and schedules, together and assign Role-based access control permissions to groups and individual users.
-
-![Folders](./3-folders.png 'Folders')
-
 ## Groups and folders together
 
 Groups and folders work together to organize permissions and access control within your workspace. Groups can be included within folders, but folders cannot be nested within groups.

docs/integrations/github.mdx

@@ -19,7 +19,7 @@ The GitHub integration is done through OAuth. You just need to sign in from your
 
 On [self-hosted instances](../advanced/1_self_host/index.mdx), integrating an OAuth API will require [Setup OAuth and SSO](../misc/2_setup_oauth/index.mdx).
 
-You might also look for how to [version control from GitHub / GitLab](../advanced/9_deploy_gh_gl/index.md).
+You might also look for how to [version control from GitHub / GitLab](../advanced/9_deploy_gh_gl/index.mdx).
 
 <div className="grid grid-cols-2 gap-6 mb-4">
 	<DocCard

docs/misc/16_partners/index.mdx

@@ -81,7 +81,7 @@ For flows, we require partners to be capable of creating custom flows with multi
 
 ### Have a dev/staging/prod setup for version controls and permissioning fit for larger organizations
 
-Be able to set up a custom [local development](../../advanced/4_local_development/index.mdx) environment, including a [git workflow](../../advanced/9_deploy_gh_gl/index.md) between a staging and a production workspace with [version control](../../advanced/13_version_control/index.mdx).
+Be able to set up a custom [local development](../../advanced/4_local_development/index.mdx) environment, including a [git workflow](../../advanced/9_deploy_gh_gl/index.mdx) between a staging and a production workspace with [version control](../../advanced/13_version_control/index.mdx).
 You have experience setting those up with GitHub and GitLab.
 
 You know how to handle [permissions](../../core_concepts/16_roles_and_permissions/index.mdx) at the instance and workspace-level, and within the git workflow.