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

{gflow_cli-0.5.0a1 → gflow_cli-0.6.0a2}/.gitattributes

@@ -28,8 +28,10 @@ LICENSE     text eol=lf
 *.sh        text eol=lf
 *.bash      text eol=lf
 
-# Windows scripts MUST stay CRLF or they break under PowerShell / cmd.exe
-*.ps1       text eol=crlf
+# PowerShell handles LF fine on both PS 5.1 and Core, so keep .ps1 as LF.
+# cmd.exe has historical edge cases with multi-line batch files, so .bat/.cmd
+# stay CRLF.
+*.ps1       text eol=lf
 *.bat       text eol=crlf
 *.cmd       text eol=crlf
 

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

@@ -15,6 +15,7 @@ env/
 
 # Test / coverage
 .pytest_cache/
+pytest-of-*/
 .coverage
 .coverage.*
 htmlcov/

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

@@ -7,6 +7,101 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0a2] — 2026-05-16
+
+> **Real Chrome auth strategy — G12 block resolved.** This release restores
+> `gflow auth login` reliability by routing logins through the system's real
+> Google Chrome instead of Playwright's bundled Chromium. A carefully ordered
+> stealth configuration prevents Google's bot-detection from blocking the sign-in
+> flow.
+
+### Added
+
+- **`--browser [auto|chrome|internal]` flag** on `gflow auth login` — selects
+  the browser strategy. `chrome` uses real system Chrome (stealth). `internal`
+  falls back to bundled Chromium. `auto` (default) probes for real Chrome and
+  falls back gracefully.
+- **`GFLOW_CLI_AUTH_BROWSER` env var** — overrides the browser strategy without
+  a CLI flag.
+- **`RealChromeStrategy`** (`src/gflow_cli/auth/real_chrome.py`) — stealth
+  persistent context via `channel="chrome"` with
+  `--disable-blink-features=AutomationControlled` and a JS init-script to mask
+  `navigator.webdriver`.
+- **`InternalChromiumStrategy`** — extracted from the previous `auth.py` monolith
+  as an explicit fallback strategy.
+- **`AuthStrategyFactory`** — routes `auto`/`chrome`/`internal` to the
+  appropriate strategy based on system state.
+- **`is_chrome_available()`** in `browser_manager.py` — non-raising probe for
+  system Chrome presence.
+- **4 new BDD scenarios** in `tests/features/auth_login.feature` covering all
+  `--browser` modes.
+
+### Fixed
+
+- **G12 bot-detection block** — Google's "browser not secure" rejection (`/v3/signin/rejected`)
+  is bypassed by the stealth Chrome launch configuration. Root cause: without
+  `--disable-blink-features=AutomationControlled`, Blink's C++ engine sets
+  `navigator.webdriver = true` as a non-configurable native property before any
+  JS init script can run, making `Object.defineProperty` overrides silently fail.
+- **`add_init_script` timing** — registration now occurs before any page is
+  accessed, ensuring the stealth script fires on every navigation including the
+  first `goto()`.
+- **Privacy Guard** — `RealChromeStrategy` validates that `profile_dir` is inside
+  `GFLOW_CLI_HOME` and raises `SecurityError` if it is not, preventing accidental
+  use of the user's primary system Chrome profile.
+- **`ConfigurationError` on missing Chrome** — clear "Chrome binary not found"
+  message with install guidance when `--browser chrome` is requested but Chrome
+  is not on the system.
+- **Two pyright `TypedDict` errors** in cookie access (`c["name"]` → `c.get("name")`).
+
+### Changed
+
+- `src/gflow_cli/auth.py` promoted to `src/gflow_cli/auth/` package with
+  `__init__.py`, `base.py`, `factory.py`, `internal_chromium.py`,
+  `real_chrome.py`, `strategies.py`.
+- `gflow auth login` now prints the launch strategy announcement before opening
+  any browser window.
+
+
+
+> **Shell-friendly multi-prompt `t2i` + performance hardening.** This release 
+> promotes `gflow image t2i` to a variadic command that can consume multiple 
+> prompts from positional arguments, a line-delimited text file, or standard 
+> input. Core generation logic has been consolidated into a shared 
+> `image_batch` module, ensuring architectural consistency between shell runs 
+> and JSON-described batches. This version also ships critical resource 
+> cleanup fixes for SQLite connections and OOM protection for stdin streams.
+
+### Added
+
+- **Variadic `gflow image t2i`** — now accepts multiple positional prompts. 
+  Example: `gflow image t2i "prompt 1" "prompt 2"`.
+- **`--prompts-file <PATH>` and `--stdin`** — read batches of prompts from 
+  text files or pipes. All prompts in a batch share a single Flow session 
+  and project, significantly reducing reCAPTCHA and project-init overhead.
+- **Shared `image_batch` logic** (`src/gflow_cli/image_batch.py`) — unified 
+  orchestration, validation, and rendering for all multi-prompt generation 
+  surfaces.
+- **Memory safety for stdin** — bounded read on standard input prevents 
+  memory exhaustion when piping large or infinite streams.
+- **`examples/multi_prompt_t2i.py` + `examples/sample_prompts.txt`** — 
+  runnable template for the new shell-multi-prompt surface.
+
+### Fixed
+
+- **Resource leaks in SQLite** — ensured all `sqlite3` connections are 
+  properly closed via `try...finally` blocks, resolving resource exhaust 
+  warnings and potential hangs in long-running processes.
+- **Output directory partitioning** — `t2i` batches now correctly land in 
+  date-partitioned folders (`images/YYYY-MM-DD/`) by default, aligning 
+  with the core design spec.
+
+### Changed
+
+- **CLI validation alignment** — `t2i` and `i2i` subcommands now use 
+  authoritative domain constants for model, aspect, and count validation, 
+  ensuring UI help text and defaults stay in perfect sync with the engine.
+
 ## [0.5.0a1] — 2026-05-12
 
 > **Pluggable image transport + JSON-described batch runs.** The image
