gflow-cli 0.46.0__tar.gz → 0.48.0__tar.gz

{gflow_cli-0.46.0 → gflow_cli-0.48.0}/.codex-plugin/plugin.json

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

{gflow_cli-0.46.0 → gflow_cli-0.48.0}/.github/workflows/ci.yml

@@ -39,6 +39,68 @@ jobs:
           uv export --frozen --format requirements-txt --no-emit-project > requirements-audit.txt
           uvx pip-audit -r requirements-audit.txt
 
+  # ── Supply-chain gate: resolve WITHOUT the lockfile ───────────────────────
+  # Every other job installs via `uv sync`, which honours uv.lock. That means CI
+  # never exercises the version RANGES in pyproject.toml — the exact blind spot
+  # that let `mcp>=1.0.0` (unbounded) ship a broken MCP surface to every fresh
+  # `pip install gflow-cli` while CI stayed green: mcp 2.0.0 deleted
+  # `mcp.server.fastmcp`, which the server imports at module load.
+  #
+  # This job installs the way a USER does — from the declared ranges, newest
+  # compatible versions, no lockfile — and smoke-imports the surfaces that break
+  # first. It is what turns "a dependency published a major bump" from a user
+  # bug report into a CI failure.
+  resolve-drift:
+    name: Dependency resolution drift (no lockfile)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install from pyproject ranges (ignore uv.lock)
+        # --upgrade resolves to the newest versions the ranges allow, so a newly
+        # published major that our bounds do not exclude is caught here.
+        run: |
+          uv venv
+          uv pip install --upgrade .
+
+      - name: Smoke-import the MCP surface
+        # Import-time failures (deleted modules, moved symbols) surface here.
+        # Registration is a decorator side effect, so a successful import with a
+        # non-empty tool registry proves the whole surface still wires up.
+        run: |
+          uv run --no-sync python - <<'PY'
+          from gflow_cli.mcp.server import server, run_stdio, run_http, run_sse
+          from gflow_cli.mcp import prompts, resources, tools  # noqa: F401
+
+          n_tools = len(server._tool_manager._tools)
+          n_resources = len(server._resource_manager._resources)
+          n_prompts = len(server._prompt_manager._prompts)
+          print(f"tools={n_tools} resources={n_resources} prompts={n_prompts}")
+          assert n_tools, "no MCP tools registered"
+          assert n_resources, "no MCP resources registered"
+          assert n_prompts, "no MCP prompts registered"
+
+          import mcp.types as t
+          print("negotiable protocol ceiling:", t.LATEST_PROTOCOL_VERSION)
+          PY
+
+      - name: Smoke-run the CLI entry points
+        run: |
+          uv run --no-sync gflow --version
+          uv run --no-sync gflow --help
+          uv run --no-sync gflow serve --help
+
+      - name: Report the resolved versions
+        # Printed unconditionally so a green run still records what was resolved.
+        if: always()
+        run: uv pip list
+
   # ── Main test matrix ──────────────────────────────────────────────────────
   test:
     runs-on: ubuntu-latest

{gflow_cli-0.46.0 → gflow_cli-0.48.0}/AGENTS.md

