gflow-cli 0.4.0a2__tar.gz → 0.5.0a1__tar.gz

{gflow_cli-0.4.0a2 → gflow_cli-0.5.0a1}/.claude/commands/release.md

@@ -9,8 +9,8 @@ You are about to release a new version of `gflow-cli`. Follow this sequence verb
 ## Inputs
 
 Ask the user (if not already provided):
-1. **Version** — the new SemVer (e.g. `0.2.0`, `0.2.0a1`, `1.0.0-rc1`). If they don't know, look at the latest entry in `CHANGELOG.md` `[Unreleased]` and propose the next bump (PATCH for fixes only, MINOR for new features, MAJOR for breaks).
-2. **Pre-release?** — `0.x.y` is alpha by definition. Only the user can say if a `0.x.y-rc1` should ship.
+1. **Version** — the new version (e.g. `0.4.0`, `0.4.0a3`, `1.0.0rc1`). Use PEP 440 prerelease suffixes (`aN`, `bN`, `rcN`) for Python package releases. If they don't know, look at the latest entry in `CHANGELOG.md` `[Unreleased]` and propose the next bump (PATCH for fixes only, MINOR for new features, MAJOR for breaks).
+2. **Pre-release?** — prerelease versions such as `0.4.0a3` should stay marked as GitHub prereleases. Only the user can say when a release line is ready for the stable tag, such as `0.4.0`.
 
 ## Sequence
 
@@ -41,7 +41,17 @@ Ask the user (if not already provided):
    version = "<NEW_VERSION>"
    ```
 
-5. **Update `CHANGELOG.md`:**
+5. **Bump package version** in `src/gflow_cli/__init__.py`:
+   ```python
+   __version__ = "<NEW_VERSION>"
+   ```
+
+6. **Update version assertion tests** if present:
+   ```bash
+   rg -n "__version__|<OLD_VERSION>|version assertion" tests src pyproject.toml
+   ```
+
+7. **Update `CHANGELOG.md`:**
    - Move all entries under `## [Unreleased]` to a new `## [<NEW_VERSION>] — YYYY-MM-DD` section.
    - Leave `## [Unreleased]` empty.
    - Update the link footer:
@@ -50,24 +60,24 @@ Ask the user (if not already provided):
      [<NEW_VERSION>]: https://github.com/ffroliva/gflow-cli/releases/tag/v<NEW_VERSION>
      ```
 
-6. **Commit the release prep.**
+8. **Commit the release prep.**
    ```bash
-   git add pyproject.toml CHANGELOG.md
-   git commit -m "release: v<NEW_VERSION>"
+   git add pyproject.toml src/gflow_cli/__init__.py CHANGELOG.md tests
+   git commit -m "chore(release): v<NEW_VERSION>"
    ```
 
-7. **Tag.** Pre-release tags include `-rc*` / `-alpha*` / `-beta*`:
+9. **Tag.** PEP 440 prerelease tags include `aN` / `bN` / `rcN`:
    ```bash
    git tag -a v<NEW_VERSION> -m "v<NEW_VERSION>"
    ```
 
-8. **Push commit + tag.**
+10. **Push commit + tag.**
    ```bash
    git push origin main
    git push origin v<NEW_VERSION>
    ```
 
-9. **Report.** Tell the user:
+11. **Report.** Tell the user:
    - The pushed tag triggers `.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.
@@ -82,5 +92,6 @@ Ask the user (if not already provided):
 
 ## See also
 
