@steipete/summarize 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,79 +1,124 @@
 # Changelog
 
-## 0.10.0 - Unreleased
+## 0.11.0 - Unreleased
+
+### Highlights
+
+- Auto CLI fallback: new controls and persisted last-success provider state (`~/.summarize/cli-state.json`) for no-key/local-CLI workflows.
+- Transcription reliability: Groq Whisper is now the preferred cloud transcriber, with custom OpenAI-compatible Whisper endpoint overrides.
+- Input reliability: binary-safe stdin handling, local media support in `--extract`, and fixes for local-file hangs/PDF preprocessing on custom OpenAI base URLs.
+
+### Features
+
+- CLI: add Cursor Agent provider (`--cli agent`) for CLI-model execution.
+- CLI auto mode: add implicit auto CLI fallback controls (`cli.autoFallback`, `--auto-cli-fallback`) and provider priority controls (`cli.providers`, `--cli-priority`), with persisted provider success ordering.
+- Transcription: add Groq Whisper as preferred cloud provider (#71, thanks @n0an).
+- Transcription: support custom OpenAI-compatible Whisper endpoints via `OPENAI_WHISPER_BASE_URL` (with safe `OPENAI_BASE_URL` fallback) (#65, thanks @toanbot).
+- Config: support generic `env` defaults in `~/.summarize/config.json` (fallback for any env var), while keeping legacy `apiKeys` mapping for compatibility (#63, thanks @entropyy0).
+
+### Fixes
+
+- CLI local files: avoid hangs when stream usage never resolves and preprocess PDFs automatically for custom OpenAI-compatible `OPENAI_BASE_URL` endpoints (e.g. non-`api.openai.com`).
+- CLI stdin: support binary-safe piping/input temp files to prevent corruption on non-text stdin (#76).
+- Extract mode: allow `--extract` for local media files (#72).
+- Auto model/daemon fallback: skip model attempts when required API keys are missing and normalize env-key checks in daemon fallback (#67, #78).
+- Cache: for auto presets (`auto`/`free`/named auto), prefer preset-level winner cache entries so stale per-candidate cache hits don’t override newer better-model results.
+- Media: treat X broadcasts (`/i/broadcasts/...`) as transcript-first media and prefer URL mode.
+- YouTube: keep explicit `--youtube apify` working when HTML fetch fails, while preserving duration metadata parity (#64, thanks @entropyy0).
+- Transcription: stabilize Groq-first fallback flow (no duplicate Groq retries in file mode), improve terminal error reporting, and surface Groq setup in media guidance (#71, thanks @n0an).
+- Media detection: detect more direct media URL extensions including `.ogg`/`.opus` (#65, thanks @toanbot).
+- Slides: allow yt-dlp cookies-from-browser via `SUMMARIZE_YT_DLP_COOKIES_FROM_BROWSER` to avoid YouTube 403s.
+- Daemon install: resolve symlinked/global bin paths and Windows shims when locating the CLI for install (#57, #62, thanks @entropyy0).
+- Extraction: strip hidden HTML + invisible Unicode before summarization or extract output (#61).
+- CLI: honor `--lang` for YouTube transcript→Markdown conversion in `--markdown-mode llm` (#56, thanks @entropyy0).
+- LLM: map Anthropic bare model ids to versioned aliases (`claude-sonnet-4` → `claude-sonnet-4-0`) (#55, thanks @entropyy0).
+
+### Improvements
+
+- Tooling: remove Biome and standardize on `oxfmt` + type-aware `oxlint`; `pnpm check` now enforces `format:check` before lint/tests.
+- Dependencies: update workspace dependencies to latest (including `@mariozechner/pi-ai` and `oxlint-tsgolint`).
+
+## 0.10.0 - 2026-01-22
 
 ### Highlights
 
 - Chrome Side Panel: **Chat mode** with metrics bar, message queue, and improved context (full transcript + summary metadata, jump-to-latest).
-- Slides: **YouTube slide screenshots + OCR + transcript-aligned cards**, timestamped seek, and an OCR/Transcript toggle.
 - Media-aware summarization in the Side Panel: Page vs Video/Audio dropdown, automatic media preference on video sites, plus visible word count/duration.
+- Slides: **YouTube slide screenshots + OCR + transcript-aligned cards**, timestamped seek, and an OCR/Transcript toggle.
 - CLI: robust URL + media extraction with transcript-first workflows and cache-aware streaming.
 
 ### Features
 
+- Chrome Side Panel chat: stream agent replies over SSE and restore chat history from daemon cache (#33, thanks @dougvk).
+- Media-aware summarization in the Side Panel: Page vs Video/Audio dropdown, automatic media preference on video sites, plus visible word count/duration.
+- Transcripts: `--timestamps` adds segment-level timings (`transcriptSegments` + `transcriptTimedText`) for YouTube, podcasts, and embedded captions.
+- Summaries: when transcript timestamps are available, prompts require timestamped bullet summaries; side panel auto-links `[mm:ss]` in summaries for media.
+- Chrome Side Panel chat: timestamped transcript context plus clickable `[mm:ss]` links that seek the current media.
 - Slides: extract slide screenshots + OCR for YouTube/direct video URLs in the CLI + extension (#41, thanks @philippb).
 - Slides: top-of-summary slide strip with expand/collapse full-width cards, timestamps, and click-to-seek.
 - Slides: slide descriptions without model calls (transcript windowing, OCR fallback) + OCR/Transcript toggle.
 - Slides: stream slide extraction status/progress and show a single header progress bar (no duplicate spinners).
-- Chrome Side Panel chat: stream agent replies over SSE and restore chat history from daemon cache (#33, thanks @dougvk).
-- Chrome Side Panel chat: timestamped transcript context plus clickable `[mm:ss]` links that seek the current media.
-- Summaries: when transcript timestamps are available, prompts require timestamped bullet summaries; side panel auto-links `[mm:ss]` in summaries for media.
-- Transcripts: `--timestamps` adds segment-level timings (`transcriptSegments` + `transcriptTimedText`) for YouTube, podcasts, and embedded captions.
-- Media-aware summarization in the Side Panel: Page vs Video/Audio dropdown, automatic media preference on video sites, plus visible word count/duration.
 - CLI: transcribe local audio/video files with mtime-aware transcript cache invalidation (thanks @mvance!).
 - Browser extension: add Firefox sidebar build + multi-browser config (#31, thanks @vlnd0).
+- CLI: add Cursor Agent CLI provider (`cli/agent`, `--cli agent`).
 - Chrome automation: add artifacts tool + REPL helpers for persistent session files (notes/JSON/CSV) and downloads.
 - Chrome automation: expand navigate tool with list/switch tab support and return matching skills after navigation.
 
 ### Fixes
 
+- Extract-only: remove implicit 8k cap; new `--max-extract-characters`/daemon `maxExtractCharacters` allow opt-in limits; resolves transcript truncation.
+- Media: route direct media URLs to the transcription pipeline and raise the local media limit to 2GB (#47, thanks @n0an).
+- Daemon (macOS): `daemon install` now falls back from `launchctl bootstrap gui/<uid>` to `user/<uid>` and resolves sudo/root uid targeting to avoid bootstrap `Input/output error` / `Domain does not support specified action` failures (#75).
+- Slides: allow yt-dlp cookies-from-browser via `SUMMARIZE_YT_DLP_COOKIES_FROM_BROWSER` to avoid YouTube 403s.
+- Chrome Side Panel chat: support JSON agent replies with explicit SSE/JSON negotiation to avoid “stream ended” errors.
+- Chrome Side Panel: scope streams/state per window so other windows don’t wipe active summaries.
+- Chrome Side Panel chat: keep auto-scroll pinned while streaming when you’re already at the bottom.
+- Chrome Side Panel chat: clear streaming placeholders on errors/aborts.
+- Chrome Side Panel: add inline error toast above chat composer; errors stay visible when scrolled.
+- Chrome Side Panel: clear/hide the inline error toast when no message is present to avoid empty red boxes.
+- Cache: include transcript timestamp requests in extract cache keys so timed summaries don’t reuse plain transcript content.
+- CLI: `--no-cache` now bypasses summary caching only; transcript/media caches still apply.
+- Media: treat X broadcasts (`/i/broadcasts/...`) as transcript-first media and prefer URL mode.
+- Daemon: avoid URL flow crashes when url-preference helpers are missing (ReferenceError guard).
+- YouTube: prefer English caption variants (`en-*`) when selecting caption tracks.
 - Prompts: ignore sponsor/ads segments in video and podcast summaries.
 - Prompts: enforce no-ads/no-skipped language and italicized standout excerpts (no quotation marks).
-- Media: route direct media URLs to the transcription pipeline and raise the local media limit to 2GB (#47, thanks @n0an).
 - Slides: render Slide X/Y labels and parse slide markers more robustly in streaming output.
+- Slides: parse `Slide N/Total` labels and stabilize title/body extraction.
 - Slides: ensure slide summary segments start with a title line when missing.
+- Slides: detect headline-style first lines and render them as slide titles (no required `Title:` markers).
 - Slides: progress updates during yt-dlp downloads and OSC progress mirrors slide extraction.
 - Slides: reuse the media cache for downloaded videos (even with `--no-cache`).
 - Slides: clear slide progress line before the finish summary to avoid stray `Slides x/y` output.
-- Slides: parse `Slide N/Total` labels and stabilize title/body extraction.
-- CLI: `--no-cache` now bypasses summary caching only; transcript/media caches still apply.
-- Chrome Side Panel chat: keep auto-scroll pinned while streaming when you’re already at the bottom.
-- Chrome Side Panel: scope streams/state per window so other windows don’t wipe active summaries.
-- Chrome Side Panel chat: support JSON agent replies with explicit SSE/JSON negotiation to avoid “stream ended” errors.
-- Chrome Side Panel chat: clear streaming placeholders on errors/aborts.
-- Chrome Side Panel: add inline error toast above chat composer; errors stay visible when scrolled.
-- Chrome Side Panel: clear/hide the inline error toast when no message is present to avoid empty red boxes.
-- Cache: include transcript timestamp requests in extract cache keys so timed summaries don’t reuse plain transcript content.
-- Extract-only: remove implicit 8k cap; new `--max-extract-characters`/daemon `maxExtractCharacters` allow opt-in limits; resolves transcript truncation.
+- CLI status line: ignore empty/ANSI-only spinner updates and duplicate texts to prevent flicker/blank status frames.
 - Automation: require userScripts (no isolated-world fallback), with improved guidance and in-panel permission notice.
-- Daemon: avoid URL flow crashes when url-preference helpers are missing (ReferenceError guard).
 - CLI: clear OSC progress on SIGINT/SIGTERM to avoid stuck indicators.
-- Slides: detect headline-style first lines and render them as slide titles (no required `Title:` markers).
-- YouTube: prefer English caption variants (`en-*`) when selecting caption tracks.
+- CLI local files: avoid hangs when stream usage never resolves and preprocess PDFs automatically for custom OpenAI-compatible `OPENAI_BASE_URL` endpoints (e.g. non-`api.openai.com`).
 
 ### Improvements
 
-- Daemon: emit slides start/progress/done metadata in extended logging for easier debugging.
-- Media: refactor routing helpers and size policy (#48, thanks @steipete).
+- Tooling: remove Biome and standardize on `oxfmt` + type-aware `oxlint`; `pnpm check` now enforces `format:check` before lint/tests.
+- Transcription: add auto transcriber selection (default) with ONNX-first when configured + `summarize transcriber setup`.
+- Cache: add media download caching with TTL/size caps + optional verification, plus `--no-media-cache`.
+- CLI: add themed output (24-bit ANSI), `--theme`, and config/env defaults for a consistent color scheme.
 - CLI: show determinate transcription progress percent when duration is known.
-- CLI: theme transcription progress lines and mirror part-based progress to OSC when duration is unknown.
 - CLI: show determinate OSC progress for transcription/download when totals are known.
 - CLI: keep OSC progress determinate when recent percent updates are available.
+- CLI: theme transcription progress lines and mirror part-based progress to OSC when duration is unknown.
 - CLI: theme tweet/extraction progress lines for consistent loading indicators.
 - CLI: theme file/slide spinner labels so all progress lines share the same styling.
 - CLI: simplify media download labels (avoid “media, video” duplication).
-- Transcription: add auto transcriber selection (default) with ONNX-first when configured + `summarize transcriber setup`.
 - Slides: cap auto slide targets at 6 by default for long videos.
-- CLI: add themed output (24-bit ANSI), `--theme`, and config/env defaults for a consistent color scheme.
-- Cache: add media download caching with TTL/size caps + optional verification, plus `--no-media-cache`.
 - Slides: render headline-style first lines as slide titles above the slide marker.
+- Media: refactor routing helpers and size policy (#48, thanks @steipete).
+- Daemon: emit slides start/progress/done metadata in extended logging for easier debugging.
 - Prompts: allow straight quotes and encourage 1-2 short exact quotes when relevant.
 
 ### Docs
 
 - README: 0.10.0 preview layout with clearer install flow, daemon rationale, and prominent Chrome Web Store link.
-- README: document ONNX transcriber setup + auto selection.
 - README/docs: add UI theme config + ONNX install hints.
+- README: document ONNX transcriber setup + auto selection.
 
 ## 0.9.0 - 2025-12-31
 
@@ -315,6 +360,7 @@
 - Add `--preprocess off|auto|always` and a `uvx markitdown` fallback for Markdown extraction and unsupported file attachments (when `--format md` is used).
 
 ## 0.3.0 - 2025-12-20
+
 ### Changes
 
 - Add yt-dlp audio transcription fallback for YouTube; prefer OpenAI Whisper with FAL fallback. Thanks @dougvk.

package/README.md

@@ -1,10 +1,14 @@
-# Summarize — Chrome Side Panel + CLI
+# Summarize 📝 — Chrome Side Panel + CLI
+
+![GitHub Repo Banner](https://ghrb.waren.build/banner?header=Summarize%F0%9F%93%9D&subheader=Chrome+Side+Panel+%2B+CLI&bg=f3f4f6&color=1f2937&support=true)
+
+<!-- Created with GitHub Repo Banner by Waren Gonzaga: https://ghrb.waren.build -->
 
 Fast summaries from URLs, files, and media. Works in the terminal, a Chrome Side Panel and Firefox Sidebar.
 
-**0.10.0 preview (unreleased):** this README reflects the upcoming release.
+**0.11.0 preview (unreleased):** this README reflects the upcoming release.
 
-## 0.10.0 preview highlights (most interesting first)
+## 0.11.0 preview highlights (most interesting first)
 
 - Chrome Side Panel **chat** (streaming agent + history) inside the sidebar.
 - **YouTube slides**: screenshots + OCR + transcript cards, timestamped seek, OCR/Transcript toggle.
@@ -36,14 +40,15 @@ YouTube slide screenshots (from the browser):
 
 ### Beginner quickstart (extension)
 
-1) Install the CLI (choose one):
+1. Install the CLI (choose one):
    - **npm** (cross‑platform): `npm i -g @steipete/summarize`
    - **Homebrew** (macOS arm64): `brew install steipete/tap/summarize`
-2) Install the extension (Chrome Web Store link above) and open the Side Panel.
-3) The panel shows a token + install command. Run it in Terminal:
+2. Install the extension (Chrome Web Store link above) and open the Side Panel.
+3. The panel shows a token + install command. Run it in Terminal:
    - `summarize daemon install --token <TOKEN>`
 
 Why a daemon/service?
+
 - The extension can’t run heavy extraction inside the browser. It talks to a local background service on `127.0.0.1` for fast streaming and media tools (yt‑dlp, ffmpeg, OCR, transcription).
 - The service autostarts (launchd/systemd/Scheduled Task) so the Side Panel is always ready.
 
@@ -72,15 +77,15 @@ More:
 
 ### Advanced (unpacked / dev)
 
-1) Build + load the extension (unpacked):
+1. Build + load the extension (unpacked):
    - Chrome: `pnpm -C apps/chrome-extension build`
      - `chrome://extensions` → Developer mode → Load unpacked
      - Pick: `apps/chrome-extension/.output/chrome-mv3`
    - Firefox: `pnpm -C apps/chrome-extension build:firefox`
      - `about:debugging#/runtime/this-firefox` → Load Temporary Add-on
      - Pick: `apps/chrome-extension/.output/firefox-mv3/manifest.json`
-2) Open Side Panel/Sidebar → copy token.
-3) Install daemon in dev mode:
+2. Open Side Panel/Sidebar → copy token.
+3. Install daemon in dev mode:
    - `pnpm summarize daemon install --token <TOKEN> --dev`
 
 ## CLI
@@ -110,7 +115,7 @@ npm i @steipete/summarize-core
 ```
 
 ```ts
-import { createLinkPreviewClient } from '@steipete/summarize-core/content'
+import { createLinkPreviewClient } from "@steipete/summarize-core/content";
 ```
 
 - Homebrew (custom tap):
@@ -143,6 +148,23 @@ summarize "/path/to/audio.mp3"
 summarize "/path/to/video.mp4"
 ```
 
+Stdin (pipe content using `-`):
+
+```bash
+echo "content" | summarize -
+pbpaste | summarize -
+# binary stdin also works (PDF/image/audio/video bytes)
+cat /path/to/file.pdf | summarize -
+```
+
+**Notes:**
+
+- Stdin has a 50MB size limit
+- The `-` argument tells summarize to read from standard input
+- Text stdin is treated as UTF-8 text (whitespace-only input is rejected as empty)
+- Binary stdin is preserved as raw bytes and file type is auto-detected when possible
+- Useful for piping clipboard content or command output
+
 YouTube (supports `youtube.com` and `youtu.be`):
 
 ```bash
@@ -243,7 +265,7 @@ Use `summarize --help` or `summarize help` for the full help text.
 - `--length short|medium|long|xl|xxl|s|m|l|<chars>`
 - `--language, --lang <language>`: output language (`auto` = match source)
 - `--max-output-tokens <count>`: hard cap for LLM output tokens
-- `--cli [provider]`: use a CLI provider (`--model cli/<provider>`). If omitted, uses auto selection with CLI enabled.
+- `--cli [provider]`: use a CLI provider (`--model cli/<provider>`). Supports `claude`, `gemini`, `codex`, `agent`. If omitted, uses auto selection with CLI enabled.
 - `--stream auto|on|off`: stream LLM output (`auto` = TTY only; disabled in `--json` mode)
 - `--plain`: keep raw output (no ANSI/OSC Markdown rendering)
 - `--no-color`: disable ANSI colors
@@ -252,7 +274,7 @@ Use `summarize --help` or `summarize help` for the full help text.
 - `--markdown-mode off|auto|llm|readability`: HTML -> Markdown mode (default `readability`)
 - `--preprocess off|auto|always`: controls `uvx markitdown` usage (default `auto`)
   - Install `uvx`: `brew install uv` (or https://astral.sh/uv/)
-- `--extract`: print extracted content and exit (URLs only)
+- `--extract`: print extracted content and exit (URLs only; stdin `-` is not supported)
   - Deprecated alias: `--extract-only`
 - `--slides`: extract slides for YouTube/direct video URLs and render them inline in the summary narrative (auto-renders inline in supported terminals)
 - `--slides-ocr`: run OCR on extracted slides (requires `tesseract`)
@@ -264,18 +286,66 @@ Use `summarize --help` or `summarize help` for the full help text.
 - `--verbose`: debug/diagnostics on stderr
 - `--metrics off|on|detailed`: metrics output (default `on`)
 
+### Coding CLIs (Codex, Claude, Gemini, Agent)
+
+Summarize can use common coding CLIs as local model backends:
+
+- `codex` -> `--cli codex` / `--model cli/codex/<model>`
+- `claude` -> `--cli claude` / `--model cli/claude/<model>`
+- `gemini` -> `--cli gemini` / `--model cli/gemini/<model>`
+- `agent` (Cursor Agent CLI) -> `--cli agent` / `--model cli/agent/<model>`
+
+Requirements:
+
+- Binary installed and on `PATH` (or set `CODEX_PATH`, `CLAUDE_PATH`, `GEMINI_PATH`, `AGENT_PATH`)
+- Provider authenticated (`codex login`, `claude auth`, `gemini` login flow, `agent login` or `CURSOR_API_KEY`)
+
+Quick smoke test:
+
+```bash
+printf "Summarize CLI smoke input.\nOne short paragraph. Reply can be brief.\n" >/tmp/summarize-cli-smoke.txt
+
+summarize --cli codex --plain --timeout 2m /tmp/summarize-cli-smoke.txt
+summarize --cli claude --plain --timeout 2m /tmp/summarize-cli-smoke.txt
+summarize --cli gemini --plain --timeout 2m /tmp/summarize-cli-smoke.txt
+summarize --cli agent --plain --timeout 2m /tmp/summarize-cli-smoke.txt
+```
+
+Set explicit CLI allowlist/order:
+
+```json
+{
+  "cli": { "enabled": ["codex", "claude", "gemini", "agent"] }
+}
+```
+
+Configure implicit auto CLI fallback:
+
+```json
+{
+  "cli": {
+    "autoFallback": {
+      "enabled": true,
+      "onlyWhenNoApiKeys": true,
+      "order": ["claude", "gemini", "codex", "agent"]
+    }
+  }
+}
+```
+
+More details: [`docs/cli.md`](docs/cli.md)
+
 ### Auto model ordering
 
 `--model auto` builds candidate attempts from built-in rules (or your `model.rules` overrides).
-CLI tools are not used in auto mode unless you enable them via `cli.enabled` in config.
-Why: CLI adds ~4s latency per attempt and higher variance.
-Shortcut: `--cli` (with no provider) uses auto selection with CLI enabled.
+CLI attempts are prepended when:
 
-When enabled, auto prepends CLI attempts in the order listed in `cli.enabled`
-(recommended: `["gemini"]`), then tries the native provider candidates
-(with OpenRouter fallbacks when configured).
+- `cli.enabled` is set (explicit allowlist/order), or
+- implicit auto selection is active and `cli.autoFallback` is enabled.
 
-Enable CLI attempts:
+Default fallback behavior: only when no API keys are configured, order `claude, gemini, codex, agent`, and remember/prioritize last successful provider (`~/.summarize/cli-state.json`).
+
+Set explicit CLI attempts:
 
 ```json
 {
@@ -283,15 +353,15 @@ Enable CLI attempts:
 }
 ```
 
-Disable CLI attempts:
+Disable implicit auto CLI fallback:
 
 ```json
 {
-  "cli": { "enabled": [] }
+  "cli": { "autoFallback": { "enabled": false } }
 }
 ```
 
-Note: when `cli.enabled` is set, it is also an allowlist for explicit `--cli` / `--model cli/...`.
+Note: explicit `--model auto` does not trigger implicit auto CLI fallback unless `cli.enabled` is set.
 
 ### Website extraction (Firecrawl + Markdown)
 
@@ -321,6 +391,7 @@ Environment variables for yt-dlp mode:
 - `SUMMARIZE_WHISPER_CPP_BINARY` - optional override for the local binary (default: `whisper-cli`)
 - `SUMMARIZE_DISABLE_LOCAL_WHISPER_CPP=1` - disable local whisper.cpp (force remote)
 - `OPENAI_API_KEY` - OpenAI Whisper transcription
+- `OPENAI_WHISPER_BASE_URL` - optional OpenAI-compatible Whisper endpoint override
 - `FAL_KEY` - FAL AI Whisper fallback
 
 Apify costs money but tends to be more reliable when captions exist.
@@ -411,6 +482,7 @@ Supported keys today:
 ```json
 {
   "model": { "id": "openai/gpt-5-mini" },
+  "env": { "OPENAI_API_KEY": "sk-..." },
   "ui": { "theme": "ember" }
 }
 ```
@@ -428,6 +500,8 @@ Also supported:
 - `model: { "mode": "auto" }` (automatic model selection + fallback; see [docs/model-auto.md](docs/model-auto.md))
 - `model.rules` (customize candidates / ordering)
 - `models` (define presets selectable via `--model <preset>`)
+- `env` (generic env var defaults; process env still wins)
+- `apiKeys` (legacy shortcut, mapped to env names; prefer `env` for new configs)
 - `cache.media` (media download cache: TTL 7 days, 2048 MB cap by default; `--no-media-cache` disables)
 - `media.videoMode: "auto"|"transcript"|"understand"`
 - `slides.enabled` / `slides.max` / `slides.ocr` / `slides.dir` (defaults for `--slides`)
@@ -450,22 +524,33 @@ Note: `--no-cache` bypasses summary caching only (LLM output). Extract/transcrip
 
 Precedence:
 
-1) `--model`
-2) `SUMMARIZE_MODEL`
-3) `~/.summarize/config.json`
-4) default (`auto`)
+1. `--model`
+2. `SUMMARIZE_MODEL`
+3. `~/.summarize/config.json`
+4. default (`auto`)
 
 Theme precedence:
 
-1) `--theme`
-2) `SUMMARIZE_THEME`
-3) `~/.summarize/config.json` (`ui.theme`)
-4) default (`aurora`)
+1. `--theme`
+2. `SUMMARIZE_THEME`
+3. `~/.summarize/config.json` (`ui.theme`)
+4. default (`aurora`)
+
+Environment variable precedence:
+
+1. process env
+2. `~/.summarize/config.json` (`env`)
+3. `~/.summarize/config.json` (`apiKeys`, legacy)
 
 ### Environment variables
 
 Set the key matching your chosen `--model`:
 
+- Optional fallback defaults can be stored in config:
+  - `~/.summarize/config.json` -> `"env": { "OPENAI_API_KEY": "sk-..." }`
+  - process env always takes precedence
+  - legacy `"apiKeys"` still works (mapped to env names)
+
 - `OPENAI_API_KEY` (for `openai/...`)
 - `ANTHROPIC_API_KEY` (for `anthropic/...`)
 - `XAI_API_KEY` (for `xai/...`)

package/dist/cli.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-if (!process.env.SUMMARIZE_GIT_SHA) process.env.SUMMARIZE_GIT_SHA = "52c05231"
+if (!process.env.SUMMARIZE_GIT_SHA) process.env.SUMMARIZE_GIT_SHA = "353e8ee6"
 await import('./esm/cli.js')