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

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

@@ -7,6 +7,24 @@ 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
@@ -1812,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.26.0 → gflow_cli-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.26.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.26.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.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.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.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.26.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.26.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.26.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.26.0 → gflow_cli-0.27.0}/pyproject.toml

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

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

{gflow_cli-0.26.0 → gflow_cli-0.27.0}/src/gflow_cli/cli_movie.py

@@ -35,7 +35,14 @@ from gflow_cli._cli_helpers import _make_provider_dir, _resolve_profile, run_wit
 from gflow_cli.api.character import CharacterImageRequest
 from gflow_cli.api.client import FlowApiClient
 from gflow_cli.api.video import Aspect, GenerateVideoRequest, Mode, VideoModel, VideoStarted
-from gflow_cli.composition import Character, Scene, build_handoff, compose_prompt
+from gflow_cli.composition import (
+    Character,
+    Scene,
+    StyleSpec,
+    build_handoff,
+    compose_prompt,
+    resume_hash,
+)
 from gflow_cli.config import get_settings
 from gflow_cli.data.recorder import OperationRecorder
 from gflow_cli.errors import ConfigurationError, DataStoreError, WireFormatError
@@ -68,6 +75,10 @@ output_dir = "./out/my-movie"  # optional
 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."
 
 [[characters]]
 name = "Alice"
@@ -89,6 +100,7 @@ id = "arrival"
 action = "walks through a busy futuristic plaza, looking around with wonder"
 framing = "wide"
 characters = ["Alice"]
+style_variant = "warm"  # select [style.variants.warm]; omit for base style
 aspect = "16:9"
 duration = 8
 
@@ -99,6 +111,7 @@ framing = "close-up"
 characters = ["Alice"]
 speaker = "Alice"
 line = "We made it!"
+style_suffix = "golden hour light"  # appended after the variant/base suffix
 aspect = "16:9"
 duration = 6
 model = "veo-quality"
@@ -257,15 +270,33 @@ def _print_header(manifest: MovieManifest, *, out_dir: Path, dry_run: bool) -> N
     console.print(f"  characters: {len(manifest.characters)}  scenes: {len(manifest.scenes)}")
 
 
-def _format_scene_line(s: Scene, done: bool, cost: int) -> str:
+def _style_tag(s: Scene, style: StyleSpec) -> str:
+    """Return the resolved-style fragment for the plan line, or ''."""
+    bits: list[str] = []
+    if s.style_variant:
+        bits.append(f"style={s.style_variant}")
+    elif style.suffix:
+        bits.append("style=base")
+    if s.style_suffix:
+        bits.append("+style_suffix")
+    return ("  " + " ".join(bits)) if bits else ""
+
+
+def _format_scene_line(s: Scene, style: StyleSpec, *, done: bool, stale: bool, cost: int) -> str:
     """Return the single-line plan summary for one scene."""
     mode = "r2v" if s.characters else "t2v"
     refs = f"  refs=[{', '.join(s.characters)}]" if s.characters else ""
     framing_tag = f"  {s.framing}" if s.framing else ""
     model_tag = f"  {s.model}" if s.model else ""
     dur_tag = f"  {s.duration}s" if s.duration else ""
-    status = "[dim]skip (done)[/dim]" if done else f"{cost} credit(s)"
-    return f"    [{mode}] {s.id!r}{framing_tag}{model_tag}{dur_tag}{refs}  {status}"
+    if done:
+        status = "[dim]skip (done)[/dim]"
+    elif stale:
+        status = f"re-run (style changed)  {cost} credit(s)"
+    else:
+        status = f"{cost} credit(s)"
+    style_tag = _style_tag(s, style)
+    return f"    [{mode}] {s.id!r}{framing_tag}{model_tag}{dur_tag}{refs}{style_tag}  {status}"
 
 
 def _print_plan(manifest: MovieManifest, state: MovieState) -> None:
@@ -284,10 +315,14 @@ def _print_plan(manifest: MovieManifest, state: MovieState) -> None:
     scene_credits = 0
     for s in manifest.scenes:
         done_state = state.scenes.get(s.id)
