Welcome to the gflow-cli documentation. This index is the routing layer: it tells you where each topic lives. Keep README.md slim (high-level overview + install) and document deep details here.
| Doc | Purpose | Read when… |
|---|---|---|
| README | Project overview, install, quick start | First time landing on the repo |
| docs/DEMOS.md | Gallery of gflow in action (terminal + split-screen Flow recordings) |
You want to see what gflow looks like running |
| AGENTS.md | Universal coding-agent spec — Cursor / Codex / Aider / Antigravity / Jules / etc. | Any AI coding agent enters the repo |
| llms.txt | LLM-readable summary (llmstxt.org format) | A user pastes context about gflow into ChatGPT / Claude / Gemini |
| docs/PROJECT_STATUS.md | Full milestone history + lifecycle policy | Auditing where the project is in its lifecycle |
| docs/AGENT_GUIDE.md | Mandates and routing rules for AI agents (companion to AGENTS.md) | A coding agent needs the longer non-negotiable rules |
| docs/GOVERNANCE_BENCHMARK.md | How the advisory materiality gate is measured (false-positive / coverage backtest) and calibrated | You're changing MATERIAL_PATHS or auditing whether the governance gate earns its friction |
| CLAUDE.md | Claude Code's session memory hub (Claude-Code-specific protocol; delegates universal rules to AGENTS.md) | First time Claude Code opens the repo |
| PLAN.md | Implementation plan (DDD / CQRS / phases / ADRs) | You want the architectural intent and roadmap |
| RELEASE.md | Release checklist, prerelease policy, PyPI/GitHub publishing protocol | Cutting or auditing a release |
| ROADMAP.md | Themed milestones from v0.9 through v1.0 | You want a multi-release view of where the project is heading |
| CHANGELOG | Version-by-version user-visible changes | Upgrading or auditing what shipped |
| KNOWN_ISSUES | Open / mitigated / resolved issues with workarounds | Before opening a bug report; when something feels off |
| DISCLAIMER | Legal scope, takedown policy, prohibited uses | Before deploying anywhere non-trivial |
| LICENSE | MIT license text | Always |
| CONTRIBUTING | The development lifecycle a PR is reviewed against (phase → skill → artifact), TDD workflow, test categories, coverage targets | Before opening a PR — and before pointing a coding agent at the repo |
| docs/DEVELOPMENT.md | Branching model, PR protocol, e2e gate, version bump protocol, AI-assisted workflow | Understanding the end-to-end dev process |
| docs/E2E_TESTING.md | Layer model, cost sub-markers, run commands, isolation patterns, roadmap to contract/replay layer | Running or extending e2e tests; cost control |
| docs/AGENT_UI_E2E.md | Deterministic e2e runbook for the Agentic UI image path (force-agent trigger, validation ledger) | Live-verifying Agentic-UI features |
| docs/GITHUB.md | Maintainer PR triage protocol, forked PR handling, SonarCloud scenarios, workflow security gates | Reviewing or merging a GitHub PR; adding or changing a workflow |
| docs/sonar-cleanup-tracker.md | SonarCloud zero-smells cleanup tracker (chore/sonar-zero-cleanup) |
Resuming or auditing the Sonar cleanup effort |
| docs/medium_tutorial.md | Long-form tutorial article (Medium draft): Veo + Imagen from the terminal | Writing or updating outreach/tutorial content |
| .env.template | All environment variables with defaults | Setting up a new shell or container |
| docs/AUTHENTICATION.md | Full auth flow, session storage, multi-account, refresh | First gflow auth login, or auth errors |
| docs/CONFIGURATION.md | All env vars, precedence chain, default paths per OS | Tuning behaviour, picking output paths |
| docs/EXTERNAL_STORAGE.md | S3, MinIO, and Google Cloud Storage output configuration | Sending generated assets to a bucket instead of local disk |
| docs/USER_GUIDE.md | Task-oriented walkthroughs (first setup, batch video, multi-image, log forensics, recovery, multi-account, migration) | You want to GET SOMETHING DONE — not look up a flag |
| docs/USAGE.md | Command-by-command reference, credit-balance inspection, manifest format, recipes, exit-code table | Day-to-day CLI use — look up specific commands / flags |
| docs/ARCHITECTURE.md | Modular monolith, per-worker Page pool, RFC 9457 Problem Details, retry layer | Adding a feature or a new provider |
| docs/SECURITY.md | What secrets are stored where, threat model, hardening | Audit, code review, multi-user machines |
| docs/DATA_LAYER.md | Local SQLite catalog: goals, schema, recording flow, redaction, gflow data CLI, migrations, extension guide |
Anything touching gflow_cli.data, debugging missing rows, building I2V/repair tooling, auditing what is stored |
| docs/CHARACTER.md | Characters feature spec & system design: domain model, endpoint/cost matrix, sequence diagrams, JSON payloads (I/O), CLI surface, reuse via referenceEntities (#145) |
Working on gflow character, reusing a character in generations, or understanding Flow's character wire protocol |
| docs/REFERENCE_STRATEGIES.md | How to reference an asset: @Name mention vs --reference-entity vs --ref — the two-axis model (identity vs image), same-wire+dedupe rule, per-path support matrix, image-less-entity prerequisite, agent rule |
Deciding how to tag a saved character/asset in a prompt, or wiring @-mentions into a generation |
| docs/MEDIA_LIBRARY.md | Flow's media library as a component: asset-kind taxonomy (media[]/workflows[]/preset voices), UUID-vs-displayName identity rules (AI caption ≤~35 chars, mutable, async, non-unique), the projectInitialData listing endpoint (complete, direct-GET-able), picker UI facts (virtualized grid, per-picker project, no a11y tree, single-click attach) + full pitfall table |
Touching any picker/listing/reference code, or debugging why an asset "isn't found" |
| docs/MOVIE.md | gflow movie — multi-scene character-consistent films: manifest format, run lifecycle (browser stays open through generate→poll→download), entity-attach mechanism (Personagens right-click), resume/handoff, credits |
Working on gflow movie, debugging scene generation, or understanding the character-entity attach + consistency model |
| docs/TOOLS.md | Tools framework: the gflow tools list/show/run group, the --tool/-t option on generation commands, the TOML tool schema, how a tool is defined, "My Tools" user-authored tools, MCP exposure + §61 parity |
Working on gflow_cli.tools, adding a built-in or user tool, or wiring --tool into a command |
| docs/INSTRUCTIONS.md | Agent Instructions: project-brief cards for Flow's Agent Mode — the mechanism (enabled cards steer generation via the reasoning path), ephemeral -i vs persistent cards, the gflow instructions CRUD surface with the single generic --ref (image or character), and the 3-layer pipeline |
Working on -i/agent instructions, the gflow instructions group, or understanding how the project brief anchors generations |
| docs/MCP.md | MCP server: gflow mcp run (stdio) + gflow serve (Streamable HTTP, SSE deprecated), the tools/prompts/resources surface, the CLI↔MCP parity contract (AGENTS.md "MCP & CLI Schema Symmetry", enforced by tests/mcp/test_cli_parity.py), security model, client setup |
Configuring an MCP client, working on gflow_cli.mcp, or debugging the stdio/HTTP transports |
| docs/PROMPT_EXPANSION.md | The creative-director tool: 5-component formula, 15 domain styles, banned-keyword policy, Gemini endpoint + I/O, never-fatal contract, expanded_prompt + metadata_json.tool provenance/redaction, config |
Using or debugging --tool creative-director, editing the tool TOML, or auditing recorded prompt provenance |
| docs/IMAGE_UPSCALE_RECON.md | gflow image upscale wire protocol: upsampleImage endpoint, full clientContext (projectId/sessionId/tool/userPaygateTier), reCAPTCHA action IMAGE_GENERATION, inline base64 response, 4K Ultra-gating, REST-is-dead proof |
Working on gflow image upscale, debugging the 403/reCAPTCHA path, or understanding Flow's image-upscale wire protocol (#171) |
| docs/AGENT_UI_RECON.md | Agentic Flow UI cohort: classic-vs-agentic DOM signature, server-side + volatile (flapping) A/B gating (no client-readable flag), why _exit_agent_mode fails, runtime-DOM-detection recommendation |
Touching _exit_agent_mode / composer mode-switch, diagnosing exit 23 selector drift, or understanding Flow's agentic-UI A/B (#183/#174) |
| docs/ASSET_TAGGING_RECON.md | @-mention asset tagging research & integration design: what Flow's @CharacterName/@me/@ingredient tags are, how they map onto the already-verified referenceEntities/referenceImages wire, the H1-vs-H2 serialization hypothesis, the CLI-side mention-resolver proposal, and the pre-implementation capture spike plan |
Working on inline @ mentions in prompts, video --character reuse, or planning the mention-capture spike |
| tasks/lessons.md | Running notebook of patterns + reviewer findings, dated and traced to commits | Starting a new phase; debugging "why did the council flag this?" |
| skills/README.md | Installable agent skill docs (gflow-cli, predict, pr-council-review, scenario) — cross-tool portable Markdown consumed by Claude Code, Cursor, Codex, Antigravity, Aider, etc. | Any agent wanting to use gflow-cli correctly |
| scripts/dev/skillopt/README.md | SkillOpt mock harness — rollout→score loop for measuring and improving skill doc accuracy, against any OpenAI-compatible endpoint via the GFLOW_CLI_LLM_* settings |
Measuring a skill edit's impact; comparing two models on gflow tasks |
| scripts/diag/README.md | Diagnostic investigation scripts — run against a live authenticated profile to capture wire samples, measure Chrome memory, or mint reCAPTCHA tokens | Running a one-off investigation against a live Flow session; establishing baseline measurements for issue #155 |
| docs/superpowers/specs/2026-07-04-pr-triage-autopilot-design.md | PR-triage autopilot design spec: Stage 0/1 gate, Docker sandboxing, Telegram and audit ledger | Reviewing or auditing the automated PR-triage setup |
| docs/superpowers/plans/2026-07-08-pr-triage-autopilot/PLAN.md | Implementation plan for the PR-Triage Autopilot | Tracking task-by-task execution |
| docs/superpowers/specs/2026-07-18-asset-tagging-design.md | Asset-tagging (@-mention) design spec: mention grammar, resolution contract, Option-B architecture, error taxonomy, spike gate |
Reviewing or implementing the @-mention feature |
| docs/superpowers/plans/2026-07-18-asset-tagging/PLAN.md | Task-by-task implementation plan for asset tagging (spike gate → resolver → CLI/MCP → live e2e) | Tracking task-by-task execution of the @-mention feature |
| docs/superpowers/specs/2026-07-19-live-verify-design.md | /gflow:live-verify design spec: pre-flight state check + per-feature live-verification gate generalizing release step 4b, council-reviewed |
Reviewing or implementing the live-verification enforcement skill |
| docs/superpowers/plans/2026-07-19-live-verify/PLAN.md | Task-by-task implementation plan for /gflow:live-verify (skill file → AGENTS.md/check.md wiring → INDEX row) |
Tracking task-by-task execution of the live-verify skill |
| docs/superpowers/plans/2026-07-27-tier-aware-credit-confirmations/SCENARIO.md | Edge-case matrix for replacing fixed chain/movie credit estimates with truthful pending-operation guidance | Reviewing the financial-safety, resume, dry-run, and compatibility scenarios |
| docs/superpowers/plans/2026-07-27-tier-aware-credit-confirmations/PLAN.md | TDD implementation plan for tier-aware chain/movie planning and confirmation output | Tracking the isolated runtime pricing-guidance bugfix |
| docs/superpowers/specs/2026-08-21-selector-registry-design.md | Selector registry + drift probe design spec: measured one-cookie auth evidence, data model, grading semantics, CI probe, risk register | Reviewing the registry/probe design or auditing its evidence |
| docs/superpowers/plans/2026-08-21-selector-registry.md | Task-by-task TDD plan for the selector registry + CI probe (executed — PR #563) | Auditing how the registry/probe was built |
| docs/superpowers/plans/2026-08-25-workflow-hardening-gaps.md | Spec + decisions + TDD plan for #568 — why the pin is derived from ci.yml, why the injection ban stays blanket, why the property tests are kept |
Bumping zizmor, or re-opening "should these tests exist" |
Slash commands for Claude Code, stored in .claude/commands/gflow/. All prefixed /gflow: to signal project scope and avoid colliding with Claude Code built-ins or user-global commands.
| Command | Purpose | Call when… |
|---|---|---|
/gflow:check |
Hygiene + auto-fix lint/format + type/test report | Before every commit |
/gflow:status [feature] |
Full state: active plan, progress, next unchecked task | Starting a session; after completing a task |
/gflow:next [feature] |
Next unchecked task only — no context noise | Quick "what do I do right now?" |
/gflow:active |
Which plan is active and its goal — no task detail | Before predict/scenario; quick orientation |
/gflow:plan <feature> |
Create a task-by-task implementation plan → writes docs/superpowers/plans/ |
After predict GO/CAUTION; when a backlog item needs a concrete breakdown |
/gflow:known-issues |
Surface open and mitigated issues | Before touching auth, reCAPTCHA, or previously-flagged code |
/gflow:changelog |
Show [Unreleased] entries + last tagged release |
Need a quick picture of recent work |
/gflow:release |
Full release flow (calls /gflow:changelog + /gflow:check) |
Cutting a new version |
/gflow:predict <proposal> |
5-persona pre-implementation analysis → GO / CAUTION / STOP | Before any high-stakes design decision (new transport, auth change, selector redesign, schema migration) |
/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 + Antigravity 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.
"What's the governance flow, and which paths require predict/council?" → AGENT_GUIDE § Governance & Enforcement
"Why did the materiality advisory flag my PR?" → AGENT_GUIDE § Materiality coverage
"I just installed gflow — how do I get to my first video?" → USER_GUIDE § Journey 1
"How do I render 20 clips overnight?" → USER_GUIDE § Journey 3
"How much will this batch cost me in Veo credits?" → USER_GUIDE § Journey 10
"How many Veo credits remain on one or all profiles?" → USAGE § gflow credits
"How do I feed gflow outputs into ffmpeg / a pipeline?" → USER_GUIDE § Journey 11
"How do I chain clips into one continuous video (initial-frame I2V)?" → USAGE § gflow video chain
"How do I stitch existing clips into one extended .mp4 (credit-free, no ffmpeg)?" → USAGE § gflow scene
"How do I make one clip longer than Flow's 8-second cap?" → USAGE § gflow video extend (costs credits per segment; a segment carries ~7s of content though Flow bills 8s — see KNOWN_ISSUES)
"How do I create a reusable character (face + body) I can reuse across generations?" → USAGE § gflow character · design: CHARACTER
"Should I use an @mention, --reference-entity, or --ref to tag an asset?" → REFERENCE_STRATEGIES — saved named identity → @Name/--reference-entity; one-off image → --ref
"How does Flow's media library / picker actually behave (names, tabs, scrolling, listing)?" → MEDIA_LIBRARY — identity = UUID, names are async AI captions; grid is virtualized; full pitfall table
"How do I turn a terse prompt into a vivid one before generating?" → --tool creative-director:style=cinema on any generation command — see PROMPT_EXPANSION · framework: TOOLS
"What tools are available and what styles do they support?" → run gflow tools list / gflow tools show creative-director — see TOOLS
"How do I make Flow's agent follow a style/reference across a project's generations?" → agent instruction cards — ephemeral -i "text" (shipped) or the persistent gflow instructions group with a generic --ref (image or character), see INSTRUCTIONS
"What preset voices can a character use?" → run gflow character voices — see USAGE § gflow character voices
"My batch run died with exit code 3 (auth) — what now?" → USER_GUIDE § Journey 7
"Exit code 4 (rate-limit) or 5 (content-policy) — how do I recover?" → USER_GUIDE § Journey 12
"How do I read the structured log (error_raised events)?" → USER_GUIDE § Journey 6
"What exit code does shell branching see for each error class?" → USAGE § Exit codes
"Is v0.5.0a1 a prerelease, and how do I cut a full release?" → RELEASE § Prerelease Versus Full Release
"Where is my session stored?" → AUTHENTICATION § Session storage
"Where do generated files land?" → CONFIGURATION § Output paths
"How do I write outputs to S3, MinIO, or Google Cloud Storage?" → EXTERNAL_STORAGE and CONFIGURATION § GFLOW_CLI_STORAGE_URI
"How do I run with multiple Google accounts?" → AUTHENTICATION § Multiple accounts
"How do I know which Google account a profile is signed into?" → AUTHENTICATION § gflow auth list
"Why is my profile named 'default' and how do I rename it?" → AUTHENTICATION § Profile naming
"How does login verification work without launching a browser?" → AUTHENTICATION § Session verification (cookie-store fast path, v0.17.0)
"How does the layered structure work?" → ARCHITECTURE § Layers
"What env var should I set for X?" → CONFIGURATION § Reference
"What does gflow remember after a generation finishes?" → DATA_LAYER § What is recorded
"How do I see what's in my gflow catalog?" → run gflow data list projects (or images / videos / profiles) — see DATA_LAYER § Querying the data layer
"Where can I look up a media ID I generated yesterday?" → DATA_LAYER § Querying the data layer
"How do I stop gflow from storing my prompts?" → DATA_LAYER § Privacy and redaction
"What does exit code 16 mean and how do I recover?" → DATA_LAYER § Persistence-failure handling
"Is my install/catalog healthy?" → run gflow doctor (read-only, never migrates; exit 33 = findings present) — see USAGE § gflow doctor
"My old assets re-upload / have no names?" → run gflow data sync --names (credit-free name backfill from Flow's listing) — see USAGE § gflow data sync
"How do I use this project's skills in Cursor / Codex / Antigravity / Aider?" → skills/README.md
"How do I benchmark a skill doc against real tasks?" → scripts/dev/skillopt/README.md
"How do I compare two models on gflow tasks?" → set GFLOW_CLI_LLM_BASE_URL / GFLOW_CLI_LLM_API_KEY at any OpenAI-compatible endpoint, then uv run python scripts/dev/skillopt/harness.py --model <id> once per model (see skillopt README)
"What does Chrome actually use in RAM during a generation?" → run uv run python scripts/diag/memory_profile.py --profile NAME (see scripts/diag/README.md)
"How do I report a security issue?" → SECURITY § Reporting
"What branch do I work on? How do I name it?" → DEVELOPMENT § Branching model
"What secures our GitHub Actions workflows?" → GITHUB § Workflow Security Gates
"How do I handle an external GitHub PR?" → GITHUB § Scenario Matrix
"What automation runs on external PRs?" → GITHUB § Automated External PR Triage
"How do we use Copilot review on PRs?" → GITHUB § GitHub Copilot Code Review
"Why did SonarCloud skip or fail on a forked PR?" → GITHUB § Forked PRs And SonarCloud
"How do I run e2e tests before a release?" → DEVELOPMENT § E2e gate
"What does each e2e marker cost? How do I run only the cheap tests?" → E2E_TESTING § Run commands
"Has Flow drifted since the last release? What is the nightly canary telling me?" → E2E_TESTING § Nightly canary
"Which Flow selector moved? What is the CI selector probe telling me (exit 0/1/2)?" → E2E_TESTING § Selector drift probe
"When does the version get bumped?" → DEVELOPMENT § Version bump protocol
"How do I embed FlowApiClient in a long-lived worker / service?" → USER_GUIDE § Journey 14
"What's the standard way to import gflow errors in my code?" → USAGE § Programmatic use
"gflow refuses to open my profile after a downgrade (exit 11, 'written by a newer Chromium')" → AUTHENTICATION § Chromium downgrade guard
"Two gflow runs on the same profile — can the second one wait instead of failing (exit 11)?" → CONFIGURATION § GFLOW_CLI_LEASE_WAIT_SECONDS (v0.56.0 opt-in bounded wait)
"How do I silence the 'newer version on PyPI' stderr banner?" → CONFIGURATION § GFLOW_CLI_UPDATE_CHECK (0 disables; auto-skipped in CI and for editable installs)
"How do I upgrade gflow-cli?" → USAGE § gflow update (gflow update runs the installer that put it here — uv tool / pipx / pip; --check only reports; source installs are refused with exit 11)
"How do I run the MCP server so an agent can't spend credits?" → CONFIGURATION § GFLOW_MCP_NO_SPEND + MCP § Option A2 (gflow mcp run --no-spend / GFLOW_MCP_NO_SPEND=1; v0.57.0 — both generate tools go unregistered, not merely refused)
"Which Flow UI arm does a run require, and why did it exit 2 or 28?" → CONFIGURATION § GFLOW_CLI_UI_MODE (auto ≡ classic for both images and video — video since v0.57.0/#299, images since #595; unreachable classic aborts pre-submit with exit 28, $0; explicit agentic on video exits 2)
"Which Flow frontend does a run drive — labs.google or the migrated flow.google.com — and why did it exit 36 or 11?" → CONFIGURATION § GFLOW_CLI_FLOW_HOST (auto = flow.google.com for every request it can serve — t2v, i2v from a local --initial-frame, r2v from local --ref files, image t2i, and image i2i from local files, with --project, on moved and unmoved accounts; flow.google.com forces it; labs.google is the kill switch. On a moved account an end frame, a UUID/@Name frame, references by @Name/--reference-entity and everything except t2v/i2v/r2v exit 36, non-retryable, and a missing --project exits 11) · recon: character surface + reCAPTCHA mint, migrated-host wire protocol, handoff mechanism, agent mode hides the settings trigger, frames attach (i2v) · evidence: LIVE_VERIFICATION_v0.67.0 (t2v), LIVE_VERIFICATION_v0.69.0 (i2v from a local start frame, v0.69.0), LIVE_VERIFICATION_v0.70.0 (r2v on the migrated host; character create verified there in #703)
"Will this get my Google account flagged or banned? What protects me?" → ACCOUNT_SAFETY.md — the operational answer in one place: rate limit vs WAF block vs ban (they are different), what the tool does to stay unremarkable (headed real Chrome, ±25% interaction jitter, 0.5–1.5 s submission pacing, one project per run, isolated profiles, refuse-don't-retry), what it deliberately does not do (no proxies, no fingerprint spoofing, no headless unlock), the knobs, the #241 field data on what actually triggers a 403, and what we cannot promise. Legal statement: DISCLAIMER
"I got a 403 / PUBLIC_ERROR_UNUSUAL_ACTIVITY — what now?" → ACCOUNT_SAFETY § When Google does push back (stop, cool down 30–60 min, use real Chrome meanwhile, switch profile, widen jitter); cadence evidence in DEBUGGING § WAF cadence; full entry in KNOWN_ISSUES
"A gflow command hangs / fails — where do I start?" → DEBUGGING § Quick reference
"A command failed — where is the incident bundle and what's in it?" → DEBUGGING § Automatic incident bundles (layout, triggers, review-before-sharing); privacy boundaries: SECURITY § Automatic incident bundles; disable via CONFIGURATION § GFLOW_CLI_INCIDENT_CAPTURE
"Flow's UI broke a selector — how do I diagnose it?" → DEBUGGING § Inspecting Flow's live UI
"What does each ui_automation.* log event mean?" → DEBUGGING § Listener & HTTP-layer debugging
What was actually live-verified for the latest release? → latest: LIVE_VERIFICATION_v0.72.0 (auto-closing gflow auth login, verified 2026-09-09 on a migrated account at $0 across six runs. Four paths: auto-close fires (probe=in_context at elapsed_s 84.8, reproduced 3x), a manual close still verifies from disk (exit 0, never exit 12), --browser auto selects and completes, and a window closed mid-2FA is noticed in 2 s (exit 8) where it previously ran the full 600 s deadline with the session endpoint touched zero times. Two runs were discarded rather than counted, and that is the useful part: the first returned exit 0 at elapsed_s: 0.2 because a throwaway profile had survived the previous session and nobody signed in — a cached session reading as a clean pass — and three attempts at the manual-close path all returned exit 0 while being the auto-close path in disguise, separable only by an absent probe=in_context. The manual path was obtained by widening the poll interval for one run so the competing branch could not fire; the 2FA path by killing the profile's own Chrome, because hand-timing lost every race on a host that completes passkey sign-in in ~15 s. Recorded as NOT verified rather than omitted: the migrated-host image slice (#692) was re-run this cycle — CLI t2i PASSED first-hand on a moved account, while the queued-MCP i2i twin failed with a typed non-retryable exit 27 whose cause is unknown — some dialog opened after the file was chosen and no maseQ left the page, on an account that has ALREADY consented, so the message's "most likely the one-time upload-terms dialog" does not fit; no incident bundle was written, so nothing names the dialog, and it is filed for a spike rather than guessed; the subprocess fallback is unit-tested only; and the OAuth-callback mechanism behind the poll fix is inferred, not proven — a host-only gate does not exclude NextAuth's callback, since it runs on the app's own origin, yet all four sign-ins passed under it, so #769 carries the spike that would settle it.) · previous: LIVE_VERIFICATION_v0.71.1 (two migrated-host error paths stopped blaming the wrong thing, 2026-09-08, $0 across three profiles. The agent-mode recovery landed earlier in this same release (#749) and worked, but its first cut collapsed three outcomes into one message — chip clicked / chip found but click blocked / chip clicked and mode still on — so a modal eating the click sent users to toggle a chip that was never the problem, and genuine selector drift after the mode was left was filed under an account setting the driver had already changed. Verified by an e2e that drives the account INTO agent mode and carries its own neutered-selector control; run twice, because review fixes landed after the first run and it no longer covered the code. The larger find: an account's FIRST upload on this host is blocked by Flow's one-time "Rights to use this image" dialog, which renders after the file chooser hands the file over — so _dismiss_dialog never sees it and the driver spent 60 s waiting for a request the page had already declined to make, then advised re-encoding the image. Six runs on ci-probe close the chain: guard fires while the dialog is up → owner-authorised accept → uploads (media_id 8914400f) → fresh session uploads clean with dialog: None. The order was forced, because the dialog is one-off and accepting it destroys the failing state — so the guard was written and verified BEFORE anything was clicked, and its firing branch is now unrepeatable here. maseQ is confirmed not renamed (six uploads, three profiles), killing #719's top hypothesis. Also: Flow's queue listing is on Zzl0ze, not the jwpduf/as29s progress polls, and two abra_r2v_8s records sat at status 6 for ~20 h unseen by any CLI command (#741). Three documents are corrected rather than patched — a KNOWN_ISSUES entry that told #719's reader this dialog did not affect gflow-cli, and a v0.71.0 host label calling ci-probe labs when it is migrated, which helped a credit-based theory survive four runs. Recorded as NOT verified: #719's second failure shape — an upload request that leaves the page and is never answered, ~1 run in 4 — which is unfixed and keeps #719 open.) · previous: LIVE_VERIFICATION_v0.71.0 (gflow character create --voice verified end to end for the first time, 2026-09-07 on profile ffroliva. Before this release a repo-wide grep for --voice across tests/e2e/ matched nothing — every voice test was a unit test of the hardcoded VOICES constant and the one that looked live parsed a fixture, so a voice that silently failed to attach was invisible to the whole suite while the command exited 0. A live create + character show read-back settles a contradiction between two of our own documents: sent='Charon' stored='Charon' identical=True, so the Capitalized canonical form round-trips and CHARACTER_RECON.md's "preset id is the lowercased name" does not describe today's wire. Both docs also now record that personalityNotes is Agent-scoped per Flow's own editor copy, not a control on the audio engine. A claim that was in the code is overturned: the _unported_form entity guard said the submit "never produces a reply" and that the backend refuses — in fact MZZa6b replies with a null payload and the generation is accepted and queued (Flow types it abra_r2v_8s and renders it); the failure is the observer, which waits out SUBMIT_REPLY_BUDGET_S (60 s, calibrated on 4.0–4.6 s replies against an idle queue) and exits 9 while the video is still rendering. The guard stays until the observer is fixed, because a timeout reported on a healthy generation is worse than an explicit refusal. Also verified: credit shortfall reports exit 37 with _raise_if_out_of_credits called from both give-up paths — and it is short for the selected model, not empty (the measured account held 50 and asked for veo-quality, which costs 100); the "+ New project" CTA anchored structurally on add (Tier-1 matches 1 where every previous entry matched 0, control 47 ligature nodes) after this same release first asserted the control did not exist and a $0 run disproved it in one click; and the incident-bundle DOM dump de-blinded — it queried i.google-symbols only, so every bundle a migrated user sent carried an empty ligature list, which is why #727 and #731 stayed invisible. One item recorded as NOT verified rather than omitted: whether a bound character's voice reaches rendered audio (#738) — attachment is proven, application is not, because no entity-bound generation has yet returned a file to measure. The blocker is no longer credits or account access but retrieval, and the measurement is pre-calibrated: plate-bound takes of one character gave 88 / 103 / 118 Hz against a 4.3 Hz engine noise floor, so an applied Algenib should sit near its sample's 163.3 Hz.) · previous: LIVE_VERIFICATION_v0.70.0 (reference-to-video on the migrated flow.google.com host, verified 2026-09-06 on profile denon82. Three r2v runs bound their references every time; the decisive one is semantic rather than structural — two hand-drawn reference images went in and the clip came back carrying the same marker strokes, face and paper texture, which is what separates "Flow bound the reference" from "Flow accepted and ignored it". A four-beat, two-character piece was then produced end to end and joined with the concat filter: 19.000s, 1280x576, clip_qa ok, A/V +0.000s, both actors recognisable across every cut from one face plate plus the canon repeated verbatim. Also verified as exit-code corrections on the real CLI: -o <existing directory> now exits 2 in 0.8s instead of exit 1 after ~2 min and a billed, orphaned clip; character create on a moved account exits 36 immediately instead of a bare RuntimeError exit 1 after a 20s wait. Four items recorded as NOT verified rather than omitted: #692's original failure could not be reproduced [the reporter's own re-run was on a build without the fix, so it shows the failure is intermittent, not that the fix works]; Flow CHARACTER entities were never exercised because character create cannot run on any account available here; image/scene/movie/extend all exit 36 on the migrated host and no unmoved account exists here; and the sign-in-interstitial fidelity question from #699 has no bundle evidence either way.) · previous: LIVE_VERIFICATION_v0.68.0 (gflow update self-upgrading a real uv tool and a real pipx install from their own running gflow.exe to the PyPI release, Windows 11, zero credits — see its own row below) · previous: LIVE_VERIFICATION_v0.67.0 (the migrated flow.google.com driver — see its own row below) · previous: LIVE_VERIFICATION_v0.64.0 (#626 --model omni-flash --end-frame — first+last interpolation on Omni 1.1 Flash, verified 2026-09-02. The guard this release removes was evidence-gated, so it was retired on evidence: a route-aborted submit capture on two distinct Google accounts (ffroliva, denon82) fired video:batchAsyncGenerateVideoStartAndEndImage with startImage AND endImage non-null at zero credits, ruling out a single-account artifact. The decisive layer is semantic, not structural: the paid 4s generation's last frame IS the supplied end image and its first frame is the start image — two visibly different subjects — which is the only check that distinguishes "Flow bound the end frame" from "Flow accepted and ignored it", and which layers 1–4 would pass either way. Render: 4.01s / 720×1280 / h264+aac / 2.4 MB, MEDIA_GENERATION_STATUS_SUCCESSFUL. The static capability table is deleted, not corrected — it went stale silently once and would again; a post-submit route check (_assert_i2v_route) now fails a run whose end frame Flow dropped back to the StartImage route, catching a rollback on any account without anyone re-reading a support page. One item is recorded as NOT verified rather than omitted: --duration 10 + end frame is submit-verified only (duration_set seconds=10 on the correct route with both images bound), because the status poll returned HTTP 401 mid-run and a retry 401'd at project.create before submitting — #561, pre-existing, so verification was stopped rather than spending further credits on an environmental fault.) · previous: LIVE_VERIFICATION_v0.63.0 (gflow video extend — continuing a clip past Flow's 8s ceiling, verified 2026-09-01 on profile ffroliva, 20 Veo credits. The decisive observation is that segment 2's source_media_id is segment 1's media_id (0c9364f3… seeded from b9458021…, then 648f9291… seeded from 0c9364f3…) — tail-only chaining, which no mock can establish; had it re-seeded from the source, the output would have been two divergent continuations of the same moment instead of one continuous shot. extend_model_resolved logged candidate_count=99 against SERVICE_TIER_INTERMEDIATE, proving the key came from the live capability listing rather than a constant, and plan cost matched actual spend (20 credits total, balance 875 → Extended — 2/2 segment(s), 20 credits). Render: 23.02s / 1280×720 / 24fps / h264+aac. The run found a defect the offline suite is structurally incapable of seeing: an extend segment carries 7.000000s of content, not the 8 Flow advertises and bills, so server-side concat pads every internal seam with a frozen frame and digital silence (15s at −75.1 dB against −29 neighbours, reproduced on a second independent render) — filed in KNOWN_ISSUES with the three questions that must be answered before any clamp, and the reason --extend N on t2v/i2v was deliberately NOT shipped. Seven items are recorded as NOT verified rather than omitted: portrait 9:16, --aspect against a mismatched source, chains longer than 2 segments, --resume-from against a live partial scene, the insufficient-credits refusal, a live Ctrl+C, and OperationKind.EXTEND rows.) · previous: LIVE_VERIFICATION_v0.62.1 (#604 --model omni-flash selects again after Flow's Omni Flash → Omni 1.1 Flash rename, verified 2026-08-30 on profile ffroliva at ZERO Veo credits. The production _select_video_model was driven against the real picker: the shipped selector resolves verbatim — model_selected model=omni_flash via="[role='menuitem']:has-text('Omni'):has-text('Flash'):not(:has-text('[Lower Priority]'))" — and all six cases came back as expected: the four offered tiers SELECT, a tier Flow does not offer REFUSES, and a deliberately ambiguous selector REFUSES rather than resolving .first. Selection happens before submit, so the whole matrix is free. The transport's own refusal diagnostic read the live menu back as Omni 1.1 Flash / Veo 3.1 - Lite / Fast / Quality, independently corroborating the fixture. Four items are recorded as NOT verified rather than omitted: the rename direction [the Omni Flash baseline is a different account, locale and date], an actual Omni ... [Lower Priority] entry [Flow has never offered one], a full credit-spending generation on omni-flash, and #539's absence question, which stays open.) · previous: LIVE_VERIFICATION_v0.62.0 (#595 auto ≡ classic for images, verified 2026-08-28 on profile ci-probe — an account Flow had moved to the agentic cohort the day before — at ZERO Veo credits. With no flags and no env vars the run logged ui_driver.ui_mode.attempt_exit_agent → ui_driver.bound mode=classic ui_mode=classic and generated a real 768x1376 JPEG (exit 0); the day before, the identical command on the same account bound auto→agentic and failed. The same log independently closed #183: mode_switch_trigger and image_mode_tab, the selectors it reported as unfindable, both matched. #591 was proven against the real 500-row catalog — 0 occurrences of the string "None", 31 proper JSON nulls, over a catalog holding 119 NULL-bearing rows. #592 shows exactly one client.account_locale_cached per command. Three items are recorded as NOT verified rather than omitted: the exit-28 abort on a pinned agentic account, the #597 batch inter-prompt guard, and any fresh announcement modal — the last two because all three accounts have already acked the current changelog, so no modal can be raised until Google ships the next one.) · previous: LIVE_VERIFICATION_v0.61.0 (#539 video-model refusal + #586 image-model refusal and server-side attribution, verified 2026-08-26/27 on profile denon82, ONE Veo generation total — the video fix was proven by a zero-credit A/B against the stashed pre-fix source running on live Flow: the old code returned SELECTED for veo-lite-lp, a model Flow does not offer to this account, and for a deliberately ambiguous selector matching 3 entries; the new code refuses both with exit 18 naming what Flow offered. Model selection happens before submit, so refusals cost nothing and the A/B was free. The happy path still generates: --model omni-flash → exit 0, a real 2.2 MB ftypisom mp4, catalog recording omni_flash. Two items are recorded as NOT verified rather than omitted: three of #584's four navigation-settle sites were never exercised [no bearer refresh occurred in these runs], and #582's canary self-re-exec has its first real exercise tonight. Also falsified: #539's recorded note that the video picker uses a different trigger — the two constants are byte-identical strings, and the repeated empty menu captures were the capture's own fault.) · previous: LIVE_VERIFICATION_v0.60.0
"Was the playwright upper bound raised, and on what evidence?" → LIVE_VERIFICATION_playwright_1.61 (>=1.59.0,<1.60.0 → >=1.61.0,<1.62.0 verified 2026-08-05, 1 Imagen + 1 Veo credit — the 2026-08-03 regression that motivated the bound does NOT reproduce on 1.61.0: a live i2v drove the full chain with image_uploaded status=200 → frame_attached → generate_captured status=200 with startImage parsed, where 1.62.0 hung silently at exactly that upload step; live i2i local-ref attach passed outright [96.7s]. 1.62.0 stays excluded — never root-caused. Also found, A/B-proven pre-existing on BOTH 1.59.0 and 1.61.0: Flow dropped the duration-tab UI, so --duration is currently broken for i2v — UiSelectorDriftError fires correctly [refusing rather than silently accepting Flow's default, #288] but the selector needs re-deriving; that is why the i2v proof was driven via the CLI without --duration, and Flow's own server-side PUBLIC_ERROR_VIDEO_GENERATION_TIMED_OUT means no finished mp4 is claimed).
"Where is the reverse-engineered wire protocol for a feature?" → the *_RECON.md design docs: CHARACTER_RECON (Flow character entity protocol), IMAGE_UPSCALE_RECON (/v1/flow/upsampleImage wire). Naming convention: one <FEATURE>_RECON.md per reverse-engineered surface, kept as the durable spec after the feature ships. Pre-capture research recons: ASSET_TAGGING_RECON (@-mention asset tagging — shipped in v0.40.0, see LIVE_VERIFICATION_v0.40.0).
"What was live-verified for v0.66.1?" → LIVE_VERIFICATION_v0.66.1 — the two migrated-origin fixes, verified 2026-09-03 on profile ffroliva at ZERO credits, on BOTH sides of what was then read as a flapping rollout (superseded 2026-09-04: the handoff is a one-way per-account flag and exit 36 is non-retryable since). On a real flow.google.com load get_ui_driver raised FlowHostMigratedError in 0 ms (was ~36 s: ~8 s detect window + ~24 s crop cascade + 4 s URL settle), exit 36, retryable: true (then; false since 2026-09-04), ui_driver.migrated_host_bail logged; await_url_settled returned null in 0 ms (measured 4018 ms before); and the locale was recovered as en from html lang=en-GB where the URL gave null. The no-regression half is the stronger evidence: minutes later the same command landed on the OLD host and completed exit 0 with a real 768x1376 JPEG in 42.2 s, proving the host guard is scoped and does not short-circuit the working path. Three items recorded as NOT verified rather than omitted: driving the migrated frontend (still impossible, #639 stays open), the pt-BR recovery live (measured html lang=pt on denon82 but exercised live only on en-GB), and the en-GB→en region reduction against a locale where region is load-bearing (zh-Hans/zh-Hant) — only two locales observed.
"What was live-verified for v0.66.0?" → LIVE_VERIFICATION_v0.66.0 — #639 Flow's flow.google.com migration, verified 2026-09-03 on profile ffroliva at ZERO credits. The maintainer's own account turned out to be inside the rollout, so the fix was proven against the real migrated frontend rather than a reconstructed DOM: a read-only probe of flow.google.com/project/<id> measured i_total: 0 (independently reproducing the reporter's central measurement) and drove the production functions against the live page — flow_host_kind: "migrated", _check_logged_in: true (it was false before the fix, i.e. a valid session read as logged-out), and _mode_switch_error returning FlowHostMigratedError / exit 36 / retryable: true (then; false since 2026-09-04). What read as a flap on ONE account was its one-time switch: a credit-free image t2i minutes earlier landed on the OLD host and completed exit 0 with a real 768x1376 JPEG (ffd8ffe0, 401,939 bytes, Pillow dims matching the API claim), proving the rewritten host gate does not regress the old path. Also recorded: the migrated URL drops /fx/tools/flow entirely — it is /project/<id> — which is why a substring gate on labs.google could never match it; and the migrated composer is not control-less but exposes no data-testid, zero ligature <i>, and 13 button[aria-label] (Settings trigger, Start generation, …), recorded as recon for the follow-up WITH the caveat that aria-label is translated and therefore Tier-2 at best under the locale-invariance rule. One item is recorded as NOT verified rather than omitted: gflow driving the migrated frontend, which is out of scope and keeps #639 open. Verification also hit pre-existing #561 (401 on project.createProject), A/B'd against unmodified develop to prove it was not this change, then routed around with an existing --project.
"What was live-verified for v0.68.0?" → LIVE_VERIFICATION_v0.68.0 — gflow update against the real package managers and the real PyPI index, run from the installed gflow.exe itself. A wheel lowered to 0.60.1 was installed through uv tool and through pipx, the pin removed, and gflow update upgraded each to PyPI 0.67.0: exit 0 both times. The uv run is the one that shaped the code — uv installed the wheel and then exited 1 copying gflow.exe over the running launcher (os error 32, which can be neither overwritten nor renamed), so the command reads the venv's installed version back instead of trusting the manager's exit code and reports the stale launcher as a note. --check --json changed nothing and returned the documented keys; the piped-stderr notice printed as one line. NOT verified: plain-venv pip on Windows, macOS/Linux for any manager, a real interactive-terminal screenshot of the panel, and the first genuine banner (0.68.0 is the first release after the change).
"What was live-verified for v0.67.0?" → LIVE_VERIFICATION_v0.67.0 — the migrated flow.google.com driver, on both maintainer accounts. gflow video t2v --project <id> on the moved account under the default route: exit 0 in 49.9 s, mp4 ftyp, byte-exact with the size the backend reported, recorder row; on the unmoved Portuguese-locale account forced onto the host: exit 0 in 50.5 s — the locale-invariance proof (no text label is matched). #650 on the new host: --model veo-fast --duration 6 aborts pre-submit with exit 11 at zero credits (this cohort renders the duration row for Omni only). Three defects were found by the runs and fixed before the record (status 3 arrives before the URL record; the labs media redirect 404s for migrated ids; DETAILS[10] is the poster JPEG). NOT verified: the positive Veo 4/6/8 path (cohort-external), model selection beyond the exit-11 abort, count>1, 9:16, 360p, the kill switch live, the MCP queued path live, any backend failure status.
"What was live-verified for v0.66.3?" → LIVE_VERIFICATION_v0.66.3 — the <html lang> hydration race, with the negative result that chose the design: readyState reaches complete a full second BEFORE the attribute flips, so "wait for complete, then read" would have shipped the same bug. Component and end-to-end measurements are reported separately on purpose. NOT verified: the migrated origin (fix proven on the old host, where the race also occurs) and the 4 s bound against a cold first load.
"What was live-verified for v0.66.2?" → LIVE_VERIFICATION_v0.66.2 — the old host proven live at zero credits (exit 0, real 768x1376 JPEG, twice), the locale cache measured 7.41 s → 2.66 s, and the migrated path recorded as NOT verified because the rollout flapped back (72/72 navigations landed on labs.google). No time-to-exit-36 is claimed — this release exists because v0.66.1 reported one from the wrong entrypoint, so see also the correction block atop LIVE_VERIFICATION_v0.66.1.
"What was live-verified for v0.65.0?" → LIVE_VERIFICATION_v0.65.0 — the guard A/B (three runs, zero credits, control included); the chain/movie duration guards are validation that refuses before any transport call, so they are covered by a red state that reproduces the mid-spend crash in a test plus negative controls, and the reason they were not live-run is recorded rather than omitted.
"Does the referenceEntity guard actually run, and is it a Web Worker or a Service Worker?" → LIVE_VERIFICATION_reference_entity_guard — A/B-proven live on denon82 2026-09-02, zero credits. Control (without #618): the guard never fired and the test failed; with #618: it fired and passed. Same account, same prompt, one variable. Settles the question that held #618 — it is a dedicated Web Worker, so context.route suffices and no service_workers="block" is needed. Also confirms route.continue_(post_data=...) does not corrupt the body (both runs produced a real image). The video glob was equally dead, which #615 never mentions. Residual: direct-wire routes still bypass structurally (#619).
"What was live-verified for the data layer (PR #58)?" → LIVE_VERIFICATION_data_layer — 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
"What is the jitter matrix evidence for gflow image batch?" → LIVE_VERIFICATION_image_batch.md — jitter matrix evidence for gflow image batch (always-same-project mode)
README.mdis for first-time visitors. Keep it under ~400 lines. Anything longer belongs indocs/.- Every new behaviour or env var needs a row in this index AND a section in the relevant
docs/*.md. - Cross-link generously. Use markdown link syntax with an anchor wherever a reader might need to jump deeper — they should never get stuck.
- Keep file size sane. If
docs/USAGE.mdgrows past ~600 lines, split intodocs/USAGE/<topic>.md.