@@ -397,9 +492,9 @@ shell-script template that branches on these codes.
 
 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
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.6.0a1...HEAD
+[0.6.0a1]: https://github.com/ffroliva/gflow-cli/compare/v0.5.0a1...v0.6.0a1
+[0.5.0a1]: https://github.com/ffroliva/gflow-cli/compare/v0.4.0a2...v0.5.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.5.0a1 → gflow_cli-0.6.0a2}/CLAUDE.md

@@ -142,3 +142,66 @@ uv run gflow auth login --profile experiments  # named profile
 - [docs/INDEX.md](docs/INDEX.md) — full doc routing
 - [PLAN.md](PLAN.md) — implementation roadmap with phases & ADRs
 - [.claude/README.md](.claude/README.md) — what's in `.claude/` and how to extend it
+
+# context-mode — MANDATORY routing rules
+
+You have context-mode MCP tools available. These rules are NOT optional — they protect your context window from flooding. A single unrouted command can dump 56 KB into context and waste the entire session.
+
+## BLOCKED commands — do NOT attempt these
+
+### curl / wget — BLOCKED
+Any Bash command containing `curl` or `wget` is intercepted and replaced with an error message. Do NOT retry.
+Instead use:
+- `ctx_fetch_and_index(url, source)` to fetch and index web pages
+- `ctx_execute(language: "javascript", code: "const r = await fetch(...)")` to run HTTP calls in sandbox
+
+### Inline HTTP — BLOCKED
+Any Bash command containing `fetch('http`, `requests.get(`, `requests.post(`, `http.get(`, or `http.request(` is intercepted and replaced with an error message. Do NOT retry with Bash.
+Instead use:
+- `ctx_execute(language, code)` to run HTTP calls in sandbox — only stdout enters context
+
+### WebFetch — BLOCKED
+WebFetch calls are denied entirely. The URL is extracted and you are told to use `ctx_fetch_and_index` instead.
+Instead use:
+- `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` to query the indexed content
+
+## REDIRECTED tools — use sandbox equivalents
+
+### Bash (>20 lines output)
+Bash is ONLY for: `git`, `mkdir`, `rm`, `mv`, `cd`, `ls`, `npm install`, `pip install`, and other short-output commands.
+For everything else, use:
+- `ctx_batch_execute(commands, queries)` — run multiple commands + search in ONE call
+- `ctx_execute(language: "shell", code: "...")` — run in sandbox, only stdout enters context
+
+### Read (for analysis)
+If you are reading a file to **Edit** it → Read is correct (Edit needs content in context).
+If you are reading to **analyze, explore, or summarize** → use `ctx_execute_file(path, language, code)` instead. Only your printed summary enters context. The raw file content stays in the sandbox.
+
+### Grep (large results)
+Grep results can flood context. Use `ctx_execute(language: "shell", code: "grep ...")` to run searches in sandbox. Only your printed summary enters context.
+
+## Tool selection hierarchy
+
+1. **GATHER**: `ctx_batch_execute(commands, queries)` — Primary tool. Runs all commands, auto-indexes output, returns search results. ONE call replaces 30+ individual calls.
+2. **FOLLOW-UP**: `ctx_search(queries: ["q1", "q2", ...])` — Query indexed content. Pass ALL questions as array in ONE call.
+3. **PROCESSING**: `ctx_execute(language, code)` | `ctx_execute_file(path, language, code)` — Sandbox execution. Only stdout enters context.
+4. **WEB**: `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` — Fetch, chunk, index, query. Raw HTML never enters context.
+5. **INDEX**: `ctx_index(content, source)` — Store content in FTS5 knowledge base for later search.
+
+## Subagent routing
+
+When spawning subagents (Agent/Task tool), the routing block is automatically injected into their prompt. Bash-type subagents are upgraded to general-purpose so they have access to MCP tools. You do NOT need to manually instruct subagents about context-mode.
+
+## Output constraints
+
+- Keep responses under 500 words.
+- Write artifacts (code, configs, PRDs) to FILES — never return them as inline text. Return only: file path + 1-line description.
+- When indexing content, use descriptive source labels so others can `ctx_search(source: "label")` later.
+
+## ctx commands
+
+| Command | Action |
+|---------|--------|
+| `ctx stats` | Call the `ctx_stats` MCP tool and display the full output verbatim |
+| `ctx doctor` | Call the `ctx_doctor` MCP tool, run the returned shell command, display as checklist |
+| `ctx upgrade` | Call the `ctx_upgrade` MCP tool, run the returned shell command, display as checklist |

