gflow-cli 0.2.0a1__tar.gz → 0.3.0a1__tar.gz

{gflow_cli-0.2.0a1 → gflow_cli-0.3.0a1}/.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.3.0a1}/.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
 
@@ -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.2.0a1 → gflow_cli-0.3.0a1}/.env.template

@@ -1,4 +1,4 @@
-# flow-cli — example environment variables.
+# gflow-cli — example environment variables.
 # Copy to `.env` (in this repo or in $FLOW_CLI_HOME) and customise.
 # All variables are OPTIONAL — defaults work out of the box for most users.
 
@@ -7,8 +7,10 @@
 # -----------------------------------------------------------------------------
 
 # Root directory for Playwright persistent contexts (signed-in Google sessions).
-# Default: %USERPROFILE%/.flow-cli  (Windows)
-#          ~/.flow-cli              (macOS / Linux)
+# 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)
 # FLOW_CLI_HOME=
 
 # Default profile name. Override per-call with `--profile <name>`.
@@ -23,9 +25,9 @@ FLOW_CLI_PROFILE=default
 #   <output_dir>/videos/<YYYY-MM-DD>/<job_id>.mp4
 #
 # Default (via `platformdirs`):
-#   Windows: %USERPROFILE%\Downloads\flow-cli
-#   macOS:   ~/Downloads/flow-cli
-#   Linux:   $XDG_DOWNLOAD_DIR/flow-cli  (falls back to ~/Downloads/flow-cli)
+#   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=
 
 # -----------------------------------------------------------------------------
@@ -34,7 +36,7 @@ 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.3+, requires Gemini API key)
+#   official  - official Veo SDK (planned for v0.5+, requires Gemini API key)
 FLOW_CLI_PROVIDER=flow
 
 # Gemini API key — only required when FLOW_CLI_PROVIDER=official.
@@ -57,3 +59,9 @@ FLOW_CLI_LOG_FORMAT=auto
 
 # Concurrency for batch operations (requires multiple profiles, v0.4+).
 FLOW_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-0.2.0a1 → gflow_cli-0.3.0a1}/.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.3.0a1}/.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.3.0a1/CHANGELOG.md

