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

{gflow_cli-0.25.0 → gflow_cli-0.27.0}/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.27.0] — 2026-07-07
+
+### Added
+
+- **Global `[style]` block with named variants in `movie.toml` (Issue #239):** channel-format
+  videos can now express a visual style system (e.g. monochrome → warm color arc) once in the
+  `[style]` block and select it per-scene via `style_variant`, without repeating style text in
+  every scene's action. Adds `prefix`/`suffix` fields to `[style]`, `[style.variants.*]`
+  sub-tables, per-scene `style_variant` and `style_suffix` fields, deterministic composition
+  rule, and `style_applied` (variant/prefix/suffix/scene_suffix) per clip in the handoff
+  manifest. `none` is a reserved variant name (opt-out keyword) and may not be defined.
+- **Prompt-aware resume for `movie run`:** completed scenes now persist a SHA-256 hash of
+  their composed prompt (`style_hash`); on resume, a scene whose prompt changed (style edit,
+  variant switch, action tweak) is regenerated instead of silently skipped. Unchanged scenes
+  still cost nothing. Old state files fall back to comparing the stored prompt text and are
+  never re-run on a guess. Dry-run shows the resolved style per scene and marks stale scenes
+  as `re-run (style changed)`.
+
+## [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
@@ -1792,7 +1830,10 @@ 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.24.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.27.0...HEAD
+[0.27.0]: https://github.com/ffroliva/gflow-cli/compare/v0.26.0...v0.27.0
+[0.26.0]: https://github.com/ffroliva/gflow-cli/compare/v0.25.0...v0.26.0
+[0.25.0]: https://github.com/ffroliva/gflow-cli/compare/v0.24.0...v0.25.0
 [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.25.0
+Version: 0.27.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.25.0 → gflow_cli-0.27.0}/docs/INDEX.md

@@ -22,7 +22,10 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | [CONTRIBUTING](../CONTRIBUTING.md) | TDD workflow, test categories, coverage targets | Before opening a PR |
 | **[docs/DEVELOPMENT.md](DEVELOPMENT.md)** | Branching model, PR protocol, e2e gate, version bump protocol, AI-assisted workflow | Understanding the end-to-end dev process |
 | **[docs/E2E_TESTING.md](E2E_TESTING.md)** | Layer model, cost sub-markers, run commands, isolation patterns, roadmap to contract/replay layer | Running or extending e2e tests; cost control |
+| **[docs/AGENT_UI_E2E.md](AGENT_UI_E2E.md)** | Deterministic e2e runbook for the Agentic UI image path (force-agent trigger, validation ledger) | Live-verifying Agentic-UI features |
 | **[docs/GITHUB.md](GITHUB.md)** | Maintainer PR triage protocol, forked PR handling, SonarCloud scenarios | Reviewing or merging a GitHub PR |
+| [docs/sonar-cleanup-tracker.md](sonar-cleanup-tracker.md) | SonarCloud zero-smells cleanup tracker (`chore/sonar-zero-cleanup`) | Resuming or auditing the Sonar cleanup effort |
+| [docs/medium_tutorial.md](medium_tutorial.md) | Long-form tutorial article (Medium draft): Veo + Imagen from the terminal | Writing or updating outreach/tutorial content |
 | [.env.template](../.env.template) | All environment variables with defaults | Setting up a new shell or container |
 | **[docs/AUTHENTICATION.md](AUTHENTICATION.md)** | Full auth flow, session storage, multi-account, refresh | First `gflow auth login`, or auth errors |
 | **[docs/CONFIGURATION.md](CONFIGURATION.md)** | All env vars, precedence chain, default paths per OS | Tuning behaviour, picking output paths |
@@ -117,7 +120,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.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.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.27.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.27.0/docs/LIVE_VERIFICATION_v0.27.0.md

@@ -0,0 +1,100 @@
+# Live Verification — v0.27.0
+
+Release date: 2026-07-07. Headline: **global `[style]` block with named variants
+in `movie.toml`** (Issue #239, PR #259) — express a visual style arc once
+(prefix/suffix + `[style.variants.*]`) and select it per-scene via
+`style_variant` / `style_suffix` — plus **prompt-aware resume** for `movie run`
+(completed scenes persist a `style_hash`; a scene whose composed prompt changed
+is regenerated instead of silently skipped).
+
+Verification run: 2026-07-07, real CLI (`gflow movie run --dry-run`), Windows,
+`.venv` build of the release tree. **Deliberately credit-free**: this release is
+pure local prompt composition + state logic — the Flow wire path (transports,
+selectors, auth) is untouched, so no live Veo generation was spent. The dry-run
+path exercises the identical manifest→parse→compose→resume-decision pipeline the
+live run uses; only `_generate_scene` (unchanged this release) is skipped.
+
+## Scope
+
+| Change | Surface | Verdict |
+|---|---|---|
+| `[style]` prefix/suffix + `[style.variants.*]`, per-scene `style_variant`/`style_suffix` | `composition.py`, `movie_manifest.py` | ✅ CLI dry-run + 91 unit/integration tests |
+| Prompt-aware resume (`style_hash`, `is_stale_for`, re-run on style edit) | `movie_manifest.py`, `cli_movie.py` | ✅ CLI dry-run 3-way ledger (below) |
+| Dry-run shows resolved style + stale marker | `cli_movie.py` | ✅ CLI dry-run output |
+| `style_applied` (variant/prefix/suffix/scene_suffix) per clip + schema | `composition.py`, `docs/schemas/movie-handoff.schema.json` | ✅ Unit-tested (jsonschema validation) |
+| Reserved `none` variant name, strict variant parsing | `movie_manifest.py` | ✅ Unit-tested (ConfigurationError paths) |
+
+## Evidence ledger (credit-free CLI runs)
+
+Manifest: 3 scenes — `s1-base` (base style), `s2-warm` (`style_variant="warm"` +
+`style_suffix="golden hour light"`), `s3-optout` (`style_variant="none"`), with
+`prefix = "SCENE:"` and a base suffix.
+
+1. **Composed prompt (canonical order)** — `compose_prompt` for `s1-base`
+   produced exactly:
+   `SCENE: Walks through a rainy plaza. Wide shot. Black and white cinematic
+   street photography, film grain.` — prefix first, sentence-composed
+   action/framing, raw base suffix last.
+2. **Run 1 (fresh state)** — plan shows the resolved style per scene and full
+   cost: `s1-base … style=base 1 credit(s)`, `s2-warm … style=warm
+   +style_suffix 1 credit(s)`, `s3-optout … style=none 1 credit(s)`,
+   `Estimated credits: ~3`.
+3. **Run 2 (s1 completed in `movie-state.json` with matching `style_hash`)** —
+   `s1-base … skip (done)`, `Estimated credits: ~2`. State file JSON carries
+   `"style_hash": "<sha256 of the composed prompt>"` (round-tripped via
+   `MovieState.save`/`load`).
+4. **Run 3 (base suffix edited to "Sepia archival newsreel look.")** —
+   `s1-base … re-run (style changed) 1 credit(s)`, `Estimated credits: ~3`.
+   The stale scene is regenerated; the unchanged `s2-warm`/`s3-optout`
+   decisions are unaffected. This is the exact staleness bug the feature
+   exists to prevent (stale clip silently skipped after a style edit).
+5. **User-confirmable artifact** — the three plan outputs above are
+   reproducible with any manifest; the same decision logic drives the real run
+   loop (`_run_movie` calls the identical `is_stale_for` check before spending
+   credits).
+
+### Not live-verified this cycle (recorded, not omitted)
+
+Actual Veo generation with a style-suffixed prompt (i.e. confirming Flow's
+model renders the requested grade) was **not** exercised — it costs 20 credits
+per scene and the prompt text demonstrably reaches the existing, unchanged
+generation path (`_run_one_scene` passes the same `compose_prompt` output that
+v0.26.0 passed). First credited `movie run` on a styled manifest will confirm
+visually; no code path is untested locally.
+
+### Pre-existing display nit (not this release)
+
+The plan line's `[t2v]`/`[r2v]` mode tag is swallowed by rich markup
+(`console.print` interprets `[t2v]` as a style tag) — present on `develop`
+before PR #259; cosmetic; tracked as a follow-up.
+
+## Pre-tag gates
+
+- `/gflow:check`: hygiene ✅ · ruff ✅ (no rewrites) · pyright `0 errors` ✅ ·
+  full suite 2054 passed / 7 skipped ✅ (local), 3.11/3.12/3.13 matrix +
+  SonarCloud quality gate ✅ on PR #259 (same tree).
+- `/code-review` (independent, 8-angle): 10 findings — all fixed in
+  `61a9887` before merge.
+- `/gflow:doc-review`: mechanical pass UPDATED×2 (PROJECT_STATUS current
+  release was stale at v0.24.0 — v0.25.0/v0.26.0/v0.27.0 entries added; 3 docs
+  added to INDEX), links 23/23 green. Council verdict: **GREEN/YELLOW/YELLOW**
+  across 3 auditors — 1 Tier-1 finding (this doc overclaimed "91
+  style-variants tests"; actual collection is 59 — fixed in the release-prep
+  commit), Tier-2 fixed (stale MOVIE.md "active development" banner), Tier-3
+  deferred (hardcoded `build_handoff` `generator.version="0.14.0"`; MOVIE.md
+  error-path doc anchor; USAGE.md movie coverage). Council reports at
+  `tmp/council/0{1,2,3}-*.md` (local-only).
+
+## Post-tag evidence
+
+*(filled after the v0.27.0 tag push / publish)*
+
+## Automated coverage
+
+- 59 style-variants tests across `tests/composition/test_style_variants.py`,
+  `test_style_variants_e2e.py`, `tests/cli/test_movie_manifest_style_variants.py`
+  (composition order, variant resolution, reserved `none`, strict parsing,
+  `style_applied` + jsonschema validation, `resume_hash` properties,
+  `is_stale_for` all four branches, state round-trip).
+- Full suite green: 2054 passed, 7 skipped (local) and 3.11/3.12/3.13 matrix +
+  SonarCloud quality gate green on PR #259. `pyright src` 0 errors, ruff clean.

{gflow_cli-0.25.0 → gflow_cli-0.27.0}/docs/MCP.md

@@ -45,7 +45,7 @@ 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_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.25.0 → gflow_cli-0.27.0}/docs/MOVIE.md

@@ -5,9 +5,9 @@ clips that share the **same characters** (face + voice) across every scene. It
 is the orchestration layer on top of `gflow character` (entity creation) and
 `gflow video` (R2V generation).
 
-> Status: under active development on the movie feature branch. The wire
-> protocol and CLI surface below are live-verified but may still change before
-> release.
+> Status: shipped (since v0.14.0) and evolving. The CLI surface below is
+> release-stable per SemVer; alpha (`0.x`) minor versions may still extend or
+> adjust it, with changes noted in the CHANGELOG.
 
 ## Quick start
 
@@ -31,6 +31,18 @@ title = "E2E Stickman"
 project = "6ba50219-…"            # reusable Flow project id
 output_dir = "./out"
 
+[style]
+look = "cinematic, shallow depth of field"
+palette = "warm golden tones"
+negative = "no text, no watermark"
+suffix = "Black and white cinematic street photography, photorealistic, film grain."
+
+  [style.variants.warm]
+  suffix = "Warm golden-hour cinematic grade."
+
+  [style.variants.cool]
+  suffix = "Cool blue-toned cinematic grade."
+
 [[characters]]
 name = "Stickman"
 identity = "entity"               # reuse a Flow CHARACTER entity across scenes
@@ -47,6 +59,14 @@ line = "We finally made it to the top!"
 aspect = "9:16"
 model = "veo-lite"
 duration = 8
+
+[[scenes]]
+id = "close-up"
+action = "smiles with excitement"
+style_variant = "warm"            # selects [style.variants.warm]
+style_suffix = "golden hour light" # appended after the variant suffix
+aspect = "9:16"
+duration = 6
 ```
 
 On first run, characters with `identity = "entity"` are created once (image
@@ -54,6 +74,53 @@ generation — **free**, no credits) and cached. Each scene then generates a cli
 that **reuses the same Flow CHARACTER entity** so the character drives every
 scene from one identity.
 
+### Style variants
+
+The `[style]` block defines a **global visual style** applied to every scene.
+For channel-format videos where the style changes across scenes (e.g. a
+monochrome → warm color arc), use **named variants**:
+
+```toml
+[style]
+prefix = ""           # optional, prepended before the composed scene text
+suffix = "Black and white cinematic street photography, photorealistic, film grain."
+
+  [style.variants.warm]
+  suffix = "Warm golden-hour cinematic grade."
+
+  [style.variants.cool]
+  suffix = "Cool blue-toned cinematic grade."
+```
+
+Per-scene selection:
+
+| Field | Effect |
+|---|---|
+| `style_variant = "warm"` | Selects `[style.variants.warm]` — its `suffix` replaces the base `suffix`. |
+| `style_variant = "none"` | Opts out of all style suffixes (base + variant). Prefix is still applied. |
+| *(omitted)* | Uses the base `[style]` suffix. |
+| `style_suffix = "sunset light"` | Scene-specific text appended **after** the variant/base suffix. |
+
+`none` is a **reserved name**: defining `[style.variants.none]` is a
+configuration error, so the opt-out keyword can never shadow a real variant.
+
+**Composition rule** (deterministic, no LLM):
+
+```
+final_prompt = [prefix] + composed_scene_text + [variant.suffix | base.suffix] + [scene.style_suffix]
+```
+
+The applied style is recorded per clip in `<manifest>-handoff.json` as
+`style_applied` (`variant`, `prefix`, `suffix`, `scene_suffix`), so downstream
+tools (Remotion, editors) can introspect it.
+
+**Resume:** each completed scene's state records a hash of its composed
+prompt. If you edit the style (or anything else that changes a scene's
+prompt) and re-run, only the affected scenes are regenerated — unchanged
+scenes are still skipped and cost no credits. State files written by older
+gflow-cli versions fall back to comparing the stored prompt text; scenes with
+no stored prompt are never re-run automatically.
+
 > **Consistency is best-effort, not pixel-exact.** gflow guarantees the *right
 > entity rides the wire* (`consistency_method = entity`); the final on-screen
 > fidelity is Flow's Veo R2V model, which may reinterpret minimalist or

{gflow_cli-0.25.0 → gflow_cli-0.27.0}/docs/PROJECT_STATUS.md

@@ -4,6 +4,43 @@
 
 ## Current release
 
+**v0.27.0 — alpha.** **Global `[style]` block with named variants + prompt-aware resume
+for `gflow movie` (#239).** A `movie.toml` can now express a visual style system once —
+`prefix`/`suffix` on `[style]` plus `[style.variants.*]` sub-tables — and select it
+per-scene via `style_variant` / `style_suffix` (deterministic composition, `none`
+reserved as the opt-out keyword). The handoff manifest records `style_applied`
+(variant/prefix/suffix/scene_suffix) per clip. Resume is now prompt-aware: completed
+scenes persist a `style_hash`; a scene whose composed prompt changed is regenerated
+instead of silently skipped, and dry-run marks it `re-run (style changed)`. Carries
+forward v0.26.0 (i2i select-in-place by UUID). Verification:
+[LIVE_VERIFICATION_v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (credit-free CLI ledger).
+
+**Develop (unreleased, post-v0.27.0):** *(empty — develop is the staging branch for the next release).*
+
+<details><summary>v0.26.0 — image i2i references a generated image by UUID (select in place)</summary>
+
+**v0.26.0 — alpha.** **Reference a generated image in `image i2i` by its Flow UUID.**
+A `reference_images` entry that is a media UUID is attached by **selecting the
+already-existing asset in Flow's reference picker** (located by UUID in the thumbnail
+URL, surfaced by display-name search when hidden) — no duplicate upload; local upload
+remains the fallback. Generated images also record their Flow `display_name` (credited
+@C1ph3r404). Verification: [LIVE_VERIFICATION_v0.26.0](LIVE_VERIFICATION_v0.26.0.md)
+(live e2e GREEN).
+
+</details>
+
+<details><summary>v0.25.0 — remote-UUID i2v + silent-failure guards</summary>
+
+**v0.25.0 — alpha.** **`video i2v` from a generated image's UUID proven live (#237)** —
+the picker-search attach was reworked to a local-upload path, producing a real 8s
+interpolation from a catalogued UUID. Home-`.env` config matrix (#240) verified live.
+Two silent failures made loud: video-as-image download rejection and rejected-upload
+fail-fast. Verification: [LIVE_VERIFICATION_v0.25.0](LIVE_VERIFICATION_v0.25.0.md).
+
+</details>
+
+<details><summary>v0.24.0 — `--project` parity across CLI + MCP</summary>
+
 **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
@@ -13,7 +50,7 @@ capability (`payload["project_id"]`) and validate the id identically. Carries fo
 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>
 
 <details><summary>v0.23.0 — MCP generation live + macOS 401 fixed</summary>
 
@@ -99,6 +136,10 @@ reporter-verified e2e on macOS).
 | Tools framework: `gflow tools` group + `--tool` + `creative-director` + "My Tools" + MCP parity | ✅ done (v0.22.0) |
 | MCP generation wired to FlowWorker (tool→queue→download→record) + `tools` applied + i2v/r2v boundary validation | ✅ done (v0.23.0) |
 | macOS generation 401 fixed — `/fx` cookie-path read + headed-context seed (#222/#230) | ✅ done (v0.23.0) |
+| `--project <id>` on `video t2v/i2v/r2v` + MCP `project` parameter (#233/#234/#235) | ✅ done (v0.24.0) |
+| `video i2v` from a generated image's UUID (#237) + home-`.env` matrix (#240) + silent-failure guards | ✅ done (v0.25.0) |
+| `image i2i` references a generated image by UUID — select in place, no duplicate upload + `display_name` capture | ✅ done (v0.26.0) |
+| `movie.toml` `[style]` block with named variants + prompt-aware resume (`style_hash`) (#239) | ✅ done (v0.27.0) |
 | `gflow video batch` (TSV manifest) on `ui_automation` | ⏳ Phase B |
 | Persistence layer (stay-mounted batch sessions across project boundaries) | ⏳ Phase B |
 | Provider abstraction for official Veo 3.1 API | ⏳ planned |

{gflow_cli-0.25.0 → gflow_cli-0.27.0}/docs/schemas/movie-handoff.schema.json

@@ -50,6 +50,15 @@
           "dialogue": { "type": "array" },
           "prompt": { "type": ["string", "null"] },
           "status": { "enum": ["completed", "failed"] },
+          "style_applied": {
+            "type": "object",
+            "properties": {
+              "variant": { "type": ["string", "null"] },
+              "prefix": { "type": ["string", "null"] },
+              "suffix": { "type": ["string", "null"] },
+              "scene_suffix": { "type": ["string", "null"] }
+            }
+          },
           "x_gflow": { "type": "object" }
         }
       }

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

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

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

{gflow_cli-0.25.0 → gflow_cli-0.27.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.25.0 → gflow_cli-0.27.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.25.0 → gflow_cli-0.27.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