{gflow_cli-0.5.0a1 → gflow_cli-0.6.0a2}/KNOWN_ISSUES.md

@@ -133,6 +133,35 @@ _(none yet)_
 
 ## Resolved
 
+### G12 "browser not secure" block — Google rejects automated sign-in
+
+- **Status:** Resolved · **Severity:** Critical (blocked `gflow auth login`) · **Fixed in:** v0.6.0a2
+
+Google's sign-in flow (`accounts.google.com/v3/signin/rejected`) detected Playwright's bundled Chromium as an automated browser and refused the login with no user-facing error.
+
+**Root cause (timing race):** Without `--disable-blink-features=AutomationControlled`,
+Blink's C++ engine sets `navigator.webdriver = true` as a non-configurable, non-writable
+native property at Chrome startup — before any JavaScript (including `add_init_script`)
+can run. The `Object.defineProperty` override silently fails. With the flag, the property
+is never set; the JS override then works as belt-and-suspenders.
+
+**Resolution:** `v0.6.0a2` adds `RealChromeStrategy` — a new auth strategy that launches
+the system's real Google Chrome via Playwright's `channel="chrome"` with stealth flags.
+
+```bash
+# Bypass G12 block explicitly:
+gflow auth login --browser chrome
+
+# Or rely on auto-detection (default behaviour; picks real Chrome if installed):
+gflow auth login
+```
+
+A cosmetic "You are using an unsupported command-line flag" notice may appear briefly in
+the Chrome window — this is harmless and can be dismissed. It is the accepted trade-off
+for bypassing G12.
+
+---
+
 ### v0.1 — provider methods are stubs
 
 - **Status:** Resolved · **Severity:** Critical (blocked usage) · **Fixed in:** v0.2.0a1

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.5.0a1
+Version: 0.6.0a2
 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
