Apply suggestions from code review

Co-authored-by: Phil Miller <[email protected]>

Author: theoephraim

packages/varlock-website/src/content/docs/guides/environments.mdx

@@ -8,9 +8,8 @@ One of the main benefits of using environment variables is the ability to boot y
 You may use both [functions](/reference/functions/) and/or environment-specific `.env` files (e.g., `.env.production`) to alter configuration accordingly in a declarative way. Plus the additional guardrails provided by `varlock` also make this much safer no matter where values come from.
 
 :::tip[environment-specific files are optional]
-While many have traditionally shied away from using environment-specific `.env` files due to fear of committing sensitive values, the new ability to set values using [plugins](/guides/plugins/) now makes it much easier to collaboratively manage these values in a secure way.
+While many have traditionally shied away from using environment-specific `.env` files due to fear of committing sensitive values, the ability to set values using [plugins](/guides/plugins/) makes it easier to securely, and collaboratively, manage these values.
 
-Whether you want to use environment-specific files, exclusively use functions, or use a mix is totally up to you. Varlock tries to provide a toolkit to let you manage your config however you best see fit.
 :::
 
 
@@ -19,16 +18,16 @@ Whether you want to use environment-specific files, exclusively use functions, o
 
 Sometimes you also may want to pass in env vars via the command line while running a command (e.g. `APP_ENV=prod pnpm run build`).
 
-However we recommend using injected overrides sparingly, and instead moving more config into your `.env` files.
+However, we recommend using injected overrides sparingly, and instead moving more config into your `.env` files.
 
 
 ### Loading environment-specific `.env` files
 
