gflow-cli 0.23.0__tar.gz → 0.25.0__tar.gz

{gflow_cli-0.23.0 → gflow_cli-0.25.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.23.0 → gflow_cli-0.25.0}/CHANGELOG.md

@@ -7,6 +7,116 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`--project` on `video t2v`/`i2v`/`r2v` (#233)**: generate into an existing Flow
+  project instead of always creating a scratch project, matching `image t2i`/`i2i`.
+  Lets programmatic callers (e.g. a multi-clip storyboard worker) share one project
+  across several video generations instead of leaving one throwaway project per clip.
+- **`project` parameter on the MCP `gflow_generate_image` / `gflow_generate_video`
+  tools**: mirrors the CLI `--project` flag so MCP callers can also target an existing
+  Flow project (validated against the same id format). Completes `--project` parity
+  across the CLI and MCP surfaces.
+
 ## [0.23.0] — 2026-07-01
 
 ### Added
@@ -1682,7 +1792,8 @@ shell-script template that branches on these codes.
 
 First skeleton. Not functional end-to-end yet.
 
-[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.23.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.24.0...HEAD
+[0.24.0]: https://github.com/ffroliva/gflow-cli/compare/v0.23.0...v0.24.0
 [0.23.0]: https://github.com/ffroliva/gflow-cli/compare/v0.22.0...v0.23.0
 [0.22.0]: https://github.com/ffroliva/gflow-cli/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/ffroliva/gflow-cli/compare/v0.20.1...v0.21.0

{gflow_cli-0.23.0 → gflow_cli-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.23.0
+Version: 0.25.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.23.0 → gflow_cli-0.25.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.23.0 → gflow_cli-0.25.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.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.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.25.0/docs/LIVE_VERIFICATION_v0.24.0.md

@@ -0,0 +1,38 @@
+# Live Verification — v0.24.0
+
+Release date: 2026-07-01. This release completes `--project` parity: `video
+t2v/i2v/r2v` gain `--project` (#233/#234) and the MCP `gflow_generate_image` /
+`gflow_generate_video` tools gain a `project` parameter (#235) — both let a caller
+target an existing Flow project instead of a scratch one.
+
+## Scope
+
+| Change | Surface | Verification |
+|---|---|---|
+| **#234** — `--project` on `video t2v/i2v/r2v` (CLI) | `cli_video.py`, `_cli_helpers.py` | ✅ Automated — behavior tests assert the id threads to `generate_video(project_id=...)` for all three modes; default (no flag) → scratch project; bad id rejected at the CLI boundary. Full council review GREEN + Sonar 100% new-coverage. |
+| **#235** — `project` param on MCP generate tools | `mcp/tools.py` | ✅ Automated — payload-threading tests assert `project` reaches `payload["project_id"]` (image + video), omitted → no `project_id`, bad id rejected before the worker. Reuses the CLI `_FLOW_ID_RE` validator. Council GREEN + Sonar pass. |
+
+## Nature of the change (why automated coverage is sufficient here)
+
+Neither change adds new generation plumbing: the worker/daemon already consumed
+`payload["project_id"]` (daemon.py:97 image, :168 video) and `FlowApiClient.generate_video`
+already accepted `project_id`. Both PRs only **surface + validate** the existing
+capability at the CLI and MCP boundaries, and thread it into the already-wired payload.
+The end-to-end "generate into an existing project" path (browser navigation to
+`project_editor_url(locale, project_id)` → `entering_existing_project`) is the same code
+prior releases exercised live for `image t2i --project`.
+
+## Live generation status
+
+A live credit-free run of `--project` against real Flow was **not** performed this cycle
+because the available `denon82` profile's Flow session is server-side expired (HTTP 401 —
+see [LIVE_VERIFICATION_v0.23.0](LIVE_VERIFICATION_v0.23.0.md)); exercising it requires an
+interactive `gflow auth login`. The project-targeting code path is shared with the
+already-live-verified `image t2i --project` path, and is fully covered by the automated
+behavior tests above.
+
+## Automated coverage
+
+- Full suite green on both PRs' CI (test matrix 3.11/3.12/3.13) at the merged tree.
+- `pyright src`: 0 errors. `ruff check` / `ruff format --check`: clean.
+- SonarCloud gate green on both PRs (#234 new-coverage 100%; #235 pass).

gflow_cli-0.25.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.23.0 → gflow_cli-0.25.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)`: Triggers text-to-image / image-to-image (Imagen / Nano Banana). `reference_images` switches to i2i.
-* `gflow_generate_video(prompt, mode, aspect, initial_frame, end_frame, reference_images, tools, profile)`: Triggers vertical or landscape video generation (Veo). `mode` is `t2v`/`i2v`/`r2v`; `i2v` requires `initial_frame`, `r2v` requires `reference_images`.
+* `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`). `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.23.0 → gflow_cli-0.25.0}/docs/PROJECT_STATUS.md

@@ -4,6 +4,19 @@
 
 ## Current release
 
+**v0.24.0 — alpha.** **`--project` parity across CLI + MCP.** The video commands
+(`video t2v`/`i2v`/`r2v`) gain `--project <id>` to generate into an existing Flow project
+instead of a scratch one (#233/#234), matching `image t2i`/`i2i`; and the MCP
+`gflow_generate_image` / `gflow_generate_video` tools gain a matching `project` parameter
+(#235), so agent callers get the same capability. Both surface an already-wired worker
+capability (`payload["project_id"]`) and validate the id identically. Carries forward
+v0.23.0 (MCP generation live + macOS 401 fix). Verification:
+[LIVE_VERIFICATION_v0.24.0](LIVE_VERIFICATION_v0.24.0.md).
+
+**Develop (unreleased, post-v0.24.0):** *(empty — develop is the staging branch for the next release).*
+
+<details><summary>v0.23.0 — MCP generation live + macOS 401 fixed</summary>
+
 **v0.23.0 — alpha.** **MCP generation goes live + macOS 401 fixed.** The MCP server's
 `gflow_generate_image` / `gflow_generate_video` tools — previously non-functional stubs —
 are now wired end-to-end to the FlowWorker queue (background worker owns download +
@@ -16,7 +29,7 @@ Carries forward v0.22.0 (Tools framework) + v0.21.0 (MCP server). Verification:
 [LIVE_VERIFICATION_v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP wiring proven live; #222
 reporter-verified e2e on macOS).
 
-**Develop (unreleased, post-v0.23.0):** *(empty — develop is the staging branch for the next release).*
+</details>
 
 <details><summary>v0.22.0 — Tools framework ("Creative Director")</summary>
 

{gflow_cli-0.23.0 → gflow_cli-0.25.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.23.0 → gflow_cli-0.25.0}/docs/USAGE.md

@@ -438,7 +438,11 @@ All prompts in a batch share one Flow project. The editor is opened once; each p
 Generate a video from a text prompt only.
 
 ```text
-gflow video t2v PROMPT [--model] [--duration] [--count] [--aspect] [--profile] [-t/--tool] [--out-dir]
+gflow video t2v PROMPT [--model] [--duration] [--count] [--aspect] [--profile] [-t/--tool] [--project] [--out-dir]
+
+Options:
+  --project ID          Generate in this EXISTING Flow project instead of a
+                        scratch project (see "Sharing one project across calls").
 ```
 
 ```bash
@@ -472,6 +476,8 @@ Arguments:
 Options:
   --initial-frame PATH  Initial frame to animate. Canonical form; replaces the positional IMAGE.
   --end-frame PATH      Optional end frame — Flow interpolates initial frame -> end frame.
+  --project ID          Generate in this EXISTING Flow project instead of a
+                        scratch project (see "Sharing one project across calls").
 ```
 
 ```bash
@@ -491,7 +497,9 @@ images. Per-model cap: `omni-flash` ≤7, the `veo-*` models ≤3. Fires
 gflow video r2v PROMPT --ref IMG [--ref IMG ...] [--model] [--duration] [--count] [--aspect] [...]
 
 Options:
-  --ref PATH  Reference image; repeat for up to 7 (omni-flash) / 3 (veo). [required]
+  --ref PATH    Reference image; repeat for up to 7 (omni-flash) / 3 (veo). [required]
+  --project ID  Generate in this EXISTING Flow project instead of a scratch
+                project (see "Sharing one project across calls").
 ```
 
 ```bash
@@ -499,6 +507,19 @@ gflow video r2v "a knight in this armor walks forward" --ref armor.png
 gflow video r2v "blend these worlds" --ref a.png --ref b.png --ref c.png --model omni-flash
 ```
 
+### Sharing one project across calls
+
+By default each `video t2v` / `i2v` / `r2v` call creates its own scratch Flow
+project. Pass `--project <id>` (same contract as `image t2i`/`i2i` — see
+[`gflow image t2i`](#gflow-image-t2i)) to generate into an existing project
+instead, e.g. to avoid one-throwaway-project-per-clip when scripting a
+multi-clip storyboard:
+
+```bash
+gflow video t2v "establishing shot" --project PROJ123
+gflow video t2v "close-up reaction" --project PROJ123
+```
+
 ## `gflow video batch`
 
 > ⚠️ **Not yet implemented.** The `batch` subcommand currently exits with
@@ -509,10 +530,12 @@ gflow video r2v "blend these worlds" --ref a.png --ref b.png --ref c.png --model
 ### Workaround — shell for-loop
 
 Until the manifest runner lands, you can drive sequential video generations
-through a plain shell loop. Each `gflow video t2v` / `i2v` / `r2v` call opens
-its **own Flow project**, so the resulting videos will NOT share a
-`project_id` (unlike `gflow image batch`, which mounts one project across
-all prompts) — but they DO get generated and downloaded:
+through a plain shell loop. Without `--project`, each `gflow video t2v` /
+`i2v` / `r2v` call opens its **own Flow project**, so the resulting videos
+will NOT share a `project_id` (unlike `gflow image batch`, which mounts one
+project across all prompts) — but they DO get generated and downloaded. Pass
+the same `--project <id>` to every call in the loop (see "Sharing one project
+across calls" above) if you want them to land in one project instead:
 
 ```bash
 # bash / WSL / macOS — one prompt per line

{gflow_cli-0.23.0 → gflow_cli-0.25.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.23.0"
+version = "0.25.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.23.0 → gflow_cli-0.25.0}/src/gflow_cli/__init__.py

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

{gflow_cli-0.23.0 → gflow_cli-0.25.0}/src/gflow_cli/_cli_helpers.py

@@ -35,6 +35,7 @@ been removed. Both error handlers now import
 
 from __future__ import annotations
 
+import re
 import sys
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal
@@ -70,16 +71,36 @@ _console = Console()
 # `reportPrivateUsage` rule does NOT honor the PEP 484 `from X import Y as Y`
 # re-export idiom for underscore names, so __all__ is the practical fix.
 __all__ = [
+    "_FLOW_ID_RE",
     "_handle_gflow_error",
     "_handle_unhandled_error",
     "_make_provider_dir",
     "_resolve_profile",
+    "_validate_project_id",
     "apply_tool_option",
     "run_with_handlers",
     "safe_path_text",
     "tool_option",
 ]
 
+# Flow project ids are interpolated into navigation URLs and CSS selectors
+# (page.goto, `data-tile-id='fe_id_<id>'`) before any other guard runs, so the
+# `--project` option on both `image t2i`/`i2i` and `video t2v`/`i2v`/`r2v`
+# validates against this allowlist at the CLI boundary. Mirrors
+# `routes._PROJECT_ID_RE`. Relocated here (T4b follow-up) so the two call-site
+# modules can't drift out of sync.
+_FLOW_ID_RE = re.compile(r"^[A-Za-z0-9\-]{1,128}$")
+
+
+def _validate_project_id(
+    _ctx: click.Context, param: click.Parameter, value: str | None
+) -> str | None:
+    """Reject a --project id that isn't alphanumeric/hyphen (1-128 chars)."""
+    if value is not None and not _FLOW_ID_RE.fullmatch(value):
+        msg = "project id must be 1-128 chars of letters, digits, or hyphens."
+        raise click.BadParameter(msg, param=param)
+    return value
+
 
 _TOOL_OPTION_HELP = (
     "Apply a prompt tool before generating, e.g. --tool creative-director or "

{gflow_cli-0.23.0 → gflow_cli-0.25.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).