envpkt 0.12.0 → 0.13.1

package/README.md

@@ -210,6 +210,32 @@ const result = boot() // decrypts sealed values, injects into process.env
 
 Mixed mode is supported — sealed values take priority, with fnox as fallback for keys without `encrypted_value`.
 
+## GitHub Actions
+
+A composite action resolves the credentials in `envpkt.toml` into the CI job — with secret values masked in the log — so later steps just see them as environment variables:
+
+```yaml
+- uses: actions/checkout@v5
+
+# Sealed packets are decrypted with the `age` CLI (not preinstalled on runners).
+- run: sudo apt-get update && sudo apt-get install -y age
+
+- uses: jordanburke/envpkt@v0.12.0
+  with:
+    config: ./envpkt.toml
+    strict: "true" # fail the build if a credential is expired/unhealthy
+  env:
+    ENVPKT_AGE_KEY: ${{ secrets.ENVPKT_AGE_KEY }}
+
+- run: ./deploy.sh # sees the resolved vars; secret values redacted in the log
+```
+
+**How it works.** Commit sealed (`encrypted_value`) packets to the repo and supply the age private key as the `ENVPKT_AGE_KEY` secret. `boot()` materializes the inline key to a `0600` temp file to decrypt, then [`env github`](#envpkt-env-github) masks each secret (`::add-mask::`) and writes it to `$GITHUB_ENV`. Identity precedence: `identity.key_file` → `ENVPKT_AGE_KEY_FILE` → `ENVPKT_AGE_KEY` (inline) → `~/.envpkt/age-key.txt`.
+
+**Inputs:** `config`, `version` (npm version to run, default `latest`), `strict`, `profile`.
+
+> Decrypting sealed packets requires the [`age`](https://github.com/FiloSottile/age) CLI on the runner (install it first, as above) — not needed if you only inject plaintext `[env.*]` defaults or resolve via fnox. Pin to a released tag (e.g. `@v0.12.0`); no moving major tag (`@v1`) is published yet. Node is assumed present; add `actions/setup-node` first to pin a version.
+
 ## Fleet Management
 
 When you're running multiple agents, `envpkt fleet` scans a directory tree for `envpkt.toml` files and aggregates credential health across your entire fleet.
@@ -431,12 +457,35 @@ eval "$(envpkt env export --profile staging)"
 eval "$(envpkt env export -c path/to/envpkt.toml)"
 ```
 
-Add to your shell startup (e.g. `~/.zshrc` or `~/.bashrc`) for automatic secret loading. envpkt's [config discovery chain](#config-resolution) finds your config automatically — no platform-specific shell logic needed:
+Add to your shell startup (e.g. `~/.zshrc`) to load a global package once at login:
 
 ```bash
 eval "$(envpkt env export 2>/dev/null)"
 ```
 
+Secret values are emitted **only when the package sets top-level `scope = "shell"`** — the default `scope = "exec"` withholds them (use `envpkt exec`). For **per-project** credentials that load on `cd`, use [`envpkt shell-hook`](#envpkt-shell-hook) rather than a one-time startup eval.
+
+### `envpkt shell-hook`
+
+Generate a `cd` hook (zsh/bash) that loads a project's credentials when you enter its directory tree and restores your environment when you leave:
+
+```bash
+eval "$(envpkt shell-hook zsh)"   # add to ~/.zshrc (or: shell-hook bash)
+```
+
+On each directory change it resolves the **nearest `envpkt.toml`, walking up from the current directory** (like `git`/`direnv` — so it works from any subdirectory, not just the project root), injects that package via `env export --track`, and restores the previous package on leave (prior values, not a blind unset). Env defaults always load; secret values load only for `scope = "shell"` packages. Backed by `envpkt config-path` — a resolve-only command that prints the active config path (no decryption).
+
+> **Upward-walk discovery**: config resolution now walks up the directory tree to the nearest `envpkt.toml` before falling back to the global package. This also applies to `exec`, `env export`, and `audit` — running any of them from a subdirectory finds the enclosing project.
+
+### `envpkt env github`
+
+Inject resolved secrets into a GitHub Actions job. Emits `::add-mask::` for each secret value (redacting it from the log) and appends assignments to `$GITHUB_ENV` — under their namespaced wire names — so later steps in the job inherit them. Env defaults are written but not masked. `--strict` exits non-zero if the pre-flight audit is unhealthy. This is the engine behind the [GitHub Action](#github-actions).
+
+```bash
+# Run as a step; later steps in the job see the resolved vars
+npx envpkt env github --strict
+```
+
 ### `envpkt shell-hook`
 
 Output a shell function that runs `envpkt audit --format minimal` whenever you `cd` into a directory. envpkt's config discovery chain automatically finds config files beyond CWD (see [Config Resolution](#config-resolution)), so the hook works even in directories without a local `envpkt.toml`.

package/dist/cli.js

@@ -303,6 +303,7 @@ const EnvpktConfigSchema = Type.Object({
 		default: 1
 	}),
 	catalog: Type.Optional(Type.String({ description: "Path to shared secret catalog (relative to this config file)" })),
+	scope: Type.Optional(Type.Union([Type.Literal("shell"), Type.Literal("exec")], { description: "Whether `env export` emits this package's secrets for ambient/shell loading (`shell`) or withholds them so they are only available via `envpkt exec` (`exec`). Default `exec`. Never affects `envpkt exec`, which always injects everything." })),
 	namespace: Type.Optional(NamespaceSchema),
 	identity: Type.Optional(IdentitySchema),
 	secret: Type.Optional(Type.Record(Type.String(), SecretMetaSchema, { description: "Per-secret metadata keyed by secret name" })),
@@ -369,11 +370,24 @@ const buildSearchPaths = () => {
 	const cloudPaths = Platform.cloudStorageDirs().toArray().map((cloud) => join(cloud.path, ".envpkt", CONFIG_FILENAME$2));
 	return [...homePaths, ...cloudPaths];
 };
-/** Discover config by checking CWD, then ENVPKT_SEARCH_PATH, then dynamic Platform paths */
+/**
+* Walk up from `dir` to the filesystem root, returning the nearest `envpkt.toml`.
+* Makes a project's config apply throughout its subtree (like git/.env/direnv finding
+* their root file), not only in the directory that literally contains the file.
+* The global package lives in `~/.envpkt/` (a subdir), so it is not matched by this
+* walk — it is resolved by the search-path/Platform fallback below.
+*/
+const walkUpForConfig = (dir) => {
+	const candidate = join(dir, CONFIG_FILENAME$2);
+	if (Fs.existsSync(candidate)) return Option(candidate);
+	const parent = dirname(dir);
+	return parent === dir ? Option(void 0) : walkUpForConfig(parent);
+};
+/** Discover config by walking up from CWD, then ENVPKT_SEARCH_PATH, then dynamic Platform paths */
 const discoverConfig = (cwd) => {
-	const cwdCandidate = join(cwd ?? process.cwd(), CONFIG_FILENAME$2);
-	if (Fs.existsSync(cwdCandidate)) return Option({
-		path: cwdCandidate,
+	const walked = walkUpForConfig(cwd ?? process.cwd()).orUndefined();
+	if (walked) return Option({
+		path: walked,
 		source: "cwd"
 	});
 	const customMatch = Env.get("ENVPKT_SEARCH_PATH").fold(() => [], (v) => v.split(":").filter(Boolean)).map((template) => ({
@@ -648,6 +662,17 @@ const formatError = (error) => {
 		case "AgeNotFound": return `${RED}Error:${RESET} age CLI not found: ${error.message}`;
 		case "DecryptFailed": return `${RED}Error:${RESET} Decrypt failed: ${error.message}`;
 		case "IdentityNotFound": return `${RED}Error:${RESET} Identity file not found: ${error.path}`;
+		case "SealKeyUnavailable": {
+			const e = error;
+			return [
+				`${RED}Error:${RESET} ${e.sealedKeys.length} sealed secret(s) can't be decrypted — no age key found.`,
+				`${DIM}Searched (in order):${RESET}`,
+				e.searched.map((l) => `  • ${l}`).join("\n"),
+				`${DIM}Fix one:${RESET}`,
+				`  • Restore your key to ~/.envpkt/age-key.txt (or set ENVPKT_AGE_KEY_FILE / ENVPKT_AGE_KEY)`,
+				`  • Re-provision from source: envpkt seal --edit <KEY>`
+			].join("\n");
+		}
 		case "AuditFailed": return `${RED}Error:${RESET} Audit failed: ${error.message}`;
 		case "CatalogNotFound": return `${RED}Error:${RESET} Catalog not found: ${error.path}`;
 		case "CatalogLoadError": return `${RED}Error:${RESET} Catalog load error: ${error.message}`;
