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

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

@@ -2,7 +2,7 @@
 
 This directory holds **internal maintainer workflows** that are bundled with the repo so any contributor running Claude Code in this checkout gets the same environment.
 
-> Distinct from `skills/flow-cli/SKILL.md` at the repo root, which is the **published** Skill end users install into their own Claude Code to learn how to use `gflow` from agent contexts. `.claude/` is for *us*, the maintainers; `skills/` is for *them*, the users.
+> Distinct from `skills/gflow-cli/SKILL.md` at the repo root, which is the **published** Skill end users install into their own Claude Code to learn how to use `gflow` from agent contexts. `.claude/` is for *us*, the maintainers; `skills/` is for *them*, the users.
 
 ## Layout
 
@@ -31,7 +31,7 @@ Example: `commands/foo.md` → invoked as `/foo`.
 
 ## Adding an internal skill
 
-Same shape as the published one in `skills/flow-cli/`:
+Same shape as the published one in `skills/gflow-cli/`:
 
 ```markdown
 ---

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

@@ -1,10 +1,10 @@
 ---
-description: Cut a new flow-cli release — bump version, update CHANGELOG, tag, push.
+description: Cut a new gflow-cli release — bump version, update CHANGELOG, tag, push.
 ---
 
-# `/release` — Cut a new flow-cli release
+# `/release` — Cut a new gflow-cli release
 
-You are about to release a new version of `flow-cli`. Follow this sequence verbatim — every step matters.
+You are about to release a new version of `gflow-cli`. Follow this sequence verbatim — every step matters.
 
 ## Inputs
 
@@ -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`:
@@ -83,4 +83,4 @@ Ask the user (if not already provided):
 ## See also
 
 - [README § Releases](../../README.md#releases) — full release policy & cadence
-- [PLAN § Phase 5](../../PLAN.md#phase-5--public-alpha-release) — first-release exit criteria
+- [PLAN § Phase 5](../../PLAN.md#phase-5--public-alpha-release-on-pypi) — first-release exit criteria

gflow_cli-0.4.0a2/.env.template

@@ -0,0 +1,75 @@
+# gflow-cli — example environment variables.
+# 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
+# -----------------------------------------------------------------------------
+
+# Root directory for Playwright persistent contexts (signed-in Google sessions).
+# Default (via `platformdirs`):
+#   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)
+# GFLOW_CLI_HOME=
+
+# 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
+# -----------------------------------------------------------------------------
+
+# Where downloaded assets land. Subfolders are created per kind/date:
+#   <output_dir>/images/<YYYY-MM-DD>/<job_id>_<index>.png
+#   <output_dir>/videos/<YYYY-MM-DD>/<job_id>.mp4
+#
+# Default (via `platformdirs`):
+#   Windows: %USERPROFILE%\Downloads\gflow-cli
+#   macOS:   ~/Downloads/gflow-cli
+#   Linux:   $XDG_DOWNLOAD_DIR/gflow-cli  (falls back to ~/Downloads/gflow-cli)
+# GFLOW_CLI_OUTPUT_DIR=
+
+# -----------------------------------------------------------------------------
+# Provider selection
+# -----------------------------------------------------------------------------
+
+# 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)
+# GFLOW_CLI_PROVIDER=flow
+
+# Gemini API key — only required when GFLOW_CLI_PROVIDER=official.
+# Get one at https://aistudio.google.com/apikey
+# GFLOW_CLI_GEMINI_API_KEY=
+
+# -----------------------------------------------------------------------------
+# Runtime tuning
+# -----------------------------------------------------------------------------
+
+# Per-request HTTP timeout (seconds). Veo videos can take 60-180s each.
+# GFLOW_CLI_TIMEOUT_SECONDS=600
+
+# Logging level — DEBUG | INFO | WARNING | ERROR
+# GFLOW_CLI_LOG_LEVEL=INFO
+
+# Log format — auto | text | json
+#   auto = text on TTY, json when piped (default)
+# GFLOW_CLI_LOG_FORMAT=auto
+
+# 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.
+# GFLOW_CLI_HEADLESS=true

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

@@ -10,7 +10,9 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.12"]
+        python-version: ["3.11", "3.12", "3.13"]
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
     steps:
       - uses: actions/checkout@v4
 

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

@@ -15,6 +15,8 @@ jobs:
     environment:
       name: pypi
       url: https://pypi.org/p/gflow-cli
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
     steps:
       - uses: actions/checkout@v4
         with:

{gflow_cli-0.2.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.2.0a1 → gflow_cli-0.4.0a2}/CLAUDE.md

@@ -4,7 +4,7 @@
 
 ## What this project is
 
-`flow-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 at `aisandbox-pa.googleapis.com`. Built for Google AI Ultra/Pro subscribers who want to spend their Flow credits via batch automation rather than the web UI.
+`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 at `aisandbox-pa.googleapis.com`. Built for Google AI Ultra/Pro subscribers who want to spend their Flow credits via batch automation rather than the web UI.
 
 **Same pattern as `edge-tts`:** a community SDK over a private cloud API.
 
@@ -17,11 +17,23 @@
 
 ## Active phase
 
-**Phase 1 — Foundation** (refactor scaffold into layered structure, wire `pydantic-settings`, `structlog`, command/query bus). See [PLAN § Phase 1](PLAN.md#phase-1--foundation-target-12-days). Subset already landed: profile-store + `gflow auth` UX (commit `d821f39`).
+**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)
 
-Layered Clean / Hexagonal — see **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** for the full diagram and rationale.
+> 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/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
 interfaces/   →  application/   →  domain/   ←  infrastructure/
@@ -37,19 +49,19 @@ 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/flow-cli/profile_*` (Windows) or `~/.local/share/flow-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.
+- **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 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.
 
@@ -61,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`).
@@ -71,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 a Provider route | [PLAN.md § 4 Feature specs](PLAN.md#4-feature-specs) + existing stubs in `src/flow_cli/providers/flow.py` + capture data in `samples/captured_requests.json` |
+| 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) |
@@ -97,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
 
@@ -121,6 +133,8 @@ uv run gflow auth login --profile experiments  # named profile
 - **Question scope creep.** If the user asks for X and you're tempted to also fix Y, ask first.
 - **Plan before implementing** for anything > 1 file or > 50 LoC. Write the plan into PLAN.md or a comment, then execute.
 - **Show your work.** When you change something non-obvious, leave a one-line comment with the WHY (not the WHAT — the diff already shows the what).
+- **Fix bugs autonomously.** Given a bug report, reproduce it, trace the root cause, fix it, and verify — no hand-holding needed. Point at logs/errors/failing tests, then resolve them.
+- **Learn from corrections.** After any user correction, append the pattern to `tasks/lessons.md` (create if absent) as a rule that prevents the same mistake. Review it at session start for relevant context.
 
 ## See also