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

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

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

gflow_cli-0.8.1/AGENTS.md

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

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

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.1] — 2026-05-23
+
+### Documentation
+
+- README rewritten as a hybrid router (~150 lines, was 398). New: prominent unofficial-tool + headed-browser callouts above the fold, polished 60-second quick start, in-depth-quick-start link, "For AI agents & LLMs" routing table, ripgrep-style documentation TOC.
+- New [AGENTS.md](AGENTS.md) at repo root — universal agent spec consumed by 60k+ repos' tooling (Cursor, Codex, Aider, Gemini CLI, Claude Code, Copilot, opencode, etc.). Closes the gap left by having Claude-Code-only memory.
+- New [llms.txt](llms.txt) at repo root — llmstxt.org-format summary for end-users feeding the project into an LLM. Forward-staged for a future docs site.
+- New [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md) — moved the full milestone table out of README; added lifecycle policy section.
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) absorbed the ASCII system diagram + Auth strategy paragraphs from README; gained a new "Headed-browser dependency — current limitation" subsection that documents the three retired HTTP transports and invites contributor work on a pure-REST path.
+- [CLAUDE.md](CLAUDE.md) trimmed from ~80 to ~25 lines; universal coding-agent rules now live in AGENTS.md, with CLAUDE.md carrying Claude-Code-specific session protocol only.
+- All `v0.7.0` references that meant "current" updated to `v0.8.1`. Historical mentions preserved in CHANGELOG and `docs/LIVE_VERIFICATION_v0.7.0.md`.
+- New per-release evidence file [docs/LIVE_VERIFICATION_v0.8.1.md](docs/LIVE_VERIFICATION_v0.8.1.md).
+
+### Released
+
+- PyPI: https://pypi.org/project/gflow-cli/0.8.1/ — refreshes the stale README rendering left over from v0.8.0.
+
 ## [0.8.0] — 2026-05-23
 
 > **Multi-image-prompt release + transport hardening.** Introduces the

gflow_cli-0.8.1/CLAUDE.md

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

