gflow-cli 0.68.0__tar.gz → 0.69.0__tar.gz

{gflow_cli-0.68.0 → gflow_cli-0.69.0}/.codex-plugin/plugin.json

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

{gflow_cli-0.68.0 → gflow_cli-0.69.0}/.env.template

@@ -183,7 +183,8 @@
 # GFLOW_CLI_UI_MODE=auto
 
 # Which Flow frontend gflow drives (#639). auto (default): flow.google.com is the
-# default host for what it can serve today (video t2v with --project) on every
+# default host for what it can serve today (video t2v, and video i2v from a local
+# --initial-frame, with --project) on every
 # account; requests it cannot serve yet keep the labs driver on an unmoved
 # account, and a moved account gets the migrated composer for everything ported.
 # flow.google.com: force the migrated composer for everything.

{gflow_cli-0.68.0 → gflow_cli-0.69.0}/.github/PULL_REQUEST_TEMPLATE.md

@@ -12,6 +12,7 @@
 - [ ] `scenario` + `plan` written under `docs/superpowers/plans/<date>-<slug>/` and linked here
 - [ ] `check` green, including the step 1b CLI↔MCP mirror sweep
 - [ ] MCP twin added, or a reasoned exemption in `tests/mcp/test_cli_parity.py`
+- [ ] **E2E evidence provided** — name the `tests/e2e/` test you ran and paste its result, or point at the new test this PR adds. If you could not run it, say why here:
 - [ ] Live-verified against real Flow where a generation path changed; what could NOT be verified is stated below
 - [ ] Council review run (`pr-council-review` / `branch-review`) and must-fix items addressed
 

{gflow_cli-0.68.0 → gflow_cli-0.69.0}/AGENTS.md

@@ -41,10 +41,10 @@ by construction, so Codex / Cursor / Aider / `agy` read exactly what Claude Code
 
 ## Project at a glance
 
-- 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` — and, for accounts Google has moved to `flow.google.com`, that frontend's `batchexecute` wire (text-to-video today; `GFLOW_CLI_FLOW_HOST`).
+- 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` — and, for accounts Google has moved to `flow.google.com`, that frontend's `batchexecute` wire (text-to-video, and image-to-video from a local `--initial-frame`, today; `GFLOW_CLI_FLOW_HOST`).
 - 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`, `diagnostics.py`, `json_output.py`, `media.py`, `profile_lease.py`, `redaction.py`, `storage.py`, `winsec.py`, `cli_project.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`, `cli_doctor.py`, `cli_update.py`, `composition.py`, `config.py`, `errors.py`, `file_integrity.py`, `flow_selectors/`, `update_check.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/extend — `extend` continues an existing clip past Flow's 8s ceiling, server-seeded from the source so the join is continuous; 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 doctor` (read-only pre-flight diagnostic, exit 33 = findings present), `gflow update` (self-update through the installer that put it here — uv tool / pipx / pip; `--check` only reports; source installs refused, exit 11; deliberately no MCP twin), `gflow project`, `gflow models`, `gflow run`, `gflow mcp` (run/setup — stdio MCP server), and `gflow serve` (Streamable HTTP at `/mcp`; `--transport sse` is deprecated).
+- 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`, `diagnostics.py`, `json_output.py`, `media.py`, `profile_lease.py`, `redaction.py`, `storage.py`, `winsec.py`, `cli_project.py`, `cli_character.py`, `cli_credits.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`, `cli_doctor.py`, `cli_update.py`, `composition.py`, `config.py`, `errors.py`, `file_integrity.py`, `flow_selectors/`, `update_check.py`, `exceptions.py`, `image_batch.py`, `movie_manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
+- Command surface: `gflow auth`, `gflow credits` (user/list — read-only Veo balance), `gflow image` (t2i/i2i/batch/upload/upscale), `gflow video` (t2v/i2v/r2v/chain/extend — `extend` continues an existing clip past Flow's 8s ceiling, server-seeded from the source so the join is continuous; 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 doctor` (read-only pre-flight diagnostic, exit 33 = findings present), `gflow update` (self-update through the installer that put it here — uv tool / pipx / pip; `--check` only reports; source installs refused, exit 11; deliberately no MCP twin), `gflow project`, `gflow models`, `gflow run`, `gflow mcp` (run/setup — stdio MCP server), and `gflow serve` (Streamable HTTP at `/mcp`; `--transport sse` is deprecated).
 - Works with any Google account that has Flow access. All generations bill against the user's own Google account.
 
 ## Headed-browser dependency (architectural reality)
@@ -95,8 +95,10 @@ the five other mirror axes), which no command here can check and no CI gate can
 - Use `pytest -m "not live and not e2e and not smoke"` locally; full suite OOMs on small dev machines. Scope to changed dirs; trust CI for the full sweep.
 - TDD is non-negotiable. Coverage floor: 80% overall.
 - Documentation is a first-class deliverable. Every behavior, workflow, config, or operator-facing change must update the relevant docs or state why no docs changed in the PR/checklist. `scripts/ci/check_doc_links.py` is a merge gate.
-- **A PR is not done until its SonarCloud gate is green (zero new issues).** The six gates above are local/pre-commit; SonarCloud is server-side and runs in CI (`sonar.qualitygate.wait=true` → a red gate turns the `SonarCloud analysis` check red). Before calling a PR merge-ready, verify it with `/gflow:sonar <N>` (it is skipped on fork PRs — maintainer-checked there).
-- Live tests (`@pytest.mark.live`) opt in via `GFLOW_LIVE=1`. E2E tests require `GFLOW_CLI_E2E_PROFILE`.
+- **A PR is not done until its SonarCloud gate is green (zero new issues).** The nine gates above are local/pre-commit; SonarCloud is server-side and runs in CI (`sonar.qualitygate.wait=true` → a red gate turns the `SonarCloud analysis` check red). Before calling a PR merge-ready, verify it with `/gflow:sonar <N>` (it is skipped on fork PRs — maintainer-checked there).
+- **E2E is the decisive layer, and it is required for every behavior change that touches a Flow surface.** Run the `tests/e2e/` test that covers the change, or write one — offline-green proves only that *our* code does what we think, never that Flow still behaves as captured. `/gflow:live-verify` does **not** satisfy this: it drives CLI commands by hand into a gitignored note and never runs `pytest -m e2e`. The two are complementary — an e2e test is a re-runnable regression, a live-verify ledger is a narrative record. If you cannot run it, say so explicitly in the PR and a maintainer will; a change touching no Flow surface (docs, help text, exit-code plumbing) is out of scope — say that rather than leaving it blank.
+- E2E tests require `GFLOW_CLI_E2E_PROFILE` and `-m e2e` (excluded from the default `addopts`, so they never run by accident). Cost sub-markers: `e2e_auth` (zero credits, browser only), `e2e_image` (zero credits, daily cap), `e2e_scene`, `e2e_data`, `e2e_batch`, `e2e_character` (opt in with `GFLOW_CLI_E2E_RUN_CHARACTER=1`), `e2e_video` (spends Veo credits — opt in with `GFLOW_CLI_E2E_RUN_VIDEO=1`). Redact account identifiers and any token or cookie value before pasting output into a PR.
+- Live tests (`@pytest.mark.live`) opt in via `GFLOW_LIVE=1`.
 
 ## Code style
 
