update docs

Author: theoephraim

packages/varlock-website/src/content/docs/getting-started/introduction.mdx

@@ -12,7 +12,7 @@ Varlock aims to be the most comprehensive environment variable management tool.
 - **[AI-Safe Config](/guides/ai-tools/)** - Your `.env.schema` gives AI agents full context on your config without ever exposing secret values. Prevent leaks to AI servers by design, and scan for leaked secrets with `varlock scan`
 - **[Security](/guides/secrets/)** - Automatic log redaction for sensitive values, leak detection in bundled code and server responses, and proactive scanning via `varlock scan`
 - **[Validation & Type Safety](/reference/data-types/)** - Powerful validation capabilities with clear error messages, plus automatic type generation for IntelliSense support
-- **[Secure Secrets](/guides/secrets/)** - Load secrets from provider [plugins](/plugins/overview/) (e.g., [1Password](/plugins/1password/), [AWS](/plugins/aws-secrets/), [HashiCorp Vault](/plugins/hashicorp-vault/)) or any CLI tool using [exec()](/reference/functions/#exec)
+- **[Secure Secrets](/guides/secrets/)** - Built-in [device-local encryption](/guides/secrets/#local-encryption) with hardware-backed security (Secure Enclave, TPM), plus provider [plugins](/plugins/overview/) (e.g., [1Password](/plugins/1password/), [AWS](/plugins/aws-secrets/), [HashiCorp Vault](/plugins/hashicorp-vault/)) or any CLI tool using [exec()](/reference/functions/#exec)
 - **[Multi-Environment Management](/guides/environments/)** - Flexible environment handling with support for environment-specific files, local overrides, and value composition
 - **[Value Composition](/reference/functions/)** - Compose values together using functions, references, and external data sources
 - **[Framework Integrations](/integrations/overview/)** - Official integrations for Next.js, Vite, Astro, and more, plus support for any language via `varlock run`

packages/varlock-website/src/content/docs/getting-started/usage.mdx

@@ -41,4 +41,22 @@ See the [`varlock load` CLI Reference](/reference/cli-commands/#load) for more i
 Executes a command in a child process, injecting your resolved and validated environment variables. This is useful when a code-level integration is not possible. For example, if you're using a database migration tool, you can use `varlock run` to run the migration tool with the correct environment variables. Or if you're using a non-js/ts language, you can use `varlock run` to run a command and inject validated environment variables.
 
 
-See the [`varlock run` CLI Reference](/reference/cli-commands/#run) for more information.
+See the [`varlock run` CLI Reference](/reference/cli-commands/#run) for more information.
+
+### `varlock encrypt`
+
+<ExecCommandWidget command="varlock encrypt --file .env.local" />
+
+Encrypts sensitive values using device-local encryption. Use `--file` to encrypt all `@sensitive` plaintext values in a `.env` file in-place, or run without arguments for interactive single-value encryption.
+
+Encrypted values are stored as `varlock("local:<encrypted>")` and are automatically decrypted during `varlock load` or `varlock run`.
+
+See the [`varlock encrypt` CLI Reference](/reference/cli-commands/#encrypt) and the [secrets guide](/guides/secrets/#local-encryption) for more information.
+
+### `varlock reveal`
+
+<ExecCommandWidget command="varlock reveal" />
+
+Securely view or copy decrypted values of `@sensitive` environment variables. Values are shown in an alternate screen buffer to prevent scrollback capture.
+
+See the [`varlock reveal` CLI Reference](/reference/cli-commands/#reveal) for more information.

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

@@ -5,20 +5,97 @@ description: Best practices for managing secrets and sensitive environment varia
 
 `varlock` uses the term _sensitive_ to describe any value that should not be exposed to the outside world. This includes secret api keys, passwords, and other generally sensitive information. Instead of relying on prefixes (e.g., `NEXT_PUBLIC_`) to know which items may be "public", varlock relies on `@decorators` to mark sensitive items explicitly.
 
-{/* For local development, `varlock` allows you to encrypt sensitive values in your `.env.*` files using `varlock encrypt` and then decrypt them using `varlock load` or `varlock run`.
+## Local encryption via `varlock()` {#local-encryption}
 
-This (currently) works exclusively for local development since it relies on encryption keys stored on your system. */}
+Varlock includes built-in device-local encryption that lets you store encrypted secrets directly in your `.env` files. Encrypted values are safe to commit to version control — they can only be decrypted on machines that have the corresponding encryption key.
 
-:::tip[Coming soon]
-We'll be adding support for our own trustless, cloud-based secret storage in the very near future. 
-:::
+This is ideal for:
+- **Solo developers** who want encrypted secrets in their repo without relying on an external service
+- **Small teams** where each developer encrypts their own local secrets
+- **Avoiding plaintext** `.env.local` files on disk
+
+### How it works
+
+Secrets are encrypted using [ECIES](https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme) (Elliptic Curve Integrated Encryption Scheme) with a device-local key. The best available encryption backend is selected automatically:
+
+| Platform | Backend | Key Storage | Biometric |
+|----------|---------|-------------|-----------|
+| macOS | Secure Enclave | Hardware Secure Enclave | Touch ID / Face ID |
+| Windows | DPAPI | Windows credential store | Planned (Windows Hello) |
+| Linux | Kernel keyring | Kernel keyring | Planned (TPM2) |
+| All platforms | File-based fallback | `~/.varlock/` directory | No |
+
+On macOS, the Secure Enclave provides hardware-backed encryption — keys cannot be extracted from the device, and decryption can require biometric authentication via Touch ID.
 
-{/* ## Encryption via `varlock`
+### Quick start
+
+1. Add your secrets as plaintext in `.env.local` (which should be gitignored)
+2. Run `varlock encrypt --file .env.local` to encrypt them in-place
+3. The values are replaced with `varlock("local:<encrypted>")` calls
+4. These encrypted values are automatically decrypted when you run `varlock load` or `varlock run`
+
+```env-spec title=".env.local"
+# Before encryption
+# @sensitive
+API_KEY=sk-secret-key-12345
+
+# After running `varlock encrypt --file .env.local`
+# @sensitive
+API_KEY=varlock("local:BGJ2a3...")
+```
 
-1. [Install](/getting-started/installation) `varlock` including the desktop app
-2. Add sensitive values to your `.env.*` file(s)
-3. Encrypt them using `varlock encrypt`
-4. Decrypt them using `varlock load` or `varlock run` */}
+### Using prompt mode
+
+Instead of encrypting existing values, you can use `varlock(prompt)` as a placeholder that will prompt you to enter a secret on first load:
+
+```env-spec title=".env.local"
+# @sensitive
+API_KEY=varlock(prompt)
+```
+
+When varlock encounters this during `varlock load` or `varlock run`, it will:
+1. Prompt you to enter the secret value (via a native dialog on macOS, or a terminal prompt otherwise)
+2. Encrypt the value
+3. Automatically replace `varlock(prompt)` with `varlock("local:<encrypted>")` in the file
+
+### Encrypting values
+
+Use [`varlock encrypt`](/reference/cli-commands/#encrypt) to encrypt values:
+
+```bash
+# Interactive: encrypt a single value
+varlock encrypt
+
+# Batch: encrypt all sensitive plaintext values in a file
+varlock encrypt --file .env.local
+```
+
+In batch mode, only items marked as `@sensitive` in your schema are considered for encryption.
+
+### Revealing encrypted values
+
+Use [`varlock reveal`](/reference/cli-commands/#reveal) to securely view decrypted values:
+
+```bash
+# Interactive picker
+varlock reveal
+
+# Reveal a specific variable
+varlock reveal API_KEY
+
+# Copy to clipboard (auto-clears after 10s)
+varlock reveal API_KEY --copy
+```
+
+Values are shown in an alternate terminal screen buffer so they don't appear in your scrollback history.
+
+### Locking the session
+
+On platforms with biometric authentication (macOS Secure Enclave), decryption sessions are cached to avoid repeated Touch ID prompts. Use [`varlock lock`](/reference/cli-commands/#lock) to invalidate the session when stepping away:
+
+```bash
+varlock lock
+```
 
 ## Marking `@sensitive` items
 Whether each item is sensitive or not is controlled by the [`@defaultSensitive`](/reference/root-decorators/#defaultsensitive) root decorator and the [`@sensitive`](/reference/item-decorators/#sensitive) item decorator. Whether you want to default to sensitive or not, or infer based on key names is up to you. For example:

packages/varlock-website/src/content/docs/reference/cli-commands.mdx

@@ -238,6 +238,96 @@ You can also set it up manually -- see the [Secrets guide](/guides/secrets/#scan
 
 </div>
 
+<div>
+### `varlock encrypt` ||encrypt||
+
+Encrypts sensitive values using device-local encryption. Encrypted values are stored in `.env` files using the `varlock()` resolver function and are automatically decrypted at load time.
+
+On macOS, encryption is hardware-backed via the Secure Enclave (with Touch ID / biometric authentication). On Windows and Linux, platform-specific secure storage is used. A pure-JavaScript file-based fallback is available on all platforms.
+
+```bash
+varlock encrypt [options]
+```
+
+**Options:**
+- `--key-id`:  Encryption key ID (default: `varlock-default`)
+- `--file`:    Path to a `.env` file — encrypts all sensitive plaintext values in-place
+
+**Examples:**
+```bash
+# Interactive mode: encrypt a single value
+varlock encrypt
+
+# Encrypt all sensitive plaintext values in a .env file
+varlock encrypt --file .env.local
+```
+
+In interactive mode, you'll be prompted to enter a value, and the encrypted output will be printed for you to copy into your `.env.local` file:
+```
+SOME_SENSITIVE_KEY=varlock("local:<encrypted>")
+```
+
+In file mode, varlock loads the env graph, identifies `@sensitive` items with plaintext values, and lets you select which to encrypt in-place.
+
+:::tip
+Use `varlock encrypt --file .env.local` after adding new secrets to quickly encrypt them all at once.
+:::
+
+:::note[Alternative: prompt mode]
+Instead of encrypting values ahead of time, you can use `varlock(prompt)` as a placeholder in your `.env` files. On first load, varlock will prompt you to enter the secret and automatically replace the placeholder with the encrypted value. See the [`varlock()` function reference](/reference/functions/#varlock) for details.
+:::
+
+</div>
+
+<div>
+### `varlock reveal` ||reveal||
+
+Securely view or copy the decrypted values of `@sensitive` environment variables. Values are displayed in an alternate terminal screen buffer so they don't persist in your scrollback history.
+
+```bash
+varlock reveal [VAR_NAME] [options]
+```
+
+**Options:**
+- `--copy`:        Copy the value to clipboard instead of displaying (auto-clears after 10s)
+- `--path` / `-p`: Path to a specific `.env` file or directory to use as the entry point
+- `--env`:         Set the environment (e.g., production, development, etc)
+
+**Examples:**
+```bash
+# Interactive picker to browse and reveal sensitive values
+varlock reveal
+
+# Reveal a specific variable
+varlock reveal MY_SECRET
+
+# Copy a value to clipboard (auto-clears after 10s)
+varlock reveal MY_SECRET --copy
+```
+
+:::note
+Non-sensitive values are not shown by `varlock reveal`. Use [`varlock printenv`](#printenv) for non-sensitive values.
+:::
+
+</div>
+
+<div>
+### `varlock lock` ||lock||
+
+Locks the encryption daemon, requiring biometric authentication (e.g., Touch ID) for the next decrypt operation. This invalidates the current biometric session cache.
+
+```bash
+varlock lock
+```
+
+This command only has an effect when using a biometric-enabled encryption backend (macOS Secure Enclave or Windows Hello). On other backends, it will display a message and exit.
+
+:::tip
+Use `varlock lock` when stepping away from your machine to ensure the next person to decrypt a secret must authenticate biometrically.
+:::
+
+</div>
+
 <div>
 ### `varlock typegen` ||typegen||
 

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

@@ -22,12 +22,38 @@ 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.
+There are built-in utility functions, a built-in `varlock()` function for device-local encryption, and plugin-provided resolver functions that can 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>
+### `varlock()`
 
+Decrypts a locally encrypted value, or prompts for a new secret to encrypt. This is the built-in resolver for varlock's [device-local encryption](/guides/secrets/#local-encryption) feature.
+
+**Decrypt mode** — pass an encrypted payload to decrypt at load time:
+```env-spec "varlock"
+# @sensitive
+API_KEY=varlock("local:<encrypted-payload>")
+```
+
+**Prompt mode** — prompts the user to enter a secret, encrypts it, and writes the encrypted value back to the source file:
+```env-spec "varlock"
+# @sensitive
+API_KEY=varlock(prompt)
+# also valid as a key=value param:
+API_KEY=varlock(prompt=1)
+```
+
+On first run with `prompt` mode, you'll be asked to enter the secret value. Once entered, the file is automatically updated with the encrypted payload. On macOS with Secure Enclave, a native dialog with biometric authentication is used.
+
+Values are encrypted using the best available backend on your platform — see the [secrets guide](/guides/secrets/#local-encryption) for details.
+
+:::tip
+You don't need to write `varlock()` calls by hand. Use [`varlock encrypt`](/reference/cli-commands/#encrypt) to encrypt values interactively or in bulk.
+:::
+</div>
 
-<div class="reference-docs">
 <div>
 ### `ref()`