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

package/docs/auto-detection.md

@@ -0,0 +1,217 @@
+# Auto-detection
+
+When `--env` is left at its default (`[".env"]`) and no `envFiles` is set in config, envx auto-detects the deployment environment from well-known platform signals and rewrites the env-file suffix accordingly. This page walks through every input shape with the resulting file load.
+
+The implementation is `detectEnvironment()` — bundled into this package's dist via Vite.
+
+## Precedence
+
+```
+1. VERCEL    →  detection from VERCEL_ENV
+2. NETLIFY   →  detection from CONTEXT
+3. NODE_ENV  →  built-in map, then lowercased passthrough
+4. (none)    →  .env  (no rewrite)
+```
+
+The first signal that fires wins. So a Vercel build with `NODE_ENV=development` set to a non-default still reads `VERCEL_ENV` first.
+
+## Worked examples
+
+### No platform signals (typical local dev)
+
+```sh
+unset VERCEL VERCEL_ENV NETLIFY CONTEXT NODE_ENV
+envx -- node app.js
+```
+
+| signal     | value     |
+|------------|-----------|
+| (none)     | —         |
+
+→ Detected: **`root`** → loads **`.env`**.
+
+### Local dev with NODE_ENV
+
+```sh
+NODE_ENV=development envx -- node app.js
+```
+
+| signal      | value         |
+|-------------|---------------|
+| `NODE_ENV`  | `development` |
+
+→ Built-in map matches `development → "dev"` → loads **`.env.dev`**.
+
+### Staging environment via NODE_ENV (no config required)
+
+```sh
+NODE_ENV=staging envx -- pnpm test
+```
+
+| signal      | value     |
+|-------------|-----------|
+| `NODE_ENV`  | `staging` |
+
+`staging` isn't in the built-in map, so envx **passes it through lowercased**. → Loads **`.env.staging`**.
+
+The same rule applies to any value: `NODE_ENV=qa` → `.env.qa`, `NODE_ENV=preview` → `.env.preview`, `NODE_ENV=PROD` → `.env.prod` (lowercased — built-in map normalizes the canonical names anyway).
+
+### Vercel preview build
+
+```sh
+# Set by Vercel automatically:
+VERCEL=1
+VERCEL_ENV=preview
+```
+
+| signal       | value     |
+|--------------|-----------|
+| `VERCEL`     | `1`       |
+| `VERCEL_ENV` | `preview` |
+
+→ Detected: **`dev`** → loads **`.env.dev`**.
+
+`VERCEL_ENV=development` and `VERCEL_ENV=preview` both map to `dev`. Only `VERCEL_ENV=production` maps to `prod`.
+
+### Vercel production build
+
+```sh
+VERCEL=1
+VERCEL_ENV=production
+```
+
+→ Detected: **`prod`** → loads **`.env.prod`**.
+
+### Netlify production build
+
+```sh
+NETLIFY=true
+CONTEXT=production
+```
+
+→ Detected: **`prod`** → loads **`.env.prod`**.
+
+### Netlify preview / branch deploy
+
+```sh
+NETLIFY=true
+CONTEXT=deploy-preview
+# or:  CONTEXT=branch-deploy
+```
+
+→ Detected: **`dev`** → loads **`.env.dev`**.
+
+Any other Netlify `CONTEXT` value also resolves to `dev` (Netlify uses `production` only for the canonical site).
+
+### NODE_ENV with custom mapping
+
+```ts
+// envx.config.ts
+export default {
+  nodeEnvMap: {
+    production: "prod",
+    development: "dev",
+    local: "local",
+    // your additions:
+    qa: "qa-prod",          // NODE_ENV=qa loads .env.qa-prod, not .env.qa
+    preview: "",            // NODE_ENV=preview loads .env (no suffix)
+    "2025-prod": "prod",    // alias an arbitrary value
+  },
+}
+```
+
+```sh
+NODE_ENV=qa envx -- node app.js
+```
+
+→ Map override hits `qa → "qa-prod"` → loads **`.env.qa-prod`**.
+
+```sh
+NODE_ENV=preview envx -- node app.js
+```
+
+→ Map override hits `preview → ""` (empty string = no suffix) → loads **`.env`**.
+
+### Disabling auto-detection entirely
+
+```ts
+// envx.config.ts
+export default { autoDetect: false }
+```
+
+```sh
+NODE_ENV=production envx -- node app.js
+```
+
+→ Auto-detection is off → loads **`.env`** regardless of platform signals. Pass `--env` explicitly when you want a different file.
+
+## Verifying what envx will do
+
+`envx info` prints the resolved settings, the platform signals it sees, the detected environment, and the active `NODE_ENV → suffix` map. Use it as a sanity check before deploying.
+
+```sh
+envx info
+```
+
+Sample output:
+
+```
+envx info
+────────────────────────────────────────────────────────────
+Workspace
+  cwd            /repo/apps/web
+  workspace root /repo
+
+Config
+  source         /repo/envx.config.ts
+  origin         auto
+
+Resolved settings
+  envFiles       [".env"]
+  envPath        (none)
+  cascade        (off)
+  envKeysFile    /repo/.env.keys  (default: cwd-first, ws-root fallback)
+  override       false
+  quiet          true
+  autoDetect     true
+
+Platform signals (process.env)
+  VERCEL         (unset)
+  VERCEL_ENV     (unset)
+  NETLIFY        (unset)
+  CONTEXT        (unset)
+  NODE_ENV       staging
+
+Auto-detection
+  source         NODE_ENV
+  detected       staging
+  → env file     .env.staging
+
+NODE_ENV → suffix mapping
+  development    → .env.dev          (default)
+  local          → .env.local        (default)
+  production     → .env.prod         (default)
+  qa             → .env.qa-prod      (config)
+  preview        → (no suffix → .env)  (config)
+
+Resolved env file paths (would be loaded in this order)
+  .env.staging  →  /repo/.env.staging
+```
+
+## Summary table
+
+| input                                          | detected   | file       |
+|------------------------------------------------|------------|------------|
+| nothing                                        | `root`     | `.env`     |
+| `NODE_ENV=production`                          | `prod`     | `.env.prod`|
+| `NODE_ENV=development`                         | `dev`      | `.env.dev` |
+| `NODE_ENV=local`                               | `local`    | `.env.local`|
+| `NODE_ENV=staging`                             | `staging`  | `.env.staging`|
+| `NODE_ENV=QA` (uppercased)                     | `qa`       | `.env.qa`  |
+| `VERCEL=1, VERCEL_ENV=production`              | `prod`     | `.env.prod`|
+| `VERCEL=1, VERCEL_ENV=preview`                 | `dev`      | `.env.dev` |
+| `VERCEL=1` (no `VERCEL_ENV`)                   | `dev`      | `.env.dev` |
+| `NETLIFY=true, CONTEXT=production`             | `prod`     | `.env.prod`|
+| `NETLIFY=true, CONTEXT=deploy-preview`         | `dev`      | `.env.dev` |
+| `NETLIFY=true, CONTEXT=branch-deploy`          | `dev`      | `.env.dev` |
+| `autoDetect: false` (any signals)              | `root`     | `.env`     |