@@ -159,7 +161,7 @@ All AI agents and harnesses working on `gflow-cli` follow this standard 10-phase
 | 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` |
+| 8. E2E + Live Verification | `pytest -m e2e` → `/gflow:live-verify` | The e2e suite against a live profile, then the 5-layer proof against real Flow transport | Pasted e2e result + `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. **Internally gates on `/gflow:changelog` → `/gflow:check` → `/gflow:live-verify` → `/gflow:doc-review`; a failure at any of them is a STOP, not a warning.** | Shipped release & back-merge |
 
@@ -174,9 +176,9 @@ Every AI agent executing any phase of this pipeline MUST proactively state the c
 | Phase 3: BDD Scaffolding | `Scenario:` blocks & test scaffold | ➔ Phase 4: Implementation Plan (`/gflow:plan <feature>`) |
 | Phase 4: Implementation Plan | `PLAN.md` created & approved | ➔ Phase 6: Task Execution (`/gflow:status`) |
 | Phase 6: Task Execution | All plan tasks checked | ➔ Phase 7: Pre-Commit Quality (`/gflow:check`) |
-| Phase 7: Pre-Commit Quality | All 7 quality gates green | ➔ Phase 5: Council Review (`/gflow:branch-review` or `/gflow:pr-council-review`) |
-| Phase 5: Council Review | Consensus 🟢 GREEN | ➔ Phase 8: Live Verification (`/gflow:live-verify`) or Phase 9 (`/gflow:issue-resolve <N>`) |
-| Phase 8: Live Verification | `LIVE_VERIFICATION_vX.Y.Z.md` | ➔ Phase 9: Issue Resolve & PR (`/gflow:issue-resolve <N>`) |
+| Phase 7: Pre-Commit Quality | All quality gates green | ➔ Phase 5: Council Review (`/gflow:branch-review` or `/gflow:pr-council-review`) |
+| Phase 5: Council Review | Consensus 🟢 GREEN | ➔ Phase 8: E2E + Live Verification (`pytest -m e2e`, then `/gflow:live-verify`) or Phase 9 (`/gflow:issue-resolve <N>`) |
+| Phase 8: E2E + Live Verification | e2e result + `LIVE_VERIFICATION_vX.Y.Z.md` | ➔ Phase 9: Issue Resolve & PR (`/gflow:issue-resolve <N>`) |
 | Phase 9: Issue Resolve & PR | PR open & SonarCloud 0-issue gate green | ➔ Phase 10: Release Pipeline (`/gflow:release`) |
 | Phase 10: Release Pipeline | Signed tag & PyPI published | ➔ Done (Release shipped & back-merged) |
 
@@ -198,6 +200,7 @@ The `skills/` directory ships installable agent skill docs in plain Markdown wit
 | `check` | [`skills/check/SKILL.md`](skills/check/SKILL.md) | Quality gates (lint/format/types/tests) before every commit |
 | `changelog` | [`skills/changelog/SKILL.md`](skills/changelog/SKILL.md) | Unreleased changes + last tagged version |
 | `known-issues` | [`skills/known-issues/SKILL.md`](skills/known-issues/SKILL.md) | Open/mitigated known issues — before auth/reCAPTCHA work |
+| `video-production` | [`skills/video-production/SKILL.md`](skills/video-production/SKILL.md) | User wants a finished multi-shot or dialogue video (consistent actors, room, several angles, spoken lines), or clips came back with a film border, a drifting room, rushed dialogue, a person-policy refusal or exit 36 |
 | `sonar` | [`skills/sonar/SKILL.md`](skills/sonar/SKILL.md) | Drive the SonarCloud quality gate to zero for a PR/branch |
 | `live-verify` | [`skills/live-verify/SKILL.md`](skills/live-verify/SKILL.md) | Pre-flight state check at start of work; live-verification against real Flow before claiming done |
 | `doc-review` | [`skills/doc-review/SKILL.md`](skills/doc-review/SKILL.md) | Council-driven documentation audit before a release |
@@ -226,7 +229,7 @@ extension does not currently load plugins, so IDE-only users should include the
 **Claude Code:** the `/gflow:` slash commands in `.claude/commands/gflow/` are auto-discovered when the project is open — no extra setup needed. To register a skill globally, copy the command file to `~/.claude/commands/`.
 **Custom agents:** fetch `skills/gflow-cli/SKILL.md` into your knowledge base before answering gflow questions.
 
-The SkillOpt harness at `scripts/dev/skillopt/` measures how accurately each skill guides an agent, and supports multiple providers (Anthropic, OpenAI-compat, Gemini, local models). See [`scripts/dev/skillopt/README.md`](scripts/dev/skillopt/README.md).
+The SkillOpt harness at `scripts/dev/skillopt/` measures how accurately each skill guides an agent. It drives any OpenAI-compatible endpoint — OpenAI, a gateway (OpenRouter, LiteLLM, freellmapi), a local model, or Google's compat endpoint — through the project's own `GFLOW_CLI_LLM_*` settings, the same ones the prompt tools use; there is no separate provider configuration. See [`scripts/dev/skillopt/README.md`](scripts/dev/skillopt/README.md).
 
 ## Where to look next
 

{gflow_cli-0.68.0 → gflow_cli-0.69.0}/CHANGELOG.md

