gflow-cli 0.24.0__tar.gz → 0.26.0__tar.gz

{gflow_cli-0.24.0 → gflow_cli-0.26.0}/.env.template

@@ -1,7 +1,8 @@
 # gflow-cli — example environment variables.
-# Copy to `.env` in the directory where you invoke `gflow` and uncomment what
-# you want to override. ($GFLOW_CLI_HOME is NOT a .env search path — only the
-# current working directory is loaded.)
+# Copy to `.env` in the directory where you invoke `gflow` (project-local
+# overrides) or to `$GFLOW_CLI_HOME/.env` (machine-wide defaults; used by
+# processes with arbitrary working directories, e.g. the MCP server) and
+# uncomment what you want to override. On conflicts the CWD `.env` wins.
 # All variables are OPTIONAL — defaults work out of the box for most users.
 # Lines below are commented to show the SHIPPED DEFAULT — uncomment to override.
 

{gflow_cli-0.24.0 → gflow_cli-0.26.0}/CHANGELOG.md

@@ -7,6 +7,123 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.26.0] — 2026-07-06
+
+### Added
+
+- **Reference a generated image in `image i2i` by its Flow UUID (`gflow_generate_image`,
+  `reference_images`)**: pass a generated image's media UUID as a reference and gflow
+  attaches it by **selecting the already-existing asset in Flow's reference picker** —
+  it does **not** upload a duplicate copy (avoiding duplication is the preferred path).
+  The asset's tile is located by its media id in the thumbnail URL (robust to
+  display-name collisions), surfaced by a display-name search when it isn't already
+  visible, and attached in place. When the asset can't be located (e.g. it's in a
+  different project's picker), gflow falls back to uploading its on-disk local file. A
+  UUID that isn't in your catalog still attaches by media id (no error). Live-verified:
+  a generated image's UUID → i2i output that references it, with no duplicate upload.
+- **Generated images now record their Flow display name**: the display name is extracted
+  from the `batchGenerateImages` response's `workflows[]` array (previously ignored) and
+  persisted in the asset catalog — the searchable label the media picker shows, and what
+  the UUID-reference path searches by. (Original find and approach by **@C1ph3r404**,
+  #253/#255.)
+
+## [0.25.0] — 2026-07-06
+
+### Fixed
+
+- **Follow-up review fixes for remote image UUIDs (#237/#245)**: a post-merge
+  multi-angle review surfaced regressions and defects now corrected:
+  - Image `i2i` with a Flow media-id ref that isn't in the local catalog is no
+    longer rejected — UUID→display-name resolution is applied only to the video
+    paths (image refs attach by media id). Restores the `i2i` pass-through.
+  - The generation result envelope's `flow_media_id` again carries the real
+    media id (it was returning the asset's `flow_workflow_id`); the workflow id
+    is exposed under its own `flow_workflow_id` key.
+  - An in-catalog asset with no display name no longer returns its raw UUID as
+    the picker search term (which timed out); it fails fast with a clear error.
+  - Remote picker tiles match the display name exactly (`get_by_role(exact=True)`),
+    so a name that is a substring of another can't silently attach the wrong image.
+  - The R2V picker-close timeout matches the I2V budget (was a too-tight 8s that
+    aborted slow-but-successful attaches).
+  - `_attach_reference_audio` selects its tile by ARIA role+name instead of an
+    apostrophe-unsafe `:has-text()` selector.
+
+- **Remote-UUID video attach reworked to use local upload (#237)**: live
+  verification found the original mechanism — resolve the UUID to a display name
+  and select its tile in Flow's resource picker — could never work for generated
+  media: Flow's asset search does not index generation prompts, and generated
+  assets carry no display name, so the picker returned "No results found" and the
+  attach timed out. The UUID is now resolved to the image's on-disk local file and
+  attached through the existing, already-verified file-upload path. The failing
+  picker path is no longer used for video UUID refs. (Automatic download-by-media-id
+  for the rare case where the local file was pruned is a planned follow-up; for now
+  that case fails fast with a clear "Reference Not On Disk" error.)
+
+- **`gflow_generate_image` no longer silently saves a video as an image**: the
+  agentic image path has no explicit image-mode toggle — Flow's conversational
+  agent infers image-vs-video from the prompt and can produce a *video*, whose
+  tile is then scraped as if it were an image. The MP4 bytes were saved with a
+  `.png` suffix and catalogued as an image, a silent corruption that only
+  surfaced far downstream (Flow 400-rejects the file as an i2v frame → text-only
+  #125 fallback). `download_image` now detects video magic bytes (ISO-BMFF / WebM)
+  and fails loud with a `WireFormatError` naming the cause, instead of writing the
+  corrupt file. (Root cause — the agentic agent producing a video for an image
+  request — is tracked separately; this stops the silent corruption.)
+
+- **Rejected i2v/r2v frame uploads now fail loud instead of falling back to T2V**:
+  `_upload_via_open_dialog` matched the `uploadImage` response by URL only and
+  ignored its status, so a Flow 4xx rejection (e.g. an invalid image file) was
+  treated as success — the code committed an empty slot and the generation
+  silently produced a text-only video (#125). The upload status is now checked and
+  a rejection aborts with a clear error.
+
+### Added
+
+- **Remote image UUIDs in `gflow_generate_video` (#237)**: I2V (`initial_frame` /
+  `end_frame`) and R2V (`reference_images`) now accept a generated image's Flow UUID,
+  not just a local file path — pipe the output of an image generation straight into a
+  video generation. At enqueue time the UUID is resolved to the image's local file
+  (already on disk from the image generation) and attached through the same proven
+  file-upload path used for a local `--initial-frame`, so no picker name-search is
+  involved. A UUID that isn't in your asset catalog fails fast with a clear "Reference
+  Not Found" error, and a catalogued asset whose local file is missing fails fast with
+  "Reference Not On Disk" (re-generate it or pass a local path) — both instead of a
+  long browser timeout. (Contributed by @C1ph3r404; the attach mechanism was
+  reworked during maintainer live-verification — see Fixed below.)
+
+### Fixed
+
+- **Removed a shadowed duplicate `Settings.daemon_token` field definition (#243)**: the
+  class body defined `daemon_token` twice; Python silently kept only the second
+  (aliased) one, leaving the first as dead code that a future edit could touch without
+  effect. The surviving definition's contract (both `GFLOW_CLI_DAEMON_TOKEN` and
+  `GFLOW_DAEMON_TOKEN` accepted) is now pinned by tests, along with a guard that the
+  field is defined exactly once.
+
+- **`$GFLOW_CLI_HOME/.env` now loads as a dotenv fallback (#240)**: `config.py`'s own
+  module docstring promised a `.env` fallback "from CWD or `$GFLOW_CLI_HOME/.env`", but
+  the implementation only ever read the CWD file — a key placed in the home `.env` was
+  silently ignored (easy to miss under the prompt tools' never-fatal contract, and it
+  bites any process whose CWD is not a project root: the MCP server launched by a
+  desktop client, a worker service, a scheduled task). `Settings` now defaults the
+  standard pydantic-settings `_env_file` init kwarg to `($GFLOW_CLI_HOME/.env, ./.env)`
+  per construction, so explicit `Settings(_env_file=...)` — including the disable idiom
+  `_env_file=None` — keeps working. Precedence: process env vars beat both files, and a
+  CWD `.env` beats `$GFLOW_CLI_HOME/.env`.
+  - **Home resolution is coherent across every channel**: the home used to locate the
+    home `.env` now matches what `Settings.home` reports when `GFLOW_CLI_HOME` comes
+    from the process env (case-insensitively, as the env source matches it), from a
+    `GFLOW_CLI_HOME` entry in the CWD `.env`, or is set-but-empty (treated as unset
+    rather than `Path('.')`). The home `.env` itself cannot relocate home (circular).
+  - **Docs reconciled**: `docs/CONFIGURATION.md` § ".env loading", `docs/SECURITY.md`
+    (Gemini-key locations) and `.env.template` previously documented CWD-only loading
+    and now describe the two-file behavior; the `gflow serve` token hint no longer
+    points at `.env.local`, which was never a loaded file.
+  - **Worker daemon**: `FlowApiClient` constructions in `process_task` now receive the
+    daemon's cached settings instead of re-reading `.env` files live per task, so a
+    mid-run edit to the home `.env` can no longer produce a task whose client config
+    disagrees with the parameters the task derived from `get_settings()`.
+
 ## [0.24.0] — 2026-07-01
 
 ### Added

{gflow_cli-0.24.0 → gflow_cli-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.24.0
+Version: 0.26.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.24.0 → gflow_cli-0.26.0}/docs/CONFIGURATION.md

@@ -312,9 +312,11 @@ predictable external storage keys, set the bucket prefix in
 
 ## .env loading
 
-`gflow-cli` (via [`pydantic-settings`](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)) loads a single `.env` from the **current working directory** at startup. There is no second load from `$GFLOW_CLI_HOME` — keep your `.env` next to where you invoke `gflow`.
+`gflow-cli` (via [`pydantic-settings`](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)) loads **two** `.env` files at startup: `$GFLOW_CLI_HOME/.env` (machine-wide defaults — useful for processes whose working directory is arbitrary, like the MCP server or a worker service) and a `.env` in the **current working directory** (project-local overrides). On conflicting keys the CWD file wins.
 
-Variables already set in the actual environment always beat any `.env` file. Anything explicitly passed on the CLI beats everything else.
+The home used for the first file is resolved from the `GFLOW_CLI_HOME` env var, else a `GFLOW_CLI_HOME` entry in the CWD `.env`, else the platform default — the same home `Settings.home` reports. (By construction the home `.env` cannot relocate home itself; set the env var or the CWD `.env` instead.)
+
+Variables already set in the actual environment always beat both `.env` files. Anything explicitly passed on the CLI beats everything else.
 
 Use [`.env.template`](../.env.template) as your starting point:
 

{gflow_cli-0.24.0 → gflow_cli-0.26.0}/docs/INDEX.md

@@ -117,7 +117,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A gflow command hangs / fails — where do I start?"** → [DEBUGGING § Quick reference](DEBUGGING.md#quick-reference)
 **"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.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.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.
 **"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.26.0/docs/LIVE_VERIFICATION_v0.25.0.md

@@ -0,0 +1,97 @@
+# Live Verification — v0.25.0
+
+Release date: 2026-07-06. Headline change: **remote image UUIDs in
+`gflow_generate_video`** (#237), plus the `$GFLOW_CLI_HOME/.env` dotenv fallback
+(#240 — the minor-bump reason) and the shadowed-duplicate `Settings.daemon_token`
+removal (#243). Live verification of the #237 attach found — and this cycle fixed —
+that the originally-merged mechanism could not work, and surfaced two pre-existing
+silent-failure guards that are now fixed too.
+
+All live runs: 2026-07-06, headed Playwright, profile `ffroliva`, against real Flow.
+
+## Scope
+
+| Change | Surface | Verdict |
+|---|---|---|
+| **#237** — UUID image refs in `gflow_generate_video` | `mcp/tools.py`, `paths.py` | ✅ **Live e2e GREEN** after the attach was reworked (below) |
+| **#240** — `$GFLOW_CLI_HOME/.env` fallback | `config.py` | ✅ Live CLI precedence matrix + pinning tests |
+| **#243** — duplicate `daemon_token` removed | `config.py` | ✅ Automated (`tests/test_config.py`) — internal fix, no live surface |
+| Hardening — video-as-image download guard | `api/client.py`, `paths.py` | ✅ Unit-verified; root-caused live |
+| Hardening — rejected-upload fail-loud | `ui_automation_video.py` | ✅ Unit-verified; root-caused live |
+
+## #237 — remote image UUIDs → video (the rework)
+
+**The originally-merged mechanism was broken.** It resolved the UUID to a *display
+name* and searched Flow's resource picker for the tile. Instrumented live
+diagnostics (picker aria-tree + screenshots) proved generated media never appear
+in that picker: Flow's asset search does not index generation prompts, and
+generated assets carry no display name (0 of 190 catalogued assets had one), so
+the picker returned **"No results found"** and every attach timed out — in scratch
+projects and in the asset's own project alike.
+
+**Fix (this cycle):** the UUID is resolved to the image's on-disk local file
+(already saved by the image generation) and attached through the same proven
+file-upload path used for a local `--initial-frame`. No picker name-search.
+
+### Live end-to-end result — GREEN
+
+`gflow_generate_video(mode="i2v", initial_frame="<generated-image-UUID>", …)`
+driven through the **real stdio MCP server** (`gflow mcp run`), start frame a
+generated image (valid JPEG, `60dcb880…`). 5-layer ledger:
+
+1. **File count**: exactly one MP4 written (`d7749780-…-2ae354.mp4`).
+2. **Magic bytes**: `00 00 00 20 66 74 79 70 69 73 6f 6d` (`ftypisom`, valid ISO-BMFF MP4), 5.30 MB.
+3. **Shape**: `ffprobe` → h264, **720×1280** (9:16 as requested), duration **8.0 s**.
+4. **Structlog / wire invariants**: upload `status: 200`; generate route
+   **`batchAsyncGenerateVideoStartImage`** (the true i2v route, **not** the T2V
+   `batchAsyncGenerateVideoText` route); captured `startImage` bound; task
+   `status: completed`.
+5. **User-confirmable artifact**: a mid-clip frame shows the wooden **"v0.25.0"**
+   sign *animating* (drifting dust, camera push-in, "Veo" watermark) — a genuine
+   interpolation of the still start frame.
+
+### Fail-fast paths (also live-verified, credit-free)
+
+- Unknown UUID → RFC 9457 **`Reference Not Found`** in ~1.5 s via the real MCP
+  server (no browser, no timeout).
+- Catalogued asset with no on-disk file → **`Reference Not On Disk`** (re-generate
+  or pass a local path; auto download-by-media-id is a planned follow-up).
+
+## #240 — `$GFLOW_CLI_HOME/.env` fallback (live CLI matrix)
+
+Marker `GFLOW_CLI_DB_PATH` observed via `gflow data list images` from a foreign
+CWD: home-`.env` only loads ✅; CWD `.env` beats home ✅; process env beats both ✅;
+set-but-empty `GFLOW_CLI_HOME` treated as unset (default-home `.env` still loads)
+✅. Pinned by `tests/test_config.py`.
+
+## Hardening — two silent-failure guards (root-caused during this verification)
+
+The first e2e attempts failed at the frame upload with a confusing i2v→T2V (#125)
+fallback. Root cause was **not** the pipeline: the "image" fed as the start frame
+(`f94bdd3f…_1.png`) was actually an **MP4 video** — its magic bytes are `ftypisom`.
+
+1. **`gflow_generate_image` produced a video-as-`.png`.** The agentic image path
+   has no explicit image-mode toggle (`switch_to_image_mode` is a no-op) — Flow's
+   conversational agent infers image-vs-video from the prompt and produced a video,
+   whose tile `await_images` scraped as an image. The MP4 bytes were saved `.png`
+   (`extension_from_magic` only knows image formats) and catalogued as an image.
+   **Fix:** `download_image` now rejects video magic bytes (`looks_like_video`:
+   ISO-BMFF / WebM) with a `WireFormatError` instead of writing the corrupt file.
+2. **Rejected uploads were treated as success.** `_upload_via_open_dialog` matched
+   the `uploadImage` response by URL only and ignored its status, so a Flow **400**
+   (Flow correctly rejecting the non-image bytes) committed an empty slot → T2V
+   fallback. **Fix:** the upload status is checked (`_upload_rejection_message`) and
+   a 4xx aborts loudly.
+
+Both are pre-existing (present in 0.24.0) and unit-tested. The underlying "agentic
+agent produces a video for an image request" is tracked as a separate follow-up;
+these guards convert the resulting silent corruption into a clear, actionable error.
+
+## Automated coverage
+
+- `pyright src`: 0 errors. `ruff check` / `ruff format --check`: clean.
+  `check_doc_links.py`, `check_repo_hygiene.py`: clean.
+- New unit tests: UUID→local-path resolution + fail-fast cases (`tests/mcp`),
+  `looks_like_video` + `download_image` video rejection (`tests/test_paths.py`,
+  `tests/api/test_client_image.py`), `_upload_rejection_message`
+  (`tests/api/transports/test_ui_automation_video.py`).

gflow_cli-0.26.0/docs/LIVE_VERIFICATION_v0.26.0.md

@@ -0,0 +1,69 @@
+# Live Verification — v0.26.0
+
+Release date: 2026-07-06. Headline: **reference a generated image in `image i2i`
+by its Flow UUID**, attached by **selecting the already-existing asset** in Flow's
+reference picker rather than uploading a duplicate copy (the founder principle:
+avoid duplication). Plus generated images now record their Flow **display name**
+(the searchable picker label), extracted from the response's `workflows[]` array.
+
+Live run: 2026-07-06, headed Playwright, profile `ffroliva`, real Flow.
+
+## Scope
+
+| Change | Surface | Verdict |
+|---|---|---|
+| Image i2i UUID ref → **select existing asset** (no duplicate) | `mcp/tools.py`, `worker/daemon.py`, `api/image.py`, `api/transports/ui_automation*.py` | ✅ **Live e2e GREEN** |
+| Generated-image `display_name` from `workflows[]` | `api/dto.py`, `data/recorder.py` | ✅ Unit-tested (real captured sample); credited @C1ph3r404 |
+
+## Mechanism
+
+An `image i2i` `reference_images` entry that is a Flow media UUID is resolved at
+enqueue time (best-effort, never errors — an uncatalogued UUID still attaches by
+media id, PR #245) to the asset's `display_name` + on-disk `local_path`. The
+transport then **prefers selecting the existing asset in place**:
+
+1. Locate the tile by the **media UUID in its thumbnail URL** (`img[src*=<uuid>]`)
+   — robust to display-name collisions, needs no search term.
+2. If not already visible, **search the display name** to surface it, then re-locate
+   by UUID.
+3. Attach in place. (The image picker attaches on tile-click and auto-closes; the
+   code also handles the video-style explicit "Add to Prompt" include.)
+4. **Fallback — local upload** only when the asset can't be located (e.g. it lives
+   in a different project's picker) and a local file exists.
+
+## Live end-to-end result — GREEN
+
+`gflow_generate_image(prompt="the same rustic workshop wall, wider shot, more
+tools", reference_images=["60dcb880-…" (a generated image's UUID)],
+project="0f4e7eaa-…" (the asset's project), profile="ffroliva")` via the real
+stdio MCP server. 5-layer ledger:
+
+1. **Attach path**: structlog `ui_automation_video.image_ref_selected_existing`
+   fired — and **no** `image_ref_upload_fallback` / `image_uploaded` event. The
+   existing asset was selected; **no duplicate was uploaded**.
+2. **Wire**: the generation ran the `batchGenerateImages` route carrying the
+   reference `imageInput` — the ref reached the generation, not a plain t2i.
+3. **File**: exactly one output written, `bee1e8a9-…_1.jpg`, 893 KB.
+4. **Magic bytes**: `ff d8 ff e0` (valid JPEG); task `status: completed`.
+5. **User-confirmable artifact**: the output shows the **same** rustic workshop
+   wall and the "v0.25.0" sign as the referenced image, as a wider shot with more
+   tools — the i2i reference visibly took.
+
+### Pre-fix note
+
+The first live attempt selected the asset correctly but errored looking for a
+separate "Add to Prompt" button — the image picker attaches on tile-click and
+auto-closes (one step), unlike the video r2v picker. Fixed to treat an
+auto-closed dialog as success; the re-run above is GREEN. (A hung Chrome holding
+the profile's `SingletonLock` also caused two transient `launch_persistent_context`
+failures between runs — cleared by killing the process + removing the lock.)
+
+## Automated coverage
+
+- `_enrich_image_refs` unit tests (`tests/mcp/test_tools_helpers.py`): enriches a
+  catalogued ref with display_name + local_path; partial meta when no on-disk file;
+  uncatalogued UUID passes through with no error and no `ref_meta`.
+- `display_name` extraction tests (`tests/api/test_image_dto.py`) against the real
+  captured `06_batchGenerateImages.json` sample.
+- Full suite green (1994 passed; the one deselected `test_packaging` case is a
+  network-dependent sdist build, unrelated). `pyright src` 0 errors, ruff clean.

{gflow_cli-0.24.0 → gflow_cli-0.26.0}/docs/MCP.md

@@ -45,8 +45,8 @@ Both Click CLI (`src/gflow_cli/cli.py`) and MCP Server (`src/gflow_cli/mcp/`) ar
 The server registers three protocol surfaces:
 
 ### Tools (Executable actions)
-* `gflow_generate_image(prompt, model, aspect, count, seed, reference_images, tools, profile, project)`: Triggers text-to-image / image-to-image (Imagen / Nano Banana). `reference_images` switches to i2i; `project` generates into an existing Flow project id (mirrors CLI `--project`).
-* `gflow_generate_video(prompt, mode, aspect, initial_frame, end_frame, reference_images, tools, profile, project)`: Triggers vertical or landscape video generation (Veo). `mode` is `t2v`/`i2v`/`r2v`; `i2v` requires `initial_frame`, `r2v` requires `reference_images`; `project` generates into an existing Flow project id (mirrors CLI `--project`).
+* `gflow_generate_image(prompt, model, aspect, count, seed, reference_images, tools, profile, project)`: Triggers text-to-image / image-to-image (Imagen / Nano Banana). `reference_images` switches to i2i and accepts **either a local file path or a generated image's Flow media UUID**. A UUID reference is attached by **selecting the already-existing asset in Flow's reference picker — no duplicate copy is uploaded** (locating the tile by the media id in its thumbnail URL, and searching the recorded display name to surface it when needed); gflow falls back to uploading the asset's on-disk local file only when it can't be located in place (e.g. it lives in a different project's picker). `project` generates into an existing Flow project id (mirrors CLI `--project`) — pass the reference's project to keep it selectable in place.
+* `gflow_generate_video(prompt, mode, aspect, initial_frame, end_frame, reference_images, tools, profile, project)`: Triggers vertical or landscape video generation (Veo). `mode` is `t2v`/`i2v`/`r2v`; `i2v` requires `initial_frame`, `r2v` requires `reference_images`; `project` generates into an existing Flow project id (mirrors CLI `--project`). `initial_frame`, `end_frame`, and `reference_images` each accept **either a local file path or the Flow image UUID of a generated asset** — pass a generated image's id straight in to chain image→video, and gflow attaches it for you (the UUID is resolved to the asset's already-on-disk local file and uploaded as the frame; no manual download/re-upload step). A UUID that isn't in your local asset catalog is rejected up front with a clear "Reference Not Found" error; a catalogued asset whose local file is no longer on disk gives a "Reference Not On Disk" error (re-generate it or pass a local path).
 * `gflow_list_projects(profile, limit)`: Queries SQLite catalog for recent generation folders.
 * `gflow_list_characters(profile)`: Lists Flow Character entities (requires an active browser session).
 

{gflow_cli-0.24.0 → gflow_cli-0.26.0}/docs/SECURITY.md

@@ -39,7 +39,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` (CWD only — `$GFLOW_CLI_HOME` is not a `.env` search path; see [CONFIGURATION.md](CONFIGURATION.md)).
+- **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.
 - **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.

{gflow_cli-0.24.0 → gflow_cli-0.26.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.24.0"
+version = "0.26.0"
 description = "Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal."
 readme = "README.md"
 license = { file = "LICENSE" }

{gflow_cli-0.24.0 → gflow_cli-0.26.0}/src/gflow_cli/__init__.py

@@ -1,3 +1,3 @@
 """gflow-cli — unofficial CLI for Google Flow."""
 
-__version__ = "0.24.0"
+__version__ = "0.26.0"

{gflow_cli-0.24.0 → gflow_cli-0.26.0}/src/gflow_cli/api/client.py

@@ -64,7 +64,7 @@ from gflow_cli.errors import (
     WafRejectionError,
     WireFormatError,
 )
-from gflow_cli.paths import adjust_key_extension, character_output_path
+from gflow_cli.paths import adjust_key_extension, character_output_path, looks_like_video
 from gflow_cli.storage import AnyPath, storage_path, write_asset_async
 
 if TYPE_CHECKING:
@@ -1097,6 +1097,24 @@ class FlowApiClient:
             _raise_for_non_retryable(resp, await resp.text(), route=route)
         body = await resp.body()
 
+        # Fail loud if an image request downloaded video content. The agentic
+        # gflow_generate_image path has no explicit image-mode toggle — Flow's
+        # conversational agent infers image-vs-video from the prompt and can
+        # produce a video, whose tile await_images then scrapes as if it were an
+        # image. Saving those bytes with an image suffix is a silent corruption
+        # that only surfaces far downstream (e.g. Flow 400-rejects the file as an
+        # i2v frame -> #125 text-only fallback). Catch it at the download.
+        if looks_like_video(body):
+            raise WireFormatError(
+                detail=(
+                    "image download returned video content (ISO-BMFF/WebM magic "
+                    "bytes) — the agentic conversational agent likely produced a "
+                    "video instead of an image. Use a Classic UI profile "
+                    "(GFLOW_CLI_PREFER_CLASSIC=1) or rephrase the prompt."
+                ),
+                route=route,
+            )
+
         # Resolve the write target: local Path or cloud UPath.
         # Compute a relative key from out_path so cloud keys mirror the local
         # directory structure (images/YYYY-MM-DD/media_id_N.ext).

{gflow_cli-0.24.0 → gflow_cli-0.26.0}/src/gflow_cli/api/dto.py

@@ -8,7 +8,7 @@ KeyErrors leak.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from typing import TYPE_CHECKING, Any, Literal, cast
 
 if TYPE_CHECKING:
@@ -128,6 +128,10 @@ class GeneratedImage:
     fife_url: str  # CDN URL — usually expires after ~6 hours
     dimensions: tuple[int, int]  # (width, height)
     media_generation_id: str | None = None
+    # Flow-assigned display name (from the response's `workflows[]` array). This
+    # is the searchable label the media picker shows — recorded so a generated
+    # image can be referenced by name later. Original find by @C1ph3r404 (#253).
+    display_name: str | None = None
 
     @property
     def is_signed_url(self) -> bool:
@@ -172,8 +176,37 @@ class GeneratedImage:
         if not isinstance(media, list):
             msg = "unexpected batchGenerateImages response shape: media is not a list"
             raise ValueError(msg)
+        # Flow returns display names in a sibling `workflows[]` array keyed by
+        # workflow id (mirrors AssetInfo.from_upload_response). Build the lookup
+        # once and inject the name onto each parsed image. (Find by @C1ph3r404.)
+        workflow_names = cls._workflow_display_names(data.get("workflows"))
         items = cast("list[dict[str, Any]]", media)
-        return [cls.from_response_item(item) for item in items]
+        results: list[GeneratedImage] = []
+        for item in items:
+            img = cls.from_response_item(item)
+            name = workflow_names.get(img.workflow_id)
+            if name:
+                img = replace(img, display_name=name)
+            results.append(img)
+        return results
+
+    @staticmethod
+    def _workflow_display_names(workflows: object) -> dict[str, str]:
+        """Map workflow id → displayName from the response's ``workflows[]``."""
+        names: dict[str, str] = {}
+        if not isinstance(workflows, list):
+            return names
+        for w in cast("list[Any]", workflows):
+            if not isinstance(w, dict):
+                continue
+            entry = cast("dict[str, Any]", w)
+            w_id = entry.get("name")
+            metadata = entry.get("metadata")
+            if isinstance(w_id, str) and isinstance(metadata, dict):
+                display_name = cast("dict[str, Any]", metadata).get("displayName")
+                if isinstance(display_name, str) and display_name:
+                    names[w_id] = display_name
+        return names
 
 
 @dataclass(frozen=True)

{gflow_cli-0.24.0 → gflow_cli-0.26.0}/src/gflow_cli/api/image.py

@@ -185,11 +185,20 @@ class ImageRef:
     """A reference image for I2I, identified by the upload's media UUID.
 
     The wire shape is the dict returned by :meth:`to_wire`. The UUID comes
-    from a prior ``/v1/flow/uploadImage`` call (see
-    ``samples/captured/01_upload_image.json``).
+    from a prior ``/v1/flow/uploadImage`` call OR a generated image's media id
+    (see ``samples/captured/01_upload_image.json``).
+
+    ``display_name`` and ``local_path`` are UI-automation-only hints (ignored by
+    :meth:`to_wire`): they let the transport attach the ref by **selecting the
+    already-existing Flow asset in the picker** — located by ``name`` (the media
+    UUID) in the tile's image URL, surfaced by ``display_name`` when a search is
+    needed — and preferred over re-uploading a duplicate. ``local_path`` is the
+    fallback file to upload only when the asset can't be located in place.
     """
 
     name: str
+    display_name: str = ""
+    local_path: str = ""
 
     def __post_init__(self) -> None:
         # Reject empty, whitespace-only, AND whitespace-padded UUIDs.

{gflow_cli-0.24.0 → gflow_cli-0.26.0}/src/gflow_cli/api/transports/ui_automation.py

@@ -2110,6 +2110,16 @@ class UiAutomationTransport(VideoGenerationMixin):
         if request.ref_paths:
             await self._attach_references(page, list(request.ref_paths), out_dir=out_dir)
 
+        # Pre-generated image UUID refs: attach by selecting the EXISTING Flow
+        # asset in the reference picker (no duplicate upload — founder principle),
+        # falling back to uploading the local file only when it can't be located.
+        if request.refs:
+            await self._attach_image_uuid_refs(
+                page,
+                [(r.name, r.display_name, r.local_path) for r in request.refs],
+                out_dir=out_dir,
+            )
+
         # Entity references: attach locked CHARACTER entities via the Personagens
         # picker (inherited from the video transport). The entity must live in the
         # project we generate in (pass --project / project_id). Flow's JS then