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

package/README.md

@@ -1,1000 +1,111 @@
 # @super-repo/envx
 
-Workspace-aware env-file loader, runner, and encryption tool — built for monorepos.
+> Workspace-aware env-file loader, runner, and encryption tool — built for monorepos.
 
-```sh
-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.
+[![NPM](https://nodei.co/npm/@super-repo/envx.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/@super-repo/envx)
 
-## Programmatic API
+[![npm version](https://img.shields.io/npm/v/@super-repo/envx.svg)](https://www.npmjs.com/package/@super-repo/envx)
+[![npm downloads](https://img.shields.io/npm/dm/@super-repo/envx.svg)](https://www.npmjs.com/package/@super-repo/envx)
+[![license](https://img.shields.io/npm/l/@super-repo/envx.svg)](./LICENSE)
 
-### `import envx from "@super-repo/envx"`
+Monorepos break a lot of dotenv-style assumptions: env files live at multiple levels, encrypted `.env*` files spread across packages, `.env.keys` lives in *one* place, cascade resolution wants the workspace root rather than cwd. envx layers workspace-aware path resolution, a single shared keys file, and atomic key rotation on top of [dotenvx's](https://dotenvx.com) battle-tested encryption format.
 
-```ts
-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
-  envFiles: ["vault/.env.prod"],
-  envPath: "vault",
-  variables: ["PORT=3000"],
-  override: false,
-  quiet: false,
-});
-```
+Wire-format compatible with `@dotenvx/dotenvx` — same crypto (`eciesjs`), same `.env.keys` convention, same `ENCRYPTED:` ciphertext layout. A `.env*` encrypted by either tool decrypts under the other given the matching private key.
 
-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.
-
-#### Programmatic options — full surface
-
-`envx()` accepts everything from `LoadEnvOptions` plus an optional `profile` string. The full shape (`EnvxProgrammaticOptions`):
-
-```ts
-import envx, { type EnvxProgrammaticOptions } from "@super-repo/envx";
-
-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
-
-  // validation + plug-ins
-  schema: zodSchema,                       // any { safeParse(input) → { success, error?, data? } }
-  resolvers: {                             // ${provider:id} → resolver(id)
-    "aws-secrets": (id) => fetchSecret(id),
-  },
-
-  // profile selection (programmatic equivalent of --profile)
-  profile: "staging",                      // throws if config.profiles[name] is missing
-
-  // advanced
-  workspaceRoot: "/abs/path",              // skip findWorkspaceRoot() walk-up
-};
-
-envx(opts);
-```
+## Inspiration
 
-Caller-supplied fields override matching fields from the discovered config **per-field** — anything you omit falls through to config, then to defaults.
+This package stands on the shoulders of [`@dotenvx/dotenvx`](https://www.npmjs.com/package/@dotenvx/dotenvx) — the encryption format, `.env.keys` convention, public-key header layout, and broad CLI shape are all directly inspired by (and compatible with) dotenvx. **If you're building a single application, just use [`@dotenvx/dotenvx`](https://dotenvx.com)** — it's excellent. envx exists for the workspace shape on top of dotenvx's foundation.
 
-### Side-effect import
-
-```ts
-// 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
+## Getting started
 
 ```sh
-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
+pnpm add -D @super-repo/envx
 ```
 
-### Bin commands
-
-| bin              | source                       | what it does                                    |
-| ---------------- | ---------------------------- | ----------------------------------------------- |
-| `envx`           | `dist/cli.js`                | This package's CLI (subcommands below)          |
-| `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). 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: 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.
+import { defineConfig } from "@super-repo/envx";
 
-#### `--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
+export default defineConfig({
+  envFiles: [".env"],
+  cascade: true,
+  required: ["DATABASE_URL"],
 });
 ```
 
 ```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
+// app entry — pick one
+import "@super-repo/envx/auto";          // side-effect load, dotenv-style
+// or
 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}