-        done = done_state is not None and done_state.status == "completed"
+        done = False
+        stale = False
+        if done_state is not None and done_state.status == "completed":
+            stale = done_state.is_stale_for(compose_prompt(manifest.style, s, manifest.characters))
+            done = not stale
         cost = 0 if done else 1
         scene_credits += cost
-        console.print(_format_scene_line(s, done, cost))
+        console.print(_format_scene_line(s, manifest.style, done=done, stale=stale, cost=cost))
 
     console.print(f"\n  Estimated credits: ~{scene_credits}")
 
@@ -364,6 +399,7 @@ async def _run_one_scene(
             status="completed",
             prompt=prompt,
             consistency_method="entity" if reference_entities else "text",
+            style_hash=resume_hash(prompt),
         )
         state.save(state_path)
         console.print(f"    saved: {video_result.local_path}")
@@ -390,6 +426,7 @@ async def _run_one_scene(
             status="failed",
             prompt=prompt,
             consistency_method=failed_method,
+            style_hash=resume_hash(prompt),
         )
         state.save(state_path)
         if continue_on_error:
@@ -468,11 +505,20 @@ async def _run_movie(
             for scene in manifest.scenes:
                 scene_state = state.scenes.get(scene.id)
                 if scene_state is not None and scene_state.status == "completed":
-                    console.print(f"  [dim]Scene {scene.id!r} — already generated, skipping.[/dim]")
-                    if scene_state.local_path:
-                        completed_local_paths.append(Path(scene_state.local_path))
-                    generated_any = True
-                    continue
+                    prompt_now = compose_prompt(manifest.style, scene, manifest.characters)
+                    if scene_state.is_stale_for(prompt_now):
+                        console.print(
+                            f"  Scene {scene.id!r} — prompt/style changed since last "
+                            "run; regenerating."
+                        )
+                    else:
+                        console.print(
+                            f"  [dim]Scene {scene.id!r} — already generated, skipping.[/dim]"
+                        )
+                        if scene_state.local_path:
+                            completed_local_paths.append(Path(scene_state.local_path))
+                        generated_any = True
+                        continue
 
                 console.print(f"\n  Generating scene [bold]{scene.id!r}[/bold]…")
                 local_path = await _run_one_scene(

{gflow_cli-0.26.0 → gflow_cli-0.27.0}/src/gflow_cli/composition.py

@@ -8,6 +8,7 @@ the reusable seam a future second consumer (e.g. remotion) can import.
 
 from __future__ import annotations
 
+import hashlib
 from collections.abc import Mapping
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -16,7 +17,12 @@ from typing import Any, cast
 
 @dataclass(frozen=True)
 class StyleSpec:
-    """Global guiding prompt — every field optional, reused verbatim per scene."""
+    """Global guiding prompt — every field optional, reused verbatim per scene.
+
+    ``prefix`` / ``suffix`` are raw strings prepended / appended to the composed
+    prompt.  ``variants`` is a name → suffix mapping that lets a manifest express
+    a style arc (e.g. monochrome → warm) without repeating text in every scene.
+    """
 
     look: str | None = None
     palette: str | None = None
@@ -25,6 +31,22 @@ class StyleSpec:
     lighting: str | None = None
     mood: str | None = None
     negative: str | None = None
+    prefix: str | None = None
+    suffix: str | None = None
+    variants: Mapping[str, str] = field(default_factory=dict[str, str])
+
+    def resolve_suffix(self, variant_name: str | None) -> str | None:
+        """Return the named variant's suffix, or the base suffix when ``None``.
+
+        Raises ValueError on an unknown variant name (mirrors
+        ``Character.resolve_variant``).
+        """
+        if variant_name is None:
+            return self.suffix
+        if variant_name not in self.variants:
+            msg = f"unknown style variant {variant_name!r}"
+            raise ValueError(msg)
+        return self.variants[variant_name]
 
 
 @dataclass(frozen=True)
@@ -100,6 +122,8 @@ class Scene:
     model: str | None = None
     aspect: str = "16:9"
     count: int = 1
+    style_variant: str | None = None
+    style_suffix: str | None = None
 
 
 def _sentence(text: str) -> str:
@@ -164,6 +188,20 @@ def _framing_camera_block(scene: Scene, style: StyleSpec) -> str:
     return _sentence(framing_cam) if framing_cam else ""
 
 
+def resolve_style_suffix(style: StyleSpec, scene: Scene) -> str | None:
+    """Resolve the effective style suffix for a scene.
+
+    ``scene.style_variant = "none"`` → opt out of base and variant suffixes
+    (``scene.style_suffix`` is independent and still applied); the manifest
+    parser rejects a variant literally named "none" so the sentinel cannot
+    shadow a real variant. Otherwise defer to :meth:`StyleSpec.resolve_suffix`
+    (variant suffix, or base ``style.suffix`` when no variant is set).
+    """
+    if scene.style_variant == "none":
+        return None
+    return style.resolve_suffix(scene.style_variant)
+
+
 def compose_prompt(
     style: StyleSpec,
     scene: Scene,
@@ -171,12 +209,17 @@ def compose_prompt(
 ) -> str:
     """Assemble the final Veo prompt deterministically (canonical order).
 
-    Order: action, subject(+variant), setting, look, palette, lighting,
-    framing+camera, mood, dialogue, negative. Each slot: scene override ->
-    global -> omit. `negative` MERGES global+scene.
+    Order: [prefix] + action + subject(+variant) + setting + look + palette +
+    lighting + framing+camera + mood + dialogue + negative + [suffix].
+    Each slot: scene override -> global -> omit.  ``negative`` MERGES
+    global+scene.  ``prefix`` / ``suffix`` wrap the entire output.
     """
     parts: list[str] = []
 
+    # 0. PREFIX (raw — wraps the entire prompt)
+    if style.prefix:
+        parts.append(style.prefix)
+
     # 1. ACTION (required)
     parts.append(_sentence(scene.action))
 
@@ -221,9 +264,28 @@ def compose_prompt(
     if negs:
         parts.append(f"Avoid: {', '.join(negs)}.")
 
+    # 11. SUFFIX (variant or base — raw)
+    suffix = resolve_style_suffix(style, scene)
+    if suffix:
+        parts.append(suffix)
+
+    # 12. SCENE STYLE_SUFFIX (raw, always last)
+    if scene.style_suffix:
+        parts.append(scene.style_suffix)
+
     return " ".join(p for p in parts if p)
 
 
+def resume_hash(prompt: str) -> str:
+    """Return the full SHA-256 hex digest of *prompt* for resume change detection.
+
+    Same digest as ``gflow_cli.data.redaction.prompt_fields`` computes for
+    observability; duplicated here because this module deliberately imports
+    nothing from the rest of the package (pure seam).
+    """
+    return hashlib.sha256(prompt.encode("utf-8")).hexdigest()
+
+
 def _build_handoff_characters(manifest: Any, state: Any) -> list[dict[str, Any]]:
     """Build the ``characters`` list for the handoff manifest."""
     chars_out: list[dict[str, Any]] = []
@@ -261,6 +323,19 @@ def _build_handoff_clip(
         stored = getattr(ss, "prompt", None) if ss else None
         prompt_val = stored or compose_prompt(manifest.style, scene, manifest.characters)
 
+    # Style applied — the styling baked into this clip's prompt. Resolved from
+    # the current manifest; the resume check in cli_movie regenerates a scene
+    # whenever its composed prompt changes, so this stays consistent with the
+    # stored prompt for every clip that survives a run.
+    style_applied: dict[str, Any] = {
+        "variant": scene.style_variant,
+        "prefix": manifest.style.prefix,
+        "suffix": resolve_style_suffix(manifest.style, scene),
+        "scene_suffix": scene.style_suffix,
+    }
+    if all(v is None for v in style_applied.values()):
+        style_applied = {}
+
     return {
         "id": scene.id,
         "index": index,
@@ -274,6 +349,7 @@ def _build_handoff_clip(
         ],
         "prompt": prompt_val,
         "status": status,
+        "style_applied": style_applied,
         "x_gflow": {
             k: v
             for k, v in (