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

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

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.27.1] — 2026-07-07
+
+### Fixed
+
+- **Version Wiring in Movie Handoff:** Properly imported and passed `__version__` to `build_handoff()` generator version instead of using a hardcoded stale default (`0.14.0`).
+- **Rich Markup Escaping in CLI Output:** Escaped brackets in `_format_scene_line` plan output (`[t2v]`, `[r2v]`, and `refs=[...]`) so they are not swallowed by Rich console formatting.
+- **MCP Server Stale Version:** Wired FastMCP version to `__version__` dynamically on startup, fixing the stale `0.21.0` version trap.
+- **MCP Agent Guide:** Added `gflow_list_tools` to the list of available tools in the static MCP agent guide resource.
+
+### Added
+
+- **Document Anchors:** Added HTML anchor (`style-configuration-errors`) to `docs/MOVIE.md` for reserved name `"none"` and unknown style variant `ConfigurationError` paths.
+- **Movie Usages Documentation:** Added complete documentation for `gflow movie run` and `gflow movie template` commands to `docs/USAGE.md`.
+
+## [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 +1844,11 @@ 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.1...HEAD
+[0.27.1]: https://github.com/ffroliva/gflow-cli/compare/v0.27.0...v0.27.1
+[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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.26.0
+Version: 0.27.1
 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.1}/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.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.27.1/docs/LIVE_VERIFICATION_v0.27.0.md

@@ -0,0 +1,107 @@
+# 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
+
+- Signed tag `v0.27.0` pushed 2026-07-07; `Release` workflow green
+  (build-and-publish 37s, digital attestations generated).
+- GitHub Release **v0.27.0** published 2026-07-07T21:16:40Z (not draft).
+- PyPI: `gflow-cli 0.27.0` live — `gflow_cli-0.27.0-py3-none-any.whl` +
+  `gflow_cli-0.27.0.tar.gz` (verified via the PyPI JSON API).
+- Release PR #260 (`chore/release-v0.27.0 → main`) merged with a merge commit
+  after a fully green matrix + SonarCloud gate; branch deleted.
+- `main` back-merged into `develop` (`2909cb6`) — branches aligned.
+
+## 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.27.1/docs/LIVE_VERIFICATION_v0.27.1.md

@@ -0,0 +1,26 @@
+# Live Verification — v0.27.1
+
+Release date: 2026-07-07. Headline: **v0.27.0 release follow-up fixes and documentation sync** (Issue #239, PR #261).
+
+Verification run: 2026-07-07, local validation gates, Windows, `.venv` build of the release tree. **Deliberately credit-free**: this patch release contains only default parameter wiring, Rich console escaping, MCP guide documentation synchronization, and user documentation. No live Flow REST api/browser automation code paths were changed, so no live generation credits were spent.
+
+## Scope
+
+| Change | Surface | Verdict |
+|---|---|---|
+| Wire package version `__version__` as default `version` in `build_handoff()` | `composition.py` | ✅ Unit tests pass (`test_build_handoff_shape_and_schema`) |
+| Escape brackets `\[` in plan output mode and refs | `cli_movie.py` | ✅ Unit tests pass (`test_format_scene_line_escapes_brackets_for_rich`) |
+| Add `gflow_list_tools` to MCP agent guide | `mcp/resources.py` | ✅ MCP guide resource updated |
+| Set `__version__` on FastMCP server on startup | `mcp/server.py` | ✅ MCP tests pass |
+| Add HTML anchors for style configuration errors | `docs/MOVIE.md` | ✅ Document checked via `check_doc_links.py` |
+| Add `gflow movie` subcommands documentation | `docs/USAGE.md` | ✅ USAGE.md updated and link-checked |
+
+## Evidence ledger (Verification Gates)
+
+All local quality gates executed in order as a merge-readiness baseline:
+1. **Hygiene check:** `check_repo_hygiene.py` ran with 0 violations across 505 tracked files.
+2. **Internal links check:** `check_doc_links.py` successfully resolved all internal markdown links across 24 files (including `docs/MOVIE.md` and `docs/USAGE.md`).
+3. **Lint check:** `ruff check src tests` passed with 0 errors.
+4. **Formatting check:** `ruff format --check src tests` verified all files are formatted.
+5. **Type check:** `pyright src` completed with 0 errors and 0 warnings.
+6. **Tests run:** 2056 tests passed, 16 skipped, 55 deselected.

{gflow_cli-0.26.0 → gflow_cli-0.27.1}/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,57 @@ 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. |
+
+<a name="style-configuration-errors"></a>
+### Style Configuration Errors
+
+There are two style configuration errors that will raise a `ConfigurationError`:
+* **Reserved `none` name:** Defining `[style.variants.none]` is a configuration error, so the opt-out keyword can never shadow a real variant.
+* **Unknown variant name:** Specifying a `style_variant` in a scene that does not exist in `[style.variants]` (and is not `"none"`) is a configuration error.
+
+**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.1}/docs/PROJECT_STATUS.md

