UX feedback: .env vs shell, playwright --help, freeze ratio (Playwright + TTS)

[jmjava]

Context

We integrated docgen into another repo (kt-flashcards) for a Playwright capture + OpenAI TTS + ffmpeg compose workflow (docgen tts, docgen compose, visual_map with type: playwright). Overall the pipeline worked well; below is feedback from that integration to improve discoverability, env handling, and first-run ergonomics.

---

1. .env loading vs existing process environment (setdefault)

What happened: docgen.yaml sets env_file: .env with a valid OPENAI_API_KEY, but docgen tts kept returning 401 until we discovered an OPENAI_API_KEY already exported in the shell (and/or IDE-injected). Docgen’s loader uses os.environ.setdefault(key, value) so existing env vars win and the file is silently ignored for that key.

Suggestion:

• Prefer explicit precedence documented in README and CLI help (e.g. “file overrides shell” vs “shell overrides file” — either is fine if obvious).
• If keeping setdefault (shell wins), print a one-line warning when env_file defines OPENAI_API_KEY but the process already has OPENAI_API_KEY set (e.g. [docgen] OPENAI_API_KEY already set; not loading from .env).
• Optional: DOCGEN_ENV_OVERRIDES=1 to force .env to win for listed keys.

---

2. Standalone docgen playwright and config discovery

What happened: Running docgen playwright from a directory without docgen.yaml failed config discovery; the minimal path wasn’t obvious until we read the source / tried --config.

Suggestion:

• In docgen playwright --help, mention --config path/to/docgen.yaml and/or cd to the bundle directory.
• If no config: print one line: “No docgen.yaml found; using cwd-only defaults (see …).”

---

3. --source path resolution vs terminal/rendered/

What happened: Passing --source rendered/foo.mp4 wrote under the demos project dir instead of terminal/rendered/, which differed from mental model of “always under terminal/rendered”.

Suggestion:

• Document the rule in docgen playwright --help and the Playwright / visual_map docs: when source contains a path separator vs basename-only.

---

4. max_freeze_ratio default for Playwright + TTS

What happened: Narration audio (~50s) was longer than the raw capture (~40s). Compose pads the video with a frozen last frame — good. The default max_freeze_ratio was too low for “short UI demo + longer voiceover,” so compose failed until we raised it in docgen.yaml.

Suggestion:

• Document a recommended validation.max_freeze_ratio (or a visual_map override) for type: playwright + TTS-heavy demos.
• Optionally raise the default slightly for playwright only, or emit a clearer error: “Increase max_freeze_ratio or shorten narration / lengthen capture.”

---

5. Positives (keep doing this)

• WebM-in-.mp4 detection + ffmpeg transcode in playwright_runner — saved us from shipping wrong container/suffix.
• docgen compose re-running Playwright from visual_map — one command to refresh video + mux after narration edits.
• repo_root in docgen.yaml — clean layout with docgen.yaml under docs/demos/ while scripts live beside it.

---

Summary

Biggest UX win would be (1) clearer .env / shell precedence and a warning when .env is skipped for OPENAI_API_KEY, plus (2) slightly more CLI/help text for playwright paths and config discovery.

Thank you for maintaining docgen — it fit this use case well once the above were understood.