package/docs/configuration.md

@@ -0,0 +1,224 @@
+# Configuration
+
+envx settings come from four layers, resolved per-field with CLI flags winning. This page documents the schema, the discovery walk, and the merge rules.
+
+The full schema is the `DotenvxConfig` interface — bundled into this package's dist and importable from the CLI's bundled types.
+
+## The schema
+
+```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: cascade using the auto-detected env name
+                                       // (CLI `--cascade <name>` overrides with an explicit string)
+  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 (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",
+  },
+
+  // ── 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 — see [auto-detection](./auto-detection.md) for the per-field defaults.
+
+### Field reference
+
+| field          | type                          | default                        | meaning |
+|----------------|-------------------------------|--------------------------------|---------|
+| `envFiles`     | `string[]`                    | `[".env"]` (with auto-detect)  | Files to load. Bare names get the `.env.` prefix. Bypasses auto-detection. |
+| `envPath`      | `string`                      | _(none)_                        | Subdirectory to look in. Cwd-first; falls back to `<workspaceRoot>/<envPath>`. |
+| `cascade`      | `boolean`                     | `false`                        | When `true`, expand each base file into `.env.<env>.local`, `.env.local`, `.env.<env>`, `.env` — where `<env>` is the auto-detected name. CLI `--cascade <name>` overrides with an explicit string. |
+| `variables`    | `string[]`                    | `[]`                           | `KEY=VALUE` overrides applied after env files load. |
+| `envKeysFile`  | `string`                      | `.env.keys` (cwd-first walk-up)| Path to the keys file. Cwd-first with workspace-root fallback. |
+| `override`     | `boolean`                     | `false`                        | When `true`, env file values overwrite existing `process.env`. Conflicts with `cascade`. |
+| `quiet`        | `boolean`                     | `true`                         | Suppress dotenv's `Loading environment from:` lines. |
+| `autoDetect`   | `boolean`                     | `true`                         | Toggle Vercel/Netlify/NODE_ENV detection. |
+| `nodeEnvMap`   | `Record<string, string>`      | see below                      | Override the `NODE_ENV → suffix` map. |
+| `required`     | `string[]`                    | `[]`                           | Keys that MUST be set in `process.env` after envx finishes. Missing values cause `process.exit(1)`. |
+| `expand`       | `boolean`                     | `false`                        | Auto-resolve `${VAR}` / `$VAR` references against `process.env` after files + variables load. |
+| `defaults`     | `Record<string, string>`      | `{}`                           | Fallback values applied only to keys still unset after files + variables. Different from `variables`, which always overrides. |
+| `workspaceRoot`| `string`                      | _(auto-detect)_                | Explicit workspace root, skipping `findWorkspaceRoot()` walk-up. Useful for non-standard layouts. |
+
+### Built-in `nodeEnvMap`
+
+```ts
+{
+  production: "prod",
+  development: "dev",
+  local: "local",
+}
+```
+
+Anything **not** in the map (after merging your overrides) passes through as the lowercased `NODE_ENV` value — `staging` → `.env.staging`, `qa` → `.env.qa`. Use empty string `""` to force "no suffix" for a specific value (`preview: ""` → `NODE_ENV=preview` loads `.env`).
+
+## Discovery walk
+
+envx finds **one** config file per invocation (no merging across files) in this exact order:
+
+```
+1. --config <path>                       (CLI only — wins if present)
+2. package.json#envx.config: "<path>"     (walks UP from cwd to /)
+3. envx.config.{ts,mts,js,mjs,cjs,json}   (cwd ONLY — does not walk up)
+4. (none)                                 (built-in defaults)
+```
+
+The first match wins; we don't merge multiple files together. This means:
+
+- A `package.json#envx.config` reference anywhere from cwd up to `/` will be picked up. Use this to point sub-packages at a workspace-root config: `{ "envx": { "config": "../../envx.config.ts" } }`.
+- A bare `envx.config.ts` at the workspace root is **only** found if `cwd` happens to be the workspace root itself. Sub-packages don't auto-discover it — they need a `package.json#envx.config` reference.
+
+`package.json#envx.config` only accepts a string path (not an inline object). This keeps the manifest free of secret-related fields and forces config to be a single file you can lint and review.
+
+### Programmatic API uses the same discovery
+
+`envx()` and `envx({...})` from `@super-repo/envx` run the same `loadDotenvxConfig()` discovery as the CLI. The only difference is step 1 (`--config`) is unavailable; programmatic callers pass options directly to `envx({...})`. Programmatic args play the same role as CLI flags — see [Per-field merge](#per-field-merge) below.
+
+### Example: per-package overrides
+
+Because `envx.config.*` is **cwd-only**, sub-packages need a `package.json#envx.config` reference to find a workspace-root config. The minimal monorepo layout looks like:
+
+```
+/repo
+├── envx.config.ts                          ← workspace defaults
+├── packages/
+│   ├── api/
+│   │   └── package.json                     ← { "envx": { "config": "../../envx.config.ts" } }
+│   └── docker-builder/
+│       ├── envx.config.ts                   ← package-specific overrides
+│       └── package.json                     ← (no envx.config field needed — local file is in cwd)
+```
+
+Running `envx -- node app.js` from `/repo/packages/api`:
+- Discovery step 2 walks up `packages/api/package.json` → `packages/package.json` → `/repo/package.json`. The first one is read first; its `envx.config` field points at `../../envx.config.ts`, which resolves to `/repo/envx.config.ts`. **Match — that file is loaded.**
+
+Running the same command from `/repo/packages/docker-builder`:
+- Discovery step 2 walks up the package.jsons. None has an `envx.config` field. No match.
+- Discovery step 3 looks for `envx.config.*` in cwd (`/repo/packages/docker-builder/`). **Match — that file is loaded.**
+
+Configs don't merge across the walk — the first one found is the **only** one read. If you want true workspace-root + package-level layering, that's a feature we don't currently have.
+
+## Per-field merge
+
+Within a single invocation, each setting is resolved **independently** through these layers:
+
+```
+For each setting field (envFiles, cascade, envPath, envKeysFile,
+                       override, quiet, autoDetect, nodeEnvMap, …):
+
+  1. Did the CLI flag — or programmatic arg — set this field?   → use that, stop
+  2. Is it set in the loaded config?                            → use that, stop
+  3. Otherwise                                                    → use the built-in default
+```
+
+So you can mix layers freely:
+
+```sh
+# Config provides envFiles + nodeEnvMap; CLI overrides only `cascade`.
+envx --cascade prod -- node app.js
+```
+
+```ts
+// envx.config.ts
+export default {
+  envFiles: [".env", "vault/.env.prod"],
+  nodeEnvMap: { qa: "qa-prod" },
+}
+```
+
+Effective settings:
+
+| field       | value                              | source           |
+|-------------|------------------------------------|------------------|
+| `envFiles`  | `[".env", "vault/.env.prod"]`       | config           |
+| `cascade`   | `"prod"` (string overrides config's boolean) | CLI flag |
+| `envPath`   | _(none)_                            | default          |
+| `nodeEnvMap`| `{ qa: "qa-prod", + built-ins }`    | config (merged)  |
+| `override`  | `false`                             | default          |
+| `quiet`     | `true`                              | default          |
+| `autoDetect`| `true`                              | default          |
+
+## Load pipeline
+
+When `envx run` (or any subcommand that calls `loadEnv`) executes, the steps run in this exact order:
+
+```
+1. resolve workspaceRoot         (config field, else findWorkspaceRoot())
+2. resolve env file paths        (envFiles → .env. prefix, cascade expansion)
+3. load each env file            (encrypted values decrypted with .env.keys)
+                                  → mutates process.env (subject to `override`)
+4. apply `variables`             (-v KEY=VALUE on CLI / variables in config)
+                                  → unconditional overwrite of process.env
+5. apply `defaults`              (only for keys still undefined)
+                                  → fills holes; never overwrites
+6. expand `${VAR}` references     (when `expand: true`)
+                                  → in-place substitution against process.env
+7. enforce `required`             (any unset → log + process.exit(1))
+```
+
+Implications:
+- `variables` beats `defaults` — variables always overwrite, defaults only fill in.
+- `expand` runs AFTER `defaults`, so a default like `URL: "${HOST}/api"` can resolve.
+- `required` runs LAST, so it sees the final shape of `process.env`. A key that was unset in the env file but provided by `defaults` will pass the `required` check.
+
+## Variable-value precedence (after files load)
+
+This is separate from setting precedence. Once envx has resolved settings and loaded the env files, the actual values that end up in `process.env` follow this order:
+
+```
+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                   (cascade order)
+  3. The next-most-specific env file's value
+  4. … all the way down the cascade
+  5. unset
+```
+
+`-v` is **not** a config layer — it's a post-load mutation of `process.env`. Use it for one-off injections; use `envFiles` / `cascade` to swap whole environments.
+
+## Validation
+
+The config is parsed by `normalize()` in `config.ts`. Unknown fields are silently dropped (so adding a typo won't error — it'll just have no effect). Wrong types for known fields are dropped too:
+
+| input                                  | result                                       |
+|----------------------------------------|----------------------------------------------|
+| `envFiles: ".env"` (string, not array) | dropped — must be `string[]`                 |
+| `nodeEnvMap: { qa: 42 }`               | the entry is dropped (value must be string)  |
+| `unknown: "field"`                     | silently dropped                              |
+
+If you want strict validation in CI, run `envx info` and grep for the field — the displayed value tells you whether envx accepted it. (A future addition could be a `--strict` flag that errors on unknowns; not currently implemented.)
+
+## See also
+
+- [Auto-detection](./auto-detection.md) — every signal shape walked through with examples.
+- [Recipes](./recipes.md) — common monorepo layouts with the exact config files.

package/docs/recipes.md

@@ -0,0 +1,234 @@
+# Monorepo recipes
+
+Concrete layouts for the most common envx-in-a-monorepo setups. Each recipe lists the directory tree, the config files, and the commands you'd run.
+
+## Recipe 1: Single workspace `.env.keys`, vault subdirectory
+
+The most common shape — encrypted env files live in `vault/` at the workspace root, with one `.env.keys` (gitignored) covering everything.
+
+```
+/repo
+├── .env.keys                          ← gitignored, holds private keys for every vault file
+├── pnpm-workspace.yaml
+├── envx.config.ts                     ← workspace-level defaults
+├── vault/
+│   ├── .env                            ← committed, encrypted
+│   ├── .env.dev                        ← committed, encrypted
+│   ├── .env.prod                       ← committed, encrypted
+│   └── .env.staging                    ← committed, encrypted
+└── packages/
+    ├── api/
+    │   └── package.json
+    └── web/
+        └── package.json
+```
+
+```ts
+// /repo/envx.config.ts
+export default {
+  envPath: "vault",      // every command pulls from vault/
+}
+```
+
+```sh
+# Commands run from any package directory — envx walks up to find the config.
+cd /repo/packages/api
+
+envx encrypt -e .env.prod              # writes vault/.env.prod + updates /repo/.env.keys
+envx -- pnpm start                     # auto-detects environment, loads vault/.env.<detected>
+envx --cascade prod -- node app.js     # layers vault/.env, vault/.env.prod, etc.
+envx rotate                            # rotates the keypair for vault/.env
+envx info                              # shows what envx resolved
+```
+
+`.gitignore` should contain `.env.keys` (and any `.env.*.local` if you use cascades).
+
+## Recipe 2: Per-package overrides on top of workspace defaults
+
+Some packages have additional environment files that don't belong at the workspace root (e.g. a Docker image-builder that pulls from a separate vault).
+
+```
+/repo
+├── envx.config.ts                     ← workspace defaults
+├── vault/
+│   └── .env                           ← shared by most packages
+└── packages/
+    ├── api/                           ← inherits /repo/envx.config.ts
+    │   └── package.json
+    └── docker-builder/
+        ├── envx.config.ts             ← package-local override
+        ├── vault/
+        │   └── .env.image             ← only relevant to this package
+        └── package.json
+```
+
+```ts
+// /repo/envx.config.ts
+export default {
+  envPath: "vault",
+}
+```
+
+```ts
+// /repo/packages/docker-builder/envx.config.ts
+export default {
+  envFiles: [".env.image"],
+  envPath: "vault",
+}
+```
+
+When run from `packages/docker-builder/`, envx finds the package-local config first and uses it. From `packages/api/`, envx walks up and uses the workspace config. Configs **don't merge** across the walk — the closest one wins entirely.
+
+## Recipe 3: NODE_ENV-driven environments without `--env` everywhere
+
+You want `pnpm start` to load `.env.dev`, `pnpm start:prod` to load `.env.prod`, and `NODE_ENV=staging pnpm test` to load `.env.staging` — all without typing `--env` each time.
+
+```ts
+// /repo/envx.config.ts
+export default {
+  // No envFiles → auto-detect kicks in.
+  // No nodeEnvMap override needed — staging passes through automatically.
+}
+```
+
+```jsonc
+// /repo/package.json
+{
+  "scripts": {
+    "start":      "envx -- node app.js",                    // → .env (no NODE_ENV)
+    "start:dev":  "NODE_ENV=development envx -- node app.js", // → .env.dev
+    "start:prod": "NODE_ENV=production  envx -- node app.js", // → .env.prod
+    "test:staging": "NODE_ENV=staging envx -- vitest run"     // → .env.staging
+  }
+}
+```
+
+If your team uses non-canonical names (`qa`, `preview`, …), envx loads `.env.<value>` automatically — no config change needed.
+
+## Recipe 4: Custom `NODE_ENV` mapping
+
+You want `NODE_ENV=qa` to load `.env.qa-prod` (because QA actually shares prod's external services), and `NODE_ENV=preview` to load just `.env` (no per-environment overrides).
+
+```ts
+// /repo/envx.config.ts
+export default {
+  envPath: "vault",
+  nodeEnvMap: {
+    qa: "qa-prod",
+    preview: "",        // empty = no suffix → .env
+  },
+}
+```
+
+```sh
+NODE_ENV=qa envx -- node app.js
+# Loads vault/.env.qa-prod (or walks up if missing)
+
+NODE_ENV=preview envx -- node app.js
+# Loads vault/.env  (no preview-specific file)
+```
+
+Verify with `envx info`:
+
+```
+NODE_ENV → suffix mapping
+  development    → .env.dev          (default)
+  local          → .env.local        (default)
+  production     → .env.prod         (default)
+  qa             → .env.qa-prod      (config)
+  preview        → (no suffix → .env) (config)
+```
+
+## Recipe 5: CI without committing `.env.keys`
+
+In CI (GitHub Actions, Vercel, Netlify, …), the `.env.keys` file isn't checked in. Inject the private keys via the platform's secret store and write them out at job start.
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/ci.yml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - run: pnpm install --frozen-lockfile
+
+      # Materialize .env.keys from secrets — one entry per encrypted file.
+      - name: Write .env.keys
+        run: |
+          cat > .env.keys <<EOF
+          ENVX_PRIVATE_KEY="${{ secrets.ENVX_PRIVATE_KEY }}"
+          ENVX_PRIVATE_KEY_PROD="${{ secrets.ENVX_PRIVATE_KEY_PROD }}"
+          ENVX_PRIVATE_KEY_STAGING="${{ secrets.ENVX_PRIVATE_KEY_STAGING }}"
+          EOF
+
+      - run: NODE_ENV=staging pnpm test
+```
+
+The `.env.keys` lands at the repo root; envx finds it via the cwd-first walk-up regardless of which package the test runs in.
+
+### Vercel / Netlify
+
+These platforms set `VERCEL_ENV` / `CONTEXT` automatically, so envx auto-detects the right `.env.<env>` without `NODE_ENV`. Inject `.env.keys` via their secret-file or env-var mechanism.
+
+For per-environment private keys, set them as project env vars and write `.env.keys` in your build step:
+
+```sh
+# Vercel build command
+echo "ENVX_PRIVATE_KEY_PROD=$ENVX_PRIVATE_KEY_PROD" > .env.keys && pnpm build
+```
+
+## Recipe 6: Programmatic embed with custom config
+
+You're building a CLI of your own and want to embed envx's loading + auto-detect without the user having to install envx separately.
+
+```ts
+import envx from "@super-repo/envx";
+
+// Same shape as envx.config.ts:
+envx({
+  envFiles: ["vault/.env.prod"],
+  envPath: "vault",
+  override: true,
+  autoDetect: false,                  // we're picking files explicitly
+  variables: ["MY_TOOL_VERSION=1.2.3"],
+});
+
+// process.env is now populated; carry on.
+```
+
+For full control over which yargs commands you re-export, pull `createCli` from the `/commands` subpath:
+
+```ts
+import { createCli } from "@super-repo/envx/commands";
+
+createCli(process.argv.slice(2)).parseSync();
+```
+
+## Recipe 7: Migrating an existing dotenvx project
+
+You have a project using `@dotenvx/dotenvx` directly and want to switch.
+
+1. **Install:**
+   ```sh
+   pnpm add @super-repo/envx
+   pnpm remove @dotenvx/dotenvx
+   ```
+
+2. **Rename references:** `dotenvx encrypt` → `envx encrypt`, `dotenvx run` → `envx run`. The `dotenvx-proxy` bin in this package is a direct passthrough to the upstream dotenvx CLI if you need to keep specific commands working during migration.
+
+3. **Keys file:** existing `.env.keys` files **work as-is**. envx reads `DOTENV_PRIVATE_KEY*` and `DOTENV_PUBLIC_KEY*` as fallbacks — no rename needed. New encrypts will use the canonical `ENVX_PRIVATE_KEY*` / `ENVX_PUBLIC_KEY*` names; you can migrate the existing entries opportunistically (or never).
+
+4. **Verify:**
+   ```sh
+   envx info
+   envx -- node app.js   # same behavior as before
+   ```
+
+If anything decrypts under dotenvx but not envx (or vice versa), they're not actually wire-compatible and we should know — open an issue.