docs: updating/maintenance of CLI command, runtime and local preferences docs (#765)

* chore: clean up runtime docs, spring cleaning of `init` CLI docs

* chore: spring cleaning of `deploy` CLI docs

* chore: updating destroy, env, logs and sandbox help text based on recent architect 11.2.1 updates to help text

* chore: scrub cli help text and local preference docs

Author: filmaj

scripts/dictionary.txt

@@ -23,3 +23,4 @@ LEANX
 Namecheap
 ParcelJS
 treeshaking
+scaffolded

src/views/docs/en/reference/cli/deploy.md

@@ -8,34 +8,34 @@ sections:
   - Flags
 ---
 
-Deploy an Architect project to AWS by creating or updating a [CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) stack with resources declared in [the project manifest](../../get-started/project-manifest).
+Deploy an Architect project to AWS by creating or updating a [CloudFormation][cfn] Stack with resources declared in [the project manifest][manifest].
 
-CloudFormation stack names are created from the name specified in the `@app` pragma and are unique to an AWS region. Changing the project name or region will create a new CF stack.
+[CloudFormation][cfn] Stack names are created from the name specified in [the `@app` pragma][app] and are unique to an AWS region. Changing the project name or region will create a new [CloudFormation][cfn] Stack.
 
 ## Usage
 
 ```bash
-arc deploy [--production|--static|--direct]
+arc deploy [flags]
 ```
 
 ## Flags
 
-- `[--debug, -d]` Displays debug (and verbose) logging.
-- `[--direct path/to/function]` Overwrite staging Lambda with local source. A faster way to deploy and test small changes to individual functions without redeploying an entire stack.
-- `[--dry-run]` Creates a CloudFormation template but does not deploy it. A dry-run allows you to check the CloudFormation and SAM output before deploying the actual stack.
-- `[--fast, -f]` Deploy the stack, but do not hold the process open to determine whether the deployment succeeded or failed within AWS
-- `[--name, -n]` Deploy a custom named staging stack.
-- `[--no-hydrate]` Do not automatically run `npm`, `bundle`, or `pip`
-- `[--production, -p]` Deploys a CloudFormation stack to a production stack.
-- `[--prune]` Remove assets not present in the local static folder.
-- `[--static, -s]` Deploys only the files in the static folder.
-- `[--tags, -t]` Adds resource tags to the CloudFormation stack.
-  - The required tag format is `key=value`, e.g. `--tags key1=value1 key2=value2`
-- `[--verbose, -v]` Displays verbose logging.
+- `--direct path/to/function`: Directly deploy the specified Lambda. A faster way to deploy and test small changes to individual functions without redeploying an entire Stack.
+- `--dry-run`: Generate a [CloudFormation][cfn] template but do not deploy it. A dry run allows you to check the [CloudFormation][cfn] and SAM output before deploying the actual stack.
+- `--eject`: Generate a [CloudFormation][cfn] template but do not deploy it. Instead, print out the `aws cloudformation` CLI invocation to execute the deployment.
+- `--fast`, `-f`: Deploy the stack, but do not block the process until deployment completed.
+- `--name`, `-n`: Deploy a custom named staging Stack. E.g. `--name CI` will deploy a `AppnameStagingCI` [CloudFormation][cfn] Stack.
+- `--no-hydrate`: Do not automatically [`hydrate`](hydrate) functions prior to deployment.
+- `--production`, `-p`: Deploys a [CloudFormation][cfn] Stack to a production Stack. If not specified, will default to deploy to a staging Stack.
+- `--prune`: Remove static assets deployed to S3 bucket not present in the local [`@static`][static] folder.
+- `--static`, `-s`: Deploys only the files in the [`@static`][static] folder.
+- `--tags`, `-t`: Adds resource tags to the CloudFormation stack. The required tag format is `key=value`, e.g. `--tags key1=value1 key2=value2`
+- `--verbose`, `-v`: Displays verbose logging.
+- `--debug`, `-d`: Displays debug (and verbose) logging.
 
 ## Local preferences: `@create`
 
-When deploying, Architect can automatically scaffold resources (via [`arc init`](./init)) found in the [application's manifest](../../get-started/project-manifest) that do not yet exist. Options are set with [`@create` in local preferences](../configuration/local-preferences#%40create).
+When deploying, Architect can automatically scaffold resources (via [`init`](init)) found in the [application's manifest][manifest] that do not yet exist. Options are set with [`@create` in local preferences](../configuration/local-preferences#%40create).
 
 - `autocreate` - Set to `true` to enable automatic creation of boilerplate Lambda handlers and static assets if they do not exist.
 - `templates` - Specify templates for automatic resource scaffolding.
@@ -52,42 +52,48 @@ templates
 
 ## Examples
 
-### Deploy a staging stack
+### Deploy a staging Stack
 
 ```bash
 arc deploy
 ```
 
-### Deploy a production stack
+### Deploy a production Stack
 
 ```bash
 arc deploy --production
 ```
 
-### Deploy a named environment
+### Deploy a named staging Stack
 
 ```bash
 arc deploy --name my-stack
 ```
 
-> 💁  Named stacks use `staging` environment variables [set with `arc env -e staging --add`](./env).
+> 💁  Named stacks use `staging` environment variables [set with the `env` command](env).
 
 ### Deploy static assets to S3
 
 ```bash
 arc deploy --static
 ```
 
-### Deploy code directly to the staging Lambda
+### Deploy the index route directly to staging
 
 ```bash
 arc deploy --direct src/http/get-index
 ```
 
 ### Run deploy without deploying
 
-This is useful for testing `@macros`; it will still generate `sam.json`.
+This is useful for testing [`@plugins`][plugins]; it will still generate `sam.json`.
 
 ```bash
 arc deploy --dry-run
 ```
+
+[cfn]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html
+[manifest]: ../../get-started/project-manifest
+[static]: ../project-manifest/static
+[app]: ../project-manifest/app
+[plugins]: ../project-manifest/plugins

src/views/docs/en/reference/cli/destroy.md

@@ -2,52 +2,63 @@
 title: arc destroy
 category: CLI
 description: CLI destroy command for removing Architect application
+sections:
+  - Usage
+  - Flags
+  - Examples
 ---
 
-Remove the CloudFormation stack and all related assets (S3 buckets, CloudWatch Log Groups, SSM environment variable parameters) for the current project from AWS completely. By default, removes the staging stack.
+Completely removes your Architect application from AWS. This command deletes all resources associated with your application, including the [CloudFormation][cfn] Stack, SSM environment variables, CloudWatch Logs, deployment S3 bucket, and static S3 bucket (if applicable). 
 
-Large applications may take several minutes to delete and by default this command times out after 150 seconds. Even if this command times out, deletion may still complete successfully as removal completes asynchronously in the background at AWS. To have this process block until all application resources are removed, use the `--no-timeout` flag (see below for more information).
+By default, this command destroys your staging environment. Use the `--production` flag to target the production environment instead. For custom environments created with [`deploy --name`][deploy], use the `--name` flag to specify the environment to destroy.
+
+Large applications may take several minutes to delete and by default this command times out after 150 seconds. Even if this command times out, deletion may still complete successfully as removal completes asynchronously in the background. To have this process block until all application resources are removed, use the `--no-timeout` flag.
 
 ## Usage
 
 ```bash
-arc destroy <--app MyAppName> [--production] [--name NamedEnvironment] [--force]
+arc destroy [flags]
 ```
 
 ## Flags
 
-- `[--app MyAppName]` Required. Specify the app name, located under `@app` in your Architect manifest, to delete the app from AWS.
-- `[--name NamedEnvironment]` If you ran [`arc deploy`][deploy] with the `--name` flag to specify a custom named environment to deploy your application to, use this flag to destroy that same named application environment.
-- `[--production]` Destroy the production stack of your application. By default, without this flag, the staging stack is removed.
-- `[--force, -f]` Force deletion of the application even if it contains DynamoDB tables ([`@tables`][tables]) or S3 bucket containing static assets ([`@static`][static]).
-- `[--no-timeout]` Do not exit the process until all application resources are deleted.
+- `--app`: App name as specified by your application's [`@app` pragma][app] (required for confirmation).
+- `--force`, `-f`: Destroy an app that has database [`@tables`][tables] and/or [`@static`][static] assets.
+- `--name`: Target a custom named environment created with [`deploy --name`][deploy].
+- `--now`: Skip the 5-second safety delay before destroying resources.
+- `--no-timeout`: Wait indefinitely for all application resources to be removed (by default times out after ~150 seconds).
+- `--production`, `-p`: Destroy the production environment instead of staging.
+- `--verbose`, `-v`: Print more detailed information during the destroy process.
+- `--debug`, `-d`: Print even more detailed information for debugging purposes.
 
 ## Examples
 
-### Destroy the staging stack
+### Destroy the staging Stack
 
 ```bash
 arc destroy --app my-app
 ```
 
-### Destroy the production stack
+### Destroy the production Stack
 
 ```bash
 arc destroy --app my-app --production
 ```
 
-### Destroy staging stack with S3 bucket and/or Dynamo tables
+### Destroy staging Stack with S3 bucket and/or Dynamo tables
 
 ```bash
 arc destroy --app my-app --force
 ```
 
-### Destroy custom named stack
+### Destroy custom named Stack
 
 ```bash
-arc destroy --app my-app --name Dev --force
+arc destroy --app my-app --name Dev
 ```
 
 [deploy]: deploy
+[app]: ../project-manifest/app
 [tables]: ../project-manifest/tables
 [static]: ../project-manifest/static
+[cfn]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html

src/views/docs/en/reference/cli/env.md

@@ -2,32 +2,54 @@
 title: arc env
 category: CLI
 description: Read and write environment variables for Lambda functions.
+sections:
+  - Usage
+  - Flags
+  - Security
+  - Examples
+  - Reserved names
+  - Specific function opt-out
 ---
 
-Read and write environment variables. This allows apps to centrally store sensitive configuration data, such as API keys, outside of the codebase in revision control.
+Manage environment variables for your Architect application across different environments. This command allows you to read, add, and remove environment variables that will be available to your Lambda functions at runtime.
 
-> `arc env` will **not** upload variables from a project's [local preferences file](../configuration/local-preferences#%40env); however, it will download variables from AWS and overwrite local preference entries.
+When run without any flags, this command will print out all environment variables and their values, across all environments.
+
+Environment variables are stored in AWS SSM Parameter Store for staging and production environments. For local development (testing environment), variables are stored in your project's [`preferences.arc` file][prefs] or `.env` file if one exists.
+
+> `arc env` will **not** upload variables from a project's [local preferences file][env-prefs]; however, it will download variables from AWS and overwrite local preference entries.
+
+> 💁  `staging` environment variables are also used in named deployments [created with `arc deploy --name <name>`](./deploy).
 
 ## Usage
 
 ```bash
-arc env [-e environment] [--add|--remove] VARIABLE_NAME VARIABLE_VALUE
+arc env [flags] [VARIABLE_NAME] [VARIABLE_VALUE]
 ```
 
-
 ## Flags
 
-- `[-e [testing|staging|production]]` Displays all environment variables for the specified environment
-- `<--add, -a> -e <testing|staging|production> NAME value` Assigns a value to the specified variable name in the specified environment
-- `<--remove, -r> -e <testing|staging|production> NAME` Removes the specified variable from the specified environment
-
+- `-e`, `--env <environment>`: Specify environment (`testing`, `staging`, or `production`)
+- `-a`, `--add`: Add a new environment variable
+- `-r`, `--remove`: Remove an environment variable
+- `-v`, `--verbose`: Print more detailed output
+- `-d`, `--debug`: Print even more detailed information for debugging
 
 ## Security
 
-It is imperative that the `ARC_APP_SECRET` environment variable be set to
-a strong secret - especially in your production environment! It should have a minimum length of 16 bytes. This secret is
-used to encode HTTP sessions if you use the [`@architect/functions` runtime helpers](../runtime-helpers/node.js#arc.http.session).
+It is imperative that the `ARC_APP_SECRET` environment variable be set to a strong secret - especially in your production environment! **It must have a minimum length of 32 bytes**. This secret is used to encode HTTP sessions if you use the [`@architect/functions` runtime helpers](../runtime-helpers/node.js#arc.http.session).
+
+## Reserved names
+
+The following environment variable names are reserved for Architect use and cannot be set in an app:
 
+- `ARC_ENV`
+- `ARC_APP_NAME`
+- `ARC_SESSION_TABLE_NAME`
+
+## Specific function opt-out
+
+A function can be [configured with a `config.arc`](../configuration/function-config#%40arc) to not load local environment variables.
 
 ## Examples
 
@@ -37,32 +59,25 @@ used to encode HTTP sessions if you use the [`@architect/functions` runtime help
 arc env
 ```
 
+### Display variables for a specific environment
+
+```bash
+arc env --env staging
+```
 
 ### Save an environment variable to the staging environment
 
 Variable values that contain special characters like email addresses should be wrapped in double quotes
 
 ```bash
-arc env -e staging --add SECRET_API_PASSWORD "p@s5w0rd!"
+arc env --add --env staging SECRET_API_PASSWORD "p@s5w0rd!"
 ```
 
-> 💁  `staging` env variables are also used in named deployments [created with `arc deploy --name <name>`](./deploy).
-
-
 ### Remove an environment variable
 
 ```bash
-arc env -e staging --remove SECRET_API_PASSWORD
+arc env --remove --env staging SECRET_API_PASSWORD
 ```
 
-
-## Reserved names
-
-- `ARC_ENV`
-- `ARC_APP_NAME`
-- `ARC_SESSION_TABLE_NAME`
-
-
-## Specific function opt-out
-
-A function can be [configured with a `config.arc`](../configuration/function-config#%40arc) to not load local environment variables.
+[prefs]: ../configuration/local-preferences
+[env-prefs]: ../configuration/local-preferences#%40env

src/views/docs/en/reference/cli/hydrate.md

@@ -1,14 +1,14 @@
 ---
-title: hydrate
+title: arc hydrate
 category: CLI
 description: Install and update dependencies for all functions in a project.
 ---
 
-Ensure that all functions managed by Architect have their dependencies installed. Functions containing all its required dependencies are considered to be "hydrated" - thus the name!
+Ensure that all functions managed by Architect have their dependencies installed. Functions containing all their required dependencies are considered to be "hydrated" - thus the name!
 
-Importantly, `arc hydrate` will also copy shared code from `src/shared` into all functions and `src/views` into `@http` GET functions.
+Importantly, `arc hydrate` will also copy [shared code][sharing] from `src/shared` into all functions and `src/views` into [`@http`][http] GET functions.
 
-When developing locally with Sandbox, it is not necessary to manually run `hydrate` since Sandbox handles this automatically. However, it can be helpful to ensure hydration happens prior to a process like `npm test`.
+When [developing locally with Sandbox][local-dev], it is not necessary to manually run `hydrate` since Sandbox handles this automatically. However, it can be helpful to ensure hydration happens prior to a process like `npm test`.
 
 ## Usage
 
@@ -18,9 +18,9 @@ arc hydrate [--shared|--update]
 
 ## Flags
 
-- `[--shared, -s]` Hydrates and copies shared files only
-- `[--update, -u]` Updates each function's dependencies
-- `[--verbose, -v]` Prints additional output to the console
+- `--shared`, `-s`: Hydrates and copies [shared files][sharing] only
+- `--update` `-u`: Updates each function's dependencies to latest versions
+- `--verbose`, `-v`: Prints additional output to the console
 
 ## Notes
 
@@ -37,3 +37,7 @@ Hydrate uses the following commands under the hood, depending on project's or fu
 - **node.js**: `npm update`
 - **python**: `pip3 install -U --upgrade-strategy eager`
 - **ruby**: `bundle update`
+
+[local-dev]: ../../guides/developer-experience/local-development
+[sharing]: ../../guides/developer-experience/sharing-code
+[http]: ../project-manifest/http

src/views/docs/en/reference/cli/init.md

@@ -4,19 +4,23 @@ category: CLI
 description: Scaffold new resources found in the app.arc file
 ---
 
-Bootstrap new Architect project code. Running `arc init` in an empty directory creates a default `app.arc` manifest file named after that directory with one default function `src/http/get-index`. Edit `app.arc` adding functions and re-run `arc init` to generate further code. This command is intended to be run and re-run; it will only generate files if they do not already exist.
+Bootstrap new Architect project code. Running `arc init` in an empty directory creates a default [`app.arc` manifest file][manifest] named after that directory with one default [`@http` function][http] at `src/http/get-index`. Pass a directory name as a final positional argument to create a project in the specified directory. Edit `app.arc`, expanding the [manifest][manifest], adding functions and re-running `arc init` to generate further code. This command is idempotent: intended to be run and re-run; it will only generate files if they do not already exist.
+
+If you run this command with the `--plugin` flag, a scaffolded [Architect plugin][plugins] will be created instead.
 
 ## Usage
 
 ```bash
-arc init [--static|--runtime]
+arc init [flags] [path/to/project-directory]
 ```
 
 ## Flags
 
-- `[--static, -s]` Create a new project with `@static` folder set to `public`
-- `[--runtime, -r]` Create a new project with a specified runtime, options are node, deno, python, or ruby
-- `[--verbose, -v]` Even more output
+- `-n`, `--name`: Set the [`@app` namespace][app] for the created app
+- `--no-install`: Do not automatically install `@architect/architect` as a dependency in the project
+- `-p`, `--plugin`: Create a new scaffolded [Architect plugin][plugins] instead of a new Architect project
+- `--runtime`, `-r`: Create a new project with the specified runtime. Defaults to `node`. See the [`runtime` configuration documentation][runtimes] for available options.
+- `--verbose`, `-v`: Even more output
 
 ## Local preferences: `@create`
 
@@ -67,3 +71,9 @@ npm init "@architect" myapp
 </arc-tab>
 </div>
 </arc-viewer>
+
+[app]: ../project-manifest/app
+[http]: ../project-manifest/http
+[manifest]: ../../get-started/project-manifest
+[plugins]: ../../guides/plugins/overview
+[runtimes]: ../project-manifest/aws#runtime