gflow-cli 0.8.0__tar.gz → 0.9.0__tar.gz

gflow_cli-0.9.0/.claude/commands/gflow/doc-review.md

@@ -0,0 +1,259 @@
+---
+description: Use before cutting any gflow-cli release or after a major documentation change — systematic council-driven audit that combines a mechanical 7-section checklist with a 3-agent parallel review (completeness / cross-reference / drift). Produces a consensus verdict and a concrete fix list.
+---
+
+# `/gflow:doc-review` — Documentation Review Gate
+
+Run this gate before cutting a release. Two phases:
+
+1. **Mechanical checks** (sections 1–7 below) — fast, scripted, deterministic. Run inline.
+2. **LLM council audit** (section 8) — 3 parallel review subagents, then consensus synthesis. The mechanical pass catches stale strings and dead links; the council catches drift between docs, fictional claims, and gaps a human reader would notice.
+
+Every item reports **PASS / UPDATED / WARN / FAIL**. Any **FAIL** or any **RED** council verdict blocks the release.
+
+> **Provenance:** the council protocol below was validated on the v0.8.1 docs refresh release (2026-05-23). The audit found 11 fixable issues that the mechanical checklist alone missed (e.g., the `experimental/` subpackage fiction in 3 files, the `gflow video i2v` non-working hero snippet in README). Keep the council step — it pays for itself.
+
+---
+
+## 0 · Pre-flight
+
+- Confirm you are on the release branch (`release/vX.Y.Z` or `hotfix/...`), not on `develop` or `main`.
+- If a release spec exists at `docs/superpowers/specs/YYYY-MM-DD-*-design.md`, identify it now — the council auditors will use it as the ground truth for "what was supposed to ship."
+- If there is no spec, that is also fine — the council will work from the docs alone, but flag the absence as a process risk.
+
+---
+
+## 1 · Version references
+
+Check these files for stale version strings (old numbers, outdated status labels):
+
+| File | What to verify |
+|---|---|
+| `README.md` | Status badge, "Project status" section, install example |
+| `AGENTS.md` | Module list, exit-code range, dev-environment commands |
+| `llms.txt` | Header summary (Python version, stable surface claims) |
+| `CLAUDE.md` | "Active phase" pointer if present |
+| `PLAN.md` | Phase status (`IN PROGRESS` / `DONE`) and version annotations |
+| `KNOWN_ISSUES.md` | `Open` entries resolved by this release → move to `Resolved` with evidence |
+| `CHANGELOG.md` | `[Unreleased]` empty; link footer matches new version |
+| `pyproject.toml` + `src/gflow_cli/__init__.py` | Both set to the new version |
+| `docs/PROJECT_STATUS.md` | "Current release" subsection + milestone-history row for this version |
+
+Quick grep:
+
+```bash
+grep -rn "v[0-9]\+\.[0-9]" README.md AGENTS.md llms.txt CLAUDE.md PLAN.md KNOWN_ISSUES.md CHANGELOG.md pyproject.toml docs/PROJECT_STATUS.md
+```
+
+Historical references in `CHANGELOG.md`, `docs/LIVE_VERIFICATION_v*.md`, and milestone-history rows in `docs/PROJECT_STATUS.md` are allowed.
+
+---
+
+## 2 · `docs/INDEX.md` completeness
+
+Every `.md` in `docs/` needs an entry; every entry must point to a real file. AGENTS.md and llms.txt also need rows since they are agent-facing entry points.
+
+```bash
+# Files in docs/ missing from INDEX.md
+for f in docs/*.md; do
+  grep -q "$(basename "$f")" docs/INDEX.md || echo "MISSING from INDEX: $f"
+done
+
+# Entries in INDEX.md pointing to deleted files
+grep -o 'docs/[^)]*\.md' docs/INDEX.md | while read path; do
+  [ -f "$path" ] || echo "DEAD LINK in INDEX: $path"
+done
+
+# AGENTS.md, llms.txt rows present?
+grep -E "AGENTS\.md|llms\.txt" docs/INDEX.md || echo "MISSING: agent-facing root files row"
+```
+
+---
+
+## 3 · Per-release evidence file
+
+After each release a `docs/LIVE_VERIFICATION_vX.Y.Z.md` must exist.
+
+- Latest version has one (create stub if live run already documented elsewhere).
+- `docs/INDEX.md` "latest release" cue points to it.
+- Previous versions' files are preserved (historical record — never delete).
+- File contains both a **Pre-tag gates** section (filled before signing) and a **Post-tag evidence** section (filled after publish).
+
+---
+
+## 4 · Doc-link validation
+
+Run the link checker:
+
+```powershell
+$env:PYTHONUTF8=1
+uv run python scripts/ci/check_doc_links.py
+```
+
+Expected: `All links resolved across N files.` (exit 0). Broken links must be fixed in source docs before continuing — do not edit the script to ignore them.
+
+If `scripts/ci/check_doc_links.py` is absent, create it from the v0.8.1 plan (it is a 30-line stdlib-only Python script).
+
+---
+
+## 5 · `.claude/commands/gflow/` skill files
+
+Scan all skills for stale phase/version references:
+
+```bash
+grep -rn "v[0-9]\+\.[0-9]\|Phase [A-Z0-9]" .claude/commands/gflow/
+```
+
+Update in the release prep commit if any references are wrong. The `release.md` skill's step list and the `plan.md` skill's phase pointers age fastest.
+
+---
+
+## 6 · CHANGELOG link footer
+
+```bash
+tail -10 CHANGELOG.md
+```
+
+Must read: `[Unreleased]: …compare/vNEW_VERSION…HEAD` and each prior `[X.Y.Z]: …compare/vPREV…vCURR`.
+
+---
+
+## 7 · Memory files
+
+Check `C:\Users\ffrol\.claude\projects\C--development-github-gflow-cli\memory\`:
+
+| File | What to verify |
+|---|---|
+| `MEMORY.md` | All listed files exist; no dangling entries |
+| `phase-b-followups.md` | Items shipped in this release marked done |
+| `video-generation-spec.md` | PR/status accurate |
+| `image-generation-401-next.md` | Resolution status and evidence pointer still valid |
+| `release-signing.md` | Procedure section matches what was actually done |
+| `release-back-merge-gap-recovery.md` | Still relevant; gap from any prior release recorded |
+
+```bash
+cd "C:\Users\ffrol\.claude\projects\C--development-github-gflow-cli\memory"
+grep -o '\[.*\]([^)]*\.md)' MEMORY.md | grep -o '([^)]*)' | tr -d '()' | while read f; do
+  [ -f "$f" ] || echo "DEAD LINK: $f"
+done
+```
+
+---
+
+## 8 · LLM council audit (NEW — required for every release ≥ v0.8.1)
+
+The mechanical checks above catch stale strings, dead links, and missing files. They do **not** catch:
+
+- A doc claiming a subpackage exists when it does not (no string sweep would notice).
+- Two docs covering the same topic with subtly different facts.
+- A working-looking hero snippet that points to a stub command (`gflow video i2v` returned "not yet available" but appeared as a production loop above the fold in v0.8.1).
+- A user-facing onboarding gap that a fresh reader would hit immediately.
+
+The council does. Dispatch three review subagents **in parallel** (they are read-only and independent). Each writes its verdict to `tmp/council/`.
+
+### Setup
+
+```bash
+mkdir -p tmp/council
+```
+
+### Auditor 1 — Completeness
+
+Role: as a fresh user / fresh AI agent, **what do you need that isn't there?**
+
+Audit:
+- `README.md`, `AGENTS.md`, `llms.txt`, `CLAUDE.md`, `docs/INDEX.md`, `docs/PROJECT_STATUS.md`
+- `docs/ARCHITECTURE.md` (especially any new sections)
+- `docs/LIVE_VERIFICATION_v*.md` (latest)
+- `CHANGELOG.md` (just the new entry)
+- `pyproject.toml`
+- The release spec at `docs/superpowers/specs/` (if present)
+- The implementation plan at `docs/superpowers/plans/` (if present)
+
+Output to `tmp/council/01-completeness.md` with verdict GREEN / YELLOW / RED and four sections:
+1. Critical gaps (block release)
+2. Important gaps (fix before next release)
+3. Nice-to-haves (track for next version)
+4. What's done well (preserve)
+
+### Auditor 2 — Cross-reference & alignment
+
+Role: do the docs **agree with each other**? Where two files cover the same topic, do they say the same thing?
+
+Check:
+- Install instructions, auth flow, headed-browser story, version number, Python requirement — all match exactly?
+- Internal `[X](path)` links — files exist AND claims at the link target equivalent to the linking-doc's claim?
+- Routing chain (README → AGENTS.md → CLAUDE.md → docs/INDEX.md) — consistent? Any contradictions?
+- CHANGELOG vs PROJECT_STATUS — milestone history matches changelog entries?
+- Spec vs implementation — does the shipped state match the design spec?
+
+Output to `tmp/council/02-crossref.md` with verdict + four sections (inconsistencies / drift / broken anchors / well-aligned).
+
+### Auditor 3 — Drift & staleness
+
+Role: does the documentation match the actual code and project state? **Where are claims unverifiable, contradicted by reality, or referencing things that no longer exist?**
+
+Check empirically (every claim needs `ls` / `grep` / `cat` evidence cited inline):
+- Version claims — `pyproject.toml`, `__init__.py`, every "v0.8.1 — alpha" statement agree?
+- Module / file claims — every `src/gflow_cli/{...}` module list verified against the actual source tree?
+- Subpackage claims (e.g., `experimental/`) — do those directories exist?
+- CLI command claims in hero snippets — is the subcommand really implemented? Does it actually do what the example shows, or is it a stub?
+- Exit-code claims — verify the range against `errors.py::EXIT_CODE_MAP`.
+- Skill files, GIF assets, slash-command files — exist at the paths claimed?
+
+Output to `tmp/council/03-drift.md` with verdict + three sections (fictional claims / stale references / verified-real).
+
+### Consensus
+
+After all three reports return:
+
+1. Read all three. List every distinct finding.
+2. Tier the findings:
+   - **Tier 1 (release-blocking)** — any RED verdict, any "block release" finding, any fictional claim that ships to PyPI.
+   - **Tier 2 (important polish)** — drift between related docs, minor mismatches, missing-but-recoverable references.
+   - **Tier 3 (track for later)** — nice-to-haves, prose improvements, deferred features.
+3. Apply Tier 1 fixes immediately (block the release until done).
+4. Apply Tier 2 fixes if the release schedule permits, otherwise open issues.
+5. Tier 3 → backlog (memory `phase-X-followups.md` or a new GitHub issue).
+
+Synthesize a single fix-plan comment under the relevant `LIVE_VERIFICATION_vX.Y.Z.md` `Pre-tag gates` entry for `/gflow:doc-review`:
+
+> _Council verdict: <GREEN|YELLOW|RED> across all 3 auditors. <N> findings; <M> Tier 1 fixed in commit <SHA>, <K> Tier 2 fixed in commit <SHA2>, <J> Tier 3 deferred to backlog. Council reports at `tmp/council/0{1,2,3}-*.md` (local-only)._
+
+If any auditor returns RED, **stop and escalate to the user**. Do not apply fixes blindly to a RED finding — it usually means the doc is wrong about the code, the code is wrong about the doc, or both.
+
+---
+
+## Output format
+
+After each section write one line:
+
+```
+[0] Pre-flight        — PASS (release spec at docs/superpowers/specs/YYYY-MM-DD-*.md)
+[1] Version refs      — PASS
+[2] INDEX completeness — UPDATED (added AGENTS.md row)
+[3] Evidence file     — PASS
+[4] Doc-link check    — PASS (9 files, 0 broken)
+[5] Skill files       — UPDATED (refreshed /gflow:plan phase pointer)
+[6] CHANGELOG footer  — PASS
+[7] Memory files      — WARN: phase-b-followups.md has shipped items not yet ticked
+[8] Council audit     — YELLOW (11 findings, all fixed in commit abc1234)
+```
+
+Then list every **UPDATED** change, every **WARN** / **FAIL** finding, and the council fix list for the user to review.
+
+---
+
+## Integration with `/gflow:release`
+
+This skill is invoked at **step 9** of `/gflow:release` (between "review commands for staleness" and "commit the release prep"). The mechanical pass (sections 1–7) is the same as before; the council audit (section 8) is the new requirement and runs after the mechanical pass succeeds.
+
+All discovered fixes are folded into the release prep commit unless genuinely unrelated to the release.
+
+---
+
+## Post-release: memory consolidation
+
+After the release ships and the back-merge completes, the **release spec** and **implementation plan** under `docs/superpowers/{specs,plans}/` are project-management artifacts, not user-facing docs. The durable knowledge they contain (patterns learned, governance rules, architecture decisions) should be extracted into project memory at `~/.claude/projects/<...>/memory/`, then the spec/plan files **deleted from the repo** in a final cleanup commit.
+
+This keeps the public-facing `docs/` tree focused on what users and contributors need, while the planning artifacts live on as memory entries usable by future Claude Code sessions. See the `release-back-merge-gap-recovery` memory and the v0.8.1 release commit history for an example.

{gflow_cli-0.8.0 → gflow_cli-0.9.0}/.env.template

@@ -77,3 +77,12 @@
 # (Google's bot-detection sometimes refuses headless Chromium but accepts a
 # visible window). The session is still reused from the persistent profile.
 # GFLOW_CLI_HEADLESS=true
+
+# BCP-47 locale tag passed to Playwright's launch `locale=` parameter
+# (controls Accept-Language only — Chrome's UI language is forced to
+# en-US via the `--lang=en-US` launch arg regardless of this setting, so
+# Flow stays on /fx/tools/flow/ instead of /fx/<locale>/). Default:
+# `en-US`. Override to capture locale-invariant DOM via
+# scripts/dev/capture_locale_invariants.py or to live-verify a non-EN
+# language end-to-end (see KNOWN_ISSUES § issue #24).
+# GFLOW_CLI_LOCALE=en-US

gflow_cli-0.9.0/AGENTS.md

@@ -0,0 +1,78 @@
+# AGENTS.md — gflow-cli
+
+> Universal entry point for AI coding agents. Read this first; everything else routes from here.
+
+Supported tools that auto-discover this file: Cursor, Codex, Aider, Gemini CLI, Jules, Devin, Windsurf, Zed, Warp, opencode, RooCode, Amp, Junie, Phoenix, GitHub Copilot, VS Code, Factory, Augment, Semgrep, Kilo Code, UiPath. Claude Code reads [CLAUDE.md](CLAUDE.md), which cross-references this file.
+
+## Project at a glance
+
+- Unofficial Python CLI for [Google Flow](https://labs.google/fx/tools/flow) — drives Veo (image-to-video, text-to-video) and Imagen (text-to-image) generations from the terminal by reverse-engineering Flow's private REST API at `aisandbox-pa.googleapis.com`.
+- Python 3.11+ · `uv`-managed · `hatchling` builds · Playwright Chromium transport · `pyright` strict · `ruff` · `pytest`.
+- Single-package modular monolith. Top-level modules under `src/gflow_cli/`: `api/`, `auth/`, `browser_manager.py`, `cli.py`, `_cli_helpers.py`, `cli_data.py`, `cli_image.py`, `cli_run.py`, `cli_video.py`, `config.py`, `data/`, `errors.py`, `exceptions.py`, `image_batch.py`, `manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
+- Requires a Google AI Ultra or Pro subscription with Flow access. All generations bill against the user's own Google account.
+
+## Headed-browser dependency (architectural reality)
+
+gflow-cli currently drives Flow via a **real Chrome session managed by Playwright** — `ui_automation` transport. Google's auth + reCAPTCHA stack rejects Playwright's bundled Chromium and most headless approaches. This is the project's defining trade-off:
+
+- ✅ Works end-to-end against live Pro/Ultra accounts.
+- ❌ Requires a saved Chrome profile, a display server for one-time login, and ~150 MB for Chromium.
+- ❌ Cannot run on serverless / headless CI workers without prerecorded profile transplant.
+- ❌ Per-account horizontal concurrency is capped by what one warm Page pool can drive.
+
+If you can help unblock a pure HTTP transport (especially for video generation, where HTTP 401 + reCAPTCHA mints currently block us), please open an issue — see the README "Architecture & current limitations" section.
+
+## Dev environment tips
+
+- `uv sync` then `uv run playwright install chromium`. No global Python install needed.
+- Copy `.env.template` to `.env.local`; never commit `.env.local`. It documents every env var.
+- Output goes to `./tmp/` for scripts/tests or `$GFLOW_CLI_OUTPUT_DIR` for CLI outputs (defaults to `./out/`).
+- One-time auth: `gflow auth login --browser chrome`. The `--browser chrome` flag is mandatory; the CLI fails fast on other strategies.
+- Use `/gflow:plan` to see the active phase before starting work; `/gflow:known-issues` before touching auth or reCAPTCHA code paths.
+
+## Testing instructions — The Impeccable Routine
+
+Run these gates in order before every commit:
+
+```powershell
+$env:PYTHONUTF8=1
+uv run python scripts/ci/check_repo_hygiene.py
+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`.
+
+- Use `pytest -m "not live and not e2e"` 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.
+- Live tests (`@pytest.mark.live`) opt in via `GFLOW_LIVE=1`. E2E tests require `GFLOW_CLI_E2E_PROFILE`.
+
+## Code style
+
+- Type hints everywhere; `pyright` strict on `src/gflow_cli`.
+- Structured logging only (`structlog`) — **never** raw `print()` or `import logging` in `src/`.
+- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–16, where 16 is the `DataStoreError` family from `gflow_cli.data`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
+- 100-char line length, `ruff` configured. Imports sorted by `ruff` (isort rules).
+
+## PR instructions
+
+- Branch naming: `feature/`, `bugfix/`, `hotfix/`, `chore/`, `docs/`, `test/`, `release/` — never `claude/` or unprefixed.
+- `develop` is the integration branch; `main` is protected. Releases tag off `main` only.
+- **Never add AI attribution to commit messages.** `Co-Authored-By:` trailers are fine if the user asks for them; auto-generated "🤖 Generated with Claude Code" footers are not.
+- 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.
+
+## Where to look next
+
+- **Architecture & target shape** → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- **Mandates & routing rules** → [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md)
+- **Full docs index** → [docs/INDEX.md](docs/INDEX.md)
+- **Known issues** (read before touching auth / reCAPTCHA) → [KNOWN_ISSUES.md](KNOWN_ISSUES.md)
+- **Active phase & backlog** → [PLAN.md](PLAN.md) or run `/gflow:plan`
+- **Release protocol** → [RELEASE.md](RELEASE.md)
+
+## Claude Code-specific notes
+
+[CLAUDE.md](CLAUDE.md) carries the auto-load instructions Claude Code reads natively. It cross-references this file for the universal rules; Claude-Code-specific session protocol (skills, slash commands, memory) stays in CLAUDE.md.

