Update cli docs (#1198)

Cleaned up the spelling and grammar. Simplified the language. Added
clarification that Zarf will only try to install k3s on Linux machines.
Added references and links to information that may be unknown or unclear
to the reader.

docs/4-user-guide/1-the-zarf-cli/2-cli-commond-uses.md

@@ -1,36 +1,35 @@
 # Common CLI Uses
 
-Since the main priority of Zarf is to make deploying applications into disconnected environments easier, almost all of the commands Zarf provides really boil down to making it easier to create and deploy packages. This is especially true with the most commonly used commands; `zarf init`, `zarf package create` and `zarf package deploy`. 
-
-
-<br />
-
+Zarf optimizes the delivery of applications and capabilities into any environment, beginning with air-gapped systems. The Zarf CLI uses declarative Zarf Packages to create, deploy, inspect, and remove these applications and capabilities.
 
 ## Building Packages: `zarf package create`
-[`zarf package create`](./100-cli-commands/zarf_package_create.md) is used to create a tar.zst binary file that contains all the necessary dependencies and instructions to deploy a set of functionality onto another machine. We call this tar.zst file a 'package'. The 'package create' command looks for a file called `zarf.yaml` which describes all of the things that make up the package and then does all the work necessary to prepare the output tar.zst package, such as downloading required container images and git repositories. More information on what these Zarf packages are can be found in the [Zarf Packages](../2-zarf-packages/index.md) page.
 
-<br />
+[`zarf package create`](./100-cli-commands/zarf_package_create.md) is used to create a `tar.zst` archive that contains all the necessary dependencies and instructions to deploy capabilities onto another machine. We call this file a 'package'. The `package create` command looks for a `zarf.yaml` configuration file which describes all of the things that make up the package. It then uses the declarative definition of the package to perform all of the actions, such as downloading required container images and git repositories, to create the final package. More detailed information on Zarf packages can be found on the [Zarf](../2-zarf-packages/index.md) Packages](../2-zarf-packages/index.md) page.
 
 ## Initializing a Cluster: `zarf init`
