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

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

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

{gflow_cli-0.44.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.44.0 → gflow_cli-0.46.0}/.pre-commit-config.yaml

@@ -23,8 +23,10 @@
 default_stages: [pre-commit]
 
 repos:
+  # Keep this rev in lockstep with the `ruff==` pin in pyproject.toml. A hook that
+  # formats with an older ruff than CI checks with will fight CI on every commit.
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.10
+    rev: v0.16.0
     hooks:
       - id: ruff
         args: [--fix]

{gflow_cli-0.44.0 → gflow_cli-0.46.0}/AGENTS.md

@@ -81,6 +81,23 @@ These rules exist because docs alone don't bind under momentum: a "check open PR
 - **If a claim can't be verified in the current environment, it's LIKELY — not CONFIRMED.** Keep the issue open, reference it with `Refs #N` (not `Closes #N`), and ship diagnostics rather than a blind fix. When you can't reproduce it, hand the fix to whoever can.
 - **This project reverse-engineers a blackbox.** gflow-cli doesn't own Google Flow — it drives real Flow through inspected HAR/DOM/browser-log behavior. Offline checks (types, lint, unit/BDD tests) verify *our* code does what we think it does; they cannot verify Flow still behaves the way we captured it. Every feature that touches a generation path is **live-verified**, not just offline-tested, before it's called done — see `/gflow:live-verify`.
 
+## Standard Workflow Sequence
+
+All AI agents and harnesses working on `gflow-cli` follow this standard 10-phase pipeline from issue discovery to public release:
+
+| Phase | Skill / Command | Purpose | Output Artifact |
+|---|---|---|---|
+| 1. Triage | `/gflow:issue-assessment <N>` | Read-only issue analysis & root cause hypothesis | `issue_assessment_<N>.md` |
+| 2. Pre-Implementation | `/gflow:predict <proposal>` | Adversarial audit (D14 YAGNI, security, risks) | GO / CAUTION / STOP verdict |
+| 3. BDD Scaffolding | `/gflow:scenario <feature>` | Edge-case explorer & BDD Gherkin spec | `Scenario:` blocks & test scaffold |
+| 4. Implementation Plan | `/gflow:plan <feature>` | Task-by-task atomic implementation plan | `docs/superpowers/plans/<date>-<slug>/PLAN.md` |
+| 5. Council Review | `/gflow:pr-council-review` / `llm-council` | Multi-dimensional audit across 6 core dimensions | Consensus verdict report |
+| 6. Task Execution | `/gflow:status` | Track unchecked tasks during TDD execution | Next unchecked task |
+| 7. Pre-Commit Quality | `/gflow:check` | The Impeccable Routine (hygiene, ruff, pyright, pytest) | All green local checks |
+| 8. Live Verification | `/gflow:live-verify` | 5-layer proof against real Flow transport | `docs/LIVE_VERIFICATION_vX.Y.Z.md` |
+| 9. PR & Issue Close | `/gflow:issue-resolve <N>` | PR, SonarCloud 0-issue gate, merge to develop | Closed GitHub issue |
+| 10. Release Pipeline | `/gflow:release` | Version bump, signed tag (`git tag -s`), PyPI publish | Shipped release & back-merge |
+
 ## Skills reference (cross-tool)
 
 The `skills/` directory ships installable agent skill docs in plain Markdown with YAML frontmatter. Any agent can consume them directly:

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

