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

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { t as createCli } from "./chunks/commands-Cg8YMJHj.js";
+import { t as createCli } from "./chunks/commands-B70xh15E.js";
 import { hideBin } from "yargs/helpers";
 //#region src/cli.ts
-createCli(hideBin(process.argv)).parseSync();
+await createCli(hideBin(process.argv)).parseAsync();
 //#endregion
 
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["// The `#!/usr/bin/env node` shebang is added at bundle time by the vite\n// build (configs/vite.config.ts → output.banner) — keeping it out of source\n// avoids a vite/esbuild quirk that drops the rest of the file body when a\n// `.ts` file starts with a shebang.\nimport { hideBin } from \"yargs/helpers\";\n\nimport { createCli } from \"./commands/index.js\";\n\ncreateCli(hideBin(process.argv)).parseSync();\n"],"mappings":";;;;AAQA,UAAU,QAAQ,QAAQ,KAAK,CAAC,CAAC,WAAW"}
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["// The `#!/usr/bin/env node` shebang is added at bundle time by the vite\n// build (configs/vite.config.ts → output.banner) — keeping it out of source\n// avoids a vite/esbuild quirk that drops the rest of the file body when a\n// `.ts` file starts with a shebang.\nimport { hideBin } from \"yargs/helpers\";\n\nimport { createCli } from \"./commands/index.js\";\n\n// `parseAsync` is required for any async command handler (template --ai\n// makes a network call). Sync handlers stay sync — yargs awaits a\n// non-promise value as a no-op, so this is a strict superset of parseSync.\nawait createCli(hideBin(process.argv)).parseAsync();\n"],"mappings":";;;;AAWA,MAAM,UAAU,QAAQ,QAAQ,KAAK,CAAC,CAAC,YAAY"}

package/dist/commands/audit.d.ts

@@ -10,4 +10,16 @@ import { CommandModule } from 'yargs';
  * only the first/last 4 chars). Exit 1 when any finding is reported.
  */
 export declare const auditCommand: CommandModule;
+/**
+ * Returns the list of files staged for the next commit (added, copied,
+ * modified, or renamed — `--diff-filter=ACMR` excludes deletions). NUL-
+ * delimited (`-z`) so paths with spaces or newlines round-trip safely.
+ *
+ * Returns `null` when not inside a git repo (so the caller can render a
+ * nicer error than git's stderr). Empty array means "in a repo, but
+ * nothing staged" — distinct from the failure case.
+ *
+ * Exported for unit testing.
+ */
+export declare function listStagedFiles(): string[] | null;
 //# sourceMappingURL=audit.d.ts.map

package/dist/commands/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/commands/audit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAO3C;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,EAAE,aA0E1B,CAAC"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/commands/audit.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAO3C;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,EAAE,aA0H1B,CAAC;AAkBF;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,GAAG,IAAI,CAejD"}

package/dist/commands/index.js

@@ -1,2 +1,2 @@
-import { t as createCli } from "../chunks/commands-Cg8YMJHj.js";
+import { t as createCli } from "../chunks/commands-B70xh15E.js";
 export { createCli };

package/dist/commands/template-ai.d.ts

@@ -0,0 +1,39 @@
+export interface AiOptions {
+    readonly provider?: "anthropic" | "openai";
+    readonly model?: string;
+    /**
+     * Env var holding the API key. Defaults to `ANTHROPIC_API_KEY` for
+     * Anthropic and `OPENAI_API_KEY` for OpenAI.
+     */
+    readonly apiKeyEnv?: string;
+    readonly baseUrl?: string;
+}
+export declare class AiError extends Error {
+    constructor(message: string);
+}
+export interface AiAuth {
+    readonly token: string;
+    readonly kind: "api-key" | "oauth";
+    readonly sourceEnv: string;
+}
+/**
+ * Resolve an API key from `process.env`. Looks at `apiKeyEnv` first
+ * (defaults to provider-appropriate name), then known OAuth fallbacks
+ * for Anthropic. Returns `null` when nothing is set — caller decides
+ * how to surface the failure.
+ */
+export declare function resolveAuth(provider: "anthropic" | "openai", apiKeyEnv: string): AiAuth | null;
+/**
+ * Generate an example value per key. Returns a Map keyed by env-var
+ * name. Keys without a usable AI response fall back to an empty string
+ * so the template still serializes cleanly.
+ *
+ * `context` is an optional per-key hint the renderer can supply (e.g.
+ * the trailing comment from the source line, or the comment block
+ * directly above) to anchor the generation.
+ */
+export declare function generateExamples(keys: ReadonlyArray<{
+    readonly name: string;
+    readonly hint?: string;
+}>, opts?: AiOptions): Promise<Map<string, string>>;
+//# sourceMappingURL=template-ai.d.ts.map

