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

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

@@ -32,7 +32,7 @@ Ask the user (if not already provided):
    uv run ruff check src tests
    uv run ruff format --check src tests
    uv run pyright src
-   uv run pytest -q --cov=flow_cli --cov-fail-under=80
+   uv run pytest -q --cov=gflow_cli --cov-fail-under=80
    ```
 
 4. **Bump version** in `pyproject.toml`:

{gflow_cli-0.3.0a1 → gflow_cli-0.4.0a2}/.env.template

@@ -1,6 +1,9 @@
 # gflow-cli — example environment variables.
-# Copy to `.env` (in this repo or in $FLOW_CLI_HOME) and customise.
+# Copy to `.env` in the directory where you invoke `gflow` and uncomment what
+# you want to override. ($GFLOW_CLI_HOME is NOT a .env search path — only the
+# current working directory is loaded.)
 # All variables are OPTIONAL — defaults work out of the box for most users.
+# Lines below are commented to show the SHIPPED DEFAULT — uncomment to override.
 
 # -----------------------------------------------------------------------------
 # Auth & profiles
@@ -11,10 +14,12 @@
 #   Windows: %LOCALAPPDATA%\gflow-cli                    (e.g. C:\Users\<you>\AppData\Local\gflow-cli)
 #   macOS:   ~/Library/Application Support/gflow-cli
 #   Linux:   $XDG_DATA_HOME/gflow-cli                    (typically ~/.local/share/gflow-cli)
-# FLOW_CLI_HOME=
+# GFLOW_CLI_HOME=
 
-# Default profile name. Override per-call with `--profile <name>`.
-FLOW_CLI_PROFILE=default
+# Default profile name. When unset, the resolution chain auto-picks (see
+# docs/CONFIGURATION.md § GFLOW_CLI_PROFILE). Override per-call with
+# `--profile <name>`.
+# GFLOW_CLI_PROFILE=default
 
 # -----------------------------------------------------------------------------
 # Output paths
@@ -28,7 +33,7 @@ FLOW_CLI_PROFILE=default
 #   Windows: %USERPROFILE%\Downloads\gflow-cli
 #   macOS:   ~/Downloads/gflow-cli
 #   Linux:   $XDG_DOWNLOAD_DIR/gflow-cli  (falls back to ~/Downloads/gflow-cli)
-# FLOW_CLI_OUTPUT_DIR=
+# GFLOW_CLI_OUTPUT_DIR=
 
 # -----------------------------------------------------------------------------
 # Provider selection
@@ -37,31 +42,34 @@ FLOW_CLI_PROFILE=default
 # Backend to use for generations.
 #   flow      - reverse-engineered Flow REST API (default, requires Ultra/Pro)
 #   official  - official Veo SDK (planned for v0.5+, requires Gemini API key)
-FLOW_CLI_PROVIDER=flow
+# GFLOW_CLI_PROVIDER=flow
 
-# Gemini API key — only required when FLOW_CLI_PROVIDER=official.
+# Gemini API key — only required when GFLOW_CLI_PROVIDER=official.
 # Get one at https://aistudio.google.com/apikey
-# FLOW_CLI_GEMINI_API_KEY=
+# GFLOW_CLI_GEMINI_API_KEY=
 
 # -----------------------------------------------------------------------------
 # Runtime tuning
 # -----------------------------------------------------------------------------
 
 # Per-request HTTP timeout (seconds). Veo videos can take 60-180s each.
-FLOW_CLI_TIMEOUT_SECONDS=600
+# GFLOW_CLI_TIMEOUT_SECONDS=600
 
 # Logging level — DEBUG | INFO | WARNING | ERROR
-FLOW_CLI_LOG_LEVEL=INFO
+# GFLOW_CLI_LOG_LEVEL=INFO
 
 # Log format — auto | text | json
 #   auto = text on TTY, json when piped (default)
-FLOW_CLI_LOG_FORMAT=auto
+# GFLOW_CLI_LOG_FORMAT=auto
 
-# Concurrency for batch operations (requires multiple profiles, v0.4+).
-FLOW_CLI_CONCURRENCY=1
+# Per-worker Playwright Page-pool size for batch runs (1-16). FlowApiClient
+# opens N Pages inside one shared persistent BrowserContext; `gflow video batch`
+# fans out via asyncio.gather. ~30-60 MiB memory per Page on Chromium headless;
+# don't exceed 8 without measuring. Shipped in v0.4.0a2.
+# GFLOW_CLI_CONCURRENCY=1
 
 # Run Playwright in headless mode for non-`auth login` commands (true|false).
 # Default: true. Set to false if reCAPTCHA Enterprise refuses to mint tokens
 # (Google's bot-detection sometimes refuses headless Chromium but accepts a
 # visible window). The session is still reused from the persistent profile.
-FLOW_CLI_HEADLESS=true
+# GFLOW_CLI_HEADLESS=true

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

@@ -51,3 +51,6 @@ samples/*.captured.json # sandbox-recorded API exchanges may contain PII
 # Claude Code worktrees and lock files
 .claude/worktrees/
 .claude/scheduled_tasks.lock
+
+# Doc-council scratch dir (bundles + raw reviews + consensus matrix)
+.doc-council/

gflow_cli-0.4.0a2/CHANGELOG.md

@@ -0,0 +1,315 @@
+# Changelog
+
+All notable changes to `gflow-cli` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0a2] — 2026-05-11
+
+> **Documentation polish.** Same release surface as v0.4.0a1; this tag fixes
+> a doc-council pass: four broken Python snippets in the README, a shell
+> exit-code branching example that silently dropped failures, a stale anchor
+> link in `AUTHENTICATION.md`, three USER_GUIDE journeys the target audience
+> needs (credit budgeting, pipeline wiring, error recovery), and a sweep of
+> "planned v0.3 / v0.4" callouts across 9 files that had been overtaken by
+> the Phase 4 release. No code changes. No tests changed.
+
+### Fixed (docs)
+
+- **`README.md` Python quick-start snippet rewritten** — the prior block had
+  four real bugs (`from gflow_cli.paths import profile_dir` → import error,
+  `upload_image(path, project_id)` args reversed, `generate_video(prompt=,
+  start_asset=, aspect=)` wrong kwargs, `poll_video_status` method does not
+  exist). Snippet now uses the same invocation pattern as
+  `gflow_cli.cli_video._run_i2v` and would actually run.
+- **`docs/USAGE.md` exit-code branching example** — `if ! cmd; then case $?`
+  always saw `0` because the `if` consumed the exit code; rewritten to
+  capture `rc=$?` first. Exit code `2` re-labelled "Bad CLI usage" (auth is
+  exit `3`).
+- **`docs/AUTHENTICATION.md` anchor link** to the Phase 4 PLAN heading
+  fixed (was `#phase-4--hardening--post-v030a1`, did not exist).
+- **`CHANGELOG.md` footer** — added `[0.4.0a1]:` and `[0.4.0a2]:` compare
+  links; reset `[Unreleased]` to compare from v0.4.0a2.
+- **`docs/USER_GUIDE.md` Journey 2** endpoint name `flowMedia:batchGenerateVeoVideo`
+  → real route `/v1/video:batchAsyncGenerateVideoText`.
+- **`docs/USER_GUIDE.md` Journey 5.2** invalid placeholder UUID
+  (`media-uuid-abc-...`) → canonical hex shape.
+- **`docs/USER_GUIDE.md` Journey 7.1** `echo $?` placement — previously
+  captured the exit code of an intermediate command, not the failing batch.
+- **`docs/USER_GUIDE.md` Journey 7.3** softened the "Flow doesn't re-bill"
+  claim — billing is a private-API contract we cannot assert.
+- **`KNOWN_ISSUES.md` same-profile examples** swapped `gflow image batch`
+  (does not exist) → `gflow video batch`.
+
+### Added (docs)
+
+- **`docs/USER_GUIDE.md` Journey on credit budgeting** — rule-of-thumb credit
+  cost per `video t2v` / `video i2v` / `image t2i` / `image i2i` call, links
+  to Flow's credit-balance UI, batch-cost math example.
+- **`docs/USER_GUIDE.md` Journey on wiring outputs into a pipeline** —
+  deterministic output-dir layout, `find` (POSIX) + `Get-ChildItem`
+  (PowerShell) recipes, `ffmpeg` consumer example.
+- **`docs/USER_GUIDE.md` Journey on `ContentPolicyError` / `RateLimitError`
+  recovery** — what each error means, how long to wait, prompt-rewrite
+  pattern, when retry is futile.
+- **`README.md` doc-nav** now links `docs/USER_GUIDE.md` (was missing).
+- **`README.md` Stack table** lists `tenacity` and `structlog` (were
+  shipped in v0.4.0a1 but not in the stack overview).
+
+### Changed (docs)
+
+- **`CHANGELOG.md` [0.4.0a1] section reordered** — `Added — Phase 4
+  hardening` now appears before `Breaking`. The hardening release was
+  user-visible value; the env-var rename was a one-line update for most
+  users.
+- **Per-class exit codes 3–7** promoted from a bullet to its own "Migration
+  notes" subsection in the [0.4.0a1] block.
+- **Version-time-warp sweep across 9 files** — every `(planned v0.3)`,
+  `(planned v0.4)`, `v0.3+ will add`, `v0.4 will add`, and `current scaffold
+  ignores this` line either describes shipped behaviour or points at v0.5+.
+  Files touched: `README.md`, `CHANGELOG.md`, `CLAUDE.md`, `PLAN.md`,
+  `KNOWN_ISSUES.md`, `CONFIGURATION.md`, `AUTHENTICATION.md`,
+  `ARCHITECTURE.md`, `DISCLAIMER.md`, `SECURITY.md`, `CONTRIBUTING.md`,
+  `.env.template`.
+- **`docs/ARCHITECTURE.md` Concurrency section** describes the shipped
+  `asyncio.Queue` Page pool, not the target-DDD `Semaphore` model.
+- **`docs/ARCHITECTURE.md` Observability section** describes the shipped
+  `error_raised` / `error_unhandled` event names, not the target-DDD
+  dot-path names.
+- **`docs/ARCHITECTURE.md` DDD error class names** annotated as target —
+  shipped Phase 4 names (`AuthExpiredError`, `RateLimitError`,
+  `ContentPolicyError`, `NetworkError`, `WireFormatError`) listed alongside.
+- **`docs/CONFIGURATION.md` `GFLOW_CLI_CONCURRENCY`** describes shipped
+  behaviour (per-worker Page pool, `asyncio.gather` fan-out).
+
+## [0.4.0a1] — 2026-05-11
+
+> **Phase 4 hardening release.** Concurrency, retry/backoff, typed errors,
+> and structured logs ship — your existing scripts keep running (the
+> `FLOW_CLI_*` env-var shim is in place until v0.5.0). The user-visible
+> contract that changed: shell scripts can now branch on stable per-class
+> exit codes (3–7) for auth / rate-limit / content-policy / network /
+> wire-format failures.
+
+### Added — Phase 4 hardening
+
+- **Per-worker Playwright Page pool.** `FlowApiClient.__aenter__` opens
+  `Settings.concurrency` Pages inside a single persistent BrowserContext.
+  Operations check out a Page via `asyncio.Queue` (FIFO, bounded by
+  `maxsize=N`). `GFLOW_CLI_CONCURRENCY=N` (1–16) now actually parallelizes.
+- **`gflow video batch` fans out via `asyncio.gather`** over manifest
+  entries — was sequential pre-v0.4.0a1.
+- **`tenacity`-based retry layer** (3 attempts, exponential jittered
+  backoff 1s±25% → 2s±25% → 4s±25%) on 5xx / 429 / `playwright.async_api.Error`
+  / `TimeoutError`. `Retry-After` honoured, **capped at 60 s**. `reraise=True`
+  so the original exception's `__cause__` chain is preserved. reCAPTCHA
+  token re-minted **inside the retry loop, every attempt**, on the worker's
+  own Page.
+- **RFC 9457 Problem Details exception hierarchy:**
+  `GFlowError → FlowApiError → {AuthExpiredError, RateLimitError,
+  ContentPolicyError, NetworkError, WireFormatError}`. `except FlowApiError`
+  catches the typed subclasses (back-compat). Each carries
+  `problem_type` URI, `title`, `status`, `detail`, `instance`
+  (`gflow:error:<correlation_id>`), `remediation_hint`, and `route`.
+  `to_problem_details()` serializes to the RFC 9457 JSON shape.
+- **Per-class exit codes**: 3 (auth) / 4 (rate-limit) / 5 (content-policy) /
+  6 (network) / 7 (wire-format). Exit 1 = unhandled. Exit 130 = SIGINT.
+- **`WireFormatError` discovery payload** — `route_name`, `http_status`,
+  `content_type`, `top_level_keys`, `body_prefix_redacted` so log mining
+  can propose new error subclasses for unexpected response shapes.
+- **`structlog` bootstrap** with TTY auto-detection (text on TTY, JSON when
+  piped). `show_locals=False` mandatory on the exception renderer so frame
+  locals (which may contain auth tokens) NEVER reach the log stream.
+  `correlation_id` + `cli_version` bound via `contextvars` at the process
+  boundary.
+- **`error_raised` and `error_unhandled` events.** `error_raised` for caught
+  `GFlowError`s — carries Problem Details. `error_unhandled` for anything
+  else — privacy-safe: hashes message + stack with SHA-256, never logs raw
+  payload.
+- **12 `pytest-bdd` scenarios** across `auth.feature`, `video.feature`,
+  `image.feature` — all use a mocked `FlowApiClient`. A
+  `_forbid_live_playwright` autouse tripwire fails any scenario that
+  accidentally tries to start a real browser.
+
+### Migration notes — stable exit codes
+
+Shell scripts that previously branched on exit code `1` for any failure
+can now distinguish the failure class. The mapping is locked by an
+ordering-invariant test in `tests/test_errors.py`:
+
+| Exit | Error class           | Meaning                              | Retry?         |
+|------|-----------------------|--------------------------------------|----------------|
+| 0    | —                     | Success                              | —              |
+| 1    | (unhandled)           | Bug. Filed via `error_unhandled`     | No             |
+| 2    | (Click)               | Bad CLI usage / missing arg          | Fix the call   |
+| 3    | `AuthExpiredError`    | Session cookies invalidated          | After re-login |
+| 4    | `RateLimitError`      | Flow returned 429                    | Yes, with wait |
+| 5    | `ContentPolicyError`  | Prompt blocked upstream              | After rewrite  |
+| 6    | `NetworkError`        | DNS / TLS / 5xx after retry          | Yes            |
+| 7    | `WireFormatError`     | Response shape changed (Flow update) | File a bug     |
+| 130  | (SIGINT)              | User Ctrl-C                          | —              |
+
+See [`docs/USAGE.md § Exit codes`](docs/USAGE.md#exit-codes) for a
+shell-script template that branches on these codes.
+
+### Breaking — package + env-var rename
+
+- **Python package renamed: `flow_cli` → `gflow_cli`.** All imports must
+  change: `from gflow_cli...` (was `from flow_cli...`). The PyPI distribution
+  name (`gflow-cli`), the CLI binary (`gflow`), and the user data directory
+  (`gflow-cli/` under `platformdirs`) are unchanged.
+- **Env var prefix renamed: `FLOW_CLI_*` → `GFLOW_CLI_*`.** Affected vars:
+  `GFLOW_CLI_HOME`, `GFLOW_CLI_OUTPUT_DIR`, `GFLOW_CLI_PROFILE`,
+  `GFLOW_CLI_HEADLESS`, `GFLOW_CLI_LOG_LEVEL`, `GFLOW_CLI_LOG_FORMAT`,
+  `GFLOW_CLI_PROVIDER`, `GFLOW_CLI_TIMEOUT_SECONDS`, `GFLOW_CLI_CONCURRENCY`,
+  `GFLOW_CLI_GEMINI_API_KEY`.
+- **Backwards-compat shim.** Legacy `FLOW_CLI_*` env vars continue to work
+  in v0.4.x; on first encounter the process emits a single
+  `DeprecationWarning` to stderr summarising the promoted keys. The shim
+  will be removed in v0.5.0 — update your `.env` files and shell exports.
+
+### Changed
+
+- `FlowApiError` re-parented under `GFlowError`. Legacy positional
+  constructor `FlowApiError(status, body, *, route)` preserved (auto-detected
+  via `isinstance(args[0], int) and not isinstance(args[0], bool)`).
+- `_resolve_profile` and `_make_provider_dir` deduped — relocated from
+  `cli_image.py` + `cli_video.py` to `gflow_cli._cli_helpers`. AST-based
+  drift guard in `tests/cli/test_helpers.py` prevents regression.
+- All `logging.*` callsites in `src/` migrated to `structlog`. The
+  remaining `print()` in `auth.py` swapped to Rich `console.print()`.
+
+### Internal
+
+- New module: `gflow_cli.errors` (RFC 9457 hierarchy + `EXIT_CODE_MAP`).
+- New module: `gflow_cli.observability` (structlog bootstrap + event
+  emitters; `show_locals=False` via
+  `ExceptionRenderer(ExceptionDictTransformer(show_locals=False))`).
+- New module: `gflow_cli.api._retry` (tenacity `AsyncRetrying` +
+  `Retry-After` parser, capped at 60 s).
+- New module: `gflow_cli._cli_helpers` (shared CLI-boundary handlers +
+  profile/provider helpers).
+
+## [0.3.0a1] — 2026-05-10
+
+### Added
+- **`gflow image upload PATH`** — upload a single local image (PNG/JPEG) into a
+  fresh Flow project and print the asset UUID + dimensions Flow inferred. The
+  UUID is reusable as a starting frame for `gflow image i2i --ref` and
+  `gflow video i2v`.
+- **`gflow image t2i PROMPT`** — text-to-image generation (1–4 images per call)
+  via Google Flow's Imagen / Nano Banana models.
+  Flags: `--model {nano2|nano-pro|image4}`, `--aspect {9:16|16:9|1:1|4:3|3:4}`,
+  `-n/--count` (1–4), `--seed` (single-image only), `--out DIR`, `--profile`.
+  Files land date-partitioned under `$GFLOW_CLI_OUTPUT_DIR/images/<YYYY-MM-DD>/`
+  by default; `--out DIR` writes flat as `<DIR>/<media_name>_<n>.png`.
+- **`gflow image i2i PROMPT --ref PATH_OR_UUID`** — image-to-image generation
+  with one or more reference images. Each `--ref` is classified at the CLI
+  boundary: case-insensitive 8-4-4-4-12 hex UUIDs are passed through verbatim
+  (no upload), anything else is canonicalized (symlinks resolved at validation
+  time) and uploaded before use. `--ref` is repeatable; UUIDs and paths can mix
+  freely on the same call. Same flag set as `t2i` otherwise.
+- **Multi-image fan-out** — `t2i` / `i2i` with `-n {2..4}` mint a single shared
+  `batch_id` and issue N parallel POSTs (one per shot, each with its own random
+  seed). Same-batch images share the prompt + refs; per-shot variation comes
+  from independent seeds.
+- **Three image models** wired behind CLI aliases:
+  `nano2` → `NARWHAL` (Nano Banana 2; default, fast/balanced),
+  `nano-pro` → `GEM_PIX_2` (Nano Banana Pro; higher quality),
+  `image4` → `IMAGEN_3_5` (Imagen 4; photoreal-leaning).
+- **Five aspect ratios** for image generation: `9:16`, `16:9`, `1:1`, `4:3`,
+  `3:4` (default `9:16`, matching the Flow web UI).
+- `download_image()` on `FlowApiClient` — direct download of a generated
+  image's signed `fifeUrl` to disk. Streams to a temp file and atomically
+  renames on success; enforces an SSRF host allowlist (only Google-controlled
+  CDNs accepted).
+- `scripts/smoke_image.py` — live single-image E2E smoke script (image
+  counterpart of `scripts/smoke_e2e.py` for video). Run after
+  `gflow auth login` to exercise the full happy path: project create →
+  `batchGenerateImages` → fifeUrl download.
+
+### Changed
+- `FlowApiClient.upload_image` now validates **PNG/JPEG/WebP/GIF magic
+  bytes** and rejects files larger than **20 MB** before issuing the upload
+  request. Existing callers (`gflow video i2v`, `gflow video batch`) inherit
+  the stricter validation; previously-undocumented use of `upload_image` for
+  non-image payloads no longer works (was never officially supported).
+- Project renamed `flow-cli` → `gflow-cli` across all docs and source. The
+  PyPI package and GitHub repo were already at the new name in v0.2.0a1;
+  this commit completes the in-source rename. Local clones may want to
+  rename their working directory to match `gh clone https://github.com/ffroliva/gflow-cli`
+  behavior.
+
+### Security
+- DEBUG-level body logs now redact reCAPTCHA Enterprise tokens and other
+  bearer-style fields before emission, eliminating a token-leak vector when
+  users share verbose logs while filing bug reports.
+- `download_image()` enforces an **SSRF host allowlist** on the signed
+  `fifeUrl` returned by Flow — only Google-controlled image CDNs
+  (`*.googleusercontent.com`, etc.) are followed; any other host raises
+  before the GET is issued. Defends against a Flow-side bug or compromise
+  redirecting downloads to an attacker-controlled origin.
+- `project_id` allowlist regex `^[A-Za-z0-9-]{1,128}$` on
+  `batch_generate_images_url` — closes percent-encoded slash (`%2F`),
+  Unicode-lookalike (U+FF0F / U+2215 / U+29F8), and CRLF/NUL injection
+  bypasses that the previous denylist guard let through.
+
+### CI
+- Test matrix now includes Python 3.13 alongside 3.11 and 3.12.
+
+## [0.2.0a1] — 2026-05-09
+
+### Added
+- **`gflow video t2v`** — generate a video from a text prompt via Veo 3.1.
+  Flags: `--aspect 9:16|16:9|1:1`, `--seed`, `--output`, `--profile`, `--poll-interval`.
+- **`gflow video i2v`** — generate a video from a start image + text prompt (Veo 3.1 I2V).
+- **`gflow video batch`** — run a TSV manifest of video generations against one shared project.
+- `gflow_cli.api` package — low-level REST client (`FlowApiClient`) + value objects
+  (`GenerateVideoRequest`, `VideoOperation`, `VideoStatus`) for video generation.
+- `gflow_cli.api.recaptcha` — reCAPTCHA Enterprise token minting via Playwright `page.evaluate`.
+  `TokenMinter` caches the discovered site key per session; `mint(action)` is called immediately
+  before each generation request.
+- `gflow_cli.manifest` — TSV manifest parser for `gflow video batch`. Supports optional
+  `start_image`, `end_image`, `aspect`, `output_path` columns; skips `# `-prefixed comments.
+- `GFLOW_CLI_HEADLESS` env var (`bool`, default `true`). Set to `false` if reCAPTCHA refuses
+  to mint tokens in headless mode (Google bot detection fallback).
+- `scripts/smoke_e2e.py` — one-shot live T2V smoke test; run after `gflow auth login` to
+  verify the full happy path (create project → generate_video → poll → download).
+- **`CLAUDE.md`** at repo root — project memory hub for AI coding agents
+  (Claude Code reads natively; Cursor/Codex/Gemini/Aider can read as reference).
+- **`.claude/`** directory — repo-local Claude Code surface for maintainers.
+  - `.claude/README.md` — what goes here, how to extend.
+  - `.claude/commands/release.md` — `/release` slash command that automates
+    version bump + CHANGELOG migration + tag + push, with quality gates.
+- `gflow_cli.profile_store` — profile inventory + default-profile persistence
+  in `$GFLOW_CLI_HOME/config.toml`. Five-step resolution chain (CLI flag > env >
+  config > auto-select > raise) with named exceptions
+  (`NoProfilesError`, `NoDefaultProfileError`).
+- New auth subcommands: bare `gflow auth`, `gflow auth list`, `gflow auth use <name>`,
+  `gflow auth logout [--profile NAME] [-y]`. First login auto-sets default profile.
+- `KNOWN_ISSUES.md` at repo root — open/mitigated/resolved issues with workarounds.
+- `docs/` tree (INDEX, AUTHENTICATION, CONFIGURATION, ARCHITECTURE, USAGE, SECURITY).
+- `.env.template` documenting every supported env var.
+- GitHub Actions CI: ruff, pyright, pytest on Python 3.11 and 3.12.
+- GitHub Actions release workflow: tag-triggered PyPI publish via Trusted Publishing.
+- MIT license, comprehensive README, [`DISCLAIMER.md`](DISCLAIMER.md), [`CONTRIBUTING.md`](CONTRIBUTING.md).
+- [`skills/gflow-cli/SKILL.md`](skills/gflow-cli/SKILL.md) — installable Claude Code Skill.
+
+### Removed
+- `gflow_cli.providers.FlowProvider` and `gflow_cli.models` — superseded by `gflow_cli.api`.
+- Legacy CLI stubs: `gflow upload`, `gflow generate`, `gflow status`, `gflow download`,
+  `gflow i2v`. Replaced by the wired `gflow video` subgroup.
+
+## [0.1.0] — _unreleased_
+
+First skeleton. Not functional end-to-end yet.
+
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.4.0a2...HEAD
+[0.4.0a2]: https://github.com/ffroliva/gflow-cli/compare/v0.4.0a1...v0.4.0a2
+[0.4.0a1]: https://github.com/ffroliva/gflow-cli/compare/v0.3.0a1...v0.4.0a1
+[0.3.0a1]: https://github.com/ffroliva/gflow-cli/releases/tag/v0.3.0a1
+[0.2.0a1]: https://github.com/ffroliva/gflow-cli/releases/tag/v0.2.0a1
+[0.1.0]: https://github.com/ffroliva/gflow-cli/releases/tag/v0.1.0

{gflow_cli-0.3.0a1 → gflow_cli-0.4.0a2}/CLAUDE.md

@@ -17,17 +17,22 @@
 
 ## Active phase
 
-**Phase 3 — Image MVP DONE (v0.3.0a1).** `gflow image upload/t2i/i2i` shipped.
-Tag at `ccce4d5`. Next phase TBD (Phase 4 Hardening — concurrency pool,
-retry/backoff, structlog, BDD).
+**Phase 4 — Hardening DONE (v0.4.0a2).** Per-worker Page pool, tenacity
+retry/backoff with reCAPTCHA re-mint, RFC 9457 Problem Details error
+taxonomy with per-class exit codes 3–7, structlog observability with
+`error_raised` / `error_unhandled` events, and 12 pytest-bdd scenarios all
+shipped. Documentation polish landed in v0.4.0a2. Next phase TBD — likely
+Phase 5 public alpha on PyPI followed by Phase 6 operations history
+(see `PLAN.md`).
 
 ## Architecture (skim)
 
 > Note: the layered diagram below describes the **target** architecture
 > (deferred per [PLAN.md ADR #2](PLAN.md#5-decision-log-adrs-in-miniature)).
 > The current package layout is the simpler
-> `src/flow_cli/{api/, cli.py, cli_image.py, cli_video.py, auth.py,
-> config.py, paths.py, profile_store.py}`. See
+> `src/gflow_cli/{api/, cli.py, cli_image.py, cli_video.py, _cli_helpers.py,
+> auth.py, config.py, errors.py, observability.py, paths.py,
+> profile_store.py}`. See
 > [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full target shape.
 
 ```text
@@ -45,18 +50,18 @@ Dependency rule: **`domain/` depends on nothing**. `application/` depends on `do
 - **Never commit secrets.** `.gitignore` excludes `auth/`, `profile_*/`, `*.cookies.json`, `storage_state.json`, `secrets.json`, `.env`, `.env.local`, `.env.*.local`. If you see one of these staged, abort and tell the user.
 - **Never add `Co-Authored-By: Claude` (or any AI co-author) to commit messages.** Author attribution is the human user's only.
 - **Sessions belong outside the repo.** Default location is `$LOCALAPPDATA/gflow-cli/profile_*` (Windows) or `~/.local/share/gflow-cli/profile_*` (POSIX) via [`platformdirs`](https://github.com/platformdirs/platformdirs). Never store sessions in `/tmp`, `%TEMP%`, or anywhere the OS auto-reaps.
-- **No `print()` in `src/`** — use `structlog` (or `logging` until structlog lands in Phase 1).
-- **Domain layer is pure** — `src/flow_cli/domain/*` must not import `application/`, `infrastructure/`, or `interfaces/`. No I/O, no frameworks.
+- **No raw `print()` and no `import logging` in `src/`** — use `structlog` for structured events, or Rich `console.print(...)` for user-facing output.
+- **Domain layer is pure** — `src/gflow_cli/domain/*` must not import `application/`, `infrastructure/`, or `interfaces/`. No I/O, no frameworks.
 - **Frozen dataclasses for value objects.** Aggregates may have controlled mutation methods, but VOs (AspectRatio, Prompt, JobId, ...) are immutable.
 - **Async all the way down.** Handlers and providers are `async def`. CLI is the only place that calls `asyncio.run(...)`.
 - **TDD is non-negotiable.** Red → Green → Refactor → Commit. Coverage floor: **80% overall**, **90% on `domain/` and `application/`**. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Coding conventions
 
-- **Python 3.11+**, strict typing (`pyright --strict` on `src/flow_cli/`), `from __future__ import annotations` at the top of every module.
+- **Python 3.11+**, strict typing (`pyright --strict` on `src/gflow_cli/`), `from __future__ import annotations` at the top of every module.
 - **`@dataclass(frozen=True)`** for value objects and DTOs. `Protocol` for ports.
 - **`pathlib.Path`** everywhere — never raw strings for filesystem paths.
-- **Click + Rich** for the CLI, **httpx + Playwright** for I/O, **pytest + pytest-bdd** for tests.
+- **Click + Rich** for the CLI, **Playwright `page.request`** as the HTTP transport (auto-attaches Google session cookies), **`tenacity`** for retry/backoff, **`structlog`** for structured logs, **`pytest + pytest-bdd`** for tests.
 - **Conventional Commits** for messages (`feat:`, `fix:`, `docs:`, `test:`, `chore:`, `refactor:`, etc.). See examples in `git log`.
 - **Short files, single responsibility.** ~200-400 lines typical, 800 max. Split into `package/<topic>.py` if growing.
 
@@ -68,7 +73,7 @@ Run all four BEFORE asking to commit:
 uv run ruff check src tests          # lint
 uv run ruff format --check src tests # formatting
 uv run pyright src                   # types
-uv run pytest -q --cov=flow_cli      # tests + coverage
+uv run pytest -q --cov=gflow_cli      # tests + coverage
 ```
 
 CI runs the same four on every push (see `.github/workflows/ci.yml`).
@@ -78,10 +83,10 @@ CI runs the same four on every push (see `.github/workflows/ci.yml`).
 | I need to… | Read this |
 |---|---|
 | Understand the architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
-| Add a CLI command | [docs/USAGE.md](docs/USAGE.md) + existing patterns in `src/flow_cli/cli.py` |
-| Add an API route | [PLAN.md § 4 Phase status](PLAN.md#4-phase-status) + existing client in `src/flow_cli/api/client.py` + capture data under `samples/captured/` |
+| Add a CLI command | [docs/USAGE.md](docs/USAGE.md) + existing patterns in `src/gflow_cli/cli.py` |
+| Add an API route | [PLAN.md § 4 Phase status](PLAN.md#4-phase-status) + existing client in `src/gflow_cli/api/client.py` + capture data under `samples/captured/` |
 | Touch auth | [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md) |
-| Add a config knob | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) + `.env.template` + (later) `src/flow_cli/shared/config.py` |
+| Add a config knob | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) + `.env.template` + (later) `src/gflow_cli/shared/config.py` |
 | Write a test | [CONTRIBUTING.md § TDD](CONTRIBUTING.md#test-driven-development-mandatory) + existing patterns in `tests/` |
 | Cut a release | [README § Releases](README.md#releases) — bump version in `pyproject.toml`, update CHANGELOG, `git tag vX.Y.Z`, push |
 | Track a known issue | [KNOWN_ISSUES.md](KNOWN_ISSUES.md) |
@@ -104,7 +109,7 @@ uv run gflow auth login --profile experiments  # named profile
 2. `uv run pytest tests/<area>/test_<thing>.py` — verify it fails for the right reason.
 3. Implement the minimum production code to pass.
 4. Refactor.
-5. `uv run pytest -q --cov=flow_cli` — verify nothing else broke and coverage didn't regress.
+5. `uv run pytest -q --cov=gflow_cli` — verify nothing else broke and coverage didn't regress.
 
 ### Update a doc
 

{gflow_cli-0.3.0a1 → gflow_cli-0.4.0a2}/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to gflow-cli
 
-Thanks for considering a contribution! Pre-1.0 the repo is private and managed by [@ffroliva](https://github.com/ffroliva), but the workflow described here is what'll be opened up to the community at the v0.2 alpha milestone.
+Thanks for considering a contribution! The repo is public and PRs are welcome. Pre-1.0 means APIs may shift between minor versions; check [PLAN.md](PLAN.md) for the active phase before starting a non-trivial change.
 
 ## Development setup
 
@@ -39,6 +39,8 @@ def test_parse_uuid_from_url(): ...
 async def test_upload_returns_asset(): ...
 
 @pytest.mark.live              # Hits the real Flow API. Requires GFLOW_LIVE=1 env var.
+# Note: the live-test gate is GFLOW_LIVE (deliberately short — not GFLOW_CLI_LIVE) so
+# you can opt in with a single export. Runtime config still uses the GFLOW_CLI_* prefix.
 @pytest.mark.skipif(not os.getenv("GFLOW_LIVE"), reason="live tests opt-in")
 async def test_full_i2v_roundtrip(): ...
 ```
@@ -47,20 +49,20 @@ CI runs `unit` + `integration` on every push. `live` tests run only on the maint
 
 ### Coverage targets
 
-- **`src/flow_cli/cli.py`, `src/flow_cli/cli_image.py`, `src/flow_cli/cli_video.py`**: 70%+ (CLI plumbing — some Click branches are hard to unit-test)
-- **`src/flow_cli/api/`**: 90%+ (the meat — every captured route has a contract test)
-- **`src/flow_cli/auth.py`, `config.py`, `paths.py`, `profile_store.py`**: 80%+
+- **`src/gflow_cli/cli.py`, `src/gflow_cli/cli_image.py`, `src/gflow_cli/cli_video.py`**: 70%+ (CLI plumbing — some Click branches are hard to unit-test)
+- **`src/gflow_cli/api/`**: 90%+ (the meat — every captured route has a contract test)
+- **`src/gflow_cli/auth.py`, `config.py`, `paths.py`, `profile_store.py`**: 80%+
 - **Overall**: 80%+
 
-`uv run pytest --cov=flow_cli --cov-fail-under=80` enforces the floor. Don't merge below it.
+`uv run pytest --cov=gflow_cli --cov-fail-under=80` enforces the floor. Don't merge below it.
 
 ## Quality gates (run before commit)
 
 ```bash
 uv run ruff check src tests          # lint
 uv run ruff format src tests         # auto-format
-uv run pyright src                   # type-check (strict on src/flow_cli/)
-uv run pytest -q --cov=flow_cli      # tests + coverage
+uv run pyright src                   # type-check (strict on src/gflow_cli/)
+uv run pytest -q --cov=gflow_cli      # tests + coverage
 ```
 
 CI runs all four on every push. Local pre-commit hook recommended:
@@ -84,7 +86,7 @@ repos:
        result = await mock_client.new_route(...)
        assert result.some_field
    ```
-3. **Implement** in `src/flow_cli/api/client.py` (and add helpers under `src/flow_cli/api/` as needed) until green.
+3. **Implement** in `src/gflow_cli/api/client.py` (and add helpers under `src/gflow_cli/api/` as needed) until green.
 4. **Add a `live` test** that runs the real flow end-to-end (skipped in CI by default).
 5. **Update `CHANGELOG.md`** under `[Unreleased] → Added`.
 6. **Document** the route in the README's Architecture section if it's a new capability.

{gflow_cli-0.3.0a1 → gflow_cli-0.4.0a2}/DISCLAIMER.md

@@ -13,7 +13,7 @@ This tool calls Google's private REST API at `aisandbox-pa.googleapis.com`. That
 - **Subject to access controls.** Google may rate-limit, throttle, restrict, or revoke access to this surface for any account at any time.
 - **Not covered by any Google SLA.** When this surface goes down, you have no support recourse.
 
-If you need a stable, supported, contractual API, use the [official Google Gen AI SDK](https://github.com/googleapis/python-genai) and the public Veo API on `generativelanguage.googleapis.com`. `gflow-cli` plans to support that path as a `--provider official` option in v0.3+.
+If you need a stable, supported, contractual API, use the [official Google Gen AI SDK](https://github.com/googleapis/python-genai) and the public Veo API on `generativelanguage.googleapis.com`. `gflow-cli` may support that path as a `GFLOW_CLI_PROVIDER=official` option in a future release (planned v0.5+); it is **not** part of v0.4.0a2.
 
 ## Account responsibility
 
@@ -69,4 +69,4 @@ See [LICENSE](LICENSE) for the full legal text. By installing or using `gflow-cl
 
 ---
 
-_Last updated: 2026-05-09._
+_Last updated: 2026-05-11 — refreshed for v0.4.0a2._

{gflow_cli-0.3.0a1 → gflow_cli-0.4.0a2}/KNOWN_ISSUES.md

@@ -35,7 +35,7 @@ Re-running `auth login` reuses the existing profile dir (you typically just clic
 
 **Why we don't auto-refresh:** Google's session-refresh flow can include CAPTCHA / device verification that only a human can complete. A community SDK can't reliably automate that step. See [docs/AUTHENTICATION.md § Refresh / expiry](docs/AUTHENTICATION.md#refresh--expiry).
 
-**Roadmap:** v0.4 will add a periodic background "session liveness" check that warns ~24h before expected expiry, and a `gflow auth refresh` command that opens the browser only if needed.
+**Roadmap:** not scheduled. The Phase 4 hardening pass (v0.4.0a2) added typed `AuthExpiredError` + exit code `3` so scripts can branch on auth expiry deterministically. A periodic "session liveness" check + a `gflow auth refresh` command are still candidates for a later phase, but not committed to a version yet.
 
 ---
 
@@ -49,13 +49,13 @@ Chromium refuses to open two persistent contexts on the same `user-data-dir` sim
 
 ```bash
 # Terminal 1
-gflow image batch ./batch-a.tsv --profile work
+gflow video batch ./batch-a.tsv --profile work
 
 # Terminal 2 — different profile, same time, OK
-gflow image batch ./batch-b.tsv --profile personal
+gflow video batch ./batch-b.tsv --profile personal
 ```
 
-**Roadmap:** v0.4's per-account pool will queue same-profile calls automatically.
+**Roadmap:** Phase 4 (v0.4.0a2) added concurrency *inside* one `gflow video batch` process via `GFLOW_CLI_CONCURRENCY=N` (per-worker Page pool on one shared BrowserContext). Cross-process same-profile serialization is a Chromium constraint we cannot work around without rewriting the auth model — multiple shells against the same profile remains a "use different profiles" workaround.
 
 ---
 
@@ -93,11 +93,29 @@ Other ratios may be silently rejected or coerced server-side. We validate in the
 
 ---
 
+### `gflow video batch` does not skip already-completed entries
+
+- **Status:** Open · **Severity:** Medium · **Affects:** v0.2.0a1+
+
+If a `gflow video batch` run dies partway through (auth expiry, network blip, Ctrl-C) and you rerun the same TSV manifest, every row is re-submitted to Flow. Flow's private API does not expose a "have I generated this before?" predicate, and `gflow-cli` does not yet maintain a local manifest-of-outputs to compare against.
+
+**Cost implication:** re-running a partially completed manifest **may consume additional Veo / Imagen credits**. We cannot guarantee that Flow de-duplicates server-side — credit accounting on a private API is not contractual.
+
+**Workaround:** before rerunning, trim the manifest down to the rows whose `output_path` does not yet exist on disk:
+```bash
+awk -F'\t' 'NR==1 || (system("test -e " $NF) != 0)' manifest.tsv > manifest.remaining.tsv
+gflow video batch manifest.remaining.tsv
+```
+
+**Roadmap:** under consideration for Phase 6 (operations history with a local SQLite ledger — see `PLAN.md`).
+
+---
+
 ### Output dir is not tidied automatically
 
 - **Status:** Open · **Severity:** Low · **By design**
 
-`gflow-cli` never deletes from `$FLOW_CLI_OUTPUT_DIR`. Generated assets accumulate forever unless you clean them up.
+`gflow-cli` never deletes from `$GFLOW_CLI_OUTPUT_DIR`. Generated assets accumulate forever unless you clean them up.
 
 **Workaround:** schedule a cron / Task Scheduler job, e.g.:
 ```bash
@@ -119,7 +137,7 @@ _(none yet)_
 
 - **Status:** Resolved · **Severity:** Critical (blocked usage) · **Fixed in:** v0.2.0a1
 
-The v0.1 scaffold left `upload_image`, `start_generation`, `get_job`, `download` raising `NotImplementedError`. v0.2.0a1 wired the video routes (T2V/I2V/batch) on a new `flow_cli.api.client.FlowApiClient` and removed the legacy `providers/` + `models` modules. v0.3.0a1 added the image routes (`gflow image upload/t2i/i2i`) on the same client.
+The v0.1 scaffold left `upload_image`, `start_generation`, `get_job`, `download` raising `NotImplementedError`. v0.2.0a1 wired the video routes (T2V/I2V/batch) on a new `gflow_cli.api.client.FlowApiClient` and removed the legacy `providers/` + `models` modules. v0.3.0a1 added the image routes (`gflow image upload/t2i/i2i`) on the same client.
 
 ---