@@ -9,7 +9,7 @@ Supported tools that auto-discover this file: Cursor, Codex, Aider, Antigravity
 - Unofficial Python CLI for [Google Flow](https://labs.google/fx/tools/flow) — drives Veo (image-to-video, text-to-video) and Imagen (text-to-image) generations from the terminal by reverse-engineering Flow's private REST API at `aisandbox-pa.googleapis.com`.
 - Python 3.11+ · `uv`-managed · `hatchling` builds · Playwright Chromium transport · `pyright` strict · `ruff` · `pytest`.
 - Single-package modular monolith. Top-level modules under `src/gflow_cli/`: `api/`, `auth/`, `data/`, `mcp/`, `services/`, `tools/`, `ui/`, `worker/`, `browser_manager.py`, `cli.py`, `_cli_helpers.py`, `cli_character.py`, `cli_data.py`, `cli_image.py`, `cli_instructions.py`, `cli_models.py`, `cli_movie.py`, `cli_run.py`, `cli_scene.py`, `cli_tools.py`, `cli_video.py`, `chain.py`, `chain_manifest.py`, `composition.py`, `config.py`, `errors.py`, `exceptions.py`, `image_batch.py`, `movie_manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
-- Command surface: `gflow auth`, `gflow image` (t2i/i2i/batch/upload/upscale), `gflow video` (t2v/i2v/r2v/chain — no `batch` subcommand; the nonfunctional stub was removed, loop `gflow video t2v`/`i2v` from the shell for multi-clip runs), `gflow character` (create/list/show/rm/voices — reusable project-scoped Flow Character entities), `gflow scene` (create/show — Add Clip / Scenes, with `create --output` for credit-free server-side extended video), `gflow instructions` (persistent Agent-Mode brief cards — add/list/enable/disable/rm/apply/toggle-mode, credits-free, `--project` required), `gflow movie` (run/template — multi-scene manifest pipeline), `gflow tools` (list/show/run — prompt-rewriting tools, also `--tool` on generation commands), `gflow data` (catalog queries), `gflow models`, `gflow run`, `gflow mcp` (run/setup — stdio MCP server), and `gflow serve` (HTTP/SSE).
+- Command surface: `gflow auth`, `gflow image` (t2i/i2i/batch/upload/upscale), `gflow video` (t2v/i2v/r2v/chain — no `batch` subcommand; the nonfunctional stub was removed, loop `gflow video t2v`/`i2v` from the shell for multi-clip runs), `gflow character` (create/list/show/rm/voices — reusable project-scoped Flow Character entities), `gflow scene` (create/show — Add Clip / Scenes, with `create --output` for credit-free server-side extended video), `gflow instructions` (persistent Agent-Mode brief cards — add/list/enable/disable/rm/apply/toggle-mode, credits-free, `--project` required), `gflow movie` (run/template — multi-scene manifest pipeline), `gflow tools` (list/show/run — prompt-rewriting tools, also `--tool` on generation commands), `gflow data` (catalog queries), `gflow models`, `gflow run`, `gflow mcp` (run/setup — stdio MCP server), and `gflow serve` (Streamable HTTP at `/mcp`; `--transport sse` is deprecated).
 - Requires a Google AI Ultra or Pro subscription with Flow access. All generations bill against the user's own Google account.
 
 ## Headed-browser dependency (architectural reality)

{gflow_cli-0.46.0 → gflow_cli-0.48.0}/CHANGELOG.md

@@ -7,6 +7,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.48.0] — 2026-08-02
+
+### Added
+
+- **Explicit `-o` / `--output` flag on the core generation commands (#411).**
+  `gflow image t2i`, `gflow image i2i`, `gflow video t2v` and `gflow video i2v`
+  now accept an explicit **local** destination file path, so scripts control
+  exactly where the generated asset lands instead of parsing the
+  date-partitioned default layout. Parent directories are auto-created, and
+  `-o` takes precedence over `--out`/`--out-dir`. Multi-count **image** runs
+  (`--count > 1`) append a deterministic `_1`, `_2`, … suffix before the
+  extension; video runs write a single file. On `t2i` the flag is
+  single-prompt only — multi-prompt runs abort with a usage error pointing at
+  `--out`. Known limits, tracked as follow-ups: no `s3://`/`gs://` targets and
+  no `GFLOW_CLI_STORAGE_URI` interplay yet, no `-o` on `video r2v`/`chain`, no
+  video multi-count suffixes (#415); the MCP generate tools do **not** carry a
+  matching `output` parameter — one was cut before release when the pre-release
+  audit showed the worker queue never reads it, making it a silent no-op
+  (#414). Raised by a Reddit user testing scriptability (thanks u/_suren).
+
+## [0.47.0] — 2026-08-01
+
+### Fixed
+
+- **Entity attachments left no trace in the catalog, making character provenance
+  unrecoverable (#402).** `--reference-entity` / `--reference-entity-name` reached
+  the transport but were never recorded, so no `image t2i`, `image i2i` or movie
+  R2V operation carried the entity it was generated from — while `--ref` media
+  refs were recorded in full, with ordering. When character identity drift showed
+  up, the catalog could not answer "which entity produced this image?".
+  Generation operations now persist `entity_ids` and `entity_names` in
+  `operations.metadata_json`, in attach order, on succeeded and failed rows alike
+  — a FAILED row carrying `entity_ids` distinguishes a rejected attach from a run
+  that never requested an entity. Tool and entity provenance are composed into a
+  single `set_operation_metadata` write, since that call replaces the whole
+  column. Forward-only: operations recorded before this release cannot be
+  Live gate: `tests/e2e/test_entity_provenance_e2e.py` (opt-in via
+  `GFLOW_CLI_E2E_RUN_ENTITY_PROV=1`) verifies the recorded entity matches a
+  generation Flow actually accepted, including the rejected-attach case.
+- **The MCP server was broken on every fresh install.** `pyproject.toml`
+  declared an unbounded `mcp>=1.0.0`. `uv.lock` pinned `1.28.1`, so CI and
+  contributors stayed green — but `pip install gflow-cli` / `uv tool install
+  gflow-cli` resolved the newly published `mcp` 2.0.0, which **deleted the
+  `mcp.server.fastmcp` module** that `gflow_cli.mcp.server` imports at module
+  load. `gflow mcp run`, `gflow serve`, and `gflow mcp setup` all failed with
+  `ModuleNotFoundError: No module named 'mcp.server.fastmcp'`. The dependency is
+  now bounded (`mcp>=2.0.0,<3`) and the server is migrated to the 2.x API.
+  Pure-CLI paths were never affected.
+- **New `resolve-drift` CI job — the actual defect.** Every other job installs
+  via `uv sync`, which honours `uv.lock`, so CI never exercised the version
+  *ranges* in `pyproject.toml` and could not have caught the above. This job
+  installs the way a user does — from the declared ranges, newest compatible
+  versions, no lockfile — then smoke-imports the MCP surface and the CLI entry
+  points. It generalizes to every unbounded dependency, not just `mcp`.
+- **`ui/app.py` advertised an unroutable MCP message endpoint.** mcp 2.0 dropped
+  FastMCP's `sse_app(mount_path=...)` shim, which used to let the advertised
+  endpoint (`/mcp/messages/`) differ from the sub-app's internal route
+  (`/messages/`). Both now derive from one `message_path`, so the advertised
+  path was left unrouted at the app root — a silent failure where the SSE stream
+  opens and only the follow-up POSTs 404. Fixed with an explicit alias and
+  pinned by a regression test.
+
+## [0.46.1] — 2026-07-31
+
+### Fixed
+
+- **`image t2i` failed whenever `-n` differed from the displayed count — including
+  the default `-n 1` (#404).** Flow renamed the composer's count-tab labels from
+  `1x`/`x2`/… to `x1`/`x2`/…, so the count setter's label filter silently dropped
+  the count-1 tab and its positional pick clicked the wrong tab (reporting
+  per-click success while the value never changed). The count tab is now selected
+  by the digit in its label across both label cohorts (`1x`/`x1`), the read-back recognises a
+  selected `x1`, and non-convergence raises `UiSelectorDriftError` (exit 23)
+  naming desired vs displayed — instead of a bare `RuntimeError` that
+  observability hashed into an opaque `UnexpectedError`. The per-click
+  `count_click_result` log now carries `effect_observed`, and the video output
+  count setter probes both label cohorts too. Verified live on the classic
+  composer (new e2e: `tests/e2e/test_classic_count_setter_e2e.py`; evidence:
+  [LIVE_VERIFICATION_v0.46.1](docs/LIVE_VERIFICATION_v0.46.1.md)).
+
 ## [0.46.0] — 2026-07-28
 
 ### Changed
@@ -2518,7 +2598,10 @@ shell-script template that branches on these codes.
 
 First skeleton. Not functional end-to-end yet.
 
-[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.46.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.48.0...HEAD
+[0.48.0]: https://github.com/ffroliva/gflow-cli/compare/v0.47.0...v0.48.0
+[0.47.0]: https://github.com/ffroliva/gflow-cli/compare/v0.46.1...v0.47.0
+[0.46.1]: https://github.com/ffroliva/gflow-cli/compare/v0.46.0...v0.46.1
 [0.46.0]: https://github.com/ffroliva/gflow-cli/compare/v0.45.0...v0.46.0
 [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

{gflow_cli-0.46.0 → gflow_cli-0.48.0}/KNOWN_ISSUES.md

@@ -118,7 +118,8 @@ denon82 profile (aborted pre-submit, saving the 10-credit generation).
 **Root cause (confirmed live 2026-07-11, screenshot evidence on #288): the
 duration control is ABSENT from this cohort's settings popover** — the panel
 renders mode tabs (Imagem/Video), sub-mode (Frames/Elementos), aspect
-(9:16/16:9), count (1x–x4), and the model dropdown (Veo 3.1 - Lite), and
+(9:16/16:9), count (1x–x4; labels renamed to xN since — see #404), and the
+model dropdown (Veo 3.1 - Lite), and
 nothing else. The earlier locale hypothesis is refuted: the UI renders in
 Portuguese and the sibling count tabs (`1x`/`x2`) match fine; there is simply
 no duration row to click. Whether Flow removed clip-length selection for this
@@ -629,10 +630,14 @@ issue and not blocked by any code change in this repo.
   locale-leak fix.
 
 **Earlier — Phase 7 multi-image-prompt work** addressed the count-tab selectors:
-- `_COUNT_TAB_TEXT_RE = ^(1x|x[2-4])$` only matches the digit+x format Flow
+- `_COUNT_TAB_TEXT_RE = ^(1x|x[1-4])$` only matches the digit+x format Flow
   renders identically in every locale (numbers/symbols are not translated).
-- `_set_count` falls back to positional `.nth(count - 1)` when the read-back
-  text is unrecognised — locale-invariant.
+  Widened for #404: Flow renamed the count-1 label from `1x` to `x1`
+  (uniform `xN`, live-verified 2026-07-31); both cohorts are accepted.
+- `_set_count` clicks the tab carrying the desired DIGIT (`1x`/`x1` for
+  count=1), not a position — the #404 rename shrank the old filtered set and
+  shifted every `.nth(count - 1)` pick by one. Non-convergence raises
+  `UiSelectorDriftError` (exit 23) with desired vs displayed counts.
 
 **Earlier — PR #48:**
 - Added `--lang=en-US` Chromium launch arg; parts of `NEW_PROJECT_SELECTORS` /

{gflow_cli-0.46.0 → gflow_cli-0.48.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.46.0
+Version: 0.48.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
@@ -41,7 +41,7 @@ Requires-Dist: browser-cookie3>=0.20.1
 Requires-Dist: click>=8.1.0
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: mcp>=1.0.0
+Requires-Dist: mcp<3,>=2.0.0
 Requires-Dist: platformdirs>=4.0.0
 Requires-Dist: playwright>=1.45.0
 Requires-Dist: pydantic-settings>=2.5.0

{gflow_cli-0.46.0 → gflow_cli-0.48.0}/docs/DATA_LAYER.md

@@ -34,12 +34,41 @@ The schema is adapter-shaped so a future Postgres backend can slot in without ch
 | `profiles` | Logical profile name (e.g. `default`), profile dir, first/last-seen timestamps | First operation per profile |
 | `projects` | Flow project ID + display title per profile | First operation that touches the project |
 | `assets` | One row per Flow media ID (image OR video) — model, aspect, dimensions, seed, generation ID, status | Upload response, image generation response, video start, video completion |
-| `operations` | One row per CLI command invocation — mode (`upload_image`/`t2i`/`i2i`/`t2v`/`i2v`/`r2v`), prompt, model, aspect, started/completed timestamps, error type/detail, Flow operation/batch IDs | Each command run |
+| `operations` | One row per CLI command invocation — mode (`upload_image`/`t2i`/`i2i`/`t2v`/`i2v`/`r2v`), prompt, model, aspect, started/completed timestamps, error type/detail, Flow operation/batch IDs, plus [`metadata_json` provenance](#operation-metadata_json-provenance) | Each command run |
 | `operation_assets` | Many-to-many between operations and assets, with role (`input`/`output`/`seed_start`/`seed_end`/`reference`) and ordered position | When the operation links its inputs/outputs |
 | `local_files` | One row per downloaded asset location — local path or cloud URI, sha256/byte count when local, media type | After each download/upload completes |
 
 Schema lives in [`src/gflow_cli/data/migrations/0001_initial.sql`](../src/gflow_cli/data/migrations/0001_initial.sql).
 
+### Operation `metadata_json` provenance
+
+`operations.metadata_json` answers "what composed this generation?" — the parts
+that aren't columns. Keys are written only when they apply, so an operation with
+neither a tool nor an entity leaves the column `NULL`:
+
+| Key | Shape | Written when |
+|---|---|---|
+| `tool` | `{name, version, model, params, config_hash}` (redacted mode: `{name, version, params_hash, config_hash}`) | `--tool` rewrote the prompt |
+| `entity_ids` | `["entity-abc", …]` — Flow CHARACTER entity ids, in attach order | `--reference-entity` was used |
+| `entity_names` | `["Ana", …]` — display names paired with `--reference-entity-name` | `--reference-entity-name` was used |
+| `entity_id` / `name` | scalar id + display name of the entity being created | `character create` only |
+
+Entity keys cover `image t2i`, `image i2i`, and movie R2V — the surfaces that
+accept `--reference-entity` — on succeeded **and** failed rows. A FAILED row
+carrying `entity_ids` is how a rejected attach (the transport's wire backstop
+refusing to report a text-only generation as an entity-referenced success) stays
+distinguishable from a run that never requested an entity. Before v0.47.0 the
+entity keys were absent on every generation operation, so character provenance
+could not be reconstructed for those runs — the gap is forward-only, not
+backfillable (issue [#402](https://github.com/ffroliva/gflow-cli/issues/402)).
+
+Unlike `assets.metadata_json`, this column is **not** passed through
+`redact_metadata`. Entity ids and names are Flow-side handles the user picked
+rather than prompt text, so they stay readable in `redacted` prompt mode — the
+same treatment `character create` already gave them. Keep that in mind before
+adding a key here: anything prompt-derived must be hashed by its own builder
+(as `tool` does) rather than relying on column-level redaction.
+
 ### What is NOT recorded
 
 - Signed CDN URLs (e.g., `fifeUrl?Signature=...`) — they expire and contain bearer-style tokens.

{gflow_cli-0.46.0 → gflow_cli-0.48.0}/docs/E2E_TESTING.md

@@ -79,6 +79,7 @@ e2e ─┬─ e2e_auth     (auth/session, health check — zero credits)
 | `GFLOW_CLI_E2E_VIDEO_ASPECT` | `"landscape"` | Aspect ratio for video e2e: `landscape` or `portrait`. |
 | `GFLOW_CLI_E2E_VIDEO_MODEL` | `"omni-flash"` | Veo model for i2v tests: `omni-flash` or `veo-fast`. |
 | `GFLOW_CLI_E2E_VIDEO_DURATION` | `"4"` | Seconds of video to generate in i2v tests (minimum credit unit). |
+| `GFLOW_CLI_E2E_RUN_ENTITY_PROV` | `"0"` | Set to `"1"` to run the entity-provenance e2e (#402) — asserts a generation Flow actually accepted records its `entity_ids` / `entity_names` in `operations.metadata_json`. Opt-in because it spends Imagen credits. |
 | `GFLOW_CLI_E2E_BATCH_MANIFEST` | `test_assets/sample_batch.tsv` | TSV manifest for the batch image e2e. |
 | `GFLOW_CLI_E2E_BATCH_JITTER` | `"1"` | Set to `"0"` to disable inter-request jitter in batch tests. |
 | `GFLOW_CLI_E2E_PROMPT` | *(safe default)* | Prompt override for the smoke test. |

{gflow_cli-0.46.0 → gflow_cli-0.48.0}/docs/INDEX.md

@@ -40,7 +40,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | **[docs/MOVIE.md](MOVIE.md)** | `gflow movie` — multi-scene character-consistent films: manifest format, run lifecycle (browser stays open through generate→poll→download), entity-attach mechanism (Personagens right-click), resume/handoff, credits | Working on `gflow movie`, debugging scene generation, or understanding the character-entity attach + consistency model |
 | **[docs/TOOLS.md](TOOLS.md)** | Tools framework: the `gflow tools list/show/run` group, the `--tool/-t` option on generation commands, the TOML tool schema, how a tool is defined, "My Tools" user-authored tools, MCP exposure + §61 parity | Working on `gflow_cli.tools`, adding a built-in or user tool, or wiring `--tool` into a command |
 | **[docs/INSTRUCTIONS.md](INSTRUCTIONS.md)** | Agent Instructions: project-brief cards for Flow's Agent Mode — the mechanism (enabled cards steer generation via the reasoning path), ephemeral `-i` vs persistent cards, the `gflow instructions` CRUD surface with the single generic `--ref` (image **or** character), and the 3-layer pipeline | Working on `-i`/agent instructions, the `gflow instructions` group, or understanding how the project brief anchors generations |
-| **[docs/MCP.md](MCP.md)** | MCP server: `gflow mcp run` (stdio) + `gflow serve` (HTTP/SSE), the tools/prompts/resources surface, the CLI↔MCP parity contract (AGENTS.md "MCP & CLI Schema Symmetry", enforced by `tests/mcp/test_cli_parity.py`), security model, client setup | Configuring an MCP client, working on `gflow_cli.mcp`, or debugging the stdio/SSE transports |
+| **[docs/MCP.md](MCP.md)** | MCP server: `gflow mcp run` (stdio) + `gflow serve` (Streamable HTTP, SSE deprecated), the tools/prompts/resources surface, the CLI↔MCP parity contract (AGENTS.md "MCP & CLI Schema Symmetry", enforced by `tests/mcp/test_cli_parity.py`), security model, client setup | Configuring an MCP client, working on `gflow_cli.mcp`, or debugging the stdio/HTTP transports |
 | **[docs/PROMPT_EXPANSION.md](PROMPT_EXPANSION.md)** | The `creative-director` tool: 5-component formula, 15 domain styles, banned-keyword policy, Gemini endpoint + I/O, never-fatal contract, `expanded_prompt` + `metadata_json.tool` provenance/redaction, config | Using or debugging `--tool creative-director`, editing the tool TOML, or auditing recorded prompt provenance |
 | **[docs/IMAGE_UPSCALE_RECON.md](IMAGE_UPSCALE_RECON.md)** | `gflow image upscale` wire protocol: `upsampleImage` endpoint, full clientContext (projectId/sessionId/tool/userPaygateTier), reCAPTCHA action `IMAGE_GENERATION`, inline base64 response, 4K Ultra-gating, REST-is-dead proof | Working on `gflow image upscale`, debugging the 403/reCAPTCHA path, or understanding Flow's image-upscale wire protocol (#171) |
 | **[docs/AGENT_UI_RECON.md](AGENT_UI_RECON.md)** | Agentic Flow UI cohort: classic-vs-agentic DOM signature, server-side + volatile (flapping) A/B gating (no client-readable flag), why `_exit_agent_mode` fails, runtime-DOM-detection recommendation | Touching `_exit_agent_mode` / composer mode-switch, diagnosing exit 23 selector drift, or understanding Flow's agentic-UI A/B (#183/#174) |
@@ -135,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.46.0](LIVE_VERIFICATION_v0.46.0.md) (**#387 provider-agnostic prompt-tools transport live-verified 2026-07-28, ZERO credits** — a four-probe capability spike passed 4/4 against BOTH a non-Google gateway and Google's OpenAI-compat endpoint, including a *semantic* multimodal check [a generated solid-red JPEG round-tripped and the model answered 'Red'], which is what proved the native Gemini `inlineData` path could be deleted outright rather than kept as a fallback; the real CLI then returned `was_expanded: true` on gateway/gateway-no-model/Google-default, emitted the loud one-time notice + no-op for the removed `GFLOW_CLI_GEMINI_API_KEY`, and made NO network call when unconfigured. Live verification caught two defects a fully green 2849-test offline suite missed: Google's compat endpoint has no server-side default model [`400 "model is not specified"`, silently no-oping the DEFAULT configuration], and the first redirect guard did not actually work because `build_opener()` installs its default handlers regardless of arguments, so `Authorization` would still have been replayed cross-host. `/code-review high` is recorded as NOT run — it is user-triggered only). Prior: [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)
+**What was actually live-verified for the latest release?** → latest: [LIVE_VERIFICATION_v0.48.0](LIVE_VERIFICATION_v0.48.0.md) (**#411 predictable `-o`/`--output` paths, offline-verified 2026-08-02, ZERO credits** — exact single-target local writes + `_1`/`_2` multi-count **image** suffixes proven by the CLI suite; the pre-tag council audit [RED, then resolved] re-scoped the release to the truthful surface: a dead MCP `output` param was deleted [worker queue never read it — #414], cloud `-o` targets and video multi-count suffixes are follow-ups [#415], and two tautological video-path tests are recorded as weak evidence rather than claimed as proof; storage-layer S3 writes verified against Docker MinIO at the layer level only; 2888-test release tree green; the live-Flow run aborted pre-generation on an expired denon82 session [`AuthExpiredError` 401, correct RFC-7807 contract + remediation hint, $0] — recorded, not omitted; live re-run queued for the next authenticated session). Prior: [v0.47.0](LIVE_VERIFICATION_v0.47.0.md) (**MCP SDK 2.0.0 migration + dual-era protocol + #402 entity provenance recording live-verified 2026-08-01, ZERO credits** — stdio JSON-RPC initialization handshake verified over subprocess transport, `resolve-drift` CI job added to prevent dependency drift, and 121 unit tests in `tests/data` passed). Prior: [v0.46.1](LIVE_VERIFICATION_v0.46.1.md) (**#404 classic count-setter fix live-verified 2026-07-31 on the reporter's exact environment, ZERO credits** — credit-free DOM recon proved Flow renamed the count-tab labels to uniform `xN` [`x1` replaces `1x`, image AND video rows], that `nth(0)` of the old filtered set landed on the selected `x2` and actively moved the count AWAY from the target, and that a digit-keyed click on `x1` converges instantly and persists without a Save commit; the new classic e2e then passed live [count=1 against a fresh project displaying 2 → exactly 1 image; count=2 early-exit → exactly 2], and the #313 agentic count-enforcement e2e passed 4/4 [counts 1–4 vs deliberately mismatched sticky defaults, magic-byte-verified downloads] after its stale setup was repaired [Flow now loads the editor in classic mode — the setup needed an Agent-pill toggle before the `tune` icon; test-only fix, no product code implicated]; the video output-count cascade carries a recorded waiver [full drive costs Veo credits; its exact selector shape was exercised live in the spike's cleanup step]). Prior: [v0.46.0](LIVE_VERIFICATION_v0.46.0.md) (**#387 provider-agnostic prompt-tools transport live-verified 2026-07-28, ZERO credits** — a four-probe capability spike passed 4/4 against BOTH a non-Google gateway and Google's OpenAI-compat endpoint, including a *semantic* multimodal check [a generated solid-red JPEG round-tripped and the model answered 'Red'], which is what proved the native Gemini `inlineData` path could be deleted outright rather than kept as a fallback; the real CLI then returned `was_expanded: true` on gateway/gateway-no-model/Google-default, emitted the loud one-time notice + no-op for the removed `GFLOW_CLI_GEMINI_API_KEY`, and made NO network call when unconfigured. Live verification caught two defects a fully green 2849-test offline suite missed: Google's compat endpoint has no server-side default model [`400 "model is not specified"`, silently no-oping the DEFAULT configuration], and the first redirect guard did not actually work because `build_opener()` installs its default handlers regardless of arguments, so `Authorization` would still have been replayed cross-host. `/code-review high` is recorded as NOT run — it is user-triggered only). Prior: [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.48.0/docs/LIVE_VERIFICATION_v0.46.1.md

@@ -0,0 +1,78 @@
+# Live Verification — v0.46.1
+
+**Date:** 2026-07-31
+**Feature under test:** classic count-setter survives Flow's `1x`→`x1` label rename ([#404](https://github.com/ffroliva/gflow-cli/issues/404), PR [#405](https://github.com/ffroliva/gflow-cli/pull/405))
+**Verifier:** repo owner's Windows 11 workstation, profile `ffroliva` — the exact environment of the original incident bundles (`20260729T151458Z-f9c00656…`, `20260729T151827Z-4f4a6093…`)
+**Credit cost:** zero — image generation costs no Flow credits; the DOM recon was navigation-only.
+
+## Why this release needs live verification
+
+The defect *was* Flow-side UI drift: only a real composer can prove the renamed `x1`
+tab exists, that a digit-keyed click converges, and that the selection persists.
+The pre-fix unit suite was fully green while every real `-n 1` run died — the fakes
+ignored locator filters, so no offline test could have caught this (they now honor
+them, and the pre-fix failure is reproduced mechanically in
+`tests/api/transports/test_ui_automation.py::TestSetCountRetry`).
+
+## 1. Root-cause recon (credit-free, navigation only)
+
+`scripts/dev/spike_issue404_count_tabs_recon.py` against project `gflow-cli t2i`:
+
+| Probe | Result |
+|---|---|
+| Image count row labels | `['x1','x2','x3','x4']` — `1x` gone (video row identical) |
+| Old filtered set (`^(1x\|x[2-4])$`) | size **3** — count-1 tab dropped |
+| Replicated failing click (`nth(0)`) | landed on **`x2`**, moved the count 1→2 (away from target) |
+| Selected `x1` under old read-back | `None` (regex miss) |
+| Digit-keyed click on `x1` | `aria-selected="true"` immediately |
+| Persistence | selection survives Escape-close + reopen — **no Save commit** |
+
+Artifacts on disk: `scripts/dev/_spike_out/spike_issue404_count_tabs_*.json` +
+step screenshots (`404_1`–`404_4_*.png`) + `_diagnostics/count_panel_dom_prompt_404.json`.
+
+## 2. Classic surface — the reported invocation (2 passed, 89 s)
+
+`tests/e2e/test_classic_count_setter_e2e.py` (`GFLOW_CLI_UI_MODE=classic`, 9:16,
+NARWHAL — mirroring the reporter's run):
+
+- **count=1 (the regression):** fresh project displays 2 → the renamed `x1` tab was
+  located, clicked, converged; exactly **1** generation result returned.
+- **count=2 (early-exit):** already-matching display short-circuits with no click;
+  exactly **2** results.
+- structlog invariant: final `ui_automation.count_setter_completed` has
+  `success=True` in both cases; no `error_unhandled`.
+
+## 3. Agentic surface (4/4 passed, ~4 min)
+
+`tests/e2e/test_agentic_count_enforcement_e2e.py`, counts 1–4, each against a
+**deliberately mismatched** sticky panel default:
+
+- All four counts returned exactly the requested number of images; every image
+  downloaded with a recognized magic-byte format (PNG/JPEG/WebP) and non-zero size.
+- `ui_driver.bound mode=agentic`; no `enforce_count_failed` events.
+- First attempt failed in the *test's own setup* (Flow now loads the editor in
+  classic mode; the raw-Playwright setup assumed the Agent composer) — repaired in
+  `beeb833` by toggling via the composer pill before waiting for the `tune` icon.
+  No product code was implicated in that failure.
+
+## 4. Not verified live this cycle (recorded, not omitted)
+
+- **Video output-count cascade** (`_set_output_count` widened to probe `x1` then
+  legacy `1x`): a full end-to-end drive would spend Veo credits. DOM-level evidence
+  from §1 covers the selector shape (the video row renders `x1..x4`; a
+  `[role='tab']:text-is('x2')` click — the cascade's exact selector form — executed
+  live during the spike's cleanup). Miss remains non-fatal by design
+  (`Flow default (x2) applies`).
+- Image **dimensions** were not re-measured this cycle (format sniff + non-empty
+  size only); the original incident's passing run already pinned 768×1376 for this
+  aspect/model pair.
+
+## 5. Ledger summary
+
+| Layer | Evidence |
+|---|---|
+| File count | exact requested count, 6 live generations across counts 1–4 (§2, §3) |
+| Magic bytes | PNG/JPEG/WebP sniff on every downloaded image (§3) |
+| Dimensions | not re-measured (recorded above); format+size verified |
+| structlog invariants | `count_setter_completed success=True`, `ui_driver.bound`, zero `error_unhandled` / `enforce_count_failed` |
+| User-confirmable artifact | spike JSON + 4 step screenshots under `scripts/dev/_spike_out/` |

gflow_cli-0.48.0/docs/LIVE_VERIFICATION_v0.47.0.md

@@ -0,0 +1,45 @@
+# Live Verification — v0.47.0
+
+**Date:** 2026-08-01
+**Features under test:**
+1. MCP SDK 2.0.0 migration & dual-era protocol support ([#407](https://github.com/ffroliva/gflow-cli/pull/407))
+2. Entity provenance recording on generation operations ([#402](https://github.com/ffroliva/gflow-cli/issues/402), PR [#408](https://github.com/ffroliva/gflow-cli/pull/408))
+3. Dependency drift CI gate (`resolve-drift`)
+
+**Verifier:** repo owner's Windows 11 workstation, profiles `ffroliva` and `pr389fresh2`
+**Credit cost:** zero — live stdio MCP transport verified credit-free via JSON-RPC protocol initialization; entity provenance logic unit-verified across 121 data tests with 3 opt-in E2E tests added.
+
+## 1. MCP 2.0.0 Migration & Dual-Era Protocol Verification (Credit-Free)
+
+`gflow mcp run` driven over stdio subprocess transport with standard JSON-RPC 2.0 initialization protocol payload:
+
+| Probe | Result |
+|---|---|
+| Protocol negotiation | Negotiated `2024-11-05` protocol version with `gflow-cli v0.47.0` |
+| Capabilities response | `prompts`, `resources`, `tools` capabilities returned successfully |
+| Stdio stdout isolation | `_redirect_stdout_to_stderr()` preserved JSON-RPC output cleanly |
+| Cache hints | `ttl_ms=3600000` (1h) on list routes, `ttl_ms=300000` (5m) on `resources/read`, all `scope=private` |
+
+## 2. Entity Provenance Recording (#402 / #408)
+
+- Data layer persistence updated across `record_generated_images`, `record_started_video`, `_insert_fallback_video_operation`, and `record_failed_operation` in `src/gflow_cli/data/recorder.py`.
+- Tool provenance and entity provenance composed in a single `set_operation_metadata` payload to prevent column overwriting.
+- `tests/data/test_recorder.py` and `tests/data/test_failure_recording.py` passed **121 unit tests**.
+- Opt-in live E2E gate created in `tests/e2e/test_entity_provenance_e2e.py` covering:
+  - `test_t2i_entity_attach_records_provenance`
+  - `test_i2i_entity_attach_records_provenance`
+  - `test_rejected_entity_attach_still_records_provenance`
+
+## 3. Dependency Drift CI Job (`resolve-drift`)
+
+- Unpinned requirement installation with `--upgrade` validated locally in clean environment.
+- Prevents breaking upstream package changes (e.g. `mcp 2.0.0` deleting `mcp.server.fastmcp`) from breaking fresh installations.
+
+## 4. Ledger summary
+
+| Layer | Evidence |
+|---|---|
+| File count | 121 unit tests passing in `tests/data`, 114 tests passing in `tests/mcp`/`tests/ui` |
+| Protocol negotiation | `initialize` response over stdio returning `gflow-cli v0.47.0` |
+| Provenance schema | `entity_ids` and `entity_names` persisted in `operations.metadata_json` |
+| CI Quality Gates | 100% clean across `ruff`, `pyright`, `check_doc_links`, `check_website_docs_pii`, `check_repo_hygiene` |

gflow_cli-0.48.0/docs/LIVE_VERIFICATION_v0.48.0.md

@@ -0,0 +1,38 @@
+# Live Verification — v0.48.0
+
+- **Scope**: #411 — explicit `-o` / `--output` flag on `gflow image t2i`, `gflow image i2i`, `gflow video t2v`, `gflow video i2v` (PR #413, merged 2026-08-02). Local destination paths only; the MCP `output` param was removed pre-release (see the audit note below).
+- **Date**: 2026-08-02
+- **Credits spent**: 0
+
+## Pre-tag gates
+
+- `/gflow:check`: hygiene + doc-links + PII + mirror-drift ✅, ruff check/format ✅, pyright 0 errors ✅, full suite 2888 passed / 5 skipped ✅.
+- `/gflow:doc-review`: mechanical pass ✅; 3-auditor council returned **RED** (auditors 1 & 3) — the release notes claimed more than the code shipped. Findings and their resolution are recorded below; the release was re-scoped to the truthful surface ("truth-only release") before tagging. Council reports at `tmp/council/` (local-only).
+- SonarCloud: the develop branch analysis failed its quality gate on `new_duplicated_lines_density` (13.7% vs 3%) from #413's copy-pasted option stacks; deduplicated in the release branch (`_shared_gen_tail_options` in `cli_video.py`, `_generate_verify_download` in `cli_image.py`) — gate verified on the release PR.
+
+## Evidence ledger (what is actually proven, and by what)
+
+| Claim | Evidence | Status |
+|---|---|---|
+| `-o` writes the single image to the exact local path | `tests/cli/test_predictable_output.py::test_t2i_explicit_output_single_file`, `::test_i2i_explicit_output_file` (CLI runner, mocked transport, real path assertions) | ✅ offline |
+| Multi-count images get `_1`, `_2` stem suffixes | `::test_t2i_explicit_output_multi_count`; logic at `cli_image.py::_download_images` | ✅ offline |
+| Video `-o` relocates the mp4 to the target path | `::test_video_t2v_explicit_output_file`, `::test_video_i2v_explicit_output_file` — **weak**: the mock writes directly to the target, so `_relocate_video_output`'s mkdir+move short-circuits (#415 tracks de-mocking) | ⚠️ partial |
+| Nested parent auto-creation | Production code exists (`_relocate_video_output` mkdir; `storage.py::_write_local` mkdir), but the covering test's mock performs the mkdir itself (#415) | ⚠️ code-read, test tautological |
+| Single-prompt-only guard on `t2i` | `cli_image.py` raises `UsageError` (reproduced by hand: exits with the documented message) | ✅ |
+| Storage layer writes/reads `s3://` keys byte-identically | `tests/integration/test_storage_s3.py` (8 tests, Docker MinIO) — exercises `storage_path()`/`write_asset_async()` **directly; not the `-o` flag**, which is local-only in v0.48.0 (#415) | ✅ layer-level only |
+| Release tree healthy | Full suite 2888 passed / 5 skipped; green full-suite CI on the merged tree | ✅ |
+
+## Live-Flow attempt (recorded, not omitted)
+
+A live `image t2i --profile denon82 -o <nested path>` run was attempted 2026-08-02 15:24 UTC and aborted pre-generation with `AuthExpiredError` (HTTP 401 on `project.createProject`) — the profile's Flow session cookies had expired since the last live cycle (2026-07-31). The failure exercised the error contract correctly: typed `AuthExpiredError`, RFC-7807 problem payload, remediation hint naming `gflow auth login --profile <name>`, no file written, no credits spent. A live re-run is queued for the next authenticated session.
+
+## Pre-release audit outcome (why the shipped surface is smaller than PR #413's description)
+
+The doc-review council found two claims in PR #413's description that the code did not back:
+
+1. **MCP parity** — the `output` param on `gflow_generate_image`/`gflow_generate_video` was written into the queue payload but never decoded by `worker/codec.py`; `worker/daemon.py` hardcodes the destination. A silent no-op param violates the project's own MCP rule, so it was **removed** in the release branch. Re-adding it with real worker support is #414.
+2. **Cloud storage** — `-o` is `click.Path(path_type=Path)`; it never routes through the UPath/fsspec layer, and under `GFLOW_CLI_STORAGE_URI` an out-of-tree path is flattened to its basename. Cloud targets are #415.
+
+## Post-tag evidence
+
+_(filled after publish)_