+const { DATABASE_URL } = envx();
 ```
 
-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.
+For everything else — full schema, recipes, hook recipes, CI examples — see [Docs](#docs).
 
-## Pre-commit hooks
+## Features
 
-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.
+- **Workspace-aware path resolution** — `--dir`, `--env-path`, `--env-keys-file` resolve cwd-first then walk up to the nearest workspace root. One `.env.keys` at the repo root serves every encrypted `.env*` across the monorepo.
+- **Cascade discovery** — `--cascade prod` layers `.env`, `.env.prod`, `.env.local`, `.env.prod.local` from the workspace root, regardless of which subpackage triggered the load.
+- **Atomic key rotation** — one `envx rotate --dir vault` refreshes the keypair for every encrypted file at once. No stale keys lurking in sibling packages.
+- **Auto-environment detection** — reads `VERCEL_ENV`, Netlify `CONTEXT`, `NODE_ENV` to pick `.env.<env>` automatically. Override per-call or disable globally.
+- **`.env*` health gate** — `envx doctor`, `envx audit` (plaintext-secret scanner), `envx template --check` (drift detection) compose into a single CI / pre-commit gate.
+- **Public-variable mirroring** — mark a variable `PUBLIC_*` once; envx auto-mirrors it under `VITE_`, `NEXT_PUBLIC_`, `REACT_APP_`, etc. so you don't maintain three near-identical entries.
+- **Schema validation** — pass any object with `safeParse()` (Zod-friendly, but duck-typed) and envx fail-closes on validation errors at load time.
+- **Edge / serverless runtime** — `createSecretRuntime()` for V8-isolate-safe lazy fetching with TTL caching and single-flight coalescing.
 
-The repo ships a reference `.hooks/pre-commit` you can adopt verbatim or copy into your own setup:
+## CLI
 
 ```sh
-# Activate the in-repo .hooks/ directory (one-time per clone)
-git config core.hooksPath .hooks
+envx -- node app.js                      # load env + run command
+envx --env dev -- pnpm start             # load .env.dev
+envx --dir vault -- pnpm test            # load every .env* in vault/
+envx encrypt -e .env.prod                # encrypt values in .env.prod
+envx rotate --dir vault                  # rotate keypair across vault/.env*
+envx audit --staged                      # scan staged files for plaintext secrets
+envx doctor                              # health check (CI-friendly)
+envx template                            # write .env.example (mirrors comments/blank lines, strips values + ENVX_PUBLIC_KEY*)
+envx template --ai                       # populate example values via Claude (reads ANTHROPIC_API_KEY from your loaded .env)
+envx template --check                    # exit 1 on .env.example drift
+envx --profile staging -- node app.js    # apply a named profile
 ```
 
-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
+| bin              | what it does                                        |
+| ---------------- | --------------------------------------------------- |
+| `envx`           | This package's CLI (run, encrypt, rotate, audit, …) |
+| `dotenvx-proxy`  | Direct passthrough to upstream `@dotenvx/dotenvx`   |
 
-exit $failed
-```
+Full subcommand and flag reference: [docs/cli.md](./docs/cli.md). Full schema for `envx.config.{ts,js,json}`: [docs/configuration.md](./docs/configuration.md).
 
-Bypass options:
-- `ENVX_SKIP_HOOK=1 git commit ...` — skip just the envx hook
-- `git commit --no-verify` — skip every git hook (use sparingly)
+## envx vs. dotenvx
 
-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).
+| capability                             | `dotenvx`                       | `envx`                                                   |
+| -------------------------------------- | ------------------------------- | -------------------------------------------------------- |
+| **Target shape**                       | single application              | workspaces (pnpm/yarn/npm, Nx, Turborepo, Bazel)         |
+| **Path resolution**                    | relative to `cwd`               | cwd-first, walk up to workspace root                     |
+| **`.env.keys` location**               | alongside the env file          | one shared file at the workspace root                    |
+| **Cascade discovery**                  | from cwd                        | from workspace root, layered with package overrides      |
+| **`rotate`**                           | per-file                        | walks every encrypted file the resolver picks up         |
+| **Secret-provider plugins**            | not built in                    | `@super-repo/envx-plugins` (AWS, GCP, Azure, Vault, …)   |
+| **Schema validation / profiles / audit / doctor / template / diff / hook / types / watch / bake** | not built in | first-class                                              |
+| **Encryption (wire format)**           | ECIES via `eciesjs`             | **identical** — interoperable                            |
+| **License**                            | BSD-3-Clause                    | MIT                                                      |
 
