gflow-cli 0.45.0__tar.gz → 0.46.0__tar.gz

{gflow_cli-0.45.0 → gflow_cli-0.46.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gflow",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "Reusable development and operations workflows for gflow-cli",
   "author": {
     "name": "Flavio Oliva",

{gflow_cli-0.45.0 → gflow_cli-0.46.0}/.env.template

@@ -56,9 +56,33 @@
 #   official  - official Veo SDK (planned for v0.5+, requires Gemini API key)
 # GFLOW_CLI_PROVIDER=flow
 
-# Gemini API key — only required when GFLOW_CLI_PROVIDER=official.
-# Get one at https://aistudio.google.com/apikey
-# GFLOW_CLI_GEMINI_API_KEY=
+# -----------------------------------------------------------------------------
+# Prompt tools LLM (--tool creative-director / reverse-engineer / storyboard)
+#
+# Any OpenAI-compatible Chat Completions endpoint: OpenAI, OpenRouter, a
+# corporate gateway, a local proxy, Ollama, or Google's compat endpoint.
+# Provider keys stay with your gateway — gflow only holds the one credential it
+# presents to the endpoint below.
+#
+# NOTE: GFLOW_CLI_GEMINI_API_KEY / GFLOW_CLI_GEMINI_MODEL were REMOVED in
+# v0.46.0 and are not forwarded. Use GFLOW_CLI_LLM_API_KEY — an existing Google
+# AIza… key still works, since the default endpoint is Google's compat surface.
+# -----------------------------------------------------------------------------
+
+# Endpoint. This is the on/off switch for the prompt tools.
+# https only, except loopback (127.0.0.1 / localhost / ::1) which may use http.
+# Use 127.0.0.1 rather than localhost — gateways often bind IPv4 only and
+# Windows resolves ::1 first, which stalls.
+# GFLOW_CLI_LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
+
+# Credential for that endpoint (Authorization: Bearer). OPTIONAL — omit it for a
+# keyless local gateway and no header is sent at all.
+# Google key: https://aistudio.google.com/apikey
+# GFLOW_CLI_LLM_API_KEY=
+
+# Model, which is also the provider selector since gateways route on it
+# (e.g. openai/gpt-4o-mini). Unset = the gateway chooses.
+# GFLOW_CLI_LLM_MODEL=
 
 # -----------------------------------------------------------------------------
 # Cloud storage

{gflow_cli-0.45.0 → gflow_cli-0.46.0}/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.46.0] — 2026-07-28
+
+### Changed
+
+- **BREAKING — the prompt tools now drive any OpenAI-compatible endpoint (#387).**
+  `--tool creative-director` / `reverse-engineer` / `storyboard` were hardwired to
+  Google's native Gemini API, so an OpenAI-compatible gateway key could not be
+  used at all. The transport now speaks **OpenAI Chat Completions**, which
+  OpenAI, gateways/proxies (OpenRouter, LiteLLM, freellmapi), local runtimes
+  (Ollama, LM Studio) and Google's own compatibility endpoint all accept.
+  - New config: `GFLOW_CLI_LLM_BASE_URL` (the on/off switch; defaults to
+    Google's compat endpoint), `GFLOW_CLI_LLM_API_KEY` (**optional** — omitted
+    from the request entirely when unset, so keyless local gateways work), and
+    `GFLOW_CLI_LLM_MODEL` (also the provider selector, since gateways route on
+    the model string).
+  - Provider keys stay with your gateway. gflow only ever holds the single
+    credential it presents to the endpoint you point it at.
+  - The three builtin tools no longer pin `model = "gemini-2.5-flash"`. That pin
+    was sent unconditionally, so any gateway not serving that exact name
+    answered 400 — silently, because the prompt tools never fail a run.
+
+### Removed
+
+- **BREAKING — `GFLOW_CLI_GEMINI_API_KEY` and `GFLOW_CLI_GEMINI_MODEL` (#387).**
+  Set `GFLOW_CLI_LLM_API_KEY` instead; an existing Google `AIza…` key keeps
+  working unchanged, because the default endpoint is Google's OpenAI-compatible
+  surface. gflow prints a one-time warning if it sees the old variable — the old
+  value is never forwarded. The warning exists because the prompt tools never
+  fail a run: without it, prompts would quietly stop being rewritten while
+  generations still billed in full.
+  `GFLOW_CLI_GEMINI_MODEL` had in fact never had a live code path — its only
+  reader was an uncalled helper — despite being documented as a global override.
+
+### Fixed
+
+- **`reverse-engineer` no longer expands a file path as if it were a prompt (#387).**
+  When multimodal analysis of a URL, video, or image failed, the runtime fell
+  through to text expansion of the *path string*, returning a confident but
+  useless prompt that still billed a full generation. It now degrades to the
+  original input.
+
+### Security
+
+- **The prompt-tools endpoint is treated as a trust boundary (#387).** `base_url`
+  is user-supplied now, so: redirects are declined (`urllib` re-sends the
+  `Authorization` header to whatever host a 302 names, which would have leaked
+  the key to a hostile gateway); `base_url` is validated to `https`, or `http`
+  for loopback only, with credentials-in-URL rejected; error-response bodies are
+  redacted before logging, since a gateway can echo the bearer token back; and
+  the resolved destination host is logged once, giving an audit trail for where
+  prompts and base64 image bytes were sent.
+
 ## [0.45.0] — 2026-07-28
 
 ### Fixed
@@ -2466,7 +2518,8 @@ shell-script template that branches on these codes.
 
 First skeleton. Not functional end-to-end yet.
 
-[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.45.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.46.0...HEAD
+[0.46.0]: https://github.com/ffroliva/gflow-cli/compare/v0.45.0...v0.46.0
 [0.45.0]: https://github.com/ffroliva/gflow-cli/compare/v0.44.0...v0.45.0
 [0.44.0]: https://github.com/ffroliva/gflow-cli/compare/v0.43.0...v0.44.0
 [0.43.0]: https://github.com/ffroliva/gflow-cli/compare/v0.42.0...v0.43.0

{gflow_cli-0.45.0 → gflow_cli-0.46.0}/CONFIGURATION.md

@@ -8,8 +8,9 @@
 | `GFLOW_CLI_OUTPUT_DIR` | `~/Downloads/gflow-cli` | Where generated images and videos are saved. |
 | `CHROME_BINARY` | (autodetect) | Override Chrome binary path. Falls back to platform-standard locations. |
 | `GFLOW_CLI_CONCURRENCY` | `4` | Maximum parallel API requests per batch. |
-| `GFLOW_CLI_GEMINI_API_KEY` | _(unset)_ | Public Gemini key enabling prompt expansion (`-e`/`--expand`). Unset = expansion is a graceful no-op. [Get one](https://aistudio.google.com/apikey). |
-| `GFLOW_CLI_GEMINI_MODEL` | `gemini-2.5-flash` | Gemini model used for prompt expansion. |
+| `GFLOW_CLI_LLM_BASE_URL` | Google compat endpoint | OpenAI-compatible endpoint for the prompt tools (`--tool`). The on/off switch. |
+| `GFLOW_CLI_LLM_API_KEY` | _(unset)_ | Credential for that endpoint. Optional — omit for a keyless local gateway. [Google key](https://aistudio.google.com/apikey). |
+| `GFLOW_CLI_LLM_MODEL` | _(unset)_ | Model, and therefore the provider selector. Unset = the gateway chooses. |
 | `GFLOW_LIVE` | _(unset)_ | Set to `1` to enable live-API test markers (`@pytest.mark.live`). |
 
 ---

{gflow_cli-0.45.0 → gflow_cli-0.46.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.45.0
+Version: 0.46.0
 Summary: Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal.
 Project-URL: Homepage, https://github.com/ffroliva/gflow-cli
 Project-URL: Issues, https://github.com/ffroliva/gflow-cli/issues

{gflow_cli-0.45.0 → gflow_cli-0.46.0}/PLAN.md

@@ -115,7 +115,7 @@ src/gflow_cli/
 
 Documented in [docs/CONFIGURATION.md](docs/CONFIGURATION.md) and [.env.template](.env.template). Variables:
 
-`GFLOW_CLI_HOME`, `GFLOW_CLI_OUTPUT_DIR`, `GFLOW_CLI_PROFILE`, `GFLOW_CLI_PROVIDER`, `GFLOW_CLI_GEMINI_API_KEY`, `GFLOW_CLI_TIMEOUT_SECONDS`, `GFLOW_CLI_LOG_LEVEL`, `GFLOW_CLI_LOG_FORMAT`, `GFLOW_CLI_CONCURRENCY`, `GFLOW_CLI_DB_PATH`, `GFLOW_CLI_HISTORY_PROMPTS`.
+`GFLOW_CLI_HOME`, `GFLOW_CLI_OUTPUT_DIR`, `GFLOW_CLI_PROFILE`, `GFLOW_CLI_PROVIDER`, `GFLOW_CLI_LLM_BASE_URL`, `GFLOW_CLI_LLM_API_KEY`, `GFLOW_CLI_LLM_MODEL`, `GFLOW_CLI_TIMEOUT_SECONDS`, `GFLOW_CLI_LOG_LEVEL`, `GFLOW_CLI_LOG_FORMAT`, `GFLOW_CLI_CONCURRENCY`, `GFLOW_CLI_DB_PATH`, `GFLOW_CLI_HISTORY_PROMPTS`.
 
 Default paths via `platformdirs`:
 

{gflow_cli-0.45.0/website → gflow_cli-0.46.0}/docs/CONFIGURATION.md

@@ -113,27 +113,97 @@ Deep setup, verification, and security notes live in
 **Default:** `flow`
 **CLI override:** none yet — set the env var to switch backends once `official` is wired.
 
-### `GFLOW_CLI_GEMINI_API_KEY`
-
-**What:** Public Gemini API key. Used by the **`creative-director`** prompt tool
-(`--tool creative-director` / `gflow tools run creative-director`, see
-[TOOLS.md](TOOLS.md) and [PROMPT_EXPANSION.md](PROMPT_EXPANSION.md)) and, in future, by the
-official Veo 3.1 SDK.
-**Required when:** you apply the `creative-director` tool (via `--tool` on any generation
-command, or `gflow tools run`), or `GFLOW_CLI_PROVIDER=official`.
-**Default:** unset
-**Behavior when unset:** the tool is a no-op — gflow logs an `INFO` notice and generates
-from your original prompt (it never fails the run). API errors (rate limit, network) fall
-back the same way after a short exponential-backoff retry, bounded by an overall ~60s
-wall-clock budget per call.
-**Get one:** <https://aistudio.google.com/apikey>
-
-### `GFLOW_CLI_GEMINI_MODEL`
-
-**What:** Gemini model used by the `creative-director` prompt tool.
-**Default:** `gemini-2.5-flash`
-**Note:** Override to select a newer Flash revision without upgrading gflow-cli, e.g.
-`GFLOW_CLI_GEMINI_MODEL=gemini-2.5-flash-lite`.
+### Prompt-tools LLM: `GFLOW_CLI_LLM_*`
+
+The prompt tools (`--tool creative-director` / `reverse-engineer` / `storyboard`, see
+[TOOLS.md](TOOLS.md) and [PROMPT_EXPANSION.md](PROMPT_EXPANSION.md)) talk to any endpoint
+speaking the **OpenAI Chat Completions API** — OpenAI, OpenRouter, a corporate gateway, a
+self-hosted proxy, a local Ollama/LM Studio, or Google's own compatibility endpoint.
+
+> **Removed in v0.46.0:** `GFLOW_CLI_GEMINI_API_KEY` and `GFLOW_CLI_GEMINI_MODEL` are no
+> longer read and are **not** forwarded. Set `GFLOW_CLI_LLM_API_KEY` instead — an existing
+> Google `AIza…` key keeps working unchanged, because the default endpoint is Google's
+> OpenAI-compatible surface. gflow prints a one-time warning if it sees the old variable,
+> because the prompt tools never fail a run: without the warning your prompts would quietly
+> stop being rewritten while generations still billed in full.
+
+#### `GFLOW_CLI_LLM_BASE_URL`
+
+**What:** Base URL of an OpenAI-compatible endpoint. This is the on/off switch for the
+prompt tools.
+**Default:** `https://generativelanguage.googleapis.com/v1beta/openai` (Google)
+**Validated:** `https` only — plus plain `http` for loopback (`127.0.0.1`, `localhost`,
+`::1`), since a local gateway never puts your key on the wire. Credentials embedded in the
+URL (`https://user:pass@host`) are rejected; pass the credential via
+`GFLOW_CLI_LLM_API_KEY`. Redirects are never followed, because `urllib` would re-send your
+`Authorization` header to whatever host a redirect names.
+
+#### `GFLOW_CLI_LLM_API_KEY`
+
+**What:** The credential gflow presents to that endpoint, as `Authorization: Bearer`.
+**Default:** unset — and **optional**. When unset the header is omitted entirely, which is
+what a keyless local gateway expects.
+**Note:** this is the *only* key gflow holds. Provider keys (OpenAI, Anthropic, Google…)
+stay with your gateway; gflow never sees them.
+
+#### `GFLOW_CLI_LLM_MODEL`
+
+**What:** Model to request. Because gateways route on the model string, this doubles as the
+provider selector (e.g. `openai/gpt-4o-mini`, `google/gemini-2.5-flash`).
+**Default:** unset.
+**Precedence:** a tool's TOML `config.model` pin > `GFLOW_CLI_LLM_MODEL` > the default
+endpoint's own default > omitted, letting the gateway choose. The builtin tools pin
+nothing on purpose: a hardcoded vendor model name is rejected by any gateway that does not
+serve it. Note Google's compat endpoint has **no** server-side default and answers
+`400 "model is not specified"`, so the default endpoint ships a matching default model.
+
+#### When is the tool active?
+
+Set **either** a key or a base URL and the tools run. Set neither and they are a silent
+no-op: gflow logs an `INFO` notice, makes no network call, and generates from your original
+prompt. It never fails the run — API errors (rate limit, network, a model the gateway does
+not serve) fall back the same way after a short exponential-backoff retry bounded by an
+overall ~60 s wall-clock budget per call. A fallback prints one line to stderr so a
+misconfiguration is not invisible.
+
+#### Examples
+
+```bash
+# Google (default endpoint) — an existing AIza… key, nothing else to set
+export GFLOW_CLI_LLM_API_KEY="AIza..."
+
+# OpenRouter, or any hosted OpenAI-compatible gateway
+export GFLOW_CLI_LLM_BASE_URL="https://openrouter.ai/api/v1"
+export GFLOW_CLI_LLM_API_KEY="sk-or-..."
+export GFLOW_CLI_LLM_MODEL="google/gemini-2.5-flash"
+
+# A local proxy in Docker — one entrypoint across many providers, keys held by
+# the gateway. freellmapi (https://github.com/tashfeenahmed/freellmapi) is one
+# such proxy; anything OpenAI-compatible works.
+export GFLOW_CLI_LLM_BASE_URL="http://127.0.0.1:3001/v1"
+export GFLOW_CLI_LLM_API_KEY="<the gateway's own unified key>"
+
+# A keyless local runtime (Ollama) — no credential at all
+export GFLOW_CLI_LLM_BASE_URL="http://127.0.0.1:11434/v1"
+export GFLOW_CLI_LLM_MODEL="llama3"
+```
+
+Verify without spending generation credits:
+
+```bash
+gflow tools run creative-director "cat in space" --json   # check "was_expanded": true
+```
+
+#### Gotchas
+
+- **Use `127.0.0.1`, not `localhost`.** Gateways commonly bind IPv4 only, and Windows'
+  dual-stack resolver tries `::1` first, which stalls until it times out.
+- **Include the version path.** Most gateways serve `/v1`; gflow appends
+  `/chat/completions` to whatever you give it.
+- **`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` apply implicitly.** Python's `urllib` honours
+  them, and on Windows it also picks up the system proxy configured in Settings even with
+  no env var set. If a corporate proxy is configured, add your local gateway to `NO_PROXY`
+  or its traffic will be routed through the proxy and fail non-obviously.
 
 ### `GFLOW_CLI_AUTH_LOGIN_TIMEOUT`
 
@@ -412,12 +482,12 @@ gflow image batch ./manifest.tsv
 ### "I want to test against the official Veo SDK"
 
 ```bash
-GFLOW_CLI_PROVIDER=official \
-GFLOW_CLI_GEMINI_API_KEY=AIza... \
-gflow video t2v "test"
+GFLOW_CLI_PROVIDER=official gflow video t2v "test"
 ```
 
-(planned v0.5+ — current scaffold accepts but ignores `GFLOW_CLI_PROVIDER=official`.)
+(planned v0.5+ — the current scaffold accepts but ignores `GFLOW_CLI_PROVIDER=official`. It will
+need its own Google credential when implemented; `GFLOW_CLI_LLM_API_KEY` is for the prompt tools
+only and is not used for generation.)
 
 ### "I want a sandbox profile that doesn't pollute my main one"
 

{gflow_cli-0.45.0 → gflow_cli-0.46.0}/docs/INDEX.md

@@ -135,7 +135,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A command failed — where is the incident bundle and what's in it?"** → [DEBUGGING § Automatic incident bundles](DEBUGGING.md#automatic-incident-bundles) (layout, triggers, review-before-sharing); privacy boundaries: [SECURITY § Automatic incident bundles](SECURITY.md#automatic-incident-bundles-gflow_cli_incident_capture-default-on); disable via [CONFIGURATION § GFLOW_CLI_INCIDENT_CAPTURE](CONFIGURATION.md#gflow_cli_incident_capture)
 **"Flow's UI broke a selector — how do I diagnose it?"** → [DEBUGGING § Inspecting Flow's live UI](DEBUGGING.md#inspecting-flows-live-ui)
 **"What does each `ui_automation.*` log event mean?"** → [DEBUGGING § Listener & HTTP-layer debugging](DEBUGGING.md#listener--http-layer-debugging)
-**What was actually live-verified for the latest release?** → latest: [LIVE_VERIFICATION_v0.45.0](LIVE_VERIFICATION_v0.45.0.md) (**#393 UUID `--ref` binding + #395 character-entity binding live-verified 2026-07-27/28** — a controlled A/B on identical input flipped `--ref` from exit 9 to exit 0 via the catalog-backed upload fallback, with the anti-silence guard [an unbindable ref aborts non-zero and writes no image] pinned by a live e2e; picker DOM + HAR showed Flow indexes a short auto-caption, NOT the prompt, so a prompt-derived search hint was dropped rather than shipped on assumption; a CDP spike against Flow's own character flow then captured the `entityContext` contract that gflow's generations were missing, root-causing #395 to two gflow defects [overlay dismissal Escaping Flow's own composer, and a character-route bounce that sent the prompt to the project composer] — both fixed, both character e2e tests now pass live, including `--format-prompt` [#383], with a read-back confirming the character carries its name and `thumbnail_media_id`). Prior: [v0.44.0](LIVE_VERIFICATION_v0.44.0.md) (**#381 dual-side project management & Playwright Chromium transport live-verified 2026-07-26** — real-editor project creation + rename tRPC server/DOM sync, prompt slugging, `gflow project` subcommand family, HTTP 429 adaptive backoff, and full E2E test suite). Prior: [v0.43.0](LIVE_VERIFICATION_v0.43.0.md) (**private incident diagnostics live-verified 2026-07-23, 1 Veo credit**). Prior: [v0.42.0](LIVE_VERIFICATION_v0.42.0.md) (**#361 production-readiness live-gaps confirmed live 2026-07-21, 1 Veo credit** — a real `veo-lite` t2v through the worker path persisted a real `remote_started` checkpoint [observer→checkpoint→DB chain confirmed], crash-recovery classified the task `indeterminate` without resubmitting, and mid-launch cancellation released the `ProfileLease` credit-free; full evidence in [v0.40.0-production-readiness § "2026-07-21 live follow-up"](LIVE_VERIFICATION_v0.40.0-production-readiness.md#2026-07-21-live-follow-up-0420-cycle); #359 content-safety `400`→`ContentPolicyError` classification is unit-covered, not live-triggered [would require a deliberate policy violation]; #360/#362 are docs-only, verified by the documentation gates). Prior: [v0.41.0](LIVE_VERIFICATION_v0.41.0.md) (**#357 production-readiness hardening — stale-session fail-fast, free image gen, paid veo-lite T2V all proven live**). Prior: [v0.40.0](LIVE_VERIFICATION_v0.40.0.md) (**#344 `@`-mention asset-tagging resolution proven live e2e, ~2 Imagen credits** — `gflow character create` staged a real taggable character [bound reference images, `has_reference_images` guard], the e2e test's documented propagation wait cleared Flow's `projectInitialData` lag, and `gflow image t2i "@Zoro …"` passed with returncode 0, a real generated image, and the correctly de-tagged prompt in the catalog — no code changes needed, `resolve_and_apply` as merged in #344 already works end-to-end; pre-existing unrelated issue #174 [Flow media-library A/B flake] can still intermittently block generation regardless of this feature — recorded, not omitted). Prior: [v0.39.0](LIVE_VERIFICATION_v0.39.0.md) (**#341 failed-generation persistence proven live** — a real `image t2i` on denon82 failed at the wire [`batchGenerateImages` HTTP 400 → `WireFormatError`] and the record-on-catch funnel wrote the **first-ever `failed` row** into the production catalog [`error_type=wire-format`, redacted `error_detail`, browsable via `gflow data list errors`], **$0**; the remaining paid paths [video/chain/batch/movie/worker] are funnel-regression-tested, not force-failed live [would cost credits], and the status-aware `succeeded=false` video-poll fix is unit-locked — recorded, not omitted). Prior: [v0.38.1](LIVE_VERIFICATION_v0.38.1.md) (**#338 agentic-pin recovery proven live ON the pinned account** — run 1 caught the composer-render race the unit suite could not [`ensure_media_incomplete` +115 ms, toggle never reached]; the readiness-wait fix landed and run 2 recovered classic on denon82 after ~2h of pin [`ui_driver.bound mode=classic`, real 768×1376 JPEG, exact prompt adherence]; reload branch unit-locked, live trigger not observed this cycle — recorded, not omitted). Prior: [v0.38.0](LIVE_VERIFICATION_v0.38.0.md) (**#332 mode control + #314 i2i ref dedup proven live e2e** — `image t2i --ui-mode classic` recovered agentic→classic in a real run [`ui_mode.attempt_exit_agent` → full classic chain, 1376×768 JPEG]; two identical `image i2i` runs proved the dedup contract [run 1: picker miss → `image_uploaded`; run 2: `reference_deduped_by_filename`, ZERO uploads]; `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 15.2 MB `ftyp` mp4]; autopilot #333 recorded deferred-with-reason [hermes-ops deployment staged separately]). Prior: [v0.37.0](LIVE_VERIFICATION_v0.37.0.md) (**viewport 1920×1080 + agentic count enforcement + FIPS-safe SAPISIDHASH proven live e2e** — `image t2i` [classic cohort, real 1376×768 JPEG] and `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 11.5 MB `ftyp` mp4] both succeeded end-to-end at the new 1920×1080 viewport with every selector resolving [no drift]; SAPISIDHASH digest verified byte-identical [FIPS-safe `usedforsecurity=False`], auth unchanged). Prior: [v0.36.0](LIVE_VERIFICATION_v0.36.0.md) (**#316 diagnostic tooling live-verified against real Flow traffic** — `GFLOW_CLI_HAR_PATH` captured a real 54-entry HAR [real Flow domains, 34× 200s, and a genuine 401 the tool exists to diagnose]; `GFLOW_CLI_DEBUG_TRACEBACK`'s typed-error scoping confirmed live [console output identical with/without the flag on a `GFlowError`]; unhandled-path behavior covered by 6 new tests (30 total across both files) + SDD task review; #312 reference-entity-smuggling fix covered by its own dedicated e2e test). Prior: [v0.35.0](LIVE_VERIFICATION_v0.35.0.md) (**#305-follow-up multimodal reverse-engineering & storyboard tool proven live e2e** — `gflow tools run storyboard` successfully deconstructed a cyberpunk scene into a cohesive 4-panel sequence; `reverse-engineer` tool extracts frames from video streams/URLs using `claude-video`'s `watch.py` and produces structured prompt components using Gemini multimodal models; dynamic token budgeting and strict Pyright types verified via test suite). Prior: [v0.34.0](LIVE_VERIFICATION_v0.34.0.md) (**#299 `--ui-mode` gate proven live, ZERO credits** — drove `get_ui_driver` directly over 4 real editor loads, never generated: bidirectional switch works [classic→agentic via `_force_agent_mode`, agentic→classic via `_exit_agent_mode`, each DOM-reverified], `agentic`-when-already-agentic is idempotent, and a timed-out toggle → **exit-28 fail-fast before submission**; deprecation behavior-change [`prefer_classic`→exit 28] confirmed). Prior: [v0.33.0](LIVE_VERIFICATION_v0.33.0.md) (**#287-follow-up picker fix proven live on the original repro** — the v0.32.1-failing `i2v <uuid> --project <crowded>` command now exits 0 with a real 3.0 MB `ftyp` mp4, `frame_ref_attached` + `video_saved`, zero uploads; **#241 jitter live-verified on both paths** — flag `--jitter 4-6` → `batch_jitter_sleep seconds=4.98`, and the new 0.5–1.5 s default → `seconds=1.47`, each firing exactly once between two t2i submissions; environment note: the denon82 cohort is now natively agentic and round-2 generations hit the pre-existing #281 `MediaAttributionError`, not a regression). Prior: [v0.32.1](LIVE_VERIFICATION_v0.32.1.md) (**#293 teardown fix live-verified credit-free** — error-path aborts leave ZERO chrome.exe holding the profile [3× leak reproduced pre-fix same day]; force-close fallback + ProfileLockedError translation unit-pinned; #283 wave logic fixes mock-verified to exact call counts). Prior: [v0.32.0](LIVE_VERIFICATION_v0.32.0.md) (**#287 UUID i2v frames proven live e2e** — an in-project asset selected by media UUID in the frame-slot dialog [frame_ref_attached, startImage bound on the wire, ZERO upload events] produced a real 720×1280 interpolation, resolving the #237 negative prior; foreign UUID → exit 9 pre-generation with screenshot; **#288 duration fail-fast proven live** — exit 23 pre-submit saved a 10-credit generation, and the debug screenshot confirmed the duration control is ABSENT from the cohort's settings popover [locale hypothesis refuted]; upload-400 exit-27 repro deferred-with-reason — the original rejected JPEG no longer exists). Prior: [v0.31.0](LIVE_VERIFICATION_v0.31.0.md) (**#281 wrong-media defenses live-verified in BOTH directions, credit-free** — correct attribution downloads with real wire metadata [seed, 768×1376]; the incident-class lazy-render ambiguity reproduced live and hard-stopped with `MediaAttributionError` exit 26 naming every candidate UUID, no file written; **#282 two-UUID-ref i2i proven e2e** — both freshly generated portrait UUIDs picker-selected into one scene with both canonical identities visually transferred). Prior: [v0.30.0](LIVE_VERIFICATION_v0.30.0.md) (**agentic-cohort image path + both fixes live-verified credit-free** — native 768×1376 stills, i2i-chain + canonical-ref identity hold; the character-create `DataIntegrityError` and the `prefer_classic` WARNING were observed live then fixed [recorder idempotent + INFO log]; MCP video-param feature deferred-with-reason on Veo credits, per the stills-only goal). Prior: [v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
+**What was actually live-verified for the latest release?** → latest: [LIVE_VERIFICATION_v0.46.0](LIVE_VERIFICATION_v0.46.0.md) (**#387 provider-agnostic prompt-tools transport live-verified 2026-07-28, ZERO credits** — a four-probe capability spike passed 4/4 against BOTH a non-Google gateway and Google's OpenAI-compat endpoint, including a *semantic* multimodal check [a generated solid-red JPEG round-tripped and the model answered 'Red'], which is what proved the native Gemini `inlineData` path could be deleted outright rather than kept as a fallback; the real CLI then returned `was_expanded: true` on gateway/gateway-no-model/Google-default, emitted the loud one-time notice + no-op for the removed `GFLOW_CLI_GEMINI_API_KEY`, and made NO network call when unconfigured. Live verification caught two defects a fully green 2849-test offline suite missed: Google's compat endpoint has no server-side default model [`400 "model is not specified"`, silently no-oping the DEFAULT configuration], and the first redirect guard did not actually work because `build_opener()` installs its default handlers regardless of arguments, so `Authorization` would still have been replayed cross-host. `/code-review high` is recorded as NOT run — it is user-triggered only). Prior: [v0.45.0](LIVE_VERIFICATION_v0.45.0.md) (**#393 UUID `--ref` binding + #395 character-entity binding live-verified 2026-07-27/28** — a controlled A/B on identical input flipped `--ref` from exit 9 to exit 0 via the catalog-backed upload fallback, with the anti-silence guard [an unbindable ref aborts non-zero and writes no image] pinned by a live e2e; picker DOM + HAR showed Flow indexes a short auto-caption, NOT the prompt, so a prompt-derived search hint was dropped rather than shipped on assumption; a CDP spike against Flow's own character flow then captured the `entityContext` contract that gflow's generations were missing, root-causing #395 to two gflow defects [overlay dismissal Escaping Flow's own composer, and a character-route bounce that sent the prompt to the project composer] — both fixed, both character e2e tests now pass live, including `--format-prompt` [#383], with a read-back confirming the character carries its name and `thumbnail_media_id`). Prior: [v0.44.0](LIVE_VERIFICATION_v0.44.0.md) (**#381 dual-side project management & Playwright Chromium transport live-verified 2026-07-26** — real-editor project creation + rename tRPC server/DOM sync, prompt slugging, `gflow project` subcommand family, HTTP 429 adaptive backoff, and full E2E test suite). Prior: [v0.43.0](LIVE_VERIFICATION_v0.43.0.md) (**private incident diagnostics live-verified 2026-07-23, 1 Veo credit**). Prior: [v0.42.0](LIVE_VERIFICATION_v0.42.0.md) (**#361 production-readiness live-gaps confirmed live 2026-07-21, 1 Veo credit** — a real `veo-lite` t2v through the worker path persisted a real `remote_started` checkpoint [observer→checkpoint→DB chain confirmed], crash-recovery classified the task `indeterminate` without resubmitting, and mid-launch cancellation released the `ProfileLease` credit-free; full evidence in [v0.40.0-production-readiness § "2026-07-21 live follow-up"](LIVE_VERIFICATION_v0.40.0-production-readiness.md#2026-07-21-live-follow-up-0420-cycle); #359 content-safety `400`→`ContentPolicyError` classification is unit-covered, not live-triggered [would require a deliberate policy violation]; #360/#362 are docs-only, verified by the documentation gates). Prior: [v0.41.0](LIVE_VERIFICATION_v0.41.0.md) (**#357 production-readiness hardening — stale-session fail-fast, free image gen, paid veo-lite T2V all proven live**). Prior: [v0.40.0](LIVE_VERIFICATION_v0.40.0.md) (**#344 `@`-mention asset-tagging resolution proven live e2e, ~2 Imagen credits** — `gflow character create` staged a real taggable character [bound reference images, `has_reference_images` guard], the e2e test's documented propagation wait cleared Flow's `projectInitialData` lag, and `gflow image t2i "@Zoro …"` passed with returncode 0, a real generated image, and the correctly de-tagged prompt in the catalog — no code changes needed, `resolve_and_apply` as merged in #344 already works end-to-end; pre-existing unrelated issue #174 [Flow media-library A/B flake] can still intermittently block generation regardless of this feature — recorded, not omitted). Prior: [v0.39.0](LIVE_VERIFICATION_v0.39.0.md) (**#341 failed-generation persistence proven live** — a real `image t2i` on denon82 failed at the wire [`batchGenerateImages` HTTP 400 → `WireFormatError`] and the record-on-catch funnel wrote the **first-ever `failed` row** into the production catalog [`error_type=wire-format`, redacted `error_detail`, browsable via `gflow data list errors`], **$0**; the remaining paid paths [video/chain/batch/movie/worker] are funnel-regression-tested, not force-failed live [would cost credits], and the status-aware `succeeded=false` video-poll fix is unit-locked — recorded, not omitted). Prior: [v0.38.1](LIVE_VERIFICATION_v0.38.1.md) (**#338 agentic-pin recovery proven live ON the pinned account** — run 1 caught the composer-render race the unit suite could not [`ensure_media_incomplete` +115 ms, toggle never reached]; the readiness-wait fix landed and run 2 recovered classic on denon82 after ~2h of pin [`ui_driver.bound mode=classic`, real 768×1376 JPEG, exact prompt adherence]; reload branch unit-locked, live trigger not observed this cycle — recorded, not omitted). Prior: [v0.38.0](LIVE_VERIFICATION_v0.38.0.md) (**#332 mode control + #314 i2i ref dedup proven live e2e** — `image t2i --ui-mode classic` recovered agentic→classic in a real run [`ui_mode.attempt_exit_agent` → full classic chain, 1376×768 JPEG]; two identical `image i2i` runs proved the dedup contract [run 1: picker miss → `image_uploaded`; run 2: `reference_deduped_by_filename`, ZERO uploads]; `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 15.2 MB `ftyp` mp4]; autopilot #333 recorded deferred-with-reason [hermes-ops deployment staged separately]). Prior: [v0.37.0](LIVE_VERIFICATION_v0.37.0.md) (**viewport 1920×1080 + agentic count enforcement + FIPS-safe SAPISIDHASH proven live e2e** — `image t2i` [classic cohort, real 1376×768 JPEG] and `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 11.5 MB `ftyp` mp4] both succeeded end-to-end at the new 1920×1080 viewport with every selector resolving [no drift]; SAPISIDHASH digest verified byte-identical [FIPS-safe `usedforsecurity=False`], auth unchanged). Prior: [v0.36.0](LIVE_VERIFICATION_v0.36.0.md) (**#316 diagnostic tooling live-verified against real Flow traffic** — `GFLOW_CLI_HAR_PATH` captured a real 54-entry HAR [real Flow domains, 34× 200s, and a genuine 401 the tool exists to diagnose]; `GFLOW_CLI_DEBUG_TRACEBACK`'s typed-error scoping confirmed live [console output identical with/without the flag on a `GFlowError`]; unhandled-path behavior covered by 6 new tests (30 total across both files) + SDD task review; #312 reference-entity-smuggling fix covered by its own dedicated e2e test). Prior: [v0.35.0](LIVE_VERIFICATION_v0.35.0.md) (**#305-follow-up multimodal reverse-engineering & storyboard tool proven live e2e** — `gflow tools run storyboard` successfully deconstructed a cyberpunk scene into a cohesive 4-panel sequence; `reverse-engineer` tool extracts frames from video streams/URLs using `claude-video`'s `watch.py` and produces structured prompt components using Gemini multimodal models; dynamic token budgeting and strict Pyright types verified via test suite). Prior: [v0.34.0](LIVE_VERIFICATION_v0.34.0.md) (**#299 `--ui-mode` gate proven live, ZERO credits** — drove `get_ui_driver` directly over 4 real editor loads, never generated: bidirectional switch works [classic→agentic via `_force_agent_mode`, agentic→classic via `_exit_agent_mode`, each DOM-reverified], `agentic`-when-already-agentic is idempotent, and a timed-out toggle → **exit-28 fail-fast before submission**; deprecation behavior-change [`prefer_classic`→exit 28] confirmed). Prior: [v0.33.0](LIVE_VERIFICATION_v0.33.0.md) (**#287-follow-up picker fix proven live on the original repro** — the v0.32.1-failing `i2v <uuid> --project <crowded>` command now exits 0 with a real 3.0 MB `ftyp` mp4, `frame_ref_attached` + `video_saved`, zero uploads; **#241 jitter live-verified on both paths** — flag `--jitter 4-6` → `batch_jitter_sleep seconds=4.98`, and the new 0.5–1.5 s default → `seconds=1.47`, each firing exactly once between two t2i submissions; environment note: the denon82 cohort is now natively agentic and round-2 generations hit the pre-existing #281 `MediaAttributionError`, not a regression). Prior: [v0.32.1](LIVE_VERIFICATION_v0.32.1.md) (**#293 teardown fix live-verified credit-free** — error-path aborts leave ZERO chrome.exe holding the profile [3× leak reproduced pre-fix same day]; force-close fallback + ProfileLockedError translation unit-pinned; #283 wave logic fixes mock-verified to exact call counts). Prior: [v0.32.0](LIVE_VERIFICATION_v0.32.0.md) (**#287 UUID i2v frames proven live e2e** — an in-project asset selected by media UUID in the frame-slot dialog [frame_ref_attached, startImage bound on the wire, ZERO upload events] produced a real 720×1280 interpolation, resolving the #237 negative prior; foreign UUID → exit 9 pre-generation with screenshot; **#288 duration fail-fast proven live** — exit 23 pre-submit saved a 10-credit generation, and the debug screenshot confirmed the duration control is ABSENT from the cohort's settings popover [locale hypothesis refuted]; upload-400 exit-27 repro deferred-with-reason — the original rejected JPEG no longer exists). Prior: [v0.31.0](LIVE_VERIFICATION_v0.31.0.md) (**#281 wrong-media defenses live-verified in BOTH directions, credit-free** — correct attribution downloads with real wire metadata [seed, 768×1376]; the incident-class lazy-render ambiguity reproduced live and hard-stopped with `MediaAttributionError` exit 26 naming every candidate UUID, no file written; **#282 two-UUID-ref i2i proven e2e** — both freshly generated portrait UUIDs picker-selected into one scene with both canonical identities visually transferred). Prior: [v0.30.0](LIVE_VERIFICATION_v0.30.0.md) (**agentic-cohort image path + both fixes live-verified credit-free** — native 768×1376 stills, i2i-chain + canonical-ref identity hold; the character-create `DataIntegrityError` and the `prefer_classic` WARNING were observed live then fixed [recorder idempotent + INFO log]; MCP video-param feature deferred-with-reason on Veo credits, per the stills-only goal). Prior: [v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
 **"Where is the reverse-engineered wire protocol for a feature?"** → the `*_RECON.md` design docs: [CHARACTER_RECON](CHARACTER_RECON.md) (Flow character entity protocol), [IMAGE_UPSCALE_RECON](IMAGE_UPSCALE_RECON.md) (`/v1/flow/upsampleImage` wire). Naming convention: one `<FEATURE>_RECON.md` per reverse-engineered surface, kept as the durable spec after the feature ships. Pre-capture research recons: [ASSET_TAGGING_RECON](ASSET_TAGGING_RECON.md) (`@`-mention asset tagging — shipped in v0.40.0, see [LIVE_VERIFICATION_v0.40.0](LIVE_VERIFICATION_v0.40.0.md)).
 **"What was live-verified for the data layer (PR #58)?"** → [LIVE_VERIFICATION_data_layer](LIVE_VERIFICATION_data_layer.md) — 1 Imagen + 1 Veo credit on denon82, 6-layer ledger (file + magic + Pillow + DB rows + CLI round-trip + structlog)
 **"What was live-verified for the video-download feature (#29)?"** → [LIVE_VERIFICATION_video_download](LIVE_VERIFICATION_video_download.md)

gflow_cli-0.46.0/docs/LIVE_VERIFICATION_v0.46.0.md

@@ -0,0 +1,135 @@
+# Live Verification — v0.46.0
+
+**Date:** 2026-07-28
+**Feature under test:** provider-agnostic prompt-tools transport ([#387](https://github.com/ffroliva/gflow-cli/issues/387), PR [#400](https://github.com/ffroliva/gflow-cli/pull/400))
+**Verifier:** repo owner, local Windows 11 workstation
+**Credit cost:** zero — the prompt tools call an LLM endpoint, never Flow's generation API.
+
+## Why this release needs live verification
+
+The whole point of #387 is that gflow now talks to an **external service it does not
+control**, chosen at runtime by the user. Offline tests inject a fake transport — which
+is precisely the seam under test — so they cannot prove the wire format is right. Two
+defects in this release were invisible to a fully green offline suite and were caught
+only here (see §4).
+
+---
+
+## 1. Endpoint capability spike
+
+`scripts/diag/spike_387_openai_compat.py`, stdlib `urllib` (deliberately not the `openai`
+SDK — an SDK would paper over the header/param quirks this exists to discover).
+
+| Probe | freellmapi (non-Google) | Google compat endpoint |
+|---|---|---|
+| text `chat/completions` | PASS 0.7 s | PASS 0.5 s |
+| `temperature` + `max_tokens` | PASS 0.5 s | PASS 0.5 s |
+| **multimodal `image_url` data URI (semantic)** | **PASS** — answered `'Red'` | **PASS** — answered `'Red'` |
+| bad key ⇒ 4xx | 401 | 400 |
+
+Probe 3 is deliberately **semantic**, not status-based: it generates a solid-red 64×64
+JPEG and asks the model for the colour. A gateway that silently drops the image part
+still returns HTTP 200 with plausible prose, so a status check would prove nothing.
+
+**Consequences settled rather than assumed:** multimodal works on both, so the native
+Gemini `inlineData` path was deleted outright with no dual-path fallback;
+`max_completion_tokens` is not needed; and 0.5–1.2 s latency against a 60 s budget means
+no configurable timeout knob was added.
+
+---
+
+## 2. Five-layer ledger — real CLI, real endpoints
+
+Exercised through `gflow tools run creative-director … --json`, i.e. the production code
+path, not a test harness.
+
+| # | Layer | Evidence |
+|---|---|---|
+| 1 | Command exits 0 | `gflow tools run creative-director "cat in space" --json` → exit 0 |
+| 2 | Response shape | `{"name","original","expanded","was_expanded"}`, `was_expanded: true` |
+| 3 | Content actually rewritten | 12-char input → 1096-char output; `original_len=12 expanded_len=1096` in the structlog event |
+| 4 | structlog invariants | `prompt_expander_endpoint host=127.0.0.1:3001` (audit trail), then `prompt_expanded model=gemini-2.5-flash` |
+| 5 | User-confirmable artifact | Full five-component rewrite returned — named camera body, nebula setting, lighting, composition |
+
+### Configuration matrix
+
+| Configuration | Expected | Observed |
+|---|---|---|
+| gateway + key + model | rewritten | `was_expanded: true`, host `127.0.0.1:3001` |
+| gateway + key, **no model** (gateway chooses) | rewritten | `was_expanded: true` |
+| **key only** (default Google endpoint) | rewritten | `was_expanded: true`, host `generativelanguage.googleapis.com` |
+| removed `GFLOW_CLI_GEMINI_API_KEY` only | loud warning + no-op | stderr warning emitted; `prompt_expander_not_configured`; `was_expanded: false` |
+| nothing configured | silent no-op, **no network call** | `prompt_expander_not_configured`; `was_expanded: false`; no endpoint log |
+
+The fourth row is the one that matters for a breaking change: because the prompt tools
+never fail a run, an unmigrated user would otherwise see no error at all — just silently
+un-rewritten prompts on full-price generations.
+
+---
+
+## 3. Integration suite
+
+`tests/integration/test_expander_gateway.py`, `containers` marker, skips cleanly when no
+endpoint is reachable so CI and other contributors are unaffected.
+
+| Target | Result |
+|---|---|
+| Google compat endpoint | **6 / 6 passed** |
+| freellmapi gateway | 4 passed, **2 skipped on a proven HTTP 429** |
+
+Rate limiting is classified, not swallowed: the expander never raises, so a failed
+expansion carries no reason. On failure the helper makes one raw probe and skips **only**
+when a 429 is proven — a genuine transport break still fails the suite. The 429 was the
+gateway's free-tier quota (`"All models exhausted. Add more API keys or wait for rate
+limits to reset."`), reached after repeated runs; the retry loop backed off three times
+and fell back cleanly, which is the designed behaviour.
+
+---
+
+## 4. Defects found *here* that the offline suite missed
+
+Both were found with 2849 offline tests passing.
+
+1. **Google's compat endpoint has no server-side default model.** Omitting `model`
+   returns `400 "model is not specified"`, which the never-raise contract turns into a
+   silent no-op — the default configuration was broken while every unit test passed.
+   Omitting the model is correct only for a *user-chosen* gateway; the default endpoint
+   now ships a matching default. Pinned by a regression test.
+2. **The first redirect guard did not work.** `urllib.request.build_opener()` installs
+   its default handler set regardless of what you pass it, so omitting
+   `HTTPRedirectHandler` left redirects enabled — meaning `Authorization` would still
+   have been replayed cross-host. The handler had to be *replaced*. Caught because the
+   test asserts the behaviour (`redirect_request` returns `None`) rather than the
+   handler list.
+
+A third was found while running the release gates: `tests/e2e/test_tools_e2e.py` gated on
+the removed `GFLOW_CLI_GEMINI_API_KEY`, so it would have skipped forever while appearing
+healthy.
+
+---
+
+## 5. Not verified this cycle
+
+- **Keyless gateway against a real server.** Header omission is proven by unit test
+  (`test_authorization_header_omitted_when_keyless`), but no keyless endpoint was
+  available — freellmapi requires its unified key. The code path is identical apart from
+  the absent header.
+- **`--tool` on a real generation command** (`image t2i --tool …`). The tool layer is
+  verified end to end above; the generation wiring is unchanged by this release and is
+  covered by `tests/e2e/test_tools_e2e.py`, which is gated on an authenticated profile.
+
+---
+
+## Gate summary
+
+| Gate | Result |
+|---|---|
+| Offline suite | 2849 passed, 5 skipped |
+| Coverage | 91% (floor 80%) |
+| ruff · ruff-format · pyright | clean · clean · 0 errors |
+| repo hygiene · doc links · website PII · mirror+nav | all pass |
+| CI on PR #400 | 13/13 pass |
+| SonarCloud quality gate | **GREEN** — zero new issues |
+| `/ponytail-review` xhigh | 3 cuts applied |
+| `security-review` | no HIGH/MEDIUM findings |
+| `/code-review high` | **not run** — user-triggered only, cannot be launched by the agent |

{gflow_cli-0.45.0/website → gflow_cli-0.46.0}/docs/PROMPT_EXPANSION.md

@@ -3,8 +3,8 @@
 `creative-director` is the first built-in [tool](TOOLS.md). It rewrites a terse prompt into a
 single, vivid, self-contained prompt using Google's officially validated **five-component
 formula**, optionally injecting domain-specific (cinema / portrait / product / …) vocabulary, and
-deterministically strips low-signal "quality-booster" keywords. It calls the public **Gemini API**
-server-side and is **never fatal** — any failure degrades to your original prompt.
+deterministically strips low-signal "quality-booster" keywords. It calls any **OpenAI-compatible**
+endpoint server-side and is **never fatal** — any failure degrades to your original prompt.
 
 > This is the tool. For the framework that hosts it (`gflow tools`, `--tool`, the TOML schema, MCP
 > exposure), see [TOOLS.md](TOOLS.md).
@@ -14,8 +14,9 @@ server-side and is **never fatal** — any failure degrades to your original pro
 ## 1. Quick start
 
 ```console
-# 1. Get a Gemini API key: https://aistudio.google.com/apikey
-export GFLOW_CLI_GEMINI_API_KEY="..."
+# 1. Point at any OpenAI-compatible endpoint. A Google key works out of the
+#    box against the default endpoint: https://aistudio.google.com/apikey
+export GFLOW_CLI_LLM_API_KEY="..."   # any OpenAI-compatible endpoint; see CONFIGURATION.md
 
 # 2. Preview an expansion (free of Flow credits)
 gflow tools run creative-director "a cat on a couch" --style cinema
@@ -25,7 +26,7 @@ gflow image t2i "a fox in the snow" --tool creative-director:style=cinema
 gflow video t2v "a city at night"  -t creative-director:style=cinematic
 ```
 
-Without `GFLOW_CLI_GEMINI_API_KEY` the tool silently leaves your prompt unchanged (see §6).
+Without `GFLOW_CLI_LLM_API_KEY` (or `GFLOW_CLI_LLM_BASE_URL`) the tool leaves your prompt unchanged (see §6).
 
 ---
 
@@ -40,7 +41,7 @@ Without `GFLOW_CLI_GEMINI_API_KEY` the tool silently leaves your prompt unchange
 | **Provenance** | `AppliedTool(name, version, model, config_hash, params)` | Recorded in history when a tool rewrote a prompt. |
 
 The tool itself lives in [`src/gflow_cli/tools/`](../src/gflow_cli/tools/): `spec.py` (schema),
-`runtime.py` (`apply_tool`), `expander.py` (the Gemini-backed `PromptExpander`), `banned.py`
+`runtime.py` (`apply_tool`), `expander.py` (the provider-agnostic `PromptExpander`), `banned.py`
 (keyword stripping), `invocation.py` (provenance + MCP adapter).
 
 ---
@@ -134,17 +135,22 @@ prompt the tool left unchanged is never altered.
 
 ## 6. Never-fatal contract
 
-The Gemini-backed `PromptExpander` ([`expander.py`](../src/gflow_cli/tools/expander.py)) is
+The `PromptExpander` ([`expander.py`](../src/gflow_cli/tools/expander.py)) is
 stdlib-only (`urllib`) and bounded. `expand()` returns the original prompt with
 `was_expanded=False` — never raising — in every degraded case:
 
-- `GFLOW_CLI_GEMINI_API_KEY` is missing.
+- Neither `GFLOW_CLI_LLM_API_KEY` nor `GFLOW_CLI_LLM_BASE_URL` is set.
+- `GFLOW_CLI_LLM_BASE_URL` is wrong (bad host, missing `/v1`).
+- `GFLOW_CLI_LLM_MODEL` names a model the endpoint does not serve.
 - Any HTTP error, network failure, timeout, or malformed JSON.
 - An empty, whitespace-only, or quote-only model response.
 
 Retryable statuses (`429, 500, 502, 503, 504`) are retried with exponential backoff (default 3
-attempts, base delay 1s, doubling); **`401` / `403` fail fast** (and still degrade to the
-original). Each attempt has a 20s socket timeout, and the whole call is bounded by an **overall
+attempts, base delay 1s, doubling); every other 4xx **fails fast** (and still degrades to the
+original). Providers disagree on the code for a bad key — most gateways answer `401`, Google's
+compat endpoint answers `400` — but neither is retryable, so both fall back immediately rather
+than burning the retry budget. Each attempt has a 20s socket timeout, and the whole call is
+bounded by an **overall
 ~60s wall-clock budget** (`max_total_seconds`): retries stop once the budget is spent and each
 attempt's timeout is clamped to the remaining budget, so sustained rate limiting can never stall a
 batch for the full timeout×retries schedule. (Both bounds are fixed defaults, not env-tunable.)
@@ -154,15 +160,25 @@ abort a generation** — the worst case is "your prompt went through unchanged."
 
 ---
 
-## 7. Gemini wiring (I/O)
+## 7. LLM wiring (I/O)
+
+The transport speaks the **OpenAI Chat Completions API** — the format OpenAI, gateways/proxies,
+local runtimes and Google's compatibility endpoint all accept. See
+[CONFIGURATION.md](CONFIGURATION.md#prompt-tools-llm-gflow_cli_llm_) for the full env-var
+reference and worked examples (Google, OpenRouter, a local Docker proxy, keyless Ollama).
 
 | Aspect | Value |
 |---|---|
-| Endpoint | `https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent` |
-| Auth | API key in the `x-goog-api-key` header (never on the query string). |
-| Default model | `gemini-2.5-flash` (TOML `config.model`; `GFLOW_CLI_GEMINI_MODEL` overrides globally). |
-| Request | `system_instruction` = built instruction; user `contents` = the (truncated) prompt; `temperature=0.7`, `maxOutputTokens=1024`. |
-| Response | First candidate's text, cleaned (quote-stripped, truncated). |
+| Endpoint | `{GFLOW_CLI_LLM_BASE_URL}/chat/completions` — default base `https://generativelanguage.googleapis.com/v1beta/openai` |
+| Auth | `Authorization: Bearer <GFLOW_CLI_LLM_API_KEY>`, in the header, never the query string. **Omitted entirely** when no key is set, for keyless local gateways. |
+| Redirects | Never followed — `urllib` would re-send the `Authorization` header to whatever host a redirect names. |
+| Model | TOML `config.model` pin > `GFLOW_CLI_LLM_MODEL` > default-endpoint default > omitted so the gateway chooses. The builtins pin nothing. |
+| Request | `messages` = `[{role: system, content: instruction}, {role: user, content: prompt}]`; `temperature=0.7` (0.4 multimodal); `max_tokens` derived from `max_output_chars`. |
+| Multimodal | Images ride the user message as `{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,…"}}` parts. |
+| Response | `choices[0].message.content`, cleaned (markdown fence and wrapping quotes stripped, truncated). `null` content — a refusal — degrades to the original. |
+
+> The system instruction is a **separate `system` message**, not concatenated onto the user's
+> prompt as it was under the Gemini-native shape.
 
 ---
 
@@ -222,8 +238,9 @@ UX from agent-invoked tools), but no new work should depend on it. See
 
 | Env var | Default | Purpose |
 |---|---|---|
-| `GFLOW_CLI_GEMINI_API_KEY` | — | Required to actually rewrite prompts. [Get a key](https://aistudio.google.com/apikey). |
-| `GFLOW_CLI_GEMINI_MODEL` | `gemini-2.5-flash` | Global override of the tool's default model. |
+| `GFLOW_CLI_LLM_BASE_URL` | Google compat endpoint | OpenAI-compatible endpoint. The on/off switch. |
+| `GFLOW_CLI_LLM_API_KEY` | — | Credential for that endpoint; optional for a keyless local gateway. [Google key](https://aistudio.google.com/apikey). |
+| `GFLOW_CLI_LLM_MODEL` | — | Model, and therefore the provider selector. |
 | `GFLOW_CLI_HISTORY_PROMPTS` | `store` | `redacted` withholds the expanded prompt and minimizes the recorded tool descriptor (§8). |
 
 See [CONFIGURATION.md](CONFIGURATION.md) for the full precedence chain.

{gflow_cli-0.45.0 → gflow_cli-0.46.0}/docs/SECURITY.md

@@ -11,7 +11,7 @@
 | Console/JSON output under `GFLOW_CLI_DEBUG_TRACEBACK` (opt-in, off by default) | Raw exception text may echo tokens/cookies present in error state, especially if piped to a shared/persistent system (CI logs, aggregators) | Medium–High (depends on destination) |
 | Generated outputs (`$GFLOW_CLI_OUTPUT_DIR/...`) | Unwanted disclosure | Medium (depends on content) |
 | Local database (`$GFLOW_CLI_HOME/gflow.db`) | Disclosure of prompt history and asset provenance | Low–Medium (depends on prompt content; use `GFLOW_CLI_HISTORY_PROMPTS=redacted` to reduce) |
-| `.env` file with `GFLOW_CLI_GEMINI_API_KEY` | Theft → API quota theft, billing | Medium |
+| `.env` file with `GFLOW_CLI_LLM_API_KEY` | Theft → API quota theft, billing | Medium |
 | Project-internal logs | Leaking prompts / asset IDs | Low |
 
 ## What we don't do
@@ -41,7 +41,7 @@
 
 Not used by v0.4.0a2's reverse-engineered Flow provider. Documented here in advance of `GFLOW_CLI_PROVIDER=official`.
 
-- **Location:** `$GFLOW_CLI_GEMINI_API_KEY` env var, optionally loaded from a `.env` file in the directory where you invoke `gflow` or from `$GFLOW_CLI_HOME/.env` (CWD wins on conflicts; see [CONFIGURATION.md](CONFIGURATION.md#env-loading)). Treat BOTH locations as secret-bearing files: keep `$GFLOW_CLI_HOME/.env` user-readable only and out of shared images/backups.
+- **Location:** `$GFLOW_CLI_LLM_API_KEY` env var, optionally loaded from a `.env` file in the directory where you invoke `gflow` or from `$GFLOW_CLI_HOME/.env` (CWD wins on conflicts; see [CONFIGURATION.md](CONFIGURATION.md#env-loading)). Treat BOTH locations as secret-bearing files: keep `$GFLOW_CLI_HOME/.env` user-readable only and out of shared images/backups.
 - **In memory:** Held only in the `Settings` dataclass, never logged.
 - **In transit:** Sent only to `generativelanguage.googleapis.com` over HTTPS.
 - **Rotate:** Set a new value in `.env`, restart the CLI. No persistence beyond the env var.