{gflow_cli-0.8.0 → gflow_cli-0.9.0}/CHANGELOG.md

@@ -7,6 +7,142 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] — 2026-05-25
+
+> **Maturity & Visibility release.** Surfaces the SQLite catalog (PR #52/#58)
+> via a read-only `gflow data list {projects,images,videos,profiles}` CLI,
+> publishes `ROADMAP.md`, and ships the locale-agnostic media-dialog
+> selectors that unblock non-English Chrome profiles. Plus the previously-
+> unreleased video model picker, i2v/r2v, and the I2I ref-attach + model-
+> select fixes. Sponsorship wiring will land in a follow-up patch release
+> once GitHub Sponsors / Buy Me a Coffee accounts are fully provisioned.
+
+### Added
+
+- `gflow data list {projects,images,videos,profiles}` — read-only catalog
+  query CLI over the local SQLite data layer. Flags: `--limit` (1..1000,
+  default 20), `--offset` (≥0, default 0), `--profile NAME`, `--json`.
+  Rich table on TTY, JSONL on pipe or `--json`. Default sort: newest first.
+  `DataStoreError` family maps to exit code 16. See
+  [`docs/DATA_LAYER.md § Querying the data layer`](docs/DATA_LAYER.md#querying-the-data-layer).
+- `ROADMAP.md` at repo root — themed milestones from v0.9 through v1.0 (no
+  dates).
+- `gflow video t2v` model picker: `--model` (`omni-flash` | `veo-lite` |
+  `veo-fast` | `veo-quality` | `veo-lite-lp`), `--duration` (`4`/`6`/`8`, plus
+  `10` for `omni-flash` only), and `--count` (1–4). Driven via the editor's
+  generation-settings panel; live-verified against a Pro/Ultra profile.
+- `gflow video i2v <image> "<prompt>"` — image-to-video with a start frame and
+  an optional `--end-image` (interpolation). Fires
+  `batchAsyncGenerateVideoStartImage` / `…StartAndEndImage`.
+- `gflow video r2v "<prompt>" --ref <img> [--ref …]` — reference-to-video
+  (Flow "ingredients"). Model-aware reference cap (omni_flash ≤7, veo_3_1_* ≤3)
+  enforced in the request DTO; the transport stops gracefully if Flow hides the
+  add-media button at the cap. Fires `batchAsyncGenerateVideoReferenceImages`.
+- `GFLOW_CLI_LOCALE` env var — overrides Playwright's launch `locale=` parameter
+  (default: `en-US`). Controls `Accept-Language` only; Chrome's UI language is
+  still forced to en-US via `--lang=en-US`. Prep for issue #24 (locale-agnostic
+  selectors); live-verified end-to-end with `GFLOW_CLI_LOCALE=pt-BR` against a
+  Pro/Ultra account. See `docs/CONFIGURATION.md § GFLOW_CLI_LOCALE`.
+- **Local data layer** — `gflow-cli` now keeps a SQLite catalog of every new
+  image, batch, and video operation under `$GFLOW_CLI_DB_PATH` (default:
+  `~/.local/share/gflow-cli/data.db`). Records profile, project, asset
+  (model / aspect / dimensions / Flow media ID), operation provenance
+  (mode / prompt / model / timing / error), input↔output links, and
+  downloaded local files. New `gflow data media <id>` command resolves a
+  Flow media ID to its origin. `DataRepository` exposes seed-image resolvers
+  (`resolve_seed_image_by_path` / `resolve_seed_image` /
+  `resolve_latest_image`) — foundation for the upcoming I2V seed-reuse
+  path. Pre-Flow store failures exit `16` (`DataStoreError` /
+  `DataMigrationError` / `DataIntegrityError`); post-success store
+  failures warn and exit `0` (Flow already charged the credits). See
+  [`docs/DATA_LAYER.md`](docs/DATA_LAYER.md). (PR #58, stacked on #52.)
+
+### Changed
+
+- `MAX_REFERENCE_IMAGES` (in `api/video.py`) now tracks the `omni_flash`
+  ceiling of **7** (was **3**). The tighter per-model cap (`veo_3_1_* ≤ 3`) is
+  still enforced in `GenerateVideoRequest.__post_init__` when the model is
+  known; the constant is only the absolute upper bound. Anyone pinning to the
+  old value of 3 should re-check against the per-model caps.
+
+### Fixed
+
+- `FlowApiClient.__aenter__` now tears down a partially-launched browser if any
+  step after the Playwright driver starts raises (e.g. the persistent-context
+  launch, the bootstrap navigation, or `transport.setup`). Python does not call
+  `__aexit__` when `__aenter__` raises, so an unguarded failure orphaned the
+  chrome process, which then held the profile's user-data-dir lock — the next
+  run could not acquire it and spiralled into rapid `about:blank` tabs +
+  `TargetClosedError`. Context close + driver stop are now shared by
+  `__aenter__`'s guard and `__aexit__` via `_close_browser_resources`.
+- `gflow image i2i --ref <local-file>` now binds the reference through the
+  editor's media dialog instead of the REST `uploadImage` endpoint (which 401s —
+  same root as #15/#39). Local-path refs ride a new `GenerateImageRequest.ref_paths`
+  field and are attached via the inherited R2V `_attach_references` (the image-mode
+  add-media dialog is the same `add_2` surface). Bare-UUID `--ref` still flows
+  through `refs` unchanged. Re-introduces #50 (reverted in #57 for the account/
+  locale variant tracked in #56); the media-dialog selectors are now
+  locale-agnostic (see the next entry).
+- The media-dialog upload selectors are now **locale-agnostic** (issue #56/#24).
+  `UPLOAD_MEDIA_BUTTON` matched localized text (`has-text('Upload media')`), so on
+  a non-English Chrome profile (Flow follows the *Chrome profile* language, which
+  the `--lang=en-US` arg cannot override) the click missed and the file chooser
+  never opened — a silent ~34s hang. It now anchors on the locale-free `upload`
+  icon ligature (`:text-is('upload')`, exact, so it doesn't grab the `Uploads`
+  tab), with the original English-text selector kept as a graceful **fallback
+  tier** (matches if Google ever changes the icon but keeps the English label);
+  'Add to Prompt' (which has no icon) is selected structurally as the only
+  iconless button in the open dialog. If neither tier opens a chooser,
+  `_upload_via_open_dialog` raises a clear error + writes a screenshot (no silent
+  hang) and points the operator at the Chrome-profile-language workaround. Fixes
+  I2I/I2V/R2V upload alike.
+- `gflow image t2i/i2i --model` now actually selects the requested model. It was
+  a no-op under `ui_automation` (the wire field was set but the model picker was
+  never clicked, so Flow used its UI default). Adds `_select_image_model`.
+- Video selector mismatches: the output-count selector `[id*=-trigger-1]`
+  collided with the `-trigger-10` duration tab; the aspect selector matched a
+  non-existent `aria-controls*=9_16`; the video-mode tab match was ambiguous.
+  All now use exact `[id$=-trigger-X]` suffixes + aria-label text.
+
+### Build
+
+- **Wheel build no longer emits duplicate ZIP entries.** An earlier attempt at
+  tagging v0.9.0 was rejected by PyPI with HTTP 400 ("Duplicate filename in
+  local headers") because `pyproject.toml` had
+  `[tool.hatch.build.targets.wheel.force-include]` and
+  `[tool.hatch.build.targets.sdist.force-include]` blocks pointing at
+  `src/gflow_cli/data/migrations`, on top of the already-comprehensive
+  `packages = ["src/gflow_cli"]` directive — hatchling included the
+  migrations directory twice (both `__init__.py` and `0001_initial.sql`). The
+  force-include blocks have been removed; hatchling's default package
+  inclusion already covers `.sql` files inside the package tree. (PR #74.)
+
+### Notes
+
+- I2V/R2V image inputs bind through the editor's media dialog (frame slot /
+  add-media → "Upload media" → file chooser → "Add to Prompt"). `set_input_files`
+  on the generic hidden input only adds to the library and Flow then ignores the
+  image (plain Text route). The editor is forced to English via the
+  `--lang=en-US` Chromium launch arg because the slot/dialog labels are localized
+  with no locale-free anchor.
+
+## [0.8.1] — 2026-05-23
+
+### Documentation
+
+- README rewritten as a hybrid router (~150 lines, was 398). New: prominent unofficial-tool + headed-browser callouts above the fold, polished 60-second quick start, in-depth-quick-start link, "For AI agents & LLMs" routing table, ripgrep-style documentation TOC.
+- New [AGENTS.md](AGENTS.md) at repo root — universal agent spec consumed by 60k+ repos' tooling (Cursor, Codex, Aider, Gemini CLI, Claude Code, Copilot, opencode, etc.). Closes the gap left by having Claude-Code-only memory.
+- New [llms.txt](llms.txt) at repo root — llmstxt.org-format summary for end-users feeding the project into an LLM. Forward-staged for a future docs site.
+- New [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md) — moved the full milestone table out of README; added lifecycle policy section.
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) absorbed the ASCII system diagram + Auth strategy paragraphs from README; gained a new "Headed-browser dependency — current limitation" subsection that documents the three retired HTTP transports and invites contributor work on a pure-REST path.
+- [CLAUDE.md](CLAUDE.md) trimmed from ~80 to ~25 lines; universal coding-agent rules now live in AGENTS.md, with CLAUDE.md carrying Claude-Code-specific session protocol only.
+- All `v0.7.0` references that meant "current" updated to `v0.8.1`. Historical mentions preserved in CHANGELOG and `docs/LIVE_VERIFICATION_v0.7.0.md`.
+- New per-release evidence file [docs/LIVE_VERIFICATION_v0.8.1.md](docs/LIVE_VERIFICATION_v0.8.1.md).
+
+### Released
+
+- PyPI: https://pypi.org/project/gflow-cli/0.8.1/ — refreshes the stale README rendering left over from v0.8.0.
+
 ## [0.8.0] — 2026-05-23
 
 > **Multi-image-prompt release + transport hardening.** Introduces the
@@ -809,7 +945,9 @@ 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.8.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/ffroliva/gflow-cli/compare/v0.8.1...v0.9.0
+[0.8.1]: https://github.com/ffroliva/gflow-cli/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/ffroliva/gflow-cli/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/ffroliva/gflow-cli/compare/v0.6.0a6...v0.7.0
 [0.6.0a6]: https://github.com/ffroliva/gflow-cli/compare/v0.6.0a5...v0.6.0a6

gflow_cli-0.9.0/CLAUDE.md

@@ -0,0 +1,27 @@
+# CLAUDE.md
+
+> Project memory hub for **Claude Code**. The universal coding-agent rules for any tool (Cursor, Codex, Aider, Gemini CLI, etc.) live in [AGENTS.md](AGENTS.md) — this file carries Claude-Code-specific session protocol only.
+
+## What this project is
+
+`gflow-cli` is an unofficial Python CLI that drives [Google Flow](https://labs.google/fx/tools/flow) (Veo image-to-video, Imagen text-to-image) from the terminal by reverse-engineering Flow's private REST API. See [README.md](README.md) for the user-facing overview.
+
+## On every session start
+
+1. Read **[AGENTS.md](AGENTS.md)** — universal rules every agent must follow.
+2. Read **[docs/INDEX.md](docs/INDEX.md)** — routing layer for all project docs and commands.
+3. Pull deeper context on demand:
+   - Starting a feature → `/gflow:plan`
+   - Touching auth or reCAPTCHA → `/gflow:known-issues`
+   - Cutting a release → `/gflow:release`
+   - Before any commit → `/gflow:check`
+
+## Claude-Code-specific
+
+- Slash commands live under `.claude/commands/gflow/` (all prefixed `/gflow:`).
+- 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.
+
+## Active phase
+
+See [PLAN.md](PLAN.md) or run `/gflow:plan` for the current detailed plan.

{gflow_cli-0.8.0 → gflow_cli-0.9.0}/KNOWN_ISSUES.md

@@ -319,7 +319,21 @@ issue and not blocked by any code change in this repo.
 
 - **Status:** Mitigated · **Severity:** Medium · **Tracking:** [issue #24](https://github.com/ffroliva/gflow-cli/issues/24)
 
-The Phase 7 multi-image-prompt work addressed the count-tab selectors:
+**Progress (2026-05-24, develop / post-v0.8.1, unreleased):**
+
+- **PR #51** — Playwright's launch `locale=` is now env-overridable via
+  `GFLOW_CLI_LOCALE` (default: `en-US`). Live-verified end-to-end with
+  `GFLOW_CLI_LOCALE=pt-BR uv run pytest -m e2e tests/e2e/test_video_t2v_e2e.py`
+  (1 credit, ~2.5 MB mp4, `MEDIA_GENERATION_STATUS_SUCCESSFUL`).
+- **PR #48** — added the `--lang=en-US` Chromium launch arg so the editor UI
+  itself stays in English regardless of the user's profile/system language.
+  Currently mandatory because the I2V frame-slot labels and parts of
+  `ONBOARDING_SELECTORS` / `NEW_PROJECT_SELECTORS` / `SUBMIT_BUTTON_SELECTORS`
+  still match by localized text. Dropping `--lang=en-US` is the goal but
+  requires invariant capture across the remaining text-matched selectors
+  (`scripts/dev/capture_locale_invariants.py` is the diagnostic).
+
+**Earlier — Phase 7 multi-image-prompt work** addressed the count-tab selectors:
 - `_COUNT_TAB_TEXT_RE = ^(1x|x[2-4])$` only matches the digit+x format Flow
   renders identically in every locale (numbers/symbols are not translated).
 - `_set_count` falls back to positional `.nth(count - 1)` when the read-back
@@ -343,6 +357,34 @@ in English or Portuguese.
 
 ---
 
+### `omni-flash` t2v response omits operation name — `flow_operation_id` persists NULL
+
+- **Status:** Open · **Severity:** Low · **Affects:** v0.9.0+ (data layer)
+
+The data layer's `on_started` callback captures
+`operations[0].operation.name` from each `batchAsyncGenerateVideoText`
+response and persists it as `operations.flow_operation_id`. The
+`omni-flash` model's response shape does not carry that field, so
+omni-flash rows end up with `flow_operation_id` NULL while `veo-*` rows
+carry the expected `operations/...` identifier. The rest of the row
+(prompt, model, aspect, started/completed timestamps, batch ID, output
+paths) is recorded normally.
+
+**Impact:** cosmetic for now — `gflow data media <id>` and provenance
+lookup by Flow media ID still work. Any future feature that joins on
+`flow_operation_id` (none in the current CLI) would miss omni-flash
+rows.
+
+**Workaround:** none needed if you don't query by `flow_operation_id`.
+
+**Roadmap:** capture an `omni-flash` `batchAsyncGenerateVideoText`
+response sample, identify the equivalent provenance handle (if any), and
+either map it into `flow_operation_id` or document that omni-flash
+legitimately has no such identifier. Track via a follow-up issue once a
+sample is captured.
+
+---
+
 ## Mitigated
 
 ### Auth verification depends on Google's NextAuth session endpoint
@@ -364,6 +406,23 @@ change surfaces there as a failing test. Start any investigation of a sudden
 
 ## Resolved
 
+### `gflow image t2i/i2i --model` was a silent no-op on `ui_automation`
+
+- **Status:** Resolved · **Severity:** Was-Medium (wrong model = wrong cost + quality, silently) · **Was-affecting:** v0.7.0 through v0.8.1 · **Fixed in:** develop post-v0.8.1 via PR #48 (2026-05-24)
+
+Pre-fix, `gflow image t2i --model nano-banana-2` (or any other model) under
+`ui_automation` would set the wire-level model field correctly but **never
+click the model picker in the editor UI**, so Flow used whichever model the
+UI's dropdown was last set to (typically the account default). Users got
+their requested model silently substituted for the default — no error, just
+wrong output and wrong credit cost. Fixed by `_select_image_model` in
+`src/gflow_cli/api/transports/ui_automation.py` which mirrors the new
+`_select_video_model` helper. If you ran `gflow image t2i --model <X>`
+against v0.7.0–v0.8.1 and noticed the output didn't match `<X>`, this is
+why; re-run on the next release (≥ v0.9.0).
+
+---
+
 ### aisandbox-pa generation 401 — bypassed by the `ui_automation` transport
 
 - **Status:** Resolved · **Severity:** Was-High (blocked image gen via HTTP transports) · **Fixed in:** v0.7.0