@@ -835,6 +860,19 @@ const runAuditOnConfig = (config, options) => {
 	process.exit(code);
 };
 //#endregion
+//#region src/cli/commands/config-path.ts
+/**
+* Print the `envpkt.toml` path resolved for the current directory, or nothing if none
+* is found. Resolve-only: no config load, no boot, no decryption — cheap enough for a
+* per-`cd` shell hook to gate on. Always exits 0; a missing config means "no package
+* here", not an error.
+*/
+const runConfigPath = (options) => {
+	resolveConfigPath(options.config).fold(() => {}, ({ path }) => {
+		console.log(path);
+	});
+};
+//#endregion
 //#region src/fnox/cli.ts
 /** Export all secrets from fnox as key=value pairs for a given profile */
 const fnoxExport = (profile, agentKey) => {
@@ -1326,10 +1364,13 @@ const materializeInlineKey = (key) => {
 * the caller must dispose().
 */
 const resolveSealIdentity = (config, configDir) => {
-	if (config.identity?.key_file) return Option({
-		path: resolve(configDir, expandPath(config.identity.key_file)),
-		dispose: noop
-	});
+	if (config.identity?.key_file) {
+		const keyFilePath = resolve(configDir, expandPath(config.identity.key_file));
+		if (existsSync(keyFilePath)) return Option({
+			path: keyFilePath,
+			dispose: noop
+		});
+	}
 	const envFile = process.env["ENVPKT_AGE_KEY_FILE"];
 	if (envFile && existsSync(envFile)) return Option({
 		path: envFile,
@@ -1344,6 +1385,21 @@ const resolveSealIdentity = (config, configDir) => {
 	});
 	return Option(void 0);
 };
+/** Describe the seal-identity precedence chain with per-entry status, for a clear no-key error. */
+const describeSealKeySearch = (config, configDir) => {
+	const keyFile = config.identity?.key_file;
+	const keyFileLine = keyFile ? `identity.key_file → ${resolve(configDir, expandPath(keyFile))} (${existsSync(resolve(configDir, expandPath(keyFile))) ? "found" : "missing"})` : `identity.key_file (not set)`;
+	const envFile = process.env["ENVPKT_AGE_KEY_FILE"];
+	const envFileLine = envFile ? `ENVPKT_AGE_KEY_FILE → ${envFile} (${existsSync(envFile) ? "found" : "missing"})` : `ENVPKT_AGE_KEY_FILE (unset)`;
+	const inlineLine = resolveInlineKey().isEmpty ? `ENVPKT_AGE_KEY (unset)` : `ENVPKT_AGE_KEY (set, inline)`;
+	const defaultPath = join(homedir(), ".envpkt", "age-key.txt");
+	return [
+		keyFileLine,
+		envFileLine,
+		inlineLine,
+		`${defaultPath} (${existsSync(defaultPath) ? "found" : "missing"})`
+	];
+};
 const resolveIdentityKey = (config, configDir) => {
 	return resolveIdentityFilePath(config, configDir, false).fold(() => Right(Option(void 0)), (path) => unwrapAgentKey(path).fold((err) => Left(err), (key) => Right(Option(key))));
 };
@@ -1413,6 +1469,12 @@ const bootSafe = (options) => {
 			message: "unexpected"
 		}));
 		const audit = computeAudit(config, detectFnoxKeys(configDir), void 0, aliasTable);
+		const sealIdentity = hasSealedValues ? resolveSealIdentity(config, configDir) : Option(void 0);
+		if (hasSealedValues && sealIdentity.isEmpty) return Left({
+			_tag: "SealKeyUnavailable",
+			sealedKeys: nonAliasMetaKeys.filter((k) => !!nonAliasSecretEntries[k]?.encrypted_value),
+			searched: describeSealKeySearch(config, configDir)
+		});
 		return checkExpiration(audit, failOnExpired, warnOnly).map((warnings) => {
 			const secrets = {};
 			const injected = [];
@@ -1426,9 +1488,8 @@ const bootSafe = (options) => {
 				process.env[envEnv(key)] = value;
 			});
 			const sealedKeys = /* @__PURE__ */ new Set();
-			if (hasSealedValues) resolveSealIdentity(config, configDir).fold(() => {
+			if (hasSealedValues) sealIdentity.fold(() => {
 				log.warn("phase.sealed.no_identity_file", { sealed_keys: nonAliasMetaKeys.filter((k) => !!nonAliasSecretEntries[k]?.encrypted_value).length });
-				warnings.push("Sealed values found but no identity file available for decryption");
 			}, ({ path: idPath, dispose }) => {
 				try {
 					unsealSecrets(nonAliasSecretEntries, idPath).fold((err) => {
@@ -1533,6 +1594,30 @@ const bootSafe = (options) => {
 	}));
 };
 //#endregion
+//#region src/core/dotenv.ts
+const BARE_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+/**
+* Quote a single value for dotenv output. Returns the value bare when safe,
+* otherwise double-quoted with POSIX-shell-quote escaping (`\`, `"`, `$`) and
+* whitespace collapsed to single-line escapes (`\n`, `\r`, `\t`) for portability.
+*/
+const quoteDotenvValue = (value) => {
+	if (value === "") return "";
+	if (BARE_SAFE.test(value)) return value;
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\$/g, "\\$").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")}"`;
+};
+const formatEntry = (entry, includeSecrets) => {
+	if (entry.secret && !includeSecrets) return `# (secret value omitted — re-run without --no-secrets to include)\n${entry.name}=`;
+	return `${entry.name}=${quoteDotenvValue(entry.value)}`;
+};
+/** Serialize entries to dotenv text (no trailing newline). */
+const formatDotenv = (entries, options) => {
+	const includeSecrets = options?.includeSecrets ?? true;
+	const body = entries.map((e) => formatEntry(e, includeSecrets)).join("\n");
+	const header = options?.header;
+	return header ? `${header}\n\n${body}` : body;
+};
+//#endregion
 //#region src/core/patterns.ts
 const EXCLUDED_VARS = Set$1([
 	"PATH",
@@ -2665,6 +2750,20 @@ const writeIfValid = (configPath, updated, successMsg) => {
 	writeFileSync(configPath, updated, "utf-8");
 	console.log(successMsg);
 };
+/**
+* Validate then preview (no write) — the `--dry-run` counterpart of `writeIfValid`.
+* Runs the same structural validation the real write would, so a dry-run can never
+* show a result that the actual write would reject. On invalid output it prints the
+* same error and exits 1, exactly as the write path does.
+*
+* `display` lets callers preview a focused slice (e.g. just the new block for `add`)
+* while still validating the full resulting config.
+*/
+const previewIfValid = (updated, display) => {
+	validateOrExit(updated);
+	console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
+	console.log(display ?? updated);
+};
 //#endregion
 //#region src/cli/commands/env.ts
 const printPostWriteGuidance = () => {
@@ -2798,10 +2897,15 @@ const runEnvExport = (options) => {
 		console.error(formatError(err));
 		process.exit(2);
 	}, (boot) => {
-		emitWarnings(boot);
-		collectEmitEntries(boot).forEach(({ name, value }) => {
-			console.log(`export ${name}='${shellEscape(value)}'`);
+		if (!options.track) emitWarnings(boot);
+		const scope = loadConfig(boot.configPath).fold(() => "exec", (config) => config.scope ?? "exec");
+		const gateSecrets = options.track === true && scope !== "shell";
+		const entries = collectEmitEntries(boot);
+		const emit = gateSecrets ? entries.filter((e) => !e.secret) : entries;
+		emit.forEach(({ name, value }) => {
+			console.log(options.track ? `_ENVPKT_HAD_${name}=\${${name}+1}; _ENVPKT_PREV_${name}="\${${name}-}"; export ${name}='${shellEscape(value)}'` : `export ${name}='${shellEscape(value)}'`);
 		});
+		if (options.track) console.log(`_ENVPKT_INJECTED='${emit.map((e) => e.name).join(" ")}'`);
 	});
 };
 const runEnvGithub = (options) => {
@@ -2825,6 +2929,33 @@ const runEnvGithub = (options) => {
 		if (options.strict) process.exit(exitCodeForAudit(boot.audit));
 	});
 };
+const buildDotenvHeader = (configPath) => `# Generated by envpkt — regenerate with: envpkt env dotenv\n# Source: ${configPath}. Do not edit by hand.`;
+const runEnvDotenv = (options) => {
+	resolveForEmit(options).fold((err) => {
+		console.error(formatError(err));
+		process.exit(2);
+	}, (boot) => {
+		emitWarnings(boot);
+		const entries = collectEmitEntries(boot);
+		const includeSecrets = options.secrets !== false;
+		const text = formatDotenv(entries, {
+			includeSecrets,
+			header: buildDotenvHeader(boot.configPath)
+		});
+		if (!options.output) {
+			console.log(text);
+			return;
+		}
+		const outPath = resolve(options.output);
+		Try(() => writeFileSync(outPath, `${text}\n`, "utf-8")).fold((writeErr) => {
+			console.error(`${RED}Error:${RESET} Failed to write ${outPath}: ${writeErr}`);
+			process.exit(1);
+		}, () => {
+			console.error(`${GREEN}✓${RESET} Wrote ${CYAN}${outPath}${RESET}`);
+			if (includeSecrets && entries.some((e) => e.secret)) console.error(`${YELLOW}Note:${RESET} ${outPath} contains secret values — ensure it is .gitignored.`);
+		});
+	});
+};
 const buildEnvBlock = (name, value, options) => {
 	const lines = [`[env.${name}]`, `value = "${value}"`];
 	if (options.purpose) lines.push(`purpose = "${options.purpose}"`);
@@ -3017,12 +3148,15 @@ const registerEnvCommands = (program) => {
 	env.command("check").description("Bidirectional drift detection between envpkt.toml and live environment").option("-c, --config <path>", "Path to envpkt.toml").option("--format <format>", "Output format: table | json", "table").option("--strict", "Exit non-zero on any drift").action((options) => {
 		runEnvCheck(options);
 	});
-	env.command("export").description("Output export statements for eval-ing secrets into the current shell. Usage: eval \"$(envpkt env export)\"").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("--skip-audit", "Skip the pre-flight audit").action((options) => {
+	env.command("export").description("Output export statements for eval-ing secrets into the current shell. Usage: eval \"$(envpkt env export)\"").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("--skip-audit", "Skip the pre-flight audit").option("--track", "Emit prior-value snapshots + an _ENVPKT_INJECTED list (for the shell hook to restore on cd)").action((options) => {
 		runEnvExport(options);
 	});
 	env.command("github").description("Inject resolved secrets into $GITHUB_ENV for GitHub Actions, masking secret values in the log (::add-mask::)").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("--strict", "Exit non-zero if the pre-flight audit is not healthy").action((options) => {
 		runEnvGithub(options);
 	});
+	env.command("dotenv").description("Output resolved credentials in .env format (for Wrangler, Docker --env-file, Vite, etc.)").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("-o, --output <file>", "Write to a file instead of stdout").option("--no-secrets", "Omit secret values (emit KEY= with a note) — values are included by default").action((options) => {
+		runEnvDotenv(options);
+	});
 	env.command("add").description("Add a new environment default entry to envpkt.toml").argument("<name>", "Environment variable name").argument("<value>", "Default value").option("-c, --config <path>", "Path to envpkt.toml").option("--purpose <purpose>", "Why this env var exists").option("--comment <comment>", "Free-form annotation").option("--tags <tags>", "Comma-separated key=value tags (e.g. env=prod,team=payments)").option("--dry-run", "Preview the TOML block without writing").action((name, value, options) => {
 		runEnvAdd(name, value, options);
 	});
@@ -3167,6 +3301,8 @@ const runFleet = (options) => {
 //#endregion
 //#region src/cli/commands/init.ts
 const CONFIG_FILENAME = "envpkt.toml";
+/** Resolve the top-level `scope` to scaffold: explicit --scope wins; --global implies "shell". */
+const resolveInitScope = (options) => options.scope ?? (options.global ? "shell" : void 0);
 const todayIso = () => (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
 const generateSecretBlock = (key, service) => {
 	return `[secret.${key}]
@@ -3191,6 +3327,8 @@ const generateTemplate = (options, fnoxKeys) => {
 	lines.push(`#:schema https://raw.githubusercontent.com/jordanburke/envpkt/main/schemas/envpkt.schema.json`);
 	lines.push(``);
 	lines.push(`version = 1`);
+	const scope = resolveInitScope(options);
+	if (scope) lines.push(`scope = "${scope}"   # shell = secrets load ambiently on cd/eval; exec = only via envpkt exec`);
 	lines.push(``);
 	if (options.catalog) {
 		lines.push(`catalog = "${options.catalog}"`);
@@ -3249,6 +3387,10 @@ const formatConfigError = (err) => {
 };
 const runInit = (dir, options) => {
 	const outPath = join(dir, CONFIG_FILENAME);
+	if (options.scope !== void 0 && options.scope !== "shell" && options.scope !== "exec") {
+		console.error(`${RED}Error:${RESET} --scope must be "shell" or "exec" (got "${options.scope}")`);
+		process.exit(1);
+	}
 	if (existsSync(outPath) && !options.force) {
 		console.error(`${RED}Error:${RESET} ${CONFIG_FILENAME} already exists. Use --force to overwrite.`);
 		process.exit(1);
@@ -3958,6 +4100,34 @@ const applySealedToml = (raw, sealedMeta) => {
 	};
 	return flushPending(List(lines).zipWithIndex().foldLeft(initial)((state, entry) => step(state, entry[0], entry[1]))).output.join("\n");
 };
+/** Affirmative answer to a `[y/N]` confirm prompt. */
+const isAffirmative = (answer) => /^y(es)?$/i.test(answer.trim());
+/**
+* Collect new plaintext values for the `--edit`ed keys via the injected `prompt`. Before
+* overwriting an entry that is **already sealed** (`encrypted_value` present), require an
+* explicit confirmation — replacing it discards the only ciphertext, and the prior value
+* can't be recovered without the original key. Declined or empty entries are skipped (reported
+* via `onSkip`). I/O flows only through `prompt`/`onSkip`, so the confirm/skip logic is
+* unit-testable without a TTY.
+*/
+const collectEditedValues = async (editKeys, entries, prompt, onSkip) => {
+	const values = {};
+	for (const key of editKeys) {
+		if (entries[key]?.encrypted_value) {
+			if (!isAffirmative(await prompt(`Replace the sealed value for ${key}? The previous value can't be recovered without the original key. [y/N] `))) {
+				onSkip?.(key, "declined");
+				continue;
+			}
+		}
+		const value = await prompt(`Enter new value for ${key}: `);
+		if (value === "") {
+			onSkip?.(key, "empty");
+			continue;
+		}
+		values[key] = value;
+	}
+	return values;
+};
 /** Write sealed values back into the TOML file, preserving structure. */
 const writeSealedToml = (configPath, sealedMeta) => {
 	const finalContent = applySealedToml(readFileSync(configPath, "utf-8"), sealedMeta);
@@ -4034,15 +4204,9 @@ const runSeal = async (options) => {
 		const prompt = (question) => new Promise((resolve) => {
 			rl.question(question, (answer) => resolve(answer));
 		});
-		const values = {};
-		for (const key of editKeys) {
-			const value = await prompt(`Enter new value for ${key}: `);
-			if (value === "") {
-				console.error(`${YELLOW}Skipped${RESET} ${key} (empty value)`);
-				continue;
-			}
-			values[key] = value;
-		}
+		const values = await collectEditedValues(editKeys, secretEntries, prompt, (key, reason) => {
+			console.error(`${YELLOW}Skipped${RESET} ${key} (${reason === "empty" ? "empty value" : "kept existing sealed value"})`);
+		});
 		rl.close();
 		if (Object.keys(values).length === 0) {
 			console.error(`${RED}Error:${RESET} No values provided`);
@@ -4129,6 +4293,27 @@ const runSeal = async (options) => {
 };
 //#endregion
 //#region src/cli/commands/secret.ts
+/**
+* Fields removable via `--unset` — exactly the metadata fields settable via a flag.
+* Mental model: you can unset any field you can set. Structural/managed fields
+* (`created`, `last_rotated_at`, `encrypted_value`, `from_key`, `namespace`) are
+* intentionally excluded — they're owned by `seal`/`rotate`/`alias`, not `edit`.
+* Field names are the canonical TOML keys (e.g. `rate_limit`, not `rate-limit`).
+*/
+const UNSETTABLE_FIELDS = [
+	"service",
+	"purpose",
+	"comment",
+	"expires",
+	"rotates",
+	"rate_limit",
+	"model_hint",
+	"source",
+	"rotation_url",
+	"required",
+	"capabilities",
+	"tags"
+];
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const buildSecretBlock = (name, options) => {
 	const lines = [`[secret.${name}]`];
@@ -4174,6 +4359,9 @@ const buildFieldUpdates = (options) => {
 		const [k, v] = pair.split("=").map((s) => s.trim());
 		return `${k} = "${v}"`;
 	}).join(", ")} }`;
+	options.unset?.forEach((field) => {
+		updates[field] = null;
+	});
 	return updates;
 };
 const withConfig = (configFlag, fn) => {
@@ -4206,12 +4394,12 @@ const runSecretAdd = (name, options) => {
 				process.exit(1);
 			}
 			const block = buildSecretBlock(name, options);
+			const updated = appendSection(readFileSync(configPath, "utf-8"), block);
 			if (options.dryRun) {
-				console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
-				console.log(block);
+				previewIfValid(updated, block);
 				return;
 			}
-			writeIfValid(configPath, appendSection(readFileSync(configPath, "utf-8"), block), `${GREEN}✓${RESET} Added ${BOLD}${name}${RESET} to ${CYAN}${configPath}${RESET}`);
+			writeIfValid(configPath, updated, `${GREEN}✓${RESET} Added ${BOLD}${name}${RESET} to ${CYAN}${configPath}${RESET}`);
 		});
 	});
 };
@@ -4220,6 +4408,12 @@ const runSecretEdit = (name, options) => {
 		console.error(`${RED}Error:${RESET} Invalid date format for --expires: "${options.expires}" (expected YYYY-MM-DD)`);
 		process.exit(1);
 	}
+	const unknownUnset = (options.unset ?? []).filter((f) => !UNSETTABLE_FIELDS.includes(f));
+	if (unknownUnset.length > 0) {
+		console.error(`${RED}Error:${RESET} Cannot --unset unknown field(s): ${unknownUnset.join(", ")}`);
+		console.error(`${DIM}Unsettable fields: ${UNSETTABLE_FIELDS.join(", ")}${RESET}`);
+		process.exit(1);
+	}
 	withConfig(Option(options.config), (configPath, raw) => {
 		loadConfig(configPath).fold((err) => {
 			console.error(formatError(err));
@@ -4239,8 +4433,7 @@ const runSecretEdit = (name, options) => {
 				process.exit(2);
 			}, (updated) => {
 				if (options.dryRun) {
-					console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
-					console.log(updated);
+					previewIfValid(updated);
 					return;
 				}
 				writeIfValid(configPath, updated, `${GREEN}✓${RESET} Updated ${BOLD}${name}${RESET} in ${CYAN}${configPath}${RESET}`);
@@ -4255,8 +4448,7 @@ const runSecretRm = (name, options) => {
 			process.exit(1);
 		}, (updated) => {
 			if (options.dryRun) {
-				console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
-				console.log(updated);
+				previewIfValid(updated);
 				return;
 			}
 			writeIfValid(configPath, updated, `${GREEN}✓${RESET} Removed ${BOLD}${name}${RESET} from ${CYAN}${configPath}${RESET}`);
@@ -4270,8 +4462,7 @@ const runSecretRename = (oldName, newName, options) => {
 			process.exit(1);
 		}, (updated) => {
 			if (options.dryRun) {
-				console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
-				console.log(updated);
+				previewIfValid(updated);
 				return;
 			}
 			writeIfValid(configPath, updated, `${GREEN}✓${RESET} Renamed ${BOLD}${oldName}${RESET} → ${BOLD}${newName}${RESET} in ${CYAN}${configPath}${RESET}`);
@@ -4404,8 +4595,7 @@ const runSecretRotate = async (name, options) => {
 			process.exit(2);
 		}, (result) => {
 			if (options.dryRun) {
-				console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
-				console.log(result);
+				previewIfValid(result);
 				return;
 			}
 			writeIfValid(configPath, result, `${GREEN}✓${RESET} Stamped ${BOLD}last_rotated_at${RESET} on ${BOLD}${name}${RESET} (unsealed — no ciphertext to update)`);
@@ -4433,8 +4623,7 @@ const runSecretRotate = async (name, options) => {
 		process.exit(2);
 	}, (result) => {
 		if (options.dryRun) {
-			console.log(`${DIM}# Preview (--dry-run):${RESET}\n`);
-			console.log(result);
+			previewIfValid(result);
 			return;
 		}
 		writeIfValid(configPath, result, `${GREEN}✓${RESET} Rotated ${BOLD}${name}${RESET} (resealed + stamped ${CYAN}${today}${RESET})`);
@@ -4446,7 +4635,8 @@ const registerSecretCommands = (program) => {
 	addSecretFlags(secret.command("add").description("Add a new secret entry to envpkt.toml").argument("<name>", "Secret name (becomes the env var key)").option("-c, --config <path>", "Path to envpkt.toml").option("--required", "Mark this secret as required").option("--dry-run", "Preview the TOML block without writing")).action((name, options) => {
 		runSecretAdd(name, options);
 	});
-	addSecretFlags(secret.command("edit").description("Update metadata fields on an existing secret").argument("<name>", "Secret name to edit").option("-c, --config <path>", "Path to envpkt.toml").option("--required", "Mark this secret as required").option("--no-required", "Mark this secret as not required").option("--dry-run", "Preview the changes without writing")).action((name, options) => {
+	const collect = (value, previous) => [...previous, value];
+	addSecretFlags(secret.command("edit").description("Update metadata fields on an existing secret").argument("<name>", "Secret name to edit").option("-c, --config <path>", "Path to envpkt.toml").option("--required", "Mark this secret as required").option("--no-required", "Mark this secret as not required").option("--unset <field>", "Remove an optional field (repeatable). Field names match TOML keys, e.g. expires, rate_limit", collect, []).option("--dry-run", "Preview the changes without writing")).action((name, options) => {
 		runSecretEdit(name, options);
 	});
 	secret.command("rm").description("Remove a secret entry from envpkt.toml").argument("<name>", "Secret name to remove").option("-c, --config <path>", "Path to envpkt.toml").option("--dry-run", "Preview the result without writing").action((name, options) => {
@@ -4464,39 +4654,96 @@ const registerSecretCommands = (program) => {
 };
 //#endregion
 //#region src/cli/commands/shell-hook.ts
-const ZSH_HOOK = `# envpkt shell hook — add to your .zshrc
-_envpkt_chpwd() {
-  envpkt audit --format minimal 2>/dev/null
-}
-
-if (( $+functions[add-zsh-hook] )); then
-  autoload -Uz add-zsh-hook
-  add-zsh-hook chpwd _envpkt_chpwd
-else
-  autoload -Uz add-zsh-hook
-  add-zsh-hook chpwd _envpkt_chpwd
-fi
-`;
-const BASH_HOOK = `# envpkt shell hook — add to your .bashrc
-_envpkt_last_dir=""
-_envpkt_prompt() {
-  if [[ "$PWD" != "$_envpkt_last_dir" ]]; then
-    _envpkt_last_dir="$PWD"
-    envpkt audit --format minimal 2>/dev/null
-  fi
-}
-
-if [[ ! "$PROMPT_COMMAND" == *"_envpkt_prompt"* ]]; then
-  PROMPT_COMMAND="_envpkt_prompt;$PROMPT_COMMAND"
-fi
-`;
-const runShellHook = (shell) => {
+const zshHook = (audit) => [
+	"# envpkt shell hook — add to ~/.zshrc:  eval \"$(envpkt shell-hook zsh)\"",
+	"# Loads the current directory package on cd, restores the prior env on leave, warns on health.",
+	"_envpkt_restore() {",
+	"  [[ -n \"$_ENVPKT_INJECTED\" ]] || return",
+	"  local k had prev",
+	"  for k in ${(s: :)_ENVPKT_INJECTED}; do",
+	"    had=\"_ENVPKT_HAD_$k\"",
+	"    prev=\"_ENVPKT_PREV_$k\"",
+	"    if [[ -n \"${(P)had}\" ]]; then",
+	"      export \"$k=${(P)prev}\"",
+	"    else",
+	"      unset \"$k\"",
+	"    fi",
+	"    unset \"$had\" \"$prev\"",
+	"  done",
+	"  unset _ENVPKT_INJECTED",
+	"}",
+	"",
+	"_envpkt_chpwd() {",
+	"  local cfg",
+	"  cfg=\"$(envpkt config-path 2>/dev/null)\"",
+	"  [[ \"$cfg\" == \"$_ENVPKT_DIR\" ]] && return",
+	"  _envpkt_restore",
+	"  _ENVPKT_DIR=\"$cfg\"",
+	"  [[ -z \"$cfg\" ]] && return",
+	"  eval \"$(envpkt env export --track)\"",
+	...audit ? ["  envpkt audit --format minimal 2>/dev/null"] : [],
+	"}",
+	"",
+	"autoload -Uz add-zsh-hook",
+	"add-zsh-hook chpwd _envpkt_chpwd",
+	"_envpkt_chpwd",
+	""
+].join("\n");
+const bashHook = (audit) => [
+	"# envpkt shell hook — add to ~/.bashrc:  eval \"$(envpkt shell-hook bash)\"",
+	"# Loads the current directory package on cd, restores the prior env on leave, warns on health.",
+	"_envpkt_restore() {",
+	"  [ -n \"$_ENVPKT_INJECTED\" ] || return",
+	"  local k had prev",
+	"  for k in $_ENVPKT_INJECTED; do",
+	"    had=\"_ENVPKT_HAD_$k\"",
+	"    prev=\"_ENVPKT_PREV_$k\"",
+	"    if [ -n \"${!had}\" ]; then",
+	"      export \"$k=${!prev}\"",
+	"    else",
+	"      unset \"$k\"",
+	"    fi",
+	"    unset \"$had\" \"$prev\"",
+	"  done",
+	"  unset _ENVPKT_INJECTED",
+	"}",
+	"",
+	"_envpkt_prompt() {",
+	"  [ \"$PWD\" = \"$_ENVPKT_PWD\" ] && return",
+	"  _ENVPKT_PWD=\"$PWD\"",
+	"  local cfg",
+	"  cfg=\"$(envpkt config-path 2>/dev/null)\"",
+	"  [ \"$cfg\" = \"$_ENVPKT_DIR\" ] && return",
+	"  _envpkt_restore",
+	"  _ENVPKT_DIR=\"$cfg\"",
+	"  [ -z \"$cfg\" ] && return",
+	"  eval \"$(envpkt env export --track)\"",
+	...audit ? ["  envpkt audit --format minimal 2>/dev/null"] : [],
+	"}",
+	"",
+	"# Register on PROMPT_COMMAND, handling both the string and (bash 5.1+) array forms.",
+	"if [[ \"$(declare -p PROMPT_COMMAND 2>/dev/null)\" == \"declare -a\"* ]]; then",
+	"  case \" ${PROMPT_COMMAND[*]} \" in",
+	"    *\" _envpkt_prompt \"*) ;;",
+	"    *) PROMPT_COMMAND+=(_envpkt_prompt) ;;",
+	"  esac",
+	"else",
+	"  case \"$PROMPT_COMMAND\" in",
+	"    *_envpkt_prompt*) ;;",
+	"    *) PROMPT_COMMAND=\"_envpkt_prompt${PROMPT_COMMAND:+;$PROMPT_COMMAND}\" ;;",
+	"  esac",
+	"fi",
+	"_envpkt_prompt",
+	""
+].join("\n");
+const runShellHook = (shell, options) => {
+	const audit = options?.audit !== false;
 	switch (shell) {
 		case "zsh":
-			console.log(ZSH_HOOK);
+			console.log(zshHook(audit));
 			break;
 		case "bash":
-			console.log(BASH_HOOK);
+			console.log(bashHook(audit));
 			break;
 		default:
 			console.error(`${RED}Error:${RESET} Unsupported shell: ${shell}. Use "zsh" or "bash".`);
@@ -4793,7 +5040,7 @@ program.name("envpkt").description("Credential lifecycle and fleet management fo
 	const pkgPath = findPkgJson(dirname(fileURLToPath(import.meta.url)));
 	return pkgPath ? JSON.parse(readFileSync(pkgPath, "utf-8")).version : "0.0.0";
 })());
-program.command("init").description("Initialize a new envpkt.toml in the current directory").option("--from-fnox [path]", "Scaffold from fnox.toml (optionally specify path)").option("--catalog <path>", "Path to shared secret catalog").option("--identity", "Include [identity] section").option("--name <name>", "Identity name (requires --identity)").option("--capabilities <caps>", "Comma-separated capabilities (requires --identity)").option("--expires <date>", "Credential expiration YYYY-MM-DD (requires --identity)").option("--force", "Overwrite existing envpkt.toml").action((options) => {
+program.command("init").description("Initialize a new envpkt.toml in the current directory").option("--from-fnox [path]", "Scaffold from fnox.toml (optionally specify path)").option("--catalog <path>", "Path to shared secret catalog").option("--identity", "Include [identity] section").option("--name <name>", "Identity name (requires --identity)").option("--capabilities <caps>", "Comma-separated capabilities (requires --identity)").option("--expires <date>", "Credential expiration YYYY-MM-DD (requires --identity)").option("--scope <scope>", "Top-level scope: \"shell\" (secrets load ambiently) or \"exec\" (only via envpkt exec)").option("--global", "Scaffold a global/ambient package (implies scope = \"shell\")").option("--force", "Overwrite existing envpkt.toml").action((options) => {
 	runInit(process.cwd(), options);
 });
 program.command("keygen").description("Generate an age keypair for sealing secrets — run this before `seal` if you don't have a key yet").option("-c, --config <path>", "Path to envpkt.toml (updates identity.recipient if found)").option("-o, --output <path>", "Output path for identity file (default: ~/.envpkt/<project>-key.txt)").option("--global", "Write key to the shared default path (~/.envpkt/age-key.txt) instead of a project-specific one").action((options) => {
@@ -4831,8 +5078,11 @@ program.command("sort").description("Group [env.*] and [secret.*] sections and a
 program.command("upgrade").description("Upgrade envpkt to the latest version (npm install -g envpkt@latest)").action(() => {
 	runUpgrade();
 });
-program.command("shell-hook").description("Output shell function for ambient credential warnings on cd — combine with env export for full setup").argument("<shell>", "Shell type: zsh | bash").action((shell) => {
-	runShellHook(shell);
+program.command("config-path").description("Print the envpkt.toml path resolved for the current directory (empty if none). Resolve-only — no decryption.").option("-c, --config <path>", "Path to envpkt.toml").action((options) => {
+	runConfigPath(options);
+});
+program.command("shell-hook").description("Output a shell hook that loads a project's credentials on cd and restores them on leave").argument("<shell>", "Shell type: zsh | bash").option("--no-audit", "Omit the credential-health audit line from the emitted hook").action((shell, options) => {
+	runShellHook(shell, options);
 });
 program.parse();
 //#endregion

package/dist/index.d.ts

@@ -78,6 +78,7 @@ type EnvMeta = Static<typeof EnvMetaSchema>;
 declare const EnvpktConfigSchema: import("@sinclair/typebox").TObject<{
   version: import("@sinclair/typebox").TNumber;
   catalog: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+  scope: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"shell">, import("@sinclair/typebox").TLiteral<"exec">]>>;
   namespace: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
     prefix: import("@sinclair/typebox").TString;
     separator: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -327,6 +328,10 @@ type BootError = ConfigError | FnoxError | CatalogError | AliasError | {
   readonly _tag: "AuditFailed";
   readonly audit: AuditResult;
   readonly message: string;
+} | {
+  readonly _tag: "SealKeyUnavailable";
+  readonly sealedKeys: ReadonlyArray<string>;
+  readonly searched: ReadonlyArray<string>;
 } | IdentityError;
 type IdentityError = {
   readonly _tag: "AgeNotFound";
@@ -389,7 +394,7 @@ type DiscoveredConfig = {
   readonly path: string;
   readonly source: "cwd" | "search";
 };
-/** Discover config by checking CWD, then ENVPKT_SEARCH_PATH, then dynamic Platform paths */
+/** Discover config by walking up from CWD, then ENVPKT_SEARCH_PATH, then dynamic Platform paths */
 declare const discoverConfig: (cwd?: string) => Option<DiscoveredConfig>;
 /** Read a config file, returning Either<ConfigError, string> */
 declare const readConfigFile: (path: string) => Either<ConfigError, string>;
@@ -549,6 +554,35 @@ declare const updateConfigIdentity: (configPath: string, options: UpdateIdentity
 /** Resolve plaintext values for the given keys via cascade: fnox → env → interactive prompt */
 declare const resolveValues: (keys: ReadonlyArray<string>, profile?: string, agentKey?: string) => Promise<Record<string, string>>;
 //#endregion
+//#region src/core/dotenv.d.ts
+/**
+ * Serialize resolved credential entries to `.env` (dotenv) format.
+ *
+ * Unlike `env export` (shell `export VAR=...` for `eval`) this emits the bare
+ * `KEY=value` syntax that the broad `.env`-consuming ecosystem auto-discovers:
+ * Wrangler, Docker `--env-file`, Vite/Next/Astro, many GitHub Actions, direnv.
+ *
+ * Pure and deterministic — no I/O, no timestamps — so regenerating a file
+ * produces identical output (clean diffs, reproducible CI).
+ */
+type DotenvEntry = {
+  readonly name: string;
+  readonly value: string;
+  readonly secret: boolean;
+};
+type FormatDotenvOptions = {
+  /** Write secret values into the output. Default true (matches `env export`/`env github`). */readonly includeSecrets?: boolean; /** A pre-formatted comment block (each line `#`-prefixed) placed at the top. */
+  readonly header?: string;
+};
+/**
+ * Quote a single value for dotenv output. Returns the value bare when safe,
+ * otherwise double-quoted with POSIX-shell-quote escaping (`\`, `"`, `$`) and
+ * whitespace collapsed to single-line escapes (`\n`, `\r`, `\t`) for portability.
+ */
+declare const quoteDotenvValue: (value: string) => string;
+/** Serialize entries to dotenv text (no trailing newline). */
+declare const formatDotenv: (entries: ReadonlyArray<DotenvEntry>, options?: FormatDotenvOptions) => string;
+//#endregion
 //#region src/core/toml-edit.d.ts
 /**
  * Remove a TOML section (e.g. `[secret.X]`) and all its fields through the next section or EOF.
@@ -634,4 +668,4 @@ type ToolDef = {
 declare const toolDefinitions: readonly ToolDef[];
 declare const callTool: (name: string, args: Record<string, unknown>) => CallToolResult;
 //#endregion
-export { type AgentIdentity, AgentIdentitySchema, type AliasError, type AliasTable, type AuditResult, type BootError, type BootOptions, type BootResult, type CallbackConfig, CallbackConfigSchema, type CatalogError, type CheckResult, type ConfidenceLevel, type ConfigError, type ConfigSource, ConsumerType, type CredentialPattern, type DirectLogger, type DirectTestLoggerHandle, type DriftEntry, type DriftStatus, type EnvAuditResult, type EnvDriftEntry, type EnvDriftStatus, type EnvMeta, EnvMetaSchema, EnvpktBootError, type EnvpktConfig, EnvpktConfigSchema, type FleetAgent, type FleetHealth, type FnoxConfig, type FnoxError, type FnoxSecret, type FormatPacketOptions, type HealthStatus, type Identity, type IdentityError, IdentitySchema, type KeygenError, type KeygenResult, type LifecycleConfig, LifecycleConfigSchema, type LogEntry, type LogLevel, type LogMetadata, type MatchResult, type ResolveOptions, type ResolveResult, type ResolvedPath, type ScanOptions, type ScanResult, type SealError, type SecretDisplay, type SecretHealth, type SecretMeta, SecretMetaSchema, type SecretStatus, type TomlEditError, type ToolsConfig, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };
+export { type AgentIdentity, AgentIdentitySchema, type AliasError, type AliasTable, type AuditResult, type BootError, type BootOptions, type BootResult, type CallbackConfig, CallbackConfigSchema, type CatalogError, type CheckResult, type ConfidenceLevel, type ConfigError, type ConfigSource, ConsumerType, type CredentialPattern, type DirectLogger, type DirectTestLoggerHandle, type DotenvEntry, type DriftEntry, type DriftStatus, type EnvAuditResult, type EnvDriftEntry, type EnvDriftStatus, type EnvMeta, EnvMetaSchema, EnvpktBootError, type EnvpktConfig, EnvpktConfigSchema, type FleetAgent, type FleetHealth, type FnoxConfig, type FnoxError, type FnoxSecret, type FormatDotenvOptions, type FormatPacketOptions, type HealthStatus, type Identity, type IdentityError, IdentitySchema, type KeygenError, type KeygenResult, type LifecycleConfig, LifecycleConfigSchema, type LogEntry, type LogLevel, type LogMetadata, type MatchResult, type ResolveOptions, type ResolveResult, type ResolvedPath, type ScanOptions, type ScanResult, type SealError, type SecretDisplay, type SecretHealth, type SecretMeta, SecretMetaSchema, type SecretStatus, type TomlEditError, type ToolsConfig, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatDotenv, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, quoteDotenvValue, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };

package/dist/index.js

@@ -111,6 +111,7 @@ const EnvpktConfigSchema = Type.Object({
 		default: 1
 	}),
 	catalog: Type.Optional(Type.String({ description: "Path to shared secret catalog (relative to this config file)" })),
+	scope: Type.Optional(Type.Union([Type.Literal("shell"), Type.Literal("exec")], { description: "Whether `env export` emits this package's secrets for ambient/shell loading (`shell`) or withholds them so they are only available via `envpkt exec` (`exec`). Default `exec`. Never affects `envpkt exec`, which always injects everything." })),
 	namespace: Type.Optional(NamespaceSchema),
 	identity: Type.Optional(IdentitySchema),
 	secret: Type.Optional(Type.Record(Type.String(), SecretMetaSchema, { description: "Per-secret metadata keyed by secret name" })),
@@ -182,11 +183,24 @@ const buildSearchPaths = () => {
 	const cloudPaths = Platform.cloudStorageDirs().toArray().map((cloud) => join(cloud.path, ".envpkt", CONFIG_FILENAME$1));
 	return [...homePaths, ...cloudPaths];
 };
-/** Discover config by checking CWD, then ENVPKT_SEARCH_PATH, then dynamic Platform paths */
+/**
+* Walk up from `dir` to the filesystem root, returning the nearest `envpkt.toml`.
+* Makes a project's config apply throughout its subtree (like git/.env/direnv finding
+* their root file), not only in the directory that literally contains the file.
+* The global package lives in `~/.envpkt/` (a subdir), so it is not matched by this
+* walk — it is resolved by the search-path/Platform fallback below.
+*/
+const walkUpForConfig = (dir) => {
+	const candidate = join(dir, CONFIG_FILENAME$1);
+	if (Fs.existsSync(candidate)) return Option(candidate);
+	const parent = dirname(dir);
+	return parent === dir ? Option(void 0) : walkUpForConfig(parent);
+};
+/** Discover config by walking up from CWD, then ENVPKT_SEARCH_PATH, then dynamic Platform paths */
 const discoverConfig = (cwd) => {
-	const cwdCandidate = join(cwd ?? process.cwd(), CONFIG_FILENAME$1);
-	if (Fs.existsSync(cwdCandidate)) return Option({
-		path: cwdCandidate,
+	const walked = walkUpForConfig(cwd ?? process.cwd()).orUndefined();
+	if (walked) return Option({
+		path: walked,
 		source: "cwd"
 	});
 	const customMatch = Env.get("ENVPKT_SEARCH_PATH").fold(() => [], (v) => v.split(":").filter(Boolean)).map((template) => ({
@@ -1949,10 +1963,13 @@ const materializeInlineKey = (key) => {
 * the caller must dispose().
 */
 const resolveSealIdentity = (config, configDir) => {
-	if (config.identity?.key_file) return Option({
-		path: resolve(configDir, expandPath(config.identity.key_file)),
-		dispose: noop
-	});
+	if (config.identity?.key_file) {
+		const keyFilePath = resolve(configDir, expandPath(config.identity.key_file));
+		if (existsSync(keyFilePath)) return Option({
+			path: keyFilePath,
+			dispose: noop
+		});
+	}
 	const envFile = process.env["ENVPKT_AGE_KEY_FILE"];
 	if (envFile && existsSync(envFile)) return Option({
 		path: envFile,
@@ -1967,6 +1984,21 @@ const resolveSealIdentity = (config, configDir) => {
 	});
 	return Option(void 0);
 };
+/** Describe the seal-identity precedence chain with per-entry status, for a clear no-key error. */
+const describeSealKeySearch = (config, configDir) => {
+	const keyFile = config.identity?.key_file;
+	const keyFileLine = keyFile ? `identity.key_file → ${resolve(configDir, expandPath(keyFile))} (${existsSync(resolve(configDir, expandPath(keyFile))) ? "found" : "missing"})` : `identity.key_file (not set)`;
+	const envFile = process.env["ENVPKT_AGE_KEY_FILE"];
+	const envFileLine = envFile ? `ENVPKT_AGE_KEY_FILE → ${envFile} (${existsSync(envFile) ? "found" : "missing"})` : `ENVPKT_AGE_KEY_FILE (unset)`;
+	const inlineLine = resolveInlineKey().isEmpty ? `ENVPKT_AGE_KEY (unset)` : `ENVPKT_AGE_KEY (set, inline)`;
+	const defaultPath = join(homedir(), ".envpkt", "age-key.txt");
+	return [
+		keyFileLine,
+		envFileLine,
+		inlineLine,
+		`${defaultPath} (${existsSync(defaultPath) ? "found" : "missing"})`
+	];
+};
 const resolveIdentityKey = (config, configDir) => {
 	return resolveIdentityFilePath(config, configDir, false).fold(() => Right(Option(void 0)), (path) => unwrapAgentKey(path).fold((err) => Left(err), (key) => Right(Option(key))));
 };
@@ -2036,6 +2068,12 @@ const bootSafe = (options) => {
 			message: "unexpected"
 		}));
 		const audit = computeAudit(config, detectFnoxKeys(configDir), void 0, aliasTable);
+		const sealIdentity = hasSealedValues ? resolveSealIdentity(config, configDir) : Option(void 0);
+		if (hasSealedValues && sealIdentity.isEmpty) return Left({
+			_tag: "SealKeyUnavailable",
+			sealedKeys: nonAliasMetaKeys.filter((k) => !!nonAliasSecretEntries[k]?.encrypted_value),
+			searched: describeSealKeySearch(config, configDir)
+		});
 		return checkExpiration(audit, failOnExpired, warnOnly).map((warnings) => {
 			const secrets = {};
 			const injected = [];
@@ -2049,9 +2087,8 @@ const bootSafe = (options) => {
 				process.env[envEnv(key)] = value;
 			});
 			const sealedKeys = /* @__PURE__ */ new Set();
-			if (hasSealedValues) resolveSealIdentity(config, configDir).fold(() => {
+			if (hasSealedValues) sealIdentity.fold(() => {
 				log.warn("phase.sealed.no_identity_file", { sealed_keys: nonAliasMetaKeys.filter((k) => !!nonAliasSecretEntries[k]?.encrypted_value).length });
-				warnings.push("Sealed values found but no identity file available for decryption");
 			}, ({ path: idPath, dispose }) => {
 				try {
 					unsealSecrets(nonAliasSecretEntries, idPath).fold((err) => {
@@ -2185,6 +2222,19 @@ const formatBootError = (error) => {
 		case "AgeNotFound": return `age not found: ${error.message}`;
 		case "DecryptFailed": return `Decrypt failed: ${error.message}`;
 		case "IdentityNotFound": return `Identity file not found: ${error.path}`;
+		case "SealKeyUnavailable": {
+			const keys = error.sealedKeys.length;
+			const searched = error.searched.map((line) => `  • ${line}`).join("\n");
+			return [
+				`${keys} sealed secret(s) can't be decrypted — no age key found.`,
+				`Searched (in order):`,
+				searched,
+				`Fix one:`,
+				`  • Restore your key to ~/.envpkt/age-key.txt (or set ENVPKT_AGE_KEY_FILE / ENVPKT_AGE_KEY)`,
+				`  • Re-provision from source: envpkt seal --edit <KEY>`,
+				`Refusing to inject empty values for sealed secrets.`
+			].join("\n");
+		}
 		case "AliasInvalidSyntax":
 		case "AliasTargetMissing":
 		case "AliasSelfReference":
@@ -2232,6 +2282,30 @@ const resolveValues = async (keys, profile, agentKey) => {
 	return result;
 };
 //#endregion
+//#region src/core/dotenv.ts
+const BARE_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+/**
+* Quote a single value for dotenv output. Returns the value bare when safe,
+* otherwise double-quoted with POSIX-shell-quote escaping (`\`, `"`, `$`) and
+* whitespace collapsed to single-line escapes (`\n`, `\r`, `\t`) for portability.
+*/
+const quoteDotenvValue = (value) => {
+	if (value === "") return "";
+	if (BARE_SAFE.test(value)) return value;
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\$/g, "\\$").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")}"`;
+};
+const formatEntry = (entry, includeSecrets) => {
+	if (entry.secret && !includeSecrets) return `# (secret value omitted — re-run without --no-secrets to include)\n${entry.name}=`;
+	return `${entry.name}=${quoteDotenvValue(entry.value)}`;
+};
+/** Serialize entries to dotenv text (no trailing newline). */
+const formatDotenv = (entries, options) => {
+	const includeSecrets = options?.includeSecrets ?? true;
+	const body = entries.map((e) => formatEntry(e, includeSecrets)).join("\n");
+	const header = options?.header;
+	return header ? `${header}\n\n${body}` : body;
+};
+//#endregion
 //#region src/core/toml-edit.ts
 const SECTION_RE = /^\[.+\]\s*$/;
 const MULTILINE_OPEN = "\"\"\"";
@@ -2730,4 +2804,4 @@ const startServer = async () => {
 	await server.connect(transport);
 };
 //#endregion
-export { AgentIdentitySchema, CallbackConfigSchema, ConsumerType, EnvMetaSchema, EnvpktBootError, EnvpktConfigSchema, IdentitySchema, LifecycleConfigSchema, SecretMetaSchema, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };
+export { AgentIdentitySchema, CallbackConfigSchema, ConsumerType, EnvMetaSchema, EnvpktBootError, EnvpktConfigSchema, IdentitySchema, LifecycleConfigSchema, SecretMetaSchema, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatDotenv, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, quoteDotenvValue, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envpkt",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Credential lifecycle and fleet management for AI agents",
   "keywords": [
     "credentials",

package/schemas/envpkt.schema.json

@@ -17,6 +17,19 @@
       "description": "Path to shared secret catalog (relative to this config file)",
       "type": "string"
     },
+    "scope": {
+      "description": "Whether `env export` emits this package's secrets for ambient/shell loading (`shell`) or withholds them so they are only available via `envpkt exec` (`exec`). Default `exec`. Never affects `envpkt exec`, which always injects everything.",
+      "anyOf": [
+        {
+          "const": "shell",
+          "type": "string"
+        },
+        {
+          "const": "exec",
+          "type": "string"
+        }
+      ]
+    },
     "namespace": {
       "description": "Optional namespace/package prefix for injected environment variable names",
       "type": "object",