@@ -0,0 +1,127 @@
+# 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.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 `$FLOW_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.
+- `flow_cli.api` package — low-level REST client (`FlowApiClient`) + value objects
+  (`GenerateVideoRequest`, `VideoOperation`, `VideoStatus`) for video generation.
+- `flow_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.
+- `flow_cli.manifest` — TSV manifest parser for `gflow video batch`. Supports optional
+  `start_image`, `end_image`, `aspect`, `output_path` columns; skips `# `-prefixed comments.
+- `FLOW_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.
+- `flow_cli.profile_store` — profile inventory + default-profile persistence
+  in `$FLOW_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
+- `flow_cli.providers.FlowProvider` and `flow_cli.models` — superseded by `flow_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.3.0a1...HEAD
+[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.3.0a1}/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,18 @@
 
 ## 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 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).
 
 ## 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/flow_cli/{api/, cli.py, cli_image.py, cli_video.py, auth.py,
+> config.py, paths.py, profile_store.py}`. See
+> [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full target shape.
 
 ```text
 interfaces/   →  application/   →  domain/   ←  infrastructure/
@@ -37,7 +44,7 @@ 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.
+- **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.
 - **Frozen dataclasses for value objects.** Aggregates may have controlled mutation methods, but VOs (AspectRatio, Prompt, JobId, ...) are immutable.
@@ -72,7 +79,7 @@ CI runs the same four on every push (see `.github/workflows/ci.yml`).
 |---|---|
 | 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 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/` |
 | 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` |
 | Write a test | [CONTRIBUTING.md § TDD](CONTRIBUTING.md#test-driven-development-mandatory) + existing patterns in `tests/` |
@@ -121,6 +128,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
 

{gflow_cli-0.2.0a1 → gflow_cli-0.3.0a1}/CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to flow-cli
+# 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.
 
@@ -6,14 +6,14 @@ Thanks for considering a contribution! Pre-1.0 the repo is private and managed b
 
 ```bash
 git clone git@github.com:ffroliva/gflow-cli.git
-cd flow-cli
+cd gflow-cli
 uv sync --extra dev
 uv run playwright install chromium
 ```
 
 ## Test-driven development (mandatory)
 
-`flow-cli` is built test-first. Every change must include tests, and CI rejects PRs that lower coverage.
+`gflow-cli` is built test-first. Every change must include tests, and CI rejects PRs that lower coverage.
 
 The cycle:
 
@@ -47,9 +47,9 @@ CI runs `unit` + `integration` on every push. `live` tests run only on the maint
 
 ### Coverage targets
 
-- **`src/flow_cli/cli.py`**: 70%+ (CLI plumbing — some Click branches are hard to unit-test)
-- **`src/flow_cli/providers/`**: 90%+ (the meat — every captured route has a contract test)
-- **`src/flow_cli/auth.py`, `models.py`**: 80%+
+- **`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%+
 - **Overall**: 80%+
 
 `uv run pytest --cov=flow_cli --cov-fail-under=80` enforces the floor. Don't merge below it.
@@ -75,17 +75,16 @@ repos:
       - id: ruff-format
 ```
 
-## Adding a new Provider route
+## Adding a new API route
 
-1. **Capture the live request** — add to `samples/captured_requests.json` (sanitise project IDs, asset UUIDs).
-2. **Write the contract test first** — `tests/providers/test_flow_<route>.py`:
+1. **Capture the live request** — add a sanitised JSON sample under `samples/captured/` (numbered, e.g. `08_<route>.json`; scrub project IDs, asset UUIDs, bearer tokens, and reCAPTCHA tokens).
+2. **Write the contract test first** — under `tests/api/`:
    ```python
-   async def test_upload_image_returns_asset(mock_flow_provider):
-       asset = await mock_flow_provider.upload_image(Path("tests/fixtures/sample.png"))
-       assert asset.uuid
-       assert asset.kind == "image"
+   async def test_new_route_returns_expected_dto(mock_client):
+       result = await mock_client.new_route(...)
+       assert result.some_field
    ```
-3. **Implement** in `src/flow_cli/providers/flow.py` until green.
+3. **Implement** in `src/flow_cli/api/client.py` (and add helpers under `src/flow_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.2.0a1 → gflow_cli-0.3.0a1}/DISCLAIMER.md

@@ -2,22 +2,22 @@
 
 ## Not affiliated with Google
 
-`flow-cli` is an **independent, unofficial** project. It is **not affiliated with, endorsed by, sponsored by, or otherwise connected to Google LLC, Alphabet Inc., DeepMind, or any of their subsidiaries.** All trademarks (Google, Flow, Veo, Gemini, Imagen, AI Ultra, AI Pro) are the property of their respective owners. The use of these names here is purely descriptive — to identify the service this tool integrates with — and does not imply endorsement.
+`gflow-cli` is an **independent, unofficial** project. It is **not affiliated with, endorsed by, sponsored by, or otherwise connected to Google LLC, Alphabet Inc., DeepMind, or any of their subsidiaries.** All trademarks (Google, Flow, Veo, Gemini, Imagen, AI Ultra, AI Pro) are the property of their respective owners. The use of these names here is purely descriptive — to identify the service this tool integrates with — and does not imply endorsement.
 
 ## Reverse-engineered surface
 
 This tool calls Google's private REST API at `aisandbox-pa.googleapis.com`. That surface is:
 
 - **Undocumented.** Google does not publish a contract for it.
