gflow-cli 0.44.0__tar.gz → 0.45.0__tar.gz

{gflow_cli-0.44.0 → gflow_cli-0.45.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gflow",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "Reusable development and operations workflows for gflow-cli",
   "author": {
     "name": "Flavio Oliva",

{gflow_cli-0.44.0 → gflow_cli-0.45.0}/.pre-commit-config.yaml

@@ -23,8 +23,10 @@
 default_stages: [pre-commit]
 
 repos:
+  # Keep this rev in lockstep with the `ruff==` pin in pyproject.toml. A hook that
+  # formats with an older ruff than CI checks with will fight CI on every commit.
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.10
+    rev: v0.16.0
     hooks:
       - id: ruff
         args: [--fix]

{gflow_cli-0.44.0 → gflow_cli-0.45.0}/AGENTS.md

@@ -81,6 +81,23 @@ These rules exist because docs alone don't bind under momentum: a "check open PR
 - **If a claim can't be verified in the current environment, it's LIKELY — not CONFIRMED.** Keep the issue open, reference it with `Refs #N` (not `Closes #N`), and ship diagnostics rather than a blind fix. When you can't reproduce it, hand the fix to whoever can.
 - **This project reverse-engineers a blackbox.** gflow-cli doesn't own Google Flow — it drives real Flow through inspected HAR/DOM/browser-log behavior. Offline checks (types, lint, unit/BDD tests) verify *our* code does what we think it does; they cannot verify Flow still behaves the way we captured it. Every feature that touches a generation path is **live-verified**, not just offline-tested, before it's called done — see `/gflow:live-verify`.
 
+## Standard Workflow Sequence
+
+All AI agents and harnesses working on `gflow-cli` follow this standard 10-phase pipeline from issue discovery to public release:
+
+| Phase | Skill / Command | Purpose | Output Artifact |
+|---|---|---|---|
+| 1. Triage | `/gflow:issue-assessment <N>` | Read-only issue analysis & root cause hypothesis | `issue_assessment_<N>.md` |
+| 2. Pre-Implementation | `/gflow:predict <proposal>` | Adversarial audit (D14 YAGNI, security, risks) | GO / CAUTION / STOP verdict |
+| 3. BDD Scaffolding | `/gflow:scenario <feature>` | Edge-case explorer & BDD Gherkin spec | `Scenario:` blocks & test scaffold |
+| 4. Implementation Plan | `/gflow:plan <feature>` | Task-by-task atomic implementation plan | `docs/superpowers/plans/<date>-<slug>/PLAN.md` |
+| 5. Council Review | `/gflow:pr-council-review` / `llm-council` | Multi-dimensional audit across 6 core dimensions | Consensus verdict report |
+| 6. Task Execution | `/gflow:status` | Track unchecked tasks during TDD execution | Next unchecked task |
+| 7. Pre-Commit Quality | `/gflow:check` | The Impeccable Routine (hygiene, ruff, pyright, pytest) | All green local checks |
+| 8. Live Verification | `/gflow:live-verify` | 5-layer proof against real Flow transport | `docs/LIVE_VERIFICATION_vX.Y.Z.md` |
+| 9. PR & Issue Close | `/gflow:issue-resolve <N>` | PR, SonarCloud 0-issue gate, merge to develop | Closed GitHub issue |
+| 10. Release Pipeline | `/gflow:release` | Version bump, signed tag (`git tag -s`), PyPI publish | Shipped release & back-merge |
+
 ## Skills reference (cross-tool)
 
 The `skills/` directory ships installable agent skill docs in plain Markdown with YAML frontmatter. Any agent can consume them directly:

{gflow_cli-0.44.0 → gflow_cli-0.45.0}/CHANGELOG.md

@@ -7,6 +7,88 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.45.0] — 2026-07-28
+
+### Fixed
+
+- **`gflow character create` binds portraits to the character again (#395).**
+  Two independent defects made every character generation land as a plain
+  project image, leaving the character empty:
+  1. **Overlay dismissal Escaped Flow's own UI.** `[role='dialog']` and
+     `[role='alert']` had been added to the overlay detector, but Flow's
+     character composer (and the media picker) carry those roles — so gflow
+     pressed Escape on the app itself, the generation went out without
+     `entityContext`, and Flow filed the image against the project with no
+     `parentEntityId`. Those two selectors are removed; `[role='banner']` and
+     the announcement matcher remain, so the original banner-dismissal intent
+     is intact.
+  2. **The character route could bounce back to the project page.** Flow
+     redirects `/project/{id}/character/{entityId}` when the entity is not yet
+     queryable — a race gflow loses by navigating immediately after
+     `flow.createEntity`. Because the project page also mounts a prompt box,
+     the old readiness check was satisfied on the wrong surface and the prompt
+     was typed into the **project** composer. gflow now verifies it actually
+     came to rest on the character route, re-navigating a few times and failing
+     loudly rather than generating on the wrong surface.
+
+  Verified live 2026-07-28 in both directions on the same account, plus a
+  read-back showing the character carrying its name and `thumbnail_media_id`.
+  The wire contract is documented in
+  [CHARACTER_RECON](docs/CHARACTER_RECON.md#entity-binding-entitycontext-captured-live-2026-07-28).
+
+- **`gflow image i2i --ref <UUID>` no longer fails when the asset is out of the
+  picker's reach (#393).** Flow's media picker is scoped to the active project
+  and its search does **not** index media UUIDs (confirmed live 2026-07-27:
+  both UUID search tiers returned zero tiles), so a `--ref` pointing at an asset
+  in another project — or buried deep in a virtualised grid — could not be
+  selected, and a bare `--ref <uuid>` carried no local file to fall back on. The
+  CLI now resolves each UUID ref against the local catalog and attaches its
+  recorded file, so the transport uploads those exact bytes instead of failing
+  the run. Verified live as a controlled A/B on identical input: exit 9 before,
+  exit 0 with the upload fallback after. Enrichment is best-effort (unknown
+  asset, unavailable catalog, or deleted file leaves the ref untouched) and the
+  **fail-loud contract is unchanged** — a reference that cannot be bound still
+  aborts the generation rather than silently producing an unreferenced image.
+- **A Flow web-app crash on the character-editor route is now reported as
+  such.** `gflow character create` surfaced Flow's client-side crash as
+  `RuntimeError: Character editor not ready: prompt textbox not visible`, which
+  blames a selector that was never on the page. The existing crash classifier is
+  now consulted at that gate too, yielding the typed, retryable `FlowAppError`
+  (exit 31). Observed live 2026-07-27 via the incident bundle's `ui.json`
+  (`title.category: flow_app_crash`).
+- **Character binding failures say what actually happened.** When Flow returns a
+  workflow that is not bound to the character entity, the error read "Unexpected
+  response shape from Flow", sending readers after a wire-format bug. It now
+  states that Flow filed the image as a plain project image and the character
+  has no portrait. The guard remains strict — verified live that unbound runs
+  leave the entity as "Untitled Character" with a null thumbnail.
+- **Tier-aware credit confirmations:** `gflow video chain` and `gflow movie run`
+  no longer present pending work as an exact one-credit-per-link/scene charge.
+  Plans, confirmation prompts, `--dry-run` output, Click help, and current docs
+  now report the count of *pending video operations* and direct operators to
+  Google Flow for current model/duration/tier pricing, which varies by account
+  tier and Flow policy. Execution, resume/stale accounting, `--yes`, JSON
+  output, flags, and exit codes are unchanged.
+
+### Added
+
+- **Top Banner & Modal Dismissal (#369):** Expanded `_detect_overlay` and
+  `_dismiss_blocking_overlays` in `ui_automation.py` to detect top banners,
+  alert bars, and announcement dialogs (`[role='banner']`, `[role='alert']`,
+  `[role='dialog']`, `div:has-text('What\'s new')`), force-clicking locale-stable
+  close/clear/Got-it buttons and falling back to Escape before automation tasks.
+- **`gflow character create --format-prompt` (#383):** Opt-in flag that clicks
+  Flow's in-editor **Format** button before submitting, letting Flow rewrite the
+  prompt into its character prompt-engineering shape. Applies to both the face and
+  body slots. Best-effort by design — if the button is not found the prompt is
+  submitted as typed rather than failing the generation. The selector cascade is
+  anchored on the locale-stable `personal_recommendations` Material Symbols
+  ligature (confirmed against live DOM 2026-07-27), not the "Format" label, which
+  Flow localises to the Chrome profile language. Flow ships the button `disabled`
+  on an empty prompt, so the driver checks enabled-ness — a disabled button is
+  still *visible*, and clicking one would stall on Playwright's actionability wait.
+- **Self-documenting error remediation & provider message pass-through (#380):** Added default `remediation_hint` strings across domain exception classes (`WireFormatError`, `ContentPolicyError`, `RateLimitError`, `DataStoreError`, `SceneConcatError`, `FrameExtractionError`), extracted and sanitized provider error messages from Google Flow tRPC/REST responses, and enriched MCP tool error envelopes and Rich CLI error displays with actionable recovery guidance at failure time.
+
 ## [0.44.0] — 2026-07-26
 
 ### Added
@@ -2384,7 +2466,8 @@ shell-script template that branches on these codes.
 
 First skeleton. Not functional end-to-end yet.
 
-[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.44.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.45.0...HEAD
+[0.45.0]: https://github.com/ffroliva/gflow-cli/compare/v0.44.0...v0.45.0
 [0.44.0]: https://github.com/ffroliva/gflow-cli/compare/v0.43.0...v0.44.0
 [0.43.0]: https://github.com/ffroliva/gflow-cli/compare/v0.42.0...v0.43.0
 [0.42.0]: https://github.com/ffroliva/gflow-cli/compare/v0.41.0...v0.42.0

{gflow_cli-0.44.0 → gflow_cli-0.45.0}/KNOWN_ISSUES.md

@@ -824,6 +824,34 @@ gflow image batch ./batch-b.tsv --profile personal
 
 ## Resolved
 
+### `character create` generated portraits that never bound to the character — RESOLVED in v0.45.0
+
+- **Status:** Resolved ([#395](https://github.com/ffroliva/gflow-cli/issues/395)) · **Severity:** Was-High · **Was-affecting:** v0.44.0 and unreleased `develop` · **Fixed in:** v0.45.0
+
+Every `gflow character create` spent an Imagen credit, produced an image, and
+left the character empty ("Untitled Character", null thumbnail). Flow filed the
+generation as an ordinary project image because the request carried no
+`entityContext`. Two independent gflow defects caused it:
+
+1. **Overlay dismissal Escaped Flow's own UI.** `[role='dialog']` and
+   `[role='alert']` had been added to the overlay detector, but Flow's character
+   composer — and the media picker — carry those roles. gflow pressed Escape on
+   the app itself and the submit lost its entity context.
+2. **The character route could bounce to the project page.** Flow redirects
+   `/project/{id}/character/{entityId}` while the entity is not yet queryable
+   (gflow navigates immediately after `flow.createEntity`). The project page
+   also mounts a prompt box, so the readiness gate passed on the wrong surface
+   and the prompt was typed into the **project** composer.
+
+Both are fixed: the two over-broad selectors are gone (banner detection intact),
+and the transport now verifies it came to rest on the character route,
+re-navigating and then failing loudly instead of generating on the wrong
+surface. The `parentEntityId` guard that surfaced this was correct throughout —
+it refused to report a portrait-less character as success.
+
+Wire contract: [CHARACTER_RECON § entity binding](docs/CHARACTER_RECON.md#entity-binding-entitycontext-captured-live-2026-07-28).
+Evidence: [LIVE_VERIFICATION_v0.45.0 §2](docs/LIVE_VERIFICATION_v0.45.0.md).
+
 ### `gflow video`'s manifest-driven batch subcommand didn't skip already-completed entries — RESOLVED as obsolete
 
 - **Status:** Resolved (obsolete) · **Severity:** Was-Medium · **Was-affecting:** v0.2.0a1 through the command's removal · **Fixed in:** n/a — removed in production-readiness hardening (see `fix: remove nonfunctional video batch command`)

{gflow_cli-0.44.0 → gflow_cli-0.45.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.44.0
+Version: 0.45.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
@@ -58,7 +58,7 @@ Requires-Dist: numpy>=1.24; extra == 'dev'
 Requires-Dist: pyright>=1.1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Requires-Dist: ruff==0.15.22; extra == 'dev'
+Requires-Dist: ruff==0.16.0; extra == 'dev'
 Provides-Extra: gcs
 Requires-Dist: gcsfs>=2024.2.0; extra == 'gcs'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 'gcs'

{gflow_cli-0.44.0 → gflow_cli-0.45.0}/docs/CHARACTER_RECON.md

@@ -82,6 +82,76 @@ calls on the same `workflowId`, chaining `imageInputs` (BASE_IMAGE = prior outpu
 This is the SAME endpoint family gflow's existing image transport already drives — the new bits are
 `tool:"PINHOLE"`, `imageInputs` types, and the `parentEntityId`/workflow binding.
 
+## Entity binding: `entityContext` (captured live 2026-07-28)
+
+**The generation request must carry `entityContext`, or Flow files the image as a
+plain project image and the character stays empty.** Captured from Flow's own UI
+via a CDP-attached real Chrome (`gflow-agent-browser-spike`, `navigator.webdriver:
+false`) while driving the plain **New Character** flow.
+
+`POST /v1/projects/{projectId}/flowMedia:batchGenerateImages`
+
+```jsonc
+{
+  "clientContext": { "projectId": "…", "tool": "PINHOLE", "sessionId": "…" },
+  "mediaGenerationContext": {
+    "batchId": "…",
+    "entityContext": {
+      "entityId": "1e6c558e-87be-4aa7-8a21-ffb7efa43bbd",
+      "characterSlot": { "imageReferenceIndex": 0 }   // 0 = portrait/face, 1 = body
+    }
+  },
+  "useNewMedia": true,
+  "requests": [ { "imageModelName": "NARWHAL", "structuredPrompt": {…}, "seed": …, "imageInputs": [] } ]
+}
+```
+
+Response — bound on the first try:
+
+```jsonc
+"workflows": [ { "name": "30551aa7-…", "projectId": "…", "parentEntityId": "1e6c558e-…" } ]
+```
+
+### Which surface produces it
+
+The composer Flow renders depends on whether the character already HAS a
+portrait, not on which URL you arrived by:
+
+| Character state | Composer placeholder | Sends `entityContext`? |
+|---|---|---|
+| Empty (no portrait yet) | *"Describe your character…"* | **Yes** — this is the creation composer, on `/characters` **and** on `/character/{entityId}` |
+| Populated (portrait exists) | *"What do you want to change?"* | Edit surface — refines the existing portrait |
+
+Both entry points reach the creation composer for an empty character, and both
+bind. Verified live 2026-07-28: driving `/project/{id}/character/{entityId}` for
+a pre-created empty entity produced `entityContext` in the request and
+`parentEntityId` in the response — including for an entity gflow itself had
+created minutes earlier. Entity age is not a factor.
+
+`flow.createEntity` may be called by Flow (the **New Character** flow does it
+itself, returning `displayName: "Untitled Character"`) or by the client
+beforehand; gflow pre-creates and deep-links, which is fine. After the
+generation Flow issues `PATCH /v1/flowWorkflows/{id}` twice
+(`metadata.displayName`, then `metadata.primaryMediaId`) — the same commit gflow
+already performs. Flow never asks for a name up front: the user renames
+afterwards via the ✏️ next to the title, and "Character Info (optional)"
+(*"Describe how your character acts…"*) is a separate free-text field.
+
+**What actually broke gflow (#395)** was therefore NOT the choice of entry
+point. Two client-side defects suppressed `entityContext` on a surface that
+would otherwise have sent it:
+
+1. **Overlay dismissal pressed Escape on the composer.** `[role='dialog']` and
+   `[role='alert']` in the overlay detector matched Flow's own character
+   composer (and the media picker), so gflow dismissed the app itself.
+2. **The character route could bounce back to the project page** while the
+   entity was not yet queryable. The project page also mounts a prompt box, so
+   the readiness gate passed on the wrong surface and the prompt was typed into
+   the **project** composer.
+
+With both fixed, the deep-linked editor binds reliably. See
+[LIVE_VERIFICATION_v0.45.0 §2](LIVE_VERIFICATION_v0.45.0.md).
+
 ## Gaps
 
 1. ✅ **RESOLVED — Entity create.** `POST /fx/api/trpc/flow.createEntity` `{json:{projectId}}` →

{gflow_cli-0.44.0 → gflow_cli-0.45.0}/docs/CONFIGURATION.md

@@ -343,9 +343,9 @@ each link in turn, so total wallclock is the sum of all link waits).
 |---|---|---|
 | `--model` | `veo-lite` | `veo-lite` / `veo-fast` / `veo-quality` / `veo-lite-lp`. `omni-flash` is rejected — it can't seed i2v links (issue #125). |
 | `--max-links N` | unset | Cap link count; exit 11 (`ConfigurationError`) if the manifest has more. A spend guardrail. |
-| `-y` / `--yes` | off | Skip the per-credit cost confirmation prompt. |
-| `--dry-run` | off | Print the plan + credit estimate and spend nothing. |
-| `--resume-from CHAIN_ID` | unset | Resume a prior chain by its id; already-paid links are skipped (not re-billed). |
+| `-y` / `--yes` | off | Skip the pending video operation confirmation prompt. |
+| `--dry-run` | off | Print the pending video operation plan and submit nothing. |
+| `--resume-from CHAIN_ID` | unset | Resume a prior chain by its id; already-completed links are skipped (not regenerated). |
 | `--jitter F` | `0.0` | Random `0..F` second pause **between** links (anti-bot cadence; never before link 0). |
 | `--seed-offset MS` | `0` | Extract the seed frame this many ms before EOF (fade-to-black guard). |
 | `--aspect` | `9:16` | `9:16` / `16:9`. Applied uniformly to every link (continuity requirement). |

{gflow_cli-0.44.0 → gflow_cli-0.45.0}/docs/INDEX.md

@@ -55,6 +55,8 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | [docs/superpowers/plans/2026-07-18-asset-tagging/PLAN.md](superpowers/plans/2026-07-18-asset-tagging/PLAN.md) | Task-by-task implementation plan for asset tagging (spike gate → resolver → CLI/MCP → live e2e) | Tracking task-by-task execution of the `@`-mention feature |
 | [docs/superpowers/specs/2026-07-19-live-verify-design.md](superpowers/specs/2026-07-19-live-verify-design.md) | `/gflow:live-verify` design spec: pre-flight state check + per-feature live-verification gate generalizing release step 4b, council-reviewed | Reviewing or implementing the live-verification enforcement skill |
 | [docs/superpowers/plans/2026-07-19-live-verify/PLAN.md](superpowers/plans/2026-07-19-live-verify/PLAN.md) | Task-by-task implementation plan for `/gflow:live-verify` (skill file → AGENTS.md/check.md wiring → INDEX row) | Tracking task-by-task execution of the live-verify skill |
+| [docs/superpowers/plans/2026-07-27-tier-aware-credit-confirmations/SCENARIO.md](superpowers/plans/2026-07-27-tier-aware-credit-confirmations/SCENARIO.md) | Edge-case matrix for replacing fixed chain/movie credit estimates with truthful pending-operation guidance | Reviewing the financial-safety, resume, dry-run, and compatibility scenarios |
+| [docs/superpowers/plans/2026-07-27-tier-aware-credit-confirmations/PLAN.md](superpowers/plans/2026-07-27-tier-aware-credit-confirmations/PLAN.md) | TDD implementation plan for tier-aware chain/movie planning and confirmation output | Tracking the isolated runtime pricing-guidance bugfix |
 
 ## Agent commands
 
@@ -133,7 +135,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A command failed — where is the incident bundle and what's in it?"** → [DEBUGGING § Automatic incident bundles](DEBUGGING.md#automatic-incident-bundles) (layout, triggers, review-before-sharing); privacy boundaries: [SECURITY § Automatic incident bundles](SECURITY.md#automatic-incident-bundles-gflow_cli_incident_capture-default-on); disable via [CONFIGURATION § GFLOW_CLI_INCIDENT_CAPTURE](CONFIGURATION.md#gflow_cli_incident_capture)
 **"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.44.0](LIVE_VERIFICATION_v0.44.0.md) (**#381 dual-side project management & Playwright Chromium transport live-verified 2026-07-26** — real-editor project creation + rename tRPC server/DOM sync, prompt slugging, `gflow project` subcommand family, HTTP 429 adaptive backoff, and full E2E test suite). Prior: [v0.43.0](LIVE_VERIFICATION_v0.43.0.md) (**private incident diagnostics live-verified 2026-07-23, 1 Veo credit**). Prior: [v0.42.0](LIVE_VERIFICATION_v0.42.0.md) (**#361 production-readiness live-gaps confirmed live 2026-07-21, 1 Veo credit** — a real `veo-lite` t2v through the worker path persisted a real `remote_started` checkpoint [observer→checkpoint→DB chain confirmed], crash-recovery classified the task `indeterminate` without resubmitting, and mid-launch cancellation released the `ProfileLease` credit-free; full evidence in [v0.40.0-production-readiness § "2026-07-21 live follow-up"](LIVE_VERIFICATION_v0.40.0-production-readiness.md#2026-07-21-live-follow-up-0420-cycle); #359 content-safety `400`→`ContentPolicyError` classification is unit-covered, not live-triggered [would require a deliberate policy violation]; #360/#362 are docs-only, verified by the documentation gates). Prior: [v0.41.0](LIVE_VERIFICATION_v0.41.0.md) (**#357 production-readiness hardening — stale-session fail-fast, free image gen, paid veo-lite T2V all proven live**). Prior: [v0.40.0](LIVE_VERIFICATION_v0.40.0.md) (**#344 `@`-mention asset-tagging resolution proven live e2e, ~2 Imagen credits** — `gflow character create` staged a real taggable character [bound reference images, `has_reference_images` guard], the e2e test's documented propagation wait cleared Flow's `projectInitialData` lag, and `gflow image t2i "@Zoro …"` passed with returncode 0, a real generated image, and the correctly de-tagged prompt in the catalog — no code changes needed, `resolve_and_apply` as merged in #344 already works end-to-end; pre-existing unrelated issue #174 [Flow media-library A/B flake] can still intermittently block generation regardless of this feature — recorded, not omitted). Prior: [v0.39.0](LIVE_VERIFICATION_v0.39.0.md) (**#341 failed-generation persistence proven live** — a real `image t2i` on denon82 failed at the wire [`batchGenerateImages` HTTP 400 → `WireFormatError`] and the record-on-catch funnel wrote the **first-ever `failed` row** into the production catalog [`error_type=wire-format`, redacted `error_detail`, browsable via `gflow data list errors`], **$0**; the remaining paid paths [video/chain/batch/movie/worker] are funnel-regression-tested, not force-failed live [would cost credits], and the status-aware `succeeded=false` video-poll fix is unit-locked — recorded, not omitted). Prior: [v0.38.1](LIVE_VERIFICATION_v0.38.1.md) (**#338 agentic-pin recovery proven live ON the pinned account** — run 1 caught the composer-render race the unit suite could not [`ensure_media_incomplete` +115 ms, toggle never reached]; the readiness-wait fix landed and run 2 recovered classic on denon82 after ~2h of pin [`ui_driver.bound mode=classic`, real 768×1376 JPEG, exact prompt adherence]; reload branch unit-locked, live trigger not observed this cycle — recorded, not omitted). Prior: [v0.38.0](LIVE_VERIFICATION_v0.38.0.md) (**#332 mode control + #314 i2i ref dedup proven live e2e** — `image t2i --ui-mode classic` recovered agentic→classic in a real run [`ui_mode.attempt_exit_agent` → full classic chain, 1376×768 JPEG]; two identical `image i2i` runs proved the dedup contract [run 1: picker miss → `image_uploaded`; run 2: `reference_deduped_by_filename`, ZERO uploads]; `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 15.2 MB `ftyp` mp4]; autopilot #333 recorded deferred-with-reason [hermes-ops deployment staged separately]). Prior: [v0.37.0](LIVE_VERIFICATION_v0.37.0.md) (**viewport 1920×1080 + agentic count enforcement + FIPS-safe SAPISIDHASH proven live e2e** — `image t2i` [classic cohort, real 1376×768 JPEG] and `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 11.5 MB `ftyp` mp4] both succeeded end-to-end at the new 1920×1080 viewport with every selector resolving [no drift]; SAPISIDHASH digest verified byte-identical [FIPS-safe `usedforsecurity=False`], auth unchanged). Prior: [v0.36.0](LIVE_VERIFICATION_v0.36.0.md) (**#316 diagnostic tooling live-verified against real Flow traffic** — `GFLOW_CLI_HAR_PATH` captured a real 54-entry HAR [real Flow domains, 34× 200s, and a genuine 401 the tool exists to diagnose]; `GFLOW_CLI_DEBUG_TRACEBACK`'s typed-error scoping confirmed live [console output identical with/without the flag on a `GFlowError`]; unhandled-path behavior covered by 6 new tests (30 total across both files) + SDD task review; #312 reference-entity-smuggling fix covered by its own dedicated e2e test). Prior: [v0.35.0](LIVE_VERIFICATION_v0.35.0.md) (**#305-follow-up multimodal reverse-engineering & storyboard tool proven live e2e** — `gflow tools run storyboard` successfully deconstructed a cyberpunk scene into a cohesive 4-panel sequence; `reverse-engineer` tool extracts frames from video streams/URLs using `claude-video`'s `watch.py` and produces structured prompt components using Gemini multimodal models; dynamic token budgeting and strict Pyright types verified via test suite). Prior: [v0.34.0](LIVE_VERIFICATION_v0.34.0.md) (**#299 `--ui-mode` gate proven live, ZERO credits** — drove `get_ui_driver` directly over 4 real editor loads, never generated: bidirectional switch works [classic→agentic via `_force_agent_mode`, agentic→classic via `_exit_agent_mode`, each DOM-reverified], `agentic`-when-already-agentic is idempotent, and a timed-out toggle → **exit-28 fail-fast before submission**; deprecation behavior-change [`prefer_classic`→exit 28] confirmed). Prior: [v0.33.0](LIVE_VERIFICATION_v0.33.0.md) (**#287-follow-up picker fix proven live on the original repro** — the v0.32.1-failing `i2v <uuid> --project <crowded>` command now exits 0 with a real 3.0 MB `ftyp` mp4, `frame_ref_attached` + `video_saved`, zero uploads; **#241 jitter live-verified on both paths** — flag `--jitter 4-6` → `batch_jitter_sleep seconds=4.98`, and the new 0.5–1.5 s default → `seconds=1.47`, each firing exactly once between two t2i submissions; environment note: the denon82 cohort is now natively agentic and round-2 generations hit the pre-existing #281 `MediaAttributionError`, not a regression). Prior: [v0.32.1](LIVE_VERIFICATION_v0.32.1.md) (**#293 teardown fix live-verified credit-free** — error-path aborts leave ZERO chrome.exe holding the profile [3× leak reproduced pre-fix same day]; force-close fallback + ProfileLockedError translation unit-pinned; #283 wave logic fixes mock-verified to exact call counts). Prior: [v0.32.0](LIVE_VERIFICATION_v0.32.0.md) (**#287 UUID i2v frames proven live e2e** — an in-project asset selected by media UUID in the frame-slot dialog [frame_ref_attached, startImage bound on the wire, ZERO upload events] produced a real 720×1280 interpolation, resolving the #237 negative prior; foreign UUID → exit 9 pre-generation with screenshot; **#288 duration fail-fast proven live** — exit 23 pre-submit saved a 10-credit generation, and the debug screenshot confirmed the duration control is ABSENT from the cohort's settings popover [locale hypothesis refuted]; upload-400 exit-27 repro deferred-with-reason — the original rejected JPEG no longer exists). Prior: [v0.31.0](LIVE_VERIFICATION_v0.31.0.md) (**#281 wrong-media defenses live-verified in BOTH directions, credit-free** — correct attribution downloads with real wire metadata [seed, 768×1376]; the incident-class lazy-render ambiguity reproduced live and hard-stopped with `MediaAttributionError` exit 26 naming every candidate UUID, no file written; **#282 two-UUID-ref i2i proven e2e** — both freshly generated portrait UUIDs picker-selected into one scene with both canonical identities visually transferred). Prior: [v0.30.0](LIVE_VERIFICATION_v0.30.0.md) (**agentic-cohort image path + both fixes live-verified credit-free** — native 768×1376 stills, i2i-chain + canonical-ref identity hold; the character-create `DataIntegrityError` and the `prefer_classic` WARNING were observed live then fixed [recorder idempotent + INFO log]; MCP video-param feature deferred-with-reason on Veo credits, per the stills-only goal). Prior: [v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
+**What was actually live-verified for the latest release?** → latest: [LIVE_VERIFICATION_v0.45.0](LIVE_VERIFICATION_v0.45.0.md) (**#393 UUID `--ref` binding + #395 character-entity binding live-verified 2026-07-27/28** — a controlled A/B on identical input flipped `--ref` from exit 9 to exit 0 via the catalog-backed upload fallback, with the anti-silence guard [an unbindable ref aborts non-zero and writes no image] pinned by a live e2e; picker DOM + HAR showed Flow indexes a short auto-caption, NOT the prompt, so a prompt-derived search hint was dropped rather than shipped on assumption; a CDP spike against Flow's own character flow then captured the `entityContext` contract that gflow's generations were missing, root-causing #395 to two gflow defects [overlay dismissal Escaping Flow's own composer, and a character-route bounce that sent the prompt to the project composer] — both fixed, both character e2e tests now pass live, including `--format-prompt` [#383], with a read-back confirming the character carries its name and `thumbnail_media_id`). Prior: [v0.44.0](LIVE_VERIFICATION_v0.44.0.md) (**#381 dual-side project management & Playwright Chromium transport live-verified 2026-07-26** — real-editor project creation + rename tRPC server/DOM sync, prompt slugging, `gflow project` subcommand family, HTTP 429 adaptive backoff, and full E2E test suite). Prior: [v0.43.0](LIVE_VERIFICATION_v0.43.0.md) (**private incident diagnostics live-verified 2026-07-23, 1 Veo credit**). Prior: [v0.42.0](LIVE_VERIFICATION_v0.42.0.md) (**#361 production-readiness live-gaps confirmed live 2026-07-21, 1 Veo credit** — a real `veo-lite` t2v through the worker path persisted a real `remote_started` checkpoint [observer→checkpoint→DB chain confirmed], crash-recovery classified the task `indeterminate` without resubmitting, and mid-launch cancellation released the `ProfileLease` credit-free; full evidence in [v0.40.0-production-readiness § "2026-07-21 live follow-up"](LIVE_VERIFICATION_v0.40.0-production-readiness.md#2026-07-21-live-follow-up-0420-cycle); #359 content-safety `400`→`ContentPolicyError` classification is unit-covered, not live-triggered [would require a deliberate policy violation]; #360/#362 are docs-only, verified by the documentation gates). Prior: [v0.41.0](LIVE_VERIFICATION_v0.41.0.md) (**#357 production-readiness hardening — stale-session fail-fast, free image gen, paid veo-lite T2V all proven live**). Prior: [v0.40.0](LIVE_VERIFICATION_v0.40.0.md) (**#344 `@`-mention asset-tagging resolution proven live e2e, ~2 Imagen credits** — `gflow character create` staged a real taggable character [bound reference images, `has_reference_images` guard], the e2e test's documented propagation wait cleared Flow's `projectInitialData` lag, and `gflow image t2i "@Zoro …"` passed with returncode 0, a real generated image, and the correctly de-tagged prompt in the catalog — no code changes needed, `resolve_and_apply` as merged in #344 already works end-to-end; pre-existing unrelated issue #174 [Flow media-library A/B flake] can still intermittently block generation regardless of this feature — recorded, not omitted). Prior: [v0.39.0](LIVE_VERIFICATION_v0.39.0.md) (**#341 failed-generation persistence proven live** — a real `image t2i` on denon82 failed at the wire [`batchGenerateImages` HTTP 400 → `WireFormatError`] and the record-on-catch funnel wrote the **first-ever `failed` row** into the production catalog [`error_type=wire-format`, redacted `error_detail`, browsable via `gflow data list errors`], **$0**; the remaining paid paths [video/chain/batch/movie/worker] are funnel-regression-tested, not force-failed live [would cost credits], and the status-aware `succeeded=false` video-poll fix is unit-locked — recorded, not omitted). Prior: [v0.38.1](LIVE_VERIFICATION_v0.38.1.md) (**#338 agentic-pin recovery proven live ON the pinned account** — run 1 caught the composer-render race the unit suite could not [`ensure_media_incomplete` +115 ms, toggle never reached]; the readiness-wait fix landed and run 2 recovered classic on denon82 after ~2h of pin [`ui_driver.bound mode=classic`, real 768×1376 JPEG, exact prompt adherence]; reload branch unit-locked, live trigger not observed this cycle — recorded, not omitted). Prior: [v0.38.0](LIVE_VERIFICATION_v0.38.0.md) (**#332 mode control + #314 i2i ref dedup proven live e2e** — `image t2i --ui-mode classic` recovered agentic→classic in a real run [`ui_mode.attempt_exit_agent` → full classic chain, 1376×768 JPEG]; two identical `image i2i` runs proved the dedup contract [run 1: picker miss → `image_uploaded`; run 2: `reference_deduped_by_filename`, ZERO uploads]; `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 15.2 MB `ftyp` mp4]; autopilot #333 recorded deferred-with-reason [hermes-ops deployment staged separately]). Prior: [v0.37.0](LIVE_VERIFICATION_v0.37.0.md) (**viewport 1920×1080 + agentic count enforcement + FIPS-safe SAPISIDHASH proven live e2e** — `image t2i` [classic cohort, real 1376×768 JPEG] and `video t2v` veo-fast [`MEDIA_GENERATION_STATUS_SUCCESSFUL`, 11.5 MB `ftyp` mp4] both succeeded end-to-end at the new 1920×1080 viewport with every selector resolving [no drift]; SAPISIDHASH digest verified byte-identical [FIPS-safe `usedforsecurity=False`], auth unchanged). Prior: [v0.36.0](LIVE_VERIFICATION_v0.36.0.md) (**#316 diagnostic tooling live-verified against real Flow traffic** — `GFLOW_CLI_HAR_PATH` captured a real 54-entry HAR [real Flow domains, 34× 200s, and a genuine 401 the tool exists to diagnose]; `GFLOW_CLI_DEBUG_TRACEBACK`'s typed-error scoping confirmed live [console output identical with/without the flag on a `GFlowError`]; unhandled-path behavior covered by 6 new tests (30 total across both files) + SDD task review; #312 reference-entity-smuggling fix covered by its own dedicated e2e test). Prior: [v0.35.0](LIVE_VERIFICATION_v0.35.0.md) (**#305-follow-up multimodal reverse-engineering & storyboard tool proven live e2e** — `gflow tools run storyboard` successfully deconstructed a cyberpunk scene into a cohesive 4-panel sequence; `reverse-engineer` tool extracts frames from video streams/URLs using `claude-video`'s `watch.py` and produces structured prompt components using Gemini multimodal models; dynamic token budgeting and strict Pyright types verified via test suite). Prior: [v0.34.0](LIVE_VERIFICATION_v0.34.0.md) (**#299 `--ui-mode` gate proven live, ZERO credits** — drove `get_ui_driver` directly over 4 real editor loads, never generated: bidirectional switch works [classic→agentic via `_force_agent_mode`, agentic→classic via `_exit_agent_mode`, each DOM-reverified], `agentic`-when-already-agentic is idempotent, and a timed-out toggle → **exit-28 fail-fast before submission**; deprecation behavior-change [`prefer_classic`→exit 28] confirmed). Prior: [v0.33.0](LIVE_VERIFICATION_v0.33.0.md) (**#287-follow-up picker fix proven live on the original repro** — the v0.32.1-failing `i2v <uuid> --project <crowded>` command now exits 0 with a real 3.0 MB `ftyp` mp4, `frame_ref_attached` + `video_saved`, zero uploads; **#241 jitter live-verified on both paths** — flag `--jitter 4-6` → `batch_jitter_sleep seconds=4.98`, and the new 0.5–1.5 s default → `seconds=1.47`, each firing exactly once between two t2i submissions; environment note: the denon82 cohort is now natively agentic and round-2 generations hit the pre-existing #281 `MediaAttributionError`, not a regression). Prior: [v0.32.1](LIVE_VERIFICATION_v0.32.1.md) (**#293 teardown fix live-verified credit-free** — error-path aborts leave ZERO chrome.exe holding the profile [3× leak reproduced pre-fix same day]; force-close fallback + ProfileLockedError translation unit-pinned; #283 wave logic fixes mock-verified to exact call counts). Prior: [v0.32.0](LIVE_VERIFICATION_v0.32.0.md) (**#287 UUID i2v frames proven live e2e** — an in-project asset selected by media UUID in the frame-slot dialog [frame_ref_attached, startImage bound on the wire, ZERO upload events] produced a real 720×1280 interpolation, resolving the #237 negative prior; foreign UUID → exit 9 pre-generation with screenshot; **#288 duration fail-fast proven live** — exit 23 pre-submit saved a 10-credit generation, and the debug screenshot confirmed the duration control is ABSENT from the cohort's settings popover [locale hypothesis refuted]; upload-400 exit-27 repro deferred-with-reason — the original rejected JPEG no longer exists). Prior: [v0.31.0](LIVE_VERIFICATION_v0.31.0.md) (**#281 wrong-media defenses live-verified in BOTH directions, credit-free** — correct attribution downloads with real wire metadata [seed, 768×1376]; the incident-class lazy-render ambiguity reproduced live and hard-stopped with `MediaAttributionError` exit 26 naming every candidate UUID, no file written; **#282 two-UUID-ref i2i proven e2e** — both freshly generated portrait UUIDs picker-selected into one scene with both canonical identities visually transferred). Prior: [v0.30.0](LIVE_VERIFICATION_v0.30.0.md) (**agentic-cohort image path + both fixes live-verified credit-free** — native 768×1376 stills, i2i-chain + canonical-ref identity hold; the character-create `DataIntegrityError` and the `prefer_classic` WARNING were observed live then fixed [recorder idempotent + INFO log]; MCP video-param feature deferred-with-reason on Veo credits, per the stills-only goal). Prior: [v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
 **"Where is the reverse-engineered wire protocol for a feature?"** → the `*_RECON.md` design docs: [CHARACTER_RECON](CHARACTER_RECON.md) (Flow character entity protocol), [IMAGE_UPSCALE_RECON](IMAGE_UPSCALE_RECON.md) (`/v1/flow/upsampleImage` wire). Naming convention: one `<FEATURE>_RECON.md` per reverse-engineered surface, kept as the durable spec after the feature ships. Pre-capture research recons: [ASSET_TAGGING_RECON](ASSET_TAGGING_RECON.md) (`@`-mention asset tagging — shipped in v0.40.0, see [LIVE_VERIFICATION_v0.40.0](LIVE_VERIFICATION_v0.40.0.md)).
 **"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.45.0/docs/LIVE_VERIFICATION_v0.45.0.md

@@ -0,0 +1,138 @@
+# Live verification — v0.45.0
+
+> Evidence that v0.45.0's user-facing changes were exercised against **real**
+> Google Flow, not just mocked tests. Profile `ffroliva`, 2026-07-27.
+> See [E2E_TESTING.md](E2E_TESTING.md) for the marker/cost model.
+
+Offline gates for the release: `ruff` clean, `pyright src` 0 errors, full
+suite green (see §5).
+
+---
+
+## 1. `image i2i --ref <UUID>` reference binding (#393) — ✅ VERIFIED
+
+The field report claimed a UUID `--ref` was **silently** dropped and the
+generation "reported success" without the reference. Live investigation
+disproved the silence and found the real defect.
+
+### 1.1 What Flow actually does (measured, not assumed)
+
+| Probe | Observation |
+|---|---|
+| `--ref <uuid>` of a recent in-project asset | Tile found in the picker's first viewport → `image_ref_selected_existing`, exit 0 |
+| `--ref <uuid>` of an older in-project asset | Both UUID search tiers `found: false`; the **scroll fallback** located it → exit 0 |
+| `--ref <uuid>` that cannot exist | Search tiers miss → scroll misses → **exit 9**, `TransportTimeoutError`. **Not silent.** |
+| Picker DOM dump (`debug_picker_dom_*.json`) | Tiles carry `img src=…?name=<uuid>` **and** a short Flow-authored caption (`alt="Box tied with crimson ribbon"`) — **not** the generation prompt |
+| HAR capture of `batchGenerateImages` | Response confirms the caption source: `workflows[0].metadata.displayName = "Calm woman natural light portrait"` |
+
+Consequences for the fix: UUID-based tile matching is exact and stays; a
+**prompt-derived search hint cannot work** on this surface (tried live, returned
+zero tiles) and was therefore dropped from the change rather than shipped on the
+strength of a plausible-sounding assumption.
+
+### 1.2 Controlled A/B — identical input, fix toggled
+
+Ref `61a0423e-…` (owned by the profile, cataloged with a local file, living in a
+**different** project so its tile is unreachable from the target project's
+picker):
+
+| Build | Result |
+|---|---|
+| Pre-fix (fix stashed) | `existing_asset_not_found` → **exit 9**, `image_ref_upload_fallback` fired **0** times |
+| Post-fix | `existing_asset_not_found` → **`image_ref_upload_fallback`** → **exit 0**, 774 KB `.jpg` written |
+
+The 5 layers: file written (774 KB) · `.jpg` payload on disk · picker-miss and
+upload-fallback events in the structlog stream · non-zero → zero exit-code flip
+on identical input · the generated image is user-inspectable in the scratch
+project.
+
+### 1.3 Automated coverage
+
+- `tests/cli/test_cli_image_uuid_ref_enrichment.py` — 8 unit tests (catalog hit,
+  missing file, absent file record, unknown asset, catalog failure, mention
+  display-name preserved, single catalog open for 10 refs, no open for zero refs).
+- `tests/e2e/test_image_uuid_ref_e2e.py` — **2 live scenarios, both passing**:
+  - `test_e2e_unresolvable_uuid_ref_fails_loud` — the anti-silence guard: an
+    unbindable ref must abort non-zero and write no generated image (0 credits).
+  - `test_e2e_cross_project_uuid_ref_falls_back_to_upload` — seed image in
+    project A, referenced from a fresh project B, rescued by the upload fallback
+    (2 Imagen credits).
+
+---
+
+## 2. `character create` binding + `--format-prompt` (#395, #383) — ✅ VERIFIED
+
+Originally recorded here as *not verifiable this cycle*. That was wrong in an
+important way: the cause was **ours**, not Flow's, and the spike below found it.
+
+### 2.1 What the spike established
+
+Drove Flow's own character flow in a CDP-attached real Chrome
+(`gflow-agent-browser-spike`, `navigator.webdriver: false`) with full
+request/response capture, then diffed it against gflow's traffic. The two
+requests were byte-comparable except for one block:
+
+```jsonc
+"mediaGenerationContext": {
+  "entityContext": { "entityId": "…", "characterSlot": { "imageReferenceIndex": 0 } }
+}
+```
+
+With it, the response carries `parentEntityId` and the portrait binds; without
+it, Flow files a plain project image. Contract documented in
+[CHARACTER_RECON](CHARACTER_RECON.md#entity-binding-entitycontext-captured-live-2026-07-28).
+
+### 2.2 Two defects, both ours
+
+| # | Defect | Evidence |
+|---|---|---|
+| 1 | Overlay dismissal pressed **Escape** on Flow's own composer — `[role='dialog']`/`[role='alert']` matched the app itself — so the submit lost `entityContext` | Removing those two selectors made the identical command bind on the first try (`entity_patched`, real `thumbnail_media_id`); with them present it failed every run |
+| 2 | The character route can **bounce** back to the project page (entity not yet queryable after `createEntity`); the project page also mounts a prompt box, so the readiness gate passed on the wrong surface and the prompt went into the **project** composer | `character_editor_ready` logged with the *project* URL; the new guard logs `character_route_bounced` → `character_route_settled` and the URL is now the character route |
+
+A third symptom seen on 2026-07-27 — Flow's app crashing on that route — was
+real but intermittent and is now reported as the typed retryable `FlowAppError`
+(§3).
+
+### 2.3 Proof
+
+- `gflow character create --name "Overlay Hypothesis"` → `"status": "ok"`,
+  `character_create.entity_patched`; read-back shows the character with its name
+  **and** `thumbnail_media_id: fdaea0d2-…` — the first fully successful create
+  since the breakage.
+- `tests/e2e/test_character_create_e2e.py::test_character_create_binds_parent_entity`
+  — **passes live** (this is the #395 contract: entity bound, same project,
+  thumbnail attached).
+- `tests/e2e/test_character_create_e2e.py::test_character_create_format_prompt_clicks_format_button`
+  — **passes live**, asserting the `ui_automation.prompt_formatted` event fired
+  (visible **and** enabled button clicked) and that neither skip-telemetry event
+  appeared, so a no-op flag cannot pass as success. This closes the
+  `--format-prompt` (#383) verification that was owed since 2026-07-26.
+
+A harness bug was fixed on the way: `_character_env` inherited the isolated
+`GFLOW_CLI_HOME`, so every subprocess test in that file exited 2 with
+"No session" before reaching Flow.
+
+## 3. Error-classification fixes — ✅ VERIFIED (observed live, unit-pinned)
+
+| Change | Live basis |
+|---|---|
+| Flow app crash at the character-editor gate → typed retryable `FlowAppError` (exit 31) instead of a bare `RuntimeError` naming a selector | Incident `ui.json` `title.category: flow_app_crash` (§2.1) |
+| Character binding failure message now states the image was filed as a plain project image | HAR + read-back showing unbound "Untitled Character" entities (§2.1) |
+
+Unit coverage: `test_flow_app_crash_raises_typed_retryable_error`,
+`test_non_crash_still_raises_selector_runtime_error`, plus tightened assertions
+in `tests/api/test_client_generate_character.py` (the previous
+`assert … or exc_info.value.detail` was vacuous — always truthy).
+
+---
+
+## 4. Not exercised this cycle
+
+- **Veo/video paths** — no video generation was run; this release changes none.
+- **Top banner & modal dismissal (#369)** — exercised incidentally (overlay
+  detect/dismiss events fired during the image runs above) but not
+  purpose-tested against a real "What's new" banner, which cannot be summoned on
+  demand.
+- **Self-documenting error remediation (#380)** — the remediation hint was
+  observed on a real `TransportTimeoutError` payload during §1.1; the full
+  matrix of exception classes is unit-covered only.

{gflow_cli-0.44.0 → gflow_cli-0.45.0}/docs/MOVIE.md

@@ -231,12 +231,15 @@ For each scene, `gflow movie` merges global manifest cards with scene overrides
 |------|---------|--------|
 | `--profile <name>` | default profile | Chrome profile to drive (must be a `chrome`-strategy profile). |
 | `--out-dir <dir>` | manifest `output_dir` | Override the output directory. |
-| `--dry-run` | off | Print the plan + credit estimate; make **no** API calls. |
+| `--dry-run` | off | Print the pending video operation plan; make **no** API calls. |
 | `--fail-fast` / `--continue-on-error` | continue | Stop on the first scene failure, or attempt the rest (default). |
 | `--stitch` | off | After generating, hard-concat all clips into one preview mp4 (ffmpeg, no transitions). |
 
 ## Credits
 
 - Character creation (image generation) is **free** — no credits, no reCAPTCHA.
-- Each **scene** is one video generation = **1 credit**, spent at submit (step 2
-  above). A `--dry-run` shows the estimate without spending anything.
+- Each **scene** is one pending video generation operation, submitted at step 2
+  above. Current credit use varies by model, duration, account tier, and Flow
+  policy — check Google Flow before submitting. An accepted operation may
+  consume credits even if later polling or download fails. A `--dry-run` prints
+  the plan without submitting anything.

{gflow_cli-0.44.0 → gflow_cli-0.45.0}/docs/PROJECT_STATUS.md

@@ -4,9 +4,16 @@
 
 ## Current release
 
+**v0.45.0 — alpha.** **Reference + character binding fixes (#393/#395).** `gflow image i2i --ref <UUID>` now attaches the catalog's recorded file when Flow's per-project media picker cannot reach the tile, instead of failing the run — the fail-loud contract (never generate without a requested reference) is unchanged and pinned by a live e2e. `gflow character create` binds portraits to the character again: overlay dismissal was pressing Escape on Flow's own composer (`[role='dialog']`/`[role='alert']` matched the app itself), and the character route could bounce to the project page, sending the prompt to the **project** composer — both produced generations with no `entityContext`, which Flow filed as plain project images. Also: a Flow web-app crash on the character route is now the typed retryable `FlowAppError` (exit 31), character binding failures say what actually happened, and `--format-prompt` (#383) is live-verified. 2810 tests pass. See [LIVE_VERIFICATION_v0.45.0.md](LIVE_VERIFICATION_v0.45.0.md).
+
+**Develop (unreleased, post-v0.45.0):** *(empty — develop is the staging branch for the next release).*
+
+<details><summary>v0.44.0 — dual-side project naming &amp; management (#381)</summary>
+
 **v0.44.0 — alpha.** **Dual-side project naming & management (#381).** Feature set includes `gflow project` subcommand family (`list`, `show`, `rename`, `create`), `--project-name` / `--project-title` options across `gflow image` (`t2i`, `i2i`) and `gflow video` (`t2v`, `i2v`, `r2v`) generation commands, prompt slugging for scratch projects, dual-side title sync updating Google Flow's tRPC server/UI and local SQLite catalog in lockstep, HTTP 429 adaptive backoff / `RateLimitError` recovery (#384), character body prompt composer fixes (#378), and a repo-local Codex plugin (`$gflow:*` skills). Verified via full test suite and live Playwright Chromium E2E transport test. See [LIVE_VERIFICATION_v0.44.0.md](LIVE_VERIFICATION_v0.44.0.md).
 
-**Develop (unreleased, post-v0.44.0):** *(empty — develop is the staging branch for the next release).*
+</details>
+
 
 <details><summary>v0.42.0 — content-safety classification + Antigravity coding agent (#359/#360/#361)</summary>
 

{gflow_cli-0.44.0 → gflow_cli-0.45.0}/docs/USAGE.md

@@ -633,10 +633,13 @@ Link 0 is a text-to-video (T2V) generation; every later link is an
 image-to-video (I2V) generation **seeded by the extracted last frame of the
 previous clip**, giving visual continuity with no server-side stitching.
 
-> ⚠️ **Costs N credits — one per link.** A chain is N sequential paid Veo
-> generations. Run `--dry-run` first to print the plan and the credit estimate
-> without spending anything. The cost-confirmation prompt is shown unless you
-> pass `-y` / `--yes`.
+> ⚠️ **Each link is a pending video generation operation.** A chain submits N
+> sequential Veo generations that may consume credits; current cost varies by
+> model, duration, account tier, and Flow policy — check Google Flow before
+> submitting. An accepted operation may consume credits even if later polling
+> or download fails. Run `--dry-run` first to print the plan without
+> submitting anything. The confirmation prompt is shown unless you pass
+> `-y` / `--yes`.
 
 > **Requires the `chain` extra.** The last-frame extractor decodes the previous
 > clip with [PyAV](https://pyav.org/) (no system ffmpeg needed). Install it
@@ -708,13 +711,13 @@ concatenate them server-side.** Chain does not auto-concat: see the
 **Examples:**
 
 ```bash
-# Preview the plan + credit cost — spends nothing
+# Preview the pending video operation plan — submits nothing
 gflow video chain story.jsonl --dry-run
 
-# Generate the chain (one credit per link), no confirmation prompt
+# Generate the chain (one pending video operation per link), no confirmation prompt
 gflow video chain story.jsonl --model veo-fast --aspect 16:9 --yes
 
-# Resume a chain that died partway — already-paid links are skipped
+# Resume a chain that died partway — already-completed links are skipped
 gflow video chain story.jsonl --resume-from 1f2e3d4c-...
 
 # Seed 150 ms before EOF to dodge a fade-to-black final frame