-### Pre-push variant
+Same crypto, same file formats, same CLI vocabulary — different path-resolution layer underneath.
 
-For a stricter gate that runs only on push (so commits stay fast but pushes are guarded):
+## Pre-commit hooks & CI
 
-```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
-```
+Three checks compose into the envx git gate, but they belong at different layers:
 
-### CI-friendly invocations
+- **pre-commit** → `envx audit --staged` only. Scans the staged file set for plaintext secrets — fast, scoped to the diff git is about to record.
+- **pre-push** → `envx audit && envx doctor && envx template --check`. Whole-repo health check; runs once per push, not per commit.
+- **CI** → same as pre-push without `--ignore-required` so missing required keys fail builds.
 
-```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
-```
+See [docs/hooks.md](./docs/hooks.md) for Husky, lefthook, simple-git-hooks, native-git, and GitHub Actions recipes (per-layer + per-runner).
 
 ## 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 `./commands` if you want to register envx's subcommands inside your own tool:
 
 ```ts
 import { createCli } from "@super-repo/envx/commands";
@@ -1002,59 +113,27 @@ import { createCli } from "@super-repo/envx/commands";
 createCli(process.argv.slice(2)).parseSync();
 ```
 
-## Development
+## Docs
 
-```sh
-pnpm install
-pnpm build               # vite library build → dist/
-pnpm test                # vitest unit tests
-pnpm test:integration    # spawn-based subprocess tests
-```
-
-Tests live in `tests/`. Integration fixtures live in `tests/integration/__static__/` — each subdirectory is a self-contained worked example.
+Deep references and worked examples live alongside this package in [./docs/](./docs/):
 
-## Layout
+- **[configuration.md](./docs/configuration.md)** — full `DotenvxConfig` schema, defaults, per-field merge rules, discovery walk.
+- **[defaults.md](./docs/defaults.md)** — the six resolution rules driving every invocation (auto-detection, cascade, path resolution, workspace detection).
+- **[encryption.md](./docs/encryption.md)** — ECIES key flow, file layout, rotation, dotenvx-compatible naming.
+- **[template.md](./docs/template.md)** — `envx template` behavior: formatting preservation, banner/public-key stripping, `--ai` placeholder generation.
+- **[auto-detection.md](./docs/auto-detection.md)** — every `VERCEL_ENV` / `CONTEXT` / `NODE_ENV` shape walked through with the file that ends up loading.
+- **[recipes.md](./docs/recipes.md)** — common monorepo layouts (single workspace `.env.keys`, vault subdir, per-app overrides) with the exact files and commands.
+- **[hooks.md](./docs/hooks.md)** — Husky / lefthook / simple-git-hooks / native-git / pre-push / GitHub Actions recipes.
+- **[library-api.md](./docs/library-api.md)** — every exported function and type (`auditFiles`, `encryptFiles`, `loadDotenvxConfig`, …).
+- **[public-variables.md](./docs/public-variables.md)** — the `PUBLIC_*` mirroring story for SSR / client bundlers.
+- **[security-models.md](./docs/security-models.md)** — encrypted-at-rest vs. load-time fetch vs. build-time bake vs. runtime/edge fetch.
 
-```
-packages/envx/core/
-├── src/
-│   ├── 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` direct passthrough to upstream
-│   └── commands/
-│       ├── 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
-│   └── integration/
-│       ├── 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
-```
+## References
 
-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.
+- [`@dotenvx/dotenvx`](https://dotenvx.com) — the upstream package envx builds on. Use it directly for single-app projects.
+- [`@super-repo/envx-plugins`](../plugins) — secret-provider plugins (AWS, GCP, Azure, Vault, 1Password, Doppler, Infisical) consumed via `resolvers:`.
+- [`eciesjs`](https://www.npmjs.com/package/eciesjs) — the secp256k1 + AES-256-GCM library used for encryption.
 
 ## 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.
+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. See [LICENSE](./LICENSE).