-- [README § Releases](../../README.md#releases) — full release policy & cadence
+- [RELEASE.md](../../RELEASE.md) — full release protocol, prerelease policy, and checklist
+- [README § Releases](../../README.md#releases) — short release policy & cadence
 - [PLAN § Phase 5](../../PLAN.md#phase-5--public-alpha-release-on-pypi) — first-release exit criteria

{gflow_cli-0.4.0a2 → gflow_cli-0.5.0a1}/.github/workflows/ci.yml

@@ -32,4 +32,11 @@ jobs:
         run: uv run pyright src
 
       - name: Test (smoke only)
-        run: uv run pytest -q
+        # e2e tests (tests/e2e/) require a logged-in `denon82` Chromium profile
+        # and live Flow auth — never runnable in CI. They self-mark with
+        # `pytestmark = pytest.mark.e2e` (file-level) and are opt-in via
+        # `-m e2e` per their module docstring. `live` marker is reserved for
+        # `GFLOW_LIVE=1` tests that hit the real Flow API. Both are excluded
+        # from the default smoke run; `tests/smoke/test_real_flow.py` already
+        # self-skips via `pytest.mark.skipif(GFLOW_E2E != "1")`.
+        run: uv run pytest -q -m "not e2e and not live"

{gflow_cli-0.4.0a2 → gflow_cli-0.5.0a1}/.github/workflows/release.yml

@@ -50,4 +50,8 @@ jobs:
         with:
           generate_release_notes: true
           files: dist/*
-          prerelease: ${{ contains(github.ref_name, '-') }}
+          # Pre-release detection covers both conventions:
+          #   - semver suffixes:  v1.2.3-alpha1, v1.2.3-rc1, v1.2.3-beta1   (any '-' qualifies)
+          #   - PEP 440 suffixes: v1.2.3a1, v1.2.3b1, v1.2.3rc1             (any 'a' / 'b' / 'rc')
+          # Stable tags like v1.2.3 contain none of these substrings.
+          prerelease: ${{ contains(github.ref_name, '-') || contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}

{gflow_cli-0.4.0a2 → gflow_cli-0.5.0a1}/.gitignore

@@ -48,6 +48,13 @@ tmp/
 !tests/fixtures/**/*.png
 samples/*.captured.json # sandbox-recorded API exchanges may contain PII
 
+# Live Flow traffic captures — NEVER commit (contain real Bearer tokens / API keys).
+# Diagnostic scripts MUST default-write here, NOT to samples/captured/.
+# Sanitised reference samples (no secrets) can still live under samples/captured/.
+tmp/captured/
+samples/captured/flow_outgoing_*.jsonl
+samples/captured/flow_outgoing_*.json
+
 # Claude Code worktrees and lock files
 .claude/worktrees/
 .claude/scheduled_tasks.lock

gflow_cli-0.5.0a1/.planning/todos/pending/2026-05-11-add-project-logo-and-docs-site-promotion-plan.md

@@ -0,0 +1,38 @@
+---
+created: 2026-05-11T11:34:56.295Z
+title: Add project logo and docs site promotion plan
+area: docs
+files:
+  - README.md:18
+  - README.md:365
+  - RELEASE.md:1
+  - docs/INDEX.md:10
+---
+
+## Problem
+
+The project is now public on GitHub and PyPI and has enough release/process
+surface to benefit from a more polished presentation. The README was cleaned up
+with working badges and a public `RELEASE.md`, but the next promotion step is
+still undecided: whether to add a logo/social preview, whether to create a
+GitHub Pages documentation site, and which static-docs stack to use.
+
+Jekyll is available on GitHub Pages, but for this Python CLI project the better
+default is likely MkDocs Material: it fits Markdown-heavy CLI docs, has search
+and navigation, and can publish to GitHub Pages cleanly. This should wait until
+after the current prerelease E2E validation, because the real launch gate is
+runtime confidence, not site polish.
+
+## Solution
+
+After E2E validation, decide a small promotion package:
+
+1. Add a simple project logo and GitHub social preview image.
+2. Keep README as the landing page and make the first screen clear for users.
+3. If docs navigation grows cramped, add a MkDocs Material site published to
+   GitHub Pages.
+4. Avoid Jekyll unless the goal shifts toward a blog-style marketing site.
+5. Add the star-history chart only after the repo has enough activity for the
+   graph to render as useful signal rather than empty axes.
+6. Keep `RELEASE.md`, README release policy, and `.claude/commands/release.md`
+   in sync when the release process changes.

{gflow_cli-0.4.0a2 → gflow_cli-0.5.0a1}/CHANGELOG.md

@@ -7,6 +7,96 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0a1] — 2026-05-12
+
+> **Pluggable image transport + JSON-described batch runs.** The image
+> generation surface now ships a new default `ui_automation` transport —
+> a Playwright-driven UI mimicry strategy validated end-to-end against
+> real Flow on a Google AI Pro/Ultra profile. Three earlier HTTP
+> transport strategies (`evaluate_fetch`, `bearer`, `sapisidhash`) move
+> into a new `experimental/` subpackage; they remain importable for
+> research but are hidden from the CLI by default. New top-level
+> `gflow run --config <file>` command drives JSON-described sequential
+> batches through one shared session.
+
+### Added
+
+- **`UiAutomationTransport`** (`gflow_cli.api.transports.ui_automation`)
+  — new default transport. Drives the Flow editor on a logged-in
+  profile through a Playwright-managed persistent context (internal CDP
+  port; no externally-exposed debug port). Mirrors the validated
+  reference flow in `scripts/smoke_worker_style.py`.
+- **`gflow run --config <file>`** — sequential JSON-described batch
+  command. Schema covers `profile`, `transport`, `output_dir`, and a
+  `prompts` list (1–50 entries) with per-prompt `text`,
+  `aspect_ratio`, `model`, `count`, and `output_filename`. Supports
+  `--continue-on-error` (default) and `--fail-fast` semantics; final
+  exit code is the max per-prompt exit code. ONE `FlowApiClient`
+  session wraps the whole loop so the browser/project persist across
+  prompts.
+- **`examples/` directory** — three runnable scripts (`single_image_t2i.py`,
+  `batch_from_config.py`) + a copy-and-edit `sample_config.json` + an
+  index `examples/README.md`. All sanitised: no hardcoded profile
+  names, generic placeholder prompts, parameterised via `--profile` /
+  `$GFLOW_EXAMPLE_PROFILE`.
+- **Opt-in real-Flow smoke test** at `tests/smoke/test_real_flow.py`,
+  gated by `GFLOW_E2E=1` + `GFLOW_E2E_PROFILE`. Runs the full
+  `UiAutomationTransport` flow against real Flow and asserts a
+  non-trivial PNG was written.
+- **`EXPERIMENTAL_TRANSPORTS` constant** + **`transport_choices()`
+  helper** in `gflow_cli.api.transports`. The factory continues to
+  accept every registered key; the CLI `--transport` Choice list is
+  the gated surface (default = `ui_automation` only;
+  `GFLOW_CLI_EXPERIMENTAL_TRANSPORTS=1` expands to all four).
+- **Download host allow-list** in `UiAutomationTransport._download`
+  (`googleusercontent.com`, `googleapis.com`, `google.com` suffix
+  match). `follow_redirects=False`. Prevents session cookies from
+  reaching a non-Google host through a malformed or compromised
+  `fifeUrl`.
+
+### Changed
+
+- **Default `--transport` flag** flipped from `evaluate_fetch` to
+  `ui_automation` across `gflow image t2i`, `gflow image i2i`, and
+  `gflow image upload`. The change is transparent to existing scripts
+  unless they pinned `--transport evaluate_fetch` explicitly.
+- **`evaluate_fetch` / `bearer` / `sapisidhash` strategies moved** to
+  `gflow_cli.api.transports.experimental.*`. Public registry keys
+  (the strings used by `make_transport()` and the
+  `GFLOW_CLI_TRANSPORT` env var) are unchanged. Import paths within
+  the package are the only user-visible delta.
+- **Debug screenshots** captured by the strategy on `_enter_editor` /
+  `_send_prompt` failures are now **viewport-only**
+  (`full_page=False`) and emit a `WARNING` log line noting the file
+  may contain identifying information from the authenticated session.
+
+### Fixed
+
+- Listener-attach race in `generate_images`. The earlier
+  `asyncio.create_task(_capture_batch_response(page))` scheduled the
+  listener registration AFTER the next event-loop tick; on a busy
+  loop the prompt click could fire before the listener attached,
+  causing the capture to time out. Refactored into a synchronous
+  `_attach_batch_response_listener(page)` + an `async
+  _await_captured(captured, ...)`. No more orphaned task on partial
+  failure.
+
+### Removed
+
+- Dead `_extract_image_urls(response)` helper on
+  `UiAutomationTransport` and its five tests.
+  `generate_images` parses `body.media[]` directly through
+  `GeneratedImage.from_response_item`; the parallel helper was
+  unreachable.
+
+### Documentation
+
+- `BrowserManager` module docstring updated to make explicit that the
+  module is retained for research / non-Flow use, not on the
+  v0.5.0a1 image-generation critical path. No behavior change.
+- README "Project status" table updated with v0.5.0a1 row.
+- `docs/USAGE.md` gains a `gflow run` section.
+
 ## [0.4.0a2] — 2026-05-11
 
 > **Documentation polish.** Same release surface as v0.4.0a1; this tag fixes

gflow_cli-0.5.0a1/CONFIGURATION.md

@@ -0,0 +1,68 @@
+# gflow-cli Configuration Reference
+
+## Environment variables
+
+| Env var | Default | Description |
+|---|---|---|
+| `GFLOW_CLI_HOME` | Platform data dir | Root directory for profiles and config. |
+| `GFLOW_CLI_OUTPUT_DIR` | `~/Downloads/gflow-cli` | Where generated images and videos are saved. |
+| `GFLOW_CLI_BROWSER` | `auto` | Browser mode. See **Browser mode** section below. |
+| `CHROME_BINARY` | (autodetect) | Override Chrome binary path. Falls back to platform-standard locations. |
+| `GFLOW_CLI_CONCURRENCY` | `4` | Maximum parallel API requests per batch. |
+| `GFLOW_LIVE` | _(unset)_ | Set to `1` to enable live-API test markers (`@pytest.mark.live`). |
+
+---
+
+## Browser mode (D.2.3+)
+
+| Env var | Default | Description |
+|---|---|---|
+| `GFLOW_CLI_BROWSER` | `auto` | `auto` attaches to running Chrome via CDP or spawns detached; `fresh` launches new Playwright Chromium per call (legacy); `cdp:<port>` attaches to explicit CDP endpoint. |
+| `CHROME_BINARY` | (autodetect) | Override Chrome binary path. Falls back to platform-standard locations. |
+
+### When to use which
+
+- **`auto`** (recommended): real Chrome fingerprint = highest reCAPTCHA risk score; persistent
+  across CLI invocations. First call spawns Chrome detached; subsequent calls attach via CDP.
+- **`fresh`**: legacy single-shot Playwright Chromium. Use when you need a clean profile per call.
+- **`cdp:<port>`**: connect to an already-running Chrome you spawned yourself
+  (e.g. with `--remote-debugging-port=9222`).
+
+### Chrome binary autodetection order
+
+1. `CHROME_BINARY` env var (checked first — always wins)
+2. `shutil.which("chrome")` / `shutil.which("google-chrome")` / `shutil.which("chromium")`
+3. Platform-standard paths:
+   - **Windows**: `C:\Program Files\Google\Chrome\Application\chrome.exe`,
+     `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`,
+     `%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe`
+   - **macOS**: `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
+   - **Linux**: `/usr/bin/google-chrome`, `/usr/bin/chromium`, `/usr/bin/chromium-browser`
+
+If Chrome is not found, gflow-cli raises a `ConfigurationError` with an install hint.
+
+### CDP port range
+
+By default gflow-cli uses CDP port `9222`. If that port is occupied by a non-gflow Chrome,
+it probes `9222–9229` until a free port is found. The chosen port is persisted in
+`<profile_dir>/.gflow-cdp.lock` so subsequent calls reuse the same port.
+
+If all 8 ports are occupied, a `ConfigurationError` is raised.
+
+### Lockfile
+
+`<profile_dir>/.gflow-cdp.lock` — JSON file containing `{pid, port, profile_name}`.
+Written atomically (tmp + `os.link`, `O_CREAT|O_EXCL|O_NOFOLLOW`, mode `0o600`)
+when Chrome is first spawned. Stale locks (PID no longer alive) are cleaned up
+automatically on the next CLI invocation.
+
+### Security note — localhost CDP trust model
+
+The Chrome DevTools Protocol endpoint (`http://localhost:<port>/json/version`)
+is **not authenticated**. Any process on the same machine that can reach
+`localhost:9222` can drive the browser. gflow-cli treats a port owner that
+matches our lockfile as trusted; an unmanaged Chrome on the same port is
+attached with a `attached_to_unmanaged_chrome=true` warning logged.
+
+**Do not run gflow-cli on a shared multi-user machine** where untrusted users
+have shell access. Use a dedicated user account or a VM per worker.

{gflow_cli-0.4.0a2 → gflow_cli-0.5.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.4.0a2
+Version: 0.5.0a1
 Summary: Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal.
 Project-URL: Homepage, https://github.com/ffroliva/gflow-cli
 Project-URL: Issues, https://github.com/ffroliva/gflow-cli/issues
@@ -69,7 +69,7 @@ Description-Content-Type: text/markdown
 
 > ⚠️ **Not affiliated with Google.** Reverse-engineered from public Flow web traffic. Endpoints can change at any time. See full [DISCLAIMER](DISCLAIMER.md) before use.
 
-📚 **Docs:** [INDEX](docs/INDEX.md) · [User Guide](docs/USER_GUIDE.md) · [Architecture](docs/ARCHITECTURE.md) · [Authentication](docs/AUTHENTICATION.md) · [Configuration](docs/CONFIGURATION.md) · [Usage](docs/USAGE.md) · [Security](docs/SECURITY.md) · [Known issues](KNOWN_ISSUES.md) · [Plan](PLAN.md) · [Changelog](CHANGELOG.md)
+📚 **Docs:** [INDEX](docs/INDEX.md) · [User Guide](docs/USER_GUIDE.md) · [Architecture](docs/ARCHITECTURE.md) · [Authentication](docs/AUTHENTICATION.md) · [Configuration](docs/CONFIGURATION.md) · [Usage](docs/USAGE.md) · [Security](docs/SECURITY.md) · [Known issues](KNOWN_ISSUES.md) · [Release protocol](RELEASE.md) · [Plan](PLAN.md) · [Changelog](CHANGELOG.md)
 🤖 **For AI agents:** [CLAUDE.md](CLAUDE.md) · [`.claude/`](.claude/README.md)
 
 ---
@@ -108,7 +108,7 @@ Read the full [DISCLAIMER](DISCLAIMER.md) before deploying this in any productio
 
 ## Project status
 
-**v0.4.0a2 — alpha.** Video (T2V/I2V/batch), image (T2I/I2I/upload), and **batch concurrency, typed errors, retry/backoff, and structured logging** are functional end-to-end against a live Google AI Ultra/Pro Flow account.
+**v0.5.0a1 — alpha.** Video (T2V/I2V/batch), image (T2I/I2I/upload), the new **`gflow run` JSON-batch command**, and the **`ui_automation` default transport** are functional end-to-end against a live Google AI Pro/Ultra Flow account. Three earlier HTTP transport strategies (`evaluate_fetch` / `bearer` / `sapisidhash`) move to an `experimental/` subpackage in this release; the production path is `ui_automation`.
 
 | Milestone | Status |
 |---|---|
@@ -122,7 +122,17 @@ Read the full [DISCLAIMER](DISCLAIMER.md) before deploying this in any productio
 | Typed errors (RFC 9457 Problem Details) + per-class exit codes 3–7 | ✅ done (v0.4.0a2) |
 | Retry / backoff + reCAPTCHA re-mint inside the retry loop | ✅ done (v0.4.0a2) |
 | Structured logs (`structlog`, JSON on pipe) | ✅ done (v0.4.0a2) |
-| Provider abstraction for official Veo 3.1 API | ⏳ planned (v0.5+) |
+| Pluggable image transport + `ui_automation` default strategy | ✅ done (v0.5.0a1) |
+| `gflow run --config <file>` sequential JSON batches | ✅ done (v0.5.0a1) |
+| `examples/` directory with runnable single-image + batch scripts | ✅ done (v0.5.0a1) |
+| Provider abstraction for official Veo 3.1 API | ⏳ planned (v0.6+) |
+
+### What's new in v0.5.0a1
+
+- `UiAutomationTransport` is now the default image-generation strategy — Playwright-driven UI mimicry against the Flow editor on a logged-in Pro/Ultra profile (no externally-exposed CDP debug port).
+- New top-level `gflow run --config <file>` command for JSON-described sequential batches (1–50 prompts per file, `--continue-on-error` / `--fail-fast` modes). See [`docs/USAGE.md`](docs/USAGE.md#gflow-run) for the schema.
+- Three runnable example scripts shipped under [`examples/`](examples/README.md) — copy and edit for your own pipelines.
+- See the full [CHANGELOG](CHANGELOG.md#0501) for the security follow-ups (download host allow-list, viewport-only debug screenshots) and the listener-attach race fix.
 
 ---
 
@@ -376,17 +386,20 @@ Each `Provider` method has a corresponding test file under `tests/`. New routes
 
 1. Update [`CHANGELOG.md`](CHANGELOG.md) with the version's changes (Keep-a-Changelog format).
 2. Bump `version` in `pyproject.toml`.
-3. Tag the commit:
+3. Bump `__version__` in `src/gflow_cli/__init__.py`.
+4. Tag the commit:
    ```bash
-   git tag vX.Y.Z          # or vX.Y.ZaN for an alpha
-   git push origin vX.Y.Z
+   git tag v<version>          # for example, v0.4.0 or v0.4.0a3
+   git push origin v<version>
    ```
-4. The [`release.yml`](.github/workflows/release.yml) GitHub Action runs:
+5. The [`release.yml`](.github/workflows/release.yml) GitHub Action runs:
    - Builds the wheel + sdist with `uv build`
    - Publishes to PyPI via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — no API tokens stored
    - Creates a GitHub Release with the changelog excerpt + built artifacts attached
 
-Pre-release tags (`v*.*.*-rc*`, `v*.*.*-alpha*`, `v*.*.*-beta*`) auto-flag as pre-releases on GitHub. Install with `pip install --pre gflow-cli` or `uvx --from "gflow-cli==0.4.0a2" gflow`.
+PEP 440 prerelease tags (`vX.Y.ZaN`, `vX.Y.ZbN`, `vX.Y.ZrcN`) and hyphenated prerelease tags (`vX.Y.Z-alphaN`, `vX.Y.Z-betaN`, `vX.Y.Z-rcN`) auto-flag as prereleases on GitHub. Stable tags such as `v0.4.0` become full GitHub Releases. See [RELEASE.md](RELEASE.md) for the checklist and the prerelease/full-release policy.
+
+Install prereleases explicitly with `pip install --pre gflow-cli` or `uvx --from "gflow-cli==0.4.0a2" gflow`.
 
 ---
 
@@ -422,6 +435,5 @@ Note that the **Google service** this tool talks to has its own terms (Google La
 [![GitHub last commit](https://img.shields.io/github/last-commit/ffroliva/gflow-cli)](https://github.com/ffroliva/gflow-cli/commits/main)
 [![GitHub repo size](https://img.shields.io/github/repo-size/ffroliva/gflow-cli)](https://github.com/ffroliva/gflow-cli)
 [![PyPI downloads](https://img.shields.io/pypi/dm/gflow-cli.svg)](https://pypi.org/project/gflow-cli/)
-[![PyPI total downloads](https://img.shields.io/pypi/dt/gflow-cli.svg)](https://pypi.org/project/gflow-cli/)
 
 If `gflow-cli` saves you time, please ⭐ the repo — it's the cheapest way to support the project.

{gflow_cli-0.4.0a2 → gflow_cli-0.5.0a1}/README.md

@@ -15,7 +15,7 @@
 
 > ⚠️ **Not affiliated with Google.** Reverse-engineered from public Flow web traffic. Endpoints can change at any time. See full [DISCLAIMER](DISCLAIMER.md) before use.
 
-📚 **Docs:** [INDEX](docs/INDEX.md) · [User Guide](docs/USER_GUIDE.md) · [Architecture](docs/ARCHITECTURE.md) · [Authentication](docs/AUTHENTICATION.md) · [Configuration](docs/CONFIGURATION.md) · [Usage](docs/USAGE.md) · [Security](docs/SECURITY.md) · [Known issues](KNOWN_ISSUES.md) · [Plan](PLAN.md) · [Changelog](CHANGELOG.md)
+📚 **Docs:** [INDEX](docs/INDEX.md) · [User Guide](docs/USER_GUIDE.md) · [Architecture](docs/ARCHITECTURE.md) · [Authentication](docs/AUTHENTICATION.md) · [Configuration](docs/CONFIGURATION.md) · [Usage](docs/USAGE.md) · [Security](docs/SECURITY.md) · [Known issues](KNOWN_ISSUES.md) · [Release protocol](RELEASE.md) · [Plan](PLAN.md) · [Changelog](CHANGELOG.md)
 🤖 **For AI agents:** [CLAUDE.md](CLAUDE.md) · [`.claude/`](.claude/README.md)
 
 ---
@@ -54,7 +54,7 @@ Read the full [DISCLAIMER](DISCLAIMER.md) before deploying this in any productio
 
 ## Project status
 
-**v0.4.0a2 — alpha.** Video (T2V/I2V/batch), image (T2I/I2I/upload), and **batch concurrency, typed errors, retry/backoff, and structured logging** are functional end-to-end against a live Google AI Ultra/Pro Flow account.
+**v0.5.0a1 — alpha.** Video (T2V/I2V/batch), image (T2I/I2I/upload), the new **`gflow run` JSON-batch command**, and the **`ui_automation` default transport** are functional end-to-end against a live Google AI Pro/Ultra Flow account. Three earlier HTTP transport strategies (`evaluate_fetch` / `bearer` / `sapisidhash`) move to an `experimental/` subpackage in this release; the production path is `ui_automation`.
 
 | Milestone | Status |
 |---|---|
@@ -68,7 +68,17 @@ Read the full [DISCLAIMER](DISCLAIMER.md) before deploying this in any productio
 | Typed errors (RFC 9457 Problem Details) + per-class exit codes 3–7 | ✅ done (v0.4.0a2) |
 | Retry / backoff + reCAPTCHA re-mint inside the retry loop | ✅ done (v0.4.0a2) |
 | Structured logs (`structlog`, JSON on pipe) | ✅ done (v0.4.0a2) |
-| Provider abstraction for official Veo 3.1 API | ⏳ planned (v0.5+) |
+| Pluggable image transport + `ui_automation` default strategy | ✅ done (v0.5.0a1) |
+| `gflow run --config <file>` sequential JSON batches | ✅ done (v0.5.0a1) |
+| `examples/` directory with runnable single-image + batch scripts | ✅ done (v0.5.0a1) |
+| Provider abstraction for official Veo 3.1 API | ⏳ planned (v0.6+) |
+
+### What's new in v0.5.0a1
+
+- `UiAutomationTransport` is now the default image-generation strategy — Playwright-driven UI mimicry against the Flow editor on a logged-in Pro/Ultra profile (no externally-exposed CDP debug port).
+- New top-level `gflow run --config <file>` command for JSON-described sequential batches (1–50 prompts per file, `--continue-on-error` / `--fail-fast` modes). See [`docs/USAGE.md`](docs/USAGE.md#gflow-run) for the schema.
+- Three runnable example scripts shipped under [`examples/`](examples/README.md) — copy and edit for your own pipelines.
+- See the full [CHANGELOG](CHANGELOG.md#0501) for the security follow-ups (download host allow-list, viewport-only debug screenshots) and the listener-attach race fix.
 
 ---
 
@@ -322,17 +332,20 @@ Each `Provider` method has a corresponding test file under `tests/`. New routes
 
 1. Update [`CHANGELOG.md`](CHANGELOG.md) with the version's changes (Keep-a-Changelog format).
 2. Bump `version` in `pyproject.toml`.
-3. Tag the commit:
+3. Bump `__version__` in `src/gflow_cli/__init__.py`.
+4. Tag the commit:
    ```bash
-   git tag vX.Y.Z          # or vX.Y.ZaN for an alpha
-   git push origin vX.Y.Z
+   git tag v<version>          # for example, v0.4.0 or v0.4.0a3
+   git push origin v<version>
    ```
-4. The [`release.yml`](.github/workflows/release.yml) GitHub Action runs:
+5. The [`release.yml`](.github/workflows/release.yml) GitHub Action runs:
    - Builds the wheel + sdist with `uv build`
    - Publishes to PyPI via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — no API tokens stored
    - Creates a GitHub Release with the changelog excerpt + built artifacts attached
 
-Pre-release tags (`v*.*.*-rc*`, `v*.*.*-alpha*`, `v*.*.*-beta*`) auto-flag as pre-releases on GitHub. Install with `pip install --pre gflow-cli` or `uvx --from "gflow-cli==0.4.0a2" gflow`.
+PEP 440 prerelease tags (`vX.Y.ZaN`, `vX.Y.ZbN`, `vX.Y.ZrcN`) and hyphenated prerelease tags (`vX.Y.Z-alphaN`, `vX.Y.Z-betaN`, `vX.Y.Z-rcN`) auto-flag as prereleases on GitHub. Stable tags such as `v0.4.0` become full GitHub Releases. See [RELEASE.md](RELEASE.md) for the checklist and the prerelease/full-release policy.
+
+Install prereleases explicitly with `pip install --pre gflow-cli` or `uvx --from "gflow-cli==0.4.0a2" gflow`.
 
 ---
 
@@ -368,6 +381,5 @@ Note that the **Google service** this tool talks to has its own terms (Google La
 [![GitHub last commit](https://img.shields.io/github/last-commit/ffroliva/gflow-cli)](https://github.com/ffroliva/gflow-cli/commits/main)
 [![GitHub repo size](https://img.shields.io/github/repo-size/ffroliva/gflow-cli)](https://github.com/ffroliva/gflow-cli)
 [![PyPI downloads](https://img.shields.io/pypi/dm/gflow-cli.svg)](https://pypi.org/project/gflow-cli/)
-[![PyPI total downloads](https://img.shields.io/pypi/dt/gflow-cli.svg)](https://pypi.org/project/gflow-cli/)
 
 If `gflow-cli` saves you time, please ⭐ the repo — it's the cheapest way to support the project.

gflow_cli-0.5.0a1/RELEASE.md

@@ -0,0 +1,97 @@
+# Release Protocol
+
+This project publishes Python distributions to PyPI and GitHub Releases from
+Git tags. The release workflow is `.github/workflows/release.yml`.
+
+## Current Policy
+
+- `0.x` versions are alpha-quality releases: useful for real testing, but APIs
+  may change before `1.0.0`.
+- PEP 440 prerelease tags use the form `vX.Y.ZaN`, `vX.Y.ZbN`, or `vX.Y.ZrcN`.
+  Example: `v0.4.0a2`.
+- Stable tags use the form `vX.Y.Z`. Example: `v0.4.0`.
+- Never rewrite a pushed release tag. If a release is wrong, ship the next
+  version with a fix.
+
+## What The Workflow Does
+
+When a tag matching `v*.*.*` is pushed, GitHub Actions:
+
+1. Verifies the tag matches `pyproject.toml` exactly after stripping the
+   leading `v`.
+2. Builds the wheel and source distribution with `uv build`.
+3. Publishes to PyPI through Trusted Publishing.
+4. Creates a GitHub Release and attaches the built artifacts.
+5. Marks tags containing PEP 440 alpha, beta, or release-candidate markers as
+   GitHub prereleases.
+
+## Prerelease Versus Full Release
+
+Use a prerelease while validating behavior with end-to-end tests:
+
+```bash
+0.4.0a1
+0.4.0a2
+0.4.0rc1
+```
+
+Use a full release only when the same release line is ready for general use:
+
+```bash
+0.4.0
+```
+
+PyPI treats `0.4.0a2` as a prerelease version. Users can install it explicitly:
+
+```bash
+uvx --from "gflow-cli==0.4.0a2" gflow --help
+python -m pip install --pre gflow-cli
+```
+
+## Release Checklist
+
+1. Confirm the working tree is clean:
+   ```bash
+   git status --short
+   ```
+2. Confirm `main` is current:
+   ```bash
+   git fetch origin
+   git branch --show-current
+   git rev-list HEAD..origin/main
+   ```
+3. Run quality gates:
+   ```bash
+   uv run ruff check src tests
+   uv run ruff format --check src tests
+   uv run pyright src
+   uv run pytest -q
+   ```
+4. Update the version in:
+   - `pyproject.toml`
+   - `src/gflow_cli/__init__.py`
+   - any tests that assert the package version
+5. Move user-visible changes from `CHANGELOG.md` `[Unreleased]` into a dated
+   release section.
+6. Commit the release prep:
+   ```bash
+   git add pyproject.toml src/gflow_cli/__init__.py CHANGELOG.md tests
+   git commit -m "chore(release): vX.Y.Z"
+   ```
+7. Tag and push:
+   ```bash
+   git tag -a vX.Y.Z -m "vX.Y.Z"
+   git push origin main
+   git push origin vX.Y.Z
+   ```
+8. Watch the release workflow:
+   <https://github.com/ffroliva/gflow-cli/actions/workflows/release.yml>
+9. Confirm the new version appears on:
+   - <https://pypi.org/project/gflow-cli/>
+   - <https://github.com/ffroliva/gflow-cli/releases>
+
+## Known Historical Quirk
+
+Older alpha tags (`v0.2.0a1`, `v0.3.0a1`) were created as normal GitHub
+Releases because the workflow only detected hyphenated prerelease names. The
+workflow now recognizes PEP 440 alpha, beta, and release-candidate tags.

{gflow_cli-0.4.0a2 → gflow_cli-0.5.0a1}/docs/AUTHENTICATION.md

@@ -230,7 +230,7 @@ Re-running `auth login` refreshes the cookies in place — no other state is los
 |---|---|
 | Session file leaked to a public repo | `.gitignore` excludes profile dirs at every layer. Recommended belt-and-braces: keep the gflow-cli home outside the repo (default location via `platformdirs` already does this) and run `git status` before any commit. Automatic in-repo detection is on the backlog (not yet scheduled). |
 | Multi-user shared machine | Profiles live under each user's home dir; OS file permissions (`0700` on POSIX, ACL on Windows) prevent cross-user reads by default. |
-| `gflow-cli` itself becomes malicious | The package is open-source under MIT; pin a version (`uv tool install gflow-cli==0.4.0a2`) and review release diffs before upgrading. |
+| `gflow-cli` itself becomes malicious | The package is open-source under MIT; pin a version (`uv tool install gflow-cli==0.5.0a1`) and review release diffs before upgrading. |
 | Stolen laptop | Anyone with disk access has your session. Use full-disk encryption (FileVault, BitLocker, LUKS). Consider a dedicated `--profile sandbox` for short-lived experiments. |
 | Sharing a profile between machines | Technically works (copy the profile dir), but Google may flag the device-fingerprint mismatch as suspicious. Re-login on the new machine instead. |
 

{gflow_cli-0.4.0a2 → gflow_cli-0.5.0a1}/docs/INDEX.md

@@ -7,6 +7,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 | [README](../README.md) | Project overview, install, quick start | First time landing on the repo |
 | [CLAUDE.md](../CLAUDE.md) | Project memory hub for AI coding agents | First time an agent (Claude/Cursor/Codex/Gemini/Aider) opens the repo |
 | [PLAN.md](../PLAN.md) | Implementation plan (DDD / CQRS / phases / ADRs) | You want the architectural intent and roadmap |
+| [RELEASE.md](../RELEASE.md) | Release checklist, prerelease policy, PyPI/GitHub publishing protocol | Cutting or auditing a release |
 | [CHANGELOG](../CHANGELOG.md) | Version-by-version user-visible changes | Upgrading or auditing what shipped |
 | [KNOWN_ISSUES](../KNOWN_ISSUES.md) | Open / mitigated / resolved issues with workarounds | Before opening a bug report; when something feels off |
 | [DISCLAIMER](../DISCLAIMER.md) | Legal scope, takedown policy, prohibited uses | Before deploying anywhere non-trivial |
@@ -31,6 +32,7 @@ Welcome to the `gflow-cli` documentation. This index is the routing layer: it te
 **"Exit code 4 (rate-limit) or 5 (content-policy) — how do I recover?"** → [USER_GUIDE § Journey 12](USER_GUIDE.md#journey-12--recovering-from-contentpolicyerror-or-ratelimiterror)
 **"How do I read the structured log (`error_raised` events)?"** → [USER_GUIDE § Journey 6](USER_GUIDE.md#journey-6--reading-structured-logs-jq-recipes)
 **"What exit code does shell branching see for each error class?"** → [USAGE § Exit codes](USAGE.md#exit-codes)
+**"Is `v0.5.0a1` a prerelease, and how do I cut a full release?"** → [RELEASE § Prerelease Versus Full Release](../RELEASE.md#prerelease-versus-full-release)
 **"Where is my session stored?"** → [AUTHENTICATION § Session storage](AUTHENTICATION.md#session-storage)
 **"Where do generated files land?"** → [CONFIGURATION § Output paths](CONFIGURATION.md#output-paths)
 **"How do I run with multiple Google accounts?"** → [AUTHENTICATION § Multiple accounts](AUTHENTICATION.md#multiple-accounts)

{gflow_cli-0.4.0a2 → gflow_cli-0.5.0a1}/docs/SECURITY.md

@@ -50,7 +50,7 @@ For users on shared / multi-user / production-adjacent machines:
 - [ ] **Set `GFLOW_CLI_HOME` to a non-default path** if you want the session away from the standard `LOCALAPPDATA` / `~/.local/share` location for any reason (auditability, separate volumes).
 - [ ] **Use `--profile sandbox`** for short-lived experiments. Easy to delete (`rm -rf $GFLOW_CLI_HOME/profile_sandbox`) without disturbing your main profile.
 - [ ] **Rotate sessions monthly** by signing out of Google → re-running `gflow auth login`. Limits blast radius of an unnoticed session theft.
-- [ ] **Pin a gflow-cli version** in production (`uv tool install gflow-cli==0.4.0a2`) and review release diffs before upgrading.
+- [ ] **Pin a gflow-cli version** in production (`uv tool install gflow-cli==0.5.0a1`) and review release diffs before upgrading.
 - [ ] **Keep the package up-to-date for security fixes.** Subscribe to GitHub Releases for `ffroliva/gflow-cli`.
 - [ ] **Scan your repo for accidentally-committed profiles** before pushing: `git ls-files | grep -E "profile_|cookies\.json|\.env$"`.