gflow-cli 0.10.0__tar.gz → 0.11.0__tar.gz

gflow_cli-0.11.0/.claude/commands/gflow/release.md

@@ -0,0 +1,241 @@
+---
+description: Cut a new gflow-cli release — bump version, update CHANGELOG, tag, push, and back-merge.
+---
+
+# `/gflow:release` — Cut a new release
+
+Follow this sequence verbatim. Every step matters.
+
+> **Branch-protection note:** `main` blocks direct pushes. The release commit travels
+> via a `chore/release-vX.Y.Z` branch PR. The signed tag is pushed independently
+> (tag pushes bypass branch protection and trigger the CI release workflow immediately).
+>
+> **Source-branch note (read first):** `develop` is the integration branch — it carries
+> ALL unreleased work and `main` usually lags it. The release branch is cut from
+> **`develop`**, NOT `main`. The PR `chore/release-vX.Y.Z → main` then brings the full
+> integration history onto `main`. Do not expect the work to already be on `main`.
+
+## Inputs
+
+Ask the user (if not already provided):
+
+1. **Version** — the new version (e.g. `0.4.0`, `0.4.0a3`, `1.0.0rc1`). Use PEP 440 prerelease suffixes (`aN`, `bN`, `rcN`). If they don't know, run `/gflow:changelog` first and propose the next bump (PATCH for fixes only, MINOR for new features, MAJOR for breaks).
+2. **Pre-release?** — prerelease versions stay marked as GitHub prereleases. Only the user can say when a release line is ready for the stable tag.
+
+---
+
+## Sequence
+
+**1. Review what's queued.**
+
+Run `/gflow:changelog` — confirm the `[Unreleased]` block is non-empty and accurate before proceeding.
+
+**2. Verify (or triage) a clean working tree.**
+
+```bash
+git status --short
+```
+
+If empty, continue. If not, **triage before aborting** — do not blindly stop:
+
+- **Auto-injected boilerplate** (e.g. a context-mode routing block appended to
+  `CLAUDE.md` by an MCP plugin's SessionStart hook): this is plugin-injected, not
+  project content — `git restore` it. Confirm with the user if unsure.
+- **Build/temp artifacts** (e.g. a stray `tmp*.tar.gz` sdist at repo root): delete them.
+- **Genuine uncommitted work:** STOP and tell the user to commit or stash on the
+  appropriate branch (never commit straight to `develop`).
+
+The tree must be clean before you create the release branch.
+
+**3. Verify `develop` is the release source and up-to-date.**
+
+The release is cut from `develop`, NOT `main` (see Source-branch note above).
+Confirm direction explicitly — a backwards divergence means a prior back-merge was skipped.
+
+```bash
+git fetch origin
+git rev-parse --abbrev-ref HEAD                      # expect "develop"
+git rev-list --count HEAD..origin/develop            # local behind origin — expect 0
+git rev-list --count origin/main..origin/develop     # develop AHEAD of main — expect > 0 (the work to release)
+git rev-list --count origin/develop..origin/main     # main AHEAD of develop — expect 0
+```
+
+If not on `develop`: `git checkout develop && git pull origin develop`.
+If local is behind origin: `git pull origin develop`.
+**If `main` is AHEAD of `develop` (last count > 0): STOP.** A prior release skipped its
+`main → develop` back-merge — recover first (see the `release-back-merge-gap-recovery`
+memory) or the release branch will hit conflicts on `pyproject.toml` / `__init__.py` / `CHANGELOG.md`.
+
+**4. Run quality gates.**
+
+Run `/gflow:check` — all gates must pass. Abort if any fail.
+
+**5. Create a release branch off `develop`.**
+
+```bash
+git checkout develop                          # ensure the base is develop, not main
+git checkout -b chore/release-v<NEW_VERSION>
+```
+
+This branch now contains all of `develop` (⊇ `main`) plus your release prep. All
+release prep commits live here; the PR into `main` (step 14) carries the full
+integration history forward.
+
+**6. Bump version** in `pyproject.toml`:
+
+```toml
+[project]
+version = "<NEW_VERSION>"
+```
+
+**7. Bump package version** in `src/gflow_cli/__init__.py`:
+
+```python
+__version__ = "<NEW_VERSION>"
+```
+
+**8. Update version assertion tests** if present:
+
+```bash
+rg -n "__version__|<OLD_VERSION>|version assertion" tests src pyproject.toml
+```
+
+**9. Migrate CHANGELOG.**
+
+- Move all entries under `## [Unreleased]` to a new `## [<NEW_VERSION>] — YYYY-MM-DD` section.
+- Leave `## [Unreleased]` empty.
+- Update the link footer. Match the repo's existing convention — every prior entry
+  uses the `compare/vPREV...vNEW` form, so use that for the new version too (NOT the
+  `releases/tag/` form), or `/gflow:doc-review` will flag the inconsistency:
+  ```
+  [Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v<NEW_VERSION>...HEAD
+  [<NEW_VERSION>]: https://github.com/ffroliva/gflow-cli/compare/v<PREV_VERSION>...v<NEW_VERSION>
+  ```
+
+**10. Run the documentation review gate.**
+
+Run `/gflow:doc-review` — audit all version refs, INDEX completeness, evidence files, skill files, CHANGELOG footer, and memory files. Fix every **FAIL** before continuing. Fold all discovered fixes into the release prep commit.
+
+**11. Commit the release prep.**
+
+```bash
+git add pyproject.toml src/gflow_cli/__init__.py uv.lock CHANGELOG.md
+git add docs/ .claude/commands/gflow/        # include any doc-review fixes
+# doc-review version-currency fixes often also touch ROOT docs — stage them too:
+git add README.md PLAN.md KNOWN_ISSUES.md AGENTS.md llms.txt 2>/dev/null || true
+git status --short                            # review EVERYTHING staged before committing
+git commit -m "chore(release): v<NEW_VERSION>"
+```
+
+- **`uv.lock` changes** on every version bump (the editable package version is
+  pinned in the lockfile) — it is easy to forget and must ship in this commit.
+- The release-prep commit must NOT carry a `Co-Authored-By` trailer (see reminders).
+
+**12. Tag the release commit.** Use `-s` for a signed annotated tag so GitHub shows **"Verified"** AND `.github/workflows/release.yml` passes the signed-tag gate (unsigned or lightweight tags are rejected by CI).
+
+```bash
+git tag -s v<NEW_VERSION> -m "v<NEW_VERSION>"
+```
+
+Signing requirements:
+- **SSH signing (preferred):** `git config --global gpg.format ssh` + `user.signingkey` pointing at your public key.
+- **GPG:** any registered GPG key works.
+- Run `git config --global user.signingkey` to confirm a key is configured.
+
+Confirm the tag actually carries a signature (this is what CI checks):
+
+```bash
+git cat-file -p v<NEW_VERSION> | grep -c "BEGIN SSH SIGNATURE"   # expect 1 (or "BEGIN PGP SIGNATURE" for GPG)
+```
+
+> **Benign local-verify error:** `git tag -v v<NEW_VERSION>` may fail with
+> `gpg.ssh.allowedSignersFile needs to be configured`. This is a *local
+> verification-config* gap only — the tag IS validly signed and CI still passes
+> (CI greps for the signature header, above). To make local verify work once and
+> for all, create an allowed-signers file (`<your-email> ssh-rsa AAAA...`) and run
+> `git config --global gpg.ssh.allowedSignersFile <path>`. See the `release-signing`
+> memory for the exact recipe. Do NOT treat this error as a signing failure.
+
+**13. Push the tag first** (bypasses branch protection; triggers the CI release workflow immediately):
+
+> **⚠ POINT OF NO RETURN — confirm with the user before this push.** Pushing the
+> tag immediately triggers `.github/workflows/release.yml` → **PyPI publish +
+> public GitHub Release**. A pushed release tag must NOT be force-replaced (ship a
+> PATCH instead). Get an explicit go-ahead, then push.
+
+```bash
+git push origin v<NEW_VERSION>
+```
+
+CI will start building the release. Watch <https://github.com/ffroliva/gflow-cli/actions>.
+Wait for the `Release` run to report **completed / success** and confirm the GitHub
+Release published before continuing (`gh release view v<NEW_VERSION>`).
+
+**14. Push the release branch and open the PR.**
+
+```bash
+git push -u origin chore/release-v<NEW_VERSION>
+gh pr create --base main --head chore/release-v<NEW_VERSION> \
+  --title "chore(release): v<NEW_VERSION>"
+```
+
+Wait for PR CI to go green (`gh pr checks <N> --watch`), then merge with a **merge
+commit** — never squash:
+
+```bash
+gh pr merge <N> --merge --delete-branch
+```
+
+> **NEVER `--squash` this PR.** Because the branch was cut from `develop`, the PR
+> carries the entire batch of unreleased integration commits. A squash collapses
+> them into one opaque commit on `main` and destroys that history. `--merge`
+> preserves it. (The release workflow already ran from the tag push in step 13 —
+> this PR is to bring the bump commit + integration history onto `main`.)
+
+**15. Back-merge `main` into `develop`.**
+
+After the release PR is merged, bring the bump commit back to `develop` so branches stay aligned:
+
+```bash
+git checkout develop
+git pull origin develop
+git fetch origin main
+git merge origin/main --no-ff -m "chore: back-merge main (v<NEW_VERSION>) into develop"
+git push origin develop
+```
+
+If there are conflicts (rare — only if `develop` has commits that touched the same lines as the bump), resolve them, keeping `develop`'s unreleased work and `main`'s version bump.
+
+**16. Report.**
+
+Tell the user:
+- Tag push triggered `.github/workflows/release.yml`.
+- Watch <https://github.com/ffroliva/gflow-cli/actions> for the release workflow.
+- On success: PyPI publish + GitHub Release with auto-generated notes.
+- On failure (most common: PyPI Trusted Publishing not yet configured): point to <https://pypi.org/manage/account/publishing/>.
+- `develop` is now synced with `main` (back-merge done in step 15).
+- Next development cycle starts on `develop` — open `## [Unreleased]` in CHANGELOG is ready.
+
+---
+
+## Critical reminders
+
+- **ALWAYS** cut the release branch from `develop`, not `main` — `develop` carries the work.
+- **NEVER** `--squash` the release PR into `main` — it destroys the integration history the branch carries. Use `--merge`.
+- **NEVER** skip the `main → develop` back-merge (step 15) — skipping it guarantees conflicts at the next release.
+- **NEVER** add `Co-Authored-By: Claude` (or any AI co-author) to the release commit.
+- **NEVER** force-push a release tag once it's on GitHub. Ship a PATCH fix instead.
+- **NEVER** `--no-verify` past hooks. Fix the underlying issue.
+- **NEVER** push directly to `main` — branch protection will reject it. Always use a PR.
+- A `git tag -v` `allowedSignersFile` error is **benign** (verify-only) — the tag is still signed and CI passes. Don't treat it as a failure.
+- **CONFIRM with the user before the step 13 tag push** — it's the irreversible PyPI + public Release trigger.
+- If quality gates fail at step 4, **STOP**. Surface the failures to the user.
+- If doc-review fails at step 10, **STOP**. Fix before committing.
+
+---
+
+## See also
+
+- [RELEASE.md](../../../RELEASE.md) — full release protocol, prerelease policy, and checklist
+- [README § Releases](../../../README.md#releases) — release policy and cadence
+- [PLAN § Phase 5](../../../PLAN.md#phase-5--public-alpha-release-on-pypi) — first-release exit criteria

gflow_cli-0.11.0/.planning/issue-125-fix.md

@@ -0,0 +1,207 @@
+# Issue #125 fix plan — `gflow video i2v` silently routes to T2V with `omni-flash`
+
+**Branch:** `bugfix/issue-125-i2v-t2v` (worktree at `.claude/worktrees/bugfix+issue-125-i2v-t2v/`)
+**Issue:** https://github.com/ffroliva/gflow-cli/issues/125
+**Status:** Plan — awaiting 5-persona council review before implementation.
+
+---
+
+## 1. Root cause (confirmed at zero credit)
+
+`omni-flash` does NOT support i2v interpolation (start+end frames). Flow's frontend silently drops the bound mediaIds at submit time and routes the request to `batchAsyncGenerateVideoText` with `image_inputs: null`. The user is charged 1 credit for a pure text-to-video generation that ignores the start/end frames entirely.
+
+This is **NOT** the originally hypothesised selector / UI-path bug. The "Add to Prompt" click in `_upload_via_open_dialog` IS correct on both EN and pt-BR locales (probe v1). The frame slots transition correctly (`FRAME_SLOTS_STRUCT.count()` drops 2 → 1 → 0, probe v3). The submit-button selector finds the right "Criar" button (probe v3). The bug is at Flow's model-vs-request-shape compatibility check, which is invisible from the DOM.
+
+## 2. Evidence
+
+### Zero-credit evidence
+
+| Probe | Sequence | Model | Captured URL | startImage | endImage |
+|---|---|---|---|---|---|
+| v4 prod-order | attaches → prompt → submit | (inherits Flow's last = omni-flash) | `batchAsyncGenerateVideoText` ❌ | `null` | `null` |
+| v4 reorder | prompt → attaches → submit | omni-flash | `batchAsyncGenerateVideoText` ❌ | `null` | `null` |
+| **v5 omni-flash + start+end** | attaches → prompt → submit | omni-flash (explicit) | `batchAsyncGenerateVideoText` ❌ | `null` | `null` |
+| **v5 omni-flash + start-only** | Start only → prompt → submit | omni-flash (explicit) | `batchAsyncGenerateVideoText` ❌ | `null` | `null` |
+| **v5 veo-lite + start+end** | attaches → prompt → submit | **veo-lite** | **`batchAsyncGenerateVideoStartAndEndImage` ✓** | **`4e551690...` ✓** | **`700c5522...` ✓** |
+
+**Conclusion: omni-flash does NOT support i2v in ANY form** — neither start-only nor start+end. The strict rejection in §3 is verified, not just conservative.
+
+Output dirs:
+- `C:\Users\ffrol\gflow-output\i2v-intercept-prodorder-20260530-160535\evidence.json` (omni-flash, broken)
+- `C:\Users\ffrol\gflow-output\i2v-intercept-veolite-20260530-165432\evidence.json` (veo-lite, correct)
+
+### Human-session HAR evidence
+
+`C:\Users\ffrol\Downloads\labs.google14.har` — manual i2v session on the same account, same UI flow as gflow. The captured generate body shows:
+
+```json
+{
+  "videoModelKey": "veo_3_1_interpolation_lite",  // ← Flow auto-promotes veo_3_1_lite → veo_3_1_interpolation_lite when start+end frames are present
+  "startImage": { "mediaId": "3c65f7ed-..." },
+  "endImage":   { "mediaId": "7e70fd03-..." }
+}
+```
+
+### Paid run evidence
+
+The original gflow paid retry (`C:\Users\ffrol\gflow-output\i2v-prompt-retry-20260530-133705\_err2.log`) used `--model omni-flash` (gflow's default), produced an 8s "wake-up in bedroom" stickman video that has zero visual continuity with `01-t2i.jpg` (stickman at desk) or `02-i2i.jpg` (arms-raised triumph at sunrise). Per the structured-log `generate_captured` event, the request URL was `batchAsyncGenerateVideoText` with all-null image_inputs — pure T2V from the prompt alone.
+
+**Retroactive impact:** every i2v paid run on `gflow v0.10.0` with the default model (or `--model omni-flash`) has been a silent T2V. The wf-004 promo "drift" was not Veo style-shift — it was a pure T2V.
+
+## 3. Scope
+
+### In scope (this PR) — council-revised
+
+- Add model-vs-mode compatibility helper `VideoModel.supports_i2v_interpolation()` returning False for `OMNI_FLASH`, True for the four `VEO_3_1_*` variants. Add `I2V_DEFAULT_MODEL = VideoModel.VEO_3_1_LITE` module constant in `api/video.py` (domain).
+- **Typed error class** `ModelModeIncompatibilityError` (new, in `gflow_cli.errors`) wired into `EXIT_CODE_MAP` with **exit code 17** (distinct from Click's exit 2 "usage error" and generic exit 1). Per CLI UX council finding: "semantic model/mode incompatibility known to the domain deserves a typed error."
+- `gflow video i2v` CLI: drop `omni-flash` from the i2v command's `--model` Click `Choice` tuple entirely (cleanest UX per CLI UX council). The `--help` output then lists only valid models; users see the constraint at help time. Note: t2v / r2v keep `omni-flash` in their Choice.
+- `gflow video i2v` CLI: when `--model` omitted → resolve to `I2V_DEFAULT_MODEL` (`veo-lite`). When a deserialized config still names `omni-flash` (e.g. from a stale `--config` JSON), the Click callback raises `ModelModeIncompatibilityError`.
+- **Defense-in-depth transport guard** in `_generate_video_locked`: place **immediately after `_select_video_model` (~L1170)** and BEFORE any `_attach_frame` call (Architect + Performance both flagged this as the right placement — fails before any DOM mutation, no cleanup needed, no `page.reload()`). Guard checks `mode is Mode.I2V and (start_image is not None or end_image is not None) and not model.supports_i2v_interpolation()` → raises `ModelModeIncompatibilityError`. Catches direct `FlowApiClient` callers (gflow-cli-remotion) who bypass Click.
+- **Structlog event** `ui_automation_video.model_mode_rejected` emitted by the transport guard before raising — fields `{model, mode, has_start_image, has_end_image, issue_ref: "#125"}`. Required for e2e assertion per CLI UX council + [[verification-ledger-5-layer]].
+- `--model` Click `help=` text on i2v + i2v command `examples=` corrected.
+- Unit tests for the typed error, Choice-drop, default resolution, transport guard, and structlog assertion — see §6.
+- CHANGELOG entries under both `### Fixed` and `### Changed` (the default-model shift is a Changed behaviour worth surfacing separately).
+- Update issue #125 with the actual root cause and link the PR.
+- Ship two diagnostic probes (`capture_i2v_post_bind_state.py`, `capture_i2v_intercept_submit.py`). **DROP probe v1 (`capture_i2v_upload_dialog_dom.py`)** — it proved a refuted hypothesis; ship-as-doc was post-hoc justification per Devil's Advocate.
+
+### Out of scope (deferred — with evidence-based plan)
+
+- **r2v + omni-flash compatibility** — Devil's Advocate flagged for in-scope inclusion. Probing r2v requires extending the probe with `--mode references` (different sub-mode, different attach helper `_attach_references`, different endpoint family `batchAsyncGenerateVideoReferenceImages`). Material rewrite. **Decision: file follow-up issue with a one-line probe extension as the first task. Defer scope expansion until evidence in hand.** The plan's transport guard is structured so adding r2v rejection later is a one-line change (`mode is Mode.R2V and not model.supports_r2v(...)`).
+- **omni-flash + start-only i2v** — RESOLVED by probe v5: also routes T2V. Already covered by the in-scope reject-omni-flash-for-any-i2v rule. No longer "unverified strictness."
+- **Full model+mode compatibility matrix** — broader spec; separate work.
+- **Selector-cascade hardening for `_upload_via_open_dialog`** (originally Stage A from the predict review) — no longer needed; probe v1 confirmed the selector works on pt-BR. Drop this scope. (Probe itself dropped from ship list per above.)
+
+## 4. Files touched — council-revised
+
+| File | Purpose | Change |
+|---|---|---|
+| `src/gflow_cli/api/video.py` | Domain | Add `VideoModel.supports_i2v_interpolation()` classmethod. Add `I2V_DEFAULT_MODEL = VideoModel.VEO_3_1_LITE`. Per Architect: "domain invariant, not adapter knowledge — analogous to `Aspect.wire()`." |
+| `src/gflow_cli/errors.py` | Typed error | Add `ModelModeIncompatibilityError(GFlowError)` with `exit_code=17`. Per CLI UX council. |
+| `src/gflow_cli/cli_video.py` | CLI surface | Drop `omni-flash` from i2v `--model` Click `Choice` (cleanest discoverability per CLI UX). Add a Click callback resolving omitted `--model` to `I2V_DEFAULT_MODEL`. Raise `ModelModeIncompatibilityError` if a deserialized config still names `omni-flash` for i2v. Update i2v `--model help=` and command examples. |
+| `src/gflow_cli/api/transports/ui_automation_video.py` | Transport guard | In `_generate_video_locked`, **immediately after `_select_video_model` (~L1170), BEFORE `_attach_frame`**: emit `ui_automation_video.model_mode_rejected` event and raise `ModelModeIncompatibilityError` if `mode is Mode.I2V and (start_image is not None or end_image is not None) and not model.supports_i2v_interpolation()`. Per Architect + Performance: earlier placement = no DOM mutation, no cleanup needed. **No `page.reload()`** — drop the R6 mitigation entirely. |
+| `tests/api/test_video.py` (or sibling) | Unit | `test_supports_i2v_interpolation_matrix` parametrized over all 5 VideoModel variants. `test_i2v_default_model_is_veo_lite`. |
+| `tests/errors/test_exit_codes.py` (or sibling) | Unit | `test_model_mode_incompatibility_error_exit_code_17` + ordering-invariant. |
+| `tests/cli/test_cli_video.py` (or sibling) | Unit | i2v --help no longer lists omni-flash; omitted --model resolves to veo-lite; explicit omni-flash via stale config raises exit 17. |
+| `tests/api/transports/test_ui_automation_video.py` (or sibling) | Unit | `test_transport_rejects_i2v_with_omni_flash` — stubbed request DTO, assert raise + `model_mode_rejected` event captured. |
+| `CHANGELOG.md` | Release note | New `### Fixed` entry (i2v silent T2V regression) + new `### Changed` entry (i2v default model shift to veo-lite). |
+| `scripts/dev/capture_i2v_post_bind_state.py` | Dev tooling | NEW — slot-state regression probe. |
+| `scripts/dev/capture_i2v_intercept_submit.py` | Dev tooling | NEW — definitive zero-credit reproducer (the smoking-gun probe). |
+| ~~`scripts/dev/capture_i2v_upload_dialog_dom.py`~~ | ~~Dev tooling~~ | **DROPPED from ship list** — proved a refuted hypothesis; not maintaining as documentation. |
+
+## 5. Implementation steps (in order — each a focused commit) — council-revised
+
+1. **Add `ModelModeIncompatibilityError`** to `gflow_cli.errors` + wire into `EXIT_CODE_MAP` with `exit_code=17`. Unit test for ordering-invariant + the new mapping.
+2. **Add `VideoModel.supports_i2v_interpolation()` + `I2V_DEFAULT_MODEL`** in `api/video.py` + unit tests.
+3. **Drop omni-flash from i2v's `--model` Click `Choice`; add resolution callback** in `cli_video.py`. Add `ModelModeIncompatibilityError` raise for the stale-config edge case. Unit tests for both paths.
+4. **Transport guard** at the correct placement (just after `_select_video_model`) in `_generate_video_locked` + structlog event + unit test stubbing the request DTO. Verify no `page.reload()` is added.
+5. **Update `--model help=` text + i2v command examples** in `cli_video.py`.
+6. **CHANGELOG**: `### Fixed` + `### Changed` entries.
+7. **Add the two dev probes** to `scripts/dev/`: `capture_i2v_post_bind_state.py` + `capture_i2v_intercept_submit.py`. Do NOT add `capture_i2v_upload_dialog_dom.py`.
+8. **Update issue #125** with the corrected root cause and link to the PR (in §7 verification, after merge).
+
+## 6. Test plan — council-revised
+
+### Unit tests
+
+- `test_omni_flash_does_not_support_i2v_interpolation`: `VideoModel.OMNI_FLASH.supports_i2v_interpolation() is False`
+- `test_veo_3_1_models_support_i2v_interpolation`: parametrize across the four VEO_3_1_* variants, all return True
+- `test_i2v_default_model_constant`: `I2V_DEFAULT_MODEL is VideoModel.VEO_3_1_LITE`
+- `test_model_mode_incompatibility_error_exit_code_is_17`: `ModelModeIncompatibilityError().exit_code == 17` and the class is registered in `EXIT_CODE_MAP`
+- `test_exit_code_map_ordering_invariant_still_holds` after the new entry (per [[exit-code-map-ordering-invariant-test-pitfall]])
+- `test_i2v_click_choice_excludes_omni_flash`: introspect the i2v command's `--model` Click `Choice` — `"omni-flash" not in choices`. (Compare to t2v Choice which DOES include it.)
+- `test_i2v_cli_resolves_default_to_veo_lite`: `gflow video i2v start.jpg "p" --end-image end.jpg` (no --model) → resolved model in the request DTO is `VideoModel.VEO_3_1_LITE`
+- `test_i2v_cli_rejects_stale_config_with_omni_flash`: a deserialized config JSON pointing at omni-flash for i2v → exits **17** (not 2) with stderr containing "#125" and "veo-lite"
+- `test_transport_raises_on_i2v_with_omni_flash_and_end_image`: invoke `_generate_video_locked` with a stubbed request `(model=OMNI_FLASH, mode=I2V, start_image=Path, end_image=Path)` → raises `ModelModeIncompatibilityError`, structlog captures `model_mode_rejected` event with fields `{model: "omni_flash", mode: "I2V", has_start_image: True, has_end_image: True, issue_ref: "#125"}`. **No DOM mutation must have occurred** — assert no `_attach_frame` call fired (via mock).
+- `test_transport_raises_on_i2v_with_omni_flash_and_start_only`: same shape but `end_image=None`, `start_image=Path` — still raises (omni-flash rejected for any i2v ref, per probe evidence).
+- `test_transport_does_NOT_raise_on_t2v_with_omni_flash`: pure t2v + omni-flash is a valid combination — guard must NOT fire.
+
+### Integration tests
+
+- BDD scenario: "user runs i2v with default model" → command resolves to veo-lite, no Flow interaction. Assert `structlog` shows `model_mode_rejected` is NOT emitted.
+- BDD scenario: "in-process API caller (e.g. flow_workflow.py shape) passes `model=OMNI_FLASH, mode=I2V, start_image=Path` to `FlowApiClient.generate_video`" → raises `ModelModeIncompatibilityError`, exit code 17. **This is the safety net for gflow-cli-remotion-style consumers.**
+- Audit existing i2v integration tests: any fixture using omni-flash for i2v must be updated to a Veo 3.1 model.
+
+### Live e2e (1 paid credit)
+
+- Re-run probe v5 (`capture_i2v_intercept_submit.py --model veo-lite ...`) zero-credit sanity check — captured URL must still be `StartAndEndImage` with bound mediaIds.
+- Then a live `gflow video i2v 01-t2i.jpg "<tightened stickman motion prompt>" --end-image 02-i2i.jpg --model veo-lite --aspect 9:16 --profile promo-denon82` → expect:
+  - structured log `ui_automation_video.generate_captured` event with `url=batchAsyncGenerateVideoStartAndEndImage` and `image_inputs.startImage` + `image_inputs.endImage` non-null
+  - **assert structured log does NOT contain `ui_automation_video.model_mode_rejected`** (positive verification that the new guard didn't false-fire on a valid combination)
+  - output mp4 visually: 2D ink line-art stickman starting at desk (matches 01-t2i.jpg), interpolating to arms-raised at sunrise (matches 02-i2i.jpg)
+  - 5-layer verification ledger per memory [[verification-ledger-5-layer]]: file count, magic bytes (mp4 signature), Pillow dims (720×1280), structlog invariants (above), user gallery confirmation.
+
+## 7. Verification ladder (definition of done) — council-revised
+
+- [ ] `ruff format --check` + `ruff check` clean on `src/gflow_cli/{cli_video,errors,api/video,api/transports/ui_automation_video}.py` and the two dev probe scripts shipping.
+- [ ] `pyright` clean on the same scoped paths.
+- [ ] All new unit tests pass (see §6).
+- [ ] Scoped pytest of `tests/cli/` + `tests/api/` + `tests/api/transports/` + `tests/errors/` passes (full sweep deferred to CI per [[full-test-suite-ooms]]).
+- [ ] BDD/integration tests pass.
+- [ ] **Exit-code-map ordering-invariant test passes** (per [[exit-code-map-ordering-invariant-test-pitfall]]) — adding code 17 must not invert any prior subclass-relation invariant.
+- [ ] Probe v5 re-run with `--model veo-lite` still produces `StartAndEndImage` URL with bound mediaIds (zero credit).
+- [ ] Probe v5 re-run with `--model omni-flash --start-only` still produces T2V (zero credit — proves the rejection is still warranted).
+- [ ] 1 paid live e2e i2v run completes; structured log shows `generate_captured.url=batchAsyncGenerateVideoStartAndEndImage` with non-null mediaIds AND `model_mode_rejected` event is NOT emitted.
+- [ ] User watches the output mp4 and verbally confirms it's a 2D ink line-art stickman desk → sunrise scene matching the refs.
+- [ ] Issue #125 comment thread updated with the actual root cause + closed by PR merge.
+- [ ] CHANGELOG entries present under `[Unreleased]` — both `### Fixed` and `### Changed`.
+
+## 8. Risks + mitigations
+
+| Risk | Severity | Mitigation |
+|---|---|---|
+| R1: Changing default model silently surprises users who already had a working incantation | LOW — prior incantation was broken (T2V output); making it work correctly is a strict improvement | None needed beyond clear CHANGELOG note |
+| R2: veo-lite has different cost/quality than omni-flash | LOW — both are tier-one lite models; veo-3.1-lite cost is documented in Flow's UI per `MEDIA_GENERATION_PAYGATE_TIER: PAYGATE_TIER_ONE` | Document in --model help text |
+| R3: omni-flash + start-only i2v might actually work (unverified) | MEDIUM — if it does work, our strict rejection blocks a valid combination | Conservative reject in this PR; reverse with probe evidence in a follow-up if proven |
+| R4: r2v + omni-flash has the same silent-drop pathology | MEDIUM — separate UI surface, separate ticket needed | Out of scope; file follow-up issue with link from #125 |
+| R5: Hidden in-process API callers (scripts using `FlowApiClient` directly like `gflow-cli-remotion/flow_workflow.py`) bypass the CLI validation | MEDIUM | The transport guard in `_generate_video_locked` is the safety net for these callers |
+| ~~R6: pre-submit guard raises but the page is left in a dirty state for the pool~~ | ~~LOW~~ | **DROPPED per Performance council review.** Guard now placed at L1170 (immediately after `_select_video_model`, BEFORE any `_attach_frame`) — fires before any DOM-state mutation, no Page cleanup needed, no `page.reload()`. Architect concurred ("earlier-fail is cleaner than dirty-state cleanup"). |
+
+## 9. Rollback
+
+- Revert the PR as a single commit-range. No DB migrations, no settings changes, no state mutations.
+- The transport guard fails-closed: if a user with cached venv hits the guard on a stale config, they get a clear error pointing at #125 with remediation. No silent regression.
+
+## 10. CHANGELOG entries — council-revised (two sections)
+
+```markdown
+### Fixed
+
+- `gflow video i2v` silently routed every call to the T2V endpoint with
+  `image_inputs: null` when the model was `omni-flash` (Flow's last-used
+  default in most sessions). Flow's frontend rejects omni-flash + frame
+  refs and falls back to text-only generation, but the rejection is
+  invisible to the client — every i2v paid run on v0.10.0 burned a
+  credit for a pure text-to-video generation that ignored the supplied
+  start/end frames. Issue #125. Fix: omni-flash dropped from the i2v
+  `--model` Click `Choice` entirely; a defense-in-depth transport guard
+  in `_generate_video_locked` raises `ModelModeIncompatibilityError`
+  (exit code 17) for direct `FlowApiClient` callers that bypass the CLI.
+
+### Changed
+
+- `gflow video i2v` default model is now `veo-lite` (was: inherit
+  Flow's last-used, which was typically `omni-flash` — see Fixed). The
+  veo-3.1 family is the only model line that supports i2v
+  interpolation; omni-flash is now correctly rejected for any i2v
+  invocation (start-only or start+end). Explicit `--model omni-flash`
+  for `gflow video t2v` and `gflow video r2v` remains valid.
+```
+
+## 11. Migration / backward compat
+
+- No breaking config or env-var changes.
+- v0.10.0 users running `gflow video i2v ... --end-image ...` without explicit `--model` previously got silent T2V output; they now get correct interpolation (silent improvement, no surprise).
+- v0.10.0 users running `gflow video i2v ... --end-image ... --model omni-flash` previously got silent T2V; they now get a clear error with `gflow video i2v ... --end-image ... --model veo-lite` as the remediation.
+- BREAKING for: nobody. The prior behavior was a silent bug.
+
+---
+
+## Appendix: probe scripts
+
+All zero-credit. Only two ship in this PR per Devil's Advocate review (probe v1 dropped — proved a refuted hypothesis, no future-locale-regression value).
+
+| Probe | What it proved | Ships? |
+|---|---|---|
+| `capture_i2v_upload_dialog_dom.py` | "Incluir no comando" pt-BR button matches the production `add_btn` selector — selector cascade is correct (REFUTED original hypothesis). | **NO** — proved a refuted hypothesis; not maintaining as documentation. |
+| `capture_i2v_post_bind_state.py` | `FRAME_SLOTS_STRUCT.count()` transitions 2 → 1 → 0 after binds; submit button is unambiguous (single arrow_forward "Criar" button); slots stay bound after prompt typing. | **YES** — useful future probe for slot-state regressions. |
+| `capture_i2v_intercept_submit.py` | Intercepts the submit XHR via `page.route(..., abort)` and inspects the request body. omni-flash → T2V with null images (both start+end and start-only); veo-lite → StartAndEndImage with populated mediaIds. **This is the definitive reproducer.** | **YES** — definitive regression probe for future model/mode work. |

{gflow_cli-0.10.0 → gflow_cli-0.11.0}/AGENTS.md

@@ -66,6 +66,23 @@ Or invoke the wrapper: `/gflow:check`.
 - Run `/gflow:check` (or the Impeccable Routine) before every commit.
 - All releases require a signed annotated tag (`git tag -s vX.Y.Z`); CI rejects unsigned tags.
 
+## Skills reference (cross-tool)
+
+The `skills/` directory ships installable agent skill docs in plain Markdown with YAML frontmatter. Any agent can consume them directly:
+
+| Skill | Path | When to load |
+|---|---|---|
+| `gflow-cli` | [`skills/gflow-cli/SKILL.md`](skills/gflow-cli/SKILL.md) | User wants to run any `gflow` command — auth, T2V, I2V, T2I, I2I, batch |
+| `predict` | [`skills/predict/SKILL.md`](skills/predict/SKILL.md) | Pre-implementation adversarial analysis before any high-stakes change |
+| `scenario` | [`skills/scenario/SKILL.md`](skills/scenario/SKILL.md) | Edge-case explorer after a predict GO/CAUTION |
+| `pr-council-review` | [`skills/pr-council-review/SKILL.md`](skills/pr-council-review/SKILL.md) | Multi-dimensional PR council review |
+
+**Cursor / Aider / Codex / Gemini CLI:** paste or include the relevant `SKILL.md` in your system context.
+**Claude Code:** symlink `skills/gflow-cli` to `~/.claude/skills/gflow-cli` to register the skill; the `/gflow:` slash commands (in `.claude/commands/gflow/`) are auto-discovered from the project directory.
+**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).
+
 ## Where to look next
 
 - **Architecture & target shape** → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)

{gflow_cli-0.10.0 → gflow_cli-0.11.0}/CHANGELOG.md

@@ -7,6 +7,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] — 2026-05-31
+
+### Changed
+
+- **`gflow video i2v` default model is now `veo-lite`** (was: inherit Flow's
+  last-used model, which was typically `omni-flash`). The Veo 3.1 family is
+  the only model line that supports i2v interpolation; `omni-flash` is now
+  rejected for any i2v invocation (start-only or start+end) and has been
+  removed from the i2v `--model` choices. Because `--duration 10` is
+  omni-flash-only, the i2v `--duration` choices are now `[4|6|8]`. `omni-flash`
+  (and `--duration 10`) remain valid for `gflow video t2v` and `gflow video r2v`.
+  See issue #125.
+
+### Fixed
+
+- **`gflow video i2v` silently produced text-to-video output, ignoring the
+  start/end frames (issue #125).** When the model was `omni-flash` (Flow's
+  last-used default in most sessions), Flow's frontend dropped the bound
+  start/end frame references at submit time and routed every call to
+  `batchAsyncGenerateVideoText` with `image_inputs: null` — charging a credit
+  for a pure text-to-video generation that had no visual relationship to the
+  supplied frames. **Every i2v paid run on v0.10.0 before this fix produced
+  T2V output regardless of the start/end frames.** Fix: `omni-flash` is
+  dropped from the i2v `--model` choices and the i2v default is now `veo-lite`;
+  a defense-in-depth transport guard raises `ModelModeIncompatibilityError`
+  (exit code 17) for direct `FlowApiClient` callers that bypass the CLI.
+
+- **`gflow video i2v` could still route to T2V even with a valid Veo model,
+  because the model-picker option `Veo 3.1 - Lite` was never selected (issue
+  #125, second path).** The picker selector was an exact-match
+  (`:text-is('volume_upVeo 3.1 - Lite')`) that hardcoded a Material Symbols
+  icon-ligature prefix; when it missed, `_select_video_model` warned and
+  continued, leaving Flow on `omni-flash` → the frames were dropped to T2V.
+  Fixes: (1) the selector is now a robust substring match
+  (`:has-text('Veo 3.1 - Lite'):not(:has-text('[Lower Priority]'))`); (2) for
+  i2v, a model-select miss is now FATAL — `_select_video_model(required=True)`
+  retries the picker then raises `VideoModelSelectionError` (exit code 18)
+  *before* any frame attach or submit, spending no credit; (3) a post-submit
+  backstop raises `WireFormatError` if an i2v request is still observed routing
+  to the T2V endpoint, so a "successful" T2V is never reported as i2v.
+
+- **Create-project generation failing when Flow's "Agent" composer mode is active.**
+  Flow's newer editor adds an Agent toggle next to the prompt box; when it is on,
+  the media-generation panel (the `crop_*` settings trigger, Image/Video mode
+  tablist, and count/model controls) is removed from the DOM, so the UI-automation
+  transport raised "mode-switch dropdown trigger not found". `_switch_to_image_mode`
+  and `_switch_to_video_mode` now call `_exit_agent_mode()` first, which re-mounts
+  the panel by clicking the toggle off. Detection is locale-invariant and uses no
+  UI text and no `aria-` attribute (`button:has(span.content)` plus the absence of
+  the locale-stable `crop_*` trigger), so it works in every Flow UI language.
+
+- **`gflow image t2i` / `i2i` model selection hardened for non-English Flow UIs
+  (issue #94).** `IMAGE_MODEL_OPTION_SELECTORS` is now a selector *cascade*
+  (consistent with every other selector group) instead of a single exact-match
+  string, so `_select_image_model` no longer silently fails to select the
+  requested model when Flow's menu markup shifts. The redundant `--lang=en-US`
+  Chromium launch arg was removed — Flow's branded model names ("Nano Banana 2",
+  "Nano Banana Pro", "Imagen 4") are not localised and `FLOW_URL`'s `?hl=en`
+  already locks the SPA to English, so the override was a no-op.
+
 ## [0.10.0] — 2026-05-29
 
 ### Fixed
@@ -1209,7 +1269,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.10.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/ffroliva/gflow-cli/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/ffroliva/gflow-cli/compare/v0.9.1...v0.10.0
 [0.9.1]: https://github.com/ffroliva/gflow-cli/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/ffroliva/gflow-cli/compare/v0.8.1...v0.9.0

{gflow_cli-0.10.0 → gflow_cli-0.11.0}/CLAUDE.md

@@ -22,6 +22,20 @@
 - Skills under `skills/` are auto-discoverable; `gflow-cli` ships its own at [`skills/gflow-cli/SKILL.md`](skills/gflow-cli/SKILL.md).
 - Auto-memory at `~/.claude/projects/C--development-github-gflow-cli/memory/MEMORY.md` carries cross-session feedback and project state.
 
+## MCP GitHub tool — PR body rule (non-negotiable)
+
+When calling `mcp__github__create_pull_request` or `mcp__github__update_pull_request`, the `body` parameter **must be a plain string**. Shell heredoc syntax (`$(cat <<'EOF' ... EOF)`) is **never valid** here — MCP tool parameters are JSON, not shell; the heredoc is not evaluated and appears literally in the PR description.
+
+```
+# WRONG — produces literal "$(cat <<'EOF'" in the PR body:
+body: "$(cat <<'EOF'\n## Summary\n...\nEOF\n)"
+
+# CORRECT — plain multiline string:
+body: "## Summary\n\n- Item 1\n- Item 2\n\n## Test plan\n- [ ] ..."
+```
+
+The heredoc pattern (`$(cat <<'EOF' ... EOF)`) is only valid inside a `Bash` tool call because the **shell** evaluates it there. In every MCP tool parameter it is a literal string. This mistake has recurred across multiple PRs — treat this rule as a hard blocker before every PR creation or update.
+
 ## Active phase
 
 See [PLAN.md](PLAN.md) or run `/gflow:plan` for the current detailed plan.

{gflow_cli-0.10.0 → gflow_cli-0.11.0}/KNOWN_ISSUES.md

@@ -315,15 +315,18 @@ issue and not blocked by any code change in this repo.
 
 ---
 
-### `UiAutomationTransport` selectors still partially localized — issue #24 partial
+### `UiAutomationTransport` selectors locale-agnostic — issue #24 Phase 5 complete
 
-- **Status:** Mitigated · **Severity:** Medium · **Tracking:** [issue #24](https://github.com/ffroliva/gflow-cli/issues/24)
+- **Status:** Resolved (pending owner live e2e on non-EN profile) · **Severity:** Low · **Tracking:** [issue #24](https://github.com/ffroliva/gflow-cli/issues/24), [issue #94](https://github.com/ffroliva/gflow-cli/issues/94)
 
-  Status stays *Mitigated* (not *Resolved*) because `--lang=en-US` is still
-  passed and `NEW_PROJECT_SELECTORS` / `SUBMIT_BUTTON_SELECTORS` tails still
-  carry English-text fallbacks; the icon-first leads cover the common path,
-  but the dependency only fully clears after a live e2e on a non-English
-  Chrome profile.
+  `--lang=en-US` removed in PR #127 (2026-05-30). All selector groups now use
+  locale-stable anchors: `IMAGE_MODEL_OPTION_SELECTORS` and
+  `VIDEO_MODEL_OPTION_SELECTORS` converted to `dict[Model, tuple[str, ...]]`
+  cascade structure; branded product names ("Nano Banana 2", "Nano Banana Pro",
+  "Imagen 4", "Veo 3.1 - *", "Omni Flash") are confirmed locale-stable
+  Google-branded identifiers. Locale is controlled by the `locale=locale_env`
+  Playwright kwarg (persists across all in-session navigations). Full resolution
+  gate: live e2e with `gflow image t2i` (each model) on a non-EN Chrome profile.
 
 **Phase 2 progress (2026-05-25, develop / post-v0.8.1, unreleased):**
 
@@ -402,9 +405,10 @@ issue and not blocked by any code change in this repo.
   lead and cover the common path, so these are maintenance debt rather than
   active blockers).
 
-**Full resolution requires:** live e2e verification on a non-English Chrome profile
-(`GFLOW_CLI_LOCALE=<non-EN>` + a non-English browser profile) to confirm no
-regression, then removing `--lang=en-US`.
+**Remaining gate:** live e2e with `gflow image t2i --model <each>` on a non-EN
+Chrome profile (`GFLOW_CLI_LOCALE=<non-EN>`) to confirm model picker resolves
+correctly without `--lang=en-US`. `--lang=en-US` has been removed (PR #127);
+`locale=locale_env` Playwright kwarg provides locale continuity across navigations.
 
 **Workaround:** with Phase 2 changes, most locales are handled automatically.
 For locales outside the 14 covered by `_ONBOARDING_TEXT_SELECTORS`, ARIA-based