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

gflow_cli-0.11.0/.claude/commands/gflow/branch-review.md

@@ -0,0 +1,13 @@
+---
+description: Multi-dimensional LLM council review on the current local feature branch — pre-PR review. Same dimensions as `/gflow:pr-council-review` but reads `git diff <base>..HEAD` instead of a PR; never posts to GitHub. Wrapper around skills/pr-council-review/SKILL.md § 8 (branch mode).
+---
+
+# `/gflow:branch-review [--base <ref>]`
+
+**Read `skills/pr-council-review/SKILL.md` and follow its protocol now in BRANCH MODE (§ 8)**, passing `$ARGUMENTS` (optional `--base <ref>`; default `develop`).
+
+> Do **not** call `Skill(skill="pr-council-review")` — the repo's `skills/*/SKILL.md` files are plain Markdown, not registered as Skill-tool-invocable (only `.claude/commands/gflow/*` are). Invoking it errors with `Unknown skill: pr-council-review`. Read the file directly instead.
+
+The canonical body is `skills/pr-council-review/SKILL.md`. § 8 documents branch-mode-specific behavior: pre-flight, the PR→branch translation table, `release/*` downgrade, SHA drift, and local-only output. All other phases (gather context, detect dimensions, dispatch, synthesize, report) are identical to PR mode.
+
+Sibling: `/gflow:pr-council-review <N>` runs the same council against an open PR.

gflow_cli-0.11.0/.claude/commands/gflow/pr-council-review.md

@@ -0,0 +1,11 @@
+---
+description: Multi-dimensional LLM council review of an open PR. Five baseline dimensions (correctness, quality, security, tests, memory-hygiene) plus adaptive per-surface dimensions. Sub-agents invoke specialized skills (security-review, code-review, verify). With no argument, lists open PRs ranked by priority. Wrapper around skills/pr-council-review/SKILL.md (canonical body).
+---
+
+# `/gflow:pr-council-review [PR#]`
+
+**Read `skills/pr-council-review/SKILL.md` and follow its protocol now**, treating `$ARGUMENTS` as the PR number (or empty for prioritize-mode). That file is the canonical body: preflight, dimension detection, parallel dispatch, synthesis, report.
+
+> Do **not** call `Skill(skill="pr-council-review")` — the repo's `skills/*/SKILL.md` files are plain Markdown, not registered as Skill-tool-invocable (only `.claude/commands/gflow/*` are). Invoking it errors with `Unknown skill: pr-council-review`. Read the file directly instead.
+
+Sibling: `/review` is the single-agent Claude-Code built-in (fast, one-pass). Use it for spot-checks; use this command for pre-merge multi-dim audits.

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