@@ -125,6 +125,7 @@ Read the full [DISCLAIMER](DISCLAIMER.md) before deploying this in any productio
 | Pluggable image transport + `ui_automation` default strategy | ✅ done (v0.5.0a1) |
 | `gflow run --config <file>` sequential JSON batches | ✅ done (v0.5.0a1) |
 | `examples/` directory with runnable single-image + batch scripts | ✅ done (v0.5.0a1) |
+| Shell multi-prompt `gflow image t2i` (`PROMPT...`, `--prompts-file`, `--stdin`) | ✅ done (v0.6.0a1) |
 | Provider abstraction for official Veo 3.1 API | ⏳ planned (v0.6+) |
 
 ### What's new in v0.5.0a1
@@ -136,6 +137,24 @@ Read the full [DISCLAIMER](DISCLAIMER.md) before deploying this in any productio
 
 ---
 
+## 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 --out ...` call against a logged-in Pro/Ultra profile. The 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 because the persistent Playwright session is already warm, so this take is intentionally terminal-only.*
+
+**Try it yourself** — this is the exact command the GIF runs:
+
+```bash
+gflow image t2i "a quiet mountain lake at dawn, cinematic photography" --aspect 9:16 --model nano2 --out ./gflow-output/example-single
+```
+
+One prompt, default model (`nano2` = Nano Banana 2), 9:16 portrait, written as `./gflow-output/example-single/<media_name>_0.png`. Wall time is typically 30–90s on a warm profile; the first call after a fresh `gflow auth login` is slower because Playwright spins up Chromium and navigates to the Flow editor. See [`docs/USAGE.md`](docs/USAGE.md) for the full `gflow image t2i` flag reference (`--model`, `--aspect`, `-n`, `--seed`, `--profile`, `--transport`).
+
+To reproduce the recording yourself, see [`scripts/record_demo.ps1`](scripts/record_demo.ps1) (Windows, requires OBS + ffmpeg + gifski).
+
+---
+
 ## Prerequisites
 
 | Requirement | Why |
@@ -243,7 +262,9 @@ gflow auth login                                         # one-time browser sign
 gflow auth status                                        # show current session
 
 gflow image upload <path>                                # upload PNG/JPEG → asset UUID
-gflow image t2i "<prompt>" [--model] [--aspect] [-n]     # text-to-image (1–4 per call)
+gflow image t2i "<prompt>" [...] [--model] [--aspect]    # text-to-image; repeat prompts for a warm batch
+gflow image t2i --prompts-file prompts.txt               # text-file multi-prompt batch
+gflow image t2i --stdin                                  # stdin multi-prompt batch
 gflow image i2i "<prompt>" --ref PATH_OR_UUID [...]      # image-to-image (1–4 per call)
 
 gflow video t2v "<prompt>" -o out.mp4                    # text-to-video (Veo 3.1)

{gflow_cli-0.5.0a1 → gflow_cli-0.6.0a2}/PLAN.md