@@ -4,6 +4,49 @@
 
 ## Current release
 
+**v0.27.1 — alpha.** **v0.27.0 release follow-up fixes and documentation sync (#239).** Patch release wiring package version dynamically to `build_handoff()` and `FastMCP` server, escaping brackets in Rich console planning output, updating MCP agent guide, and adding `gflow movie` usage documentation. Verification: [LIVE_VERIFICATION_v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (credit-free baseline verification).
+
+**Develop (unreleased, post-v0.27.1):** *(empty — develop is the staging branch for the next release).*
+
+<details><summary>v0.27.0 — Global [style] block with named variants + prompt-aware resume for gflow movie</summary>
+
+**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).
+
+</details>
+
+<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 +56,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 +142,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.1}/docs/USAGE.md

@@ -1044,6 +1044,84 @@ GFLOW_EXAMPLE_PROFILE=<your-profile> python examples/batch_from_config.py
 
 The bundled `examples/sample_config.json` produces three images at three aspect ratios in `gflow-output/example-batch/`. Copy and edit for your own scenes.
 
+## `gflow movie`
+
+Sequential TOML-described multi-scene AI movie generation. New in v0.14.0.
+
+### `gflow movie template`
+
+Writes a starter `movie.toml` template.
+
+```text
+gflow movie template [OUTPUT] [--force]
+```
+
+* `OUTPUT`: The destination path for the template file (defaults to `./movie.toml`).
+* `--force`: Overwrite the destination file if it already exists.
+
+### `gflow movie run`
+
+Generates individual video clips sequentially from a single TOML manifest file, maintaining crash-recoverable state in a local state JSON file.
+
+```text
+gflow movie run MANIFEST [--out-dir DIR] [--profile NAME] [--continue-on-error|--fail-fast] [--dry-run] [--stitch]
+```
+
+Refer to the complete [Movie Manifests Guide](MOVIE.md) for detailed syntax, character entity creation, and style consistency features.
+
+### Parameters
+
+* `MANIFEST`: Path to your `movie.toml` manifest file (required positional argument).
+* `--out-dir DIR`: Output directory for generated video clips and the handoff file. Defaults to `out/` or `GFLOW_CLI_OUTPUT_DIR`.
+* `--profile NAME`: Specify Google Flow profile to use.
+* `--continue-on-error`: Skip failed scenes and continue generating subsequent scenes (default).
+* `--fail-fast`: Terminate immediately on the first failed scene generation.
+* `--dry-run`: Parse the manifest, estimate credits, and print the generation plan without calling Google Flow.
+* `--stitch`: Run a post-generation preview stitch using ffmpeg to concatenate clips into a single video file.
+
+### Manifest structure (movie.toml)
+
+```toml
+title = "My Cinematic Film"
+project = "Cinematics"
+
+[style]
+look = "3d animation"
+mood = "mysterious"
+negative = "text, watermark"
+prefix = "Cinematic film still, high detail."
+suffix = "Shot on IMAX 70mm, unreal engine 5 render."
+
+[style.variants.warm]
+suffix = "Golden hour light, warm color grading."
+
+[[characters]]
+name = "Stickman"
+identity = "text"
+voice = "alnilam"
+
+[[scenes]]
+id = "scene_01"
+action = "A mysterious stickman walks slowly through a dark forest."
+framing = "wide"
+duration = 5
+characters = ["Stickman"]
+
+[[scenes]]
+id = "scene_02"
+action = "Close up of the stickman looking back in shock."
+framing = "close-up"
+duration = 5
+characters = ["Stickman"]
+style_variant = "warm"
+```
+
+### Outputs
+
+1. **Clip Files:** Individual video files saved under `<out_dir>/scene_<id>.mp4` (or other formats).
+2. **State File:** A `<stem>-state.json` file recording completed operations, seeds, and metadata, allowing a run to resume without wasting credits.
+3. **Handoff Manifest:** A `<stem>-handoff.json` file that projects the run's metadata and clip paths, designed for downstream assemblers.
+
 ## Recipes
 
 ### Burn through a directory of inputs

{gflow_cli-0.26.0 → gflow_cli-0.27.1}/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.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.26.0"
+version = "0.27.1"
 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.1}/scripts/ci/check_doc_links.py

@@ -40,6 +40,8 @@ FILES: tuple[str, ...] = (
     "docs/USER_GUIDE.md",
     "docs/LIVE_VERIFICATION_v0.8.1.md",
     "docs/CHARACTER.md",
+    "docs/MOVIE.md",
+    "docs/LIVE_VERIFICATION_v0.27.1.md",
 )
 
 # [text](target) — non-greedy text, balanced target (no nested parens).

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

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