@@ -0,0 +1,19 @@
+---
+description: >
+  Pre-implementation 5-persona adversarial analysis for high-stakes gflow-cli proposals.
+  Produces a GO / CAUTION / STOP verdict before any code is written.
+  Invoke before new transports, auth changes, selector redesigns, schema migrations,
+  or any PLAN.md backlog item gated on an investigation step.
+---
+
+# `/gflow:predict [proposal]`
+
+**Read `skills/predict/SKILL.md` and follow its protocol now**, passing `$ARGUMENTS` as the proposal description.
+
+> Do **not** call `Skill(skill="predict")` — the repo's `skills/*/SKILL.md` files are plain Markdown, not registered as Skill-tool-invocable (only `.claude/commands/gflow/*` are). Invoking it errors with `Unknown skill: predict`. Read the file directly instead.
+
+The skill at `skills/predict/SKILL.md` runs five independent expert personas
+(Architect · Security/reCAPTCHA · Performance/Playwright · CLI UX · Devil's Advocate),
+resolves conflicts, and returns a GO / CAUTION / STOP verdict with a confidence score.
+
+**Pair with `/gflow:scenario`** after a GO or CAUTION to enumerate edge cases before EXECUTE.

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/.claude/commands/gflow/scenario.md

@@ -0,0 +1,23 @@
+---
+description: >
+  Pre-implementation edge-case explorer for gflow-cli features.
+  Decomposes a proposed change across 12 gflow-cli-specific dimensions
+  (WAF/reCAPTCHA, selector drift, auth lifecycle, batch resume, data layer,
+  cross-platform paths, error propagation, observability) and produces a
+  severity-ranked scenario table and BDD skeleton.
+---
+
+# `/gflow:scenario [feature description]`
+
+**Read `skills/scenario/SKILL.md` and follow its protocol now**, passing `$ARGUMENTS` as the feature or change description.
+
+> Do **not** call `Skill(skill="scenario")` — the repo's `skills/*/SKILL.md` files are plain Markdown, not registered as Skill-tool-invocable (only `.claude/commands/gflow/*` are). Invoking it errors with `Unknown skill: scenario`. Read the file directly instead.
+
+The skill at `skills/scenario/SKILL.md` covers 12 dimensions tuned to gflow-cli's
+known failure surfaces and outputs:
+- A severity-ranked scenario table (Critical / High / Medium / Low)
+- Must-cover acceptance criteria for the PLAN.md task
+- Suggested BDD `Scenario:` blocks for `tests/features/`
+- Cross-references to open KNOWN_ISSUES entries
+
+**Typical order:** `/gflow:predict` → `/gflow:scenario` → PLAN.md task → `/gflow:check` → PR.

{gflow_cli-0.9.1 → gflow_cli-0.11.0}/.env.template

@@ -52,6 +52,34 @@
 # Get one at https://aistudio.google.com/apikey
 # GFLOW_CLI_GEMINI_API_KEY=
 
+# -----------------------------------------------------------------------------
+# Cloud storage
+# -----------------------------------------------------------------------------
+
+# Upload generated assets directly to a cloud bucket instead of saving local
+# asset copies. Supported schemes:
+#   gs://   – Google Cloud Storage (requires: pip install 'gflow-cli[gcs]')
+#   s3://   – Amazon S3 or any S3-compatible store, e.g. MinIO
+#             (requires: pip install 'gflow-cli[s3]')
+#
+# Examples:
+#   GFLOW_CLI_STORAGE_URI=gs://my-gcs-bucket/gflow/
+#   GFLOW_CLI_STORAGE_URI=s3://my-s3-bucket/gflow/
+#   GFLOW_CLI_STORAGE_URI=s3://gflow-test/gflow/   # MinIO local dev
+#
+# For S3 / MinIO you also need the standard AWS SDK env vars:
+#   AWS_ACCESS_KEY_ID=minioadmin
+#   AWS_SECRET_ACCESS_KEY=minioadmin
+#   AWS_ENDPOINT_URL=http://localhost:9000   # omit for real AWS
+#   AWS_DEFAULT_REGION=us-east-1
+#
+# For GCS (local emulator):
+#   STORAGE_EMULATOR_HOST=http://localhost:4443
+#
+# When unset, assets are saved to GFLOW_CLI_OUTPUT_DIR (local disk). gflow-cli
+# does not dual-write local + cloud copies; configure one storage target per run.
+# GFLOW_CLI_STORAGE_URI=
+
 # -----------------------------------------------------------------------------
 # Runtime tuning
 # -----------------------------------------------------------------------------

{gflow_cli-0.9.1 → gflow_cli-0.11.0}/.github/PULL_REQUEST_TEMPLATE.md

@@ -7,6 +7,8 @@
 <!-- List the focused commands you ran, plus any checks you could not run. -->
 
 - [ ] Focused tests added or updated for behavior changes
+- [ ] Documentation updated or explicitly marked not applicable
+- [ ] `uv run python scripts/ci/check_doc_links.py`
 - [ ] `uv run ruff check src tests`
 - [ ] `uv run pyright src`
 - [ ] Relevant pytest command:

{gflow_cli-0.9.1 → gflow_cli-0.11.0}/.github/workflows/ci.yml

@@ -6,7 +6,9 @@ on:
   pull_request:
 
 env:
-  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  # Suppress Node.js deprecation warnings and align with user request to use Node 22/remove noise.
+  ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: true
+  NODE_VERSION: '22'
 
 jobs:
   # ── Security gate: runs first, on every push/PR, never skippable ──────────
@@ -44,6 +46,9 @@ jobs:
       - name: Repo hygiene (no artefacts, no hardcoded paths)
         run: uv run python scripts/ci/check_repo_hygiene.py
 
+      - name: Documentation links
+        run: uv run python scripts/ci/check_doc_links.py
+
       - name: Lint
         run: uv run ruff check src tests
 
@@ -94,7 +99,7 @@ jobs:
         continue-on-error: true  # graceful if coverage upload was skipped
 
       - name: SonarCloud scan
-        uses: SonarSource/sonarcloud-github-action@master
+        uses: SonarSource/sonarcloud-github-action@v5.0.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # PR decoration
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}    # set in repo → Settings → Secrets

{gflow_cli-0.9.1 → gflow_cli-0.11.0}/.github/workflows/release.yml

@@ -16,7 +16,8 @@ jobs:
       name: pypi
       url: https://pypi.org/p/gflow-cli
     env:
-      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+      ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: true
+      NODE_VERSION: '22'
     steps:
       - uses: actions/checkout@v6
         with:

{gflow_cli-0.9.1 → gflow_cli-0.11.0}/.gitignore

@@ -71,6 +71,8 @@ samples/captured/flow_outgoing_*.jsonl
 samples/captured/flow_outgoing_*.json
 
 # Claude Code worktrees and lock files
+.claude/settings.json
+.claude/settings.local.json
 .claude/worktrees/
 .claude/scheduled_tasks.lock
 

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. |