+
 <!-- TODO: Find a good place to talk about what the init command is actually doing (there's a lot of special magic sauce going on with that command) -->
 <!-- TODO: Should we talk about the 'Zarf Agent - A Mutating Webhook' here? -->
-Before you are able to deploy onto a cluster, Zarf needs to initialize the cluster to be ready. This is done through the [`zarf init`](./100-cli-commands/zarf_init.md) command, which injects and starts-up an in-cluster container registry, along with other optional tools and services into your cluster within the Zarf namespace that future packages will need. If you don't have a cluster yet, this command can help with that too! This command uses a specialized package called an 'init-package' that also contains all the resources necessary to create a local k3s cluster on your machine. This init-package can either be located in your current working directory, in the directory where the Zarf CLI binary lives, or be downloaded from the GitHub releases as the command is running. More information about what the 'init' command is doing will be provided soon but more information about the init-package can be found on the [init-package](../2-zarf-packages/3-the-zarf-init-package.md) page.
 
-:::note
-Depending on the permissions of your user, if you are installing k3s through the `zarf init` command you may need to run the command as a privileged user. This can be done by either:
+Before you can deploy a package to a cluster, Zarf needs to initialize the cluster. This is done with [`zarf init`](./100-cli-commands/zarf_init.md). This command creates and bootstraps an in-cluster container registry. It also provides the ability to install optional tools and services into the cluster that future packages will need.
+
+For Windows and macOS environments, A cluster needs to exist before Zarf can initialize it. You can use [Kind](https://kind.sigs.k8s.io/), [K3d](https://k3d.io/), [Docker Desktop](https://docs.docker.com/desktop/kubernetes/), or any other local or remote Kubernetes cluster.
+
+For Linux, Zarf makes it even easier. If you don't have a cluster running, Zarf can take care of that for you. The init package used by `zarf init` also contains all the resources necessary to create a local [k3s](https://k3s.io/) cluster on your machine. The init package can be located in your current working directory, in the directory where the Zarf CLI binary lives, or be downloaded from the GitHub releases as the command is running. More information about the init package can be found on the [init package](../2-zarf-packages/3-the-zarf-init-package.md) page.
+
+::: note
+Depending on the permissions of your user, if you are installing k3s with `zarf init`, you may need to run it as a privileged user. This can be done by either:
 
 1. Becoming a privileged user via the command `sudo su` and then running all the Zarf commands as you normally would.
-2. Manually running all the Zarf commands as a privileged user via the command `sudo {ZARF_COMMAND_HERE}`.
+2. Manually running all the Zarf commands as a privileged user via the command `sudo <command>`.
 3. Running the init command as a privileged user via `sudo zarf init` and then changing the permissions of the `~/.kube/config` file to be readable by the current user.
-:::
-
-<br />
+   :::
 
 ## Deploying Packages: `zarf package deploy`
 
-<!-- The most common use case (like 99.9% of the time) is deploying onto a k8s cluster.. but that doesn't HAVE to be the case.. How do I write the docs for this then? -->
 <!-- TODO: Write some docs (or reddirect to other docs) describing when you would be able to do a `zarf package deploy` before a `zarf init` -->
-As stated many times now, the entire purpose of Zarf is to make it easier to deploy applications onto air gapped environments. This is where that magic happens! [`zarf package deploy`](./100-cli-commands/zarf_package_deploy.md) is used to deploy an already built tar.zst package onto a machine, usually specifically into a k8s cluster. It is usually assumed that the `zarf init` command has already been run on the machine you are deploying to but there are a few rare cases where this doesn't apply. 
+
+The [`zarf package deploy`](./100-cli-commands/zarf_package_deploy.md) command is where the air-gapped magic happens. It deploys our packaged capabilities into our target environment. It is usually assumed that the `zarf init` command has already been run on the machine you are deploying to but there are a few cases where this doesn't apply such as [YOLO Mode](../../9-faq.md#what-is-yolo-mode-and-why-would-i-use-it)
 
 Since the package has all of its dependencies built-in, it can be deployed onto any cluster, even without an external internet connection. The dependency resources are pushed onto the cluster in their respective places, such as an in-cluster Gitea Git server or Docker registry, and then the application is deployed as instructed in the `zarf.yaml` file (i.e. deploying a helm chart, deploying raw k8s manifests, or even just executing a series of shell commands).
 

docs/4-user-guide/2-zarf-packages/1-zarf-packages.md

@@ -6,48 +6,43 @@ sidebar_position: 1
 
 A Zarf package is a single tarball archive that contains everything you need to deploy a system or capability while fully disconnected. Zarf packages are defined by a `zarf.yaml` file.
 
-Zarf packages are built while 'online' and connected to whatever is hosting the dependencies your package definition defined. When being built, all these defined dependencies are downloaded and stored within the archive. Because all the dependencies are now within the tarball, the package can be deployed on to disconnected systems that don't have connection to the outside world.
+Zarf packages are built while 'online' and connected to whatever is hosting the dependencies your package definition defined. When being built, all these defined dependencies are downloaded and stored within the archive. Because all the dependencies are now within the tarball, the package can be deployed on to disconnected systems that don't have a connection to the outside world.
 
-The `zarf.yaml` file, that the package builds from, defines declarative instructions on how capabilities of the package should be deployed. The declarative nature of the package means everything is represented by code and automatically runs as it is configured, instead of having to give manual steps that might not be reproducible on all systems.
+The `zarf.yaml` file, which the package builds from, defines declarative instructions on how the capabilities of the package should be deployed. The declarative nature of the package means everything is represented by code and automatically runs as it is configured, instead of having to give manual steps that might not be reproducible on all systems.
 
 Zarf Packages are made up of functionality blocks called components which are described more in the [Zarf Components page](./2-zarf-components.md). These components can be optional, giving more flexibility to how packages can be used.
 
-<br />
-
 <!-- TODO: @JPERRY This feels out of place here.. -->
 
 ## Deploying on to Airgapped Systems
 
-Zarf packages are built with all the dependencies necessary being included within the package itself, this is important when deploying on to systems. Since there is no need for an outbound connection to the internet, these packages become highly distributable and can be run on edge, embedded systems, secure cloud, data centers, or even in a local environment. When deploying a package onto a cluster, the dependencies of the cluster (which were included in the package itself when it was created) are pushed into a docker registry and git server that Zarf stands up on the airgapped system. This way later steps can use the dependencies as they are needed.
-
-<br />
-<br />
+Zarf packages are built with all the dependencies necessary being included within the package itself, this is important when deploying on to systems. Since there is no need for an outbound connection to the internet, these packages become highly distributable and can be run on edge, embedded systems, secure cloud, data centers, or even in a local environment. When deploying a package onto a cluster, the dependencies of the cluster (which were included in the package itself when it was created) are pushed into a docker registry and git server that Zarf stands up on the air-gapped system. This way later steps can use the dependencies as they are needed.
 
 ## Types of Zarf Packages
 
 There are two types of Zarf packages, a `ZarfInitConfig` and a `ZarfPackageConfig`. The package type is defined by the `kind:` field in the zarf.yaml file.
 
-For the remainder of the docs, we will often refer to the `ZarfInitConfig` as an `init config` or `init package` package and the `ZarfPackageConfig` as any `package`.
+For the remainder of the docs, we will often refer to the `ZarfInitConfig` as an `init config` package or `init` package and the `ZarfPackageConfig` as any package.
 
 ### ZarfInitConfig
 
-The init package is the package you use to initialize your cluster to be ready to deploy other Zarf packages on to. Because the init package is a special package, we have more documentation in the [Zarf 'init' Package page](./3-the-zarf-init-package.md) if you're still curious after reading this section.
+The init package is the package you use to initialize your cluster to be ready to deploy other Zarf packages. Because the init package is special, we have more documentation on the Zarf ['init' package page](./3-the-zarf-init-package.md) if you're still curious after reading this section.
 
 **The init package needs to be run once on every cluster you want to deploy another package onto, even if the clusters share the same host.**
 
-If you don't have a cluster running yet, the init-package can help with that too! The init-package has a deployable k3s cluster as a component that can optionally be deployed onto your machine. An init-package will almost always be the first Zarf package you deploy onto a cluster since other packages will often depend on the services the package installs onto your cluster.
+If you don't have a cluster running yet, the init package can help with that too! The init package has a deployable k3s cluster as a component that can optionally be deployed onto your machine. An init package will almost always be the first Zarf package you deploy onto a cluster since other packages will often depend on the services the package installs onto your cluster.
 
-> Note: The only exception where you wouldn't deploy an init package first is when you don't have a k8s cluster yet, you don't want to deploy with the k3s distro built into the init-package and you have a package that deploys your preferred distro. In those situations, you can deploy the distro package first, then the init-package, and then whatever other packages you want.)
+> Note: The only exception where you wouldn't deploy an init package first is when you don't have a k8s cluster yet, you don't want to deploy with the k3s distro built into the init package and you have a package that deploys your preferred distro. In those situations, you can deploy the distro package first, then the init package, and then whatever other packages you want.)
 
-While initializing, Zarf will seed your cluster with an container registry so it can have a place to push images that other packages will need. The init package will also optionally deploy other functionality to your cluster, such as a git-server to push git repositories to, or a simple PLG logging stack so you can monitor the things running on your cluster.
+While initializing, Zarf will seed your cluster with a container registry so it can have a place to push images that other packages will need. The init package will also optionally deploy other functionality to your cluster, such as a git server to push git repositories to, or a simple PLG logging stack so you can monitor the things running on your cluster.
 
 #### Using the init-package
 
-You initialize your cluster by running the command `zarf init`, which will search your current working directory for a file that matches the name `zarf-init-{ARCHITECTURE}-{VERSION}.tar.zst` where the `ARCHITECTURE` matches the architecture of the host you are running on. If the machine your are deploying onto has a different machine architecture, you will have to specify the name of the architecture you are deploying onto. For example, if you are on a arm64 machine but are deploying on a amd64 machine, you will run `zarf init zarf-init-amd64-v0.24.0.tar.zst`
+You initialize your cluster by running the command `zarf init`, which will search your current working directory for a file that matches the name `zarf-init-{ARCHITECTURE}-{VERSION}.tar.zst` where the `ARCHITECTURE` matches the architecture of the host you are running on. If the machine you are deploying onto has a different machine architecture, you will have to specify the name of the architecture you are deploying onto. For example, if you are on an arm64 machine but are deploying on an amd64 machine, you will run `zarf init zarf-init-amd64-v0.24.0.tar.zst`
 
 At the end of the day, init packages are just like other packages, meaning they can also be run with `zarf package deploy zarf-init-{ARCHITECTURE}-{VERSION}.tar.zst`
 
-Init configs are not something you will have to create yourself unless you really want to customize how your cluster is installed / configured (i.e. if you wanted to use the init process to install a specifically configured k3s cluster onto your host machine), and even then it is often easier to create a specific package to do that before your run the init package.
+Init configs are not something you will have to create yourself unless you want to customize how your cluster is installed/configured (i.e. if you wanted to use the init process to install a specifically configured k3s cluster onto your host machine), and even then it is often easier to create a specific package to do that before your run the init package.
 
 ### ZarfPackageConfig
 
@@ -57,20 +52,13 @@ You can deploy a Zarf package with the command `zarf package deploy` which will
 
 When Zarf is deploying the package, it will use the infrastructure that was created when doing the 'init' process (such as the docker registry and git server) to push all of the images and repos that the package needs to operate.
 
-<br />
-<br />
-
 ## What Makes Up A Package
 
 Zarf packages are split into smaller chunks called 'components'. These components are defined more in the [Zarf Components page](./2-zarf-components.md) but a quick way to understand components are as the actual named capabilities that packages provide. The schema of a zarf.yaml package is available here: [ZarfPackage Schema Docs](../3-zarf-schema.md)
 
-<br />
-<br />
-
 ## Building A Zarf Package
 
-
-:::info
+::: info
 
 **Dependencies** for Building a Zarf Package
 
@@ -80,13 +68,10 @@ Zarf packages are split into smaller chunks called 'components'. These component
 
 :::
 
-The process of defining a package is covered in the [Creating Your Own Package](../../13-walkthroughs/0-using-zarf-package-create.md) page. Assuming you have a package already defined, building the package itself is fairly simple.
+The process of defining a package is covered in the [Creating a Package](../../13-walkthroughs/0-using-zarf-package-create.md) page. Assuming you have a package already defined, building the package itself is fairly simple.
 
 `zarf package create` will look for a `zarf.yaml` file in the current directory and build the package from that file. Behind the scenes, this is pulling down all the resources it needs from the internet and placing them in a temporary directory, once all the necessary resources of retrieved, Zarf will create the tarball of the temp directory and clean up the temp directory.
 
-<br />
-<br />
-
 ## Inspecting a Built Package
 
 `zarf package inspect ./path/to/package.tar.zst` will look at the contents of the package and print out the contents of the zarf.yaml file that defined it.