gflow-cli 0.66.2__tar.gz → 0.68.0__tar.gz

{gflow_cli-0.66.2 → gflow_cli-0.68.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gflow",
-  "version": "0.66.2",
+  "version": "0.68.0",
   "description": "Reusable development and operations workflows for gflow-cli",
   "author": {
     "name": "Flavio Oliva",

{gflow_cli-0.66.2 → gflow_cli-0.68.0}/.env.template

@@ -138,9 +138,10 @@
 # Holders always run to completion; the waiter takes over on release (#478).
 # GFLOW_CLI_LEASE_WAIT_SECONDS=0
 
-# Once-a-day best-effort PyPI check printing a one-line notice when a newer
-# gflow-cli exists (#479). Never blocks; skipped in CI and for
-# editable/source installs. Set to 0 to disable.
+# Once-a-day best-effort PyPI check that shows an update banner on stderr when
+# a newer gflow-cli exists (#479; one plain line when stderr is piped). Never
+# blocks; skipped in CI and for editable/source installs. Set to 0 to disable.
+# Upgrade with `gflow update`.
 # GFLOW_CLI_UPDATE_CHECK=1
 
 # Whether generation prompts (and the prompt-derived display names used as the
@@ -181,6 +182,14 @@
 # reached. -i instructions force agentic automatically. See docs/CONFIGURATION.md.
 # GFLOW_CLI_UI_MODE=auto
 
+# Which Flow frontend gflow drives (#639). auto (default): flow.google.com is the
+# default host for what it can serve today (video t2v with --project) on every
+# account; requests it cannot serve yet keep the labs driver on an unmoved
+# account, and a moved account gets the migrated composer for everything ported.
+# flow.google.com: force the migrated composer for everything.
+# labs.google: never use it — a moved account fails with exit 36 (kill switch).
+# GFLOW_CLI_FLOW_HOST=auto
+
 # DEPRECATED — use GFLOW_CLI_UI_MODE=classic. true maps to ui_mode=classic, but the
 # old silent agentic fallback is gone: a classic-required run now aborts (exit 28).
 # GFLOW_CLI_PREFER_CLASSIC=false

gflow_cli-0.68.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,35 @@
+## Summary
+
+<!-- What changed and why? Link issues with "Fixes #123" when applicable. -->
+
+## Lifecycle
+
+<!-- The pipeline every PR is reviewed against: CONTRIBUTING.md § "The development lifecycle"
+     and AGENTS.md § "Standard Workflow Sequence". Tick what applies; strike what does not and say why. -->
+
+- [ ] Issue triaged with `issue-assessment` (verdict + which surfaces reproduce it: CLI / MCP / both)
+- [ ] `predict` verdict recorded (transport / auth / selector / schema changes only)
+- [ ] `scenario` + `plan` written under `docs/superpowers/plans/<date>-<slug>/` and linked here
+- [ ] `check` green, including the step 1b CLI↔MCP mirror sweep
+- [ ] MCP twin added, or a reasoned exemption in `tests/mcp/test_cli_parity.py`
+- [ ] Live-verified against real Flow where a generation path changed; what could NOT be verified is stated below
+- [ ] Council review run (`pr-council-review` / `branch-review`) and must-fix items addressed
+
+## Validation
+
+<!-- List the focused commands you ran, plus any checks you could not run. -->
+
+- [ ] Focused tests added or updated for behavior changes
+- [ ] Documentation updated or explicitly marked not applicable
+- [ ] `uv run python scripts/ci/check_doc_links.py`
+- [ ] `uv run ruff check src tests`
+- [ ] `uv run pyright src`
+- [ ] Relevant pytest command:
+
+## Contribution Checklist
+
+- [ ] This PR targets `develop`, unless it is a release or emergency fix
+- [ ] My commits use my real Git identity or GitHub noreply email
+- [ ] External contribution commits include `Signed-off-by:` (`git commit -s`)
+- [ ] I did not include secrets, cookies, account tokens, signed URLs, or private captured data
+- [ ] I reviewed any AI-assisted changes before submitting

{gflow_cli-0.66.2 → gflow_cli-0.68.0}/.github/workflows/ci.yml

@@ -196,6 +196,9 @@ jobs:
       - name: Website docs mirror in sync (regenerate-and-diff)
         run: uv run python scripts/ci/generate_website_docs.py --check
 
+      - name: Council memory (every cited slug resolves, every file is cited)
+        run: uv run python scripts/ci/check_council_memory.py
+
       - name: Lint
         run: uv run ruff check src tests
 

{gflow_cli-0.66.2 → gflow_cli-0.68.0}/AGENTS.md

@@ -41,10 +41,10 @@ by construction, so Codex / Cursor / Aider / `agy` read exactly what Claude Code
 
 ## Project at a glance
 
-- Unofficial Python CLI for [Google Flow](https://labs.google/fx/tools/flow) — drives Veo (image-to-video, text-to-video) and Imagen (text-to-image) generations from the terminal by reverse-engineering Flow's private REST API at `aisandbox-pa.googleapis.com`.
+- Unofficial Python CLI for [Google Flow](https://labs.google/fx/tools/flow) — drives Veo (image-to-video, text-to-video) and Imagen (text-to-image) generations from the terminal by reverse-engineering Flow's private REST API at `aisandbox-pa.googleapis.com` — and, for accounts Google has moved to `flow.google.com`, that frontend's `batchexecute` wire (text-to-video today; `GFLOW_CLI_FLOW_HOST`).
 - Python 3.11+ · `uv`-managed · `hatchling` builds · Playwright Chromium transport · `pyright` strict · `ruff` · `pytest`.
-- Single-package modular monolith. Top-level modules under `src/gflow_cli/`: `api/`, `auth/`, `data/`, `mcp/`, `services/`, `tools/`, `ui/`, `worker/`, `browser_manager.py`, `cli.py`, `_cli_helpers.py`, `diagnostics.py`, `json_output.py`, `media.py`, `profile_lease.py`, `redaction.py`, `storage.py`, `winsec.py`, `cli_project.py`, `cli_character.py`, `cli_data.py`, `cli_image.py`, `cli_instructions.py`, `cli_models.py`, `cli_movie.py`, `cli_run.py`, `cli_scene.py`, `cli_tools.py`, `cli_video.py`, `chain.py`, `chain_manifest.py`, `cli_doctor.py`, `composition.py`, `config.py`, `errors.py`, `file_integrity.py`, `flow_selectors/`, `update_check.py`, `exceptions.py`, `image_batch.py`, `movie_manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
-- Command surface: `gflow auth`, `gflow image` (t2i/i2i/batch/upload/upscale), `gflow video` (t2v/i2v/r2v/chain/extend — `extend` continues an existing clip past Flow's 8s ceiling, server-seeded from the source so the join is continuous; no `batch` subcommand; the nonfunctional stub was removed, loop `gflow video t2v`/`i2v` from the shell for multi-clip runs), `gflow character` (create/list/show/rm/voices — reusable project-scoped Flow Character entities), `gflow scene` (create/show — Add Clip / Scenes, with `create --output` for credit-free server-side extended video), `gflow instructions` (persistent Agent-Mode brief cards — add/list/enable/disable/rm/apply/toggle-mode, credits-free, `--project` required), `gflow movie` (run/template — multi-scene manifest pipeline), `gflow tools` (list/show/run — prompt-rewriting tools, also `--tool` on generation commands), `gflow data` (catalog queries), `gflow doctor` (read-only pre-flight diagnostic, exit 33 = findings present), `gflow project`, `gflow models`, `gflow run`, `gflow mcp` (run/setup — stdio MCP server), and `gflow serve` (Streamable HTTP at `/mcp`; `--transport sse` is deprecated).
+- Single-package modular monolith. Top-level modules under `src/gflow_cli/`: `api/`, `auth/`, `data/`, `mcp/`, `services/`, `tools/`, `ui/`, `worker/`, `browser_manager.py`, `cli.py`, `_cli_helpers.py`, `diagnostics.py`, `json_output.py`, `media.py`, `profile_lease.py`, `redaction.py`, `storage.py`, `winsec.py`, `cli_project.py`, `cli_character.py`, `cli_data.py`, `cli_image.py`, `cli_instructions.py`, `cli_models.py`, `cli_movie.py`, `cli_run.py`, `cli_scene.py`, `cli_tools.py`, `cli_video.py`, `chain.py`, `chain_manifest.py`, `cli_doctor.py`, `cli_update.py`, `composition.py`, `config.py`, `errors.py`, `file_integrity.py`, `flow_selectors/`, `update_check.py`, `exceptions.py`, `image_batch.py`, `movie_manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
+- Command surface: `gflow auth`, `gflow image` (t2i/i2i/batch/upload/upscale), `gflow video` (t2v/i2v/r2v/chain/extend — `extend` continues an existing clip past Flow's 8s ceiling, server-seeded from the source so the join is continuous; no `batch` subcommand; the nonfunctional stub was removed, loop `gflow video t2v`/`i2v` from the shell for multi-clip runs), `gflow character` (create/list/show/rm/voices — reusable project-scoped Flow Character entities), `gflow scene` (create/show — Add Clip / Scenes, with `create --output` for credit-free server-side extended video), `gflow instructions` (persistent Agent-Mode brief cards — add/list/enable/disable/rm/apply/toggle-mode, credits-free, `--project` required), `gflow movie` (run/template — multi-scene manifest pipeline), `gflow tools` (list/show/run — prompt-rewriting tools, also `--tool` on generation commands), `gflow data` (catalog queries), `gflow doctor` (read-only pre-flight diagnostic, exit 33 = findings present), `gflow update` (self-update through the installer that put it here — uv tool / pipx / pip; `--check` only reports; source installs refused, exit 11; deliberately no MCP twin), `gflow project`, `gflow models`, `gflow run`, `gflow mcp` (run/setup — stdio MCP server), and `gflow serve` (Streamable HTTP at `/mcp`; `--transport sse` is deprecated).
 - Works with any Google account that has Flow access. All generations bill against the user's own Google account.
 
 ## Headed-browser dependency (architectural reality)
@@ -76,6 +76,7 @@ uv run python scripts/ci/check_repo_hygiene.py
 uv run python scripts/ci/check_doc_links.py
 uv run python scripts/ci/check_website_docs_pii.py
 uv run python scripts/ci/generate_website_docs.py --check
+uv run python scripts/ci/check_council_memory.py
 uv run ruff check src tests
 uv run ruff format --check src tests
 uv run pyright src
@@ -101,7 +102,7 @@ the five other mirror axes), which no command here can check and no CI gate can
 
 - Type hints everywhere; `pyright` strict on `src/gflow_cli`.
 - Structured logging only (`structlog`) — **never** raw `print()` or `import logging` in `src/`.
-- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–35, e.g. 11 is `ConfigurationError` — including `ProfileLockedError` for same-profile lease contention, 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`, 25 `FlowAgentUiError`, 28 `UiModeUnavailableError`, 29 `MentionIndexUnavailableError`, 30 `QueueSchemaError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping. Exit 33 is reserved outside that map: `gflow doctor` findings-present — a successful diagnosis, not an error class.
+- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–36, e.g. 11 is `ConfigurationError` — including `ProfileLockedError` for same-profile lease contention, 16 is the `DataStoreError` family, 19 `SceneConcatError`, 20 `FrameExtractionError`, 21 `ChainPartialError`, 22 `UpscaleUnavailableError`, 25 `FlowAgentUiError`, 28 `UiModeUnavailableError`, 29 `MentionIndexUnavailableError`, 30 `QueueSchemaError`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping. Exit 33 is reserved outside that map: `gflow doctor` findings-present — a successful diagnosis, not an error class.
 - 100-char line length, `ruff` configured. Imports sorted by `ruff` (isort rules).
 - **YAGNI / least-code**: prefer the smallest change that works. No speculative abstractions (interface/factory with one implementation), no config or flags nobody sets, no dead constants/helpers, no reinventing the stdlib. Review carries this as its own lens — the **D14 over-engineering** dimension of [`pr-council-review`](skills/pr-council-review/SKILL.md) (baseline, always runs). Its rubric is portable; the `ponytail` plugin (see CONTRIBUTING) is an optional accelerant, not a dependency.
 - **MCP & CLI Schema Symmetry**: Any updates or additions to user-facing CLI command parameters (e.g., `gflow image t2i`, `gflow video`) must be mirrored in the corresponding MCP tool definitions. Never add option/argument fields to Click commands without updating the MCP server implementation. This symmetry is enforced programmatically in CI via `tests/mcp/test_cli_parity.py` (every CLI leaf command needs a mapped MCP tool or an explicit, reasoned exemption) plus the schema checks in `tests/mcp/test_server.py`.

{gflow_cli-0.66.2 → gflow_cli-0.68.0}/CHANGELOG.md

@@ -7,10 +7,160 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.68.0] — 2026-09-05
+
+### Added
+
+- **`gflow update` — self-update in place.** Runs the package manager that
+  installed gflow-cli, read off the install itself rather than guessed from
+  `PATH`: `uv-receipt.toml` in the venv root → `uv tool upgrade gflow-cli`,
+  `pipx_metadata.json` → `pipx upgrade gflow-cli`, otherwise that venv's own
+  `python -m pip install --upgrade gflow-cli`. Asks PyPI first and runs nothing
+  when already current; if PyPI is unreachable the manager still runs. After an
+  upgrade it re-reads the venv's Playwright version and prints the
+  `playwright install chromium` hint only when it moved. `--check` reports
+  installed vs latest plus the command that would run; `--json` returns the
+  same as a document. The outcome is verified against the venv, not the
+  manager's exit code: on Windows the running `gflow.exe` launcher holds its
+  own file open, so `uv tool upgrade` installs the new wheel and then exits 1
+  copying the launcher — measured — and that is reported as an upgrade with a
+  note, because the launcher only points at the venv's python and keeps
+  working. Editable / local / VCS / source installs, a manager binary missing
+  from `PATH`, a `uv venv` with no `pip` module, and a manager run that leaves
+  the version unchanged all surface as `ConfigurationError` (exit 11) — except
+  the one honest no-op: PyPI unreachable, manager exit 0, nothing changed, which
+  is exit 0. Deliberately no MCP twin (a server must not replace its own code under a live
+  session) — recorded as a reasoned exemption in the parity test.
+
+### Changed
+
+- **The once-a-day update notice (#479) is now a banner.** On a terminal it is
+  a bordered panel on stderr naming the new version, `gflow update`, and the
+  release-notes link; when stderr is piped it stays one plain yellow line so
+  logs and `2>&1 | jq` pipelines see one line per event. Same cache, same
+  gates (`GFLOW_CLI_UPDATE_CHECK=0`, CI, non-index installs). The notice text
+  points at `gflow update` instead of listing three manager commands.
+- **CONTRIBUTING.md now routes contributors — and their coding agents — through the
+  same lifecycle AGENTS.md defines.** A phase → skill → artifact table (issue
+  assessment, predict, scenario/plan, check with the step 1b mirror sweep,
+  live-verify, council review, sonar, known-issues) says what a PR is expected to
+  have gone through and what it leaves behind for the reviewer; the PR template
+  gains a matching *Lifecycle* checklist; the quality-gate list is now identical to
+  AGENTS.md's (it had drifted to six of nine commands).
+
+### Fixed
+
+- **Migrated host: `video t2v` no longer fails on the submit-enable race (#670,
+  @ChandraLiuswanto).** The Angular composer on `flow.google.com` flips the
+  `arrow_forward` button from `disabled` roughly 100 ms after `insert_text`
+  lands, and the composer read it synchronously, so a fully migrated account got
+  `UiSelectorDriftError` ("missing or disabled after the prompt was typed",
+  exit 23) on every run before anything was submitted. The composer now waits
+  up to 5 s (100 ms polls) for the button to enable; a button that never
+  enables is still selector drift, now worded as "stayed disabled for 5s".
+  Measured on a moved account: `insert_text` → enabled at the 107 ms sample;
+  with the wait, veo-lite t2v completed in 62 s.
+
+## [0.67.0] — 2026-09-05
+
+### Added
+
+- **Text-to-video on Flow's migrated `flow.google.com` host** (#639). An account
+  Google has moved off labs.google no longer exits 36 on `gflow video t2v`: the new
+  migrated composer drives the Angular editor (option-group radios, model menu,
+  `contenteditable` composer, `arrow_forward` submit) and then *observes* the app's
+  own `batchexecute` replies — `YhhmEf` submit, `jwpduf` status, `as29s` result —
+  before downloading the clip. Under the default
+  `GFLOW_CLI_FLOW_HOST=auto`, flow.google.com is now the **default host for every
+  request it can serve** — t2v with `--project`, on moved and unmoved accounts
+  alike (the new host serves both); what it cannot serve yet keeps the labs
+  driver on an unmoved account. `flow.google.com` forces it for everything,
+  `labs.google` is the kill switch. `--project` is required on
+  that host for now; everything except t2v still exits 36 there. Recon with two
+  real generations: `docs/superpowers/spikes/2026-09-05-migrated-host-wire-protocol.md`.
+
+### Changed
+
+- **Exit 36 (`FlowHostMigratedError`) is no longer retryable** (#639). Two $0 spikes
+  settled the mechanism: labs.google serves a normal 200 to a fully authenticated
+  session, then the app itself runs `location.replace('https://flow.google.com' +
+  path)` from a `useEffect`, gated on a server-assigned per-account config boolean.
+  It is a one-way rollout — 5/5 and 7/7 on a flagged account — not the per-page-load
+  flap the error text claimed, so once an account is flagged a retry never lands the
+  old frontend. The remediation, the `_mode_switch_error` fallback, `docs/USAGE.md`,
+  `docs/MCP.md`, `KNOWN_ISSUES.md` and `docs/PROJECT_STATUS.md` no longer invite a
+  retry, and the MCP, worker and `--json` envelopes carry `retryable: false`.
+  Detection is unchanged from v0.66.2: Playwright updates `page.url` in the same
+  tick it emits the hop's `framenavigated`, so re-checking it wherever the run is
+  about to spend time — the shape the reporter measured at 4.1 s — was already right
+  (maintainer A/B on the same machine and profile: 16.0 s vs 16.6 s on unmodified
+  `develop`, Chrome launch included).
+
+- **`--duration` now accepts 4s/6s/8s on the Veo 3.1 models** (#650, @stgmt); `10`
+  stays `omni-flash`-only. Flow's duration control turns out to be account/cohort-
+  dependent — some accounts render the row for Veo, some render none, on the same
+  frontend — so the static table that refused it everywhere was wrong for part of
+  the userbase. `supports_duration()` is gone; one shared
+  `validate_duration_for_model()` now backs the DTO, CLI, chain, movie manifest and
+  MCP surfaces. On an account **without** the control the run now reaches the browser
+  and aborts pre-submit with no credits spent — exit 23 on the labs driver, exit 11
+  on the migrated `flow.google.com` host, where the maintainer cohort renders the
+  duration row for Omni 1.1 Flash only (measured 2026-09-05) — instead of refusing
+  instantly at the CLI edge — a deliberate trade, since a static per-model table
+  cannot express a per-account capability.
+
+### Fixed
+
+- **`--model` on the migrated host selected the model and then lost the settings pane**
+  (#665). After the model menu — a second overlay — opened and closed, the driver
+  resolved `.cdk-overlay-pane.last` to the detached menu pane, so every axis after the
+  switch read "0 option groups". The pane is now the overlay that contains the option
+  groups; a regression test keeps a stale menu pane as the last overlay.
+- **MCP `gflow_generate_video` accepted any `duration` when `model` was omitted**
+  (#659): `duration=99` queued and burned a browser run. The tool now validates the
+  value against the supported set regardless of model, like the CLI's choice list.
+
+## [0.66.3] — 2026-09-03
+
+### Fixed
+
+- **`<html lang>` was read before the app set it, so every account whose URL could not answer
+  resolved to `en` ([#651](https://github.com/ffroliva/gflow-cli/issues/651)).** Flow serves an
+  **`en` shell** and rewrites `lang` during hydration. The single early read added by
+  [#643](https://github.com/ffroliva/gflow-cli/issues/643) therefore returned the shell value —
+  and the accounts it hit are exactly the ones #643 was written for: those where the URL carries
+  no locale segment. Reported by
+  [@maipmacrothorax-75](https://github.com/maipmacrothorax-75) on a pt-BR account resolving `en`
+  while both pages served `<html lang="pt">`, with the mechanism offered explicitly as a guess.
+
+  The guess is confirmed, and it reproduces on the **old** host — so this was never a migration
+  bug. Measured on a pt account, two consecutive loads:
+
+  | t (ms) | `lang` | `readyState` |
+  |---|---|---|
+  | 887 | `en` | interactive |
+  | **1510** | `en` | **complete** |
+  | 2092 | `en` | complete |
+  | **2488** | **`pt`** | complete |
+
+  **`readyState` is not a usable signal** — it reaches `complete` a full second *before* the
+  flip, so the obvious "wait for complete, then read" would have shipped the same bug with more
+  code. The DOM node count oscillates (136 → 300 → 249 → 251) and does not discriminate either.
+  Nothing cheap predicts the flip, so `_resolve_account_locale` now **observes** it: read once,
+  bounded-wait for the value to change, re-read.
+
+  A timeout is an **answer**, not a failure — either the account's locale genuinely equals the
+  shell default, or the page never hydrated in the window. Both leave the first read as the best
+  available answer, which is exactly the previous behaviour, so the branch can never be worse
+  than what it replaces. It is logged as `client.account_locale_lang_unchanged` so the field can
+  tell the two apart. Cost: an account whose locale **is** the shell default pays the 4 s bound
+  once per process.
+
 ## [0.66.2] — 2026-09-03
 
 ### Fixed
 
+
 - **v0.66.1's migrated-origin fast-fail never fired on a real run
   ([#639](https://github.com/ffroliva/gflow-cli/issues/639)).** The guard read `page.url` once,
   at `get_ui_driver` entry — but `routes.project_editor_url` only ever builds a `labs.google`
@@ -3784,7 +3934,10 @@ 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.66.2...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.68.0...HEAD
+[0.68.0]: https://github.com/ffroliva/gflow-cli/compare/v0.67.0...v0.68.0
+[0.67.0]: https://github.com/ffroliva/gflow-cli/compare/v0.66.3...v0.67.0
+[0.66.3]: https://github.com/ffroliva/gflow-cli/compare/v0.66.2...v0.66.3
 [0.66.2]: https://github.com/ffroliva/gflow-cli/compare/v0.66.1...v0.66.2
 [0.66.1]: https://github.com/ffroliva/gflow-cli/compare/v0.66.0...v0.66.1
 [0.66.0]: https://github.com/ffroliva/gflow-cli/compare/v0.65.0...v0.66.0

{gflow_cli-0.66.2 → gflow_cli-0.68.0}/CLAUDE.md

@@ -27,7 +27,7 @@ it yet" is not a reachable state.
 ## On every session start
 
 1. Read **[docs/INDEX.md](docs/INDEX.md)** — routing layer for all project docs and
-   commands. Deliberately *not* imported: at 36 KB it is a lookup table, not a rule set,
+   commands. Deliberately *not* imported: at ~47 KB it is a lookup table, not a rule set,
    and AGENTS.md points into it. Read it when you need to find a doc.
 2. Pull deeper context on demand:
    - Current task / where we left off → `/gflow:status`

{gflow_cli-0.66.2 → gflow_cli-0.68.0}/CONTRIBUTING.md

@@ -2,6 +2,46 @@
 
 Thanks for considering a contribution! The repo is public and PRs are welcome. Pre-1.0 means APIs may shift between minor versions; check [PLAN.md](PLAN.md) for the active phase before starting a non-trivial change.
 
+## The development lifecycle — how a PR gets in without back-and-forth
+
+This project is developed through a fixed pipeline, and every PR is reviewed against it.
+The pipeline is written down once, in [AGENTS.md](AGENTS.md) — the **Skill Routing**
+table (which skill to load for which situation) and the **Standard Workflow Sequence**
+(the ten phases, their artifacts, and the gates between them). The skills themselves are
+plain Markdown under [`skills/<name>/SKILL.md`](skills/): agent-agnostic by design, so
+Claude Code (`/gflow:<name>`), Codex (`$gflow:<name>`), Cursor, Aider, Antigravity, or a
+human reading the file all follow the same protocol.
+
+**If you use a coding agent, point it at [AGENTS.md](AGENTS.md) first.** Most tools
+auto-discover it; if yours does not, paste the Skill Routing table into its context. A PR
+whose agent skipped the pipeline is the single biggest source of review churn here.
+
+What a contributor PR is expected to have gone through, phase by phase:
+
+| Phase | Skill (`skills/<name>/SKILL.md`) | What it leaves behind for the reviewer |
+|---|---|---|
+| Touching a GitHub issue | [`issue-assessment`](skills/issue-assessment/SKILL.md) | A verdict (CONFIRMED / LIKELY / NEEDS-INFO …) and which surfaces reproduce it — CLI, MCP, or both |
+| Transport / auth / selector / schema change | [`predict`](skills/predict/SKILL.md) | A GO / CAUTION / STOP verdict **before** code exists; STOP means open an issue instead |
+| Any feature | [`scenario`](skills/scenario/SKILL.md) → [`plan`](skills/plan/SKILL.md) | `docs/superpowers/plans/<date>-<slug>/SCENARIO.md` + `PLAN.md` — the edge-case table and the task list; link them from the PR (they live on the branch and in the PR's history; at release the durable facts are folded into `docs/superpowers/memory/` and the plan dir is removed) |
+| Every commit | [`check`](skills/check/SKILL.md) | The Impeccable Routine green (it is the exact CI gate), plus the **step 1b** CLI↔MCP mirror sweep no CI gate can see |
+| Anything on a generation path | [`live-verify`](skills/live-verify/SKILL.md) | Evidence against real Flow, not just green offline tests — this project drives a black box; say plainly what you could **not** verify |
+| Opening the PR | [`pr-council-review`](skills/pr-council-review/SKILL.md) / [`branch-review`](.claude/commands/gflow/branch-review.md) | The multi-dimension council (correctness, quality, security, tests, memory, YAGNI, parity …); maintainers run it on every PR, so running it yourself first removes a round trip |
+| Red SonarCloud check | [`sonar`](skills/sonar/SKILL.md) | Zero new issues — the gate measures *new* code |
+| Auth or reCAPTCHA | [`known-issues`](skills/known-issues/SKILL.md) | Known-broken surfaces have documented workarounds; rediscovering them costs days |
+
+Three rules the pipeline enforces that catch first-time contributors most often:
+
+1. **Ship each capability twice, or say why not.** Every CLI command has an MCP twin or a
+   reasoned exemption in `tests/mcp/test_cli_parity.py` — and options, payload keys and tool
+   docstrings must stay mirrored (AGENTS.md § *MCP & CLI Schema Symmetry*).
+2. **Locale-invariant selectors only.** No `has-text(...)` on Flow's DOM, ever
+   (AGENTS.md § *Locale-Invariance Discipline*).
+3. **Verified beats claimed.** If a fix cannot be verified on the affected surface in your
+   environment, the PR says so and uses `Refs #N`, not a green checkbox.
+
+The PR template's *Lifecycle* checklist mirrors this table. Tick what applies, strike what
+does not, and say why — a reviewer can then start from your evidence instead of re-deriving it.
+
 ## Development setup
 
 ```bash
@@ -96,16 +136,24 @@ cost table, and run commands.
 
 ## Quality gates (run before commit)
 
+Prefer the skill — [`skills/check/SKILL.md`](skills/check/SKILL.md) (`/gflow:check` in
+Claude Code, `$gflow:check` in Codex) — because it also carries the step 1b CLI↔MCP mirror
+sweep that no command below can check. The mechanical subset it runs, in order:
+
 ```bash
-uv run python scripts/ci/check_repo_hygiene.py  # artefact + path hygiene
-uv run python scripts/ci/check_doc_links.py     # internal Markdown links
+uv run python scripts/ci/check_repo_hygiene.py        # artefact + path hygiene
+uv run python scripts/ci/check_doc_links.py           # internal Markdown links
+uv run python scripts/ci/check_website_docs_pii.py    # no private identifiers in website/docs
+uv run python scripts/ci/generate_website_docs.py --check  # website mirror in sync
+uv run python scripts/ci/check_council_memory.py      # council memory slugs resolve both ways
 uv run ruff check src tests          # lint
-uv run ruff format src tests         # auto-format
+uv run ruff format --check src tests # formatting
 uv run pyright src                   # type-check (strict on src/gflow_cli/)
 uv run pytest -q --cov=gflow_cli      # tests + coverage
 ```
 
-CI runs all six on every push. Documentation is part of the merge gate: update
+CI runs all of them on every push (this list is kept identical to AGENTS.md's; a shorter
+copy once shipped a stale website mirror to a green local run and a red CI). Documentation is part of the merge gate: update
 the relevant docs for behavior, workflow, configuration, architecture, or
 operator-facing changes. If no documentation change is needed, state that in
 the PR validation checklist.

{gflow_cli-0.66.2 → gflow_cli-0.68.0}/KNOWN_ISSUES.md

@@ -14,9 +14,9 @@ Living list of behaviour that's broken, surprising, or limited by design — alo
 
 ## Open
 
-### Flow is migrating to `flow.google.com`; the migrated frontend is not drivable
+### Flow is migrating to `flow.google.com`; gflow drives the migrated frontend for t2v (rest of the matrix pending)
 
-- **Status:** Open · **Severity:** High (every generation command fails on a migrated page load) · **Affected:** all `gflow image` / `gflow video` generation, CLI and MCP alike, on accounts the rollout has reached
+- **Status:** Open (partially resolved) · **Severity:** High for everything except text-to-video · **Affected:** on accounts the rollout has reached, `gflow video t2v` now runs on the migrated host (with `--project`); `image`, i2v/r2v, characters, scenes, extend, instructions and tools are not ported yet and still exit 36
 - **Tracked:** [#639](https://github.com/ffroliva/gflow-cli/issues/639) · Reported 2026-09-02 against 0.59.0, 0.62.1, 0.63.0 and 0.65.0
 - **Confirmed live 2026-09-03 on a second, independent account** (`ffroliva`) — see [LIVE_VERIFICATION_v0.66.0](docs/LIVE_VERIFICATION_v0.66.0.md). A read-only probe of the migrated origin measured `i_total: 0`, reproducing the reporter's central measurement.
 
@@ -27,9 +27,10 @@ contains **zero `<i>` elements**. Every gflow selector anchors on Material
 Symbols ligatures (`i.google-symbols:text-is(...)`), so cohort detection and
 every mode control miss at once.
 
-**The rollout flaps per page load.** The same account, profile and project land
-on the old host on one navigation and the migrated one on the next, minutes
-apart, with no client change. Measured on one account ~35 minutes apart:
+**v0.66.0 read the rollout as flapping per page load** — the same account, profile
+and project landing on the old host on one navigation and the migrated one on the
+next, minutes apart. Those two captures straddled the account's one-time switch
+(see the 2026-09-04 note under Workaround). Measured on one account ~35 minutes apart:
 
 ```
 old host       labs.google/fx/<locale>/tools/flow/...   i=55  i.google-symbols=49  crop_* present   -> exit 0
@@ -44,19 +45,35 @@ This is **not** selector rot, not [#493](https://github.com/ffroliva/gflow-cli/i
 and not the agentic cohort — the agentic indicators are absent too. It is a
 different origin serving different markup.
 
-**Workaround:** re-run the command. While the rollout flaps, a fresh navigation
-frequently lands the old frontend and the run completes normally. Automated
-callers get this for free: the failure is `FlowHostMigratedError` (exit 36) with
-`retryable: true`, so retry loops driven by the `--json` / MCP / worker error
-envelope will keep trying.
-
-**What gflow does today (v0.66.2):** recognises the migrated origin and fails
-with the distinct, retryable exit 36 instead of the misleading
+**What works now — text-to-video on the migrated host.** `gflow video t2v … --project <id>`
+drives the migrated editor directly (settings through its option groups, prompt,
+submit, then it observes the app's own `batchexecute` status replies and downloads
+the clip). Two real clips were generated this way on 2026-09-05 — spike
+`docs/superpowers/spikes/2026-09-05-migrated-host-wire-protocol.md`. Routing
+(`GFLOW_CLI_FLOW_HOST=auto`): flow.google.com is the **default** host for that
+command on every account — moved or not; `flow.google.com` forces it for
+everything, and `labs.google` switches the migrated composer off. Limits today: `--project` is required (project creation from the
+migrated editor is not ported), and only `t2v` — everything else still exits 36.
+
+**Workaround for the rest:** none client-side. The handoff
+is a per-account setting the labs.google app applies on every load (measured
+5/5 and 7/7 with no flap, 2026-09-04 — spike
+`docs/superpowers/spikes/2026-09-04-migrated-host-handoff-mechanism.md`), so
+once the account is flagged, re-running will not land the old frontend. Earlier text here said the rollout
+"flaps" and told you to retry; that observation straddled the account's one-time
+switch and is withdrawn. The REST surface (`gflow project list`, `gflow data …`)
+is unaffected. Automated callers now receive `retryable: false` so retry loops
+stop instead of burning a doomed attempt each time.
+
+**What gflow does today for the rest of the matrix:** recognises the migrated
+origin — `page.url` is re-checked at every point the run is about to spend time,
+which Playwright updates in the same tick as the hand-off navigation — and fails
+with the distinct, non-retryable exit 36 instead of the misleading
 `UiSelectorDriftError` (exit 23, "file a selector bug"). `_check_logged_in` also
 accepts the migrated host, so a migrated load is no longer misread as a
-logged-out session. **Support for driving the new frontend is separate work and
-is not implemented** — once the rollout completes for an account, no retry will
-help until then.
+logged-out session. Text-to-video is driven (above); image, i2v/r2v, characters,
+scenes, extend, instructions, tools and project creation are the remaining work
+tracked here — no retry helps for those until each is ported.
 
 > **v0.66.1's fast-fail did not fire in the field, and v0.66.2 is the correction.**
 > The guard read `page.url` once, at `get_ui_driver` entry — before the hop to
@@ -267,31 +284,59 @@ listing endpoint (privacy-gated to `store` history mode), and `gflow doctor`
 (#542) surfaces the affected-row count. Freshly generated rows whose caption
 has not landed yet stay nameless until the next sync sweep.
 
-### Video duration tab probe misses on the current Frames-submode DOM
-
-- **Status:** Open ([#288](https://github.com/ffroliva/gflow-cli/issues/288))
-- **Severity:** Medium · **Affected:** `gflow video` with an explicit `--duration`
-  on at least some Classic-profile cohorts (3/3 miss on a live 2026-07-11 run)
-
-The `duration_tab` selector cascade (`[role='tab']:text-is('4s')` /
-`:has-text('4s')`) fails to match on Flow's current Frames-submode settings
-panel. Pre-fix this silently produced a clip of Flow's default length; since
-the #289 fix the run fails fast with `UiSelectorDriftError` (exit 23) and a
-`debug_no_duration_tab.png` screenshot — live-verified 2026-07-11 on the
-denon82 profile (aborted pre-submit, saving the 10-credit generation).
-**Workaround:** omit `--duration` to accept Flow's default.
+### Video duration control is absent on some account cohorts
+
+- **Status:** Mitigated — fail-fast shipped in
+  [#289](https://github.com/ffroliva/gflow-cli/pull/289).
+  [#288](https://github.com/ffroliva/gflow-cli/issues/288) and
+  [#451](https://github.com/ffroliva/gflow-cli/issues/451) are closed; the
+  Flow-side behaviour is unresolved and untracked upstream. gflow's own static
+  gate was relaxed in [#650](https://github.com/ffroliva/gflow-cli/pull/650).
+- **Severity:** Medium · **Affected:** `gflow video` with an explicit
+  `--duration` (3/3 miss on a live 2026-07-11 run; re-confirmed by a $0
+  capability capture 2026-09-03)
+
+**Workaround:** omit `--duration` and accept Flow's default clip length.
+
+**What actually happens today.** gflow accepts `--duration 4`, `6` or `8` on the
+Veo 3.1 models and `10` on `omni-flash` only — the CLI no longer refuses a
+duration it cannot know your account supports. What it still cannot do is tell
+your cohort apart before opening the browser, so on an account that renders no
+duration row the run reaches Flow's settings popover and fails there — on the
+labs driver as `UiSelectorDriftError` (exit 23) with a `debug_no_duration_tab.png`
+screenshot, on the migrated `flow.google.com` host as `ConfigurationError` (exit 11)
+naming the duration axis (the maintainer cohort renders the row for Omni 1.1 Flash
+only there, measured 2026-09-05).
+That abort is **pre-submit**, so no credits are spent — live-verified 2026-07-11
+on the denon82 profile.
 
 **Root cause (confirmed live 2026-07-11, screenshot evidence on #288): the
 duration control is ABSENT from this cohort's settings popover** — the panel
 renders mode tabs (Imagem/Video), sub-mode (Frames/Elementos), aspect
 (9:16/16:9), count (1x–x4; labels renamed to xN since — see #404), and the
-model dropdown (Veo 3.1 - Lite), and
-nothing else. The earlier locale hypothesis is refuted: the UI renders in
-Portuguese and the sibling count tabs (`1x`/`x2`) match fine; there is simply
-no duration row to click. Whether Flow removed clip-length selection for this
-cohort/model or moved it elsewhere is unknown — until that's answered,
-`--duration` cannot be honored on affected cohorts and the fail-fast is the
-correct behavior, not a selector bug to patch.
+model dropdown (Veo 3.1 - Lite), and nothing else. The earlier locale hypothesis
+is refuted: the UI renders in Portuguese and the sibling count tabs (`1x`/`x2`)
+match fine; there is simply no duration row to click.
+
+**Updated 2026-09-04 — it is a cohort difference, not a removal.** A third
+profile on the *same* `labs.google` frontend renders `4s/6s/8s` on all three
+selectable Veo 3.1 models, at different credit prices, in a credit-free capture
+whose count tabs came back on every model. (`veo_3_1_lite_lower_priority` missed
+its picker, so it is unmeasured either way.) Some accounts have the control, some
+do not; the cohort key — region, account age, experiment bucket — is unknown.
+
+Because the gate is a static per-model table rather than a read of your session,
+gflow cannot express that difference: it now allows `4/6/8` on every Veo 3.1
+model, and an account without the control discovers this in the browser rather
+than at the CLI edge. Trading an instant, wrong rejection for a slower, correct
+attempt was the deliberate call in #650. A session-level capability probe would
+remove the trade entirely and nobody has written one.
+
+**Reporting.** If Flow's UI shows a duration row for a Veo model on your account,
+that is useful — it narrows the cohort key. Attach the exact `--model` /
+`--duration` invocation and the error text; a `--model omni-flash` run
+additionally yields the probe name and `debug_no_duration_tab.png`. No tokens or
+signed URLs.
 
 ### macOS: generation runs logged-out → HTTP 401, even with `--browser chrome`
 

{gflow_cli-0.66.2 → gflow_cli-0.68.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gflow-cli
-Version: 0.66.2
+Version: 0.68.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
@@ -112,6 +112,7 @@ Same Veo and Imagen models, same quality, same billing against your own Google a
 # 1 · Install (uv recommended; also: pip install gflow-cli)
 uv tool install gflow-cli
 uv tool run --from gflow-cli playwright install chromium     # one-time, ~150 MB
+# later: `gflow update` upgrades in place (every command shows a banner when a newer release is out)
 
 # 2 · Authenticate (one-time, opens a real Chrome window)
 gflow auth login --browser chrome
@@ -194,6 +195,8 @@ gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (te
 
 **Current transport:** `ui_automation` drives Flow through a persistent Playwright Chromium profile. It is production-stable and verified end-to-end every release (see the per-release `LIVE_VERIFICATION_*` evidence files).
 
+**Two Flow frontends:** Google is moving accounts from `labs.google` onto `flow.google.com` ([#639](https://github.com/ffroliva/gflow-cli/issues/639)) — same product, different widget toolkit and wire protocol (`batchexecute` instead of `aisandbox-pa`). `flow.google.com` is the default host for what gflow has ported to it — text-to-video today — on every account; the rest of the matrix keeps the labs driver until ported (`GFLOW_CLI_FLOW_HOST`, see [CONFIGURATION](docs/CONFIGURATION.md#gflow_cli_flow_host)).
+
 **What's blocked:** a pure HTTP transport for video generation. The video upload endpoint returns HTTP 401 under non-Chrome browsers plus a reCAPTCHA mint we cannot reproduce headlessly. Three earlier HTTP strategies (`evaluate_fetch`, `bearer`, `sapisidhash`) live under `src/gflow_cli/api/transports/experimental/` for research, off the production path.
 
 **How you can help:** if you have driven `aisandbox-pa.googleapis.com` from outside a real Chrome session, or you understand Google's anti-bot stack here, please open an issue. A working REST transport would unlock serverless deployments, true horizontal concurrency, and roughly 10x the project's reach. Details: [docs/ARCHITECTURE.md § Headed-browser dependency](docs/ARCHITECTURE.md#headed-browser-dependency--current-limitation).

{gflow_cli-0.66.2 → gflow_cli-0.68.0}/README.md

@@ -41,6 +41,7 @@ Same Veo and Imagen models, same quality, same billing against your own Google a
 # 1 · Install (uv recommended; also: pip install gflow-cli)
 uv tool install gflow-cli
 uv tool run --from gflow-cli playwright install chromium     # one-time, ~150 MB
+# later: `gflow update` upgrades in place (every command shows a banner when a newer release is out)
 
 # 2 · Authenticate (one-time, opens a real Chrome window)
 gflow auth login --browser chrome
@@ -123,6 +124,8 @@ gflow CLI  →  Provider (interchangeable)  →  Flow (ui_automation) / Mock (te
 
 **Current transport:** `ui_automation` drives Flow through a persistent Playwright Chromium profile. It is production-stable and verified end-to-end every release (see the per-release `LIVE_VERIFICATION_*` evidence files).
 
+**Two Flow frontends:** Google is moving accounts from `labs.google` onto `flow.google.com` ([#639](https://github.com/ffroliva/gflow-cli/issues/639)) — same product, different widget toolkit and wire protocol (`batchexecute` instead of `aisandbox-pa`). `flow.google.com` is the default host for what gflow has ported to it — text-to-video today — on every account; the rest of the matrix keeps the labs driver until ported (`GFLOW_CLI_FLOW_HOST`, see [CONFIGURATION](docs/CONFIGURATION.md#gflow_cli_flow_host)).
+
 **What's blocked:** a pure HTTP transport for video generation. The video upload endpoint returns HTTP 401 under non-Chrome browsers plus a reCAPTCHA mint we cannot reproduce headlessly. Three earlier HTTP strategies (`evaluate_fetch`, `bearer`, `sapisidhash`) live under `src/gflow_cli/api/transports/experimental/` for research, off the production path.
 
 **How you can help:** if you have driven `aisandbox-pa.googleapis.com` from outside a real Chrome session, or you understand Google's anti-bot stack here, please open an issue. A working REST transport would unlock serverless deployments, true horizontal concurrency, and roughly 10x the project's reach. Details: [docs/ARCHITECTURE.md § Headed-browser dependency](docs/ARCHITECTURE.md#headed-browser-dependency--current-limitation).

{gflow_cli-0.66.2 → gflow_cli-0.68.0}/RELEASE.md

@@ -60,9 +60,13 @@ python -m pip install --pre gflow-cli
    git branch --show-current
    git rev-list HEAD..origin/main
    ```
-3. Run quality gates:
+3. Run quality gates (`/gflow:check` — the same nine commands AGENTS.md lists):
    ```bash
    uv run python scripts/ci/check_repo_hygiene.py
+   uv run python scripts/ci/check_doc_links.py
+   uv run python scripts/ci/check_website_docs_pii.py
+   uv run python scripts/ci/generate_website_docs.py --check
+   uv run python scripts/ci/check_council_memory.py
    uv run ruff check src tests
    uv run ruff format --check src tests
    uv run pyright src
@@ -87,12 +91,13 @@ python -m pip install --pre gflow-cli
    - `pyproject.toml`
    - `.codex-plugin/plugin.json`
    - `src/gflow_cli/__init__.py`
+   - `uv.lock` (run `uv lock` — the editable package version is pinned there)
    - any tests that assert the package version
 7. Move user-visible changes from `CHANGELOG.md` `[Unreleased]` into a dated
    release section.
 8. Commit the release prep:
    ```bash
-   git add pyproject.toml .codex-plugin/plugin.json src/gflow_cli/__init__.py CHANGELOG.md tests docs
+   git add pyproject.toml .codex-plugin/plugin.json src/gflow_cli/__init__.py uv.lock CHANGELOG.md tests docs
    git commit -m "chore(release): vX.Y.Z"
    ```
 9. Tag and push. **Must be a signed annotated tag** (`-s`) — `.github/workflows/release.yml` rejects unsigned or lightweight tags. Requires a GPG or SSH signing key registered with your GitHub account.