package/dist/commands/template-ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-ai.d.ts","sourceRoot":"","sources":["../../src/commands/template-ai.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,OAAQ,SAAQ,KAAK;gBACpB,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,WAAW,GAAG,QAAQ,EAChC,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAyBf;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EACtE,IAAI,GAAE,SAAc,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA+B9B"}

package/dist/commands/template.d.ts

@@ -1,8 +1,12 @@
 import { CommandModule } from 'yargs';
 /**
  * Generate (or check) a stripped `.env.example` from one or more real
- * env files. Values are removed; keys, declaration order, comments,
- * and blank lines are preserved so the example file stays readable.
+ * env files. The output mirrors the source files' organization —
+ * comments, blank lines, and declaration order are preserved verbatim.
+ * Values are stripped (or replaced with AI-generated placeholders when
+ * `--ai` is set). The encryption banner block (`#/-----[ENVX_PUBLIC_KEY]…`)
+ * and the `*PUBLIC_KEY*` kv lines themselves are dropped — the example
+ * file should be encryption-agnostic.
  *
  * Three modes:
  *   - default:  write the rendered template to --out (default `.env.example`)

package/dist/commands/template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/commands/template.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAa3C;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,aAiF7B,CAAC"}
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/commands/template.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAgB3C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,EAAE,aA2H7B,CAAC"}

package/dist/index.js

@@ -1,64 +1,3 @@
-import { A as isEncrypted, C as parseEnv, D as decryptValueAsymmetric, E as ENCRYPTED_PREFIX, O as encryptValueAsymmetric, T as toRecord, _ as resolveCwdOrWorkspace, a as auditFiles, b as expandEnvSrc, c as encryptFiles, d as writeKeysFile, g as loadEnv, i as BUILT_IN_PATTERNS, k as generateKeyPair, l as defaultKeysPath, m as findWorkspaceRoot, n as defineConfig, o as rotateFiles, p as detectEnvironment, r as loadDotenvxConfig, s as decryptFiles, u as readKeysFile, v as resolveEnvPaths, w as serializeEnv, x as expandRecord } from "./chunks/src-jaqb5pGP.js";
-//#region src/index.ts
-function envx(arg) {
-	const { config: baseConfig } = loadDotenvxConfig();
-	const userOpts = arg === void 0 ? {} : typeof arg === "string" ? { cascade: arg } : arg;
-	let cfg = baseConfig;
-	if (userOpts.profile) {
-		const profile = cfg.profiles?.[userOpts.profile];
-		if (!profile) throw new Error(`[ENVX_UNKNOWN_PROFILE] '${userOpts.profile}' not found (available: ${Object.keys(cfg.profiles ?? {}).join(", ") || "none"})`);
-		cfg = {
-			...cfg,
-			...profile
-		};
-	}
-	const { profile: _drop, ...rest } = userOpts;
-	loadEnv(mergeOpts(cfg, rest));
-	return process.env;
-}
-/**
-* Per-field merge: caller-supplied option wins, falling through to the
-* matching config field, falling through to whatever default `loadEnv`
-* has built in. Fields the caller doesn't pass and the config doesn't
-* set are simply omitted from the merged options object.
-*/
-function mergeOpts(config, user) {
-	const out = {};
-	if (user.envFiles !== void 0) out.envFiles = user.envFiles;
-	else if (config.envFiles !== void 0) out.envFiles = [...config.envFiles];
-	if (user.envPath !== void 0) out.envPath = user.envPath;
-	else if (config.envPath !== void 0) out.envPath = config.envPath;
-	if (user.cascade !== void 0) out.cascade = user.cascade;
-	else if (config.cascade !== void 0) out.cascade = config.cascade;
-	if (user.vault !== void 0) out.vault = user.vault;
-	if (user.variables !== void 0) out.variables = user.variables;
-	if (user.override !== void 0) out.override = user.override;
-	else if (config.override !== void 0) out.override = config.override;
-	if (user.quiet !== void 0) out.quiet = user.quiet;
-	else if (config.quiet !== void 0) out.quiet = config.quiet;
-	if (user.autoDetect !== void 0) out.autoDetect = user.autoDetect;
-	else if (config.autoDetect !== void 0) out.autoDetect = config.autoDetect;
-	if (user.nodeEnvMap !== void 0) out.nodeEnvMap = user.nodeEnvMap;
-	else if (config.nodeEnvMap !== void 0) out.nodeEnvMap = config.nodeEnvMap;
-	if (user.required !== void 0) out.required = user.required;
-	else if (config.required !== void 0) out.required = config.required;
-	if (user.expand !== void 0) out.expand = user.expand;
-	else if (config.expand !== void 0) out.expand = config.expand;
-	if (user.defaults !== void 0) out.defaults = user.defaults;
-	else if (config.defaults !== void 0) out.defaults = config.defaults;
-	if (user.workspaceRoot !== void 0) out.workspaceRoot = user.workspaceRoot;
-	else if (config.workspaceRoot !== void 0) out.workspaceRoot = config.workspaceRoot;
-	if (user.schema !== void 0) out.schema = user.schema;
-	else if (config.schema !== void 0) out.schema = config.schema;
-	if (user.resolvers !== void 0) out.resolvers = user.resolvers;
-	else if (config.resolvers !== void 0) out.resolvers = config.resolvers;
-	if (user.publicPrefixes !== void 0) out.publicPrefixes = user.publicPrefixes;
-	else if (config.publicPrefixes !== void 0) out.publicPrefixes = config.publicPrefixes;
-	if (user.publicSource !== void 0) out.publicSource = user.publicSource;
-	else if (config.publicSource !== void 0) out.publicSource = config.publicSource;
-	return out;
-}
-//#endregion
+import { A as isEncrypted, C as parseEnv, D as decryptValueAsymmetric, E as ENCRYPTED_PREFIX, O as encryptValueAsymmetric, T as toRecord, _ as resolveCwdOrWorkspace, a as auditFiles, b as expandEnvSrc, c as encryptFiles, d as writeKeysFile, i as BUILT_IN_PATTERNS, k as generateKeyPair, l as defaultKeysPath, m as findWorkspaceRoot, n as defineConfig, o as rotateFiles, p as detectEnvironment, r as loadDotenvxConfig, s as decryptFiles, u as readKeysFile, v as resolveEnvPaths, w as serializeEnv, x as expandRecord } from "./chunks/src-BeMTu_ms.js";
+import { t as envx } from "./chunks/src-B_rA7_sV.js";
 export { BUILT_IN_PATTERNS, ENCRYPTED_PREFIX, auditFiles, decryptFiles, decryptValueAsymmetric, envx as default, envx, defaultKeysPath, defineConfig, detectEnvironment, encryptFiles, encryptValueAsymmetric, expandEnvSrc, expandRecord, findWorkspaceRoot, generateKeyPair, isEncrypted, loadDotenvxConfig, parseEnv, readKeysFile, resolveCwdOrWorkspace, resolveEnvPaths, rotateFiles, serializeEnv, toRecord, writeKeysFile };