@@ -2,7 +2,7 @@
 
 > **Status:** Living document. Updated as phases complete.
 > **Owner:** [@ffroliva](https://github.com/ffroliva)
-> **Last revised:** 2026-05-11 (Phase 4 Hardening shipped, v0.4.0a2)
+> **Last revised:** 2026-05-15 (Phase 6 / v0.6.0a2 — Real Chrome auth)
 
 This plan turns the v0.1 scaffold into a production-grade CLI for Google AI Ultra/Pro subscribers who want to spend their Flow credits via batch automation. The plan is opinionated, treating this repo as a portfolio-grade benchmark.
 
@@ -76,7 +76,12 @@ Current package layout (post-Phase 4):
 src/gflow_cli/
 ├── __init__.py
 ├── __main__.py
-├── auth.py             ← login + status (Playwright headed for login)
+├── auth/               ← v0.6.0a2: strategy pattern (real Chrome + internal Chromium)
+│   ├── __init__.py     ← login(), AuthStatus, get_status(), list_profiles()
+│   ├── base.py         ← AuthStrategy Protocol
+│   ├── factory.py      ← AuthStrategyFactory (auto/chrome/internal routing)
+│   ├── internal_chromium.py  ← bundled Chromium (legacy fallback)
+│   └── real_chrome.py  ← system Chrome with G12 stealth flags
 ├── cli.py              ← Click app, top-level + auth subgroup
 ├── cli_image.py        ← gflow image upload/t2i/i2i (Click subgroup)
 ├── cli_video.py        ← gflow video t2v/i2v/batch (Click subgroup)
@@ -323,17 +328,28 @@ Page creation averaged **44.7–48.1 ms per page** across N=2/4/8/16 inside one
 
 ### Phase 5 — Public alpha soak + first non-alpha release
 
-`v0.2.0a1` through `v0.4.0a2` are already on PyPI under Trusted Publishing.
+`v0.2.0a1` through `v0.6.0a1` are already on PyPI under Trusted Publishing.
 Phase 5 is the soak window before dropping the `aN` suffix:
 
-- Let `v0.4.0a2` soak on PyPI for at least 1 week with external installs
-- Verify `uvx --from "gflow-cli==0.4.0a2" gflow --help` works on a fresh machine on all three OSes (Windows / macOS / Linux)
+- Let `v0.6.0a1` soak on PyPI for at least 1 week with external installs
+- Verify `uvx --from "gflow-cli==0.6.0a1" gflow --help` works on a fresh machine on all three OSes (Windows / macOS / Linux)
 - Triage any issues filed by external users (`gh issue list`)
-- Tag the first non-alpha (`v0.4.0`) once the surface is stable enough for external automation
+- Tag the first non-alpha (`v0.6.0`) once the surface is stable enough for external automation
 - Optional follow-up: scaffold `OfficialVeoProvider` against [`googleapis/python-genai`](https://github.com/googleapis/python-genai) behind `GFLOW_CLI_PROVIDER=official`
 
 ---
 
+### Technical Debt & Refactoring — BACKLOG
+
+Identified during v0.6.0a1 Council Review. To be addressed before or during Phase 6.
+
+- **Unify Output Resolution**: `cli_run.py` uses `out/<UTC>` while `cli_image.py` uses `images/<YYYY-MM-DD>`. Align both to the date-partitioned daily strategy or a single shared helper.
+- **Deduplicate JSON Validation**: `cli_run.py` duplicates model/aspect validation logic. Consolidate into `image_batch.py` helpers.
+- **Generic Batch Orchestrator**: Refactor `run_image_batch` to accept a worker callback. This will allow the same sequential/fail-fast orchestration to support `video` batches in the future.
+- **Playwright Thread Safety**: Investigate why `unittest.mock.patch` plus multi-threaded `asyncio` hangs in `tests/test_browser_manager.py`. The test is currently skipped.
+
+---
+
 ### Phase 6 — Operations history & cost tracking — BACKLOG
 
 Foundation laid by Phase 4's structured `error_raised` events + Problem Details. Phase 6 adds a local persistence layer so users can answer "what did I generate last week and what did it cost?".

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

@@ -71,6 +71,7 @@ Read the full [DISCLAIMER](DISCLAIMER.md) before deploying this in any productio
 | Pluggable image transport + `ui_automation` default strategy | ✅ done (v0.5.0a1) |
 | `gflow run --config <file>` sequential JSON batches | ✅ done (v0.5.0a1) |
 | `examples/` directory with runnable single-image + batch scripts | ✅ done (v0.5.0a1) |
+| Shell multi-prompt `gflow image t2i` (`PROMPT...`, `--prompts-file`, `--stdin`) | ✅ done (v0.6.0a1) |
 | Provider abstraction for official Veo 3.1 API | ⏳ planned (v0.6+) |
 
 ### What's new in v0.5.0a1
@@ -82,6 +83,24 @@ Read the full [DISCLAIMER](DISCLAIMER.md) before deploying this in any productio
 
 ---
 
+## 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 --out ...` call against a logged-in Pro/Ultra profile. The 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 because the persistent Playwright session is already warm, so this take is intentionally terminal-only.*
+
+**Try it yourself** — this is the exact command the GIF runs:
+
+```bash
+gflow image t2i "a quiet mountain lake at dawn, cinematic photography" --aspect 9:16 --model nano2 --out ./gflow-output/example-single
+```
+
+One prompt, default model (`nano2` = Nano Banana 2), 9:16 portrait, written as `./gflow-output/example-single/<media_name>_0.png`. Wall time is typically 30–90s on a warm profile; the first call after a fresh `gflow auth login` is slower because Playwright spins up Chromium and navigates to the Flow editor. See [`docs/USAGE.md`](docs/USAGE.md) for the full `gflow image t2i` flag reference (`--model`, `--aspect`, `-n`, `--seed`, `--profile`, `--transport`).
+
+To reproduce the recording yourself, see [`scripts/record_demo.ps1`](scripts/record_demo.ps1) (Windows, requires OBS + ffmpeg + gifski).
+
+---
+
 ## Prerequisites
 
 | Requirement | Why |
@@ -189,7 +208,9 @@ gflow auth login                                         # one-time browser sign
 gflow auth status                                        # show current session
 
 gflow image upload <path>                                # upload PNG/JPEG → asset UUID
-gflow image t2i "<prompt>" [--model] [--aspect] [-n]     # text-to-image (1–4 per call)
+gflow image t2i "<prompt>" [...] [--model] [--aspect]    # text-to-image; repeat prompts for a warm batch
+gflow image t2i --prompts-file prompts.txt               # text-file multi-prompt batch
+gflow image t2i --stdin                                  # stdin multi-prompt batch
 gflow image i2i "<prompt>" --ref PATH_OR_UUID [...]      # image-to-image (1–4 per call)
 
 gflow video t2v "<prompt>" -o out.mp4                    # text-to-video (Veo 3.1)

{gflow_cli-0.5.0a1 → gflow_cli-0.6.0a2}/docs/ARCHITECTURE.md

@@ -57,6 +57,43 @@ The hexagonal target above is the steady state. The **current** package — and
 - Restructure existing modules beyond minimal dedup (shared CLI helpers were promoted to `gflow_cli._cli_helpers` at the package top level — kept flat to avoid a `cli.py` file / `cli/` package collision).
 - Introduce dependency-injection containers, command/query buses, or any DDD/CQRS scaffolding (deferred per [PLAN ADR #2](../PLAN.md#5-decision-log-adrs-in-miniature)).
 
+**v0.6.0a2 module additions — auth strategy package:**
+
+`auth.py` was promoted to a sub-package `gflow_cli.auth/` with the strategy pattern to support multiple browser backends for the `gflow auth login` command:
+
+```text
+src/gflow_cli/auth/
+├── __init__.py          # public: login(), AuthStatus, get_status(), list_profiles()
+├── base.py              # AuthStrategy Protocol — the shared contract
+├── factory.py           # AuthStrategyFactory — routes auto/chrome/internal modes
+├── internal_chromium.py # InternalChromiumStrategy — Playwright bundled Chromium (legacy)
+├── real_chrome.py       # RealChromeStrategy — system Google Chrome with stealth flags
+└── strategies.py        # (internal) shared Playwright helpers
+```
+
+**Why:** Google's bot-detection ("G12 block") rejects Playwright's bundled Chromium during `gflow auth login`. Launching the user's installed Google Chrome with `--disable-blink-features=AutomationControlled` plus a JS `add_init_script` that overrides `navigator.webdriver` bypasses detection. Two strategies are needed because the setup (persistent-context flags, Chrome binary path, stealth init) differs fundamentally between them.
+
+**AuthStrategy Protocol** (`base.py`):
+```python
+class AuthStrategy(Protocol):
+    name: str
+    async def login(self, profile_dir: Path, headless: bool) -> None: ...
+```
+
+**AuthStrategyFactory** (`factory.py`):
+- `mode="auto"` — probes `is_chrome_available()` → `RealChromeStrategy` if found, else `InternalChromiumStrategy` with a warning.
+- `mode="chrome"` — explicit `RealChromeStrategy`; raises `ConfigurationError` if Chrome binary missing.
+- `mode="internal"` — explicit `InternalChromiumStrategy`.
+
+**RealChromeStrategy stealth design** (`real_chrome.py`):
+- Uses a **Passive Capture** pattern: launches system Chrome via `subprocess.Popen` without any automation flags or remote-debugging ports.
+- Provides a 100% clean browser process that Google's G12 block cannot detect.
+- The CLI blocks on `proc.wait()`, prompting the user to complete the sign-in and **close the browser completely**.
+- Post-close: performs a fast, headless `launch_persistent_context` probe to verify the `SAPISID` cookie was successfully captured.
+- Privacy guard: raises `SecurityError` if the resolved `profile_dir` is outside `GFLOW_CLI_HOME` — protects the user's primary system Chrome profile from being used as a session store.
+
+**CLI surface:** `gflow auth login [--browser auto|chrome|internal]` (env: `GFLOW_CLI_AUTH_BROWSER`).
+
 When the project converges on the hexagonal target above, modules graduate to layers: e.g., today's `gflow_cli.api` becomes `gflow_cli.infrastructure.flow_api`, `gflow_cli.cli` becomes `gflow_cli.interfaces.cli`, and so on. The modular-monolith shape is the staging area, not the destination.
 
 ## Folder layout
@@ -64,7 +101,7 @@ When the project converges on the hexagonal target above, modules graduate to la
 > **Note: this document describes the TARGET architecture, not the current
 > package layout.** The current shape (per [PLAN.md § 2](../PLAN.md#2-architecture-steady-state)
 > and [ADR #2](../PLAN.md#5-decision-log-adrs-in-miniature)) is the simpler
-> `src/gflow_cli/{api/, cli.py, cli_image.py, cli_video.py, auth.py,
+> `src/gflow_cli/{api/, auth/, cli.py, cli_image.py, cli_video.py,
 > config.py, paths.py, profile_store.py}`. The DDD layout below was deferred
 > indefinitely; converge toward it incrementally if/when a second `Provider`
 > or a `gflow serve` HTTP front-end justifies the split.

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

@@ -127,14 +127,38 @@ Use `gflow auth login --profile <name>` to add or refresh a profile.
 
 ### `gflow auth login`
 
-Opens a headed Chromium, navigates to `https://labs.google/fx/tools/flow?hl=en`, and waits for you to sign in. The browser window must be closed within **10 minutes total** (the underlying `wait_for_event("close", timeout=600_000)`); after that the command times out. When the window is closed, the captured session is persisted to disk.
+Opens a headed browser, navigates to `https://labs.google/fx/tools/flow?hl=en`, and waits
+for you to sign in. The CLI automatically detects success and persists the session to disk.
 
 ```bash
-gflow auth login                  # default profile
-gflow auth login --profile work   # named profile (creates if missing)
+gflow auth login                   # default profile, auto browser
+gflow auth login --profile work    # named profile (creates if missing)
+gflow auth login --browser chrome  # force real Chrome (bypasses G12 block)
 ```
 
-Re-running this command refreshes an expired session: it reuses the existing profile dir, so you typically just have to click "Continue as <you>" on the Google account chooser.
+Re-running this command refreshes an expired session: it reuses the existing profile dir,
+so you typically just have to click "Continue as <you>" on the Google account chooser.
+
+#### `--browser [auto|chrome|internal]`
+
+| Value | Browser used | When to use |
+|---|---|---|
+| `auto` (default) | Real Chrome if installed; falls back to internal | First choice for most users |
+| `chrome` | System Google Chrome (**Passive Capture**) | Required to bypass "G12" blocks |
+| `internal` | Playwright's bundled Chromium | Fallback when Chrome isn't installed |
+
+Override with the env var: `GFLOW_CLI_AUTH_BROWSER=chrome gflow auth login`
+
+**Why `chrome` bypasses bot detection:** Playwright's default automation mode exposes
+`navigator.webdriver = true` as a non-configurable native property. Google detects this
+and redirects to `/v3/signin/rejected` (the "G12 block"). The `chrome` strategy
+implements **Passive Capture**: it launches your real system Chrome as a 100% standard
+process without any automation flags or debugging ports. You log in manually, close
+the window, and `gflow` extracts the verified session from the profile.
+
+**Privacy guard:** The `chrome` strategy strictly refuses to use any profile directory
+outside `GFLOW_CLI_HOME`. This protects your primary system Chrome profile from
+accidental interference or data corruption.
 
 ### `gflow auth status`
 

{gflow_cli-0.5.0a1 → gflow_cli-0.6.0a2}/docs/USAGE.md

@@ -82,15 +82,24 @@ gflow image i2i "make it cinematic" --ref "$UUID"
 
 ## `gflow image t2i`
 
-Generate 1–4 images from a text prompt using Google Flow's Imagen / Nano Banana models.
+Generate 1–4 images from one text prompt, or run a shell-friendly batch of 1–50
+prompts through one Flow session/project.
 
 ```text
-gflow image t2i PROMPT [OPTIONS]
+gflow image t2i PROMPT [PROMPT ...] [OPTIONS]
+gflow image t2i --prompts-file FILE [OPTIONS]
+gflow image t2i --stdin [OPTIONS]
 
 Arguments:
-  PROMPT                    Text prompt.                           [required]
+  PROMPT                    Text prompt. Repeat for multi-prompt mode.
 
 Options:
+  --prompts-file FILE       UTF-8 text file: one prompt per non-empty line;
+                            whole-line # comments skipped.
+  --stdin                   Read prompts from stdin using the same format.
+  --continue-on-error /
+  --fail-fast               Continue after per-prompt failures or stop at the
+                            first failed prompt. [default: continue-on-error]
   --model [nano2|nano-pro|image4]
                             Image model alias.                [default: nano2]
   --aspect [9:16|16:9|1:1|4:3|3:4]
@@ -109,12 +118,26 @@ Options:
 | `nano-pro` | Nano Banana Pro (`GEM_PIX_2`) | Higher quality, slower. |
 | `image4` | Imagen 4 (`IMAGEN_3_5`) | Photoreal-leaning Imagen variant. |
 
-**Seed-requires-count==1 invariant.** `--seed` is only valid when generating a single image (`-n 1`). For multi-image runs the CLI rejects the combination upfront — multi-image fan-out uses N independent random seeds (one per shot) wired to a shared `batch_id`, which gives you variation. If you need reproducibility across many shots, run `--seed` once per call in a loop.
+**Multi-prompt shortcut.**
+
+- Positional multi-prompt: `gflow image t2i "p1" "p2" "p3"`.
+- `--prompts-file FILE`: UTF-8 text, one prompt per non-empty line, whole-line
+  `#` comments skipped.
+- `--stdin`: same format as `--prompts-file`.
+- Sources are mutually exclusive.
+- Output names use `prompt_<prompt-index>_<variation-index>.png`.
+- With `-n 4`, each prompt produces four images; the maximum shell shortcut
+  fan-out is 50 prompts * 4 = 200 images.
+- `--continue-on-error` is default; `--fail-fast` stops after the first failed
+  prompt.
+
+**Seed-requires-count==1 invariant.** `--seed` is only valid when generating a single image (`-n 1`). For multi-image runs the CLI rejects the combination upfront — multi-image fan-out uses N independent random seeds (one per shot) wired to a shared `batch_id`, which gives you variation. `--seed` is not supported in multi-prompt mode; use separate single-prompt commands for seeded work today.
 
 **Output paths.**
 
 - **Default (`--out` omitted).** Files land under `$GFLOW_CLI_OUTPUT_DIR/images/<YYYY-MM-DD>/<media_name>_<n>.png`. The date partition keeps long-running batches navigable.
 - **`--out DIR` provided.** Files are written **flat** as `<DIR>/<media_name>_<n>.png` — no date subdirectory. `--out` must be a directory; flat-file output paths are not supported (you can rename after the fact).
+- **Multi-prompt mode.** Files are written as `prompt_<prompt-index>_<variation-index>.png`; the prompt index and variation index are zero-based.
 
 **Examples:**
 
@@ -130,6 +153,15 @@ gflow image t2i "variations of a minimalist fox logo" -n 4 --aspect 1:1 --out ./
 
 # Reproducible single shot
 gflow image t2i "reproducible reference shot" --seed 42
+
+# Three prompts in one warm Flow session/project
+gflow image t2i "p1" "p2" "p3" --aspect 16:9 --model image4
+
+# Text file input: comments and blank lines are ignored
+gflow image t2i --prompts-file prompts.txt --fail-fast
+
+# Pipeline input
+Get-Content prompts.txt | gflow image t2i --stdin
 ```
 
 A 4-image run with `--out ./logos/` produces: