gflow-cli 0.35.0__tar.gz → 0.36.0__tar.gz

gflow_cli-0.36.0/.claude/commands/gflow/llm-council.md

@@ -0,0 +1,13 @@
+---
+description: Run pr-council-review (PR or branch mode) plus an external-tools corroboration layer (codex, gemini, opt-in agy) for high-stakes reviews where a same-model-family blind spot is a real risk. Tiers: small (internal only, default) / medium (+codex) / high (+codex+gemini). Wrapper around skills/llm-council/SKILL.md.
+---
+
+# `/gflow:llm-council [PR# | --base <ref>] [--tier small|medium|high] [--include-agy]`
+
+**Read `skills/llm-council/SKILL.md` and follow its protocol now**, treating `$ARGUMENTS` as: the PR number or `--base <ref>` (branch mode, same as `/gflow:pr-council-review` / `/gflow:branch-review`), plus `--tier <small|medium|high>` (default `small`) and the optional `--include-agy` flag.
+
+> Do **not** call `Skill(skill="llm-council")` or `Skill(skill="pr-council-review")` — the repo's `skills/*/SKILL.md` files are plain Markdown, not registered as Skill-tool-invocable (only `.claude/commands/gflow/*` are). Invoking either errors with `Unknown skill: ...`. Read the files directly instead.
+
+`skills/llm-council/SKILL.md` is the canonical body: tier resolution, the tool registry (fixed invocation recipes per external tool — read this before running any external tool, `codex review` in particular is a known trap), the availability-probe step, dispatch flow, and synthesis. It wraps `skills/pr-council-review/SKILL.md` unchanged for the internal dimension council.
+
+Siblings: `/gflow:pr-council-review <N>` (internal-only, PR mode), `/gflow:branch-review` (internal-only, branch mode) — use either directly when external corroboration isn't warranted.

{gflow_cli-0.35.0 → gflow_cli-0.36.0}/.env.template

@@ -155,6 +155,20 @@
 # derivation (tab title / page hints) fails.
 # GFLOW_CLI_PROJECT_NAME=
 
+# -----------------------------------------------------------------------------
+# Debugging (opt-in only — both can expose secrets, see docs/CONFIGURATION.md)
+# -----------------------------------------------------------------------------
+
+# Captures full Playwright network traffic (requests, responses, headers,
+# cookies) to this HAR file for the session. SECURITY: a HAR file contains
+# live auth cookies and bearer tokens -- never share one publicly.
+# GFLOW_CLI_HAR_PATH=
+
+# Prints the real exception message + traceback for unhandled errors, to the
+# console and (under --json) into the payload, instead of the generic
+# placeholder. SECURITY: may leak tokens/cookies present in exception text.
+# GFLOW_CLI_DEBUG_TRACEBACK=
+
 # -----------------------------------------------------------------------------
 # Headless Daemon (gflow serve)
 # -----------------------------------------------------------------------------

{gflow_cli-0.35.0 → gflow_cli-0.36.0}/AGENTS.md

@@ -91,6 +91,7 @@ The `skills/` directory ships installable agent skill docs in plain Markdown wit
 | `plan` | [`skills/plan/SKILL.md`](skills/plan/SKILL.md) | Create a structured task-by-task implementation plan for a feature |
 | `status` | [`skills/status/SKILL.md`](skills/status/SKILL.md) | Show current plan state, progress, and next unchecked task |
 | `pr-council-review` | [`skills/pr-council-review/SKILL.md`](skills/pr-council-review/SKILL.md) | Multi-dimensional PR council review |
+| `llm-council` | [`skills/llm-council/SKILL.md`](skills/llm-council/SKILL.md) | Wraps `pr-council-review` with external CLI reviewers (`codex`/`gemini`, opt-in `agy`) for high-stakes reviews |
 | `issue-assessment` | [`skills/issue-assessment/SKILL.md`](skills/issue-assessment/SKILL.md) | Triage a GitHub issue (read-only) before any fix work |
 | `issue-resolve` | [`skills/issue-resolve/SKILL.md`](skills/issue-resolve/SKILL.md) | Drive an assessed issue to a test-first fix + draft PR |
 | `check` | [`skills/check/SKILL.md`](skills/check/SKILL.md) | Quality gates (lint/format/types/tests) before every commit |

{gflow_cli-0.35.0 → gflow_cli-0.36.0}/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.36.0] — 2026-07-16
+
+### Added
+
+- **`GFLOW_CLI_HAR_PATH`:** captures full Playwright network traffic (requests, responses, headers, cookies) to a HAR file for the session — useful for diagnosing wire-format surprises or WAF rejections. Opt-in, env-var only; the file is hardened to `0600` on POSIX after Playwright writes it (#316).
+- **`GFLOW_CLI_DEBUG_TRACEBACK`:** prints the real exception message + traceback for unhandled errors — to the console and, under `--json`, into the payload's `error.detail`/`error.traceback` fields — instead of the generic placeholder. The structured telemetry event stays SHA-256-hashed unconditionally either way; this only changes what the operator/caller sees (#316).
+- **`llm-council` skill:** `/gflow:llm-council` composes with `pr-council-review`, adding `codex`/`gemini` (opt-in `agy`) as independent external reviewers alongside the internal Claude-subagent council for high-stakes reviews (#320).
+
+### Fixed
+
+- **Reference entity smuggling:** a poisoned character entity (from a `gflow character create` that failed mid-workflow, e.g. the body-triptych step) could leak its `referenceEntities` into unrelated `gflow image i2i` calls in the same project workspace, even when the caller never passed `--reference-entity`. The UI-automation interceptor now strips unrequested `referenceEntities` before submit (#312).
+
 ## [0.35.0] — 2026-07-14
 
 ### Added
@@ -1980,7 +1992,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.34.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.36.0...HEAD
+[0.36.0]: https://github.com/ffroliva/gflow-cli/compare/v0.35.0...v0.36.0
+[0.35.0]: https://github.com/ffroliva/gflow-cli/compare/v0.34.0...v0.35.0
 [0.34.0]: https://github.com/ffroliva/gflow-cli/compare/v0.33.0...v0.34.0
 [0.33.0]: https://github.com/ffroliva/gflow-cli/compare/v0.32.1...v0.33.0
 [0.32.1]: https://github.com/ffroliva/gflow-cli/compare/v0.32.0...v0.32.1

{gflow_cli-0.35.0 → gflow_cli-0.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.35.0
+Version: 0.36.0
 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

gflow_cli-0.36.0/docs/CONFIGURATION.md

@@ -0,0 +1,429 @@
+# Configuration
+
+`gflow-cli` is configured via three layers, with a strict precedence order:
+
+```text
+CLI flag (highest)  >  environment variable  >  .env file  >  built-in default (lowest)
+```
+
+Every setting validates at startup via [`pydantic-settings`](https://docs.pydantic.dev/latest/concepts/pydantic_settings/). Bad values fail loudly with the offending key + the rule it violated, never silently.
+
+## Reference
+
+Each variable in `.env.template` documented here:
+
+### `GFLOW_CLI_HOME`
+
+**What:** Root directory for Playwright persistent contexts (signed-in Google sessions).
+**Default:** Per-OS user-data-dir via [`platformdirs`](https://github.com/platformdirs/platformdirs):
+- Windows: `%LOCALAPPDATA%\gflow-cli` (e.g. `C:\Users\<you>\AppData\Local\gflow-cli`)
+- macOS: `~/Library/Application Support/gflow-cli`
+- Linux (XDG): `$XDG_DATA_HOME/gflow-cli` (typically `~/.local/share/gflow-cli`)
+
+**Override examples:**
+```bash
+export GFLOW_CLI_HOME=/secure-volume/gflow-cli                       # POSIX
+$env:GFLOW_CLI_HOME = "D:\gflow-cli"                                # PowerShell
+```
+
+See [AUTHENTICATION § Session storage](AUTHENTICATION.md#session-storage) for the full layout.
+`$GFLOW_CLI_HOME` also holds `config.toml`, the SQLite catalog (`gflow.db`), and — if you
+create it — a `tools/` directory of user-authored "My Tools" TOMLs
+(`<GFLOW_CLI_HOME>/tools/*.toml`, auto-loaded; see [TOOLS.md § My Tools](TOOLS.md)).
+
+### `GFLOW_CLI_PROFILE`
+
+**What:** Default profile name used when `--profile` isn't passed on the CLI.
+**Default:** Resolved from `$GFLOW_CLI_HOME/config.toml` → auto-pick if exactly one profile → otherwise prompts the user to choose.
+**CLI override:** `--profile <name>`
+
+A profile maps to a directory `$GFLOW_CLI_HOME/profile_<name>/`. Profiles are isolated — different Google accounts, different cookies, different Flow project histories. See [AUTHENTICATION § Multiple accounts](AUTHENTICATION.md#multiple-accounts).
+
+#### Default-profile resolution chain
+
+1. CLI flag `--profile <name>` (highest)
+2. Env var `GFLOW_CLI_PROFILE`
+3. `$GFLOW_CLI_HOME/config.toml` → `default_profile = "..."` (set by `gflow auth use <name>`)
+4. Auto: if exactly one `profile_*` dir exists, it's the de-facto default
+5. Fail with the list of available profiles (lowest)
+
+### `GFLOW_CLI_OUTPUT_DIR`
+
+**What:** Root directory where downloaded assets land. Subfolders are created per kind/date.
+**Default:** Per-OS Downloads dir + `/gflow-cli`:
+- Windows: `%USERPROFILE%\Downloads\gflow-cli`
+- macOS: `~/Downloads/gflow-cli`
+- Linux (XDG): `$XDG_DOWNLOAD_DIR/gflow-cli` (falls back to `~/Downloads/gflow-cli`)
+
+**CLI override:** command-specific output flags such as `--out` for image
+commands and `--out-dir` for video commands.
+
+If [`GFLOW_CLI_STORAGE_URI`](#gflow_cli_storage_uri) is set, generated asset
+bytes are uploaded to the configured cloud bucket instead of this local output
+root. `GFLOW_CLI_OUTPUT_DIR` still matters for local mode and for deriving the
+default image/video key layout. See [EXTERNAL_STORAGE.md](EXTERNAL_STORAGE.md).
+
+### `GFLOW_CLI_STORAGE_URI`
+
+**What:** Optional cloud storage URI prefix for generated assets.
+**Values:** `gs://bucket/prefix/` for Google Cloud Storage or
+`s3://bucket/prefix/` for S3-compatible storage, including MinIO.
+**Default:** unset, which means local filesystem output.
+**Requires:** install the matching optional extra:
+
+```bash
+uv tool install "gflow-cli[gcs]"
+uv tool install "gflow-cli[s3]"
+```
+
+When set, `gflow-cli` uploads generated assets to the cloud prefix instead of
+saving local asset copies. It does not dual-write local + cloud copies. The
+local SQLite catalog still records the operation and stores `storage_provider`
+plus `cloud_uri` for each uploaded asset.
+
+Examples:
+
+```bash
+# Choose one:
+export GFLOW_CLI_STORAGE_URI=gs://my-gcs-bucket/gflow/
+export GFLOW_CLI_STORAGE_URI=s3://my-s3-bucket/gflow/
+export GFLOW_CLI_STORAGE_URI=s3://gflow-test/dev/   # MinIO local dev
+```
+
+S3 and MinIO use the standard AWS SDK environment variables:
+
+```bash
+export AWS_ACCESS_KEY_ID=minioadmin
+export AWS_SECRET_ACCESS_KEY=minioadmin
+export AWS_ENDPOINT_URL=http://localhost:9000   # omit for real AWS
+export AWS_DEFAULT_REGION=us-east-1
+```
+
+GCS uses Application Default Credentials, a service-account file through
+`GOOGLE_APPLICATION_CREDENTIALS`, or `STORAGE_EMULATOR_HOST` for local emulator
+runs.
+
+Deep setup, verification, and security notes live in
+[EXTERNAL_STORAGE.md](EXTERNAL_STORAGE.md).
+
+### `GFLOW_CLI_PROVIDER`
+
+**What:** Backend to use for generations.
+**Values:** `flow` (default — reverse-engineered, requires Ultra/Pro) | `official` (planned v0.5+ — Phase 5 official Veo SDK swap, will require a Gemini API key).
+**Default:** `flow`
+**CLI override:** none yet — set the env var to switch backends once `official` is wired.
+
+### `GFLOW_CLI_GEMINI_API_KEY`
+
+**What:** Public Gemini API key. Used by the **`creative-director`** prompt tool
+(`--tool creative-director` / `gflow tools run creative-director`, see
+[TOOLS.md](TOOLS.md) and [PROMPT_EXPANSION.md](PROMPT_EXPANSION.md)) and, in future, by the
+official Veo 3.1 SDK.
+**Required when:** you apply the `creative-director` tool (via `--tool` on any generation
+command, or `gflow tools run`), or `GFLOW_CLI_PROVIDER=official`.
+**Default:** unset
+**Behavior when unset:** the tool is a no-op — gflow logs an `INFO` notice and generates
+from your original prompt (it never fails the run). API errors (rate limit, network) fall
+back the same way after a short exponential-backoff retry, bounded by an overall ~60s
+wall-clock budget per call.
+**Get one:** <https://aistudio.google.com/apikey>
+
+### `GFLOW_CLI_GEMINI_MODEL`
+
+**What:** Gemini model used by the `creative-director` prompt tool.
+**Default:** `gemini-2.5-flash`
+**Note:** Override to select a newer Flash revision without upgrading gflow-cli, e.g.
+`GFLOW_CLI_GEMINI_MODEL=gemini-2.5-flash-lite`.
+
+### `GFLOW_CLI_AUTH_LOGIN_TIMEOUT`
+
+**What:** Maximum time (seconds) that `gflow auth login` waits for the user to complete the Google sign-in flow in the browser.
+**Default:** `600` (10 minutes)
+**Range:** 1–86400
+**Exit code on expiry:** 12 (`AuthLoginTimeoutError`)
+**Note:** Useful for CI/CD or agent pipelines where a hung login should surface as a definite failure rather than blocking indefinitely. Set to a large value (e.g. `3600`) for interactive sessions over slow connections.
+
+```bash
+GFLOW_CLI_AUTH_LOGIN_TIMEOUT=120 gflow auth login   # abort after 2 minutes
+```
+
+### `GFLOW_CLI_TIMEOUT_SECONDS`
+
+**What:** Per-request HTTP timeout. Veo videos can take 60–180 s each.
+**Default:** `600`
+**Note:** This is a single-request ceiling; the *batch* timeout you experience is sum of all per-clip waits.
+
+### `GFLOW_CLI_JITTER_RANGE`
+
+**What:** Anti-bot pause between prompt submissions in multi-prompt image runs (`gflow image batch`, `gflow image t2i --prompts-file` / `--stdin` / multiple positional prompts, and `gflow run` image batches). Spaces out the *submission clicks* only — generations still run in parallel inside Flow.
+**Values:** `MIN-MAX` seconds (e.g. `10-30`), a single number `N` (uniform `0`–`N`, mirrors `video chain --jitter`), or `0` to disable.
+**Default:** `0.5-1.5` — deliberately small so runs don't waste wall-clock. **Widen (e.g. `10-30`) when runs start hitting WAF 403s**, then dial back once the score decays.
+**CLI override:** `--jitter` on `image t2i` and `image batch` (flag beats env).
+**Why:** Flow's WAF reacts to cumulative submission cadence — see [DEBUGGING § WAF cadence](DEBUGGING.md#waf-cadence).
+
+### `GFLOW_CLI_LOG_LEVEL`
+
+**What:** Logging verbosity.
+**Values:** `DEBUG` | `INFO` | `WARNING` | `ERROR`
+**Default:** `INFO`
+**CLI override:** `-v` / `--verbose` flag flips to `DEBUG`.
+
+### `GFLOW_CLI_LOG_FORMAT`
+
+**What:** Output format for log lines.
+**Values:**
+- `auto` (default) — text on TTY, JSON when stdout is piped/redirected
+- `text` — always pretty (Rich-styled, colours)
+- `json` — always machine-readable (one JSON object per line)
+
+### `GFLOW_CLI_CONCURRENCY`
+
+**What:** Per-worker Playwright Page-pool size for batch runs. `FlowApiClient.__aenter__` opens N Pages inside one shared persistent BrowserContext; operations check out a Page via an `asyncio.Queue` (FIFO, bounded by `maxsize=N`). `gflow video batch` fans out manifest entries via `asyncio.gather`.
+**Values:** `1`–`16`
+**Default:** `1` (no fan-out)
+**Recommended starting point:** `4`. Each Page costs ~30–60 MiB of memory on Chromium headless; don't exceed `8` without measuring resident-set size. Cookies and storage state are shared at Context level, so every Page inherits the signed-in profile for free.
+**Shipped in:** v0.4.0a2.
+
+### `GFLOW_CLI_DB_PATH`
+
+**What:** Override the path to the local SQLite operations database.
+**Default:** `<GFLOW_CLI_HOME>/gflow.db`
+**Override examples:**
+```bash
+export GFLOW_CLI_DB_PATH=/secure-volume/gflow.db       # POSIX
+$env:GFLOW_CLI_DB_PATH = "D:\gflow-data\gflow.db"     # PowerShell
+```
+
+Use this when you want the DB on a different volume, outside `GFLOW_CLI_HOME`, or when running multiple isolated environments that share the same home dir.
+
+### `GFLOW_CLI_HISTORY_PROMPTS`
+
+**What:** Controls how prompt text is persisted in the local database.
+**Values:**
+- `store` (default) — the full prompt text is saved to the database alongside the operation record.
+- `redacted` — only the SHA-256 hash of the prompt is stored; the prompt text itself is never written to disk. Use this when prompts may contain sensitive content.
+
+**Default:** `store`
+
+**Tool provenance:** when a prompt tool (e.g. `creative-director`) rewrites a prompt, `store`
+mode also records the submitted `expanded_prompt` and a full `metadata_json.tool` descriptor;
+`redacted` withholds the expanded prompt and reduces the descriptor to
+`{name, version, params_hash, config_hash}`. See [PROMPT_EXPANSION.md](PROMPT_EXPANSION.md).
+
+```bash
+GFLOW_CLI_HISTORY_PROMPTS=redacted gflow image t2i "confidential brief"
+```
+
+### `GFLOW_CLI_HEADLESS`
+
+**What:** Run Playwright in headless mode for non-`auth login` commands.
+**Values:** `true` | `false`
+**Default:** `true`
+**When to flip to `false`:** if reCAPTCHA Enterprise refuses to mint tokens (Google's bot-detection sometimes refuses headless Chromium but accepts a visible window). Set to `false` and re-run; the browser will appear during generation but the session is still reused from the persistent profile.
+
+### `GFLOW_CLI_BROWSER_ENGINE`
+
+**What:** Selects the browser-automation engine backing the Playwright API.
+**Values:** `playwright` | `patchright`
+**Default:** `playwright`
+**What `patchright` is:** an opt-in, drop-in patched Playwright (Chromium) that runs page evaluations in an isolated execution context to avoid the `Runtime.enable` CDP leak, for stronger reCAPTCHA-Enterprise evasion on the **headed** path. It is **not** a headless unlock — Google still detects headless Chromium regardless of engine.
+**Install:** `pip install 'gflow-cli[patchright]'` (or `pip install patchright`). Selecting `patchright` without it installed fails fast with exit code 24 and a pip remediation hint. When using system Chrome (the gflow default, `channel=chrome`) you do **not** need `patchright install chromium`.
+**Reverting:** unset the variable (or set `playwright`) — the default path is byte-identical to a build without this feature, with no profile migration.
+**Security note:** the `patchright` extra ships a *patched Chromium driver* that handles your live Google session cookies; it is exact-pinned and treated as a security-review-required dependency. See [SECURITY.md § Dependencies](SECURITY.md).
+
+### `GFLOW_CLI_UI_MODE`
+
+**What:** Which Flow UI arm to use for generation. Flow serves a **classic** composer (hard crop/aspect controls) or an **agentic** chat cohort, server-assigned and flapping per page load ([#299](https://github.com/ffroliva/gflow-cli/issues/299)).
+**Values:**
+- `auto` (default) — bind whatever the composer renders.
+- `classic` — require the classic composer (hard aspect controls). gflow switches to it, re-probes to verify, and if the arm is still agentic **aborts before submitting** with `UiModeUnavailableError` (**exit 28**) — no credits spent.
+- `agentic` — require the agentic chat surface (needed for `-i` agent instructions). gflow switches to it, verifies, and aborts (exit 28) if it can't be reached.
+**Default:** `auto`
+**How it works:** before each generation, gflow determines the required arm, clicks the classic↔agentic toggle as a **prerequisite**, **verifies** with a DOM re-probe, then binds — or fails fast. The required arm is also **inferred**: `-i` instructions are agentic-only, so they force `agentic` automatically (and `--ui-mode classic` + `-i` is a hard conflict, not a silent drop).
+**Why `classic`:** the agentic cohort treats aspect ratio as a soft prompt hint (portrait 9:16 can come back landscape). `classic` enforces it or fails fast instead of silently degrading.
+**Retry note:** the cohort flaps per load, so an exit-28 abort is **retryable** — a re-run often lands the wanted arm. A server experiment can pin the arm, in which case it's unreachable from the client (the abort still saves the credits).
+**Supersedes:** `GFLOW_CLI_PREFER_CLASSIC` and `GFLOW_CLI_FORCE_AGENT_UI` (below).
+
+### `GFLOW_CLI_PREFER_CLASSIC` *(deprecated — use `GFLOW_CLI_UI_MODE=classic`)*
+
+**Deprecated** in favor of [`GFLOW_CLI_UI_MODE`](#gflow_cli_ui_mode). `true` now maps to `ui_mode=classic` (emits a `DeprecationWarning`). **Behavior change:** the old silent fallback to agentic when the toggle was unavailable is gone — a classic-required run now **aborts with exit 28** instead of producing an agentic-cohort result. `GFLOW_CLI_UI_MODE` (and `--ui-mode`) take precedence when both are set.
+
+### `GFLOW_CLI_FORCE_AGENT_UI` *(deprecated — use `GFLOW_CLI_UI_MODE=agentic`)*
+
+**Deprecated** in favor of [`GFLOW_CLI_UI_MODE`](#gflow_cli_ui_mode). `true` maps to `ui_mode=agentic` (emits a `DeprecationWarning`). `-i` instructions already force agentic automatically, so this is rarely needed explicitly.
+
+### `GFLOW_CLI_LOCALE`
+
+**What:** BCP-47 locale tag passed to Playwright's `launch_persistent_context(locale=...)` — controls the `Accept-Language` HTTP header only.
+**Values:** any BCP-47 tag (e.g. `en-US`, `pt-BR`, `es-ES`, `ja-JP`)
+**Default:** `en-US`
+**Shipped in:** post-v0.8.1 develop (PR #51).
+**When to set it:** capturing locale-invariant DOM via `scripts/dev/capture_locale_invariants.py`, or live-verifying a generation under a non-EN account language.
+**Important:** Chrome's *UI* language is independently forced to `en-US` via the `--lang=en-US` launch arg (so Flow keeps serving `/fx/tools/flow/` and the editor's localized text selectors keep working). This env var only affects request headers — not the editor UI you see. See [KNOWN_ISSUES § issue #24](../KNOWN_ISSUES.md) for the path to dropping `--lang=en-US`.
+
+### `GFLOW_CLI_HAR_PATH`
+
+**What:** Captures full Playwright network traffic (requests, responses, headers, cookies) to a HAR file for the session — useful for diagnosing wire-format surprises or WAF rejections.
+**Default:** unset (no capture).
+**Override examples:**
+```bash
+export GFLOW_CLI_HAR_PATH=/tmp/gflow-debug/session.har       # POSIX
+$env:GFLOW_CLI_HAR_PATH = "C:\gflow-debug\session.har"      # PowerShell
+```
+
+**SECURITY:** a HAR file contains live auth cookies and bearer tokens — never share one publicly. The file is chmod'd `0o600` on POSIX after Playwright writes it (best-effort; no-op on Windows). Two concurrent `gflow` processes pointed at the same path will overwrite each other's HAR (last-writer-wins, no error) — use a distinct path per run if running more than one profile/command at once.
+
+### `GFLOW_CLI_DEBUG_TRACEBACK`
+
+**What:** Prints the real exception message + full traceback for unhandled (non-typed) errors — to the console, and under `--json`, into the payload's `error.detail` / `error.traceback` fields — instead of the default generic "Unexpected error" placeholder. This CLI's structured telemetry event is always SHA-256-hashed regardless of this setting; this flag only changes what you see, not what's logged.
+**Values:** `true` | `false`
+**Default:** `false`
+**Override examples:**
+```bash
+GFLOW_CLI_DEBUG_TRACEBACK=1 gflow image t2i "a cat" --profile dev   # POSIX
+$env:GFLOW_CLI_DEBUG_TRACEBACK = "1"                                # PowerShell
+```
+
+**SECURITY:** the real error text may contain tokens/cookies present in exception state — for local debugging only. `--json` output under this flag is a materially higher-risk surface than the interactive console: a human watches the console live and can react to the yellow warning, but `--json` output is designed to be piped into CI logs, log aggregators, and webhooks that persist or forward it unreviewed. **Never pipe `--json` output under this flag to a shared or persistent system without redacting it first.**
+
+## Output paths
+
+The default output scheme keeps generated assets sortable, dated, and grouped by job:
+
+```text
+$GFLOW_CLI_OUTPUT_DIR/
+├── images/<YYYY-MM-DD>/<media_name>_<index>.png
+└── videos/<YYYY-MM-DD>/<media_name>.mp4
+```
+
+`<media_name>` is the per-asset UUID Flow assigns; `<index>` is the 1-based shot number for multi-image runs (`-n 2..4`).
+
+With `GFLOW_CLI_STORAGE_URI` set, the same default layout is used under the
+configured bucket prefix, and `gflow data media <media_id>` reports `cloud_uri_N`
+rows instead of local paths.
+
+### Per-call override
+
+```bash
+# Image: --out is a directory; files written flat (no date subdir)
+gflow image t2i "..." --out ./shots/
+
+# Video: --out-dir is a directory for the generated mp4
+gflow video t2v "..." --out-dir ./out/
+
+# Video batch: --out-dir overrides the videos/<date>/ root
+gflow video batch ./manifest.tsv --out-dir ./batch-out/
+
+# Video chain: --out-dir holds the per-link mp4s + seed frames
+gflow video chain ./story.jsonl --out-dir ./chain-out/ --yes
+```
+
+For images, `--out DIR` writes flat as `<DIR>/<media_name>_<n>.png` — file paths are not accepted (rename after the fact if needed). For videos, `--out-dir DIR` controls the local output directory.
+
+## `gflow video chain` flags
+
+`gflow video chain` (last-frame I2V chaining — see
+[USAGE § gflow video chain](USAGE.md#gflow-video-chain)) is configured entirely
+by command-line flags; it adds **no new environment variables**. It reuses
+`GFLOW_CLI_OUTPUT_DIR` (default output root), `GFLOW_CLI_PROFILE`,
+`GFLOW_CLI_DB_PATH` (chain links are recorded for `--resume-from`), and
+`GFLOW_CLI_TIMEOUT_SECONDS` (per-link generation ceiling — the chain waits for
+each link in turn, so total wallclock is the sum of all link waits).
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--model` | `veo-lite` | `veo-lite` / `veo-fast` / `veo-quality` / `veo-lite-lp`. `omni-flash` is rejected — it can't seed i2v links (issue #125). |
+| `--max-links N` | unset | Cap link count; exit 11 (`ConfigurationError`) if the manifest has more. A spend guardrail. |
+| `-y` / `--yes` | off | Skip the per-credit cost confirmation prompt. |
+| `--dry-run` | off | Print the plan + credit estimate and spend nothing. |
+| `--resume-from CHAIN_ID` | unset | Resume a prior chain by its id; already-paid links are skipped (not re-billed). |
+| `--jitter F` | `0.0` | Random `0..F` second pause **between** links (anti-bot cadence; never before link 0). |
+| `--seed-offset MS` | `0` | Extract the seed frame this many ms before EOF (fade-to-black guard). |
+| `--aspect` | `9:16` | `9:16` / `16:9`. Applied uniformly to every link (continuity requirement). |
+| `--out-dir DIR` | output root | Directory for the link mp4s + `linkN_lastframe.jpg` seed frames. |
+| `--profile NAME` | default profile | Per-subcommand profile override. |
+| `--json` | off | Emit a machine-readable JSON result. |
+
+The last-frame extractor needs the **`chain` optional extra** (PyAV — no system
+ffmpeg required):
+
+```bash
+pip install 'gflow-cli[chain]'
+# or:  uv tool install 'gflow-cli[chain]'
+```
+
+Per-call local output flags are not intended as bucket-prefix controls. For
+predictable external storage keys, set the bucket prefix in
+`GFLOW_CLI_STORAGE_URI` and leave per-command output flags unset.
+
+## .env loading
+
+`gflow-cli` (via [`pydantic-settings`](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)) loads **two** `.env` files at startup: `$GFLOW_CLI_HOME/.env` (machine-wide defaults — useful for processes whose working directory is arbitrary, like the MCP server or a worker service) and a `.env` in the **current working directory** (project-local overrides). On conflicting keys the CWD file wins.
+
+The home used for the first file is resolved from the `GFLOW_CLI_HOME` env var, else a `GFLOW_CLI_HOME` entry in the CWD `.env`, else the platform default — the same home `Settings.home` reports. (By construction the home `.env` cannot relocate home itself; set the env var or the CWD `.env` instead.)
+
+Variables already set in the actual environment always beat both `.env` files. Anything explicitly passed on the CLI beats everything else.
+
+Use [`.env.template`](../.env.template) as your starting point:
+
+```bash
+cp .env.template .env
+$EDITOR .env
+```
+
+## Worked examples
+
+### "I want all output on a different drive"
+
+```bash
+# .env in CWD or $GFLOW_CLI_HOME
+GFLOW_CLI_OUTPUT_DIR=/mnt/big-disk/flow-output
+```
+
+### "I want generated assets in S3 or GCS"
+
+```bash
+GFLOW_CLI_STORAGE_URI=s3://my-bucket/gflow/ \
+AWS_ACCESS_KEY_ID=... \
+AWS_SECRET_ACCESS_KEY=... \
+AWS_DEFAULT_REGION=us-east-1 \
+gflow image t2i "product photo on a white sweep"
+```
+
+See [EXTERNAL_STORAGE.md](EXTERNAL_STORAGE.md) for MinIO and GCS examples.
+
+### "I'm running in CI — I want JSON logs and a strict timeout"
+
+```bash
+GFLOW_CLI_LOG_FORMAT=json \
+GFLOW_CLI_TIMEOUT_SECONDS=300 \
+gflow video batch ./manifest.tsv
+```
+
+### "I want to test against the official Veo SDK"
+
+```bash
+GFLOW_CLI_PROVIDER=official \
+GFLOW_CLI_GEMINI_API_KEY=AIza... \
+gflow video t2v "test"
+```
+
+(planned v0.5+ — current scaffold accepts but ignores `GFLOW_CLI_PROVIDER=official`.)
+
+### "I want a sandbox profile that doesn't pollute my main one"
+
+```bash
+gflow auth login --profile experiments
+gflow image t2i "test idea" --profile experiments
+# sandbox dir lives at $GFLOW_CLI_HOME/profile_experiments/
+```
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `ValidationError: GFLOW_CLI_TIMEOUT_SECONDS must be a positive integer` | Bad `.env` value | Set to a number ≥ 1 |
+| `FileNotFoundError: $GFLOW_CLI_HOME/profile_default not found` | First run, no auth yet | `gflow auth login` |
+| `AuthExpiredError` | Cookies expired or revoked | `gflow auth login --profile <name>` |
+| Output files don't appear where I expect | Flag > env > .env > default — check actual resolved path | `gflow image t2i ... --verbose` shows the resolved output path |
+| Two concurrent calls fail with "Chromium profile locked" | Same profile used twice | Use `--profile other` for the second call |

{gflow_cli-0.35.0 → gflow_cli-0.36.0}/docs/INDEX.md

@@ -66,6 +66,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 | `/gflow:scenario <feature>` | 12-dimension edge-case explorer → severity-ranked scenario table + BDD skeleton | After predict GO/CAUTION; before `/gflow:plan` |
 | `/gflow:pr-council-review [PR#]` | Multi-dimensional council review of an open PR (5 baseline + adaptive dimensions) | Before merging any non-trivial PR; mandatory for auth/transport/data changes |
 | `/gflow:branch-review` | Same council review run against the current local feature branch (no PR needed) | Pre-PR self-audit; after predict/scenario on a high-stakes branch |
+| `/gflow:llm-council [PR#\|--base <ref>] [--tier small\|medium\|high]` | Wraps `pr-council-review` with external CLI reviewers (`codex`/`gemini`, opt-in `agy`) for cross-model corroboration | High-stakes reviews where a same-model-family blind spot is a real risk |
 | `/gflow:doc-review` | Systematic council-driven audit of documentation completeness and drift | Before cutting a release; after major documentation changes |
 
 **Governance:** commands are executable docs — they decay like any doc. When a phase advances or a file path changes, update the relevant command in the same commit. `/gflow:release` includes a staleness review step.
@@ -122,7 +123,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A gflow command hangs / fails — where do I start?"** → [DEBUGGING § Quick reference](DEBUGGING.md#quick-reference)
 **"Flow's UI broke a selector — how do I diagnose it?"** → [DEBUGGING § Inspecting Flow's live UI](DEBUGGING.md#inspecting-flows-live-ui)
 **"What does each `ui_automation.*` log event mean?"** → [DEBUGGING § Listener & HTTP-layer debugging](DEBUGGING.md#listener--http-layer-debugging)
-**What was actually live-verified for the latest release?** → latest: [LIVE_VERIFICATION_v0.35.0](LIVE_VERIFICATION_v0.35.0.md) (**#305-follow-up multimodal reverse-engineering & storyboard tool proven live e2e** — `gflow tools run storyboard` successfully deconstructed a cyberpunk scene into a cohesive 4-panel sequence; `reverse-engineer` tool extracts frames from video streams/URLs using `claude-video`'s `watch.py` and produces structured prompt components using Gemini multimodal models; dynamic token budgeting and strict Pyright types verified via test suite). Prior: [v0.34.0](LIVE_VERIFICATION_v0.34.0.md) (**#299 `--ui-mode` gate proven live, ZERO credits** — drove `get_ui_driver` directly over 4 real editor loads, never generated: bidirectional switch works [classic→agentic via `_force_agent_mode`, agentic→classic via `_exit_agent_mode`, each DOM-reverified], `agentic`-when-already-agentic is idempotent, and a timed-out toggle → **exit-28 fail-fast before submission**; deprecation behavior-change [`prefer_classic`→exit 28] confirmed). Prior: [v0.33.0](LIVE_VERIFICATION_v0.33.0.md) (**#287-follow-up picker fix proven live on the original repro** — the v0.32.1-failing `i2v <uuid> --project <crowded>` command now exits 0 with a real 3.0 MB `ftyp` mp4, `frame_ref_attached` + `video_saved`, zero uploads; **#241 jitter live-verified on both paths** — flag `--jitter 4-6` → `batch_jitter_sleep seconds=4.98`, and the new 0.5–1.5 s default → `seconds=1.47`, each firing exactly once between two t2i submissions; environment note: the denon82 cohort is now natively agentic and round-2 generations hit the pre-existing #281 `MediaAttributionError`, not a regression). Prior: [v0.32.1](LIVE_VERIFICATION_v0.32.1.md) (**#293 teardown fix live-verified credit-free** — error-path aborts leave ZERO chrome.exe holding the profile [3× leak reproduced pre-fix same day]; force-close fallback + ProfileLockedError translation unit-pinned; #283 wave logic fixes mock-verified to exact call counts). Prior: [v0.32.0](LIVE_VERIFICATION_v0.32.0.md) (**#287 UUID i2v frames proven live e2e** — an in-project asset selected by media UUID in the frame-slot dialog [frame_ref_attached, startImage bound on the wire, ZERO upload events] produced a real 720×1280 interpolation, resolving the #237 negative prior; foreign UUID → exit 9 pre-generation with screenshot; **#288 duration fail-fast proven live** — exit 23 pre-submit saved a 10-credit generation, and the debug screenshot confirmed the duration control is ABSENT from the cohort's settings popover [locale hypothesis refuted]; upload-400 exit-27 repro deferred-with-reason — the original rejected JPEG no longer exists). Prior: [v0.31.0](LIVE_VERIFICATION_v0.31.0.md) (**#281 wrong-media defenses live-verified in BOTH directions, credit-free** — correct attribution downloads with real wire metadata [seed, 768×1376]; the incident-class lazy-render ambiguity reproduced live and hard-stopped with `MediaAttributionError` exit 26 naming every candidate UUID, no file written; **#282 two-UUID-ref i2i proven e2e** — both freshly generated portrait UUIDs picker-selected into one scene with both canonical identities visually transferred). Prior: [v0.30.0](LIVE_VERIFICATION_v0.30.0.md) (**agentic-cohort image path + both fixes live-verified credit-free** — native 768×1376 stills, i2i-chain + canonical-ref identity hold; the character-create `DataIntegrityError` and the `prefer_classic` WARNING were observed live then fixed [recorder idempotent + INFO log]; MCP video-param feature deferred-with-reason on Veo credits, per the stills-only goal). Prior: [v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
+**What was actually live-verified for the latest release?** → latest: [LIVE_VERIFICATION_v0.36.0](LIVE_VERIFICATION_v0.36.0.md) (**#316 diagnostic tooling live-verified against real Flow traffic** — `GFLOW_CLI_HAR_PATH` captured a real 54-entry HAR [real Flow domains, 34× 200s, and a genuine 401 the tool exists to diagnose]; `GFLOW_CLI_DEBUG_TRACEBACK`'s typed-error scoping confirmed live [console output identical with/without the flag on a `GFlowError`]; unhandled-path behavior covered by 6 new tests (30 total across both files) + SDD task review; #312 reference-entity-smuggling fix covered by its own dedicated e2e test). Prior: [v0.35.0](LIVE_VERIFICATION_v0.35.0.md) (**#305-follow-up multimodal reverse-engineering & storyboard tool proven live e2e** — `gflow tools run storyboard` successfully deconstructed a cyberpunk scene into a cohesive 4-panel sequence; `reverse-engineer` tool extracts frames from video streams/URLs using `claude-video`'s `watch.py` and produces structured prompt components using Gemini multimodal models; dynamic token budgeting and strict Pyright types verified via test suite). Prior: [v0.34.0](LIVE_VERIFICATION_v0.34.0.md) (**#299 `--ui-mode` gate proven live, ZERO credits** — drove `get_ui_driver` directly over 4 real editor loads, never generated: bidirectional switch works [classic→agentic via `_force_agent_mode`, agentic→classic via `_exit_agent_mode`, each DOM-reverified], `agentic`-when-already-agentic is idempotent, and a timed-out toggle → **exit-28 fail-fast before submission**; deprecation behavior-change [`prefer_classic`→exit 28] confirmed). Prior: [v0.33.0](LIVE_VERIFICATION_v0.33.0.md) (**#287-follow-up picker fix proven live on the original repro** — the v0.32.1-failing `i2v <uuid> --project <crowded>` command now exits 0 with a real 3.0 MB `ftyp` mp4, `frame_ref_attached` + `video_saved`, zero uploads; **#241 jitter live-verified on both paths** — flag `--jitter 4-6` → `batch_jitter_sleep seconds=4.98`, and the new 0.5–1.5 s default → `seconds=1.47`, each firing exactly once between two t2i submissions; environment note: the denon82 cohort is now natively agentic and round-2 generations hit the pre-existing #281 `MediaAttributionError`, not a regression). Prior: [v0.32.1](LIVE_VERIFICATION_v0.32.1.md) (**#293 teardown fix live-verified credit-free** — error-path aborts leave ZERO chrome.exe holding the profile [3× leak reproduced pre-fix same day]; force-close fallback + ProfileLockedError translation unit-pinned; #283 wave logic fixes mock-verified to exact call counts). Prior: [v0.32.0](LIVE_VERIFICATION_v0.32.0.md) (**#287 UUID i2v frames proven live e2e** — an in-project asset selected by media UUID in the frame-slot dialog [frame_ref_attached, startImage bound on the wire, ZERO upload events] produced a real 720×1280 interpolation, resolving the #237 negative prior; foreign UUID → exit 9 pre-generation with screenshot; **#288 duration fail-fast proven live** — exit 23 pre-submit saved a 10-credit generation, and the debug screenshot confirmed the duration control is ABSENT from the cohort's settings popover [locale hypothesis refuted]; upload-400 exit-27 repro deferred-with-reason — the original rejected JPEG no longer exists). Prior: [v0.31.0](LIVE_VERIFICATION_v0.31.0.md) (**#281 wrong-media defenses live-verified in BOTH directions, credit-free** — correct attribution downloads with real wire metadata [seed, 768×1376]; the incident-class lazy-render ambiguity reproduced live and hard-stopped with `MediaAttributionError` exit 26 naming every candidate UUID, no file written; **#282 two-UUID-ref i2i proven e2e** — both freshly generated portrait UUIDs picker-selected into one scene with both canonical identities visually transferred). Prior: [v0.30.0](LIVE_VERIFICATION_v0.30.0.md) (**agentic-cohort image path + both fixes live-verified credit-free** — native 768×1376 stills, i2i-chain + canonical-ref identity hold; the character-create `DataIntegrityError` and the `prefer_classic` WARNING were observed live then fixed [recorder idempotent + INFO log]; MCP video-param feature deferred-with-reason on Veo credits, per the stills-only goal). Prior: [v0.29.0](LIVE_VERIFICATION_v0.29.0.md) (**persistent `gflow instructions` CRUD proven live e2e GREEN, credit-free** — 11-command sequence on a fresh project: add incl. `--ref <image-UUID>` attach, list/enable/disable, master toggle both ways, TOML `apply` destructive full-sync with `enabled=false` honored, `rm` with server card-id preserved across mutations; movie brief-sync code-path-verified via the same primitives, deferred-with-reason on credits; MCP `gflow_instructions_*` tools are thin adapters over the live-verified primitives). Prior: [v0.28.0](LIVE_VERIFICATION_v0.28.0.md) (**agent instructions `-i` now steer agentic generation — crayon e2e GREEN**: a style-neutral prompt + an enabled "crayon" card produced an unmistakable crayon drawing through the real transport; root causes were conversational phrasing + the `project_brief.enabled` master switch). Prior: [v0.27.1](LIVE_VERIFICATION_v0.27.1.md) (**v0.27.0 release follow-up fixes and documentation sync**). Prior: [v0.27.0](LIVE_VERIFICATION_v0.27.0.md) (**`[style]` block with named variants + prompt-aware resume — credit-free CLI verification**: real `movie run --dry-run` 3-way ledger proving resolved-style display, `skip (done)` on matching `style_hash`, and `re-run (style changed)` after a style edit; composition is local, wire path untouched, so no Veo credits spent — first credited styled run will confirm visually). Prior: [v0.26.0](LIVE_VERIFICATION_v0.26.0.md) (**image i2i by generated-image UUID proven live e2e GREEN** — the existing asset is *selected in place* by its media UUID, no duplicate upload, producing an i2i output that references it; plus generated-image `display_name` capture, credited @C1ph3r404). Prior: [v0.25.0](LIVE_VERIFICATION_v0.25.0.md) (**#237 remote-UUID i2v proven live e2e GREEN** — a real 8s 720×1280 interpolation from a generated image's UUID, after the picker-search attach was reworked to local upload; #240 home-`.env` matrix live; plus two silent-failure guards root-caused live: video-as-image download rejection and rejected-upload fail-loud). Prior: [v0.24.0](LIVE_VERIFICATION_v0.24.0.md) (--project parity across CLI + MCP — automated coverage; live gen auth-gated). Prior: [v0.23.0](LIVE_VERIFICATION_v0.23.0.md) (MCP generation wiring proven live end-to-end — tool→worker→real Flow REST→structured-error translation; final image-write blocked by an expired session, environmental. #222 macOS fix reporter-verified e2e on Apple Silicon). Prior: [v0.22.0](LIVE_VERIFICATION_v0.22.0.md) (Tools framework — automated/CI coverage complete; credit/key-gated live feature run is a pending owner gate, see the doc) · [v0.21.0](LIVE_VERIFICATION_v0.21.0.md) (MCP server over stdio + HTTP/SSE — credit-free protocol handshake; 4 tools / 2 prompts / 3 resources confirmed on stdout) · [v0.20.1](LIVE_VERIFICATION_v0.20.1.md) · [v0.20.0](LIVE_VERIFICATION_v0.20.0.md) · [v0.19.0](LIVE_VERIFICATION_v0.19.0.md) · [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
 **"Where is the reverse-engineered wire protocol for a feature?"** → the `*_RECON.md` design docs: [CHARACTER_RECON](CHARACTER_RECON.md) (Flow character entity protocol), [IMAGE_UPSCALE_RECON](IMAGE_UPSCALE_RECON.md) (`/v1/flow/upsampleImage` wire). Naming convention: one `<FEATURE>_RECON.md` per reverse-engineered surface, kept as the durable spec after the feature ships.
 **"What was live-verified for the data layer (PR #58)?"** → [LIVE_VERIFICATION_data_layer](LIVE_VERIFICATION_data_layer.md) — 1 Imagen + 1 Veo credit on denon82, 6-layer ledger (file + magic + Pillow + DB rows + CLI round-trip + structlog)
 **"What was live-verified for the video-download feature (#29)?"** → [LIVE_VERIFICATION_video_download](LIVE_VERIFICATION_video_download.md)

gflow_cli-0.36.0/docs/LIVE_VERIFICATION_v0.36.0.md

@@ -0,0 +1,46 @@
+# Live Verification — v0.36.0 (2026-07-16)
+
+The release's new user-facing features — `GFLOW_CLI_HAR_PATH` and `GFLOW_CLI_DEBUG_TRACEBACK` — were exercised against a live Flow session and verified. The third change in this release, the reference-entity-smuggling fix (#312), already carries its own dedicated e2e regression test (`tests/e2e/test_entity_smuggling_e2e.py`) from the PR that introduced it; not re-run here.
+
+---
+
+## 1. Verified Features
+
+### A. `GFLOW_CLI_HAR_PATH` (Playwright network capture)
+
+* **Command:** `GFLOW_CLI_HAR_PATH=<path> gflow character list --project 74a0ffb6-ccff-4bd2-a6a2-3c5b9b805256 --profile ffroliva`
+* **Ledger Details:**
+  * **File written:** 9.4 MB HAR file at the configured path, valid JSON (HAR 1.2 format).
+  * **Structlog invariant:** `client.har_capture_enabled` fired with the security hint before launch, correlated to the run's `correlation_id`.
+  * **Real traffic captured:** 54 entries across 9 domains including `labs.google`, `aisandbox-pa.googleapis.com`, `lh3.googleusercontent.com`. 34 successful (200) responses, including the Flow editor shell (`GET https://labs.google/fx/tools/flow?hl=en` → 200) and static assets.
+  * **Genuine failure captured too:** the profile's session token had expired since its last use — the HAR correctly captured the resulting real `401` on the `projectInitialData` call, which the CLI surfaced as a typed `AuthExpiredError` (exit 3) with the standard remediation hint. This is exactly the diagnostic scenario the feature exists for.
+  * **Permissions:** `os.stat().st_mode` reports `0o666` on this Windows run — expected, not a bug: NTFS has no POSIX permission bits, and the design's own chmod call is a documented no-op there (`tests/api/test_client_launch_kwargs.py::test_close_browser_resources_chmods_har_file` skips the permission assertion on `win32` for the same reason). POSIX hardening is covered by unit tests with a real `stat.S_IMODE` assertion; not independently live-verified on this Windows machine.
+
+### B. `GFLOW_CLI_DEBUG_TRACEBACK` (unhandled-exception visibility)
+
+* **Command:** `GFLOW_CLI_DEBUG_TRACEBACK=1 gflow character list --project not-a-real-project-id-!!! --profile ffroliva`
+* **Ledger Details:**
+  * **Correct scoping confirmed live:** the run hit the same typed `AuthExpiredError` (a `GFlowError`, not the unhandled catch-all this flag gates) — console output was identical with and without the flag, confirming `GFLOW_CLI_DEBUG_TRACEBACK` does not alter typed-error output, exactly as designed (typed errors already show full `detail`/`remediation_hint` unconditionally; only the unhandled/catch-all path is gated).
+  * **Unhandled-path behavior:** not independently re-triggered live in this pass (the available live sessions only reached typed-error paths). Covered by 6 tests added specifically for this feature (2 console-path, 2 JSON-path, 1 Rich-markup regression, plus 1 env-var-parsing test) across `tests/cli/test_error_handling.py` and `tests/test_json_output.py` — 30 tests total in those two files after this change, including pre-existing coverage — each individually reviewed by a task-scoped code reviewer during implementation (see PR #321) — including the Rich-markup regression test for a real crash the review process caught (bracketed exception text, e.g. this codebase's own Playwright selector strings, previously risked crashing or silently corrupting the debug output).
+
+### C. Reference entity smuggling fix (#312)
+
+* **Verification:** covered by its own dedicated e2e test added in the fix's PR (`test(e2e): add E2E test for reference entity smuggling prevention`, commit `1c53e42`, file `tests/e2e/test_entity_smuggling_e2e.py`), part of `develop` before this release cycle. Not re-exercised live in this pass.
+
+---
+
+## 2. Verification Ledger Summary
+
+| Feature | Verification Method | Status | Evidence |
+|---|---|---|---|
+| `GFLOW_CLI_HAR_PATH` | Live run against real Flow session | ✅ Verified | 54-entry HAR, real domains + a genuine captured 401 |
+| `GFLOW_CLI_DEBUG_TRACEBACK` (typed-error scoping) | Live run, compared with/without flag | ✅ Verified | Identical console output on a typed `GFlowError` |
+| `GFLOW_CLI_DEBUG_TRACEBACK` (unhandled path) | 6 new tests (30 total in both files) + SDD task review | ✅ Verified | `tests/cli/test_error_handling.py`, `tests/test_json_output.py` |
+| Reference entity smuggling fix (#312) | Dedicated e2e test (prior PR) | ✅ Verified | `tests/e2e/test_entity_smuggling_e2e.py` |
+
+---
+
+## 3. Not Verified This Cycle
+
+* `GFLOW_CLI_HAR_PATH`'s POSIX `0600` file-permission hardening — only unit-tested (real assertion, real `stat` check), not live-verified, since this session's development machine is Windows and the hardening is a documented POSIX-only no-op there.
+* `GFLOW_CLI_DEBUG_TRACEBACK`'s unhandled-exception path — not re-triggered against a live Flow session in this pass (both available live-auth attempts surfaced typed errors instead); covered by extensive unit/integration coverage instead (see above).

{gflow_cli-0.35.0 → gflow_cli-0.36.0}/docs/PROJECT_STATUS.md

@@ -4,9 +4,15 @@
 
 ## Current release
 
+**v0.36.0 — alpha.** **Diagnostic tooling (`GFLOW_CLI_HAR_PATH` + `GFLOW_CLI_DEBUG_TRACEBACK`) + reference-entity-smuggling fix (#312/#316).** Two opt-in, env-var-only debug knobs: `GFLOW_CLI_HAR_PATH` captures full Playwright network traffic to a HAR file (0600-hardened on POSIX); `GFLOW_CLI_DEBUG_TRACEBACK` prints the real exception + traceback for unhandled errors (console and `--json`) instead of the generic placeholder, while structured telemetry stays hashed unconditionally either way. Also fixes a poisoned character entity leaking `referenceEntities` into unrelated `image i2i` calls in the same project workspace. Also ships the `llm-council` skill (`/gflow:llm-council`), adding external CLI reviewers (`codex`/`gemini`, opt-in `agy`) alongside the internal council for high-stakes reviews. Verification: [LIVE_VERIFICATION_v0.36.0](LIVE_VERIFICATION_v0.36.0.md) (live HAR capture against real Flow traffic; typed-error scoping confirmed live; unhandled path covered by 6 new tests, 30 total across both files).
+
+**Develop (unreleased, post-v0.36.0):** *(empty — develop is the staging branch for the next release).*
+
+<details><summary>v0.35.0 — multimodal reverse-engineering + storyboard tool</summary>
+
 **v0.35.0 — alpha.** **Multimodal reverse-engineering + Storyboard tool + Dynamic Token Budgeting (#305-follow-up).** Adds `gflow tools run storyboard` to generate sequential visual prompts from single ideas, and integrates `gflow tools run reverse-engineer` with `claude-video`'s `watch.py` script for frame extraction and multimodal deconstruction of video/URL references using Gemini. Token budgets now scale dynamically with character limits. Verification: [LIVE_VERIFICATION_v0.35.0](LIVE_VERIFICATION_v0.35.0.md) (proven live storyboard expansion + frame extraction).
 
-**Develop (unreleased, post-v0.35.0):** *(empty — develop is the staging branch for the next release).*
+</details>
 
 <details><summary>v0.34.0 — bidirectional UI cohort switching</summary>
 
@@ -202,6 +208,7 @@ reporter-verified e2e on macOS).
 | `movie.toml` `[style]` block with named variants + prompt-aware resume (`style_hash`) (#239) | ✅ done (v0.27.0) |
 | Agent instructions (`-i`/`--instruction`) steer agentic generation — conversational directive + brief master switch (PR #263) | ✅ done (v0.28.0) |
 | Persistent `gflow instructions` CRUD + `movie.toml` instructions brief-sync + `gflow_instructions_*` MCP tools + CI-enforced MCP↔CLI parity (#192) | ✅ done (v0.29.0) |
+| Diagnostic tooling (`GFLOW_CLI_HAR_PATH` + `GFLOW_CLI_DEBUG_TRACEBACK`) + reference-entity-smuggling fix (#312/#316) | ✅ done (v0.36.0) |
 | `gflow video batch` (TSV manifest) on `ui_automation` | ⏳ Phase B |
 | Persistence layer (stay-mounted batch sessions across project boundaries) | ⏳ Phase B |
 | Provider abstraction for official Veo 3.1 API | ⏳ planned |