-
-//# sourceMappingURL=index.js.map

package/docs/defaults.md

@@ -0,0 +1,130 @@
+# Defaults
+
+Six resolution rules drive every envx invocation. Each is overridable — see [Configuration](./configuration.md) 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.
+
+## 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", ...] })`.

package/docs/encryption.md

@@ -0,0 +1,57 @@
+# 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.

package/docs/hooks.md

@@ -0,0 +1,267 @@
+# Pre-commit hooks & CI
+
+Three commands compose into the envx git gate, but they belong at different layers:
+
+| layer          | command                                                                                  | scope                          |
+| -------------- | ---------------------------------------------------------------------------------------- | ------------------------------ |
+| **pre-commit** | `envx audit --staged`                                                                    | only the files git is about to commit |
+| **pre-push**   | `envx audit && envx doctor && envx template --check`                                     | the whole working tree         |
+| **CI**         | same as pre-push, without `--ignore-required` so missing required keys fail builds       | the whole repo at the merge target |
+
+> **Note:** `envx audit` honors `.gitignore` by default (anything matched by `.gitignore` or `.git/info/exclude` is skipped, including `.env*` files). Pass `--no-respect-gitignore` to scan everything.
+
+## Choosing the runner
+
+Every recipe below uses the bare `envx` command. If the package is installed locally as a devDependency, prefix it with whichever runner your project uses — they're all interchangeable:
+
+| project setup       | invocation                       |
+| ------------------- | -------------------------------- |
+| npm / unknown       | `npx envx audit --staged`        |
+| pnpm                | `pnpm exec envx audit --staged`  |
+| Yarn (PnP or v1+)   | `yarn envx audit --staged`       |
+| Bun                 | `bunx envx audit --staged`       |
+| globally installed  | `envx audit --staged`            |
+
+`npx envx` is the most portable and works in any project that has `@super-repo/envx` on the install graph (root or nested). The recipes below show `npx`; swap for your runner if you prefer.
+
+## Why this split
+
+A pre-commit hook should only inspect what the commit is actually changing. Three reasons:
+
+1. **Speed** — pre-commit runs on every `git commit`. The developer notices anything over a second. Whole-repo checks (`doctor`, `template --check`) cross that line; staged-set scans don't.
+2. **Signal** — a failing `template --check` on a commit that didn't touch any `.env*` file is noise, not a real defect. Push the heavier checks one layer out where they make sense.
+3. **Honesty** — the gate should reflect the diff git is about to record, not the rest of the working tree.
+
+`envx audit --staged` runs `git diff --cached --name-only --diff-filter=ACMR` internally to find the staged set, then scans only those files. That's the right shape for pre-commit. Everything else is pre-push (or CI).
+
+## Pre-commit recipes
+
+All four recipes do the same one thing: scan the staged file set for plaintext secrets. Fast, scoped, fails closed when a secret slips into the diff.
+
+### Husky
+
+```sh
+npm i -D husky && npx husky init
+```
+
+```bash
+# .husky/pre-commit
+[ "${ENVX_SKIP_HOOK:-}" = "1" ] && exit 0
+npx envx audit --staged
+```
+
+### lefthook
+
+```sh
+npm i -D lefthook && npx lefthook install
+```
+
+```yaml
+# lefthook.yml
+pre-commit:
+  commands:
+    audit:
+      run: npx envx audit --staged
+```
+
+### simple-git-hooks
+
+```sh
+npm i -D simple-git-hooks
+```
+
+```json
+{
+  "simple-git-hooks": {
+    "pre-commit": "npx envx audit --staged"
+  }
+}
+```
+
+### Native git (no third-party tool)
+
+Commit hooks under `.hooks/` and activate the directory once per clone — everyone gets the same hooks, no install step.
+
+```sh
+# One-time per clone
+git config core.hooksPath .hooks
+```
+
+```bash
+#!/usr/bin/env bash
+# .hooks/pre-commit
+set -euo pipefail
+[ "${ENVX_SKIP_HOOK:-}" = "1" ] && exit 0
+npx envx audit --staged
+```
+
+## Pre-push recipes
+
+Pre-push is where the whole-repo checks run. The push has a much bigger blast radius than a commit, and it happens far less often, so the latency cost is acceptable. This is the right place for `doctor` (config / keys-file / decryptability sanity) and `template --check` (drift detection between source `.env*` and the committed `.env.example`).
+
+### Husky
+
+```bash
+# .husky/pre-push
+[ "${ENVX_SKIP_HOOK:-}" = "1" ] && exit 0
+npx envx audit
+npx envx doctor --ignore-required
+[ -f .env ] && npx envx template --check
+```
+
+### lefthook
+
+```yaml
+# lefthook.yml
+pre-push:
+  parallel: true
+  commands:
+    audit:
+      run: npx envx audit
+    doctor:
+      run: npx envx doctor --ignore-required
+    template-check:
+      run: '[ -f .env ] && npx envx template --check || true'
+```
+
+### simple-git-hooks
+
+```json
+{
+  "simple-git-hooks": {
+    "pre-push": "npx envx audit && npx envx doctor --ignore-required && ([ ! -f .env ] || npx envx template --check)"
+  }
+}
+```
+
+### Native git
+
+```bash
+#!/usr/bin/env bash
+# .hooks/pre-push
+set -euo pipefail
+[ "${ENVX_SKIP_HOOK:-}" = "1" ] && exit 0
+npx envx audit
+npx envx doctor --ignore-required
+[ -f .env ] && npx envx template --check
+```
+
+## Bypass
+
+- `ENVX_SKIP_HOOK=1 git commit …` (or `git push …`) — skip the envx hook only.
+- `git commit --no-verify` / `git push --no-verify` — skip every git hook (use sparingly).
+
+## Want both layers in one hook?
+
+If you don't run pre-push hooks at all (some teams disable them entirely), you can still scope the heavier checks to commits that actually touch env-related files. Use the staged file list as a trigger:
+
+```bash
+#!/usr/bin/env bash
+# .hooks/pre-commit — staged audit always; doctor + template only when env files change
+set -euo pipefail
+[ "${ENVX_SKIP_HOOK:-}" = "1" ] && exit 0
+
+# Always: scan the commit set for plaintext secrets.
+npx envx audit --staged
+
+# Conditionally: re-validate config / template when env-related files
+# are part of this commit. The trigger matches `.env*`, envx config
+# files, and package.json (because `envx.config` can live there).
+ENV_TRIGGER='(^|/)\.env(\.|$)|(^|/)envx\.config\.|(^|/)package\.json$'
+if git diff --cached --name-only --diff-filter=ACMR | grep -qE "$ENV_TRIGGER"; then
+  npx envx doctor --ignore-required
+  [ -f .env ] && npx envx template --check
+fi
+```
+
+This keeps the common-case commit (no env files touched) at the speed of just `audit --staged`, while still gating commits that change env-relevant files.
+
+## CI
+
+CI is the canonical place for the full battery — no `--ignore-required` so missing required keys fail builds, not just commits. Examples for the three most common npm clients — pick one:
+
+### npm
+
+```yaml
+# .github/workflows/secrets.yml
+name: secrets-gate
+on: [pull_request, push]
+jobs:
+  envx:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: npm }
+      - run: npm ci
+      - run: npx envx audit --json > audit.json   # fails on plaintext secrets
+      - run: npx envx doctor                       # fails on missing required keys
+      - run: npx envx template --check             # fails on .env.example drift
+      - if: failure()
+        uses: actions/upload-artifact@v4
+        with: { name: envx-audit, path: audit.json }
+```
+
+### pnpm
+
+```yaml
+# .github/workflows/secrets.yml
+name: secrets-gate
+on: [pull_request, push]
+jobs:
+  envx:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec envx audit --json > audit.json
+      - run: pnpm exec envx doctor
+      - run: pnpm exec envx template --check
+      - if: failure()
+        uses: actions/upload-artifact@v4
+        with: { name: envx-audit, path: audit.json }
+```
+
+### yarn
+
+```yaml
+# .github/workflows/secrets.yml
+name: secrets-gate
+on: [pull_request, push]
+jobs:
+  envx:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: yarn }
+      - run: yarn install --frozen-lockfile
+      - run: yarn envx audit --json > audit.json
+      - run: yarn envx doctor
+      - run: yarn envx template --check
+      - if: failure()
+        uses: actions/upload-artifact@v4
+        with: { name: envx-audit, path: audit.json }
+```
+
+### Matrix CI
+
+Point `--profile` at a profile defined in `envx.config.ts`:
+
+```yaml
+strategy:
+  matrix: { profile: [staging, prod] }
+steps:
+  - run: npx envx --profile ${{ matrix.profile }} doctor
+```
+
+### Without installing — `npx -p`
+
+`npx -p @super-repo/envx envx audit --staged` runs the latest published version without adding it to the install graph. Useful for one-off audits or environments where you don't want the devDependency:
+
+```yaml
+- run: npx -p @super-repo/envx envx audit --json > audit.json
+```