gflow-cli 0.63.0__tar.gz → 0.64.0__tar.gz

{gflow_cli-0.63.0 → gflow_cli-0.64.0}/.codex-plugin/plugin.json

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

{gflow_cli-0.63.0 → gflow_cli-0.64.0}/AGENTS.md

@@ -75,13 +75,21 @@ $env:PYTHONUTF8=1
 uv run python scripts/ci/check_repo_hygiene.py
 uv run python scripts/ci/check_doc_links.py
 uv run python scripts/ci/check_website_docs_pii.py
+uv run python scripts/ci/generate_website_docs.py --check
 uv run ruff check src tests
 uv run ruff format --check src tests
 uv run pyright src
 uv run python -m pytest -q --cov=gflow_cli
 ```
 
-Or invoke the wrapper: `/gflow:check`.
+Or invoke the wrapper: `/gflow:check` — **prefer it.** This list is the mechanical subset;
+the skill additionally carries the **step 1b surface blast-radius sweep** (MCP↔CLI parity and
+the five other mirror axes), which no command here can check and no CI gate can see.
+
+> **Do not trim this list again.** It previously omitted
+> `generate_website_docs.py --check`, so an agent following AGENTS.md instead of the skill
+> shipped a stale `website/docs/` mirror to a green local run and a red CI (#626 session,
+> 2026-09-02). Two lists that disagree means the shorter one is silently wrong.
 
 - 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.
@@ -97,6 +105,26 @@ Or invoke the wrapper: `/gflow:check`.
 - 100-char line length, `ruff` configured. Imports sorted by `ruff` (isort rules).
 - **YAGNI / least-code**: prefer the smallest change that works. No speculative abstractions (interface/factory with one implementation), no config or flags nobody sets, no dead constants/helpers, no reinventing the stdlib. Review carries this as its own lens — the **D14 over-engineering** dimension of [`pr-council-review`](skills/pr-council-review/SKILL.md) (baseline, always runs). Its rubric is portable; the `ponytail` plugin (see CONTRIBUTING) is an optional accelerant, not a dependency.
 - **MCP & CLI Schema Symmetry**: Any updates or additions to user-facing CLI command parameters (e.g., `gflow image t2i`, `gflow video`) must be mirrored in the corresponding MCP tool definitions. Never add option/argument fields to Click commands without updating the MCP server implementation. This symmetry is enforced programmatically in CI via `tests/mcp/test_cli_parity.py` (every CLI leaf command needs a mapped MCP tool or an explicit, reasoned exemption) plus the schema checks in `tests/mcp/test_server.py`.
+
+  **That CI gate is command-level only** — it fires on a new *leaf*, and stays green while an
+  option goes unmirrored, a queued-payload key goes unread, or a tool docstring asserts a
+  restriction the CLI no longer has. So MCP is a responsibility of **every phase**, not a
+  post-hoc checklist item. Each skill owns its slice:
+
+  | Phase | Skill | Its MCP duty |
+  |---|---|---|
+  | 1 Triage | `issue-assessment` | Name which surfaces reproduce it — CLI, MCP, or both |
+  | 2 Pre-impl | `predict` | Persona 4 scopes the MCP blast radius before code exists |
+  | 3 BDD | `scenario` | **D13** — enumerate the MCP twin of every edge case |
+  | 4 Plan | `plan` | **Task 6 is not optional when task 5 exists** |
+  | 5 Review | `pr-council-review` | **D15** — surface parity, incl. the payload-key round trip |
+  | 7 Check | `check` | **Step 1b** — the canonical six mirror axes |
+  | 8 Live-verify | `live-verify` | The MCP queued path is *different code*; decide if it needs its own run |
+  | 10 Release | `doc-review` | Grade `docs/MCP.md` + tool docstrings; a **false** claim blocks |
+
+  The six mirror axes are written out **once**, in [`skills/check/SKILL.md`](skills/check/SKILL.md)
+  step 1b. Every other skill cites them. Do not copy the table around — a duplicated checklist
+  drifts, which is the exact failure this row exists to prevent.
 - **Locale-Invariance Discipline for UI Automation**: **Never** write text-label string selectors (`has-text(...)` or multi-locale text lists) for DOM elements, overlays, announcements, menus, tabs, or buttons. All DOM selectors in `src/gflow_cli/api/transports/` must be 100% language-agnostic, anchoring exclusively on structural properties: **Tier 1 Anchors** — e.g. hyperlinks (`a[href*='changelog']`), icon ligatures (`button:has(i.google-symbols:text('close'))`), ARIA roles (`[role='banner']`, `button[data-dismiss]`), and hierarchical DOM relationships (`[role='dialog']:has(a[href*='changelog']) button`). Relying on translated display labels or maintaining multi-locale text cascades is strictly forbidden as an anti-pattern hack.
 
 ## PR instructions

{gflow_cli-0.63.0 → gflow_cli-0.64.0}/CHANGELOG.md

@@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.64.0] — 2026-09-02
+
+### Added
+
+- **`gflow video i2v --model omni-flash --end-frame` now works** ([#626](https://github.com/ffroliva/gflow-cli/issues/626)).
+  Google shipped first-and-last-frame generation for Omni 1.1 Flash, so the
+  guard that rejected that combination with exit 17 is gone:
+
+  ```bash
+  gflow video i2v ./start.png "she turns toward the window" \
+      --model omni-flash --end-frame ./end.png --duration 10
+  ```
+
+  omni-flash is the only model that also exposes `--duration`, so this is the
+  one route to a 10-second first+last interpolation.
+
+### Changed
+
+- **i2v end-frame safety moved from a static table to a post-submit route
+  check.** gflow used to decide which models could carry an end frame from a
+  hardcoded capability list, which silently went stale when Google shipped the
+  feature. It now verifies the route Flow *actually* used: a run that carried an
+  end frame but came back on `batchAsyncGenerateVideoStartImage` — Flow dropping
+  the frame at submit and billing a clip that was never interpolated — fails
+  with `WireFormatError` instead of being reported as a success. This also
+  catches a partial or staged rollback on any account, which the old table
+  could not.
+
+  **Breaking for scripts** that branched on exit 17 for `omni-flash` +
+  `--end-frame`: that combination now succeeds. Exit 17 is unchanged for
+  `gflow video chain --model omni-flash`, which is still rejected (chain-scale
+  seeded i2v remains unverified).
+
+- **MCP↔CLI parity is now a duty of every pipeline phase** (contributor-facing).
+  `tests/mcp/test_cli_parity.py` is command-level: it fires when a new CLI *leaf*
+  lacks a mapped MCP tool, and stays green while an option goes unmirrored, a
+  queued-payload key goes unread, or a tool docstring asserts a restriction the
+  CLI no longer has. #626 shipped exactly that third case — `mcp/tools.py` and
+  `docs/MCP.md` kept telling agents `omni_flash` was rejected for i2v-with-frames
+  through a fully green pipeline. Each skill now owns a slice: `issue-assessment`
+  names affected surfaces, `predict` scopes the MCP blast radius, `scenario` adds
+  **D13**, `plan` makes the MCP mirror **task 6** (not optional when task 5
+  exists), `pr-council-review` adds **D15**, `check` adds **step 1b** (the
+  canonical six mirror axes), `live-verify` treats the MCP queued path as
+  separate code, and `doc-review` grades a *false* MCP claim as release-blocking.
+  Automating the mechanically checkable part is tracked in
+  [#628](https://github.com/ffroliva/gflow-cli/issues/628).
+
+### Fixed
+
+- **`AGENTS.md`'s Impeccable Routine was missing `generate_website_docs.py --check`**,
+  which `skills/check` already ran. Following the shorter list produced a green
+  local run against a stale `website/docs/` mirror and a red CI. The two lists now
+  agree.
+
 ## [0.63.0] — 2026-09-01
 
 ### Added
@@ -3515,7 +3570,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.63.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.64.0...HEAD
+[0.64.0]: https://github.com/ffroliva/gflow-cli/compare/v0.63.0...v0.64.0
 [0.63.0]: https://github.com/ffroliva/gflow-cli/compare/v0.62.1...v0.63.0
 [0.62.1]: https://github.com/ffroliva/gflow-cli/compare/v0.62.0...v0.62.1
 [0.62.0]: https://github.com/ffroliva/gflow-cli/compare/v0.61.0...v0.62.0

{gflow_cli-0.63.0 → gflow_cli-0.64.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gflow-cli
-Version: 0.63.0
+Version: 0.64.0
 Summary: Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal.
 Project-URL: Homepage, https://github.com/ffroliva/gflow-cli
 Project-URL: Issues, https://github.com/ffroliva/gflow-cli/issues

{gflow_cli-0.63.0 → gflow_cli-0.64.0}/docs/INDEX.md

@@ -155,7 +155,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.63.0](LIVE_VERIFICATION_v0.63.0.md) (**`gflow video extend` — continuing a clip past Flow's 8s ceiling, verified 2026-09-01 on profile `ffroliva`, 20 Veo credits.** The decisive observation is that segment 2's `source_media_id` **is** segment 1's `media_id` (`0c9364f3…` seeded from `b9458021…`, then `648f9291…` seeded from `0c9364f3…`) — tail-only chaining, which no mock can establish; had it re-seeded from the source, the output would have been two divergent continuations of the same moment instead of one continuous shot. `extend_model_resolved` logged `candidate_count=99` against `SERVICE_TIER_INTERMEDIATE`, proving the key came from the live capability listing rather than a constant, and plan cost matched actual spend (`20 credits total, balance 875` → `Extended — 2/2 segment(s), 20 credits`). Render: 23.02s / 1280×720 / 24fps / h264+aac. **The run found a defect the offline suite is structurally incapable of seeing:** an extend segment carries **7.000000s** of content, not the 8 Flow advertises and bills, so server-side concat pads every internal seam with a frozen frame and digital silence (15s at −75.1 dB against −29 neighbours, reproduced on a second independent render) — filed in KNOWN_ISSUES with the three questions that must be answered before any clamp, and the reason `--extend N` on t2v/i2v was deliberately NOT shipped. Seven items are recorded as NOT verified rather than omitted: portrait `9:16`, `--aspect` against a mismatched source, chains longer than 2 segments, `--resume-from` against a live partial scene, the insufficient-credits refusal, a live Ctrl+C, and `OperationKind.EXTEND` rows.) · previous: [LIVE_VERIFICATION_v0.62.1](LIVE_VERIFICATION_v0.62.1.md) (**#604 `--model omni-flash` selects again after Flow's `Omni Flash` → `Omni 1.1 Flash` rename, verified 2026-08-30 on profile `ffroliva` at ZERO Veo credits.** The production `_select_video_model` was driven against the real picker: the shipped selector resolves verbatim — `model_selected model=omni_flash via="[role='menuitem']:has-text('Omni'):has-text('Flash'):not(:has-text('[Lower Priority]'))"` — and all six cases came back as expected: the four offered tiers SELECT, a tier Flow does not offer REFUSES, and a deliberately ambiguous selector REFUSES rather than resolving `.first`. Selection happens before submit, so the whole matrix is free. The transport's own refusal diagnostic read the live menu back as `Omni 1.1 Flash / Veo 3.1 - Lite / Fast / Quality`, independently corroborating the fixture. Four items are recorded as NOT verified rather than omitted: the rename *direction* [the `Omni Flash` baseline is a different account, locale and date], an actual `Omni ... [Lower Priority]` entry [Flow has never offered one], a full credit-spending generation on omni-flash, and #539's absence question, which stays open.) · previous: [LIVE_VERIFICATION_v0.62.0](LIVE_VERIFICATION_v0.62.0.md) (**#595 `auto` ≡ `classic` for images, verified 2026-08-28 on profile `ci-probe` — an account Flow had moved to the agentic cohort the day before — at ZERO Veo credits.** With no flags and no env vars the run logged `ui_driver.ui_mode.attempt_exit_agent` → `ui_driver.bound mode=classic ui_mode=classic` and generated a real 768x1376 JPEG (exit 0); the day before, the identical command on the same account bound `auto`→`agentic` and failed. The same log independently closed **#183**: `mode_switch_trigger` and `image_mode_tab`, the selectors it reported as unfindable, both matched. #591 was proven against the real 500-row catalog — **0** occurrences of the string `"None"`, 31 proper JSON `null`s, over a catalog holding 119 NULL-bearing rows. #592 shows exactly one `client.account_locale_cached` per command. Three items are recorded as NOT verified rather than omitted: the exit-28 abort on a *pinned* agentic account, the #597 batch inter-prompt guard, and any fresh announcement modal — the last two because all three accounts have already acked the current changelog, so no modal can be raised until Google ships the next one.) · previous: [LIVE_VERIFICATION_v0.61.0](LIVE_VERIFICATION_v0.61.0.md) (**#539 video-model refusal + #586 image-model refusal and server-side attribution, verified 2026-08-26/27 on profile `denon82`, ONE Veo generation total** — the video fix was proven by a **zero-credit A/B against the stashed pre-fix source running on live Flow**: the old code returned SELECTED for `veo-lite-lp`, a model Flow does not offer to this account, and for a deliberately ambiguous selector matching 3 entries; the new code refuses both with exit 18 naming what Flow offered. Model selection happens before submit, so refusals cost nothing and the A/B was free. The happy path still generates: `--model omni-flash` → exit 0, a real 2.2 MB `ftypisom` mp4, catalog recording `omni_flash`. Two items are recorded as NOT verified rather than omitted: three of #584's four navigation-settle sites were never exercised [no bearer refresh occurred in these runs], and #582's canary self-re-exec has its first real exercise tonight. Also falsified: #539's recorded note that the video picker uses a different trigger — the two constants are byte-identical strings, and the repeated empty menu captures were the capture's own fault.) · previous: [LIVE_VERIFICATION_v0.60.0](LIVE_VERIFICATION_v0.60.0.md)
+**What was actually live-verified for the latest release?** → latest: [LIVE_VERIFICATION_v0.64.0](LIVE_VERIFICATION_v0.64.0.md) (**#626 `--model omni-flash --end-frame` — first+last interpolation on Omni 1.1 Flash, verified 2026-09-02.** The guard this release removes was evidence-gated, so it was retired on evidence: a route-aborted submit capture on **two distinct Google accounts** (`ffroliva`, `denon82`) fired `video:batchAsyncGenerateVideoStartAndEndImage` with `startImage` AND `endImage` non-null at **zero credits**, ruling out a single-account artifact. The decisive layer is semantic, not structural: the paid 4s generation's **last frame IS the supplied end image** and its first frame is the start image — two visibly different subjects — which is the only check that distinguishes "Flow bound the end frame" from "Flow accepted and ignored it", and which layers 1–4 would pass either way. Render: 4.01s / 720×1280 / h264+aac / 2.4 MB, `MEDIA_GENERATION_STATUS_SUCCESSFUL`. The static capability table is **deleted**, not corrected — it went stale silently once and would again; a post-submit route check (`_assert_i2v_route`) now fails a run whose end frame Flow dropped back to the `StartImage` route, catching a rollback on any account without anyone re-reading a support page. One item is recorded as NOT verified rather than omitted: `--duration 10` + end frame is **submit-verified only** (`duration_set seconds=10` on the correct route with both images bound), because the status poll returned HTTP 401 mid-run and a retry 401'd at `project.create` before submitting — [#561](https://github.com/ffroliva/gflow-cli/issues/561), pre-existing, so verification was stopped rather than spending further credits on an environmental fault.) · previous: [LIVE_VERIFICATION_v0.63.0](LIVE_VERIFICATION_v0.63.0.md) (**`gflow video extend` — continuing a clip past Flow's 8s ceiling, verified 2026-09-01 on profile `ffroliva`, 20 Veo credits.** The decisive observation is that segment 2's `source_media_id` **is** segment 1's `media_id` (`0c9364f3…` seeded from `b9458021…`, then `648f9291…` seeded from `0c9364f3…`) — tail-only chaining, which no mock can establish; had it re-seeded from the source, the output would have been two divergent continuations of the same moment instead of one continuous shot. `extend_model_resolved` logged `candidate_count=99` against `SERVICE_TIER_INTERMEDIATE`, proving the key came from the live capability listing rather than a constant, and plan cost matched actual spend (`20 credits total, balance 875` → `Extended — 2/2 segment(s), 20 credits`). Render: 23.02s / 1280×720 / 24fps / h264+aac. **The run found a defect the offline suite is structurally incapable of seeing:** an extend segment carries **7.000000s** of content, not the 8 Flow advertises and bills, so server-side concat pads every internal seam with a frozen frame and digital silence (15s at −75.1 dB against −29 neighbours, reproduced on a second independent render) — filed in KNOWN_ISSUES with the three questions that must be answered before any clamp, and the reason `--extend N` on t2v/i2v was deliberately NOT shipped. Seven items are recorded as NOT verified rather than omitted: portrait `9:16`, `--aspect` against a mismatched source, chains longer than 2 segments, `--resume-from` against a live partial scene, the insufficient-credits refusal, a live Ctrl+C, and `OperationKind.EXTEND` rows.) · previous: [LIVE_VERIFICATION_v0.62.1](LIVE_VERIFICATION_v0.62.1.md) (**#604 `--model omni-flash` selects again after Flow's `Omni Flash` → `Omni 1.1 Flash` rename, verified 2026-08-30 on profile `ffroliva` at ZERO Veo credits.** The production `_select_video_model` was driven against the real picker: the shipped selector resolves verbatim — `model_selected model=omni_flash via="[role='menuitem']:has-text('Omni'):has-text('Flash'):not(:has-text('[Lower Priority]'))"` — and all six cases came back as expected: the four offered tiers SELECT, a tier Flow does not offer REFUSES, and a deliberately ambiguous selector REFUSES rather than resolving `.first`. Selection happens before submit, so the whole matrix is free. The transport's own refusal diagnostic read the live menu back as `Omni 1.1 Flash / Veo 3.1 - Lite / Fast / Quality`, independently corroborating the fixture. Four items are recorded as NOT verified rather than omitted: the rename *direction* [the `Omni Flash` baseline is a different account, locale and date], an actual `Omni ... [Lower Priority]` entry [Flow has never offered one], a full credit-spending generation on omni-flash, and #539's absence question, which stays open.) · previous: [LIVE_VERIFICATION_v0.62.0](LIVE_VERIFICATION_v0.62.0.md) (**#595 `auto` ≡ `classic` for images, verified 2026-08-28 on profile `ci-probe` — an account Flow had moved to the agentic cohort the day before — at ZERO Veo credits.** With no flags and no env vars the run logged `ui_driver.ui_mode.attempt_exit_agent` → `ui_driver.bound mode=classic ui_mode=classic` and generated a real 768x1376 JPEG (exit 0); the day before, the identical command on the same account bound `auto`→`agentic` and failed. The same log independently closed **#183**: `mode_switch_trigger` and `image_mode_tab`, the selectors it reported as unfindable, both matched. #591 was proven against the real 500-row catalog — **0** occurrences of the string `"None"`, 31 proper JSON `null`s, over a catalog holding 119 NULL-bearing rows. #592 shows exactly one `client.account_locale_cached` per command. Three items are recorded as NOT verified rather than omitted: the exit-28 abort on a *pinned* agentic account, the #597 batch inter-prompt guard, and any fresh announcement modal — the last two because all three accounts have already acked the current changelog, so no modal can be raised until Google ships the next one.) · previous: [LIVE_VERIFICATION_v0.61.0](LIVE_VERIFICATION_v0.61.0.md) (**#539 video-model refusal + #586 image-model refusal and server-side attribution, verified 2026-08-26/27 on profile `denon82`, ONE Veo generation total** — the video fix was proven by a **zero-credit A/B against the stashed pre-fix source running on live Flow**: the old code returned SELECTED for `veo-lite-lp`, a model Flow does not offer to this account, and for a deliberately ambiguous selector matching 3 entries; the new code refuses both with exit 18 naming what Flow offered. Model selection happens before submit, so refusals cost nothing and the A/B was free. The happy path still generates: `--model omni-flash` → exit 0, a real 2.2 MB `ftypisom` mp4, catalog recording `omni_flash`. Two items are recorded as NOT verified rather than omitted: three of #584's four navigation-settle sites were never exercised [no bearer refresh occurred in these runs], and #582's canary self-re-exec has its first real exercise tonight. Also falsified: #539's recorded note that the video picker uses a different trigger — the two constants are byte-identical strings, and the repeated empty menu captures were the capture's own fault.) · previous: [LIVE_VERIFICATION_v0.60.0](LIVE_VERIFICATION_v0.60.0.md)
 **"Was the playwright upper bound raised, and on what evidence?"** → [LIVE_VERIFICATION_playwright_1.61](LIVE_VERIFICATION_playwright_1.61.md) (**`>=1.59.0,<1.60.0` → `>=1.61.0,<1.62.0` verified 2026-08-05, 1 Imagen + 1 Veo credit** — the 2026-08-03 regression that motivated the bound does NOT reproduce on 1.61.0: a live `i2v` drove the full chain with `image_uploaded status=200` → `frame_attached` → `generate_captured status=200` with `startImage` parsed, where **1.62.0 hung silently at exactly that upload step**; live `i2i` local-ref attach passed outright [96.7s]. **1.62.0 stays excluded** — never root-caused. Also found, A/B-proven pre-existing on BOTH 1.59.0 and 1.61.0: Flow dropped the duration-tab UI, so **`--duration` is currently broken for i2v** — `UiSelectorDriftError` fires correctly [refusing rather than silently accepting Flow's default, #288] but the selector needs re-deriving; that is why the i2v proof was driven via the CLI without `--duration`, and Flow's own server-side `PUBLIC_ERROR_VIDEO_GENERATION_TIMED_OUT` means no finished mp4 is claimed).
 **"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)

gflow_cli-0.64.0/docs/LIVE_VERIFICATION_v0.64.0.md

@@ -0,0 +1,112 @@
+# Live verification — v0.64.0
+
+> Evidence for [#626](https://github.com/ffroliva/gflow-cli/issues/626): lifting the
+> `omni-flash` i2v END-frame guard. The paid surface under test is
+> `gflow video i2v START PROMPT --model omni-flash --end-frame END`, which was rejected
+> pre-submit with exit 17 before this release.
+
+## Environment
+
+- Date: 2026-09-02
+- gflow-cli version: 0.63.0 → 0.64.0 (branch `feature/omni-flash-end-frame-626`)
+- Python: 3.13 local; CI matrix 3.11 / 3.12 / 3.13
+- Chrome: headed, real-Chrome strategy (`--browser chrome` profile)
+- OS: Windows 11
+- Profiles: `ffroliva`, `denon82` (two distinct Google accounts)
+
+---
+
+## Part A — Credit-free wire evidence (route-abort)
+
+`scripts/dev/capture_i2v_intercept_submit.py` binds Start + End through the production
+helpers, installs `page.route(..., abort)` on the submit XHR, clicks submit, and inspects the
+request the browser *tried* to send. The request never reaches Veo, so **zero credits**.
+
+| # | Profile | Account | Captured route | startImage | endImage |
+|---|---|---|---|---|---|
+| A1 | `ffroliva` | A | `video:batchAsyncGenerateVideoStartAndEndImage` | `35104644` | `1160c1c5` |
+| A2 | `denon82` | B | `video:batchAsyncGenerateVideoStartAndEndImage` | `3dbe6f2f` | `d8fa8761` |
+
+Two distinct Google accounts produced the identical route with both images non-null, which
+rules out a single-account artifact and a visibly staged rollout. This is the same probe and
+methodology that re-enabled omni-flash START-frame i2v on 2026-08-03.
+
+Artifacts: `tmp/i2v_626/evidence.json`, `tmp/i2v_626_denon82/evidence.json`.
+
+---
+
+## Part B — Paid live generations
+
+### B1 — omni-flash + start + end frame, `--duration 4` — ✅ VERIFIED
+
+```bash
+gflow video i2v <start>.jpg "she rises from the chair and turns toward the window, \
+    warm afternoon light" --model omni-flash --end-frame <end>.jpg \
+    --duration 4 --aspect 9:16 --profile ffroliva
+```
+
+Five-layer verification ledger:
+
+| Layer | Evidence |
+|---|---|
+| 1 · Exit code | `0` |
+| 2 · Wire route | `POST .../video:batchAsyncGenerateVideoStartAndEndImage` → HTTP 200, `startImage=a49791a4`, `endImage=06373fa6`, `referenceCount=0` |
+| 3 · Flow status | `MEDIA_GENERATION_STATUS_SUCCESSFUL` (`poll_terminal`), media `2dba1401-f2e0-48da-917c-5189b1aa42b2` |
+| 4 · Artifact | 2 465 096 B mp4; `ffprobe`: h264 + aac, 720×1280 (9:16 portrait), **duration 4.01 s** — matches `--duration 4` |
+| 5 · Semantic | **First frame of the output is the start image; last frame is the END image.** Extracted with `ffmpeg -sseof -0.1`; visually confirmed as two different subjects. This is the layer that proves the end frame was *used*, not merely accepted. |
+
+Layer 5 is the one that matters for this change. A run that bound the end frame but ignored it
+would still pass layers 1–4.
+
+The new post-submit route backstop (`_assert_i2v_route`) ran on this generation and correctly
+did **not** fire — the route matched the frames the request carried.
+
+### B2 — omni-flash + start + end frame, `--duration 10` — ⚠️ SUBMIT VERIFIED, RENDER UNCONFIRMED
+
+Same command with `--duration 10`. This is the largest-payload combination and had never been
+exercised end-to-end on this model.
+
+| Layer | Evidence |
+|---|---|
+| 1 · Duration selection | `duration_tab` matched `[role='tab']:text-is('10s')`; `duration_set seconds=10` |
+| 2 · Wire route | `POST .../video:batchAsyncGenerateVideoStartAndEndImage` → HTTP 200, `startImage=76f57d19`, `endImage=eb7d1627` |
+| 3 · Flow status | ❌ **not obtained** — `batchCheckAsyncVideoGenerationStatus` returned HTTP 401 mid-poll (`AuthExpiredError`) |
+| 4–5 | not reached |
+
+A single retry failed earlier still, at `project.create` with HTTP 401, before any submit — so
+no second credit was spent. `gflow auth status` verified the Flow session as valid
+immediately before and after both attempts.
+
+**This is [#561](https://github.com/ffroliva/gflow-cli/issues/561)**, a pre-existing defect
+(browser-context 401 while the on-disk Flow session is valid), not a regression from this
+change. Verification was stopped rather than spending further credits chasing an environmental
+fault.
+
+**Honest status:** `--duration 10` + end frame is verified as far as *submit* — Flow accepted
+the 10-second first+last request on the correct route with both images bound. Whether the
+render completes is **unconfirmed**. Per the project's rule, that is LIKELY, not CONFIRMED.
+It carries low residual risk: B1 proved the render path for this model/route, and duration
+selection is an independent, already-verified control (`supports_duration`, #451/#288).
+
+---
+
+## Offline gates (same tree)
+
+| Gate | Result |
+|---|---|
+| `check_repo_hygiene.py` | 858 files, no violations |
+| `check_doc_links.py` | all links resolved across 29 files |
+| `check_website_docs_pii.py` | no private identifiers, 25 files |
+| `generate_website_docs.py --check` | mirror in sync (20 files), nav complete |
+| `ruff check src tests` | all checks passed |
+| `ruff format --check src tests` | 414 files already formatted |
+| `pyright src` | 78 errors — **byte-identical count on clean `develop`**; local stub skew, zero new |
+| `pytest` (api/cli/mcp/chain/errors) | 2065 passed, 3 skipped |
+
+---
+
+## Verdict
+
+The feature is **live-verified** for the case the issue reported and for the case a user is
+most likely to hit. The 10-second variant is submit-verified with its render unconfirmed for
+an unrelated, already-tracked auth defect — recorded here rather than papered over.

{gflow_cli-0.63.0 → gflow_cli-0.64.0}/docs/MCP.md

@@ -83,7 +83,7 @@ The server registers three protocol surfaces:
 
 ### Tools (Executable actions)
 * `gflow_generate_image(prompt, model, aspect, count, seed, reference_images, tools, profile, project, project_name, instructions, ui_mode, output, wait)`: Triggers text-to-image / image-to-image (Imagen / Nano Banana). `instructions` is an optional list of ephemeral agent-instruction strings (agentic cohort only). `reference_images` switches to i2i and accepts **either a local file path or a generated image's Flow media UUID**. A UUID reference is attached by **selecting the already-existing asset in Flow's reference picker — no duplicate copy is uploaded** (locating the tile by the media id in its thumbnail URL, and searching the recorded display name to surface it when needed); gflow falls back to uploading the asset's on-disk local file only when it can't be located in place (e.g. it lives in a different project's picker). `project` generates into an existing Flow project id (mirrors CLI `--project`) — pass the reference's project to keep it selectable in place. `ui_mode` selects the Flow UI arm (`auto`/`classic`/`agentic`, mirroring CLI `--ui-mode`, matched case-insensitively). Since [#595](https://github.com/ffroliva/gflow-cli/issues/595) `auto` means "no arm was asked for" and **resolves to `classic`** — the arm that can satisfy an image request — so an account in Flow's agentic cohort aborts pre-submit (exit-28 equivalent envelope, zero credits) instead of failing mid-run with selector drift or video bytes; the agentic arm is bound only when named. Passing `instructions` forces `agentic` automatically, so `ui_mode="classic"` + `instructions` is a hard conflict rather than a silent drop. An unknown value returns a 400 problem-details envelope. See [CONFIGURATION § GFLOW_CLI_UI_MODE](CONFIGURATION.md#gflow_cli_ui_mode).
-* `gflow_generate_video(prompt, mode, aspect, initial_frame, end_frame, reference_images, model, duration, count, tools, profile, project, project_name, ui_mode, output, wait)`: Triggers vertical or landscape video generation (Veo). `mode` is `t2v`/`i2v`/`r2v`; `model` (`veo_lite`/`veo_fast`/`veo_quality`/`omni_flash`, aliases accepted), `duration` (seconds), and `count` mirror the CLI `gflow video` flags — an omitted `model` lets the transport apply its i2v veo-lite default (issue #125), and `omni_flash` is rejected for i2v-with-frames; `i2v` requires `initial_frame`, `r2v` requires `reference_images`; `project` generates into an existing Flow project id (mirrors CLI `--project`). `initial_frame`, `end_frame`, and `reference_images` each accept **either a local file path or the Flow image UUID of a generated asset** — pass a generated image's id straight in to chain image→video, and gflow attaches it for you. Since v0.58.0 (#529) the CLI and MCP surfaces are unified for i2v frames: the UUID keeps its identity and is enriched with the catalog's recorded display name plus an integrity-verified local fallback, so the transport prefers **selecting the exact asset in the project's media picker** (no duplicate upload) and re-uploads the recorded local file only when the tile is unreachable — and only if its byte count/SHA-256 still match. A UUID that isn't in your local asset catalog is rejected up front with a clear "Reference Not Found" error; a catalogued asset with neither a display name nor a verified local file gives a "Reference Not Usable" error (re-generate it or pass a local path). `r2v` UUID refs are resolved to the recorded local file for upload. `ui_mode` selects the Flow UI arm (#299 PR-A, mirroring CLI `--ui-mode`) and **applies to every mode of this tool, including `r2v`** — unlike the CLI, where `video r2v`/`chain` have no flag and follow the env-only path. Video generation has **only a classic driver**, so `auto` ≡ `classic`: both verify the classic editor pre-submit and abort before spending credits if it is unreachable. `ui_mode="agentic"` is rejected with a 400 problem-details envelope, because no agentic video driver exists yet. Values are matched case-insensitively. (MCP tools return envelopes, never process exit codes — the CLI equivalents of these aborts are exit 28 and exit 2 respectively.) See [CONFIGURATION § GFLOW_CLI_UI_MODE](CONFIGURATION.md#gflow_cli_ui_mode).
+* `gflow_generate_video(prompt, mode, aspect, initial_frame, end_frame, reference_images, model, duration, count, tools, profile, project, project_name, ui_mode, output, wait)`: Triggers vertical or landscape video generation (Veo). `mode` is `t2v`/`i2v`/`r2v`; `model` (`veo_lite`/`veo_fast`/`veo_quality`/`omni_flash`, aliases accepted), `duration` (seconds), and `count` mirror the CLI `gflow video` flags — an omitted `model` lets the transport apply its i2v veo-lite default (issue #125), and every model — `omni_flash` included — accepts i2v with a start frame and with an end frame (wire-verified 2026-09-02, issue #626); `i2v` requires `initial_frame`, `r2v` requires `reference_images`; `project` generates into an existing Flow project id (mirrors CLI `--project`). `initial_frame`, `end_frame`, and `reference_images` each accept **either a local file path or the Flow image UUID of a generated asset** — pass a generated image's id straight in to chain image→video, and gflow attaches it for you. Since v0.58.0 (#529) the CLI and MCP surfaces are unified for i2v frames: the UUID keeps its identity and is enriched with the catalog's recorded display name plus an integrity-verified local fallback, so the transport prefers **selecting the exact asset in the project's media picker** (no duplicate upload) and re-uploads the recorded local file only when the tile is unreachable — and only if its byte count/SHA-256 still match. A UUID that isn't in your local asset catalog is rejected up front with a clear "Reference Not Found" error; a catalogued asset with neither a display name nor a verified local file gives a "Reference Not Usable" error (re-generate it or pass a local path). `r2v` UUID refs are resolved to the recorded local file for upload. `ui_mode` selects the Flow UI arm (#299 PR-A, mirroring CLI `--ui-mode`) and **applies to every mode of this tool, including `r2v`** — unlike the CLI, where `video r2v`/`chain` have no flag and follow the env-only path. Video generation has **only a classic driver**, so `auto` ≡ `classic`: both verify the classic editor pre-submit and abort before spending credits if it is unreachable. `ui_mode="agentic"` is rejected with a 400 problem-details envelope, because no agentic video driver exists yet. Values are matched case-insensitively. (MCP tools return envelopes, never process exit codes — the CLI equivalents of these aborts are exit 28 and exit 2 respectively.) See [CONFIGURATION § GFLOW_CLI_UI_MODE](CONFIGURATION.md#gflow_cli_ui_mode).
 * `gflow_auth_status(profile)`: Credit-free, non-interactive Flow session probe (#497) — wraps the same fail-closed `verify_flow_profile` check as `gflow auth status`. Returns `{"status": "authenticated", "profile", "user_email"}` or a problem-details error with a `remediation_hint`; a `verification_error` outcome means a network/endpoint problem, which re-login does not fix. Call it before a generation tool to fail fast on dead auth (the queue is async — without it, an auth failure surfaces only later from the daemon). Login/logout remain CLI-only (genuinely interactive).
 * `gflow_list_projects(profile, limit, offset)`: Queries the SQLite catalog for recent generation folders, paginated — the response carries `count` (rows in this page), `offset`, `has_more`, and `next_offset` (pass it back as `offset` for the next page; `null` on the last page).
 * `gflow_list_tools()`: Lists the prompt tools (name/title/description/category) accepted by the generate tools' `tools` param.

{gflow_cli-0.63.0 → gflow_cli-0.64.0}/docs/PROJECT_STATUS.md

@@ -4,6 +4,49 @@
 
 ## Current release
 
+**v0.64.0 — alpha.** **`gflow video i2v --model omni-flash --end-frame` — first+last
+interpolation on Omni 1.1 Flash ([#626](https://github.com/ffroliva/gflow-cli/issues/626)).**
+Google shipped first-and-last-frame generation for Omni 1.1 Flash, so the guard that
+rejected that combination with exit 17 was enforcing a fact that had expired. omni-flash is
+also the only model exposing `--duration`, so this is the one route to a 10-second first+last
+interpolation.
+
+The interesting part is what replaced the guard. gflow used to decide which models could
+carry an end frame from a hand-maintained mirror of Google's support matrix — which went
+stale silently, and could have gone stale in the permissive direction just as easily. That
+table is **deleted**, not corrected. gflow now checks the route Flow *actually* used after
+submit: a run carrying an end frame that comes back on `batchAsyncGenerateVideoStartImage` —
+Flow dropping the frame and billing a clip that was never interpolated — fails with
+`WireFormatError` rather than being reported as success. That catches a partial or staged
+rollback on any account, at any time, with nobody re-reading a support page. It also closes a
+narrower hole the old backstop had: it only fired when Flow dropped *every* frame to the T2V
+route.
+
+**Live-verified on two accounts at zero credits plus one paid render.** The route-abort probe
+fired `batchAsyncGenerateVideoStartAndEndImage` with both images non-null on two distinct
+Google accounts, ruling out a staged rollout. The decisive layer is semantic, not structural:
+the paid 4s clip's **last frame is the supplied end image** and its first frame is the start
+image — the only check that distinguishes "Flow used the end frame" from "Flow accepted and
+ignored it", since exit code, HTTP status and file properties pass either way. Recorded as
+*not* verified rather than omitted: `--duration 10` + end frame is submit-verified only, its
+status poll having hit the pre-existing 401 of
+[#561](https://github.com/ffroliva/gflow-cli/issues/561). See
+[LIVE_VERIFICATION_v0.64.0.md](LIVE_VERIFICATION_v0.64.0.md).
+
+**Breaking:** scripts branching on exit 17 for `omni-flash` + `--end-frame` now see success.
+Exit 17 is unchanged for `gflow video chain --model omni-flash`, still rejected because
+chain-scale seeded i2v remains unverified.
+
+Also in this release, contributor-facing: **MCP↔CLI parity became a duty of every pipeline
+phase.** This very change drifted — `mcp/tools.py` and `docs/MCP.md` went on telling agents
+`omni_flash` was rejected for i2v-with-frames — through green lint, types, the full suite and
+`test_cli_parity.py`, which is command-level and cannot see a docstring that lies. Each skill
+now owns a slice (`scenario` D13, `plan` task 6, `pr-council-review` D15, `check` step 1b,
+`doc-review` blocking on a *false* MCP claim); automating the mechanically checkable part is
+tracked in [#628](https://github.com/ffroliva/gflow-cli/issues/628).
+
+<details><summary>v0.63.0 — <code>gflow video extend</code>, past Flow's 8-second ceiling</summary>
+
 **v0.63.0 — alpha.** **`gflow video extend` — continue a clip past Flow's 8-second ceiling.**
 Veo caps a single generation at 8 seconds. `extend` chains server-side
 continuations: each segment is seeded from the *previous segment's* media rather
@@ -34,6 +77,8 @@ Also in this release: `CLAUDE.md` now `@`-imports `AGENTS.md` so the project's
 agent rules load rather than being politely requested, and `AGENTS.md` opens with
 a Skill Routing table making the `/gflow:` lifecycle the default workflow.
 
+</details>
+
 > **Releases v0.60.0 – v0.62.1 are not expanded below.** This file drifted for
 > five releases; rather than reconstruct their summaries after the fact, they are
 > recorded accurately in [CHANGELOG.md](../CHANGELOG.md) and in their own
@@ -398,6 +443,7 @@ reporter-verified e2e on macOS).
 | `gflow scene` — Add Clip / Scenes compose + credit-free server-side extended video (`runVideoFxConcatenation`) | ✅ done (v0.12.0) |
 | `gflow video chain` — last-frame I2V chaining from a JSONL manifest (`--dry-run`/`--max-links`/`--resume-from`) | ✅ done (v0.12.0) |
 | `gflow video extend` — chained server-side Veo continuations past the 8s ceiling (tier-resolved model, whole-run balance pre-flight, resumable) | ✅ done (v0.63.0) |
+| `i2v --model omni-flash --end-frame` — first+last interpolation on Omni 1.1 Flash; static capability table replaced by a post-submit route check that fails a dropped end frame (#626) | ✅ done (v0.64.0) |
 | Create-project generation works under Flow's Agent docked chat panel | ✅ done (v0.12.0) |
 | Video status poll raises `AuthExpiredError` (exit 3) on mid-workflow 401 (#156) + Docker `/dev/shm` hardening | ✅ done (v0.15.1) |
 | Locale-free resource-picker include selectors — entity attach works on every account language (#170) | ✅ done (v0.16.0) |

{gflow_cli-0.63.0 → gflow_cli-0.64.0}/docs/USAGE.md

@@ -514,20 +514,25 @@ All prompts in a batch share one Flow project. The editor is opened once and sta
 > `t2v` and `i2v` (not `r2v`) additionally take `-o, --output PATH` (explicit file destination).
 > The mp4 lands at `<output_file>` or `<out-dir>/<media_id>.mp4`.
 >
-> **`i2v` model rules (issue #125, re-verified 2026-08-03):** every model —
-> `omni-flash` included — supports **start-frame** i2v; the **default is
-> `veo-lite`** (not Flow's UI default). `--model omni-flash` unlocks
-> `--duration 10` for i2v. The **end frame is narrower**: `--end-frame`
-> (first+last interpolation) requires a Veo 3.1 model — Flow's official
-> support matrix lists first+last as "coming soon" for Omni Flash, and gflow
-> rejects that combination up front (exit 17).
+> **`i2v` model rules (issues #125 / #626):** every model — `omni-flash`
+> included — supports i2v with a **start frame** and with an **end frame**
+> (`--end-frame`, first+last interpolation). The **default is `veo-lite`** (not
+> Flow's UI default) because it is the cheapest, not because of any capability
+> edge. `--model omni-flash` additionally unlocks `--duration 10` for i2v.
 > History: omni-flash was excluded from i2v entirely after a 2026-05-30 wire
 > capture showed Flow silently dropping the frames and billing the run as
 > text-to-video. A 2026-08-03 route-aborted re-capture
 > (`scripts/dev/capture_i2v_intercept_submit.py --model omni-flash
 > --start-only`) proved Flow now routes omni + start frame to
 > `batchAsyncGenerateVideoStartImage` with the frame bound, and a live x1
-> 10s generation confirmed the output interpolates from the start frame.
+> 10s generation confirmed the output interpolates from the start frame. The
+> end frame followed once Flow shipped first+last for Omni 1.1 Flash: on
+> 2026-09-02 the same probe without `--start-only` captured
+> `batchAsyncGenerateVideoStartAndEndImage` with both `startImage` and
+> `endImage` non-null, reproduced on two accounts at zero credits (#626).
+> Instead of a static per-model table, gflow now checks the route Flow
+> **actually used** after submit: a run whose end frame was silently dropped
+> fails loudly rather than reporting a clip that ignored it as a success.
 
 ## `gflow video t2v`
 
@@ -1603,7 +1608,7 @@ shell scripts can branch on the failure mode without parsing stderr.
 | `14` | `AuthBrowserRejectedError` | Google rejected the login browser             | `gflow auth login --browser chrome`                        |
 | `15` | `BrowserSessionClosedError` | The automation browser window was closed mid-operation | Re-run; keep the browser window open until the command finishes |
 | `16` | `DataStoreError`      | Local database cannot be opened, a migration failed, or the DB schema is newer than the installed gflow-cli | See below                                  |
-| `17` | `ModelModeIncompatibilityError` | The chosen video model can't do the requested mode (e.g. `--model omni-flash` with `--end-frame`, or `omni-flash` for `chain` — issue #125) | omni-flash does start-frame `i2v` only: drop `--end-frame`, or use a Veo 3.1 model (`veo-lite` / `veo-fast` / `veo-quality` / `veo-lite-lp`) for first+last and for `chain` |
+| `17` | `ModelModeIncompatibilityError` | The chosen video model can't do the requested mode — today that is `omni-flash` for `chain` (issues #125, #626) | Use a Veo 3.1 model (`veo-lite` / `veo-fast` / `veo-quality` / `veo-lite-lp`) for `chain`. Single-clip `i2v` with omni-flash, `--end-frame` included, is accepted |
 | `18` | `VideoModelSelectionError` | gflow could not select the requested video model in Flow's editor for an `i2v` run (model-picker option not found) | Usually transient — retry; if it persists, Flow's model-picker UI changed (report referencing #125) |
 | `19` | `SceneConcatError`    | Server-side scene render/concat failed (`gflow scene --output`) | Retry; the recorded compose survives, so re-render is safe |
 | `20` | `FrameExtractionError` | Could not extract the last frame for a video chain link | Check the source video downloaded intact; retry the link  |

{gflow_cli-0.63.0 → gflow_cli-0.64.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.63.0"
+version = "0.64.0"
 description = "Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal."
 readme = "README.md"
 license = { file = "LICENSE" }

{gflow_cli-0.63.0 → gflow_cli-0.64.0}/skills/check/SKILL.md

@@ -31,6 +31,82 @@ The last check fails on either half of the published-site contract:
   `website/mkdocs.yml` points at it, so it is live but unreachable. Add the
   entry under the right nav section.
 
+**1b. Surface blast radius — MCP↔CLI parity and the other mirrors** (read-only; MANDATORY whenever the change touches a CLI command, option, flag help text, exit code, or user-facing error string)
+
+`tests/mcp/test_cli_parity.py` is a **command-level** gate only: it asserts every CLI *leaf*
+has a mapped MCP tool or a stated exemption. It is green while a new `--option` goes
+unmirrored, and green while an MCP docstring asserts a restriction the CLI no longer has.
+That semantic drift is invisible to every automated gate in this file, so it is checked here
+by hand — deliberately, because the alternative is shipping it.
+
+```bash
+PYTHONUTF8=1 uv run python -m pytest -q tests/mcp/test_cli_parity.py tests/mcp/test_server.py
+```
+
+Then enumerate the blast radius. For the CLI symbol(s) you changed (option name, model
+alias, exit code, capability), grep the whole repo and confirm **every** hit is either
+updated or still true:
+
+```bash
+# substitute the flag / alias / capability word you changed
+grep -rn --exclude-dir=.git --exclude-dir=__pycache__ --exclude-dir=tmp "<your-symbol>" \
+    src/gflow_cli/mcp/ docs/ website/docs/ README.md KNOWN_ISSUES.md CHANGELOG.md skills/
+```
+
+Six axes, in blast-radius order. Tick each or state why it does not apply — "I did not touch
+a CLI surface" is a valid answer for the whole step; silence is not.
+
+**A. Execution paths — a request is built in THREE places, not one.**
+
+| Hop | File | Fails as |
+|---|---|---|
+| CLI | `cli_video.py` / `cli_image.py` dataclass → request | option parsed but never passed |
+| MCP direct | `mcp/tools.py` tool signature → payload dict | param accepted, dropped before the queue |
+| MCP queued | `mcp/tools.py` payload keys → `worker/codec.py` decode → request | **silent no-op** — accepted, queued, never read |
+
+The third hop is the dangerous one: the payload key the tool writes and the key the codec
+reads are matched by string, so a mismatch type-checks, lints, and passes tests while doing
+nothing. This has shipped before — a dead `output` param the queue never read survived until
+a pre-release audit (#495). Verify the key names literally line up end to end:
+
+```bash
+grep -n "<param>" src/gflow_cli/mcp/tools.py src/gflow_cli/worker/codec.py
+```
+
+**B. MCP surface truth** — `mcp/tools.py` tool signature **and** every behavioural claim in
+its docstring; `docs/MCP.md` parameter prose. `tests/mcp/test_cli_parity.py`'s
+`CLI_TO_MCP` / `_MCP_EXEMPT` only when adding a NEW leaf.
+
+**C. Agent-facing surfaces** — read by Codex / Cursor / Aider, not just by us, and covered by
+no test at all: `skills/gflow-cli/SKILL.md`, the `AGENTS.md` "Command surface" bullet,
+`README.md`, `docs/INDEX.md`.
+
+**D. Error and exit-code surface** — `errors.py` `_default_remediation` **and** the class
+docstring, `EXIT_CODE_MAP`, and the exit-code table in `docs/USAGE.md`. When a raise site is
+deleted, re-derive what the remaining sites are: a remediation string that still describes a
+removed case actively misleads.
+
+```bash
+grep -rn "raise <ErrorClass>" src/gflow_cli/   # must match what the docs table claims
+```
+
+**E. Declarative / template surfaces** — defaults baked into files users copy:
+`cli_movie.py`'s manifest template, `movie_manifest.py`, `chain_manifest.py`,
+`.env.template` for any env var, and the capability-reporting commands `gflow models` and
+`gflow doctor`.
+
+**F. Docs + published mirror** — `docs/USAGE.md` command section, `website/docs/`
+(regenerate; step 1 catches staleness but never wrongness), `KNOWN_ISSUES.md` claims about
+the surface, `CHANGELOG.md` under `### Changed` whenever behaviour a script could branch on
+moves.
+
+**Why this step exists.** In #626 the CLI stopped rejecting `omni-flash --end-frame` while
+`mcp/tools.py` and `docs/MCP.md` went on telling agents the combination was rejected. Lint,
+types, the full 2065-test suite, and the parity gate were green throughout, because none of
+them can see a docstring that lies. The AGENTS.md prose saying "keep them in sync" had been
+there the whole time and did not fire — the project's own lesson, again: wire the rule, or it
+is a wish.
+
 **2. Auto-fix lint and formatting** (rewrites files in place)
 
 ```bash
@@ -82,6 +158,7 @@ uv run python -m pytest -q --cov=gflow_cli --cov-fail-under=80
 ## Output
 
 - List files changed by the fix pass (empty = nothing needed fixing)
+- **Step 1b blast radius — the mirror table, each row ticked or explicitly marked N/A. "I did not touch a CLI surface" is a valid answer; silence is not.**
 - **Step 4 verify result — `ruff check` + `ruff format --check` both clean (this is the CI gate; a non-zero here is a blocking finding, not a warning)**
 - All pyright errors with `file:line` references
 - Pytest summary line and coverage percentage

{gflow_cli-0.63.0 → gflow_cli-0.64.0}/skills/doc-review/SKILL.md

@@ -175,6 +175,22 @@ assign a coverage grade: **D0** (nothing) · **D1** (docstrings only) · **D2**
 be **D3+**; a new env var or command at **D0/D1** is a release-blocking finding.
 List every surface below D3 with its grade and the doc it needs.
 
+**Every CLI surface in that list has an MCP twin — grade both.** `docs/MCP.md` and the
+`mcp/tools.py` docstrings are documentation for an *agent* audience, and they rot the same
+way, silently, with a green test suite. Two failure shapes, both release-blocking:
+
+- **Absent:** a CLI flag shipped and mirrored in code, but `docs/MCP.md` never mentions the
+  MCP parameter. The D0–D4 grading above applies unchanged.
+- **False:** the tool docstring or `docs/MCP.md` still asserts a restriction the code dropped.
+  This is worse than absent — it tells agents not to attempt something that now works, and no
+  link check, lint, or parity test can see it. Grade a false claim as a blocker regardless of
+  how well-documented the surface otherwise is.
+
+```bash
+# Cross-check every behavioural claim about models/flags in the MCP surface against the code.
+grep -rn "rejected\|not supported\|requires a\|only\|coming soon" src/gflow_cli/mcp/tools.py docs/MCP.md
+```
+
 ---
 
 ## 5 · Skill files (`skills/` + `.claude/commands/gflow/`)

{gflow_cli-0.63.0 → gflow_cli-0.64.0}/skills/issue-assessment/SKILL.md

@@ -65,6 +65,15 @@ Disprove parts of the reporter's framing where the code says otherwise (e.g.
 `browser_engine: playwright` is the engine axis, not the channel) — a precise
 correction is more useful than agreement.
 
+**Name the affected SURFACES, not just the affected code.** A reporter hits one
+surface; the defect usually spans both. gflow ships most capabilities twice — CLI
+command and MCP tool — so state explicitly whether the issue reproduces on the CLI,
+on the MCP tool, or on both, and whether a fix in one automatically fixes the other
+(it does when both route through the same transport; it does not when the MCP path
+carries its own params through `worker/codec.py`). Getting this wrong scopes the
+whole downstream fix wrong: a "CLI bug" that is really a shared-transport bug leaves
+MCP users broken after the issue is closed.
+
 ### 3. Classify — exactly one verdict
 
 | Verdict | Meaning |

{gflow_cli-0.63.0 → gflow_cli-0.64.0}/skills/live-verify/SKILL.md

@@ -73,6 +73,14 @@ path is default-in-scope; skipping this gate requires a named reason, not silenc
    - Which command(s) does the change touch?
    - Which variations actually exercise it? (E.g. for a mention-resolution fix: a character
      mention, a media mention, an ambiguous-name case, an unresolvable name.)
+   - **Which surface(s)?** A capability that ships as both a CLI command and an MCP tool has
+     **two live paths, not one** — and the MCP queued path runs different code
+     (`mcp/tools.py` → queue payload → `worker/codec.py` → request → daemon owns download and
+     recording). A CLI run does not exercise it. Decide per change whether the MCP path needs
+     its own live run, and if you skip it, say so with a reason. The cheap version is usually
+     enough: one queued MCP call on a credit-free operation proves the payload keys round-trip,
+     which is the hop that silently no-ops (#495). Offline parity tests cannot see this —
+     they never build a real payload and decode it.
 
 **2. Check the cost tier for each variation — the tier follows the operation, not the
    command family:**

{gflow_cli-0.63.0 → gflow_cli-0.64.0}/skills/plan/SKILL.md

@@ -91,10 +91,15 @@ Skip any question already answered by predict/scenario output or the feature des
 | 3 | Core implementation | Domain objects / value types / parsers. |
 | 4 | Transport / API layer | `FlowApiClient` or `UiAutomationTransport` changes. |
 | 5 | CLI surface | `cli_*.py` + Click commands + `--help` text. |
-| 6 | Docs update | `USAGE.md`, `CONFIGURATION.md` (new env vars), `KNOWN_ISSUES.md` if relevant. |
-| 7 | Full gates + release prep | `/gflow:check` green; CHANGELOG updated. |
-
-Adjust: not every task applies to every feature. Merge or split tasks as the scope demands.
+| 6 | **MCP surface mirror** | **Never optional when task 5 exists.** `mcp/tools.py` signature + docstring claims, the queued-path payload keys in `worker/codec.py`, `tests/mcp/test_cli_parity.py` for a new leaf. |
+| 7 | Docs update | `USAGE.md`, `CONFIGURATION.md` (new env vars), `docs/MCP.md`, `KNOWN_ISSUES.md` if relevant. |
+| 8 | Full gates + release prep | `/gflow:check` green; CHANGELOG updated. |
+
+Adjust: not every task applies to every feature. Merge or split tasks as the scope demands —
+**except task 6.** If the plan has a task 5, it has a task 6, because gflow ships every
+capability twice and the automated gates cannot see the two drifting apart. A plan that
+touches the CLI and has no MCP task is incomplete, not lean. The mirror axes are enumerated
+once, in `skills/check/SKILL.md` step 1b; cite them, do not copy them.
 
 ### Phase 4 — Draft the plan and show it to the user