Add a global e-stack config + secrets file that all skills read from

[ElliotDrel]

Problem

There is no single place to store e-stack configuration or API keys. Today each skill invents its own storage, and none of it is clearly safe across updates.

Concretely, hit while using estack-pdf-to-md:

1. Per-skill .env files live inside the skill folder, which is a symlink into ~/.agents/skills/<skill>/. That directory is managed by the elliot-stack npm installer (npx elliot-stack@latest --startup, run from ~/.agents/hooks/estack-startup-update-core.js) and tracked by ~/.claude/.estack-checksums.json. It is not a git repo and there is no .gitignore, so there is no visible guarantee that a user-created .env survives an update. A user should not have to read the installer source to know whether their API key is about to get wiped.

2. The fallback (a Windows user env var) goes stale silently. PULSE_API_KEY was set as a Windows user env var. The startup check happily reported [OK] with a masked key, then every RunPulse request came back 401 UNAUTHORIZED. The check only verifies a key is present, never that it works, and there's no single place to go correct it.

3. Keys end up scattered. Skill-local .env, Windows user env var, shell env var, and (in this session) a temporary file that had to be created and then deleted by hand just to get one conversion done.

Proposed fix

One global e-stack config file — something like ~/.agents/estack.config.json or ~/.estack/config.env — that:

• Lives outside the installer-managed skill tree, or is explicitly declared as preserved-on-update, so an elliot-stack update can never clobber it.
• Holds all e-stack config (shared settings, per-skill overrides) in one place, not one file per skill.
• Holds all e-stack secrets/API keys in one place, keyed by name (PULSE_API_KEY, and whatever other skills need going forward), so there is exactly one file to open when a key needs rotating.
• Is read by a shared loader every skill's script uses, with a documented precedence order (process env → global config → error), replacing the per-skill ad-hoc .env lookups.
• Is created with restrictive permissions and documented as never-echoed-to-chat.

Nice-to-have

Startup key checks should be able to validate a key, not just detect its presence — a cheap auth ping so a stale/revoked key surfaces at check time instead of as a mid-run 401 on batch 3 of 27.

Related

• estack-pdf-to-md: startup API-key check gets blocked by Claude Code auto-mode classifier #26 (the estack-pdf-to-md startup check block getting blocked by the Claude Code auto-mode classifier) — a global config with a shared loader would likely remove the need for that inline shell block entirely.

🤖 Generated with Claude Code