@@ -7,6 +7,138 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.69.0] — 2026-09-06
+
+### Added
+
+- **Read-only Flow balance inspection:** `gflow credits user`, `gflow credits list`, and the
+  matching `gflow_get_credits` MCP tool report current
+  balances and account tiers from saved profiles. Multi-profile inspection preserves partial
+  successes and emits stable JSON for automation. Saved cookies + ordinary HTTP are the primary
+  path, with browser-backed retrieval only as a fallback; cookies remain scoped to `labs.google`,
+  and no copied bearer token or browser API key is stored. The reported balance funds Veo video;
+  image generation uses separate per-model daily quotas.
+
+- **Image-to-video from a local start frame on the migrated `flow.google.com` host**
+  ([#639](https://github.com/ffroliva/gflow-cli/issues/639), slice 1). `gflow video i2v
+  --initial-frame <local file> --project <id>` now runs on the new host — on a moved
+  account, and by default (`GFLOW_CLI_FLOW_HOST=auto`) on an unmoved one too. The port
+  is UI-driven and observed, never replayed: the composer selects the Frames submode,
+  uploads the file through the editor's own toolbar Upload entry and reads the media id
+  off the app's `maseQ` reply, finds the upload in the Start-frame picker under its file
+  name (the picker exposes no media id in its DOM), and only then submits. **An unbound
+  chip is refused before the click** — exit 23, zero credits — because an empty Frames
+  submit silently goes out as text-to-video (the labs #125 shape). The app's submit
+  *request* is then inspected as it leaves: a body without that media id, or carrying a
+  `_t2v_` model key, fails the run with `WireFormatError` (exit 7) naming what Flow was
+  actually asked to make — after the fact, since the request is already on the wire.
+  An upload Flow refuses is exit 27 on route `batchexecute:maseQ`; a file the picker
+  never lists after three searches is exit 32. For i2v the submit rpc is `eb1hJf` (t2v
+  stays `YhhmEf`), and an i2v request with no `--model` binds the veo-lite default here
+  exactly as it has always done on labs (#125). Not ported in this slice and named in
+  the exit-36 detail: `--end-frame`, a frame given by media UUID or `@Name`, and r2v.
+  A "Get started" modal over a fresh migrated editor is now dismissed before the run.
+  Recon: `docs/superpowers/spikes/2026-09-05-migrated-frames-attach.md`.
+
+- **`--model veo-lite-lp` is drivable on the migrated `flow.google.com` host.** It was
+  the one tier the migrated model map omitted, so an account Google has already moved
+  could not select it at all: `_select_model` refused with `ConfigurationError` (exit
+  11, "not available on the migrated Flow host") before ever reading the live menu.
+  The omission was not an oversight — the tier's full menu label is unknown, because
+  Flow has never rendered the entry on any account gflow has driven (the 2026-08-14
+  two-account capability matrix, #650's duration capture and v0.61.0's refusal A/B all
+  recorded a picker MISS), and the migrated map is keyed by label. It is now matched
+  the way the labs driver has matched it since #539 — by the `[Lower Priority]` tag
+  alone. **The entry has now been captured** (2026-09-05, a migrated account): the menu
+  renders `Veo 3.1 - Lite [Lower Priority]`, and that account's picker was already
+  *defaulted* to it — presumably why every earlier capture missed the entry, having been
+  taken on accounts Flow was not throttling. Matching stays on the tag rather than the
+  newly-known label: one account's rendering, and a tag Flow appends to whichever tier it
+  throttles survives that tier changing. Verified live at $0 by driving `_select_model`
+  for all five tiers and reading the picker back after each switch — including the
+  lower-priority tier reached through the menu — plus one real 8 s generation on it.
+  Routing is deliberately unchanged: `veo-lite-lp` still does not make
+  `migrated_can_serve` pull an **unmoved** account onto the new host, since Flow appears
+  not to offer the tier to accounts it is not throttling.
+  Capture: `docs/superpowers/spikes/2026-09-05-migrated-model-menu-lower-priority.md`.
+
+### Changed
+
+- **`video-production` skill, epoch 1: the reference cap now routes instead of only
+  forbidding.** A scored rollout picked `veo-quality` for a two-reference shot while
+  correctly reciting that its reference cap is 0 — the skill stated the prohibition in two
+  places and named the substitute in none, and the remedy lived only in the reference files
+  an agent may never load. Step 4 now carries the rule: the reference count picks the model
+  before quality does, `omni-flash` for a single generation needing references and quality
+  together, a `veo-lite` variant when 3 refs is enough — and `video chain` is called out as
+  the exception, since it refuses `omni-flash` outright. Validated by a controlled A/B on
+  one model with the document as the only variable: 0.00 → 0.90.
+
+- **The SkillOpt harness uses the project's own `GFLOW_CLI_LLM_*` settings.** It carried a
+  second, parallel provider configuration — its own `--provider anthropic|openai` switch,
+  its own key env vars and its own `--base-url` — while `Settings.llm_base_url` /
+  `llm_api_key` / `llm_model` already drove the prompt tools. Any OpenAI-compatible endpoint
+  works through the one setting (OpenAI, OpenRouter, LiteLLM, freellmapi, a local gateway,
+  Google's compat endpoint); both LLM SDK dependencies are gone, and the harness now
+  inherits the URL validation its own flag used to bypass. It requires `uv run`. A scoring
+  bug is fixed with it: float accumulation made `1.0 - 0.3 + 0.1` fall short of the `>= 0.8`
+  PASS threshold, so a task at exactly the threshold graded PARTIAL while printing "0.80".
+
+### Fixed
+
+- **Moved accounts: `image t2i` / `i2i` (and `upscale`, `extend`) now exit 36, not a
+  bare `RecaptchaError` exit 1 (#673).** The labs client mints the reCAPTCHA token on
+  the pool's bootstrap page *before* the UI transport runs, so none of the transport's
+  migration guards could fire; on a moved account that page is the `flow.google.com`
+  project grid after the client-side handoff, which loads no
+  `recaptcha/enterprise.js`, so site-key discovery raised `RecaptchaError` — a
+  `RuntimeError` unmapped in `EXIT_CODE_MAP`: exit 1 "unexpected", with a remediation
+  about headless Chrome. `_mint_recaptcha_token` now runs the same one-line
+  `raise_if_migrated` guard the transport uses, so the distinct, non-retryable exit
+  36 and its migration remediation come back within seconds, before any submit.
+  Reproduced and re-verified on a moved maintainer account at zero credits (exit 1 →
+  exit 36); the new
+  `tests/e2e/test_migrated_host_e2e.py::test_e2e_image_on_a_moved_account_exits_36_not_recaptcha`
+  (`e2e_auth`, $0) is the regression.
+
+- **The migrated model picker could bind a tier the user did not ask for.** The port
+  matched menu entries by case-insensitive *substring* and took `.first`, so on an
+  account whose menu carries a lower-priority sibling, `--model veo-lite` also matched
+  `Veo 3.1 - Lite [Lower Priority]` and Flow billed whichever Angular happened to list
+  first. The same substring ran against the picker button's read-back, where a pane
+  already showing the lower-priority tier satisfied `startswith("Veo 3.1 - Lite")` and
+  returned "already selected" without opening the menu — silently keeping the wrong
+  tier. This is the ambiguity #539 fixed on labs.google (whose selectors carry
+  `:not(:has-text('[Lower Priority]'))`) and which this port had dropped. Ordinary
+  tiers now exclude the tag on both paths, and a matcher hitting more than one live
+  entry **refuses** (exit 11) naming every candidate rather than guessing which one
+  Flow would bill. Confirmed against the real button text on a throttled account:
+  `"Veo 3.1 - Lite [Lower Priority] arrow_drop_down".lower().startswith("veo 3.1 - lite")`
+  is `True`, so pre-fix `--model veo-lite` there generated on the throttled tier without
+  ever opening the menu.
+
+- **Switching `--model` on the migrated host broke the next run** — reported as "run 1
+  with a new model dies, run 2 with the same model works, run 3 with another model dies
+  again". Picking from the model menu leaves Angular with **two** stacked overlays (the
+  settings pane and the menu opened over it) and each Escape dismisses exactly one, so
+  `_close_pane`'s single press closed only the menu and left the settings pane covering
+  the composer. `send_prompt`'s click then failed actionability and surfaced ~5 s later
+  as a bare `TimeoutError` naming `[contenteditable='true']`, pointing nowhere near the
+  pane. A repeat run binds the model at the button read-back, never opens the menu and
+  never stacks the second overlay — which is exactly why re-running the same model
+  worked. Measured at $0: after a switch the composer's bounding box is *identical* for
+  12 s (it was never unstable) while `.cdk-overlay-pane:visible` stays at 1; one more
+  Escape takes it to 0. `_close_pane` now escapes until no overlay is visible, bounded,
+  and raises pre-submit if one will not close rather than leaving the composer click to
+  report it. The old read-back did fire `migrated.pane_still_open` — as a warning the run
+  ignored; the observation was there and only the consequence was missing.
+
+- **A migrated run that short-circuited model selection logged nothing.** `_select_model`
+  returning at its button read-back emitted no event, so a field timeline could not tell
+  "bound the tier you asked for" from "never touched the picker" — answering that for the
+  2026-09-05 run took a separate probe. It now logs `migrated.model_already_selected`
+  with the observed button text.
+
 ## [0.68.0] — 2026-09-05
 
 ### Added
@@ -3934,7 +4066,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.68.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.69.0...HEAD
+[0.69.0]: https://github.com/ffroliva/gflow-cli/compare/v0.68.0...v0.69.0
 [0.68.0]: https://github.com/ffroliva/gflow-cli/compare/v0.67.0...v0.68.0
 [0.67.0]: https://github.com/ffroliva/gflow-cli/compare/v0.66.3...v0.67.0
 [0.66.3]: https://github.com/ffroliva/gflow-cli/compare/v0.66.2...v0.66.3

{gflow_cli-0.68.0 → gflow_cli-0.69.0}/CONTRIBUTING.md

@@ -24,12 +24,13 @@ What a contributor PR is expected to have gone through, phase by phase:
 | Transport / auth / selector / schema change | [`predict`](skills/predict/SKILL.md) | A GO / CAUTION / STOP verdict **before** code exists; STOP means open an issue instead |
 | Any feature | [`scenario`](skills/scenario/SKILL.md) → [`plan`](skills/plan/SKILL.md) | `docs/superpowers/plans/<date>-<slug>/SCENARIO.md` + `PLAN.md` — the edge-case table and the task list; link them from the PR (they live on the branch and in the PR's history; at release the durable facts are folded into `docs/superpowers/memory/` and the plan dir is removed) |
 | Every commit | [`check`](skills/check/SKILL.md) | The Impeccable Routine green (it is the exact CI gate), plus the **step 1b** CLI↔MCP mirror sweep no CI gate can see |
-| Anything on a generation path | [`live-verify`](skills/live-verify/SKILL.md) | Evidence against real Flow, not just green offline tests — this project drives a black box; say plainly what you could **not** verify |
+| Any behavior change | [`tests/e2e/`](tests/e2e/) | The e2e test you ran, or the new one you wrote. E2E is the layer that proves the change works against real Flow — unit + integration + BDD green is never the whole story here. Name the test and paste its result |
+| Anything on a generation path | [`live-verify`](skills/live-verify/SKILL.md) | Evidence against real Flow **on top of** the e2e run — the 5-layer ledger; say plainly what you could **not** verify |
 | Opening the PR | [`pr-council-review`](skills/pr-council-review/SKILL.md) / [`branch-review`](.claude/commands/gflow/branch-review.md) | The multi-dimension council (correctness, quality, security, tests, memory, YAGNI, parity …); maintainers run it on every PR, so running it yourself first removes a round trip |
 | Red SonarCloud check | [`sonar`](skills/sonar/SKILL.md) | Zero new issues — the gate measures *new* code |
 | Auth or reCAPTCHA | [`known-issues`](skills/known-issues/SKILL.md) | Known-broken surfaces have documented workarounds; rediscovering them costs days |
 
-Three rules the pipeline enforces that catch first-time contributors most often:
+Four rules the pipeline enforces that catch first-time contributors most often:
 
 1. **Ship each capability twice, or say why not.** Every CLI command has an MCP twin or a
    reasoned exemption in `tests/mcp/test_cli_parity.py` — and options, payload keys and tool
@@ -38,6 +39,14 @@ Three rules the pipeline enforces that catch first-time contributors most often:
    (AGENTS.md § *Locale-Invariance Discipline*).
 3. **Verified beats claimed.** If a fix cannot be verified on the affected surface in your
    environment, the PR says so and uses `Refs #N`, not a green checkbox.
+4. **E2E is the evidence layer.** A behavior change **that touches a Flow surface** needs an
+   e2e test — the one you ran, or the one you wrote. `tests/e2e/` already covers auth,
+   session, image, video, scene, data and batch; if nothing there represents your use case,
+   add a test that does. Read-only and inspection paths belong under `e2e_auth` and cost zero
+   credits, so "it's expensive" is almost never the reason. If you cannot run it, say why in
+   the PR and a maintainer will — a silently unticked box is what stalls a review. Changes
+   that touch no Flow surface at all (docs, help text, exit-code plumbing) are out of scope;
+   say that instead of leaving it blank.
 
 The PR template's *Lifecycle* checklist mirrors this table. Tick what applies, strike what
 does not, and say why — a reviewer can then start from your evidence instead of re-deriving it.
@@ -103,7 +112,22 @@ async def test_full_t2i_roundtrip(): ...
 async def test_full_i2v_roundtrip(): ...
 ```
 
-CI runs `unit` + `integration` on every push. `e2e` tests require a live authenticated profile and are opt-in:
+**E2E is required, not optional.** CI cannot run these — they need a live authenticated
+profile — so the e2e layer is the one gate that only a human, or an agent with credentials,
+can close. That makes it the contributor's job, not the maintainer's. A PR that changes
+behavior **on a Flow surface** must either:
+
+- **run an existing test** that already covers the use case — browse `tests/e2e/` — and
+  paste the result (redact account identifiers, emails and any token or cookie value); or
+- **add a new one** when nothing covers it, marked `e2e` plus the cost sub-marker that fits.
+
+Pick the cost sub-marker honestly — most inspection and auth paths are `e2e_auth` and spend
+zero credits. Use the `e2e_profile_dir` / `e2e_env` fixtures in `tests/e2e/conftest.py`.
+If you genuinely cannot run e2e (no Flow account, no credits for a video path), say so
+explicitly in the PR and a maintainer will run it — but do not leave the box silently unticked.
+
+CI runs `unit` + `integration` on every push. `e2e` tests require a live authenticated profile
+and are excluded from the default run — select them with `-m e2e`:
 
 ```bash
 export GFLOW_CLI_E2E_PROFILE=<profile-name>   # name of a logged-in profile

{gflow_cli-0.68.0 → gflow_cli-0.69.0}/KNOWN_ISSUES.md

@@ -14,11 +14,12 @@ Living list of behaviour that's broken, surprising, or limited by design — alo
 
 ## Open
 
-### Flow is migrating to `flow.google.com`; gflow drives the migrated frontend for t2v (rest of the matrix pending)
+### Flow is migrating to `flow.google.com`; gflow drives the migrated frontend for t2v and i2v from a local start frame (rest of the matrix pending)
 
-- **Status:** Open (partially resolved) · **Severity:** High for everything except text-to-video · **Affected:** on accounts the rollout has reached, `gflow video t2v` now runs on the migrated host (with `--project`); `image`, i2v/r2v, characters, scenes, extend, instructions and tools are not ported yet and still exit 36
+- **Status:** Open (partially resolved) · **Severity:** High for everything except text-to-video and local-file image-to-video · **Affected:** on accounts the rollout has reached, `gflow video t2v` and `gflow video i2v --initial-frame <local file>` now run on the migrated host (with `--project`); an end frame, a frame by UUID or `@Name`, `image`, r2v, characters, scenes, extend, instructions and tools are not ported yet and still exit 36
 - **Tracked:** [#639](https://github.com/ffroliva/gflow-cli/issues/639) · Reported 2026-09-02 against 0.59.0, 0.62.1, 0.63.0 and 0.65.0
 - **Confirmed live 2026-09-03 on a second, independent account** (`ffroliva`) — see [LIVE_VERIFICATION_v0.66.0](docs/LIVE_VERIFICATION_v0.66.0.md). A read-only probe of the migrated origin measured `i_total: 0`, reproducing the reporter's central measurement.
+- **Image commands on a moved account** ([#673](https://github.com/ffroliva/gflow-cli/issues/673), fixed in the unreleased line, post-v0.68.0): through v0.68.0 `image t2i` / `i2i` (and `upscale`, `extend`) died with exit 1 `RecaptchaError` within seconds, before any submit, instead of the exit 36 above, because the labs client minted the reCAPTCHA token on the `flow.google.com` project grid before any migration guard ran. The guard now runs at the mint. If you still see a `RecaptchaError` on a moved account right after `auth login`, that is the labs logged-out landing page from the [#644](https://github.com/ffroliva/gflow-cli/issues/644) cookie harvest, not this.
 
 Google is moving Flow off Labs onto its own origin. On a migrated page load,
 `https://labs.google/fx/tools/flow/project/<id>` redirects to
@@ -53,7 +54,20 @@ the clip). Two real clips were generated this way on 2026-09-05 — spike
 (`GFLOW_CLI_FLOW_HOST=auto`): flow.google.com is the **default** host for that
 command on every account — moved or not; `flow.google.com` forces it for
 everything, and `labs.google` switches the migrated composer off. Limits today: `--project` is required (project creation from the
-migrated editor is not ported), and only `t2v` — everything else still exits 36.
+migrated editor is not ported), and only `t2v` and `i2v` from a local `--initial-frame` (no end frame,
+no UUID/`@Name` frame — the migrated Frames picker exposes no media id in its DOM, so a frame is
+found by file name after gflow uploads it through the editor) — everything else still exits 36.
+
+**Models on the migrated host.** Its picker is driven for every tier the account's
+menu actually renders, `veo-lite-lp` included — matched by the `[Lower Priority]`
+tag alone, exactly as on labs.google. That entry was first captured on 2026-09-05
+(`Veo 3.1 - Lite [Lower Priority]`, on an account whose picker was already defaulted
+to it); matching stays on the tag, which survives Flow throttling a different tier. A tier whose matcher hits more than
+one live entry is refused (exit 11) naming both, rather than bound by DOM order
+([#539](https://github.com/ffroliva/gflow-cli/issues/539)). `veo-lite-lp` is
+deliberately **not** a routing trigger: an account Flow has not moved keeps the
+labs driver for it, since pulling a request onto the new host for a tier no
+capture has seen would trade a working driver for an unverified one.
 
 **Workaround for the rest:** none client-side. The handoff
 is a per-account setting the labs.google app applies on every load (measured
@@ -699,13 +713,15 @@ A block that survives dismissal now aborts pre-submit with exit 23 (probe `overl
 
 ---
 
-### No in-CLI quota visibility
+### No in-CLI quota visibility — resolved
 
-- **Status:** Open · **Severity:** Low · **Roadmap:** v0.5
+- **Status:** Resolved 2026-09-05
 
-`gflow-cli` doesn't yet show how many Veo / Imagen credits remain on your Ultra/Pro subscription. You can check at <https://gemini.google/subscriptions/> in the meantime.
-
-**Roadmap:** v0.5 will surface remaining quota via `gflow auth status` once we capture the relevant Google API.
+Use `gflow credits user` for the selected profile or `gflow credits list` for all saved
+profiles. Both commands query Flow's current read-only credits endpoint with the saved browser
+session; `--json` provides a stable automation contract. The equivalent MCP surface is
+`gflow_get_credits`. The reported balance funds Veo video generation; image generation consumes
+separate per-model daily quotas.
 
 ---
 

{gflow_cli-0.68.0 → gflow_cli-0.69.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gflow-cli
-Version: 0.68.0
+Version: 0.69.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
@@ -117,6 +117,9 @@ uv tool run --from gflow-cli playwright install chromium     # one-time, ~150 MB
 # 2 · Authenticate (one-time, opens a real Chrome window)
 gflow auth login --browser chrome
 
+# Check the current balance (or use `credits list` for every saved profile)
+gflow credits user
+
 # 3 · Generate
 gflow image t2i "a hot air balloon over Tokyo at sunrise"
 # or:
@@ -195,7 +198,7 @@ gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (te
 
 **Current transport:** `ui_automation` drives Flow through a persistent Playwright Chromium profile. It is production-stable and verified end-to-end every release (see the per-release `LIVE_VERIFICATION_*` evidence files).
 
-**Two Flow frontends:** Google is moving accounts from `labs.google` onto `flow.google.com` ([#639](https://github.com/ffroliva/gflow-cli/issues/639)) — same product, different widget toolkit and wire protocol (`batchexecute` instead of `aisandbox-pa`). `flow.google.com` is the default host for what gflow has ported to it — text-to-video today — on every account; the rest of the matrix keeps the labs driver until ported (`GFLOW_CLI_FLOW_HOST`, see [CONFIGURATION](docs/CONFIGURATION.md#gflow_cli_flow_host)).
+**Two Flow frontends:** Google is moving accounts from `labs.google` onto `flow.google.com` ([#639](https://github.com/ffroliva/gflow-cli/issues/639)) — same product, different widget toolkit and wire protocol (`batchexecute` instead of `aisandbox-pa`). `flow.google.com` is the default host for what gflow has ported to it — text-to-video, and image-to-video from a local start frame, today — on every account; the rest of the matrix keeps the labs driver until ported (`GFLOW_CLI_FLOW_HOST`, see [CONFIGURATION](docs/CONFIGURATION.md#gflow_cli_flow_host)).
 
 **What's blocked:** a pure HTTP transport for video generation. The video upload endpoint returns HTTP 401 under non-Chrome browsers plus a reCAPTCHA mint we cannot reproduce headlessly. Three earlier HTTP strategies (`evaluate_fetch`, `bearer`, `sapisidhash`) live under `src/gflow_cli/api/transports/experimental/` for research, off the production path.
 

{gflow_cli-0.68.0 → gflow_cli-0.69.0}/README.md

@@ -46,6 +46,9 @@ uv tool run --from gflow-cli playwright install chromium     # one-time, ~150 MB
 # 2 · Authenticate (one-time, opens a real Chrome window)
 gflow auth login --browser chrome
 
+# Check the current balance (or use `credits list` for every saved profile)
+gflow credits user
+
 # 3 · Generate
 gflow image t2i "a hot air balloon over Tokyo at sunrise"
 # or:
@@ -124,7 +127,7 @@ gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (te
 
 **Current transport:** `ui_automation` drives Flow through a persistent Playwright Chromium profile. It is production-stable and verified end-to-end every release (see the per-release `LIVE_VERIFICATION_*` evidence files).
 
-**Two Flow frontends:** Google is moving accounts from `labs.google` onto `flow.google.com` ([#639](https://github.com/ffroliva/gflow-cli/issues/639)) — same product, different widget toolkit and wire protocol (`batchexecute` instead of `aisandbox-pa`). `flow.google.com` is the default host for what gflow has ported to it — text-to-video today — on every account; the rest of the matrix keeps the labs driver until ported (`GFLOW_CLI_FLOW_HOST`, see [CONFIGURATION](docs/CONFIGURATION.md#gflow_cli_flow_host)).
+**Two Flow frontends:** Google is moving accounts from `labs.google` onto `flow.google.com` ([#639](https://github.com/ffroliva/gflow-cli/issues/639)) — same product, different widget toolkit and wire protocol (`batchexecute` instead of `aisandbox-pa`). `flow.google.com` is the default host for what gflow has ported to it — text-to-video, and image-to-video from a local start frame, today — on every account; the rest of the matrix keeps the labs driver until ported (`GFLOW_CLI_FLOW_HOST`, see [CONFIGURATION](docs/CONFIGURATION.md#gflow_cli_flow_host)).
 
 **What's blocked:** a pure HTTP transport for video generation. The video upload endpoint returns HTTP 401 under non-Chrome browsers plus a reCAPTCHA mint we cannot reproduce headlessly. Three earlier HTTP strategies (`evaluate_fetch`, `bearer`, `sapisidhash`) live under `src/gflow_cli/api/transports/experimental/` for research, off the production path.
 

{gflow_cli-0.68.0/website → gflow_cli-0.69.0}/docs/ARCHITECTURE.md

@@ -436,7 +436,7 @@ We attempted three pure-HTTP transport strategies before settling on `ui_automat
 
 All three now live as standalone modules under `src/gflow_cli/api/transports/experimental/` (`evaluate_fetch.py` / `bearer.py` / `sapisidhash.py`), preserved for reference and future iteration. None survives Google's anti-bot stack for mutation/generation endpoints, so the production path is `ui_automation`.
 
-**The migrated `flow.google.com` host (#639, v0.67.0).** Google is moving accounts off `labs.google` onto `flow.google.com`, a rewritten frontend with a different widget toolkit and a `batchexecute` wire instead of `aisandbox-pa` REST. `src/gflow_cli/api/transports/migrated_composer.py` drives that editor for text-to-video — still through the same real-Chrome Playwright session — by operating the composer UI and then *observing* the app's own `batchexecute` replies (`YhhmEf` submit, `jwpduf` status, `as29s` result) before downloading the clip. `GFLOW_CLI_FLOW_HOST` routes between the two (`auto` = migrated host for every request it can serve, `--project` required there); the rest of the command matrix keeps `ui_automation` on unmoved accounts and exits 36 on moved ones. Recon: `docs/superpowers/spikes/2026-09-05-migrated-host-wire-protocol.md`.
+**The migrated `flow.google.com` host (#639, v0.67.0).** Google is moving accounts off `labs.google` onto `flow.google.com`, a rewritten frontend with a different widget toolkit and a `batchexecute` wire instead of `aisandbox-pa` REST. `src/gflow_cli/api/transports/migrated_composer.py` drives that editor for text-to-video and for image-to-video from a local start frame — still through the same real-Chrome Playwright session — by operating the composer UI and then *observing* the app's own `batchexecute` replies (`YhhmEf`/`eb1hJf` submit, `jwpduf` status, `as29s` result) before downloading the clip. A start frame goes in through the editor's own Upload entry (the app's `maseQ` reply names the media id — `migrated.frame_uploaded`), is bound in the Frames picker by file name (`migrated.frame_bound`), and the submit *request* is inspected for that id and an i2v model key before the run is trusted (`WireFormatError` otherwise); a modal over a fresh editor is closed first (`migrated.dialog_dismissed`). `GFLOW_CLI_FLOW_HOST` routes between the two (`auto` = migrated host for every request it can serve, `--project` required there); the rest of the command matrix keeps `ui_automation` on unmoved accounts and exits 36 on moved ones. Recon: `docs/superpowers/spikes/2026-09-05-migrated-host-wire-protocol.md`.
 
 **Standalone-only transports.** `bearer` and `sapisidhash` discard any caller-supplied Playwright page and launch their own browser under a fresh `ProfileLease`, so they are **standalone-only** — they cannot run inside a `FlowApiClient` that already holds the profile lease (the second acquire would self-lock with `ProfileLockedError`). Selecting either via `GFLOW_CLI_TRANSPORT` (or the Python API) while the client owns the profile now fails fast with a clear `ConfigurationError` naming the transport, rather than the opaque lock error. `evaluate_fetch` is exempt: it reuses the client's shared page and takes no second lease. The standalone-only set lives in `STANDALONE_ONLY_TRANSPORTS` (`api/transports/__init__.py`); to drive `bearer`/`sapisidhash`, run them outside an owning client.
 

{gflow_cli-0.68.0/website → gflow_cli-0.69.0}/docs/CONFIGURATION.md

@@ -361,11 +361,11 @@ GFLOW_CLI_HISTORY_PROMPTS=redacted gflow image t2i "confidential brief"
 
 **What:** Which Flow frontend gflow drives. Google is moving accounts from `labs.google/fx/tools/flow` onto `flow.google.com` one at a time ([#639](https://github.com/ffroliva/gflow-cli/issues/639)); the two are the same product on different widget toolkits and different wire protocols, so each has its own driver.
 **Values:**
-- `auto` (default) — **`flow.google.com` is the default host for every request it can serve today** (`video t2v` with `--project`), on moved and unmoved accounts alike — the new host serves both. A request the new host cannot serve yet keeps the labs driver on an unmoved account; a moved account has no labs to fall back to: other modes exit 36, a missing `--project` or a labs-only model exit 11.
+- `auto` (default) — **`flow.google.com` is the default host for every request it can serve today** (`video t2v`, and `video i2v` from a local `--initial-frame` with no end frame, both with `--project`), on moved and unmoved accounts alike — the new host serves both. A request the new host cannot serve yet keeps the labs driver on an unmoved account; a moved account has no labs to fall back to: other modes exit 36, a missing `--project` or a labs-only model exit 11.
 - `flow.google.com` — force the migrated composer for everything, including what it cannot serve yet (those requests then exit 36/11 instead of falling back).
 - `labs.google` — never use the migrated composer; a moved account fails with exit 36 (kill switch).
 **Default:** `auto`
-**Scope today:** the migrated composer covers `gflow video t2v` with `--project <id>` (settings via the option groups, model picker, submit, status observed on the page's own `batchexecute` replies, download from the signed CDN URL). Image, i2v/r2v, characters, scenes, extend, instructions and tools are not ported yet and exit 36 on a moved account. MCP inherits the setting from the server/daemon environment, not per call.
+**Scope today:** the migrated composer covers `gflow video t2v` and `gflow video i2v --initial-frame <local file>` with `--project <id>` (settings via the option groups, model picker, a local start frame uploaded through the editor's own Upload entry and bound in the Frames picker by file name, submit, status observed on the page's own `batchexecute` replies, download from the signed CDN URL). An end frame, a frame given by UUID or `@Name`, image, r2v, characters, scenes, extend, instructions and tools are not ported yet and exit 36 on a moved account. MCP inherits the setting from the server/daemon environment, not per call.
 
 ### `GFLOW_CLI_PREFER_CLASSIC` *(deprecated — use `GFLOW_CLI_UI_MODE=classic`)*
 

{gflow_cli-0.68.0/website → gflow_cli-0.69.0}/docs/DEVELOPMENT.md

@@ -128,7 +128,9 @@ This repo is actively developed with Claude Code (see [CLAUDE.md](../CLAUDE.md))
 
 - Claude branches are renamed to the appropriate `feature/`, `fix/`, `docs/` prefix before the PR is opened. The `claude/` prefix is internal scaffolding.
 - Claude never bumps the version or cuts a release without explicit instruction — use `/release`.
-- Claude opens PRs as **drafts** targeting `develop`. The maintainer reviews, runs e2e if needed, and merges.
+- Claude opens PRs as **drafts** targeting `develop`. E2E evidence for any change touching a
+  Flow surface is part of the PR, not something the maintainer supplies afterwards (CONTRIBUTING
+  § *Test categories*); the maintainer reviews, runs e2e only where the author could not, and merges.
 - Commit messages never carry `Co-Authored-By: Claude` or any AI attribution — author credit is the human maintainer's only.
 
 ---

{gflow_cli-0.68.0 → gflow_cli-0.69.0}/docs/INDEX.md

@@ -31,7 +31,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | **[docs/CONFIGURATION.md](CONFIGURATION.md)** | All env vars, precedence chain, default paths per OS | Tuning behaviour, picking output paths |
 | **[docs/EXTERNAL_STORAGE.md](EXTERNAL_STORAGE.md)** | S3, MinIO, and Google Cloud Storage output configuration | Sending generated assets to a bucket instead of local disk |
 | **[docs/USER_GUIDE.md](USER_GUIDE.md)** | Task-oriented walkthroughs (first setup, batch video, multi-image, log forensics, recovery, multi-account, migration) | You want to GET SOMETHING DONE — not look up a flag |
-| **[docs/USAGE.md](USAGE.md)** | Command-by-command reference, manifest format, recipes, exit-code table | Day-to-day CLI use — look up specific commands / flags |
+| **[docs/USAGE.md](USAGE.md)** | Command-by-command reference, credit-balance inspection, manifest format, recipes, exit-code table | Day-to-day CLI use — look up specific commands / flags |
 | **[docs/ARCHITECTURE.md](ARCHITECTURE.md)** | Modular monolith, per-worker Page pool, RFC 9457 Problem Details, retry layer | Adding a feature or a new provider |
 | **[docs/SECURITY.md](SECURITY.md)** | What secrets are stored where, threat model, hardening | Audit, code review, multi-user machines |
 | **[docs/DATA_LAYER.md](DATA_LAYER.md)** | Local SQLite catalog: goals, schema, recording flow, redaction, `gflow data` CLI, migrations, extension guide | Anything touching `gflow_cli.data`, debugging missing rows, building I2V/repair tooling, auditing what is stored |
@@ -48,7 +48,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | **[docs/ASSET_TAGGING_RECON.md](ASSET_TAGGING_RECON.md)** | `@`-mention asset tagging research & integration design: what Flow's `@CharacterName`/`@me`/`@ingredient` tags are, how they map onto the already-verified `referenceEntities`/`referenceImages` wire, the H1-vs-H2 serialization hypothesis, the CLI-side mention-resolver proposal, and the pre-implementation capture spike plan | Working on inline `@` mentions in prompts, `video --character` reuse, or planning the mention-capture spike |
 | **[tasks/lessons.md](../tasks/lessons.md)** | Running notebook of patterns + reviewer findings, dated and traced to commits | Starting a new phase; debugging "why did the council flag this?" |
 | **[skills/README.md](../skills/README.md)** | Installable agent skill docs (gflow-cli, predict, pr-council-review, scenario) — cross-tool portable Markdown consumed by Claude Code, Cursor, Codex, Antigravity, Aider, etc. | Any agent wanting to use gflow-cli correctly |
-| **[scripts/dev/skillopt/README.md](../scripts/dev/skillopt/README.md)** | SkillOpt mock harness — rollout→score loop for measuring and improving skill doc accuracy across multiple LLM providers | Measuring a skill edit's impact; comparing Claude vs GPT-4o vs Gemini on gflow tasks |
+| **[scripts/dev/skillopt/README.md](../scripts/dev/skillopt/README.md)** | SkillOpt mock harness — rollout→score loop for measuring and improving skill doc accuracy, against any OpenAI-compatible endpoint via the `GFLOW_CLI_LLM_*` settings | Measuring a skill edit's impact; comparing two models on gflow tasks |
 | **[scripts/diag/README.md](../scripts/diag/README.md)** | Diagnostic investigation scripts — run against a live authenticated profile to capture wire samples, measure Chrome memory, or mint reCAPTCHA tokens | Running a one-off investigation against a live Flow session; establishing baseline measurements for issue #155 |
 | [docs/superpowers/specs/2026-07-04-pr-triage-autopilot-design.md](superpowers/specs/2026-07-04-pr-triage-autopilot-design.md) | PR-triage autopilot design spec: Stage 0/1 gate, Docker sandboxing, Telegram and audit ledger | Reviewing or auditing the automated PR-triage setup |
 | [docs/superpowers/plans/2026-07-08-pr-triage-autopilot/PLAN.md](superpowers/plans/2026-07-08-pr-triage-autopilot/PLAN.md) | Implementation plan for the PR-Triage Autopilot | Tracking task-by-task execution |
@@ -92,6 +92,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"I just installed gflow — how do I get to my first video?"** → [USER_GUIDE § Journey 1](USER_GUIDE.md#journey-1--first-time-setup-10-minutes)
 **"How do I render 20 clips overnight?"** → [USER_GUIDE § Journey 3](USER_GUIDE.md#journey-3--batch-video-from-a-prompt-list-shell-loop)
 **"How much will this batch cost me in Veo credits?"** → [USER_GUIDE § Journey 10](USER_GUIDE.md#journey-10--budgeting-credits-before-a-batch-run)
+**"How many Veo credits remain on one or all profiles?"** → [USAGE § `gflow credits`](USAGE.md#gflow-credits)
 **"How do I feed gflow outputs into ffmpeg / a pipeline?"** → [USER_GUIDE § Journey 11](USER_GUIDE.md#journey-11--wiring-gflow-outputs-into-a-downstream-pipeline)
 **"How do I chain clips into one continuous video (initial-frame I2V)?"** → [USAGE § `gflow video chain`](USAGE.md#gflow-video-chain)
 **"How do I stitch existing clips into one extended .mp4 (credit-free, no ffmpeg)?"** → [USAGE § `gflow scene`](USAGE.md#gflow-scene)
@@ -126,7 +127,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"My old assets re-upload / have no names?"** → run `gflow data sync --names` (credit-free name backfill from Flow's listing) — see [USAGE § `gflow data sync`](USAGE.md#gflow-data-sync)
 **"How do I use this project's skills in Cursor / Codex / Antigravity / Aider?"** → [skills/README.md](../skills/README.md#use-with-other-agents)
 **"How do I benchmark a skill doc against real tasks?"** → [scripts/dev/skillopt/README.md](../scripts/dev/skillopt/README.md)
-**"How do I compare Claude vs GPT-4o vs Gemini on gflow tasks?"** → `python scripts/dev/skillopt/harness.py --provider openai --model gpt-4o` (see [skillopt README](../scripts/dev/skillopt/README.md))
+**"How do I compare two models on gflow tasks?"** → set `GFLOW_CLI_LLM_BASE_URL` / `GFLOW_CLI_LLM_API_KEY` at any OpenAI-compatible endpoint, then `uv run python scripts/dev/skillopt/harness.py --model <id>` once per model (see [skillopt README](../scripts/dev/skillopt/README.md))
 **"What does Chrome actually use in RAM during a generation?"** → run `uv run python scripts/diag/memory_profile.py --profile NAME` (see [scripts/diag/README.md](../scripts/diag/README.md))
 **"How do I report a security issue?"** → [SECURITY § Reporting](SECURITY.md#reporting)
 **"What branch do I work on? How do I name it?"** → [DEVELOPMENT § Branching model](DEVELOPMENT.md#branching-model)
@@ -148,7 +149,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"How do I upgrade gflow-cli?"** → [USAGE § `gflow update`](USAGE.md#gflow-update) (`gflow update` runs the installer that put it here — uv tool / pipx / pip; `--check` only reports; source installs are refused with exit 11)
 **"How do I run the MCP server so an agent can't spend credits?"** → [CONFIGURATION § GFLOW_MCP_NO_SPEND](CONFIGURATION.md#gflow_mcp_no_spend) + [MCP § Option A2](MCP.md#option-a2-read-only-server) (`gflow mcp run --no-spend` / `GFLOW_MCP_NO_SPEND=1`; v0.57.0 — both generate tools go unregistered, not merely refused)
 **"Which Flow UI arm does a run require, and why did it exit 2 or 28?"** → [CONFIGURATION § GFLOW_CLI_UI_MODE](CONFIGURATION.md#gflow_cli_ui_mode) (`auto` ≡ `classic` for **both** images and video — video since v0.57.0/#299, images since #595; unreachable classic aborts pre-submit with exit 28, $0; explicit `agentic` on video exits 2)
-**"Which Flow frontend does a run drive — labs.google or the migrated flow.google.com — and why did it exit 36 or 11?"** → [CONFIGURATION § GFLOW_CLI_FLOW_HOST](CONFIGURATION.md#gflow_cli_flow_host) (`auto` = flow.google.com for every request it can serve — `t2v` with `--project`, on moved and unmoved accounts; `flow.google.com` forces it; `labs.google` is the kill switch. On a moved account everything except `t2v` exits 36, non-retryable, and `t2v` without `--project` exits 11) · recon: [migrated-host wire protocol](superpowers/spikes/2026-09-05-migrated-host-wire-protocol.md), [handoff mechanism](superpowers/spikes/2026-09-04-migrated-host-handoff-mechanism.md) · evidence: [LIVE_VERIFICATION_v0.67.0](LIVE_VERIFICATION_v0.67.0.md)
+**"Which Flow frontend does a run drive — labs.google or the migrated flow.google.com — and why did it exit 36 or 11?"** → [CONFIGURATION § GFLOW_CLI_FLOW_HOST](CONFIGURATION.md#gflow_cli_flow_host) (`auto` = flow.google.com for every request it can serve — `t2v`, and `i2v` from a local `--initial-frame`, with `--project`, on moved and unmoved accounts; `flow.google.com` forces it; `labs.google` is the kill switch. On a moved account an end frame, a UUID/`@Name` frame and everything except `t2v`/`i2v` exit 36, non-retryable, and a missing `--project` exits 11) · recon: [migrated-host wire protocol](superpowers/spikes/2026-09-05-migrated-host-wire-protocol.md), [handoff mechanism](superpowers/spikes/2026-09-04-migrated-host-handoff-mechanism.md), [frames attach (i2v)](superpowers/spikes/2026-09-05-migrated-frames-attach.md) · evidence: [LIVE_VERIFICATION_v0.67.0](LIVE_VERIFICATION_v0.67.0.md) (t2v), [LIVE_VERIFICATION_v0.69.0](LIVE_VERIFICATION_v0.69.0.md) (i2v from a local start frame, v0.69.0)
 **"Will this get my Google account flagged or banned? What protects me?"** → [ACCOUNT_SAFETY.md](ACCOUNT_SAFETY.md) — the operational answer in one place: rate limit vs WAF block vs ban (they are different), what the tool does to stay unremarkable (headed real Chrome, ±25% interaction jitter, 0.5–1.5 s submission pacing, one project per run, isolated profiles, refuse-don't-retry), what it deliberately does **not** do (no proxies, no fingerprint spoofing, no headless unlock), the knobs, the [#241](https://github.com/ffroliva/gflow-cli/issues/241) field data on what actually triggers a 403, and what we cannot promise. Legal statement: [DISCLAIMER](../DISCLAIMER.md)
 
 **"I got a 403 / `PUBLIC_ERROR_UNUSUAL_ACTIVITY` — what now?"** → [ACCOUNT_SAFETY § When Google does push back](ACCOUNT_SAFETY.md#when-google-does-push-back) (stop, cool down 30–60 min, use real Chrome meanwhile, switch profile, widen jitter); cadence evidence in [DEBUGGING § WAF cadence](DEBUGGING.md#waf-cadence); full entry in [KNOWN_ISSUES](../KNOWN_ISSUES.md)

{gflow_cli-0.68.0 → gflow_cli-0.69.0}/docs/LIVE_VERIFICATION_v0.68.0.md

@@ -73,6 +73,32 @@ working, and the next update from another shell refreshes it.
   both branches (`tests/test_cli_update.py`). A real interactive-terminal screenshot was
   **not** taken this cycle.
 
+## #670 — migrated submit-enable race (PR #672, @ChandraLiuswanto), verified on the flagged maintainer account
+
+Folded into v0.68.0 from develop after the release branch was cut. The fix changes a real
+generation path (`migrated_composer.submit_and_observe` now polls `is_enabled()` for up to
+5 s after `insert_text`), so it was run for real on this machine at PR head `e3c3220`
+(0.67.0 + the PR diff, built in a detached worktree), one veo-lite clip:
+
+| # | Command | Profile / cohort | Result |
+|---|---|---|---|
+| 1 | `gflow video t2v "a paper crane unfolding on a wooden desk, soft morning light" --model veo-lite --aspect 16:9 --project c5550ed7-… --json` | ffroliva (flagged, en-GB), route `migrated` under `auto` | **exit 0, 60 s wall**, `MEDIA_GENERATION_STATUS_SUCCESSFUL` |
+
+Five-layer ledger: one new mp4 (`44f890db-….mp4`); `ftyp` at offset 4; **1,578,650 B** =
+the size the `jwpduf` / `as29s` records reported, ffprobe `h264 1280x720 8.000 s`; structlog
+`migrated.dispatch → navigate → editor_ready → settings_applied → prompt_typed (17:51:15.810)
+→ submit_clicked (17:51:16.165) → submit_observed (YhhmEf) → status ×7 → status 3 (bytes) →
+as29s → download`, no `error_raised`; the media id and workflow id are in the run's
+`result.json`. `prompt_typed → submit_clicked` = **355 ms**: the new poll ran through at least
+one disabled read. On stock 0.67.0 this account submitted at ~200 ms and never hit the race,
+which is why the v0.67.0 ledger was green while the reporter's account failed every run. A
+first attempt with `--duration 8` on veo-lite aborted pre-submit with exit 11 at $0 — this
+cohort renders no duration row for veo-lite (the v0.67.0 ledger's #650 finding, unrelated).
+
+NOT verified: the reporter's account (only they can run it; their patched-wheel run in the
+PR body covers it), an unmigrated account (none remains on this machine), and the MCP queued
+path (no payload key changed; it reaches the identical `submit_and_observe`).
+
 ## Pre-tag gates (filled before signing)
 
 | Gate | Result |
@@ -87,8 +113,17 @@ working, and the next update from another shell refreshes it.
 
 ## Post-tag evidence
 
-To be appended after the tag push: release workflow run URL, `gh release view v0.68.0`,
-PyPI page, and one `pip index versions gflow-cli` read showing 0.68.0.
+| Item | Evidence |
+|---|---|
+| Tag | `v0.68.0` on `16ed7e2` (release branch head after folding #672), SSH-signed, `git tag -v` → "Good git signature" |
+| Release workflow | https://github.com/ffroliva/gflow-cli/actions/runs/33984171793 — completed, success |
+| GitHub Release | https://github.com/ffroliva/gflow-cli/releases/tag/v0.68.0 — published 2026-09-05T18:29:12Z, not a prerelease, 5 assets |
+| PyPI | `pip index versions gflow-cli` → `gflow-cli (0.68.0)` |
+| Release PR | #674 `chore/release-v0.68.0 → main`, 16 checks passing at the tagged head (SonarCloud included) |
+
+Note for the next cycle: the tag was first created on 14f5742, then deleted locally and
+re-signed on 16ed7e2 after PR #672 landed on develop during the doc-review pass. Nothing
+had been pushed in between, so no published tag ever moved.
 
 ## NOT verified this cycle (recorded, not omitted)