envpkt 0.13.0 → 0.13.2

package/README.md

@@ -5,43 +5,38 @@
 
 **Credentials your agents actually understand.**
 
-Structured metadata for every secret — capabilities, constraints, expiration, and fleet health — so agents operate within their boundaries instead of flying blind.
+envpkt gives every credential an `envpkt.toml` entry describing _what service it authenticates to_, _what it's allowed to do_, _when it expires_, and _how to rotate it_ — while the secret values stay in your secrets manager, encrypted at rest, or injected at runtime, never committed in plaintext.
 
-Every credential in your system gets an `envpkt.toml` entry describing _what service it authenticates to_, _what it's allowed to do_, _when it expires_, and _how to rotate it_. Your agents query this metadata via MCP to understand their operating constraints. Your operators audit credential health across entire agent fleets. The secrets themselves stay where they belong — in your secrets manager, encrypted at rest, or injected at runtime — never in the agent's conversation context.
+**Day one, with zero agents,** it's an encrypted-at-rest `.env` replacement with scoped loading: scan the credentials already in your shell, seal them into a file that's safe to commit, and load them automatically on `cd`, into a single command, or as a plain `.env` for any tool that wants one.
 
-## MCP Integration
+**As you add agents,** the same metadata gives them structured awareness of their own credentials over [MCP](#for-agents-and-fleets) — capabilities, expiry, drift, fleet health — without any secret value ever entering the model's context window.
 
-envpkt ships an [MCP](https://modelcontextprotocol.io/) server that gives AI agents structured awareness of their credentials. Add it to Claude, Cursor, VS Code, or any MCP-compatible client:
+## Quick Start
 
-```json
-{
-  "mcpServers": {
-    "envpkt": {
-      "command": "envpkt",
-      "args": ["mcp"]
-    }
-  }
-}
-```
+The whole loop for a single project — discover, seal, load — with zero agents involved:
 
-### Tools
+```bash
+npm install -g envpkt
 
-| Tool               | Description                                             |
-| ------------------ | ------------------------------------------------------- |
-| `getPacketHealth`  | Get overall health status with per-secret audit results |
-| `listCapabilities` | List agent and per-secret capabilities                  |
-| `getSecretMeta`    | Get metadata for a specific secret by key               |
-| `checkExpiration`  | Check expiration status and days remaining              |
-| `getEnvMeta`       | Get metadata for environment defaults and drift status  |
+# 1. Discover the credentials already in your shell, and scaffold envpkt.toml from them
+envpkt env scan
+envpkt env scan --write
 
-### Resources
+# 2. Generate an age key and seal the secret values into envpkt.toml (the file is safe to commit)
+envpkt keygen
+envpkt seal
 
-| URI                     | Description                       |
-| ----------------------- | --------------------------------- |
-| `envpkt://health`       | Current credential health summary |
-| `envpkt://capabilities` | Agent and secret capabilities     |
+# 3. Load them — pick whatever fits the moment:
+envpkt exec -- your-tool            # run one command with the secrets injected, scoped to it
+eval "$(envpkt shell-hook zsh)"     # add to ~/.zshrc: auto-load on cd into a project, restore on leave
+envpkt env dotenv -o .env           # materialize a .env for Docker / Wrangler / Vite / …
+
+# Anytime: check health and drift
+envpkt audit
+envpkt env check
+```
 
-The MCP server exposes metadata only — it does not have access to secret values. See [Security Model](#security-model) for details.
+Encrypted secrets committed to git, loaded where you need them, with health you can audit — and not an agent in sight. Scaling the same metadata to agents and fleets is [act two](#for-agents-and-fleets).
 
 ## Security Model
 
@@ -53,30 +48,6 @@ envpkt operates a three-tier trust model. Each tier has different guarantees, an
 
 **Tier 3: Shell-level agents** — Agents with shell access (Claude Code, Devin, etc.) can read environment variables directly. Prevention isn't possible at this tier. envpkt provides encrypted storage, scoped access, and audit trails — because when prevention isn't possible, visibility is what matters.
 
-## Quick Start
-
-Start where your credentials already are — environment variables — and graduate to encrypted, per-agent-scoped metadata.
-
-```bash
-# Install
-npm install -g envpkt
-
-# Auto-discover credentials from your shell environment
-envpkt env scan
-
-# Scaffold envpkt.toml from discovered credentials
-envpkt env scan --write
-
-# Audit credential health
-envpkt audit
-
-# Check for drift between envpkt.toml and live environment
-envpkt env check
-
-# Scan a directory tree of agents
-envpkt fleet
-```
-
 ## The envpkt.toml File
 
 Every project gets one `envpkt.toml` that describes its credentials. Here's a minimal example:
@@ -236,6 +207,44 @@ A composite action resolves the credentials in `envpkt.toml` into the CI job —
 
 > 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.
 
+## For agents and fleets
+
+Everything above stands on its own with no agents involved. Once you _do_ have them, the same `envpkt.toml` metadata powers three more capabilities: agents reading their own constraints over MCP, fleet-wide health monitoring, and shared catalogs across many agents.
+
+### MCP server
+
+envpkt ships an [MCP](https://modelcontextprotocol.io/) server that gives AI agents structured awareness of their credentials. Add it to Claude, Cursor, VS Code, or any MCP-compatible client:
+
+```json
+{
+  "mcpServers": {
+    "envpkt": {
+      "command": "envpkt",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**Tools**
+
+| Tool               | Description                                             |
+| ------------------ | ------------------------------------------------------- |
+| `getPacketHealth`  | Get overall health status with per-secret audit results |
+| `listCapabilities` | List agent and per-secret capabilities                  |
+| `getSecretMeta`    | Get metadata for a specific secret by key               |
+| `checkExpiration`  | Check expiration status and days remaining              |
+| `getEnvMeta`       | Get metadata for environment defaults and drift status  |
+
+**Resources**
+
+| URI                     | Description                       |
+| ----------------------- | --------------------------------- |
+| `envpkt://health`       | Current credential health summary |
+| `envpkt://capabilities` | Agent and secret capabilities     |
+
+The MCP server exposes metadata only — it reads `envpkt.toml` and strips any `encrypted_value` ciphertext from responses, so prompt injection cannot leak what isn't there. See [Security Model](#security-model) for the full trust model.
+
 ## 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.
@@ -355,6 +364,19 @@ envpkt audit -c path/to/envpkt.toml # Specify config path
 
 Exit codes: `0` = healthy, `1` = degraded, `2` = critical.
 
+### `envpkt doctor`
+
+One-shot environment check: is the `age` CLI installed, is a config resolvable here, and do its sealed secrets decrypt with an available key?
+
+```bash
+envpkt doctor
+# ✓ age      v1.2.0
+# ✓ config   /path/to/envpkt.toml
+# ✓ secrets  5 resolved, 0 skipped
+```
+
+If `age` is missing it prints the platform-specific install command; if a sealed packet has no key, it lists the paths it searched. Exits non-zero when a check fails.
+
 ### `envpkt resolve`
 
 Resolve catalog references and output a flat, self-contained config.
@@ -470,7 +492,8 @@ Secret values are emitted **only when the package sets top-level `scope = "shell
 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)
+eval "$(envpkt shell-hook zsh)"             # add to ~/.zshrc (or: shell-hook bash)
+eval "$(envpkt shell-hook zsh --no-audit)"  # …without the per-cd health-check line
 ```
 
 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).
@@ -486,18 +509,6 @@ Inject resolved secrets into a GitHub Actions job. Emits `::add-mask::` for each
 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`.
-
-```bash
-# Add to your .zshrc
-eval "$(envpkt shell-hook zsh)"
-
-# Add to your .bashrc
-eval "$(envpkt shell-hook bash)"
-```
-
 ### `envpkt mcp`
 
 Start the envpkt MCP server (stdio transport) for AI agent integration.

package/dist/cli.js

@@ -8,10 +8,10 @@ import { TypeCompiler } from "@sinclair/typebox/compiler";
 import { Env, Fs, Path, Platform } from "functype-os";
 import { TomlDate, parse, stringify } from "smol-toml";
 import { FormatRegistry, Type } from "@sinclair/typebox";
-import { randomBytes } from "node:crypto";
+import { execFileSync } from "node:child_process";
 import { homedir, tmpdir } from "node:os";
 import { directSilentLogger } from "functype-log/direct";
-import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -557,6 +557,63 @@ const resolveConfig = (agentConfig, agentConfigDir) => {
 	}));
 };
 //#endregion
+//#region src/fnox/identity.ts
+/** Check if the age CLI is available on PATH */
+const ageAvailable = () => Try(() => {
+	execFileSync("age", ["--version"], { stdio: "pipe" });
+	return true;
+}).fold(() => false, (v) => v);
+/** The age CLI version string (e.g. "v1.2.0"), or None if age isn't on PATH. */
+const ageVersion = () => Try(() => execFileSync("age", ["--version"], {
+	stdio: [
+		"pipe",
+		"pipe",
+		"pipe"
+	],
+	encoding: "utf-8"
+}).trim()).fold(() => Option.none(), (v) => Option(v));
+/** Platform-aware instructions for installing the age CLI. */
+const ageInstallHint = () => {
+	return `Install age:\n    ${{
+		darwin: "brew install age",
+		linux: "apt install age   (or: apk add age · dnf install age · nix-env -iA nixpkgs.age)",
+		win32: "scoop install age   (or: winget install FiloSottile.age)"
+	}[process.platform] ?? "see the install guide"}\n    https://github.com/FiloSottile/age#installation`;
+};
+/**
+* Extract the secret key from an age identity file (plain or encrypted).
+* - Plain identity files (from `age-keygen`) contain `AGE-SECRET-KEY-*` lines directly
+* - Encrypted identity files need `age --decrypt` to unwrap
+*/
+const unwrapAgentKey = (identityPath) => {
+	if (!existsSync(identityPath)) return Left({
+		_tag: "IdentityNotFound",
+		path: identityPath
+	});
+	return Try(() => readFileSync(identityPath, "utf-8")).fold((err) => Left({
+		_tag: "DecryptFailed",
+		message: `Failed to read identity file: ${err}`
+	}), (content) => {
+		const secretKeyLine = content.split("\n").find((l) => l.startsWith("AGE-SECRET-KEY-"));
+		if (secretKeyLine) return Right(secretKeyLine.trim());
+		if (!ageAvailable()) return Left({
+			_tag: "AgeNotFound",
+			message: "age CLI not found on PATH"
+		});
+		return Try(() => execFileSync("age", ["--decrypt", identityPath], {
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			encoding: "utf-8"
+		})).fold((err) => Left({
+			_tag: "DecryptFailed",
+			message: `age decrypt failed: ${err}`
+		}), (output) => Right(output.trim()));
+	});
+};
+//#endregion
 //#region src/cli/output.ts
 const RESET = "\x1B[0m";
 const BOLD = "\x1B[1m";
@@ -659,9 +716,20 @@ const formatError = (error) => {
 		case "ParseError": return `${RED}Error:${RESET} Failed to parse TOML: ${error.message}`;
 		case "ValidationError": return `${RED}Error:${RESET} Config validation failed:\n${String(error.errors)}`;
 		case "ReadError": return `${RED}Error:${RESET} Could not read file: ${error.message}`;
-		case "AgeNotFound": return `${RED}Error:${RESET} age CLI not found: ${error.message}`;
+		case "AgeNotFound": return `${RED}Error:${RESET} age is required for this operation but was not found on PATH.\n${DIM}${ageInstallHint()}${RESET}`;
 		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}`;
@@ -907,46 +975,6 @@ const fnoxAvailable = () => Try(() => {
 	return true;
 }).fold(() => false, (v) => v);
 //#endregion
-//#region src/fnox/identity.ts
-/** Check if the age CLI is available on PATH */
-const ageAvailable = () => Try(() => {
-	execFileSync("age", ["--version"], { stdio: "pipe" });
-	return true;
-}).fold(() => false, (v) => v);
-/**
-* Extract the secret key from an age identity file (plain or encrypted).
-* - Plain identity files (from `age-keygen`) contain `AGE-SECRET-KEY-*` lines directly
-* - Encrypted identity files need `age --decrypt` to unwrap
-*/
-const unwrapAgentKey = (identityPath) => {
-	if (!existsSync(identityPath)) return Left({
-		_tag: "IdentityNotFound",
-		path: identityPath
-	});
-	return Try(() => readFileSync(identityPath, "utf-8")).fold((err) => Left({
-		_tag: "DecryptFailed",
-		message: `Failed to read identity file: ${err}`
-	}), (content) => {
-		const secretKeyLine = content.split("\n").find((l) => l.startsWith("AGE-SECRET-KEY-"));
-		if (secretKeyLine) return Right(secretKeyLine.trim());
-		if (!ageAvailable()) return Left({
-			_tag: "AgeNotFound",
-			message: "age CLI not found on PATH"
-		});
-		return Try(() => execFileSync("age", ["--decrypt", identityPath], {
-			stdio: [
-				"pipe",
-				"pipe",
-				"pipe"
-			],
-			encoding: "utf-8"
-		})).fold((err) => Left({
-			_tag: "DecryptFailed",
-			message: `age decrypt failed: ${err}`
-		}), (output) => Right(output.trim()));
-	});
-};
-//#endregion
 //#region src/fnox/parse.ts
 /** Read and parse fnox.toml, extracting secret keys and profiles */
 const readFnoxConfig = (path) => Try(() => readFileSync(path, "utf-8")).fold((err) => Left({
@@ -1583,6 +1611,57 @@ const bootSafe = (options) => {
 	}));
 };
 //#endregion
+//#region src/cli/commands/doctor.ts
+const ok = (label, detail) => console.log(`  ${GREEN}✓${RESET} ${label}  ${DIM}${detail}${RESET}`);
+const warn = (label, detail) => console.log(`  ${YELLOW}—${RESET} ${label}  ${detail}`);
+const bad = (label, detail) => console.log(`  ${RED}✗${RESET} ${label}  ${detail}`);
+/** Print the resolution/key check, returning whether it passed. */
+const reportResolution = (configPath) => bootSafe({
+	configPath,
+	inject: false,
+	warnOnly: true
+}).fold((err) => {
+	if (err._tag === "SealKeyUnavailable") {
+		bad("key   ", `${err.sealedKeys.length} sealed secret(s) but no decryption key`);
+		err.searched.forEach((line) => console.log(`${DIM}        ${line}${RESET}`));
+	} else bad("config", `${err._tag}`);
+	return false;
+}, (boot) => {
+	const resolved = Object.keys(boot.secrets).length;
+	ok("secrets", `${resolved} resolved, ${boot.skipped.length} skipped`);
+	const auditColor = boot.audit.status === "healthy" ? GREEN : YELLOW;
+	console.log(`  ${auditColor}•${RESET} audit   ${DIM}${boot.audit.status}${RESET}`);
+	return true;
+});
+/**
+* One-shot environment check: is age installed, is a config resolvable, and do its sealed
+* secrets decrypt with an available key? Read-only; exits non-zero if any check fails.
+*/
+const runDoctor = (options) => {
+	console.log(`${BOLD}envpkt doctor${RESET}\n`);
+	const ageOk = ageVersion().fold(() => {
+		bad("age   ", "not found on PATH");
+		console.log(`${DIM}        ${ageInstallHint().split("\n").join("\n        ")}${RESET}`);
+		return false;
+	}, (version) => {
+		ok("age   ", version);
+		return true;
+	});
+	const resolveOk = resolveConfigPath(options.config).fold(() => {
+		warn("config", "no envpkt.toml found for this directory");
+		return true;
+	}, ({ path }) => {
+		ok("config", path);
+		return reportResolution(path);
+	});
+	console.log("");
+	if (ageOk && resolveOk) console.log(`${GREEN}✓ no issues${RESET}`);
+	else {
+		console.log(`${RED}✗ ${[!ageOk, !resolveOk].filter(Boolean).length} issue(s) found${RESET} ${CYAN}(see above)${RESET}`);
+		process.exit(1);
+	}
+};
+//#endregion
 //#region src/core/dotenv.ts
 const BARE_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
 /**
@@ -2886,12 +2965,11 @@ const runEnvExport = (options) => {
 		console.error(formatError(err));
 		process.exit(2);
 	}, (boot) => {
-		emitWarnings(boot);
+		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 = scope === "shell" ? entries : entries.filter((e) => !e.secret);
-		const withheld = entries.length - emit.length;
-		if (withheld > 0) console.error(`${DIM}${withheld} secret(s) withheld (scope="${scope}") — use \`envpkt exec\` or set top-level scope="shell".${RESET}`);
+		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)}'`);
 		});
