gflow-cli 0.31.0__tar.gz → 0.32.0__tar.gz

{gflow_cli-0.31.0 → gflow_cli-0.32.0}/AGENTS.md

@@ -57,7 +57,7 @@ Or invoke the wrapper: `/gflow:check`.
 
 - Type hints everywhere; `pyright` strict on `src/gflow_cli`.
 - Structured logging only (`structlog`) — **never** raw `print()` or `import logging` in `src/`.
-- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–25, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`, 25 `FlowAgentUiError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
+- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–27, e.g. 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`, 25 `FlowAgentUiError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
 - 100-char line length, `ruff` configured. Imports sorted by `ruff` (isort rules).
 - **MCP & CLI Schema Symmetry**: Any updates or additions to user-facing CLI command parameters (e.g., `gflow image t2i`, `gflow video`) must be mirrored in the corresponding MCP tool definitions. Never add option/argument fields to Click commands without updating the MCP server implementation. This symmetry is enforced programmatically in CI via `tests/mcp/test_cli_parity.py` (every CLI leaf command needs a mapped MCP tool or an explicit, reasoned exemption) plus the schema checks in `tests/mcp/test_server.py`.
 

{gflow_cli-0.31.0 → gflow_cli-0.32.0}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.32.0] — 2026-07-11
+
+### Added
+
+- **`gflow video i2v` accepts an in-project asset media UUID for `--initial-frame` / `--end-frame` (and the positional IMAGE).** A UUID-shaped value selects the already-existing Flow asset in place via the same `_select_existing_asset` picker the image `--ref` flow uses (#282 scroll/search fixes included) instead of forcing a duplicate local-file upload — the duplicate-asset pileup and per-run re-upload from the 2026-07-11 chalkboard pilot. Pair with `--project` so the asset's project is the one generated in; a UUID that can't be located in the picker fails with `TransportTimeoutError` (exit 9) naming the slot and UUID (#287).
+
+### Fixed
+
+- **A Flow upload-endpoint rejection is now a typed error instead of "Unexpected error." (exit 1).** An `uploadImage` 4xx during frame/reference attach (observed live: one JPEG rejected with HTTP 400 while byte-identical-format siblings uploaded fine) raised a bare `RuntimeError` that fell through to the generic handler with no hint the *input image* was refused. It now raises the new `MediaUploadRejectedError` (**exit code 27**, RFC 9457 type `media-upload-rejected`) with a re-encode remediation hint (`ffmpeg -q:v 2 -map_metadata -1`) (#287).
+- **An explicit `--duration` that cannot be applied now fails fast instead of silently producing a clip of Flow's default length.** When the video settings panel's duration tab probe missed (observed 3/3 on a live 2026-07-11 Frames-submode run: `--duration 4` returned an 8-second clip and the JSON result reported success), `_select_video_duration` demoted the failure to a warning and generation continued on Flow's default. Duration is a contract parameter — downstream timeline math sizes cuts from the requested value — so a probe miss with an explicit `--duration` now raises `UiSelectorDriftError` (**exit code 23**, the #183 selector-drift semantics) with a `debug_no_duration_tab.png` viewport screenshot and an omit-`--duration` remediation hint. Omitting `--duration` is unaffected. Root cause confirmed live 2026-07-11: the duration control is absent from the affected cohort's settings popover (#288, #289).
+
 ## [0.31.0] — 2026-07-10
 
 ### Fixed
@@ -1908,7 +1919,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.30.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.32.0...HEAD
+[0.32.0]: https://github.com/ffroliva/gflow-cli/compare/v0.31.0...v0.32.0
+[0.31.0]: https://github.com/ffroliva/gflow-cli/compare/v0.30.0...v0.31.0
 [0.30.0]: https://github.com/ffroliva/gflow-cli/compare/v0.29.0...v0.30.0
 [0.29.0]: https://github.com/ffroliva/gflow-cli/compare/v0.28.0...v0.29.0
 [0.28.0]: https://github.com/ffroliva/gflow-cli/compare/v0.27.1...v0.28.0

{gflow_cli-0.31.0 → gflow_cli-0.32.0}/KNOWN_ISSUES.md

@@ -14,6 +14,63 @@ Living list of behaviour that's broken, surprising, or limited by design — alo
 
 ## Open
 
+### Flow's `uploadImage` endpoint rejects some JPEGs with HTTP 400 (metadata-sensitive)
+
+- **Status:** Open ([#287](https://github.com/ffroliva/gflow-cli/issues/287))
+- **Severity:** Low (typed + remediable) · **Affected:** i2v frame / reference uploads
+
+Observed live 2026-07-11: one JPEG was rejected with HTTP 400 while
+byte-identical-format siblings uploaded fine; re-encoding with
+`ffmpeg -q:v 2 -map_metadata -1` fixed it, implicating a metadata segment.
+Since #290 the rejection raises `MediaUploadRejectedError` (exit 27) with that
+remediation instead of a generic "Unexpected error." (exit 1). **Workaround:**
+re-encode the file, or reference the already-in-project asset by media UUID
+(`--initial-frame <UUID> --project <id>`). Root cause of Flow's metadata
+sensitivity is unidentified.
+
+### i2v frame-slot picker selection by UUID — RESOLVED live 2026-07-11
+
+- **Status:** **Verified live** ([#287](https://github.com/ffroliva/gflow-cli/issues/287) / PR [#290](https://github.com/ffroliva/gflow-cli/pull/290))
+- **Affected:** `gflow video i2v --initial-frame/--end-frame <UUID>`
+
+#290 routes i2v frame slots through `_select_existing_asset` (the UUID picker
+live-proven in the **Add-Media** dialog: v0.26.0 i2i-by-UUID, #282 scroll
+fixes). The **frame-slot** dialog carried a negative prior — #237's
+name-search there never surfaced generated media (v0.25.0 rework) — but the
+thumbnail-URL tile match succeeds where name search failed. Live evidence
+(2026-07-11, denon82): `frame_ref_attached {slot: Start}` → wire capture on
+`batchAsyncGenerateVideoStartImage` with the asset's `startImage` bound →
+SUCCESSFUL 720×1280 mp4; **zero** `image_uploaded` events (no duplicate
+upload). Negative check: a foreign UUID exits 9 pre-generation with a
+`debug_frame_ref_miss_start.png` screenshot. Caveat that stands: the asset's
+project must be entered via `--project`, and projects that open in the
+full-page media-library UI (#174) can fail earlier at `mode_switch_trigger`.
+
+### Video duration tab probe misses on the current Frames-submode DOM
+
+- **Status:** Open ([#288](https://github.com/ffroliva/gflow-cli/issues/288))
+- **Severity:** Medium · **Affected:** `gflow video` with an explicit `--duration`
+  on at least some Classic-profile cohorts (3/3 miss on a live 2026-07-11 run)
+
+The `duration_tab` selector cascade (`[role='tab']:text-is('4s')` /
+`:has-text('4s')`) fails to match on Flow's current Frames-submode settings
+panel. Pre-fix this silently produced a clip of Flow's default length; since
+the #289 fix the run fails fast with `UiSelectorDriftError` (exit 23) and a
+`debug_no_duration_tab.png` screenshot — live-verified 2026-07-11 on the
+denon82 profile (aborted pre-submit, saving the 10-credit generation).
+**Workaround:** omit `--duration` to accept Flow's default.
+
+**Root cause (confirmed live 2026-07-11, screenshot evidence on #288): the
+duration control is ABSENT from this cohort's settings popover** — the panel
+renders mode tabs (Imagem/Video), sub-mode (Frames/Elementos), aspect
+(9:16/16:9), count (1x–x4), and the model dropdown (Veo 3.1 - Lite), and
+nothing else. The earlier locale hypothesis is refuted: the UI renders in
+Portuguese and the sibling count tabs (`1x`/`x2`) match fine; there is simply
+no duration row to click. Whether Flow removed clip-length selection for this
+cohort/model or moved it elsewhere is unknown — until that's answered,
+`--duration` cannot be honored on affected cohorts and the fail-fast is the
+correct behavior, not a selector bug to patch.
+
 ### macOS: generation runs logged-out → HTTP 401, even with `--browser chrome`
 
 - **Status:** **RESOLVED in v0.23.0** ([#222](https://github.com/ffroliva/gflow-cli/issues/222),

{gflow_cli-0.31.0 → gflow_cli-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.31.0
+Version: 0.32.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.31.0 → gflow_cli-0.32.0}/docs/INDEX.md

@@ -122,7 +122,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.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.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.
 **"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.32.0/docs/LIVE_VERIFICATION_v0.32.0.md

@@ -0,0 +1,74 @@
+# Live verification — v0.32.0 (2026-07-11)
+
+Scope: the two user-facing changes of this release, exercised against live Flow
+on the `denon82` profile (Classic strategy, Chrome, Windows 11; Flow renders in
+Portuguese for this profile — `/fx/pt/` redirect). Credits spent: **1 image +
+1 video generation**; every failure-path check completed pre-submit at zero
+credit cost.
+
+## 1. `gflow video i2v --initial-frame <UUID>` — in-project asset selection (#287, PR #290)
+
+The declared-riskiest surface: the frame-slot dialog carried a negative prior
+(#237's name-search never surfaced generated media there — see
+[LIVE_VERIFICATION_v0.25.0](LIVE_VERIFICATION_v0.25.0.md)). The thumbnail-URL
+tile match succeeds where name search failed.
+
+Run: seed `gflow image t2i` (asset `0bbcdf05-19e0-43c3-bbeb-ba0ff7246e54`,
+project `dd9e498c-22b1-4d73-a748-0bc0eac14c8b`), then
+`gflow video i2v --initial-frame 0bbcdf05-… "slow cinematic push-in toward the
+mug, steam rising gently" --project dd9e498c-… --profile denon82 --json`
+(correlation `92b99c8c-5d69-4e00-905f-734f8eb6dadc`).
+
+5-layer ledger:
+
+1. **File count:** exactly 1 mp4 in `--out-dir` (`b61bcce6-baca-4934-b6e5-5ca84e10b49a.mp4`, 3,031,564 bytes).
+2. **Magic bytes:** `00 00 00 20 66 74 79 70 69 73 6f 6d` — valid `ftypisom` MP4 header.
+3. **Dimensions/shape:** ffprobe `720×1280`, duration `8.000000` s (Flow default — no `--duration` passed, correct).
+4. **Structlog invariants:**
+   - `ui_automation_video.frame_ref_attached {slot: Start, media_id: 0bbcdf05…}` — UUID picker selection in the frame-slot dialog;
+   - `ui_automation_video.generate_captured {url: …/video:batchAsyncGenerateVideoStartImage, image_inputs.startImage: "0bbcdf05"}` — the asset is bound in the actual wire request (no #125 T2V fallback);
+   - **zero `image_uploaded` events** in the whole run — no duplicate upload (the founding goal of #287);
+   - `poll_terminal {status: MEDIA_GENERATION_STATUS_SUCCESSFUL}` → `video_saved`.
+5. **User-confirmable artifact:** video `b61bcce6-…` in Flow project `dd9e498c-…` (denon82 account) — a genuine motion interpolation of the seeded red-mug still.
+
+Negative check (free): a foreign UUID (`00000000-0000-4000-8000-000000000001`)
+in the same project → **exit 9** (`TransportTimeoutError`) pre-generation, the
+message naming slot + UUID + the `--project` hint, with
+`debug_frame_ref_miss_start.png` captured (valid PNG).
+
+Not verified this cycle: a live `uploadImage` HTTP-400 → exit 27
+(`MediaUploadRejectedError`) repro — the original Flow-rejected JPEG from the
+2026-07-11 pilot no longer exists on disk (only thumbnails survive). The typed
+raise is pinned by a unit test that drives the real `_upload_via_open_dialog`
+listener with a 400 response (`tests/api/transports/test_ui_automation_video.py::TestUploadRejectionTypedError`).
+The KNOWN_ISSUES entry on metadata-sensitive rejections tracks the live case.
+
+## 2. `--duration` fail-fast (#288, PR #289)
+
+Run: `gflow video i2v <local file> "slow pan across the mug" --duration 4
+--profile denon82 --json` (correlation `b8e66830-58bf-4928-9afe-1eecbbfcdb60`).
+
+- `duration_tab` probe missed (reproducing the pilot's 3/3) and the run
+  **aborted pre-submit with exit 23** (`UiSelectorDriftError`) — the settings
+  popover showed "A geração vai usar 10 créditos", so the fail-fast saved that
+  spend instead of delivering a silent 8-second clip reported as success.
+- `debug_no_duration_tab.png` captured (valid PNG, `89 50 4E 47` header) and
+  **answers the #288 investigation: the duration control is absent from this
+  cohort's Frames-submode settings popover** (rows rendered: Imagem/Vídeo →
+  Frames/Elementos → 9:16/16:9 → 1x/x2/x3/x4 → model dropdown; no duration
+  row). The council's locale hypothesis is refuted — the UI is Portuguese and
+  the sibling text-matched count tabs match fine.
+- Happy-path caveat, recorded per the honesty rule: "duration tab found →
+  clicked" is unverifiable on this cohort because the control does not exist.
+  If a cohort still renders duration tabs, the pre-existing selector cascade
+  should match them unchanged; the fail-fast only fires on a miss.
+
+## Incidental live findings (logged on their issues)
+
+- Project `f6caf027-…` opens in the full-page media-library UI (#174 shape,
+  "Agente" composer pill) where even `mode_switch_trigger` fails — fresh
+  projects still get the classic composer and work. Posted to #288/#174 trail.
+- Error-path browser teardown can leave Chrome holding the profile dir
+  (subsequent runs die with `TargetClosedError` until the process is killed),
+  and `_capture_debug_screenshot` can report a screenshot path it never wrote
+  when capture fails. Both noted as #283-wave follow-ups.

{gflow_cli-0.31.0 → gflow_cli-0.32.0}/docs/MCP.md

@@ -46,7 +46,7 @@ The server registers three protocol surfaces:
 
 ### Tools (Executable actions)
 * `gflow_generate_image(prompt, model, aspect, count, seed, reference_images, tools, profile, project, instructions)`: Triggers text-to-image / image-to-image (Imagen / Nano Banana). `instructions` is an optional list of ephemeral agent-instruction strings (agentic cohort only). `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, model, duration, count, tools, profile, project)`: Triggers vertical or landscape video generation (Veo). `mode` is `t2v`/`i2v`/`r2v`; `model` (`veo_lite`/`veo_fast`/`veo_quality`/`omni_flash`, aliases accepted), `duration` (seconds), and `count` mirror the CLI `gflow video` flags — an omitted `model` lets the transport apply its i2v veo-lite default (issue #125), and `omni_flash` is rejected for i2v-with-frames; `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_generate_video(prompt, mode, aspect, initial_frame, end_frame, reference_images, model, duration, count, tools, profile, project)`: Triggers vertical or landscape video generation (Veo). `mode` is `t2v`/`i2v`/`r2v`; `model` (`veo_lite`/`veo_fast`/`veo_quality`/`omni_flash`, aliases accepted), `duration` (seconds), and `count` mirror the CLI `gflow video` flags — an omitted `model` lets the transport apply its i2v veo-lite default (issue #125), and `omni_flash` is rejected for i2v-with-frames; `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). Note the CLI's semantics diverge here (#287): `gflow video i2v --initial-frame <UUID>` selects the asset **in the project's media picker with no upload** and needs no local catalog entry — so the same UUID input can succeed on one surface and fail on the other.
 * `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_list_tools()`: Lists the prompt tools (name/title/description/category) accepted by the generate tools' `tools` param.

{gflow_cli-0.31.0 → gflow_cli-0.32.0}/docs/USAGE.md

@@ -67,7 +67,7 @@ See [AUTHENTICATION § Commands](AUTHENTICATION.md#commands).
 
 ## `gflow image upload`
 
-Upload a local PNG/JPEG/WebP/GIF into a fresh Flow project and print the asset UUID + dimensions Flow inferred. The UUID is what later subcommands (`gflow image i2i --ref UUID`, `video i2v`) accept as an initial frame.
+Upload a local PNG/JPEG/WebP/GIF into a fresh Flow project and print the asset UUID + dimensions Flow inferred. The UUID is what later subcommands (`gflow image i2i --ref UUID`, `video i2v`) accept as an initial frame. Note for `video i2v`: the UUID is selected from the generation project's media picker, and `upload` puts the asset in a *fresh scratch project* — so pass `--project <id>` of the project that holds the asset, or the picker lookup fails with exit 9 (#287).
 
 ```text
 gflow image upload PATH [OPTIONS]
@@ -460,9 +460,12 @@ gflow video t2v "a dog surfing" --tool creative-director:style=cinematic
 ## `gflow video i2v`
 
 Generate a video from an INITIAL frame (+ optional END frame) and a motion prompt.
-Each image is a local PNG/JPEG; it is bound into the editor's frame slot via the
-media dialog, then Flow fires `batchAsyncGenerateVideoStartImage` (initial only) or
-`…StartAndEndImage` (initial+end interpolation).
+Each frame is a local PNG/JPEG **or the media UUID of an existing in-project asset**
+(#287 — the asset is selected in place, no duplicate upload; pair with `--project`
+so the UUID's project is the one being generated in). A local file is bound into
+the editor's frame slot via the media dialog, then Flow fires
+`batchAsyncGenerateVideoStartImage` (initial only) or `…StartAndEndImage`
+(initial+end interpolation).
 
 ```text
 gflow video i2v --initial-frame INITIAL [--end-frame LAST] PROMPT [--model] [--duration] [--count] [--aspect] [...]
@@ -474,19 +477,28 @@ Arguments:
   PROMPT  Motion prompt.  [required]
 
 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").
+  --initial-frame PATH|UUID  Initial frame to animate: local image path or in-project
+                             asset media UUID. Canonical form; replaces the positional IMAGE.
+  --end-frame PATH|UUID      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
 gflow video i2v --initial-frame ./hero.png "Slow camera arc, soft golden light"
 gflow video i2v --initial-frame ./first.png --end-frame ./last.png "morph between scenes" --model veo-quality
+# Reference an existing in-project asset by media UUID (no re-upload, #287):
+gflow video i2v --initial-frame d6f1927a-3eae-4626-bc90-9a6ea7637bab "pan left" --project f6caf027-...
 # Back-compat positional form:
 gflow video i2v ./hero.png "Slow camera arc, soft golden light"
 ```
 
+Exit codes specific to this surface: **27** — Flow's upload endpoint rejected a
+local frame file (`MediaUploadRejectedError`; try re-encoding, e.g.
+`ffmpeg -i in.jpg -q:v 2 -map_metadata -1 out.jpg`, or reference the asset by
+UUID instead); **9** — a frame UUID could not be located in the project's media
+picker (`TransportTimeoutError`; wrong `--project` or foreign UUID).
+
 ## `gflow video r2v`
 
 Reference-to-video (Flow "ingredients"): condition a generation on reference
@@ -1212,7 +1224,7 @@ shell scripts can branch on the failure mode without parsing stderr.
 | `6`  | `NetworkError`        | Network failure persisted across 3 attempts      | Check connectivity                                         |
 | `7`  | `WireFormatError`     | Unexpected response shape — Flow API changed     | File a bug (do NOT include captured tokens or signed URLs) |
 | `8`  | `AuthMissingError`    | Required auth credential is absent from profile   | `gflow auth login --profile <name>`                        |
-| `9`  | `TransportTimeoutError` | Browser/API operation exceeded its timeout      | Retry; raise the relevant timeout if needed                |
+| `9`  | `TransportTimeoutError` | Browser/API operation exceeded its timeout (incl. an i2v frame UUID not found in the media picker, #287) | Retry; raise the relevant timeout — or, for a frame-UUID miss, verify the UUID belongs to the `--project` passed |
 | `10` | `WafRejectionError`   | Flow security layer rejected the request          | Change prompt/request and retry                            |
 | `11` | `ConfigurationError`  | Local configuration or browser mode is invalid    | Fix the option/env var shown in the error                  |
 | `12` | `AuthLoginTimeoutError` | Browser sign-in was not completed in time       | Re-run login or raise `GFLOW_CLI_AUTH_LOGIN_TIMEOUT`       |
@@ -1228,6 +1240,9 @@ shell scripts can branch on the failure mode without parsing stderr.
 | `22` | `UpscaleUnavailableError` | 4K upscale is gated to Flow **Ultra** accounts (HTTP 403) | Use `--scale 2k`, or upgrade the Flow plan                |
 | `23` | `UiSelectorDriftError` | A Flow editor control could not be located — Google changed the frontend (issue #183) | Update gflow-cli; file a bug with the probe name + debug screenshot from the error message |
 | `24` | `BrowserEngineUnavailableError` | `GFLOW_CLI_BROWSER_ENGINE=patchright` but the engine is not installed | `pip install 'gflow-cli[patchright]'`, or unset `GFLOW_CLI_BROWSER_ENGINE` |
+| `25` | `FlowAgentUiError`    | The profile is on Flow's Agentic UI cohort and the classic media panel is unrecoverable for this operation | Use a Classic-cohort profile; see KNOWN_ISSUES on the agentic cohort |
+| `26` | `MediaAttributionError` | Generated media could not be reliably attributed to this request (issue #281) | Re-run; a dedicated project with fewer pre-existing assets avoids the ambiguity |
+| `27` | `MediaUploadRejectedError` | Flow's upload endpoint refused the input file (`uploadImage` 4xx, issue #287) | Re-encode the image (`ffmpeg -q:v 2 -map_metadata -1`), or reference the asset by its media UUID |
 | `130`| SIGINT                | User-interrupted (Ctrl-C)                        | —                                                          |
 
 **Exit code 16 — data store / migration error.** Fires when:

{gflow_cli-0.31.0 → gflow_cli-0.32.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.31.0"
+version = "0.32.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.31.0 → gflow_cli-0.32.0}/scripts/dev/spike_movie_attach_payload.py

@@ -106,7 +106,7 @@ async def _run(
             if full:
                 await VideoGenerationMixin._select_video_aspect(page, Aspect.PORTRAIT)  # noqa: SLF001
                 await VideoGenerationMixin._set_output_count(page, 1)  # noqa: SLF001
-                await VideoGenerationMixin._select_video_duration(page, 8)  # noqa: SLF001
+                await VideoGenerationMixin._select_video_duration(page, 8, out_dir=None)  # noqa: SLF001
                 await page.keyboard.press("Escape")
                 await page.wait_for_timeout(600)
             await page.wait_for_timeout(800)

{gflow_cli-0.31.0 → gflow_cli-0.32.0}/skills/gflow-cli/SKILL.md

@@ -68,7 +68,7 @@ gflow image i2i "<prompt>" --ref PATH_OR_UUID [--ref ...] [...same as t2i]
 
 # Video generation (Veo 3.1)
 gflow video t2v "<prompt>" [--out-dir DIR] [--aspect ...] [--seed N]
-gflow video i2v --initial-frame <image> "<prompt>" [--out-dir DIR] [...same as t2v]
+gflow video i2v --initial-frame <image|media-UUID> "<prompt>" [--out-dir DIR] [...same as t2v]  # UUID = in-project asset, no re-upload (#287; pair with --project)
 gflow video batch <manifest.tsv> [--out-dir DIR]
 gflow video chain <manifest.jsonl> [--out-dir DIR] [--dry-run] \
                   [--max-links N] [--resume-from N]   # last-frame I2V chaining; veo models only
@@ -259,7 +259,7 @@ Documented errors agents commonly make — negative examples for the SkillOpt tr
 | `playwright install` or `playwright install --all` | `uvx --from gflow-cli playwright install chromium` (Chromium only, ~150 MB) |
 | Running two generations on the same `--profile` in parallel | Use different `--profile` names — Chromium refuses two persistent contexts on the same dir |
 | `GFLOW_CLI_HEADLESS=true` to fix reCAPTCHA failures | `GFLOW_CLI_HEADLESS=false` — headless mode *causes* bot-detection, not prevents it |
-| Calling `gflow image upload` again for an already-uploaded UUID | Pass the UUID directly to `--ref UUID` — no re-upload needed |
+| Calling `gflow image upload` again for an already-uploaded UUID | Pass the UUID directly to `--ref UUID` (i2i) or `--initial-frame/--end-frame UUID` (i2v, with `--project`) — no re-upload needed |
 | `--model imagen` / `--model quality` / `--model high` | `--model image4` (Imagen 3.5), `--model nano-pro` (Gem Pix 2), `--model nano2` (Narwhal) |
 | Python: `client = FlowApiClient(...)` then method calls | Must use `async with FlowApiClient(...) as client:` — it's an async context manager |
 | Python: `from gflow_cli import FlowApiClient` | `from gflow_cli.api.client import FlowApiClient` |

{gflow_cli-0.31.0 → gflow_cli-0.32.0}/src/gflow_cli/__init__.py

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

{gflow_cli-0.31.0 → gflow_cli-0.32.0}/src/gflow_cli/api/transports/drivers/classic.py

@@ -156,7 +156,7 @@ class ClassicFlowUiDriver:
         )
         if request.duration is not None:
             await VideoGenerationMixin._select_video_duration(  # type: ignore[reportPrivateUsage]
-                page, request.duration
+                page, request.duration, out_dir=out_dir
             )
         await page.keyboard.press("Escape")
         await page.wait_for_timeout(600)

{gflow_cli-0.31.0 → gflow_cli-0.32.0}/src/gflow_cli/api/transports/ui_automation_video.py

@@ -42,6 +42,7 @@ from gflow_cli.api.video import (
 from gflow_cli.errors import (
     AuthExpiredError,
     FlowAgentUiError,
+    MediaUploadRejectedError,
     ModelModeIncompatibilityError,
     TransportTimeoutError,
     UiSelectorDriftError,
@@ -1096,19 +1097,31 @@ class VideoGenerationMixin:
             raise VideoModelSelectionError(detail=msg, route="model_option")
 
     @staticmethod
-    async def _select_video_duration(page: Page, seconds: int) -> None:
+    async def _select_video_duration(page: Page, seconds: int, *, out_dir: Path | None) -> None:
         """Click the duration tab for `seconds` (4/6/8, or 10 for omni_flash).
-        Disambiguated by aria-label text ('4s'..'10s'), NOT id-suffix
+        Disambiguated by visible tab text ('4s'..'10s'), NOT id-suffix
         (collides with count). Must run AFTER model select — the 10s tab only
-        exists once omni_flash is chosen. Non-fatal on miss."""
+        exists once omni_flash is chosen. Fatal on miss (issue #288): this
+        only runs for an explicit --duration, and duration is a contract
+        parameter — a silent fall-through to Flow's default corrupts
+        downstream timeline math."""
         tab = await VideoGenerationMixin._probe_selector_cascade(
             page,
             "duration_tab",
             (f"[role='tab']:text-is('{seconds}s')", f"[role='tab']:has-text('{seconds}s')"),
         )
         if tab is None:
-            log.warning("ui_automation_video.duration_not_set", seconds=seconds)
-            return
+            shot = await _capture_debug_screenshot(page, out_dir, "debug_no_duration_tab.png")
+            raise UiSelectorDriftError(
+                selector_drift_detail(
+                    "duration_tab",
+                    f"the {seconds}s duration tab was not found on the Flow editor; "
+                    f"refusing to proceed — Flow's default duration (typically 8s) "
+                    f"would silently replace the requested value (issue #288). Omit "
+                    f"--duration to accept Flow's default.",
+                    shot,
+                )
+            )
         await tab.click()
         await page.wait_for_timeout(400)
         log.info("ui_automation_video.duration_set", seconds=seconds)
@@ -1314,6 +1327,51 @@ class VideoGenerationMixin:
         )
         log.info("ui_automation_video.remote_frame_attached", slot=label, display_name=name)
 
+    @staticmethod
+    async def _attach_frame_by_media_id(
+        page: Page,
+        slot_index: int,
+        label: str,
+        media_id: str,
+        *,
+        out_dir: Path | None,
+    ) -> None:
+        """Fill the I2V first/last frame slot with an already-existing in-project
+        asset, selected by its media UUID (#287) — no duplicate upload. Opens the
+        slot's media dialog (same entry as `_attach_frame`/`_attach_remote_frame`)
+        then reuses the `_select_existing_asset` UUID picker. There is no local
+        fallback: the caller asked for THIS asset, so a miss is a hard error."""
+        slot = await VideoGenerationMixin._resolve_frame_slot(
+            page, slot_index, label, out_dir=out_dir, wait_ms=12000
+        )
+        await slot.click()
+        await page.wait_for_timeout(1000)  # media dialog opens
+
+        # Presence-guarded search clear, mirroring _attach_image_uuid_refs: a
+        # picker variant with no search box must not become a hard dependency.
+        search = page.locator(PICKER_SEARCH_INPUT).first
+        if await search.count():
+            await search.fill("")
+
+        if not await VideoGenerationMixin._select_existing_asset(
+            page, media_id, "", out_dir=out_dir
+        ):
+            # The frame-slot dialog is the one surface this picker reuse is
+            # unproven on (#237's name-search never surfaced generated media
+            # here) — capture the dialog state so a live miss is diagnosable.
+            shot = await _capture_debug_screenshot(
+                page, out_dir, f"debug_frame_ref_miss_{label.lower()}.png"
+            )
+            msg = (
+                f"{label} frame asset {media_id!r} could not be located in the "
+                "media picker — is it in the target project (missing or wrong "
+                "--project), and is the UUID from this profile's library?"
+            )
+            if shot is not None:
+                msg = f"{msg} Screenshot: {shot}"
+            raise TransportTimeoutError(msg)
+        log.info("ui_automation_video.frame_ref_attached", slot=label, media_id=media_id)
+
     @staticmethod
     async def _upload_via_open_dialog(
         page: Page,
@@ -1383,10 +1441,11 @@ class VideoGenerationMixin:
                 log.warning("ui_automation_video.upload_incomplete", target=log_label)
             else:
                 # Fail loud on a rejected upload instead of committing an empty
-                # slot that silently falls back to T2V (#125).
+                # slot that silently falls back to T2V (#125). Typed (#287) so
+                # callers get exit 27 + a re-encode hint, not "Unexpected error."
                 rejection = _upload_rejection_message(uploaded[-1], log_label)
                 if rejection is not None:
-                    raise RuntimeError(rejection)
+                    raise MediaUploadRejectedError(detail=rejection, route=UPLOAD_IMAGE_ROUTE)
         finally:
             page.remove_listener("response", on_response)
 
@@ -1508,8 +1567,9 @@ class VideoGenerationMixin:
         (react-virtuoso renders off-viewport tiles lazily — #282) and
         re-checks between scrolls, the same strategy `_find_picker_entity_tile`
         uses for the entity picker. Returns ``True`` once attached, ``False``
-        when the asset can't be located by any of the above (the caller then
-        falls back to a local upload).
+        when the asset can't be located by any of the above (callers with a
+        local file fall back to uploading it; the #287 frame-ref path has no
+        fallback and raises instead).
         """
         tile = VideoGenerationMixin._existing_asset_tile(page, media_id)
         visible = True
@@ -2090,11 +2150,16 @@ class VideoGenerationMixin:
     async def _attach_i2v_frames(
         page: Page, request: GenerateVideoRequest, *, out_dir: Path | None
     ) -> None:
-        """Attach the Start (and optional End) I2V frame, local path or remote ref."""
+        """Attach the Start (and optional End) I2V frame: local path, in-project
+        asset UUID (#287), or remote display-name ref."""
         if request.start_image is not None:
             await VideoGenerationMixin._attach_frame(
                 page, 0, "Start", request.start_image, out_dir=out_dir
             )
+        elif request.start_image_ref_id is not None:
+            await VideoGenerationMixin._attach_frame_by_media_id(
+                page, 0, "Start", request.start_image_ref_id, out_dir=out_dir
+            )
         elif request.start_image_ref_name is not None:
             await VideoGenerationMixin._attach_remote_frame(
                 page, 0, "Start", request.start_image_ref_name, out_dir=out_dir
@@ -2103,6 +2168,10 @@ class VideoGenerationMixin:
             await VideoGenerationMixin._attach_frame(
                 page, 1, "End", request.end_image, out_dir=out_dir
             )
+        elif request.end_image_ref_id is not None:
+            await VideoGenerationMixin._attach_frame_by_media_id(
+                page, 1, "End", request.end_image_ref_id, out_dir=out_dir
+            )
         elif request.end_image_ref_name is not None:
             await VideoGenerationMixin._attach_remote_frame(
                 page, 1, "End", request.end_image_ref_name, out_dir=out_dir

{gflow_cli-0.31.0 → gflow_cli-0.32.0}/src/gflow_cli/api/video.py

@@ -8,6 +8,7 @@ retired — see the Phase A plan).
 
 from __future__ import annotations
 
+import re
 from collections.abc import Awaitable, Callable, Mapping
 from dataclasses import dataclass
 from enum import StrEnum
@@ -174,6 +175,19 @@ def max_duration_for(model: VideoModel) -> int:
     return 10 if model is VideoModel.OMNI_FLASH else 8
 
 
+# Case-insensitive 8-4-4-4-12 hex with hyphens — Flow's media UUIDs (the same
+# shape cli_image's --ref classifier accepts).
+_MEDIA_UUID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+    re.IGNORECASE,
+)
+
+
+def is_media_uuid(value: str) -> bool:
+    """True when *value* is shaped like a Flow media UUID (#287)."""
+    return _MEDIA_UUID_RE.fullmatch(value) is not None
+
+
 def aspect_choices() -> dict[str, str]:
     """Map each accepted CLI aspect ratio to its wire value."""
     return {
@@ -203,8 +217,10 @@ class GenerateVideoRequest:
     seed: int | None = None
     start_image: Path | None = None  # I2V (local file path)
     start_image_ref_name: str | None = None  # I2V (remote asset display name)
+    start_image_ref_id: str | None = None  # I2V (in-project asset media UUID, #287)
     end_image: Path | None = None  # I2V (optional local file path)
     end_image_ref_name: str | None = None  # I2V (optional remote asset display name)
+    end_image_ref_id: str | None = None  # I2V (optional in-project asset media UUID, #287)
     reference_images: tuple[Path, ...] = ()  # R2V (local file paths)
     ref_names: tuple[str, ...] = ()  # R2V (remote asset display names)
     reference_entities: tuple[str, ...] = ()  # R2V — Flow CHARACTER entity ids
@@ -222,10 +238,28 @@ class GenerateVideoRequest:
         self._validate_prompt()
         self._validate_duration()
         self._validate_count()
+        self._validate_frame_ref_ids()
         self._validate_mode_symmetry()
         self._validate_r2v_caps()
         self._validate_seed()
 
+    def _validate_frame_ref_ids(self) -> None:
+        for slot, ref_id, alternatives in (
+            ("start", self.start_image_ref_id, (self.start_image, self.start_image_ref_name)),
+            ("end", self.end_image_ref_id, (self.end_image, self.end_image_ref_name)),
+        ):
+            if ref_id is None:
+                continue
+            if not is_media_uuid(ref_id):
+                msg = f"{slot}_image_ref_id {ref_id!r} is not a valid media UUID"
+                raise ValueError(msg)
+            if any(alt is not None for alt in alternatives):
+                msg = (
+                    f"at most one of {slot}_image, {slot}_image_ref_name, or "
+                    f"{slot}_image_ref_id may be set"
+                )
+                raise ValueError(msg)
+
     def _validate_prompt(self) -> None:
         if not self.prompt.strip():
             msg = "prompt must not be empty"
@@ -254,8 +288,12 @@ class GenerateVideoRequest:
             raise ValueError(msg)
 
     def _validate_i2v_symmetry(self) -> None:
-        if self.start_image is None and self.start_image_ref_name is None:
-            msg = "I2V request requires start_image or start_image_ref_name"
+        if (
+            self.start_image is None
+            and self.start_image_ref_name is None
+            and self.start_image_ref_id is None
+        ):
+            msg = "I2V request requires start_image, start_image_ref_name, or start_image_ref_id"
             raise ValueError(msg)
         if self.reference_images or self.ref_names or self.reference_entities:
             msg = "I2V request must not carry reference_images, ref_names, or reference_entities"
@@ -268,8 +306,10 @@ class GenerateVideoRequest:
         if (
             self.start_image
             or self.start_image_ref_name
+            or self.start_image_ref_id
             or self.end_image
             or self.end_image_ref_name
+            or self.end_image_ref_id
         ):
             msg = "R2V request must not carry start/end images"
             raise ValueError(msg)
@@ -278,8 +318,10 @@ class GenerateVideoRequest:
         if self.mode is Mode.T2V and (
             self.start_image
             or self.start_image_ref_name
+            or self.start_image_ref_id
             or self.end_image
             or self.end_image_ref_name
+            or self.end_image_ref_id
             or self.reference_images
             or self.ref_names
         ):