-- **Unstable.** Endpoints, request shapes, and response shapes may change without notice. A version of `flow-cli` that worked yesterday may break today.
+- **Unstable.** Endpoints, request shapes, and response shapes may change without notice. A version of `gflow-cli` that worked yesterday may break today.
 - **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`. `flow-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` plans to support that path as a `--provider official` option in v0.3+.
 
 ## Account responsibility
 
-To use `flow-cli` you must:
+To use `gflow-cli` you must:
 
 1. **Own a valid Google account** with active access to [Google Flow](https://labs.google/fx/tools/flow) — typically an [AI Ultra or AI Pro](https://gemini.google/subscriptions/) subscription as of late 2025.
 2. **Comply with Google's terms of service** for that account, including:
@@ -26,13 +26,13 @@ To use `flow-cli` you must:
    - Any subscription-specific terms (Ultra, Pro, etc.)
    - The [Google Labs Additional Terms](https://labs.google/terms) governing Flow
 
-3. **Bear all costs.** Every generation made through `flow-cli` consumes credits from your Google account, exactly as if you had clicked "Generate" in the web UI. Neither the maintainer nor any contributor will be liable for unexpected billing.
+3. **Bear all costs.** Every generation made through `gflow-cli` consumes credits from your Google account, exactly as if you had clicked "Generate" in the web UI. Neither the maintainer nor any contributor will be liable for unexpected billing.
 
-4. **Use only your own credentials.** Sharing accounts, automating mass-account creation, or otherwise circumventing Google's per-account quotas is prohibited by Google's terms and is **not a supported use case for `flow-cli`**.
+4. **Use only your own credentials.** Sharing accounts, automating mass-account creation, or otherwise circumventing Google's per-account quotas is prohibited by Google's terms and is **not a supported use case for `gflow-cli`**.
 
 ## Prohibited uses
 
-The maintainer asks that you do **not** use `flow-cli` to:
+The maintainer asks that you do **not** use `gflow-cli` to:
 
 - Generate content that violates the [Generative AI Prohibited Use Policy](https://policies.google.com/terms/generative-ai/use-policy) (CSAM, harassment, IP infringement, etc.).
 - Circumvent Google's billing, quota, or rate limits via account-rotation farms.
@@ -43,7 +43,7 @@ These uses can get **your** Google account banned, can put the maintainer in a d
 
 ## Takedown policy
 
-If Google formally requests that `flow-cli` cease or restrict any reverse-engineered surface, the maintainer will:
+If Google formally requests that `gflow-cli` cease or restrict any reverse-engineered surface, the maintainer will:
 
 1. Acknowledge the request publicly within 7 days.
 2. Comply by archiving / removing the affected code path.
@@ -53,13 +53,13 @@ If you are at Google and reading this: please open an issue at <https://github.c
 
 ## No warranty
 
-`flow-cli` is provided **AS IS**, without warranty of any kind, express or implied. The maintainer:
+`gflow-cli` is provided **AS IS**, without warranty of any kind, express or implied. The maintainer:
 
 - Makes no guarantee that any version will work, today or tomorrow.
 - Makes no guarantee about output quality, completeness, or fitness for any particular use.
 - Will not be liable for lost credits, banned accounts, lost time, or any other damages arising from use of this tool.
 
-See [LICENSE](LICENSE) for the full legal text. By installing or using `flow-cli`, you acknowledge that you have read and accept this disclaimer.
+See [LICENSE](LICENSE) for the full legal text. By installing or using `gflow-cli`, you acknowledge that you have read and accept this disclaimer.
 
 ## Reporting issues
 

{gflow_cli-0.2.0a1 → gflow_cli-0.3.0a1}/KNOWN_ISSUES.md

@@ -24,7 +24,7 @@ Google's web session cookies aren't permanent. They expire when:
 - You sign out from another device's session manager
 - Google flags the session as suspicious (geo-jump, new device fingerprint)
 
-When this happens, the next API call returns 401/403 and `flow-cli` raises `AuthExpiredError`.
+When this happens, the next API call returns 401/403 and `gflow-cli` raises `AuthExpiredError`.
 
 **Workaround:**
 ```bash