@@ -3291,6 +3369,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}]
@@ -3315,6 +3395,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}"`);
@@ -3373,6 +3455,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);
@@ -4636,85 +4722,96 @@ const registerSecretCommands = (program) => {
 };
 //#endregion
 //#region src/cli/commands/shell-hook.ts
-const ZSH_HOOK = `# envpkt shell hook — add to ~/.zshrc:  eval "$(envpkt shell-hook zsh)"
-# Loads a project envpkt.toml on cd (secrets only for scope="shell" packages), restores the
-# prior environment on leave, and warns on credential health. Use \`envpkt exec\` for scope="exec".
-_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 2>/dev/null)"
-  envpkt audit --format minimal 2>/dev/null
-}
-
-autoload -Uz add-zsh-hook
-add-zsh-hook chpwd _envpkt_chpwd
-_envpkt_chpwd
-`;
-const BASH_HOOK = `# envpkt shell hook — add to ~/.bashrc:  eval "$(envpkt shell-hook bash)"
-# Loads a project envpkt.toml on cd (secrets only for scope="shell" packages), restores the
-# prior environment on leave, and warns on credential health. Use \`envpkt exec\` for scope="exec".
-_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 2>/dev/null)"
-  envpkt audit --format minimal 2>/dev/null
-}
-
-case "$PROMPT_COMMAND" in
-  *_envpkt_prompt*) ;;
-  *) PROMPT_COMMAND="_envpkt_prompt\${PROMPT_COMMAND:+;$PROMPT_COMMAND}" ;;
-esac
-_envpkt_prompt
-`;
-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".`);
@@ -5011,7 +5108,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) => {
@@ -5049,11 +5146,14 @@ 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("doctor").description("Check that age is installed and that the resolved config's sealed secrets can be decrypted").option("-c, --config <path>", "Path to envpkt.toml").action((options) => {
+	runDoctor(options);
+});
 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 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("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/package.json

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