[miguel-heygen]

What changes

A project's .env only sets the CLI's own settings. The working directory's .env could set any environment variable for every command except capture; now every command reads the same short list:

• the credentials HEYGEN_API_KEY, HYPERFRAMES_API_KEY, ELEVENLABS_API_KEY, FIGMA_TOKEN
• the vision settings that capture already allowed: OPENROUTER_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, the Vertex project, service account, location and model, the OpenRouter and Gemini models, and HYPERFRAMES_VISION_TIMEOUT_MS

HYPERFRAMES_BROWSER_PATH is deliberately not on the list: a project could point it at any program, so it stays something only the user's own environment sets.

A variable already in the environment still wins. Any other key in the file is ignored, and one stderr line names the keys (never their values).

PROJECT_ENV_KEYS in utils/dotEnv.ts is the one list; it replaces CAPTURE_ENV_KEYS, so capture no longer has its own rule. loadProjectDotEnv is the one loader cli.ts calls. The capture-only HYPERFRAMES_NO_CAPTURE_DOTENV opt-out is unchanged.

Decision needed

The key list is a product call. I built it from the keys the docs say a .env supplies plus the vision list; anything a project .env was setting beyond it stops working and prints the stderr line.

Tests

dotEnv.test.ts loads a .env with NODE_OPTIONS, HTTPS_PROXY and GEMINI_API_KEY: only the API key is set, one line names the other two, and no value is printed. It fails when the allowlist is removed from the loader. The docs page for the CLI gets one paragraph.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Oct 27, 2026, 2:43 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

Edit accuracy: accurate 271 (base branch 271), smooth 117 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (0)

Unstable (1)

• seqplainkeys-none-px-r0-root-z100: tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo false, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true