@@ -59,23 +59,13 @@ gflow image batch ./batch-b.tsv --profile personal
 
 ---
 
-### v0.1 — provider methods are stubs
-
-- **Status:** Open · **Severity:** Critical (blocks usage) · **Resolution:** v0.2
-
-The current published code is a **scaffold**. `upload_image`, `start_generation`, `get_job`, `download` all raise `NotImplementedError` until the route wiring lands in [PLAN](PLAN.md) Phases 2 and 3.
-
-**Workaround:** none — wait for v0.2.
-
----
-
 ### Flow's first-upload terms-of-use dialog ("Aviso") blocks the worker (worker-only)
 
-- **Status:** Open · **Severity:** Low · **Affects:** the legacy in-tree Compiled Growth worker, NOT `flow-cli` itself
+- **Status:** Open · **Severity:** Low · **Affects:** the legacy in-tree Compiled Growth worker, NOT `gflow-cli` itself
 
-Flow shows a one-time "Aviso" / "Notice" terms-of-use confirmation on the first image upload of a new account session. The legacy Playwright worker has to explicitly click "Concordo" / "Agree". `flow-cli`'s API-driven path bypasses this dialog entirely (the REST endpoint already implies acceptance).
+Flow shows a one-time "Aviso" / "Notice" terms-of-use confirmation on the first image upload of a new account session. The legacy Playwright worker has to explicitly click "Concordo" / "Agree". `gflow-cli`'s API-driven path bypasses this dialog entirely (the REST endpoint already implies acceptance).
 
-**Workaround in flow-cli:** none needed.
+**Workaround in gflow-cli:** none needed.
 
 **Workaround in legacy worker:** see Compiled Growth's `flow_video.py` consent-dismiss block.
 
@@ -85,7 +75,7 @@ Flow shows a one-time "Aviso" / "Notice" terms-of-use confirmation on the first
 
 - **Status:** Open · **Severity:** Low · **Roadmap:** v0.5
 
-`flow-cli` doesn't yet show how many Veo / Imagen credits remain on your Ultra/Pro subscription. You can check at <https://gemini.google/subscriptions/> in the meantime.
+`gflow-cli` doesn't yet show how many Veo / Imagen credits remain on your Ultra/Pro subscription. You can check at <https://gemini.google/subscriptions/> in the meantime.
 
 **Roadmap:** v0.5 will surface remaining quota via `gflow auth status` once we capture the relevant Google API.
 
@@ -107,12 +97,12 @@ Other ratios may be silently rejected or coerced server-side. We validate in the
 
 - **Status:** Open · **Severity:** Low · **By design**
 
-`flow-cli` never deletes from `$FLOW_CLI_OUTPUT_DIR`. Generated assets accumulate forever unless you clean them up.
+`gflow-cli` never deletes from `$FLOW_CLI_OUTPUT_DIR`. Generated assets accumulate forever unless you clean them up.
 
 **Workaround:** schedule a cron / Task Scheduler job, e.g.:
 ```bash
 # Delete files older than 30 days
-find "$HOME/Downloads/flow-cli" -type f -mtime +30 -delete
+find "$HOME/Downloads/gflow-cli" -type f -mtime +30 -delete
 ```
 
 ---
@@ -125,7 +115,11 @@ _(none yet)_
 
 ## Resolved
 
-_(none yet — first release pending)_
+### v0.1 — provider methods are stubs
+
+- **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.
 
 ---
 
@@ -135,7 +129,7 @@ If you hit something not listed here:
 
 1. Search existing issues at <https://github.com/ffroliva/gflow-cli/issues>.
 2. If none match, open a new issue with:
-   - `flow-cli` version (`gflow --version`)
+   - `gflow-cli` version (`gflow --version`)
    - Python version (`python --version`)
    - OS + version
    - Exact command that failed + full error output