gflow_cli-0.8.1/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: gflow-cli
+Version: 0.8.1
+Summary: Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal.
+Project-URL: Homepage, https://github.com/ffroliva/gflow-cli
+Project-URL: Issues, https://github.com/ffroliva/gflow-cli/issues
+Author-email: Flavio Oliva <ffroliva@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Flavio Oliva (ffroliva)
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai,cli,flow,google,veo,video
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: playwright>=1.45.0
+Requires-Dist: pydantic-settings>=2.5.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: structlog>=24.0.0
+Requires-Dist: tenacity>=8.2
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gflow-cli
+
+> **Unofficial Python CLI for Google Flow.** Drive [Veo](https://labs.google/fx/tools/flow) (image-to-video, text-to-video) and Imagen (text-to-image) generations from your terminal — scripted, batched, pipeline-friendly.
+
+[![PyPI version](https://img.shields.io/pypi/v/gflow-cli.svg)](https://pypi.org/project/gflow-cli/)
+[![CI](https://github.com/ffroliva/gflow-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/ffroliva/gflow-cli/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/gflow-cli.svg)](https://pypi.org/project/gflow-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](docs/PROJECT_STATUS.md)
+
+> ⚠️ **Unofficial. Reverse-engineered. Not affiliated with Google.** Endpoints can change at any time. Full [DISCLAIMER](DISCLAIMER.md).
+>
+> 🌐 **Headed-browser today.** gflow drives Flow via a persistent Playwright Chromium profile — Google's auth + reCAPTCHA gates currently require it. See [Architecture & current limitations](#architecture--current-limitations) for the contributor opportunity.
+
+## Why gflow-cli?
+
+For Google AI Ultra / Pro subscribers with Veo credits and batch workloads:
+
+- **Burn credits efficiently** — `for p in $(cat prompts.txt); do gflow image t2i "$p"; done` _(image batching ships today; `gflow video i2v` lands in Phase B)_
+- **Build pipelines** — wire Veo into your content automation, AI video stack, or batch experiments
+- **Stay in the terminal** — no Chromium UI, no clicking through dialogs (after a one-time `gflow auth login`)
+
+Same Veo + Imagen models, same quality, same Ultra/Pro billing — programmatic.
+
+## 60-second quick start
+
+```bash
+# 1 · Install (uv recommended — also: pip install gflow-cli)
+uv tool install gflow-cli
+uv tool run --from gflow-cli playwright install chromium     # one-time, ~150 MB
+
+# 2 · Authenticate (one-time, opens a real Chrome window)
+gflow auth login --browser chrome
+
+# 3 · Generate
+gflow image t2i "a hot air balloon over Tokyo at sunrise"
+# or:
+gflow video t2v "Slow cinematic push-in on a sunlit forest clearing" --aspect 16:9
+```
+
+Outputs land under `./out/` (or `$GFLOW_CLI_OUTPUT_DIR`). First call is ~30–90 s while Chromium warms; subsequent calls reuse the warm session.
+
+> **Why `--browser chrome`?** Google rejects Playwright's bundled Chromium. The CLI fails fast with a friendly error (`AuthBrowserRejectedError`, exit code 14) if you pick anything else.
+
+## In-depth quick start
+
+See **[USER_GUIDE — Journey 1: First-time setup](docs/USER_GUIDE.md#journey-1--first-time-setup-10-minutes)** for the 10-minute walkthrough with troubleshooting, multi-account setup, and the structured-log primer.
+
+## Demo
+
+![gflow image t2i — single 9:16 prompt, streaming structlog output, PNG on disk](docs/assets/example-run.gif)
+
+*A single `gflow image t2i "..." --aspect 9:16 --model nano2` call against a logged-in Pro/Ultra profile. Terminal shows the streaming `structlog` JSON for the run, the final `ls` of the written PNG, and nothing else — Chromium drives the Flow editor silently in the background.*
+
+Reproduce the recording: [`scripts/record_demo.ps1`](scripts/record_demo.ps1) (Windows + OBS + ffmpeg + gifski).
+
+## Documentation
+
+[**docs/INDEX.md**](docs/INDEX.md) is the master routing layer. Quick links:
+
+| Topic | Read |
+|---|---|
+| 🎯 **Getting started** | [User Guide](docs/USER_GUIDE.md) · [Usage](docs/USAGE.md) · [Configuration](docs/CONFIGURATION.md) |
+| 🔐 **Auth & sessions** | [Authentication](docs/AUTHENTICATION.md) · [Known issues](KNOWN_ISSUES.md) |
+| 🏗️ **Internals** | [Architecture](docs/ARCHITECTURE.md) · [Security](docs/SECURITY.md) · [Debugging](docs/DEBUGGING.md) |
+| 📦 **Releases** | [Changelog](CHANGELOG.md) · [Release protocol](RELEASE.md) · [Project status](docs/PROJECT_STATUS.md) |
+| 🤝 **Contributing** | [Contributing](CONTRIBUTING.md) · [Development](docs/DEVELOPMENT.md) · [GitHub workflow](docs/GITHUB.md) |
+
+## For AI agents & LLMs
+
+gflow-cli ships three agent entry points — pick the one your tool reads first.
+
+| File | Audience | Tools |
+|---|---|---|
+| [**AGENTS.md**](AGENTS.md) | Universal coding-agent spec | Cursor · Codex · Aider · Gemini CLI · Jules · Devin · Windsurf · Zed · Warp · opencode · Copilot · 60k+ repos |
+| [**CLAUDE.md**](CLAUDE.md) | Claude Code's auto-loaded memory | Claude Code |
+| [**llms.txt**](llms.txt) | LLM-readable summary (llmstxt.org format) | Paste into ChatGPT / Claude / Gemini to onboard the model |
+| [`skills/gflow-cli/SKILL.md`](skills/gflow-cli/SKILL.md) | Claude Code Skill | Symlink into `~/.claude/skills/` |
+
+**Onboarding any agent in one line:** paste this into your agent of choice —
+
+> *"Read [AGENTS.md](https://github.com/ffroliva/gflow-cli/blob/main/AGENTS.md) and [docs/INDEX.md](https://github.com/ffroliva/gflow-cli/blob/main/docs/INDEX.md), then help me with my Flow batch."*
+
+## Architecture & current limitations
+
+```text
+gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (tests) / [planned: Official Veo]
+                                              ↓
+                                      Playwright Chromium (headed login, headless after)
+                                              ↓
+                              aisandbox-pa.googleapis.com  (Google's private Flow API)
+```
+
+**Current transport:** `ui_automation` — drives Flow via a persistent Playwright Chromium profile. Production-stable, end-to-end verified per release (see [LIVE_VERIFICATION_*](docs/) per-release evidence files).
+
+**What's blocked:** A pure HTTP transport for video generation. The video upload endpoint returns HTTP 401 under non-Chrome browsers + a reCAPTCHA mint we cannot reproduce headlessly. Three earlier HTTP strategies (`evaluate_fetch` / `bearer` / `sapisidhash`) are named in the codebase history; the actual transport modules have not yet been extracted into a subpackage.
+
+**How you can help:** If you have successfully driven `aisandbox-pa.googleapis.com` from outside a real Chrome session — or have insight into Google's anti-bot stack here — please open an issue. A working REST transport would unlock serverless deployments, true horizontal concurrency, and roughly 10× the project's reach. Details: [docs/ARCHITECTURE.md § Headed-browser dependency](docs/ARCHITECTURE.md#headed-browser-dependency--current-limitation).
+
+## Project status
+
+**v0.8.1 — alpha (docs refresh).** Image (T2I / I2I / upload) + Video T2V live end-to-end on `ui_automation`. Video I2V + batch are queued for Phase B. Full milestone history → [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md). Changelog → [CHANGELOG.md](CHANGELOG.md).
+
+## License & legal
+
+[MIT License](LICENSE) © 2026 Flavio Oliva (`ffroliva`). The MIT license covers `gflow-cli`'s code only — it does not grant rights to Flow, Veo model output, or any Google service. Google's own terms (Labs Additional Terms, Ultra/Pro subscription terms) govern your generations. See [DISCLAIMER](DISCLAIMER.md).
+
+## Acknowledgements
+
+- [`edge-tts`](https://github.com/rany2/edge-tts) — design inspiration for community SDKs over private cloud APIs.
+- [`googleapis/python-genai`](https://github.com/googleapis/python-genai) — the official Veo SDK that a future provider release may alias.
+- [Keysight — *Google Labs – Flow AI with Veo3: A Network Traffic Analysis*](https://www.keysight.com/blogs/en/tech/nwvs/2025/08/04/google-flow-ai-har-analysis) — independent capture that helped validate the captured route patterns.
+
+---
+
+If `gflow-cli` saves you time, please ⭐ the repo — it is the cheapest way to support the project.