@super-repo/envx 0.2.3-b.2 → 0.2.3-b.4

package/README.md

@@ -1,24 +1,86 @@
-# @honeycluster/envx
+# @super-repo/envx
 
-A small wrapper around [`@dotenvx/dotenvx`](https://www.npmjs.com/package/@dotenvx/dotenvx)
-for monorepos. Auto-detects the active environment from common
-platform signals, loads the matching `.env*` files from the workspace
-root and the current package, and runs your command (or your code)
-with that environment applied.
+Workspace-aware env-file loader, runner, and encryption tool — built for monorepos.
 
 ```sh
-pnpm add @honeycluster/envx
+pnpm add @super-repo/envx
 ```
 
+## Tribute
+
+This package stands on the shoulders of [`@dotenvx/dotenvx`](https://www.npmjs.com/package/@dotenvx/dotenvx). The encryption format, the `.env.keys` convention, the public-key header layout, and the broad CLI shape are all directly inspired by — and **wire-format compatible with** — dotenvx. We re-use [`eciesjs`](https://www.npmjs.com/package/eciesjs) (the same library dotenvx uses) for asymmetric encryption, so a `.env*` file encrypted by either tool can be decrypted by the other given the matching private key.
+
+If you're building a single application, **just use [`@dotenvx/dotenvx`](https://dotenvx.com)**. It's excellent, well-maintained, and battle-tested. This package exists for one specific case: when "load the environment for one app" doesn't capture what you actually need.
+
+## The problem
+
+Monorepos break a lot of dotenv-style assumptions:
+
+- **Env files live at multiple levels.** Workspace-wide secrets sit at the repo root; per-package overrides sit inside each package; CI injects yet another layer. dotenv's "look in cwd" model produces different results depending on which package directory you happen to be in when you ran the command.
+- **`.env.keys` lives in *one* place, but encrypted `.env*` files live in many.** Without a workspace-aware lookup, every package needs its own copy of the keys file, or a fragile `--env-keys-file ../../../.env.keys` per command.
+- **Cascade resolution wants the workspace root, not cwd.** `--cascade prod` should layer `.env`, `.env.prod`, `.env.local`, and `.env.prod.local` from the *workspace root*, regardless of which subpackage triggered the load. Without this, a Vite build run from `packages/web/` and a Node script run from `apps/api/` see different environments for the same prod target.
+- **Encryption keys want to rotate atomically across the whole stack.** Rotating one package's key while leaving the others stale is a leak waiting to happen. You want one `rotate` command that walks the workspace.
+- **Per-package configuration is a real thing.** Some packages legitimately want a different env-file set than the rest of the monorepo (e.g. a Docker image-builder package that pulls from `vault/` while the rest pull from `.env`).
+
+dotenvx handles single-app cases beautifully. envx handles the workspace shape on top of dotenvx's foundation.
+
+## The solution
+
+envx adds three things on top of the dotenvx model:
+
+1. **Cwd-first paths with workspace-root fallback.** Both `--dir`/`--env-path` and `--env-keys-file`/`-fk` resolve **relative to where the command is invoked**. If the requested directory or keys file isn't there, envx walks *up* to the nearest workspace root (any ancestor with `pnpm-workspace.yaml`, `package.json#workspaces`, `nx.json`, etc.) and looks again. So `envx encrypt --dir vault` works whether `vault/` lives in your current package or at the workspace root — same command, same intent, no per-package `../../../.env.keys` ceremony.
+
+2. **One `.env.keys` for the workspace by default.** With no `-fk` flag, envx looks for `.env.keys` at cwd; if it's not there, it walks up. So a single keys file at the workspace root serves every encrypted `.env*` across the monorepo. Override per-call with `-fk <path>` whenever you need a different file.
+
+3. **`rotate` walks every encrypted file you point it at.** One command refreshes the asymmetric keypair for every file the resolver picks up — every file in `--dir vault`, every file in a `-e` list, every cascade target. The new keypair lands in both the env file's `ENVX_PUBLIC_KEY*` header and the matching `.env.keys` entry atomically.
+
+The CLI shape, the `encrypted:<base64>` ciphertext format, the `ENVX_PUBLIC_KEY*` headers, and the `.env.keys` file layout are all directly compatible with `dotenvx`. envx also reads keys stored under the upstream `DOTENV_PUBLIC_KEY*` / `DOTENV_PRIVATE_KEY*` names so a `.env.keys` produced by either tool decrypts under the other.
+
+## envx vs. dotenvx
+
+| capability                                | `dotenvx`                                                  | `envx`                                                                                |
+| ----------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| **Target shape**                          | Single application                                         | pnpm / yarn / npm workspaces, Nx, Turborepo, Bazel, etc.                              |
+| **Env-file path resolution**              | Relative to `cwd`                                          | Cwd-first; walks up to workspace root (`pnpm-workspace.yaml`, `package.json#workspaces`, `nx.json`, …) on miss |
+| **`.env.keys` default location**          | Alongside the env file                                     | Cwd first, then walk-up to workspace root — one keys file serves the whole monorepo |
+| **`--env-keys-file` relative resolution** | Relative to `cwd`                                          | Relative to `cwd`, with walk-up to the workspace root if the file isn't at cwd       |
+| **`--dir` flag**                          | Not present (use `-f <path>` per file)                     | First-class `--dir` / `-d` / `--env-path`, cwd-first with workspace fallback         |
+| **Per-package config**                    | Single project root                                        | `package.json#envx.config: "<path>"` per package + workspace-level inheritance       |
+| **Cascade discovery**                     | From cwd                                                   | From workspace root, then layered with package-local overrides                       |
+| **Encryption**                            | ECIES via `eciesjs` (secp256k1 + AES-256-GCM)              | **Identical** ECIES via `eciesjs` — wire-format compatible                           |
+| **Public-key header**                     | `DOTENV_PUBLIC_KEY*`                                       | `ENVX_PUBLIC_KEY*` (canonical), `DOTENV_PUBLIC_KEY*` accepted as a read fallback     |
+| **Private-key var name**                  | `DOTENV_PRIVATE_KEY*`                                      | `ENVX_PRIVATE_KEY*` (canonical), `DOTENV_PRIVATE_KEY*` accepted as a read fallback   |
+| **`rotate` command**                      | Per-file rotation                                          | Walks every encrypted file the resolver picks up                                     |
+| **Programmatic API**                      | `dotenvx.config()` / library functions                     | `envx()` (single call), `import "@super-repo/envx/auto"` side-effect entry           |
+| **Auto-environment detection**            | Limited                                                    | Reads `VERCEL_ENV`, Netlify `CONTEXT`, `NODE_ENV` to pick `.env.<env>` when `--env` is omitted |
+| **Distribution**                          | npm package                                                | npm package + workspace-private helpers (`envx-libs`, `envx-common`) bundled via Vite |
+| **Health check**                          | Not built in                                               | `envx doctor` — workspace, config, keys file, decryptability, required, expand cycles |
+| **`.env.example` sync**                   | Not built in                                               | `envx template` (and `--check` for CI drift detection)                                |
+| **Diff between env files**                | Not built in                                               | `envx diff` — keys-only-in-a/b + value mismatches (decrypts via `.env.keys`)         |
+| **Shell injection**                       | Not built in                                               | `envx hook bash|zsh|fish|powershell` — eval-able exports for the parent shell        |
+| **Typed `process.env`**                   | Not built in                                               | `envx types` — emits `env.d.ts` from loaded keys (Zod-shape-aware)                   |
+| **Watch mode**                            | Not built in                                               | `envx watch -- node app.js` — restart on `.env*` change                              |
+| **Repo-wide secret audit**                | Not built in                                               | `envx audit` — AKIA, ghp_, sk_live_, JWT, OpenAI/Anthropic keys, PEM blocks, …       |
+| **Selective encryption**                  | Per-key flag (`-k`)                                        | Per-key, glob patterns (`--pattern`), and `--secrets` preset                         |
+| **Schema validation (Zod)**               | Not built in                                               | `schema:` field in config — duck-typed `safeParse()` with fail-fast exit             |
+| **Named profiles**                        | Not built in                                               | `profiles: { staging: { ... } }` + `--profile staging` (per-field override)          |
+| **External secret refs**                  | Not built in                                               | `${aws-secrets:my-id}` resolved by user-registered `resolvers:` callbacks            |
+| **Secret-provider plugins**               | Not built in                                               | `@super-repo/envx-plugins` ships AWS, GCP, Azure, Vault, 1Password, Doppler, Infisical |
+| **Public-variable mirroring**             | Not built in                                               | `PUBLIC_*` vars auto-mirror under `VITE_`, `NEXT_PUBLIC_`, `REACT_APP_`, etc.        |
+| **Build-time secret bake**                | Not built in                                               | `envx bake` resolves all refs into `.env.resolved` for bundlers (Vite/Next/esbuild) |
+| **Runtime / edge secrets**                | Not built in                                               | `createSecretRuntime()` — async, TTL-cached, V8-isolate-safe (CF Workers, Vercel Edge) |
+| **License**                               | BSD-3-Clause                                               | MIT                                                                                   |
+
+In short: same crypto, same file formats, same CLI vocabulary — different path-resolution layer underneath.
+
 ## Programmatic API
 
-### `import envx from "@honeycluster/envx"`
+### `import envx from "@super-repo/envx"`
 
 ```ts
-import envx from "@honeycluster/envx";
+import envx from "@super-repo/envx";
 
 // Three call shapes — all mutate process.env and return it for ergonomics.
-
 const env = envx();              // load .env (auto-detect from NODE_ENV / VERCEL_ENV / NETLIFY)
 const env = envx("prod");        // cascade-load .env, .env.prod, .env.local, .env.prod.local
 const env = envx({               // full options
@@ -30,56 +92,90 @@ const env = envx({               // full options
 });
 ```
 
-The string form (`envx("prod")`) is shorthand for "scope this load to
-the named environment" — it sets `cascade` so `.env.prod` and any local
-overrides layer cleanly over `.env`.
+The string form (`envx("prod")`) is shorthand for "scope this load to the named environment" — it sets `cascade` so `.env.prod` and any local overrides layer cleanly over `.env`.
+
+`envx()` discovers `envx.config.{ts,js,json}` and `package.json#envx.config` automatically; explicit args override matching fields from the config.
 
-`envx()` discovers `envx.config.{ts,js,json}` and `package.json`'s
-`envx.config` automatically; the explicit args you pass override
-matching fields from the config. See [`docs/CONFIG.md`](../../docs/CONFIG.md).
+#### Programmatic options — full surface
 
-### `import "@honeycluster/envx/auto"` — side-effect
+`envx()` accepts everything from `LoadEnvOptions` plus an optional `profile` string. The full shape (`EnvxProgrammaticOptions`):
 
 ```ts
-// In your app's entry file:
-import "@honeycluster/envx/auto";
+import envx, { type EnvxProgrammaticOptions } from "@super-repo/envx";
 
-// envx() has already run by the time this line executes.
-const env = process.env;
-```
+const opts: EnvxProgrammaticOptions = {
+  // env-file selection
+  envFiles: ["vault/.env.prod"],
+  envPath: "vault",
+  cascade: "prod",                        // string for explicit, true for auto-detected, false to disable
+  vault: false,                            // shortcut for envPath: "vault"
+
+  // load behavior
+  override: false,
+  quiet: true,
+  variables: ["DEBUG=1"],                  // post-load mutation; always wins
+
+  // auto-detection
+  autoDetect: true,
+  nodeEnvMap: { qa: "qa-prod" },
+
+  // post-load behavior
+  required: ["DATABASE_URL"],              // exit 1 if any is unset after load
+  expand: true,                            // resolve ${VAR} references
+  defaults: { LOG_LEVEL: "info" },         // fill holes; never overwrite
 
-`@honeycluster/envx/config` is an alias of `/auto` (matches the
-`dotenv/config` convention).
+  // validation + plug-ins
+  schema: zodSchema,                       // any { safeParse(input) → { success, error?, data? } }
+  resolvers: {                             // ${provider:id} → resolver(id)
+    "aws-secrets": (id) => fetchSecret(id),
+  },
 
-### Lower-level building blocks
+  // profile selection (programmatic equivalent of --profile)
+  profile: "staging",                      // throws if config.profiles[name] is missing
 
-The same helpers the CLI uses are also exported from
-`@honeycluster/libs` if you want fine-grained control:
+  // advanced
+  workspaceRoot: "/abs/path",              // skip findWorkspaceRoot() walk-up
+};
+
+envx(opts);
+```
+
+Caller-supplied fields override matching fields from the discovered config **per-field** — anything you omit falls through to config, then to defaults.
+
+### Side-effect import
 
 ```ts
-import {
-  detectEnvironment,
-  expandCascadePaths,
-  findWorkspaceRoot,
-  loadEnv,
-  resolveEnvPaths,
-  encryptFiles,
-  decryptFiles,
-  expandEnvSrc,
-  loadDotenvxConfig,
-} from "@honeycluster/libs";
+// In your app's entry file:
+import "@super-repo/envx/auto";
+
+// envx() has already run by the time this line executes.
+const env = process.env;
 ```
 
+`@super-repo/envx/config` is an alias of `/auto` (matches the `dotenv/config` convention).
+
 ## CLI
 
 ```sh
-envx -- node app.js                # load .env (auto-detected) and run
-envx --env dev -- pnpm start       # load .env.dev
-envx print DATABASE_URL            # print one variable
-envx debug --cascade prod          # show resolved paths
-envx encrypt -e .env.prod          # encrypt values in .env.prod
-envx decrypt -e .env.prod -k FOO   # decrypt only FOO
-envx expand -e vault/.env.prod     # decrypt + expand to stdout
+envx -- node app.js                      # load .env (auto-detected) and run
+envx --env dev -- pnpm start             # load .env.dev
+envx --dir vault -- pnpm test            # load every .env* in vault/
+envx print DATABASE_URL                  # print one variable
+envx debug --cascade prod                # show resolved paths
+envx encrypt -e .env.prod                # encrypt values in .env.prod (writes ./.env.keys)
+envx encrypt --secrets                   # encrypt only conventional secret keys (*_SECRET, *_TOKEN, …)
+envx decrypt -e .env.prod -k FOO         # decrypt only FOO
+envx rotate --dir vault                  # rotate keypair for every vault/.env* file
+envx expand -e vault/.env.prod           # decrypt + expand to stdout
+envx doctor                              # health check (workspace, keys, decryptability, required, cycles)
+envx template                            # write .env.example with values stripped
+envx template --check                    # CI gate — exit 1 on .env.example drift
+envx diff .env.dev .env.prod             # show keys-only-in-a/b + value mismatches
+eval "$(envx hook bash)"                 # inject loaded env into the parent shell
+envx types                               # emit env.d.ts for typed process.env access
+envx watch -- node app.js                # restart on .env* change
+envx audit                               # scan repo for plaintext secrets
+envx --profile staging -- node app.js    # apply named profile from envx.config.*
 envx -c ./envx.config.json run -- node app.js
 ```
 
@@ -88,57 +184,820 @@ envx -c ./envx.config.json run -- node app.js
 | bin              | source                       | what it does                                    |
 | ---------------- | ---------------------------- | ----------------------------------------------- |
 | `envx`           | `dist/cli.js`                | This package's CLI (subcommands below)          |
-| `dotenvx-proxy`  | `dist/bin/dotenvx.js`        | Passthrough to upstream `@dotenvx/dotenvx`      |
+| `dotenvx-proxy`  | `dist/bin/dotenvx.js`        | Direct passthrough to upstream `@dotenvx/dotenvx` |
 
 ### Subcommands
 
+#### Core
+
 | command   | what it does                                                                           |
 | --------- | -------------------------------------------------------------------------------------- |
 | `run`     | (default) load env files into `process.env` and execute a command                      |
 | `print`   | load env files and print a single variable's value                                     |
 | `debug`   | show which files would be loaded without loading them                                  |
-| `encrypt` | encrypt values in one or more `.env*` files (writes `.env.keys` on first run)          |
+| `encrypt` | encrypt values in one or more `.env*` files (writes `.env.keys` on first run). Selective: `--key`, `--pattern '*_SECRET,*_TOKEN'`, `--secrets` preset |
 | `decrypt` | decrypt values back in place                                                           |
+| `rotate`  | generate a fresh keypair and re-encrypt every encrypted value in place                 |
+| `info`    | print resolved configuration, auto-detection details, NODE_ENV mappings, and the env files that would load |
 | `expand`  | decrypt (if needed) and expand `${VAR}` / `$VAR` / `${VAR:-default}` / `${VAR:?msg}`   |
 
+#### Workflow + DX
+
+| command       | what it does                                                                                                     |
+| ------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `doctor`      | run health checks: workspace + config visible, env files exist, keys file present, every encrypted value decrypts, `required` keys filled after a dry load, expansion has no cycles. Exits non-zero on hard failures. CI-friendly. |
+| `template`    | emit a value-stripped `.env.example` from your real env files. `--check` mode exits 1 on drift; `--stdout` prints to stdout; `--annotate` (default on) tags each key with the source file. |
+| `diff <a> <b>` | compare two env files key-by-key. Reports keys-only-in-a, keys-only-in-b, and value mismatches. Decrypts via `.env.keys` so the comparison reflects logical values; values are masked unless `--show-values`. |
+| `hook <shell>` | print eval-able shell exports for the loaded env. Supports `bash`, `zsh`, `fish`, `powershell`/`pwsh` with proper escaping. Use `eval "$(envx hook bash)"` to inject env into the parent shell. |
+| `types`       | emit an `env.d.ts` declaring every loaded key on `NodeJS.ProcessEnv`. Keys listed in `required` (or non-optional in a Zod schema) narrow to `string`; everything else is `string \| undefined`. |
+| `watch`       | spawn a command and restart it whenever any of the resolved env files change. Debounce + SIGTERM-then-SIGKILL grace for clean restarts. |
+| `audit`       | walk the repo looking for plaintext secrets — AWS keys, GitHub PATs, Stripe live/test keys, JWTs, OpenAI / Anthropic keys, Google API keys, Slack tokens, PEM private-key blocks. Findings are redacted; exit 1 on any hit. `--json` for downstream tools. |
+| `bake`        | resolve every `${{provider:id}}` ref + decrypt every encrypted value + run defaults / expand / schema / public-mirror, then write a sealed `.env.resolved` for build tools to consume. Output is plaintext — refuses to write under `.git/`; use `--public-only` for client bundles. `--json` for structured tools, `--out=-` for stdout. |
+
 ### Global options
 
-| option          | alias       | default     | description                                                                              |
-| --------------- | ----------- | ----------- | ---------------------------------------------------------------------------------------- |
-| `--config`      | `-c`        | _(auto)_    | Path to an `envx.config.{ts,js,json}`. Discovery order: flag → `package.json` `envx.config` → auto-discover. |
-| `--env`         | `-e`        | `[".env"]`  | Files to load (repeatable). Auto-discovered from `--env-path` when omitted.              |
-| `--env-path`    |             | _(none)_    | Subdirectory holding env files. When set + `--env` omitted, every `.env*` in the dir is included. |
-| `--vault`       | `--va`      | `false`     | Shortcut for `--env-path vault`.                                                         |
-| `--variables`   | `-v`        | `[]`        | Inline `name=value` overrides (repeatable).                                              |
-| `--cascade`     |             | _(off)_     | Cascade name; expands `.env`, `.env.<c>`, `.env.local`, `.env.<c>.local`.                |
-| `--override`    | `-o`        | `false`     | Override existing `process.env` values. Conflicts with `--cascade`.                      |
-| `--quiet`       | `-q`        | `true`      | Suppress dotenv's own output.                                                            |
-
-### Auto-detect rules
-
-The auto-detected environment becomes the suffix on `.env.<env>`:
-
-| signal                                | resolves to     |
-| ------------------------------------- | --------------- |
-| `VERCEL_ENV=production`               | `.env.prod`     |
-| `VERCEL_ENV=preview` (or unset)       | `.env.dev`      |
-| Netlify `CONTEXT=production`          | `.env.prod`     |
-| Netlify `CONTEXT=deploy-preview` / `branch-deploy` | `.env.dev` |
-| `NODE_ENV=production`                 | `.env.prod`     |
-| `NODE_ENV=development`                | `.env.dev`      |
-| `NODE_ENV=local`                      | `.env.local`    |
-| _no signals_                          | `.env`          |
-
-Auto-detection only triggers when `--env` is left at its default
-(`[".env"]`). Explicit `--env` always wins.
+| option            | alias            | default              | description                                                                              |
+| ----------------- | ---------------- | -------------------- | ---------------------------------------------------------------------------------------- |
+| `--config`        | `-c`             | _(auto)_             | Path to an `envx.config.{ts,js,json}`. Discovery: flag → `package.json#envx.config` → walk-up auto-discovery. |
+| `--env`           | `-e`             | `[".env"]`           | Files to load (repeatable). Auto-discovered from `--env-path` when omitted.              |
+| `--env-path`      | `-d`, `--dir`    | _(none)_             | Subdirectory holding env files. Cwd-first; falls back to `<workspace-root>/<dir>` if the cwd path doesn't exist. When set + `--env` omitted, every `.env*` in the resolved dir is included. |
+| `--vault`         | `--va`           | `false`              | Shortcut for `--env-path vault`.                                                         |
+| `--env-keys-file` | `-fk`            | `<cwd>/.env.keys`    | Path to the `.env.keys` file. Cwd-first; walks up to the workspace root if no keys file exists at cwd. |
+| `--variables`     | `-v`             | `[]`                 | Inline `name=value` overrides (repeatable).                                              |
+| `--cascade`       |                  | _(off)_              | Cascade name; expands `.env`, `.env.<c>`, `.env.local`, `.env.<c>.local`.                |
+| `--override`      | `-o`             | `false`              | Override existing `process.env` values. Conflicts with `--cascade`.                      |
+| `--quiet`         | `-q`             | `true`               | Suppress dotenv's own output.                                                            |
+| `--profile`       | `-P`             | _(none)_             | Named profile from `profiles` in `envx.config.*` — fields override the base config per-field. |
+
+### Defaults
+
+Six resolution rules drive every envx invocation. Each is overridable — see [Configuration](#configuration) below for the layered customization map.
+
+#### 1. Environment auto-detection
+
+When `--env` is left at its default (`[".env"]`), envx auto-detects the deployment environment from well-known platform signals and rewrites the env-file suffix accordingly. Source-of-truth: `detectEnvironment()`.
+
+Order of precedence: **Vercel → Netlify → `NODE_ENV` → unsuffixed**.
+
+| signal                                                  | detected   | env file picked |
+| ------------------------------------------------------- | ---------- | --------------- |
+| `VERCEL` set + `VERCEL_ENV=production`                  | `prod`     | `.env.prod`     |
+| `VERCEL` set + any other `VERCEL_ENV` (or unset)        | `dev`      | `.env.dev`      |
+| `NETLIFY` set + `CONTEXT=production`                    | `prod`     | `.env.prod`     |
+| `NETLIFY` set + `CONTEXT=deploy-preview` / `branch-deploy` | `dev`   | `.env.dev`      |
+| `NETLIFY` set + any other `CONTEXT`                     | `dev`      | `.env.dev`      |
+| `NODE_ENV=production`                                   | `prod`     | `.env.prod`     |
+| `NODE_ENV=development`                                  | `dev`      | `.env.dev`      |
+| `NODE_ENV=local`                                        | `local`    | `.env.local`    |
+| `NODE_ENV=<other>` (e.g. `staging`, `qa`, `preview`)    | `<other>`  | `.env.<other>`  |
+| _no signals_                                            | `root`     | `.env`          |
+
+`NODE_ENV` values not in the built-in map (`production`, `development`, `local`) **pass through lowercased** as the suffix. So `NODE_ENV=staging` → `.env.staging`, `NODE_ENV=QA` → `.env.qa`, etc. — no config required.
+
+**Customize:**
+- Pass `--env <name>` (or `-e <name>`) to bypass detection entirely; bare names get the `.env.` prefix automatically (`--env staging` → `.env.staging`).
+- Disable detection: set `autoDetect: false` in `envx.config.{ts,js,json}`.
+- Override the `NODE_ENV → suffix` mapping in config:
+  ```ts
+  // envx.config.ts
+  export default {
+    nodeEnvMap: {
+      // built-ins keep working unless you override them:
+      production: "prod",
+      development: "dev",
+      local: "local",
+      // your additions / remappings:
+      qa: "qa-prod",       // NODE_ENV=qa → .env.qa-prod
+      preview: "",         // NODE_ENV=preview → .env (no suffix)
+    },
+  }
+  ```
+- Programmatic: `envx({ envFiles: [...] })`, `envx("staging")` (sets `cascade`), or `envx({ autoDetect: false, nodeEnvMap: { ... } })`.
+
+Run **`envx info`** to print the resolved settings, the detected environment, the active mapping, and which files would be loaded.
+
+#### 2. Cascade expansion order
+
+`--cascade <name>` expands the base files into a layered set, **least- to most-specific**, so that the most specific one wins. Source-of-truth: `expandCascadePaths()`.
+
+For a base of `.env` and `--cascade prod`:
+
+| order | path              | role                              |
+| :---: | ----------------- | --------------------------------- |
+|   1   | `.env.prod.local` | per-developer prod override (gitignored) |
+|   2   | `.env.local`      | per-developer override (gitignored) |
+|   3   | `.env.prod`       | shared prod values (committable, encryptable) |
+|   4   | `.env`            | shared baseline                   |
+
+Without `--cascade`: `.env.local` → `.env` (still least-specific-last).
+
+**Customize:**
+- **CLI**: pass `--cascade <name>` to cascade with an explicit env name (e.g. `--cascade prod`).
+- **Config**: set `cascade: true` to cascade using the auto-detected env name. `cascade: false` (or omit) disables.
+- **Programmatic**: `envx({ cascade: true })` for auto-detected, `envx({ cascade: "prod" })` for explicit, `envx("prod")` (string shorthand) is equivalent to the explicit form.
+- `--override` conflicts with cascade — envx exits with an error if both are set.
+
+#### 3. Path resolution (cwd-first → workspace-root fallback)
+
+Every relative path passed to `--dir`, `--env-path`, `--env-keys-file`, or set in config goes through the same resolver. Source-of-truth: `resolveCwdOrWorkspace()`.
+
+```
+absolute path?            → use verbatim
+<cwd>/<rel> exists?       → use that
+<workspaceRoot>/<rel>?    → use that
+neither?                  → return <cwd>/<rel> so callers (encrypt, etc.) can create it
+```
+
+The "default `.env.keys`" lookup runs the same resolver against the literal `".env.keys"` — so a single `.env.keys` at the workspace root serves every package by default.
+
+**Customize:**
+- Pass an absolute path to `-fk` / `--dir` to skip the walk-up entirely.
+- Set `envKeysFile` / `envPath` in `envx.config.{ts,js,json}`.
+- Programmatic: `envx({ envPath: "vault", envKeysFile: "/abs/path/.env.keys" })`.
+
+#### 4. Workspace root detection
+
+`findWorkspaceRoot(startDir)` walks up from `startDir` and returns the first directory that matches one of these signals, in order:
+
+| pass | signal                                                       |
+| :--: | ------------------------------------------------------------ |
+|  1   | `package.json` with a `workspaces` field (npm/yarn)          |
+|  1   | `package.json` with a `pnpm.workspaces` field                |
+|  2   | `pnpm-workspace.yaml`                                        |
+|  2   | `lerna.json`                                                 |
+|  2   | `nx.json`                                                    |
+|  2   | `rush.json`                                                  |
+|  2   | `yarn.lock`                                                  |
+|  2   | `pnpm-lock.yaml`                                             |
+
+If nothing matches, `startDir` is returned (so envx degrades to single-package behavior — the cwd-first / fallback resolver still works, the fallback is just a no-op).
+
+**Customize:**
+- The detection is currently hardcoded. If you have a non-standard layout, pass absolute paths to `--dir` / `-fk` / `--env` and skip the walk entirely. Reach out if you have a layout that needs a new indicator added.
+
+#### 5. Default `--env` / `--env-path` behavior
+
+| condition                                              | resolved env files                                              |
+| ------------------------------------------------------ | --------------------------------------------------------------- |
+| `--env` explicitly passed                              | exactly the files passed (with `.env.` prefix added to bare names) |
+| `envFiles` set in config                               | the config's list                                               |
+| `--env-path <dir>` set, no `--env`                     | every `.env*` file inside `<dir>` (sorted, excluding `.env.keys`) |
+| neither set                                            | `[".env"]` (with auto-detection from rule #1)                  |
+
+`--vault` is exact shorthand for `--env-path vault`. The `.env.keys` file is **never** discovered by `listEnvFiles`, so `--dir vault` won't accidentally try to "encrypt" your private keys.
+
+**Customize:**
+- `--env <file>` (repeatable) — explicit list.
+- `--env-path <dir>` (or `--dir`, `-d`) — pull every `.env*` from a directory.
+- `envFiles` / `envPath` in config.
+- Programmatic: `envx({ envFiles: [...], envPath: "..." })`.
+
+#### 6. CLI variable overrides
+
+`-v KEY=VALUE` (repeatable) sets values on `process.env` *after* env files load. Format is `^(\w+)=([\s\S]+)$` — multi-line values are supported, but the key must be a valid bash identifier. Source-of-truth: `validateCmdVariable()`.
+
+**Customize:**
+- `-v KEY=VALUE` per-call.
+- Programmatic: `envx({ variables: ["KEY=VALUE", ...] })`.
+
+## Encryption
+
+envx uses **asymmetric (ECIES) encryption by default** — exactly the same scheme as `dotenvx`. On first encrypt of a fresh `.env*` file:
+
+1. A fresh secp256k1 keypair is generated.
+2. The public key gets prepended to the env file as a banner + `ENVX_PUBLIC_KEY*` header (safe to commit).
+3. The matching private key gets written to `.env.keys` (gitignore this) under `ENVX_PRIVATE_KEY*` with a section banner per env file.
+4. Every selected value is encrypted with the public key. Since the public key is committed alongside the env file, anyone with read access can encrypt new values; only the private-key holder can decrypt.
+
+A typical encrypted `.env.dev`:
+
+```
+#/-------------------[ENVX_PUBLIC_KEY]----------------------/
+#/            public-key encryption for .env files          /
+#/       [how it works](https://dotenvx.com/encryption)     /
+#/----------------------------------------------------------/
+ENVX_PUBLIC_KEY_DEV="0266287313a6f4d107115d5963640830fcca378ae34a5e3dbf775122fd121f7084"
+
+DATABASE_URL=encrypted:Bf3p…
+API_KEY=encrypted:7nQ2…
+```
+
+…and the matching `.env.keys` (gitignored):
+
+```
+#/------------------!ENVX_PRIVATE_KEYS!---------------------/
+#/ private decryption keys. DO NOT commit to source control /
+#/     [how it works](https://dotenvx.com/encryption)       /
+#/----------------------------------------------------------/
+
+# .env.dev
+ENVX_PRIVATE_KEY_DEV="…64 hex chars…"
+
+# .env.prod
+ENVX_PRIVATE_KEY_PROD="…64 hex chars…"
+```
+
+### Rotating keys
+
+```sh
+envx rotate                  # rotate keypair for ./.env
+envx rotate --dir vault      # rotate every vault/.env* file
+envx rotate -k API_KEY       # rotate one variable in place
+```
+
+Rotation generates a fresh keypair, decrypts every value with the old private key, re-encrypts with the new public key, and updates both the env file and `.env.keys` atomically. Files without a public-key header surface an error — run `envx encrypt` against them first to set up the keypair.
+
+### dotenvx-compatible naming
+
+envx reads keys under either prefix and writes new ones under the canonical names:
+
+| concept     | canonical (envx writes this)   | dotenvx-compat (envx reads this) |
+| ----------- | ------------------------------- | -------------------------------- |
+| public key  | `ENVX_PUBLIC_KEY*`              | `DOTENV_PUBLIC_KEY*`             |
+| private key | `ENVX_PRIVATE_KEY*`             | `DOTENV_PRIVATE_KEY*`            |
+
+A `.env.keys` produced by upstream dotenvx will Just Work — envx decrypts and re-encrypts in place without renaming the entry, so the diff doesn't ripple.
+
+## Configuration
+
+Every default in the previous section can be overridden. There are three precedence layers — highest to lowest:
+
+| layer                                                  | scope                       | when to use                                                |
+| ------------------------------------------------------ | --------------------------- | ---------------------------------------------------------- |
+| 1. **Per-invocation overrides** — CLI flag (`--env`, `--dir`, …) **or** programmatic arg (`envx({...})`) | one invocation              | ad-hoc overrides, scripts, embedded usage |
+| 2. **The one resolved config file**                    | the package containing the resolved config | per-package or workspace-shared defaults |
+| 3. **Built-in defaults**                                | every invocation            | the fallbacks documented in [Defaults](#defaults)         |
+
+`-v KEY=VALUE` is **not** a config layer — it's a post-load mutation of `process.env` that runs after env files are read. See "Variable-value precedence" further down.
+
+The "one resolved config file" in layer 2 comes from this discovery walk (first match wins, no merging across files):
+
+| step | source                                                          | walks up? |
+| :--: | --------------------------------------------------------------- | :-------: |
+|  1   | `--config <path>` flag (CLI only)                               | n/a       |
+|  2   | nearest `package.json#envx.config: "<path>"` from cwd up to `/` | yes       |
+|  3   | `envx.config.{ts,mts,js,mjs,cjs,json}` in **cwd only**          | no        |
+|  4   | (none — fall through to defaults)                               | n/a       |
+
+A workspace-root `envx.config.ts` is not auto-discovered from sub-packages — point sub-packages at it via `package.json#envx.config: "../../envx.config.ts"` (or whatever the relative path is).
+
+The programmatic API runs the same discovery (minus step 1):
+
+```ts
+import envx from "@super-repo/envx";
+
+envx();              // discovery + defaults
+envx("staging");     // shorthand for envx({ cascade: "staging" })
+envx({ ... });       // explicit args play the role of CLI flags (layer 1)
+```
+
+### How the layers actually merge
+
+The precedence table glosses over a real distinction: **settings** (`envFiles`, `cascade`, `envKeysFile`, …) and **variable values** (the contents of `process.env` after envx runs) flow through different rules. Worth knowing the difference if you're debugging a "why is this value what it is?" moment.
+
+#### Per-setting merge (independent, top-to-bottom)
+
+Each setting in the config-file shape (next section) is resolved **independently**. envx walks the layers for each field on its own — there's no all-or-nothing inheritance.
+
+```
+For each setting field (envFiles, cascade, envPath, envKeysFile, override, quiet, …):
+
+  1. Did the CLI flag — or programmatic arg — set this field?   → use that, stop
+  2. Is it set in the resolved config file?                     → use that, stop
+  3. Otherwise                                                    → use the built-in default
+```
+
+So you can do this without thinking about layer order:
+
+```sh
+# Config provides envFiles; CLI overrides only `cascade`.
+# Effective settings: envFiles=[".env","vault/.env.prod"], cascade="prod", everything else default.
+envx --cascade prod -- node app.js
+```
+
+with
+
+```ts
+// envx.config.ts
+export default {
+  envFiles: [".env", "vault/.env.prod"],
+}
+```
+
+The CLI flag for `cascade` wins for that field; `envFiles` falls through to the config; everything else falls through to defaults.
+
+#### Variable-value precedence (after files load)
+
+Once envx has resolved settings and loaded the env files, the actual values that end up in `process.env` follow a different order — this is dotenv's contract, with two envx-specific tweaks:
+
+```
+Final value of process.env.SOME_KEY is the FIRST hit, top-down:
+
+  1. `-v SOME_KEY=…` passed on the CLI                    (always wins)
+  2. Existing process.env.SOME_KEY when --override=false  (the default)
+     OR, when --override=true:
+     The most-specific env file's value for SOME_KEY     (cascade-wise)
+  3. The next-most-specific env file's value             (cascade order)
+  4. … all the way down the cascade
+  5. unset
+```
+
+`-v` is **not** a config layer — it's a post-load mutation of `process.env`. It runs after every env file has been loaded, and it unconditionally overwrites whatever was there. Rule of thumb:
+
+- Need to inject one ad-hoc value? `-v KEY=VALUE`.
+- Need to swap a whole environment? `--env`, `--cascade`, or `envFiles` in config.
+
+#### `--override` flips one thing only
+
+`--override=false` (the default) means **existing `process.env` wins** over what's in the env files. This matches dotenv: if your shell already exports `DATABASE_URL`, env files won't clobber it.
+
+`--override=true` means **env files win** over existing `process.env`. Useful when you want a config-driven environment to be authoritative regardless of what's in the parent shell. It's incompatible with `--cascade` (envx exits with an error) — within a cascade chain, the *most-specific* file wins anyway, which is the only ordering that makes sense.
+
+### Config-file shape
+
+```ts
+// envx.config.ts
+export default {
+  // ── env-file selection ─────────────────────────────────
+  envFiles: [".env", ".env.local"],   // bypass auto-detect; explicit list
+  envPath: "vault",                    // workspace-relative subdir (cwd-first, ws-root fallback)
+  cascade: true,                       // boolean: enable layered cascade using the auto-detected env name
+                                       // (CLI `--cascade <name>` still accepts an explicit string and overrides)
+  variables: ["DEBUG=1"],              // KEY=VALUE overrides applied after load
+
+  // ── encryption keys ────────────────────────────────────
+  envKeysFile: ".env.keys",            // overrides the cwd-first / workspace fallback default
+
+  // ── load behavior ──────────────────────────────────────
+  override: false,                     // false: existing process.env wins
+                                       // true:  env files win (incompatible with cascade)
+  quiet: true,                         // suppress dotenv's load-line output
+
+  // ── auto-detection ─────────────────────────────────────
+  autoDetect: true,                    // false disables Vercel/Netlify/NODE_ENV detection
+  nodeEnvMap: {                         // override the NODE_ENV → suffix mapping
+    production: "prod",                 // (built-ins shown — yours layer on top)
+    development: "dev",
+    local: "local",
+    qa: "qa-prod",                      // NODE_ENV=qa → .env.qa-prod
+    preview: "",                        // NODE_ENV=preview → .env (empty = no suffix)
+  },
+
+  // ── post-load behavior ─────────────────────────────────
+  required: ["DATABASE_URL", "API_KEY"], // fail-fast: exit 1 if any are unset after load
+  expand: true,                          // auto-resolve ${VAR} references against process.env
+  defaults: {                            // applied AFTER files + variables, only for unset keys
+    LOG_LEVEL: "info",
+    PORT: "3000",
+  },
+
+  // ── validation ─────────────────────────────────────────
+  schema: z.object({                     // any object exposing `safeParse(input) → { success, error?, data? }`
+    DATABASE_URL: z.string().url(),       // Zod is the obvious choice but envx duck-types — bring your own
+    PORT: z.coerce.number(),              // coerced values are written back to process.env
+  }),
+
+  // ── named profiles ─────────────────────────────────────
+  profiles: {                            // `--profile staging` (or programmatic `envx({ profile: "staging" })`)
+    staging: {                            // merges this object onto the base config per-field, profile wins
+      envFiles: [".env.staging"],
+      required: ["DB_URL"],
+    },
+    prod: {
+      envFiles: [".env.prod"],
+      cascade: true,
+      required: ["DB_URL", "API_KEY"],
+    },
+  },
+
+  // ── external secret refs ───────────────────────────────
+  resolvers: {                           // values like `${aws-secrets:my-id}` get passed to the resolver
+    "aws-secrets": (id: string) => {     // and replaced by its return. Sync — wrap async SDK calls externally.
+      return cachedAwsSecret(id);         // (e.g. pre-warm a cache before envx() runs in your bootstrap)
+    },
+  },
+
+  // ── public-variable mirroring (SSR / client-side bundlers) ─
+  publicPrefixes: ["VITE_", "NEXT_PUBLIC_"],  // duplicate every PUBLIC_* under each prefix
+  publicSource: "PUBLIC_",                     // (default) the prefix that marks a var as public
+
+  // ── advanced ───────────────────────────────────────────
+  workspaceRoot: "/abs/path/to/repo",   // escape hatch — skip findWorkspaceRoot() walk-up
+}
+```
+
+All fields are optional. Anything you omit falls through to the built-in default for that field.
+
+> **Note:** `schema`, `profiles`, and `resolvers` are TS/JS-only — JSON configs can't carry callable functions. A `package.json#envx.config` reference must point at a `.ts` / `.mts` / `.js` / `.mjs` / `.cjs` file to use them.
+
+### Discovery order
+
+When `--config <path>` is not passed, envx walks up looking for a config in this order:
+
+1. `<cwd>/envx.config.{ts,js,json,mjs,cjs}` — first hit wins
+2. `<cwd>/package.json#envx.config: "<path>"` — the string is resolved relative to that `package.json`'s directory
+3. Each parent directory, up to the workspace root, repeating steps 1 & 2
+
+`package.json#envx.config` only accepts a **string path** (not an inline object), so the config is always a single file you can lint, review, and version-control independently from the manifest.
+
+### Programmatic customization
+
+Every config field maps 1:1 onto the options accepted by the `envx()` programmatic entry point:
+
+```ts
+import envx from "@super-repo/envx";
+
+// Same as `envx --env .env.prod --env-path vault --override`:
+envx({
+  envFiles: [".env.prod"],
+  envPath: "vault",
+  override: true,
+});
+
+// String shorthand sets `cascade`:
+envx("staging");                  // == envx({ cascade: "staging" })
+```
+
+Programmatic args **override** anything from the discovered config; the config supplies fields you didn't pass.
+
+## Further reading
+
+Expanded explanations, worked examples, and recipes ship with the package in [`./docs/`](./docs/):
+
+- **[Auto-detection](./docs/auto-detection.md)** — every `VERCEL_ENV` / `CONTEXT` / `NODE_ENV` shape walked through with the file that ends up loading.
+- **[Configuration](./docs/configuration.md)** — full schema, the per-field merge rules, where each field gets read from, and the discovery walk.
+- **[Monorepo recipes](./docs/recipes.md)** — common layouts (single workspace `.env.keys`, vault subdir, per-app overrides, CI patterns) with the exact files and commands.
+
+## Library API
+
+Beyond `envx()`, the package re-exports the building blocks the CLI uses internally — useful when you need to script the same behavior from your own tool, plugin, or test harness. Everything below is importable from the default entry:
+
+```ts
+import {
+  // Programmatic loader
+  envx,
+  type EnvxProgrammaticOptions,
+  type LoadEnvOptions,
+
+  // Audit (plaintext-secret scanner)
+  auditFiles,
+  BUILT_IN_PATTERNS,
+  type AuditFinding,
+  type AuditOptions,
+  type SecretPattern,
+
+  // Crypto primitives
+  ENCRYPTED_PREFIX,
+  generateKeyPair,
+  encryptValueAsymmetric,
+  decryptValueAsymmetric,
+  isEncrypted,
+
+  // Higher-level operations
+  encryptFiles,
+  decryptFiles,
+  rotateFiles,
+
+  // Env-file parser (line-preserving)
+  parseEnv,
+  serializeEnv,
+  toRecord,
+
+  // Variable expansion (cycle-safe)
+  expandRecord,
+  expandEnvSrc,
+
+  // Config + path resolution
+  loadDotenvxConfig,
+  findWorkspaceRoot,
+  resolveCwdOrWorkspace,
+  resolveEnvPaths,
+  detectEnvironment,
+
+  // Keys-file management
+  readKeysFile,
+  writeKeysFile,
+  defaultKeysPath,
+} from "@super-repo/envx";
+```
+
+### Audit programmatically
+
+`envx audit` is a thin wrapper around `auditFiles()`. Use it directly to plug envx's secret detection into a pre-commit hook, a CI script, or your own dashboard:
+
+```ts
+import { auditFiles, type SecretPattern } from "@super-repo/envx";
+
+// Add custom patterns alongside the built-ins.
+const orgPatterns: SecretPattern[] = [
+  { id: "internal-token", label: "ACME internal token", regex: /\bacme_[A-Za-z0-9]{32}\b/ },
+];
+
+const { findings, filesScanned } = auditFiles({
+  roots: ["packages/", "apps/"],
+  ignore: ["fixtures", "snapshots"],
+  extra: orgPatterns,
+  max: 100,                       // 0 = unlimited
+});
+
+if (findings.length > 0) {
+  console.error(`audit: ${findings.length} finding(s) across ${filesScanned} files`);
+  process.exit(1);
+}
+```
+
+Findings are redacted (`AKIA…MPLE [redacted 20 chars]`) so the report itself never leaks the secret payload.
+
+### Custom profiles + resolvers in code
+
+When you need conditional behavior in a programmatic call (without a config file):
+
+```ts
+import envx from "@super-repo/envx";
+import { z } from "zod";
+
+const Schema = z.object({
+  DATABASE_URL: z.string().url(),
+  PORT: z.coerce.number().int().min(1).max(65535),
+});
+
+await preloadAwsSecretsCache();   // resolvers are sync — warm caches up front
+
+envx({
+  schema: Schema,
+  resolvers: {
+    "aws-secrets": (id) => awsSecretsCache.get(id),
+    "1password": (ref) => onePasswordCache.get(ref),
+  },
+  required: ["DATABASE_URL", "PORT"],
+  expand: true,                    // ${HOST}/api works after resolvers run
+});
+```
+
+Order of operations inside `envx()` once a profile / resolvers / schema are in play:
+
+```
+1. resolve workspaceRoot
+2. resolve env file paths
+3. load each env file              → mutates process.env (subject to `override`)
+4. apply `variables`               → unconditional overwrite
+5. run `resolvers` on ${provider:id} refs
+6. apply `defaults`                → only for keys still unset
+7. expand `${VAR}` references      (when `expand: true`)
+8. validate against `schema`       (when configured) — exits 1 on failure
+9. enforce `required`              (any unset → log + exit 1)
+```
+
+## Public variables (SSR + client bundlers)
+
+Modern frameworks each demand their own prefix for variables that should reach client-side code:
+
+| framework         | prefix          |
+| ----------------- | --------------- |
+| Vite              | `VITE_`         |
+| Next.js           | `NEXT_PUBLIC_`  |
+| Create React App  | `REACT_APP_`    |
+| Nuxt 3 (public)   | `NUXT_PUBLIC_`  |
+| SvelteKit (public)| `PUBLIC_`       |
+| Remix (loader)    | _(none)_        |
+
+Maintaining the same value under three different keys (`VITE_API_URL`, `NEXT_PUBLIC_API_URL`, `REACT_APP_API_URL`) is the kind of busywork envx exists to delete. Mark a variable "public" once with `PUBLIC_` (or any prefix you configure as `publicSource`), and envx mirrors it under every framework prefix at load time.
+
+```ts
+// envx.config.ts
+export default {
+  publicPrefixes: ["VITE_", "NEXT_PUBLIC_"],
+  // publicSource: "PUBLIC_"  // (default)
+}
+```
+
+```env
+# .env
+PUBLIC_API_URL=https://api.example.com
+PUBLIC_FEATURE_FLAG=true
+DATABASE_URL=secret-stuff       # not mirrored — no PUBLIC_ prefix
+```
+
+After `envx -- node app.js`, `process.env` looks like:
+
+| key                          | value                       | source          |
+| ---------------------------- | --------------------------- | --------------- |
+| `PUBLIC_API_URL`             | `https://api.example.com`   | original        |
+| `VITE_API_URL`               | `https://api.example.com`   | mirror          |
+| `NEXT_PUBLIC_API_URL`        | `https://api.example.com`   | mirror          |
+| `PUBLIC_FEATURE_FLAG`        | `true`                      | original        |
+| `VITE_FEATURE_FLAG`          | `true`                      | mirror          |
+| `NEXT_PUBLIC_FEATURE_FLAG`   | `true`                      | mirror          |
+| `DATABASE_URL`               | `secret-stuff`              | original (kept private — no mirror) |
+
+CLI flag for one-off use:
+
+```sh
+envx --public-prefix VITE_ --public-prefix NEXT_PUBLIC_ -- pnpm build
+```
+
+Mirroring runs **after** `expand`, so `${VAR}` references inside `PUBLIC_*` values resolve before being mirrored. Existing target keys are never overwritten — a `VITE_API_URL` already set in the parent shell wins over the auto-mirror.
+
+## Security models — when secrets are fetched
+
+Pick one based on where you want plaintext to live:
+
+| model                          | when secrets are fetched                | plaintext on disk?              | best for                                 |
+| ------------------------------ | --------------------------------------- | ------------------------------- | ---------------------------------------- |
+| **Encrypted-at-rest** (default)| process startup — `envx run --` decrypts via `.env.keys` | ciphertext only, in committed `.env*` | most apps — single binary, fast cold start |
+| **Load-time fetch** (resolvers)| process startup — plugins fetch via `resolvers:` | none — plaintext stays in process memory | server processes, long-running workers   |
+| **Build-time bake**            | once, in CI — `envx bake` writes `.env.resolved` | yes (in the build artifact) ⚠️   | static SPA bundles, public-only vars     |
+| **Runtime fetch** (edge)       | per cold start, lazily — `secrets.get()` on first read | none — secrets stay in the source-of-truth | edge functions, serverless, zero-trust   |
+
+The four models stack — most apps end up using two or more (e.g. encrypted-at-rest for non-secret config, runtime fetch for actual secrets).
+
+### Build-time bake (`envx bake`)
+
+```sh
+# CI step — resolves every encrypted value + ${provider:id} ref + ${VAR}
+# expansion + schema validation, then writes a sealed file the bundler picks up.
+envx bake --out dist/.env.resolved
+
+# Public-only mode for client bundles — only PUBLIC_* keys + their framework mirrors.
+envx bake --public-only --out dist/.env.public
+```
+
+⚠️ The output file is **plaintext**. envx writes a `# DO NOT COMMIT` banner and refuses to write under `.git/`, but you must add the path to `.gitignore` yourself. Use `--public-only` whenever the artifact will ship to clients.
+
+Build-tool integration:
+
+```ts
+// vite.config.ts
+import { defineConfig, loadEnv } from "vite";
+
+export default defineConfig(({ mode }) => {
+  // Vite's loadEnv reads .env.resolved like any other .env file.
+  const env = loadEnv(mode, process.cwd(), ".env.resolved");
+  return {
+    define: {
+      "import.meta.env.VITE_API_URL": JSON.stringify(env.VITE_API_URL),
+    },
+  };
+});
+```
+
+```sh
+# CI script
+envx bake --public-only --out .env.resolved && pnpm vite build
+```
+
+### Runtime fetch — edge / serverless
+
+For the "secrets never leave the source-of-truth" model, use `createSecretRuntime` from `@super-repo/envx-plugins/runtime`. Async-first, TTL caching, no `fs` / `child_process` dependencies — works in Cloudflare Workers, Vercel Edge, Deno Deploy, AWS Lambda, Bun, Node.
+
+```ts
+// src/secrets.ts — module-level singleton, one per worker
+import { createSecretRuntime } from "@super-repo/envx-plugins/runtime";
+import { hcVault } from "@super-repo/envx-plugins/vault";
+
+export const secrets = createSecretRuntime({
+  providers: [
+    hcVault({
+      endpoint: env.VAULT_ADDR,
+      token: env.VAULT_TOKEN,
+    }),
+  ],
+  ttl: 300,                    // refresh every 5 min
+  onFailure: "cache-stale",    // serve stale on transient backend failures
+});
+```
+
+```ts
+// src/handler.ts (Cloudflare Worker / Vercel Edge / Lambda — same shape)
+import { secrets } from "./secrets";
+
+export default async function handler(req: Request): Promise<Response> {
+  const dbUrl = await secrets.get("vault:prod/db");
+  const apiKey = await secrets.get("vault:prod/api");
+  // … handler logic …
+}
+```
+
+What you get:
+- **Lazy fetch** — first read triggers the network call. Subsequent reads within the TTL window hit memory.
+- **Single-flight** — N concurrent reads of the same ref coalesce into one fetch. Edge functions handling a burst of requests don't fan out N parallel calls to your secret store.
+- **TTL refresh** — values older than `ttl` seconds are refetched on next read. Set `ttl: Infinity` to cache forever; `ttl: 0` to fetch every read.
+- **Failure modes** — `"throw"` (default), `"cache-stale"` (serve previous value, log warning), or `"cache-error"` (cache the failure for `errorTtl` seconds so you don't hammer a failing backend).
+- **No fs / child_process imports** — the runtime entry point is V8-isolate-safe.
+
+### Compatibility note
+
+Plugin compatibility for the runtime entry depends on what each provider's transport needs:
+
+| provider           | edge runtime?               | reason                              |
+| ------------------ | --------------------------- | ----------------------------------- |
+| HashiCorp Vault    | ✓                           | native `fetch`                       |
+| Doppler            | ✓                           | native `fetch`                       |
+| Infisical          | ✓                           | native `fetch`                       |
+| AWS Secrets Manager| ⚠ Node-compat only           | `@aws-sdk/client-secrets-manager` uses Node streams |
+| GCP Secret Manager | ⚠ Node-compat only           | `@google-cloud/secret-manager` uses gRPC |
+| Azure Key Vault    | ⚠ Node-compat only           | `@azure/identity` token chain        |
+| 1Password (CLI)    | ✗                           | spawns the `op` binary               |
+| 1Password (SDK)    | depends on `@1password/sdk`  | check the SDK's runtime support       |
+
+For Cloudflare Workers / Vercel Edge / Deno: prefer Vault, Doppler, Infisical, or a custom HTTP `buildProvider`. AWS / GCP / Azure SDKs run fine in Lambda / Cloud Run / Cloud Functions but won't work in V8-only edges.
+
+## Secret-provider plugins
+
+Ship as a sibling package: [`@super-repo/envx-plugins`](https://www.npmjs.com/package/@super-repo/envx-plugins). Plugins return a `SecretProvider` you wire into envx's `resolvers:` config so values like `${aws-secrets:my-db}` and `${vault:prod/api}` fetch from the matching backend at load time.
+
+```ts
+import envx from "@super-repo/envx";
+import { awsSecrets, autoPreload, asResolvers } from "@super-repo/envx-plugins";
+
+const aws = awsSecrets({ region: "us-east-1" });
+
+await autoPreload([aws], { envFiles: [".env", "vault/.env.prod"] });
+
+envx({ resolvers: asResolvers([aws]) });
+```
+
+```env
+DATABASE_URL=${aws-secrets:prod/db}
+```
+
+Built-in providers: AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, HashiCorp Vault, 1Password (CLI + SDK), Doppler, Infisical. Each plugin lazy-loads its SDK — install only what you use. See the [`@super-repo/envx-plugins` README](../plugins/README.md) for per-provider setup.
+
+## Pre-commit hooks
+
+Three of the new commands (`audit`, `doctor`, `template --check`) are designed to compose into a single git pre-commit gate so secrets, broken configs, and stale `.env.example` files never reach the remote.
+
+The repo ships a reference `.hooks/pre-commit` you can adopt verbatim or copy into your own setup:
+
+```sh
+# Activate the in-repo .hooks/ directory (one-time per clone)
+git config core.hooksPath .hooks
+```
+
+That single config line tells git to look for hooks under `<repo>/.hooks/` instead of `.git/hooks/`. The directory is committed (everyone gets the same hooks), no third-party tool is required.
+
+The hook itself:
+
+```bash
+#!/usr/bin/env bash
+# .hooks/pre-commit
+set -euo pipefail
+[[ "${ENVX_SKIP_HOOK:-}" == "1" ]] && exit 0
+
+# Use the workspace binary if available, else a global envx
+if command -v pnpm >/dev/null && [[ -f package.json ]]; then
+  ENVX="pnpm exec envx"
+else
+  ENVX="envx"
+fi
+
+failed=0
+
+# 1. Audit staged files for plaintext secrets (AKIA, ghp_, sk_live_, JWTs, …)
+staged=$(git diff --cached --name-only --diff-filter=ACMR | tr '\n' ' ')
+[[ -n "$staged" ]] && ! $ENVX audit $staged && failed=1
+
+# 2. Workspace health (skip required-key gate so dev machines don't fail)
+$ENVX doctor --ignore-required || failed=1
+
+# 3. .env.example drift gate
+[[ -f .env ]] && ! $ENVX template --check && failed=1
+
+exit $failed
+```
+
+Bypass options:
+- `ENVX_SKIP_HOOK=1 git commit ...` — skip just the envx hook
+- `git commit --no-verify` — skip every git hook (use sparingly)
+
+The full annotated script lives at `.hooks/pre-commit` in this repo. CI should run the same three commands without the `--ignore-required` flag so missing required keys fail builds (not just commits).
+
+### Pre-push variant
+
+For a stricter gate that runs only on push (so commits stay fast but pushes are guarded):
+
+```bash
+#!/usr/bin/env bash
+# .hooks/pre-push — same checks, run against the whole repo, no skip.
+set -euo pipefail
+envx audit && envx doctor && envx template --check
+```
+
+### CI-friendly invocations
+
+```yaml
+# .github/workflows/secrets.yml
+- run: pnpm exec envx audit --json > audit.json
+- run: pnpm exec envx doctor                        # fails the build on missing required keys
+- run: pnpm exec envx template --check              # fails on .env.example drift
+```
 
 ## Embedding the CLI
 
-The yargs factory is exported under the `./commands` subpath if you
-want to register `envx`'s commands inside your own tool:
+The yargs factory is exported under the `./commands` subpath if you want to register envx's commands inside your own tool:
 
 ```ts
-import { createCli } from "@honeycluster/envx/commands";
+import { createCli } from "@super-repo/envx/commands";
 
 createCli(process.argv.slice(2)).parseSync();
 ```
@@ -146,49 +1005,56 @@ createCli(process.argv.slice(2)).parseSync();
 ## Development
 
 ```sh
-# From the package root
 pnpm install
-pnpm build               # tsc + tsc-alias → dist/
-pnpm dev                 # tsc --watch
+pnpm build               # vite library build → dist/
 pnpm test                # vitest unit tests
 pnpm test:integration    # spawn-based subprocess tests
-pnpm typecheck           # tsc --noEmit
-pnpm format              # prettier --write src/
 ```
 
-Tests live in `tests/`. The vitest config is at
-`configs/vitest.config.ts`; the `test` script invokes vitest with
-`--config` so the layout stays explicit. Integration fixtures live in
-`tests/integration/__static__/` — each subdirectory is a self-contained
-worked example (read the file content for the canonical demonstration
-of every feature).
+Tests live in `tests/`. Integration fixtures live in `tests/integration/__static__/` — each subdirectory is a self-contained worked example.
 
 ## Layout
 
 ```
-packages/core/
+packages/envx/core/
 ├── src/
-│   ├── index.ts         # default export: envx() programmatic API
-│   ├── auto.ts          # `import "@honeycluster/envx/auto"` side-effect entry
-│   ├── cli.ts           # `envx` bin entry — wires yargs + parses argv
+│   ├── index.ts            # default export: envx() programmatic API
+│   ├── auto.ts             # `import "@super-repo/envx/auto"` side-effect entry
+│   ├── cli.ts              # `envx` bin entry — wires yargs + parses argv
 │   ├── bin/
-│   │   └── dotenvx.ts   # `dotenvx-proxy` legacy passthrough
+│   │   └── dotenvx.ts      # `dotenvx-proxy` direct passthrough to upstream
 │   └── commands/
-│       ├── index.ts     # createCli — registers subcommands + global options
-│       ├── run.ts       # `run [command..]`
-│       ├── print.ts     # `print <variable>`
-│       ├── debug.ts     # `debug`
-│       ├── encrypt.ts   # `encrypt`
-│       ├── decrypt.ts   # `decrypt`
-│       └── expand.ts    # `expand`
+│       ├── index.ts        # createCli — registers subcommands + global options
+│       ├── run.ts          # `run [command..]`     — load env + spawn
+│       ├── print.ts        # `print <variable>`    — print one value
+│       ├── debug.ts        # `debug`               — show resolved paths
+│       ├── encrypt.ts      # `encrypt`             — incl. --pattern / --secrets
+│       ├── decrypt.ts      # `decrypt`
+│       ├── rotate.ts       # `rotate`              — refresh keypair across files
+│       ├── expand.ts       # `expand`              — resolve ${VAR} on stdout
+│       ├── info.ts         # `info`                — print resolved config
+│       ├── doctor.ts       # `doctor`              — health checks (CI gate)
+│       ├── template.ts     # `template`            — emit/check .env.example
+│       ├── diff.ts         # `diff <a> <b>`        — keys + value mismatches
+│       ├── hook.ts         # `hook <shell>`        — eval-able shell exports
+│       ├── types.ts        # `types`               — emit env.d.ts
+│       ├── watch.ts        # `watch -- <cmd>`      — restart on env change
+│       └── audit.ts        # `audit`               — plaintext-secret scanner
 ├── tests/
-│   ├── *.test.ts        # unit suites (env, factory, programmatic API)
+│   ├── *.test.ts           # unit suites
 │   └── integration/
-│       ├── cli.test.ts  # subprocess end-to-end suite
-│       └── __static__/  # read-only fixtures (cp'd to tmp per test)
+│       ├── cli.test.ts     # subprocess end-to-end suite
+│       └── __static__/     # read-only fixtures (cp'd to tmp per test)
 ├── configs/
 │   ├── tsconfig.build.json
+│   ├── vite.config.ts      # bundles workspace-private envx-libs/common helpers
 │   └── vitest.config.ts
 ├── tsconfig.json
 └── package.json
 ```
+
+The `envx-libs` and `envx-common` workspace packages are bundled into the published `dist/` via Vite, so this is the only npm package consumers need to install.
+
+## License
+
+MIT — same as `@dotenvx/dotenvx`. We're grateful for their work; please go support [`dotenvx.com`](https://dotenvx.com) if you build single-app stuff.