@@ -7,6 +7,140 @@ 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
+
+- **`gflow character create` binds portraits to the character again (#395).**
+  Two independent defects made every character generation land as a plain
+  project image, leaving the character empty:
+  1. **Overlay dismissal Escaped Flow's own UI.** `[role='dialog']` and
+     `[role='alert']` had been added to the overlay detector, but Flow's
+     character composer (and the media picker) carry those roles — so gflow
+     pressed Escape on the app itself, the generation went out without
+     `entityContext`, and Flow filed the image against the project with no
+     `parentEntityId`. Those two selectors are removed; `[role='banner']` and
+     the announcement matcher remain, so the original banner-dismissal intent
+     is intact.
+  2. **The character route could bounce back to the project page.** Flow
+     redirects `/project/{id}/character/{entityId}` when the entity is not yet
+     queryable — a race gflow loses by navigating immediately after
+     `flow.createEntity`. Because the project page also mounts a prompt box,
+     the old readiness check was satisfied on the wrong surface and the prompt
+     was typed into the **project** composer. gflow now verifies it actually
+     came to rest on the character route, re-navigating a few times and failing
+     loudly rather than generating on the wrong surface.
+
+  Verified live 2026-07-28 in both directions on the same account, plus a
+  read-back showing the character carrying its name and `thumbnail_media_id`.
+  The wire contract is documented in
+  [CHARACTER_RECON](docs/CHARACTER_RECON.md#entity-binding-entitycontext-captured-live-2026-07-28).
+
+- **`gflow image i2i --ref <UUID>` no longer fails when the asset is out of the
+  picker's reach (#393).** Flow's media picker is scoped to the active project
+  and its search does **not** index media UUIDs (confirmed live 2026-07-27:
+  both UUID search tiers returned zero tiles), so a `--ref` pointing at an asset
+  in another project — or buried deep in a virtualised grid — could not be
+  selected, and a bare `--ref <uuid>` carried no local file to fall back on. The
+  CLI now resolves each UUID ref against the local catalog and attaches its
+  recorded file, so the transport uploads those exact bytes instead of failing
+  the run. Verified live as a controlled A/B on identical input: exit 9 before,
+  exit 0 with the upload fallback after. Enrichment is best-effort (unknown
+  asset, unavailable catalog, or deleted file leaves the ref untouched) and the
+  **fail-loud contract is unchanged** — a reference that cannot be bound still
+  aborts the generation rather than silently producing an unreferenced image.
+- **A Flow web-app crash on the character-editor route is now reported as
+  such.** `gflow character create` surfaced Flow's client-side crash as
+  `RuntimeError: Character editor not ready: prompt textbox not visible`, which
+  blames a selector that was never on the page. The existing crash classifier is
+  now consulted at that gate too, yielding the typed, retryable `FlowAppError`
+  (exit 31). Observed live 2026-07-27 via the incident bundle's `ui.json`
+  (`title.category: flow_app_crash`).
+- **Character binding failures say what actually happened.** When Flow returns a
+  workflow that is not bound to the character entity, the error read "Unexpected
+  response shape from Flow", sending readers after a wire-format bug. It now
+  states that Flow filed the image as a plain project image and the character
+  has no portrait. The guard remains strict — verified live that unbound runs
+  leave the entity as "Untitled Character" with a null thumbnail.
+- **Tier-aware credit confirmations:** `gflow video chain` and `gflow movie run`
+  no longer present pending work as an exact one-credit-per-link/scene charge.
+  Plans, confirmation prompts, `--dry-run` output, Click help, and current docs
+  now report the count of *pending video operations* and direct operators to
+  Google Flow for current model/duration/tier pricing, which varies by account
+  tier and Flow policy. Execution, resume/stale accounting, `--yes`, JSON
+  output, flags, and exit codes are unchanged.
+
+### Added
+
+- **Top Banner & Modal Dismissal (#369):** Expanded `_detect_overlay` and
+  `_dismiss_blocking_overlays` in `ui_automation.py` to detect top banners,
+  alert bars, and announcement dialogs (`[role='banner']`, `[role='alert']`,
+  `[role='dialog']`, `div:has-text('What\'s new')`), force-clicking locale-stable
+  close/clear/Got-it buttons and falling back to Escape before automation tasks.
+- **`gflow character create --format-prompt` (#383):** Opt-in flag that clicks
+  Flow's in-editor **Format** button before submitting, letting Flow rewrite the
+  prompt into its character prompt-engineering shape. Applies to both the face and
+  body slots. Best-effort by design — if the button is not found the prompt is
+  submitted as typed rather than failing the generation. The selector cascade is
+  anchored on the locale-stable `personal_recommendations` Material Symbols
+  ligature (confirmed against live DOM 2026-07-27), not the "Format" label, which
+  Flow localises to the Chrome profile language. Flow ships the button `disabled`
+  on an empty prompt, so the driver checks enabled-ness — a disabled button is
+  still *visible*, and clicking one would stall on Playwright's actionability wait.
+- **Self-documenting error remediation & provider message pass-through (#380):** Added default `remediation_hint` strings across domain exception classes (`WireFormatError`, `ContentPolicyError`, `RateLimitError`, `DataStoreError`, `SceneConcatError`, `FrameExtractionError`), extracted and sanitized provider error messages from Google Flow tRPC/REST responses, and enriched MCP tool error envelopes and Rich CLI error displays with actionable recovery guidance at failure time.
+
 ## [0.44.0] — 2026-07-26
 
 ### Added
@@ -2384,7 +2518,9 @@ 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.44.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
 [0.42.0]: https://github.com/ffroliva/gflow-cli/compare/v0.41.0...v0.42.0

{gflow_cli-0.44.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.44.0 → gflow_cli-0.46.0}/KNOWN_ISSUES.md

@@ -824,6 +824,34 @@ gflow image batch ./batch-b.tsv --profile personal
 
 ## Resolved
 
+### `character create` generated portraits that never bound to the character — RESOLVED in v0.45.0
+
+- **Status:** Resolved ([#395](https://github.com/ffroliva/gflow-cli/issues/395)) · **Severity:** Was-High · **Was-affecting:** v0.44.0 and unreleased `develop` · **Fixed in:** v0.45.0
+
+Every `gflow character create` spent an Imagen credit, produced an image, and
+left the character empty ("Untitled Character", null thumbnail). Flow filed the
+generation as an ordinary project image because the request carried no
+`entityContext`. Two independent gflow defects caused it:
+
+1. **Overlay dismissal Escaped Flow's own UI.** `[role='dialog']` and
+   `[role='alert']` had been added to the overlay detector, but Flow's character
+   composer — and the media picker — carry those roles. gflow pressed Escape on
+   the app itself and the submit lost its entity context.
+2. **The character route could bounce to the project page.** Flow redirects
+   `/project/{id}/character/{entityId}` while the entity is not yet queryable
+   (gflow navigates immediately after `flow.createEntity`). The project page
+   also mounts a prompt box, so the readiness gate passed on the wrong surface
+   and the prompt was typed into the **project** composer.
+
+Both are fixed: the two over-broad selectors are gone (banner detection intact),
+and the transport now verifies it came to rest on the character route,
+re-navigating and then failing loudly instead of generating on the wrong
+surface. The `parentEntityId` guard that surfaced this was correct throughout —
+it refused to report a portrait-less character as success.
+
+Wire contract: [CHARACTER_RECON § entity binding](docs/CHARACTER_RECON.md#entity-binding-entitycontext-captured-live-2026-07-28).
+Evidence: [LIVE_VERIFICATION_v0.45.0 §2](docs/LIVE_VERIFICATION_v0.45.0.md).
+
 ### `gflow video`'s manifest-driven batch subcommand didn't skip already-completed entries — RESOLVED as obsolete
 
 - **Status:** Resolved (obsolete) · **Severity:** Was-Medium · **Was-affecting:** v0.2.0a1 through the command's removal · **Fixed in:** n/a — removed in production-readiness hardening (see `fix: remove nonfunctional video batch command`)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.44.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
@@ -58,7 +58,7 @@ Requires-Dist: numpy>=1.24; extra == 'dev'
 Requires-Dist: pyright>=1.1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Requires-Dist: ruff==0.15.22; extra == 'dev'
+Requires-Dist: ruff==0.16.0; extra == 'dev'
 Provides-Extra: gcs
 Requires-Dist: gcsfs>=2024.2.0; extra == 'gcs'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 'gcs'

{gflow_cli-0.44.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.44.0 → gflow_cli-0.46.0}/docs/CHARACTER_RECON.md

@@ -82,6 +82,76 @@ calls on the same `workflowId`, chaining `imageInputs` (BASE_IMAGE = prior outpu
 This is the SAME endpoint family gflow's existing image transport already drives — the new bits are
 `tool:"PINHOLE"`, `imageInputs` types, and the `parentEntityId`/workflow binding.
 
+## Entity binding: `entityContext` (captured live 2026-07-28)
+
+**The generation request must carry `entityContext`, or Flow files the image as a
+plain project image and the character stays empty.** Captured from Flow's own UI
+via a CDP-attached real Chrome (`gflow-agent-browser-spike`, `navigator.webdriver:
+false`) while driving the plain **New Character** flow.
+
+`POST /v1/projects/{projectId}/flowMedia:batchGenerateImages`
+
+```jsonc
+{
+  "clientContext": { "projectId": "…", "tool": "PINHOLE", "sessionId": "…" },
+  "mediaGenerationContext": {
+    "batchId": "…",
+    "entityContext": {
+      "entityId": "1e6c558e-87be-4aa7-8a21-ffb7efa43bbd",
+      "characterSlot": { "imageReferenceIndex": 0 }   // 0 = portrait/face, 1 = body
+    }
+  },
+  "useNewMedia": true,
+  "requests": [ { "imageModelName": "NARWHAL", "structuredPrompt": {…}, "seed": …, "imageInputs": [] } ]
+}
+```
+
+Response — bound on the first try:
+
+```jsonc
+"workflows": [ { "name": "30551aa7-…", "projectId": "…", "parentEntityId": "1e6c558e-…" } ]
+```
+
+### Which surface produces it
+
+The composer Flow renders depends on whether the character already HAS a
+portrait, not on which URL you arrived by:
+
+| Character state | Composer placeholder | Sends `entityContext`? |
+|---|---|---|
+| Empty (no portrait yet) | *"Describe your character…"* | **Yes** — this is the creation composer, on `/characters` **and** on `/character/{entityId}` |
+| Populated (portrait exists) | *"What do you want to change?"* | Edit surface — refines the existing portrait |
+
+Both entry points reach the creation composer for an empty character, and both
+bind. Verified live 2026-07-28: driving `/project/{id}/character/{entityId}` for
+a pre-created empty entity produced `entityContext` in the request and
+`parentEntityId` in the response — including for an entity gflow itself had
+created minutes earlier. Entity age is not a factor.
+
+`flow.createEntity` may be called by Flow (the **New Character** flow does it
+itself, returning `displayName: "Untitled Character"`) or by the client
+beforehand; gflow pre-creates and deep-links, which is fine. After the
+generation Flow issues `PATCH /v1/flowWorkflows/{id}` twice
+(`metadata.displayName`, then `metadata.primaryMediaId`) — the same commit gflow
+already performs. Flow never asks for a name up front: the user renames
+afterwards via the ✏️ next to the title, and "Character Info (optional)"
+(*"Describe how your character acts…"*) is a separate free-text field.
+
+**What actually broke gflow (#395)** was therefore NOT the choice of entry
+point. Two client-side defects suppressed `entityContext` on a surface that
+would otherwise have sent it:
+
+1. **Overlay dismissal pressed Escape on the composer.** `[role='dialog']` and
+   `[role='alert']` in the overlay detector matched Flow's own character
+   composer (and the media picker), so gflow dismissed the app itself.
+2. **The character route could bounce back to the project page** while the
+   entity was not yet queryable. The project page also mounts a prompt box, so
+   the readiness gate passed on the wrong surface and the prompt was typed into
+   the **project** composer.
+
+With both fixed, the deep-linked editor binds reliably. See
+[LIVE_VERIFICATION_v0.45.0 §2](LIVE_VERIFICATION_v0.45.0.md).
+
 ## Gaps
 
 1. ✅ **RESOLVED — Entity create.** `POST /fx/api/trpc/flow.createEntity` `{json:{projectId}}` →

{gflow_cli-0.44.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`
 
@@ -343,9 +413,9 @@ each link in turn, so total wallclock is the sum of all link waits).
 |---|---|---|
 | `--model` | `veo-lite` | `veo-lite` / `veo-fast` / `veo-quality` / `veo-lite-lp`. `omni-flash` is rejected — it can't seed i2v links (issue #125). |
 | `--max-links N` | unset | Cap link count; exit 11 (`ConfigurationError`) if the manifest has more. A spend guardrail. |
-| `-y` / `--yes` | off | Skip the per-credit cost confirmation prompt. |
-| `--dry-run` | off | Print the plan + credit estimate and spend nothing. |
-| `--resume-from CHAIN_ID` | unset | Resume a prior chain by its id; already-paid links are skipped (not re-billed). |
+| `-y` / `--yes` | off | Skip the pending video operation confirmation prompt. |
+| `--dry-run` | off | Print the pending video operation plan and submit nothing. |
+| `--resume-from CHAIN_ID` | unset | Resume a prior chain by its id; already-completed links are skipped (not regenerated). |
 | `--jitter F` | `0.0` | Random `0..F` second pause **between** links (anti-bot cadence; never before link 0). |
 | `--seed-offset MS` | `0` | Extract the seed frame this many ms before EOF (fade-to-black guard). |
 | `--aspect` | `9:16` | `9:16` / `16:9`. Applied uniformly to every link (continuity requirement). |
@@ -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.44.0 → gflow_cli-0.46.0}/docs/INDEX.md

@@ -55,6 +55,8 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | [docs/superpowers/plans/2026-07-18-asset-tagging/PLAN.md](superpowers/plans/2026-07-18-asset-tagging/PLAN.md) | Task-by-task implementation plan for asset tagging (spike gate → resolver → CLI/MCP → live e2e) | Tracking task-by-task execution of the `@`-mention feature |
 | [docs/superpowers/specs/2026-07-19-live-verify-design.md](superpowers/specs/2026-07-19-live-verify-design.md) | `/gflow:live-verify` design spec: pre-flight state check + per-feature live-verification gate generalizing release step 4b, council-reviewed | Reviewing or implementing the live-verification enforcement skill |
 | [docs/superpowers/plans/2026-07-19-live-verify/PLAN.md](superpowers/plans/2026-07-19-live-verify/PLAN.md) | Task-by-task implementation plan for `/gflow:live-verify` (skill file → AGENTS.md/check.md wiring → INDEX row) | Tracking task-by-task execution of the live-verify skill |
+| [docs/superpowers/plans/2026-07-27-tier-aware-credit-confirmations/SCENARIO.md](superpowers/plans/2026-07-27-tier-aware-credit-confirmations/SCENARIO.md) | Edge-case matrix for replacing fixed chain/movie credit estimates with truthful pending-operation guidance | Reviewing the financial-safety, resume, dry-run, and compatibility scenarios |
+| [docs/superpowers/plans/2026-07-27-tier-aware-credit-confirmations/PLAN.md](superpowers/plans/2026-07-27-tier-aware-credit-confirmations/PLAN.md) | TDD implementation plan for tier-aware chain/movie planning and confirmation output | Tracking the isolated runtime pricing-guidance bugfix |
 
 ## Agent commands
 
@@ -133,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.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)