-`varlock` automatically detects all `.env.*` files in the current directory. However any environment-specific files (e.g., `.env.development`) will only be loaded if they match the value of the _current environment_ as set by the [`@currentEnv`](/reference/root-decorators/#currentEnv) root decorator in your `.env.schema` file.
+`varlock` automatically detects all `.env.*` files in the current directory. However, any environment-specific files (e.g., `.env.development`) will only be loaded if they match the value of the _current environment_ as set by the [`@currentEnv`](/reference/root-decorators/#currentEnv) root decorator in your `.env.schema` file.
 
 The files are applied with a specific precedence (increasing):
 - `.env.schema` - your schema file, which can also contain default values
-- `.env` - will be loaded, but not recommended
+- `.env` - will be loaded, but not recommended, instead use something more specific
 - `.env.[currentEnv]` - environment-specific values
 - `.env.local` - local overrides (gitignored)
 - `.env.[currentEnv].local` - environment-specific local overrides (gitignored)

packages/varlock-website/src/content/docs/guides/plugins.mdx

@@ -42,7 +42,7 @@ You may omit the version specifier only if your project has a `package.json` fil
 ```
 
 :::caution[Only `@varlock/*` plugins supported for now]
-For now, only official Varlock plugins under the `@varlock` npm scope are supported. We plan to support third-party plugins in the future, along with additional plugin source types (e.g., jsr, git, http, etc.) - but need additional security measures in place first.
+For now, only official Varlock plugins under the `@varlock` npm scope are supported. We plan to support third-party plugins in the future, along with additional plugin source types (e.g., jsr, git, http, etc.).
 :::
 
 {/*
@@ -59,10 +59,10 @@ Plugins are loaded globally, and the additional functionality they provide will
 
 Note that plugins will not be loaded from an inactive file - for example an environment-specific file that does not match the current environment, or one that uses the [`@disable` root decorator](/reference/root-decorators/#disable).
 
-No specific namespacing or prefixes are enforced, and any naming conflicts will trigger an error, but plugins will use fairly specific names to avoid conflicts.
+No specific namespacing or prefixes are enforced, and any naming conflicts will trigger an error, but plugins will use specific names to avoid conflicts.
 
 ## Initialization
-Plugins are initialized using custom root decorators that they introduce. In some cases no specific initialization is needed, and in others, you may need to intialize multiple instances of a plugin with different options, referred to by some identifier. How (or if) a plugin needs to be initialized depends on the specific plugin and can depend on the the external service's data/auth model.
+Plugins are initialized using custom root decorators that they introduce. In some cases, no specific initialization is needed, and in others, you may need to initialize multiple instances of a plugin with different options, referred to by some identifier. How (or if) a plugin needs to be initialized depends on the specific plugin and can depend on the the external service's data/auth model.
 
 A plugin initialization root decorator is used to set IDs, toggle features, and wire up auth. Note that sensitive data should be passed in via references to config items within your schema.
 
@@ -77,7 +77,7 @@ OP_TOKEN=
 ### Multiple plugin instances
 In secret storage tools, you should segment your data to follow the [_principle of least privilege_](https://en.wikipedia.org/wiki/Principle_of_least_privilege), so that different environments/services/devs only have access to the minimal secrets they need. At the very least, this usually means splitting your extra sensitive prod secrets from everything else, but it can be as fine-grained as needed.
 
-We cannot always assume that you won't need access to multiple segments at the same time. In these cases, a plugin may be designed to be initialized multiple times with some kind of id parameter. Resolver functions and decorators can then accept an additional parameter to specify which instance to use. It is up to the plugin author to structure this in a way that makes sense.
+We cannot always assume that you won't need access to multiple segments at the same time. In these cases, a plugin may be designed to be initialized multiple times with some kind of id parameter. Resolver functions and decorators can then accept an additional parameter to specify which instance to use.
 
 
 ```env-spec title=".env.schema" "@initOpVault" /id=[a-z]+/ /\\((dev),/

packages/varlock-website/src/content/docs/guides/schema.mdx

@@ -84,7 +84,7 @@ More details:
 
 You may use [resolver functions](/reference/functions/) instead of static values within both config items and decorator values.
 
-Functions may be composed together to create complex value resolution logic.
+Functions may be composed together to create more complex value resolution logic.
 
 ```env-spec
 # @required=forEnv(prod)
@@ -110,7 +110,6 @@ MY_KEY=exec(`op read "op://${OP_VAULT_NAME}/service/api-key"`)
 ```
 
 More details:
-- [Functions reference](/reference/functions/)
 
 
 

packages/varlock-website/src/content/docs/plugins/1password.mdx

@@ -7,7 +7,7 @@ import { Steps, Icon } from '@astrojs/starlight/components';
 
 Our [1Password](https://1password.com/) plugin enables secure loading of values from 1Password vaults using declarative instructions within your `.env` files.
 
-For local development, it (optionally) supports authenticating using the local 1Password desktop app, including using biometric unlock. Otherwise it uses a [service account](https://developer.1password.com/docs/service-accounts/) making it suitable for CI/CD and production environments.
+For local development, it (optionally) supports authenticating using the local 1Password desktop app, including using biometric unlock. Otherwise, it uses a [service account](https://developer.1password.com/docs/service-accounts/) making it suitable for CI/CD and production environments.
 
 This plugin is compatible with any 1Password account type (personal, family, teams, business), but note that [rate limits](https://developer.1password.com/docs/service-accounts/rate-limits/) vary by account type.
 
@@ -49,7 +49,7 @@ If you already use 1Password and your secrets live in a vault that holds other s
 
 </Steps>
 
-This service account token will now serve as your _secret-zero_ - which grants access to the rest of your sensitive data stored in 1Password. It must be set locally (unless relying on app-based auth) and in any deployed environments, usually as an environment variable with your platform's UI.
+This service account token will now serve as your _secret-zero_ - which grants access to the rest of your sensitive data stored in 1Password. It must be set locally (unless relying on app-based auth) and in any deployed environments, usually as an environment variable with your platform's env var management UI.
 
 :::tip[Vault organization best practices]
 Consider how you want to organize your vaults and service accounts, keeping in mind [best practices](https://support.1password.com/business-security-practices/#access-management-and-the-principle-of-least-privilege). At a minimum, we recommend having a vault for highly sensitive production secrets and another for everything else.

packages/varlock-website/src/content/docs/plugins/overview.mdx

@@ -5,7 +5,7 @@ description: Varlock plugins overview
 
 Plugins allow extending the functionality of Varlock. See the [plugins guide](/guides/plugins/) for more details on using plugins.
 
-For now, only official Varlock plugins under the `@varlock` npm scope are supported. We plan to support third-party plugins in the future, along with loading plugins from different sources (e.g., local files, git, npm/jsr, http, etc.) - but need additional security measures in place first.
+For now, only official Varlock plugins under the `@varlock` npm scope are supported. We plan to support third-party plugins in the future, along with loading plugins from different sources (e.g., local files, git, npm/jsr, http, etc.).
 
 ## Official plugins
 - [1Password](/plugins/1password/)

packages/varlock-website/src/content/docs/reference/functions.mdx

@@ -5,7 +5,7 @@ description: A comprehensive reference of all available function resolvers in va
 
 You may use _resolver functions_ instead of static values within both config items and decorator values.
 
-Functions can be composed together to create complex value resolution logic.
+Functions can be composed together to create more complex value resolution logic.
 ```env-spec
 ITEM=fn(arg1, arg2)
 COMPOSITION=fn1(fn1Arg1, fn2(fn2Arg1, fn2Arg2))
@@ -24,14 +24,14 @@ CONFIG=exec(`aws ssm get-parameter --name "/config/${APP_ENV}" --with-decryption
 
 Currently, there are built-in utility functions, and soon there will be functions to handle values encrypted using varlock provided tools.
 
-Plugins may also register additional resolvers - which can be used to generate and  transform values, or even fetch data from external providers.
+Plugins may also register additional resolvers - which can be used to generate and transform values, or fetch data from external providers.
 
 
 <div class="reference-docs">
 <div>
 ### `ref()`
 
-References another config item (env var) - which is very useful when composing multiple functions together.
+References another config item (env var) - which is useful when composing multiple functions together.
 
 Expansion equivalent: `ref(OTHER_VARL)` === `${OTHER_VAR}` (and also `$OTHER_VAR`)
 
@@ -152,7 +152,7 @@ DEBUG_FLAG=
 <div>
 ### `eq()`
 
-Checks if 2 values are equal and resvolves to a boolean.
+Checks if 2 values are equal and resolves to a boolean.
 
 ```env-spec "regex"
 IS_STAGING_DEPLOYMENT=eq($GIT_BRANCH, "staging")

packages/varlock-website/src/content/docs/reference/item-decorators.mdx

@@ -103,10 +103,11 @@ SECRET_KEY=
 
 <div>
 ### `@docs()`
-URL of documentation related to the item.
+URL of documentation related to the item. Can be called multiple times. 
 
 ```env-spec
-# @docsUrl=https://platform.openai.com/docs/api-reference/authentication
+# @docs(https://platform.openai.com/docs/api-reference/authentication)
+# @docs(https://platform.openai.com/docs/api-reference/security)
 OPENAI_API_KEY=
 ```
 </div>

packages/varlock-website/src/content/docs/reference/root-decorators.mdx

@@ -27,7 +27,7 @@ More details of the minutiae of decorator handling can be found in the [@env-spe
 ### `@currentEnv`
 
 Sets the current _environment_ value, which will be used when determining if environment-specific .env files will be loaded (e.g. `.env.production`),
-and also may affect other dynamic behaviour in your schema, such as the [`forEnv()` function](/reference/functions/#forenv). We often refer to the name of this item as your _environment flag_.
+and also may affect other dynamic behaviour in your schema, such as the [`forEnv()` function](/reference/functions/#forenv). We refer to the name of this item as your _environment flag_.
 
 This will usually be something like `@currentEnv=$APP_ENV`.